Events
Events
Events tell you what happened at your hubs: a door unlocked, a temperature changed, a device joined, a hub went offline. 1key keeps every hub's events for 30 days in your organization's event log, one ordered list read with one cursor. Needs events:read.
The log is the source of truth. Keep your cursor, and you can always resume where you stopped, after a deploy, an outage or a crash, without missing an event.
Reading the log
Start without a cursor to get the oldest events kept, then pass next_cursor as after each time:
curl "https://api.1keyplatform.dev/v1/events?after=8811&wait=30" \ -H "Authorization: Bearer $ONEKEY_API_KEY"
{
"data": [
{
"id": "evt_104311",
"cursor": "8812",
"type": "channel.observed",
"hub_id": "1key-xfy2-nmf4-5xwp",
"device_id": 7,
"time": "2026-10-03T14:03:11.143000Z",
"clock_trusted": true,
"data": { "key": "lock", "endpoint": 0, "value": false }
}
],
"next_cursor": "8812",
"has_more": false,
"retention_days": 30
}
import os, requests
API = "https://api.1keyplatform.dev/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['ONEKEY_API_KEY']}"}
def follow(cursor=None):
while True:
params = {"wait": 30, **({"after": cursor} if cursor else {})}
res = requests.get(f"{API}/events", headers=HEADERS, params=params, timeout=70)
if res.status_code == 410:
cursor = resync() # read current state, then continue from the newest event
continue
res.raise_for_status()
page = res.json()
for event in page["data"]:
handle(event) # deduplicate on event["id"]
cursor = page["next_cursor"]
save_cursor(cursor) # persist after handling
async function follow(cursor) {
for (;;) {
const url = new URL("https://api.1keyplatform.dev/v1/events");
url.searchParams.set("wait", "30");
if (cursor) url.searchParams.set("after", cursor);
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.ONEKEY_API_KEY}` } });
if (res.status === 410) { cursor = await resync(); continue; }
if (!res.ok) throw new Error(`events: ${res.status}`);
const page = await res.json();
for (const event of page.data) await handle(event);
cursor = page.next_cursor;
await saveCursor(cursor);
}
}
Streaming
For a held-open connection, use Server-Sent Events:
curl -N https://api.1keyplatform.dev/v1/events/stream \ -H "Authorization: Bearer $ONEKEY_API_KEY" \ -H "Last-Event-ID: 8811"
id: 8812
event: channel.observed
data: {"id":"evt_104311","cursor":"8812","type":"channel.observed","hub_id":"1key-xfy2-nmf4-5xwp","device_id":7,"time":"2026-10-03T14:03:11.143000Z","clock_trusted":true,"data":{"key":"lock","endpoint":0,"value":false}}
: keepalive
Each message's id is the event's cursor. Without Last-Event-ID, the stream starts with the next new event, and opens with an id: line alone naming where it starts, so a client that reconnects before any event arrives misses none. A : keepalive comment arrives every 30 seconds, and the server ends the stream after 15 minutes. Reconnect with Last-Event-ID set to the last id you processed; SSE clients do this automatically. The stream takes the filters of GET /events.
Signals
Between events, a stream sends signals: something you read changed. A signal names what changed, not its new value; read it again through the API.
event: hub.updated
data: {"type":"hub.updated","hub_id":"1key-xfy2-nmf4-5xwp","site_id":"0b7c5e0e-6a43-4f7e-9d0a-2f3c1b9e8d21","time":"2026-10-03T14:03:12.020000Z","data":{"changed":["connection","status"]}}
| Signal | data |
Read again |
|---|---|---|
hub.created |
{}: the hub joined your organization |
GET /hubs/{hub_id} |
hub.deleted |
{}: the hub was removed from your organization and the cloud |
nothing: it no longer exists |
hub.updated |
{"changed": [...]}: connection (online or offline), status (its status report and lights), firmware, network, stability, link, network_check, last_seen, name, site |
GET /hubs/{hub_id} |
sim.updated |
{"changed": [...]}: sim (which SIM the hub holds), status, usage |
GET /hubs/{hub_id}/sim |
setup_code.created, setup_code.updated, setup_code.deleted |
{"ids": ["sc_3f2a9c0d1e4b5a67"]}: codes added to, changed in or removed from the cloud's copy of the hub's list |
GET /hubs/{hub_id}/setup-codes |
Signals are not kept:
- A signal has no
id, so it leaves yourLast-Event-IDwhere it was, and a reconnect doesn't replay it. After a reconnect, read current state again. - They aren't in
GET /eventsorGET /hubs/{hub_id}/events. - A burst is merged: at most one signal of a type a second for a hub, its
changedoridsjoined.
type, hub_id and site_id filter signals as they filter events. device_id leaves them out; category=connectivity keeps hub.updated and sim.updated. last_seen changes go only to the hub's own stream, GET /hubs/{hub_id}/events/stream.
One hub's events
GET /hubs/{hub_id}/events and GET /hubs/{hub_id}/events/stream read one hub's events the same way, with that hub's own cursors. The list takes type, category, device_id and order. An event's id is the same in both; its cursor is its position where you read it.
GET /hubs/{hub_id}/events/counts counts the hub's kept events by family, the type's first word; category=connectivity counts only those:
{ "families": { "channel": 812, "device": 14, "hub": 9 }, "total": 835, "retention_days": 30 }
Delivery rules
| Rule | What to do |
|---|---|
| Ordered | The log is in the order 1key stored events; each hub's events are in the hub's order. |
| At least once | You may see an event again after a reconnect or retry. Deduplicate on id. |
| 30-day retention | A cursor older than the events kept gets 410 cursor_expired. |
| Gaps | If 1key could not get some of a hub's events, a hub.events_skipped event says so. Re-read the hub's devices for current state. |
Resyncing after 410
410 cursor_expired means events you had not read are gone. Read current state instead of replaying history: read your hubs and their devices (GET /hubs/{hub_id}?expand=devices), then read events without after and continue from the newest one.
Cursors
A cursor looks like 8812. Treat it as an opaque string: store it, compare it for equality, pass it back. Do not parse it or do arithmetic on it.
Event types and their data are listed in the event reference.