1KEY Developers
Guides

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"

Streaming

For a held-open connection, use Server-Sent Events:

curl
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 your Last-Event-ID where it was, and a reconnect doesn't replay it. After a reconnect, read current state again.
  • They aren't in GET /events or GET /hubs/{hub_id}/events.
  • A burst is merged: at most one signal of a type a second for a hub, its changed or ids joined.

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:

json
{ "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.