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 -X POST https://api.1keyplatform.dev/v1/sites \
-H "Authorization: Bearer $ONEKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "120 Harbour St"}'
{
"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 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 -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 -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.