Hubs
Hubs
A hub is the 1key device in a building that controls its locks, thermostats, switches and sensors. Each hub has a hub ID printed on its label, such as 1key-xfy2-nmf4-5xwp.
Adding a hub
Each hub is at one of your organization's sites. Once a hub is installed and online, add it to a site by the Serial on its label:
curl -X POST https://api.1keyplatform.dev/v1/hubs \
-H "Authorization: Bearer $ONEKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"serial": "1KEY-XFY2-NMF4-5XWP", "site_id": "6f1c2a9e-4b7d-4e0a-9c3f-2d8e5a1b7c40", "name": "Lobby hub"}'
Needs hubs:write. The Serial is accepted in any case, with or without dashes. From then on the hub appears in GET /hubs. The portal does the same.
A hub belongs to one organization at a time: the first to add it keeps it. 422 hub_not_addable means the Serial isn't one 1Key made, or another organization has it. A hub can be added before it's installed: it shows as not connected until it comes online. Adding a hub your organization already has moves it to the site you name.
Reading hubs
curl https://api.1keyplatform.dev/v1/hubs/1key-xfy2-nmf4-5xwp \ -H "Authorization: Bearer $ONEKEY_API_KEY"
{
"id": "1key-xfy2-nmf4-5xwp",
"name": "Lobby hub",
"site_id": "6f1c2a9e-4b7d-4e0a-9c3f-2d8e5a1b7c40",
"connection": {
"status": "online",
"since": "2026-10-01T09:14:02Z",
"last_seen_at": "2026-10-01T11:02:40Z",
"stability": "stable",
"stability_reasons": [],
"disconnects_24h": 1,
"disconnect_reason": null,
"public_ip": "203.0.113.7",
"link": {
"down_s": 41,
"tries": 2,
"drops_24h": 1,
"flaps_24h": 0,
"rtt_ms": 48,
"rtt_p95_ms": 120,
"loss_pct": 0,
"retrans_pct": 0.4,
"at": "2026-10-01T10:14:03Z"
},
"network_check": null,
"lights": null
},
"firmware": { "version": "0.4.2" },
"network": {
"type": "wifi",
"interface": "wlan0",
"ip_address": "192.168.1.40",
"ipv6_address": null,
"mac_address": "b8:27:eb:12:34:56",
"ssid": "Lobby",
"signal_dbm": -61,
"carrier": null,
"radio": null,
"metered": false,
"reported_at": "2026-10-01T09:14:03Z"
},
"interfaces": [
{ "if": "eth0", "type": "ethernet", "up": false },
{ "if": "wlan0", "type": "wifi", "up": true, "ip4": "192.168.1.40", "gw": "192.168.1.1", "dns": ["192.168.1.1"], "mac": "b8:27:eb:12:34:56", "ssid": "Lobby", "rssi": -61, "band": "5GHz", "channel": 36 },
{ "if": "wwan0", "type": "cellular", "up": false }
],
"registered_at": "2026-09-12T15:30:00Z"
}
firmware and network are what the hub reported when it last connected, and null until it does. network.type is wifi, ethernet or cellular.
interfaces lists each of the hub's networks, whether or not it carries the connection, as the hub last reported them: up (a cable linked, Wi-Fi joined, or cellular registered), its address, router and DNS, and by type the link speed, the Wi-Fi network, band and signal, or the carrier, LTE band and signal (rsrp, rsrq, sinr). The hub sends them when it connects, and again at once when up, ip4, gw, ssid or op changes; a signal step of 6 dB or more, or a new band or channel, at most every 10 minutes. Link speed and duplex are present only while Ethernet is linked, and the Wi-Fi fields only while Wi-Fi is joined.
A hub that is not your organization's returns 404, the same as one that does not exist.
Connection
| Field | |
|---|---|
status |
online or offline as AWS IoT sees the hub's connection, or unknown when the hub has not connected since it was added |
since |
when status last changed |
status_at |
when the hub last sent its status report |
last_seen_at |
the last time the cloud heard from the hub: a message, an answer or a connect. Updated at most every 30 seconds |
stability |
stable or unstable; null while status is unknown |
stability_reasons |
why it is unstable, below |
instability |
while the hub is online and unstable, reasons and disconnects_1h; otherwise null |
disconnects_1h, disconnects_24h |
unplanned disconnects in the last hour and 24 hours, short drops included |
recent_disconnects |
when each of the last 24 hours' unplanned disconnects happened, newest first, at most 100 |
disconnect_reason |
why the last connection ended, as AWS IoT reports it |
modem |
the cellular modem as the hub last reported it: identity, registration and radio, each with when it took its value; null without one |
public_ip |
the address the hub connects from, while online |
port |
the MQTT port its latest status says it connected on: 443, or 8883 where its network blocks MQTT on 443; null until it reports one |
link |
the hub's latest report on its connection, with at, when it sent it; null until it sends one |
network_check |
the latest network check, or null |
lights |
the hub's four status lights as it last reported them, or null |
hub.offline is recorded once a hub has been offline for 30 seconds, timed when it disconnected, and hub.online when it returns; a hub back within 30 seconds records neither.
| A hub that | Shows as |
|---|---|
| connects | online within seconds |
| disconnects cleanly (restart, network change) | offline within seconds |
| loses power or its network | offline once AWS gives up on it: 3 minutes on Ethernet or Wi-Fi, up to 30 minutes on cellular, where the hub keeps its connection quieter to save data |
The cloud also checks every hub against AWS's live connection state every five minutes and corrects any it got wrong.
Stability
A hub is unstable while any of these holds. Each clears on its own, at a lower level than it starts:
| Reason | Unstable at | Stable again at |
|---|---|---|
disconnects |
3 unplanned disconnects within an hour | 1 or none within the last hour |
packet_loss |
link.loss_pct 5 or more |
below 2.5 |
retransmits |
link.retrans_pct 5 or more |
below 2.5 |
latency |
link.rtt_p95_ms 2000 or more |
below 1000 |
Every disconnect counts except one the hub made itself (CLIENT_INITIATED_DISCONNECT), including drops too short for hub.offline. The hub sends link when it connects and every hour (every 6 hours on a metered network); a figure it leaves out, such as a round trip after an hour with nothing sent, changes nothing, and a report older than 7 hours no longer counts. hub.unstable and hub.stable are recorded when stability changes.
link field |
|
|---|---|
down_s |
seconds the hub was offline before this connection |
tries |
connection attempts that failed before this one |
drops_24h, flaps_24h |
connections lost, and times its network interface lost its link, in the last 24 hours |
rtt_ms, rtt_p95_ms |
round trip to the cloud over the last hour, median and 95th percentile |
loss_pct, loss_pct_24h |
messages the cloud didn't acknowledge within 10 seconds, %, last hour and 24 hours |
retrans_pct, retrans_pct_24h |
TCP segments sent again, %, last hour and 24 hours |
rsrq, sinr |
cellular signal quality and signal to noise, dB |
Any field may be absent.
Status lights
connection.lights is what the four lights on the hub say, as its latest status reports them:
{
"row": [
{"state": "ok", "link": null, "causes": [], "since": "2026-10-22T10:00:00Z"},
{"state": "error", "link": "wifi", "causes": ["InternetUnreached"], "since": "2026-10-22T10:12:40Z"},
{"state": "ok", "link": null, "causes": [], "since": null},
{"state": "warning", "link": null, "causes": ["ZWaveCongested"], "since": null}
],
"display": {"effect": "row", "leds": [{"colour": "green", "pattern": "steady"}, {"colour": "red", "pattern": "flashing"}, {"colour": "green", "pattern": "steady"}, {"colour": "amber", "pattern": "steady"}]},
"mcu": true
}
row is the lights in order: system, internet, cloud, software. state is ok, warning (degraded), progress or error; link names the network the internet light speaks for; causes are the alarms by name (see hub.alarm_raised) or conditions (see hub.condition) behind a light that isn't ok; since is when the state began, null if the hub's clock wasn't set then. display is what the hub commanded its LEDs to show, effect row for the four lights or another signal such as dark (asleep after 5 minutes unchanged), locate or updating; nothing reports what the LEDs actually show. mcu is whether the hub's light controller answers.
Network checks
A hub checks each of its network interfaces out to the cloud, and says what is wrong in terms an installer can act on. Each interface is checked over itself, so a broken Wi-Fi can be checked while the hub stays connected over cellular.
curl -X POST https://api.1keyplatform.dev/v1/hubs/1key-xfy2-nmf4-5xwp/network-check \
-H "Authorization: Bearer $ONEKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"trace": false}'
Needs hubs:read. Every field is optional:
| Field | |
|---|---|
interfaces |
interface names, such as ["wlan0"]; default every interface the hub has |
trace |
trace the route to the cloud |
wifi_scan |
list the Wi-Fi networks the hub can see |
count |
probes per measured step, 1 to 20; default 5 |
It takes up to 20 seconds, or 75 with trace or wifi_scan. interfaces names 1 to 8 interfaces to check; without it, every interface is checked. The answer has, for each interface, its link, dhcp, ip6, steps (gateway, dns_resolver, dns_public, dns_hijack, internet, captive_portal, ports, tls, mtu, mqtt, time), and trace and scan when asked; findings, each with the cloud's message and fix; ok, true when no finding is an error; and round_trip_ms, how long the call took. A hub that is offline answers 503 hub_offline, and one too slow 504 hub_timeout.
{
"hub_id": "1key-xfy2-nmf4-5xwp",
"ok": false,
"round_trip_ms": 11840,
"at": "2026-10-01T11:02:40Z",
"findings": [
{
"if": "wlan0",
"code": "port_blocked",
"severity": "error",
"detail": { "port": 8883, "proto": "tcp" },
"message": "The network blocks outbound port 8883, which the hub uses to reach the cloud.",
"fix": "Ask the network's administrator to allow TCP 8883 to *.iot.us-east-2.amazonaws.com, or use port 443."
}
],
"interfaces": [
{ "if": "wlan0", "type": "wifi", "default": false, "link": { "state": "associated", "ssid": "Front Desk WiFi", "rssi": -67 }, "dhcp": { "ok": true, "ip4": "192.168.1.40", "gateway": "192.168.1.1", "dns": ["192.168.1.1"], "link_local": false }, "ip6": { "addresses": [], "router_advert": false }, "steps": [ { "check": "gateway", "ok": true, "rtt_ms": 2, "loss_pct": 0 } ] }
]
}
The result is kept as connection.network_check, with source request and received_at, when the cloud received it. A hub that loses the cloud for more than a minute runs the check itself and sends it when it is back: that one has source hub, down_s, how long it was offline, and no round_trip_ms.
| Finding | Severity | Meaning |
|---|---|---|
no_link |
error | no Ethernet carrier: the cable is out or the port is off |
wifi_auth_failed |
error | the access point refused the hub's Wi-Fi password |
wifi_ssid_not_found |
error | the hub's Wi-Fi network is not in range (with wifi_scan) |
wifi_weak_signal |
warning | the Wi-Fi signal is below -75 dBm |
cellular_no_sim |
error | the modem cannot read a SIM |
cellular_not_registered |
error | the modem is searching for a network, or was refused |
no_dhcp |
error | no address from DHCP, or only a link-local one |
no_gateway_reply |
warning | the router answers no ping (some never do) |
dns_failed |
error | no DNS server the network hands out resolves the cloud |
dns_slow |
warning | a DNS server took over a second |
dns_blocked_outbound |
warning | the network's DNS works, but public DNS servers can't be reached |
dns_intercepted |
warning | something on the network answers DNS sent to 1.1.1.1; detail.cloudflare, what 1.1.1.1's whoami.cloudflare returned (not an address), and detail.google, the address 8.8.8.8 saw the query from, when it answered |
dns_nxdomain_hijack |
warning | the network's DNS answers for names that don't exist; detail.answers, what came back |
no_internet |
error | the hub reaches its router but not the internet |
captive_portal |
error | the network sends the hub to a sign-in page |
port_blocked |
error for the cloud's ports 8883 and 443, else warning | an outbound port is blocked; detail.port, detail.proto |
tls_intercepted |
error | something on the network intercepts encrypted traffic; detail.issuer |
mtu_blackhole |
warning | large packets vanish on the way out; detail.path_mtu |
ntp_blocked |
warning | time servers can't be reached |
clock_unsynced |
warning | the hub's clock isn't set from a time server |
high_loss |
warning | over 5 % of probes to the router or the internet are lost |
high_latency |
warning | over 300 ms to the internet |
The portal's hub page runs the same check with Check network and draws each interface's path to the cloud.
Devices
A hub's devices are read and commanded live through the hub. See devices and commands.
Listing hubs
GET /hubs lists your hubs by hub ID, 50 to a page (limit takes 1–100). Pass next_cursor as cursor for the next page, or the last hub's id as starting_after. total_count is how many hubs match, across all pages. Narrow it with:
| Parameter | Lists |
|---|---|
site_id |
one site's hubs |
status |
online, offline or unknown hubs |
kind |
hubs of one kind, or online for ethernet, wifi and cellular |
issue |
hubs that need attention for one reason: offline, never, or one of the flags |
issue_site |
one site's hubs, with issue |
include_test |
false leaves out hubs at test sites (default true) |
q |
hubs whose ID, name or site name contains it |
sort=attention lists problems first: offline hubs, then hubs never heard from, then the rest, each by hub ID. Page it with cursor only.
Each hub carries how it stands now:
| Field | |
|---|---|
site_name |
its site's name |
kind |
ethernet, wifi or cellular while online, offline, or never when the cloud has not heard from it |
flags |
why it needs attention, below |
crashes_7d |
restarts after a crash in the last 7 days |
alarms |
the health alarms standing: name, class (degraded, maintenance or null) and raised_at; see Health alarms |
registered_by |
who added it: email, and id their member ID, null once they have left; null when no person added it |
| Flag | The hub |
|---|---|
crash |
restarted after a crash 3 or more times in 7 days |
blocked |
is online, and its last network check found Wi-Fi blocking the cloud's ports |
weak |
is on Wi-Fi below -75 dBm |
nobackup |
has connected, with cellular auto-activate off or a SIM the carrier rejected |
unchecked |
has connected, with no network check yet |
GET /hubs/{hub_id}?expand=devices includes the hub's devices, read live. A hub that can't answer still returns, with devices null and devices_error saying why, so one call shows a building's state.
The fleet
GET /fleet is your hubs together: how many are of each kind now (kinds), every attention category with its hubs and sites (attention), and the trend over range (24h, 7d or 30d) with the range before's total (trend.previous):
curl "https://api.1keyplatform.dev/v1/fleet?range=7d&expand=wifi,backup,firmware,top,events" \ -H "Authorization: Bearer $ONEKEY_API_KEY"
| Parameter | |
|---|---|
site_id |
one site's hubs, in its days; otherwise UTC days |
include_test |
true counts test sites |
expand |
wifi, backup, firmware, top (most crash restarts and downtime over the range), events (the last 24 hours) |
kind, limit |
with expand=events: one kind (conn, failover, reboot, sim), and how many (default 6) |
measures |
the trend measures to include, comma-separated; default all |
Trend measures are the rollups': known_s, online_s, cellular_s, offline_s, outages, longest_outage_s, failovers, the restarts counts, unplanned, alarms_raised and cellular_bytes. Uptime is 1 - offline_s / known_s.
GET /fleet/hubs/trends?hub_id=a,b,… returns up to 100 hubs' trends in one call, each in its site's days. Pass measures=known_s,offline_s,unplanned when that's all you show: the full set is about 9 KB a hub for 24h.
Both need hubs:read.
Resetting a hub's link
A hub that was factory reset, or lost its key, can't reconnect with its old certificate. Reset its link and it requests a new certificate on its own:
curl -X POST https://api.1keyplatform.dev/v1/hubs/1key-xfy2-nmf4-5xwp/reset-link \ -H "Authorization: Bearer $ONEKEY_API_KEY"
A hub that was refused retries every six hours, so it reconnects within six hours, or at once if you restart it. It stays in your organization, at its site. Needs hubs:write.
Removing a hub
To start a hub over completely, or when it leaves for good, remove it:
curl -X DELETE https://api.1keyplatform.dev/v1/hubs/1key-xfy2-nmf4-5xwp \
-H "Authorization: Bearer $ONEKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"confirm": "1key-xfy2-nmf4-5xwp"}'
This deletes the hub's certificates and its AWS IoT thing, and everything recorded about it: events, sessions, uptime, alarms, connection, setup codes and deployments. Organization and site totals keep its past. Its SIM stays on your account and is set inactive. confirm repeats the hub's ID. The answer is 204, and a hub.deleted signal goes out on the event streams.
The hub can't reconnect afterwards. To use it again, factory reset it; once it has requested a new certificate, add it by its Serial, which also lets its SIM be activated again. Owners and admins only. Needs hubs:write.
Wi-Fi
A hub keeps a list of Wi-Fi networks and tries them in order. Read it, and change it remotely, through the hub:
curl https://api.1keyplatform.dev/v1/hubs/1key-xfy2-nmf4-5xwp/wifi \ -H "Authorization: Bearer $ONEKEY_API_KEY"
{
"networks": [
{ "ssid": "Lobby", "security": "wpa2", "priority": 1 },
{ "ssid": "Lobby-old", "security": "wpa2", "priority": 2 }
]
}
| Call | Does |
|---|---|
GET /hubs/{hub_id}/wifi/scan |
lists the networks the hub can see, with signal, band, channel and security, without leaving its network; hidden networks aren't listed |
POST /hubs/{hub_id}/wifi/networks |
saves ssid with password (left out for an open network) and optional priority; changes a saved one |
DELETE /hubs/{hub_id}/wifi/networks/{ssid} |
removes a network |
PUT /hubs/{hub_id}/wifi/order |
sets the order: ssids names every saved network once |
curl -X POST https://api.1keyplatform.dev/v1/hubs/1key-xfy2-nmf4-5xwp/wifi/networks \
-H "Authorization: Bearer $ONEKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ssid": "Lobby-5G", "password": "correct horse battery", "priority": 1}'
A change answers with the saved networks, as GET does. The hub saves it at once and applies it 2 seconds later by restarting its Wi-Fi, so it is off Wi-Fi for a few seconds and then joins the first saved network in range that isn't held; removing the network it was on leaves it. A change that changes nothing restarts nothing.
When the joined network goes 2 minutes without reaching the internet, the hub holds it out and moves to the next saved network in range that isn't held, if there is one; otherwise it stays joined and the hub carries on over Ethernet or cellular. It tries the held network again after 15 minutes, doubling with each hold in a row up to 4 hours, and back to 15 minutes once the network reaches the internet. Each hold records hub.wifi_failover with from, to, the network it moves to, and held_s; while it lasts the network's entry carries held_s, the seconds left. Saving or removing a held network ends its hold; reordering doesn't. A reboot, or a restart of the hub's Wi-Fi, ends them all.
Whether Wi-Fi works shows in the hub's interfaces, where the wifi entry has up and ssid.
A password saves the network as WPA2: an access point in WPA2/WPA3 mode takes it, a WPA3-only one doesn't. Without password, a network already saved keeps its own and a new one is saved as open. A hidden network can be saved by its name.
Passwords are write-only. The cloud passes them to the hub and doesn't store or log them, and the hub keeps only the key derived from them and never returns it. A hub holds at most 16 networks. Changes need hubs:write; reading needs hubs:read. A change the hub refuses, such as a 17th network or an order that doesn't name each network once, answers invalid_request; an unknown network not_found; a hub whose Wi-Fi is busy hub_unavailable, which can be retried; and one that couldn't save it hub_error. In each case nothing changes.
Uptime
GET /hubs/{hub_id}/uptime?range=24h answers when the hub was connected, from the connections the cloud records:
range |
Window |
|---|---|
24h (default) |
the last 24 hours |
7d |
from midnight 6 days ago in the site's time zone |
30d |
from midnight 29 days ago in the site's time zone |
segments cover the window in order, each online (Ethernet or Wi-Fi), cellular, offline (a gap of 5 s or more) or unknown (before the cloud's first record of the hub). outages are the offline segments with the disconnect reason, and restart, boot_reason and boot_detail when the hub came back from a restart. uptime_pct is the share of the time on record the hub was online. days splits the window by day in time_zone: the site's, or Etc/UTC when it has none. Needs hubs:read.
Health
GET /hubs/{hub_id}/health reads the hub's own health live from the hub:
| Field | |
|---|---|
uptime_s |
seconds since it started |
memory, disk_used_percent, cpu_temp_c, load |
memory in MB, how full the data partition is, CPU temperature, and the 1, 5 and 15 minute load averages |
alarms |
the alarms standing, by name: Wedged, ZWavePortDown, ZWaveNotReady, NotSecured, … |
clock |
{"trusted": true} once its clock is set from a trusted source |
last_reboot |
what the previous boot ended in (cause), and when this one started (at) |
bytes_today, metered |
data used this UTC day by interface, and whether its default route is cellular |
setup_codes_listening |
the radio is listening for devices whose setup code it keeps |
A field the hub can't read is null. Needs hubs:read.
Health alarms
A hub raises hub.alarm_raised when something about its health needs a person, and hub.alarm_cleared when it no longer does; a hub's alarms lists those standing. Each event's data has the alarm's name and a description written for people, which can change between firmware versions: read the name, not the description. A degraded alarm also turns the hub's software light amber; a maintenance alarm shows only through the API and the portal. None of them restarts the hub.
| Alarm | Class | Raised when |
|---|---|---|
MemoryLow |
degraded | Available memory under 10% for 3 minutes |
FileDescriptorsLow |
degraded | Open files at 80% of the limit |
CpuSaturated |
degraded | The processor 90% busy for 5 minutes; the description names the 3 busiest processes |
Overheating |
degraded | The processor at 70 °C or more for 3 minutes |
StorageLow |
degraded | Its main storage 90% full, or its temporary storage 80% |
ProcessLimitsNear |
degraded | Its software's processes, ports or atoms at 80% of their limits, its system processes at 80%, or 20 stopped processes not cleaned up |
MemoryGrowing |
maintenance | Memory use rose every hour for 6 hours, by 25% or more |
FileDescriptorsGrowing |
maintenance | Open files rose every hour for 6 hours, by 50 or more |
MailboxBacklog |
maintenance | A process holding 10,000 queued messages for 2 minutes |
EmmcWearing |
maintenance | Its storage chip reports wear near the end of its life |
For a degraded alarm, check the hub and restart it if the alarm stays. MemoryGrowing, FileDescriptorsGrowing and MailboxBacklog usually mean a firmware leak: report them with the hub's serial. EmmcWearing means planning to replace the hub.
Logs and black box
| Call | Answers |
|---|---|
GET /hubs/{hub_id}/logs?lines=200 |
the hub's most recent log lines, oldest first; lines 1 to 500 |
GET /hubs/{hub_id}/black-box?which=previous |
what the hub kept across reboots: previous, what it recorded before its last reboot; boots, a line per boot with its cause; panic, the last kernel panic. 404 when it has no such recording |
Both are read live from the hub. Need hubs:read.
Audit log
GET /hubs/{hub_id}/audit?limit=50 reads what was done on the hub, newest first, live from the hub: devices added or forgotten, credentials, resets, reboots and repairs.
{
"data": [
{ "id": 812, "at": "2026-10-22T14:02:11Z", "clock": "ntp", "action": "device.forget",
"actor": "cloud", "subject": "device", "subject_id": 7, "detail": {} }
],
"has_more": true
}
actor is cloud, or the id of the certificate that asked. limit is 1 to 100; page back with before, the last entry's id. Needs hubs:read.
Z-Wave diagnostics
| Call | Answers |
|---|---|
GET /hubs/{hub_id}/radio |
the radio: state, region, module firmware, chip restarts and faults, last network backup, background noise per channel, the last hour's frames, backoffs, CRC errors and foreign frames, Long Range, queued work, failed devices, and 48 hours of hourly history |
GET /hubs/{hub_id}/devices/{device_id}/zwave |
a device's node: listening type, wake-up interval, failed mark, when it was last heard and sent to, the last frame each way (RSSI, hops, delivery time, tries, speed), neighbours, whether its lifeline points at the hub, associations, security, whether it was interviewed, and 48 hours of hourly link history. 404 when it isn't on the Z-Wave network |
Both are read live from the hub's radio; neither asks the device. Their fields follow the radio and may change with the hub's firmware, and a value the radio can't give is null. Devices, routes and neighbours are named by device_id, the hub as "hub". Need hubs:read.
To act on a device, use its setup actions (identify, interview, rebuild_routes, repair_reporting), which work on any device, and ping.
Recovery actions
POST /hubs/{hub_id}/actions/{action} runs one of:
action |
Does | Who |
|---|---|---|
repair_lifeline |
points a device's Lifeline association, and the groups its product needs, at the hub; send {"device_id": 7}. For a device that works when commanded but never reports changes |
any member |
zwave_restart |
restarts the Z-Wave radio program: a few seconds without Z-Wave | owners and admins |
reboot |
reboots the hub: offline for about a minute | owners and admins |
network_reconnect |
re-applies the hub's network configuration: its link drops and comes back | any member |
The hub answers 202, then acts two seconds later. Needs hubs:write.
Cellular
A hub with a cellular modem carries a Super SIM. The cloud keeps it inactive until the hub needs cellular, activates it then, and sets it inactive again 7 days after its last use.
GET /hubs/{hub_id}/sim answers the SIM the hub last reported: its kore_status and unique_name at KORE, this period's usage (with the SIM's settings packages), status from its newest connection events (attached or not, network, cell, data session), hold_due while it is active, and auto_activate. 404 when the hub has reported no SIM. refresh=true reads the status and usage from KORE first; expand=tower adds where OpenCelliD places its cell. GET /hubs/{hub_id}/sim/events lists its attach and data-session events, newest first, with limit, offset and total. Need hubs:read.
curl -X PUT https://api.1keyplatform.dev/v1/hubs/1key-xfy2-nmf4-5xwp/sim/auto-activate \
-H "Authorization: Bearer $ONEKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"enabled": false}'
With auto-activate off, the SIM is never activated, for example for a hub in stock; held_note says who turned it off. Owners and admins only; needs hubs:write.
Renaming and moving
curl -X PATCH https://api.1keyplatform.dev/v1/hubs/1key-xfy2-nmf4-5xwp \
-H "Authorization: Bearer $ONEKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Lobby hub", "site_id": "6f1c2a9e-4b7d-4e0a-9c3f-2d8e5a1b7c40"}'
Send name, site_id or both. A null name clears it. Needs hubs:write.
Alert rules
Each member chooses which alerts email them. They apply to every site but test sites, and email once when the condition starts holding.
| Rule | Emails when | On by default |
|---|---|---|
site_offline |
a site has 3 or more hubs offline for 5 minutes | yes |
crash_loop |
a hub restarts after a crash 3 times in 24 hours | no |
cellular_plan |
a hub's SIM passes 90% of its plan's data in a billing period | yes |
GET /alert-rules lists them for the person the key acts as, each with enabled. Turn one on or off with PUT /alert-rules/{rule} (needs hubs:write):
curl -X PUT https://api.1keyplatform.dev/v1/alert-rules/crash_loop \
-H "Authorization: Bearer $ONEKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"enabled": true}'
Troubleshooting
Each hub's Troubleshoot tab in the portal is an AI assistant for that hub. Describe a problem, such as a lock that doesn't respond or a hub that keeps going offline, and it gathers evidence, then explains what it found in Z-Wave terms and what to do.
| Who | every member of the organization |
| Reads | the hub's connection, health, logs, black box and audit log; its devices, their interview state, values, settings, recent events and product; each device's Z-Wave node (signal, route, lifeline, wake-up) and the radio's noise and history. Run as it needs them, read live from the hub |
| Actions | sending a command, pinging or identifying a device, rebuilding its routes, interviewing it again, repairing its lifeline, forgetting it, restarting the Z-Wave radio, reconnecting the hub's network, rebooting the hub, resetting its link. Each runs only after you confirm it |
| Acting key | the API console's "Act with": its scopes limit what the assistant may read and do |
| Kept | nothing: the conversation lasts as long as the page |
What it reads goes to OpenAI to produce the answer; OpenAI stores none of it. Everything it reads or does goes through this API, and each request appears in the API console. Reads the hub's firmware doesn't support are skipped, and the assistant works from everything else.