1KEY Developers
Guides

Sites

Sites

A site is a building your organization manages. Every hub is at one of your sites, so create the site before you add its hubs.

Creating a site

curl
curl -X POST https://api.1keyplatform.dev/v1/sites \
  -H "Authorization: Bearer $ONEKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "120 Harbour St"}'
json
{
  "id": "6f1c2a9e-4b7d-4e0a-9c3f-2d8e5a1b7c40",
  "name": "120 Harbour St",
  "time_zone": null,
  "location": null,
  "test": false,
  "hub_count": 0,
  "created_at": "2026-09-12T15:20:00Z",
  "updated_at": "2026-09-12T15:20:00Z"
}

Needs sites:write. Keep the id: you add hubs to a site by it.

Listing sites

curl
curl https://api.1keyplatform.dev/v1/sites \
  -H "Authorization: Bearer $ONEKEY_API_KEY"

Sites come oldest first, 50 to a page (limit takes 1–100). When has_more is true, pass the last site's id as starting_after for the next page. q lists only sites whose name contains it. Needs sites:read.

GET /sites/{site_id}?expand=hubs includes the site's hubs, which also needs hubs:read. include_test=false lists only sites that aren't test sites.

Site status and trend

expand=status,trend on GET /sites or GET /sites/{site_id} adds, for each site:

Field
status.hub_counts its hubs of each kind now: ethernet, wifi, cellular, offline, never
status.attention_count, status.attention its hubs that need attention, and how many in each category
status.firmware the versions its hubs report, most hubs first
trend its trend over range (24h, 7d or 30d), days in its time zone

measures limits the trend to the measures you show. Each needs hubs:read.

Site outages

GET /sites/{site_id}/outages?from=…&to=… lists the times at least half of a site's hubs, and two or more, were offline together for a minute or more: likely the building's network or power. Each has from, to, offline (the most hubs offline at once) and ongoing. to defaults to now and from to 24 hours before it, at most 35 days. Needs hubs:read.

Renaming a site

curl
curl -X PATCH https://api.1keyplatform.dev/v1/sites/6f1c2a9e-4b7d-4e0a-9c3f-2d8e5a1b7c40 \
  -H "Authorization: Bearer $ONEKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Harbour Tower"}'

Needs sites:write.

Time zone and location

Set a site's IANA time zone and its location, so its hubs run schedules and local-time conditions in the right time, and know when the sun rises and sets:

curl
curl -X PATCH https://api.1keyplatform.dev/v1/sites/6f1c2a9e-4b7d-4e0a-9c3f-2d8e5a1b7c40 \
  -H "Authorization: Bearer $ONEKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"time_zone": "America/Toronto", "location": {"latitude": 43.65, "longitude": -79.38}}'

The hubs at the site get them at once if they're online, or when they next connect, and keep them. An unknown time zone is refused with 400. Needs sites:write.

Test sites

"test": true marks a site you test with, such as a bench of hubs in your office. Lists (GET /sites, GET /hubs) include test sites unless include_test=false; fleet totals and trends (GET /fleet) leave them out unless include_test=true. Set it when creating the site or with PATCH. Needs sites:write.