1KEY Developers
API reference

Events

Base URL https://api.1keyplatform.dev/v1. Every endpoint below is generated from the OpenAPI contract, which you can download as openapi.yaml.

Log in to send these requests to your organization from this page.

Events

Events from your hubs, kept 30 days. Read your organization's log with one cursor, or one hub's events with its own.

GET /events/stream

Stream your organization's events

Needs the events:read scope.

Server-Sent Events of every hub's events. Each message's id is the event's cursor in your organization's log and its event the event type. Starts after Last-Event-ID, or with the next new event without it; then the stream opens with an id: line alone, the cursor it starts from. A : keepalive comment arrives every 30 seconds. The server ends the stream after 15 minutes; reconnect with Last-Event-ID. Takes the filters of GET /v1/events.

Between events, the stream sends signals (Signal): hub.created, hub.updated, sim.updated, setup_code.created, setup_code.updated and setup_code.deleted. A signal has no id: it isn't kept, so Last-Event-ID doesn't replay it. It names what changed; read it again. At most one of a type a second for a hub. type, hub_id and site_id filter signals too; device_id leaves them out, and category=connectivity keeps hub.updated and sim.updated.

Parameters

Name In Type Description
Last-Event-ID optional header string
type optional query string Only events whose type starts with one of these comma-separated prefixes: device., hub.online,hub.offline. At most 20.
category optional query "connectivity" connectivity: only events about the hub's connection: hub.online, hub.offline, hub.unstable, hub.stable, hub.network_changed, hub.wifi_failover, hub.condition, and the hub alarms about connectivity.
hub_id optional query string
site_id optional query string Only events from the site's hubs.
device_id optional query integer

Responses

200 An event stream.
200 · example
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}}

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"]}}

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
410 The cursor is older than the events kept.
GET /hubs/{hub_id}/events/counts

Count a hub's events by family

Needs the events:read scope.

How many of the hub's kept events there are of each family, the type's first word (channel, device, hub, …). Families with none are absent.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).
category optional query "connectivity" connectivity: only events about the hub's connection: hub.online, hub.offline, hub.unstable, hub.stable, hub.network_changed, hub.wifi_failover, hub.condition, and the hub alarms about connectivity.

Responses

200 The counts.
200 · example
{
  "families": {
    "channel": 812,
    "device": 14,
    "hub": 9
  },
  "retention_days": 30,
  "total": 835
}

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
GET /hubs/{hub_id}/events/stream

Stream a hub's events

Needs the events:read scope.

Server-Sent Events. Each message's id is the event's cursor and its event the event type. Starts after Last-Event-ID, or with the next new event without it; then the stream opens with an id: line alone, the cursor it starts from. A : keepalive comment arrives every 30 seconds. The server ends the stream after 15 minutes; reconnect with Last-Event-ID. Between events, the hub's signals (Signal) arrive without an id, as on GET /v1/events/stream, last_seen changes included.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).
Last-Event-ID optional header string

Responses

200 An event stream.
200 · example
id: 1043
event: channel.observed
data: {"cursor":"1043","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}}

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
410 cursor_expired The cursor is older than the 30 days events are kept.
GET /events

Read your organization's events

Needs the events:read scope.

Every hub's events in one order, after after, oldest first. Without after, from the oldest kept. Pass next_cursor as after next time: a reader that keeps its cursor misses nothing, even after downtime. Deduplicate on id. With order=desc, newest first, before before.

Parameters

Name In Type Description
after optional query string A cursor from a previous page or event.
order optional query "asc" | "desc" asc (default): oldest first, after after. desc: newest first, before before.
before optional query string With order=desc: a cursor from a previous page or event; events before it. Without it, from the newest.
limit optional query integer, 1–500, default 100
wait optional query integer, 0–60, default 0 Seconds to hold the request open when there are no events yet. Not with order=desc.
type optional query string Only events whose type starts with one of these comma-separated prefixes: device., hub.online,hub.offline. At most 20.
category optional query "connectivity" connectivity: only events about the hub's connection: hub.online, hub.offline, hub.unstable, hub.stable, hub.network_changed, hub.wifi_failover, hub.condition, and the hub alarms about connectivity.
hub_id optional query string
site_id optional query string Only events from the site's hubs.
device_id optional query integer

Responses

200 A page of events.

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
410 The cursor is older than the events kept. Read current state, then continue from the newest event.
GET /hubs/{hub_id}/events

Read a hub's events

Needs the events:read scope.

Events after after, oldest first. Without after, from the oldest kept (events are kept 30 days). Pass next_cursor as after next time. With order=desc, newest first, before before.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).
after optional query string A cursor from a previous page or event.
order optional query "asc" | "desc" asc (default): oldest first, after after. desc: newest first, before before.
before optional query string With order=desc: a cursor from a previous page or event; events before it. Without it, from the newest.
limit optional query integer, 1–500, default 100
wait optional query integer, 0–60, default 0 Seconds to hold the request open when there are no events yet. Not with order=desc.
type optional query string Only events whose type starts with one of these comma-separated prefixes: device., hub.online,hub.offline. At most 20.
category optional query "connectivity" connectivity: only events about the hub's connection: hub.online, hub.offline, hub.unstable, hub.stable, hub.network_changed, hub.wifi_failover, hub.condition, and the hub alarms about connectivity.
device_id optional query integer Only events about this device.

Responses

200 A page of events.

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
410 cursor_expired The cursor is older than the 30 days events are kept.
GET /intercoms/{intercom_id}/events

Read an intercom's events

Needs the events:read scope.

An intercom's events, read as a hub's (GET /hubs/{hub_id}/events): the same parameters, cursors and retention, with the intercom's ID as hub_id.

Parameters

Name In Type Description
intercom_id required path string The intercom's ID, its Serial (lowercase).
after optional query string A cursor from a previous page or event.
order optional query "asc" | "desc" asc (default): oldest first, after after. desc: newest first, before before.
before optional query string With order=desc: a cursor from a previous page or event; events before it. Without it, from the newest.
limit optional query integer, 1–500, default 100
wait optional query integer, 0–60, default 0 Seconds to hold the request open when there are no events yet. Not with order=desc.
type optional query string Only events whose type starts with one of these comma-separated prefixes: device., hub.online,hub.offline. At most 20.
category optional query "connectivity" connectivity: only events about the hub's connection: hub.online, hub.offline, hub.unstable, hub.stable, hub.network_changed, hub.wifi_failover, hub.condition, and the hub alarms about connectivity.

Responses

200 A page of events.

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
410 cursor_expired The cursor is older than the 30 days events are kept.