Hubitat Hub Endpoints (grounded)

Verified 2026-07-14 against three C-8 Pro hubs on platform 2.5.1.125, local network, Hub Security off. These endpoints are undocumented and version-sensitive — Hubitat does not support them and they can shift between firmware releases. Only the Maker API and the /management/* token API are officially supported. Re-verify after a platform update; the _meta.verified_platform in skills/_reference/capabilities.json tracks the baseline.

Base is http://<hub-ip>:8080 unless noted. Websockets are on port 80 (ws://<hub-ip>/...). With Hub Security off, no authentication is needed — no login, no cookie. If a hub ever enables Hub Security, every call below needs a session cookie from POST /login.

Code enumeration (what's installed in the editors)

Confirmed returning clean JSON on 2.5.1.125:

The id from these lists is the <codeId> used in the code round-trip and update endpoints below. (These /hub2/user* endpoints supersede the older /app/list/... HTML pages the community catalogs list.)

Code round-trip (read source + version)

version is an integer bumped on every save. It is the optimistic-concurrency token — see below.

Code deploy (create / update)

All Content-Type: application/x-www-form-urlencoded.

Optimistic concurrency: the hub rejects an update whose version is not the current one. This is the "don't clobber a newer hub edit" guard. The deploy flow: read current version via /…/ajax/code, send it with the update; on rejection, re-pull and reconcile — never blindly retry with a bumped number. Save == compile: a Groovy compile error is returned inline and the code does not save.

Live logging & events (websockets)

Both confirmed on 2.5.1.125 — GET upgrade returns HTTP 101 Switching Protocols, server frames are unmasked text (opcode 1), no external library required.

Verified /logsocket frame captured live: {"name":"mZone-Butler Pantry Zone","msg":"...is inactive","id":1199,"time":"2026-07-14 08:05:53.760","type":"dev","level":"info"}.

REST log pulls also exist: GET /logs/json, /logs/eventsJson, /logs/past/json.

Event history (undocumented — grounded 2026-07-16)

Both verified on 2.5.1.128. These answer "when did this actually change?", which no status field can.

Commands are events too, and they name their caller. /device/eventsJson carries command-<name> entries (type: "command") alongside attribute changes, so a command being issued is visible separately from the attribute moving — that gap is the whole diagnosis in a silent-failure case. producedBy names the app that issued it. Verified frame:

{"name": "command-on", "value": null, "type": "command", "date": "2026-07-14T11:01:54.455-0500",
 "descriptionText": "Command called: on()", "isStateChange": false, "deviceId": 442,
 "producedBy": "<a href='/installedapp/configure/583' target='_blank' class='text-base'>HomeKit Integration</a>"}

/hub/eventsJson is how you correlate "it broke around Tuesday" with a platform update, and it pairs with the version-sensitivity warning at the top of this file: it is how you find out when the platform moved.

HTML rides inside JSON string fields. producedBy above is an anchor, not a name. So is ipAddress in /hub/details/json (<a href="http://192.0.2.12">192.0.2.12</a> (Ethernet)), and app names in the log endpoints carry status markup (Ecobee Suite Manager<span style="color:green"> Online</span> — 3570 of 8205 past-log lines held markup on the measured hub). Strip tags before matching on any of these; a name compared raw will not match.

The two log endpoints disagree about time and order

Measured on one C-7, one moment, hub TZ US/Central (-0500):

Correlating an app's log line against an event across these two silently mis-orders by the hub's offset — you conclude a handler never fired when it fired five hours "earlier". Same trap as the zwaveJS lastTime note above, on two endpoints a debugger uses together constantly.

They are also ordered oppositely — /logs/past/json is oldest-first, /logs/eventsJson is newest-first. And /logs/past/json returns a JSON array of raw pre-formatted strings, not objects: three tab-separated fields, the third pipe-delimited.

"2026-07-16 20:12:40.424\tTRACE\tapp|4|Ecobee Suite Manager|Updates sent (132 / 2095ms)"

Hub info & identity

Device usage / blast radius (undocumented — grounded 2026-07-16)

GET /device/fullJson/<deviceId> returns the hub's own computed "in use by" list for a device — verified live on 2.5.1.128 (C-8 Pro, Hub Security off). This is the removal blast radius, straight from the hub; skills/_scripts/hub_device_usage.py projects it and the device-removal skill reads it.

appsUsing is the delete blast radius, not a liveness list. Rule Machine can leave a stale tDev-N setting and state.trigDevsW entry after its live trigger moved; the old device remains in appsUsing even though state.trigDevs points elsewhere. The inert reference still belongs in a delete warning.

Device command & state surfaces (fullJson, grounded 2.5.1.134–135)

The same GET /device/fullJson/<id> that carries the blast radius also carries the device's command surface and both persistence stores — read them here instead of reading driver source or inferring from the declared capability.

deviceState and device.currentStates are easy to reach for backwards — Groovy state is top-level deviceState, attributes are nested under device. currentStates[attr].date is the last change, not the last report — it sits right beside value and reads like a freshness stamp but is not one (the rules/state-vs-attributes.md trap, embodied in a field). Measure a real gap distribution with GET /device/eventsJson/<id>.

Read-route response-shape traps (grounded 2.5.1.134)

Defensive-parse these — each bit during the irrigation recon:

• GET /hub2/appsList returns a dict with an apps key, not a list. Built-in app entries populate name and leave label null.
• GET /installedapp/statusJson/<id> can return a bare {} — another instance of this route being unreliable for reading app config (below).
• GET /installedapp/configure/json/<appId>/mainPage can return non-JSON — parse defensively, do not assume a JSON body.
• GET /device/edit/<id> is a 6.8 KB SPA shell — no state, no routes, nothing in the served HTML. It is the natural first thing to try for a device and it is a dead end; drive the page with Playwright and capture the request instead (skills/_reference/playwright-ui.md).

Installed-app configuration and live-consumer surfaces (grounded through 2026-07-24)

GET /installedapp/statusJson/<appId> carries several distinct surfaces:

GET /installedapp/configure/json/<appId>/<page>.settings remains the page-specific configured-input view and also carries removeButton. A page value is a device-id→label map, not a {value: ...} wrapper. Configuration alone does not prove liveness.

For Rule Machine, read trigDevs even when eventSubscriptions is empty: a false Required Expression temporarily removes subscriptions while the trigger remains correctly configured. Absence from trigDevs is a negative only for a trigger-role reference. A Rule Machine action or condition device may be live without appearing in that trigger map. For arbitrary apps, a missing subscription is not a safe negative because command-only consumers do not subscribe. skills/_scripts/hub_device_usage.py --live applies this three-state audit and leaves unsupported negative cases unknown.

Device control (official — Maker API)

Prefer Maker API for exercising devices in a test loop. Local: http://<hub-ip>/apps/api/<makerAppId>/<path>?access_token=<token>. The <token> is a secret — read it from an environment variable or the operator's secrets store at call time; never hardcode it, commit it, echo it into agent output, or write it to a log (a token carried in a query string otherwise leaks into request logs). The undocumented local endpoints above are the preferred path precisely because they need no token on a Hub-Security-off hub. Key paths: /devices (list), /devices/all (full JSON: capabilities, attributes, commands), /devices/<id>, /devices/<id>/<command>/<secondaryValue> (send command), /devices/<id>/events. Multi-hub note: with hubs meshed, one Maker API instance can expose devices from secondary hubs too — but code endpoints are per-hub and have no mesh.

UI-fired requests you can replay (undocumented — grounded 2026-07-19 – 07-22)

Several operations documented as "UI-only" are ordinary HTTP requests the UI fires. Drive the UI once with Playwright, read the request the button fires (browser_network_requests), then replay it directly thereafter — the UI is the discovery tool, not the runtime. Baseline for this section: C-8 Pro, 2.5.1.x, zwaveJS backend, local network, Hub Security off; re-verify after a platform update. Still expanding as findings accumulate.

Hub Mesh sharing is two-sided. The source hub shares a device (addToMesh); the destination hub must then explicitly link it (createLinked) — a shared device does not auto-appear on the destination, and neither a Linked-devices refresh nor hubMeshFullRefreshNow links it. The Hub Mesh UI lives at /device/hubMesh (not /hub2/hubMesh, which 404s). Un-share / un-link are not yet captured — removeFromMesh and a removeLinked counterpart are likely but unverified; do not assume the path. Read side is /hub2/hubMeshJson (Hub mesh section below); this grounds the cross-hub re-home in skills/device-migration/SKILL.md.

Instance creation is transient. createchild (parent/child, e.g. Room Lighting) and create (standalone user app) both land on /installedapp/configure/<newId>/mainPage that persists only on Done (_action_update) and is discarded on Cancel — the parent/child and standalone companions to GET /installedapp/direct/<builtInAppType> for built-in apps (above). The UI-drive mechanics for filling and committing those config pages are in skills/_reference/playwright-ui.md (gotchas 16, 27–28).

nodeRemove is guarded to FAILED orphans only. Verified 23× live on nodes with no bound deviceId, each confirmed by census diff against /hub/zwaveDetails/json. Behavior on a healthy/OK node (strict removeFailedNode vs. general remove) is untested — gate every call on present + no deviceId + nodeState:FAILED, and never POST a real device id.

runmethod is the "flash a stale device to wake it" primitive — verified {"id":389,"method":"on","args":[]} turned a plug on and flipped its Z-Wave nodeState FAILED→OK.

A command return code is not evidence it executed. runmethod returns {"success":true} when the Groovy method is dispatched, not when the device moved — a method that throws, or a command to the state the device is already in, returns the identical payload, and in the already-in-state case the platform's change filter suppresses the event too (rules/state-vs-attributes.md), so "no event" does not distinguish worked from failed. This is the same success-shaped-lie as /device/delete returning 302 for a nonexistent id. Confirm through the command's relatedAttribute moving in currentStates, or through GET /device/eventsJson/<id>. The command surface (fullJson.commands[]) is in Device command & state surfaces above.

POST /device/update (device rename/edit) — verified 9 devices, 2.5.1.135. Same /device/ namespace as runmethod, entirely different conventions — do not assume one shape from the other:

The full field set: name, label, zigbeeId, maxEvents, maxStates, spammyThreshold, deviceNetworkId, deviceTypeId, deviceTypeReadableType, roomId, meshEnabled, retryEnabled, meshFullSync, homeKitEnabled, locationId, hubId, groupId, dashboardIds, tags, defaultIcon, notes, id, version, controllerType. Three traps:

• version is an optimistic-concurrency token, the same pattern as /app/ajax/code (rules/multi-hub-topology.md) — read it fresh from fullJson immediately before each POST; a successful update bumps it.
• The form mixes two boolean encodings. meshEnabled / meshFullSync are checkbox-semantic — sent as on when true, omitted entirely when false. retryEnabled / homeKitEnabled, right beside them, are literal true / false strings. Mis-encoding the mesh pair is destructive: it disables hub-mesh sharing, removing the mirrored device on the consuming hub and breaking every app bound to the mirror. A naive "serialize all booleans the same way" replay triggers it.
• The label input hides on an inactive PrimeVue tab — UI-capture mechanics in skills/_reference/playwright-ui.md.

Retention fields are display-tuned defaults. maxEvents defaults to 11 per attribute — 11 stored changes, not reports (eventsJson is change-filtered), so on a slow-moving signal it is a few hours and on a fast-changing one under an hour, rolled silently either way. maxStates 30, spammyThreshold 300. Raise maxEvents through this endpoint to use the hub as a short-horizon data buffer — 1000 covers ~two weeks of a slow-moving signal (rules/data-collection.md).

Hub-mesh mirrors follow a rename automatically — all nine mirror name values updated on the consuming hub with no action there. This is the opposite of delete, where mirrors survive the source's removal and need cleanup on both hubs (rules/device-lifecycle.md): rename propagates, delete does not.

Z-Wave rebuild is gated by node type. The per-node "Rebuild route" action is offered only for mains / always-listening nodes (repeaters, plugs, lamps); sleepy battery nodes (e.g. a door lock) show only Refresh · State — no on-demand route rebuild. The global rebuild (zwaveRepair2) is the only lever that touches a sleepy node, and its route rebuilds on its next wake — it sits in the status Pending list and completes async. zwaveJS backend only (the "Rebuild network" label); legacy uses different wording. For a marginal battery node the durable fix is RF/topology — a repeater — not a repair click (rules/zwave-zigbee-mesh.md).

Z-Wave & Zigbee mesh detail (undocumented — grounded through 2026-07-23)

Both return clean JSON through 2.5.1.132, no auth with Hub Security off. Drive them for mesh diagnostics; the mesh-health skill reads them via skills/_scripts/hub_mesh.py.

Z-Wave nodes[] per-node fields: nodeId, deviceId (Hubitat device id), deviceName, nodeState (OK | FAILED — FAILED is a failed/ghost node), msgCount (int — traffic volume; weigh per against it), per (cumulative packet-error count, not a %), averageRtt (ms, string), lwrRssi (string — see scale note), neighbors (int), routeChanges (int or N/A), route, security, listening, beaming, batteryPercent, lastTime (when the hub last heard the node — see the timestamp trap below; absent on a node never heard, which is reported nodeState:OK).

listening:true is the always-on / classic-mesh repeater indicator. beaming means the node requires beam wake-up, not that it beams for others; its JSON value was false for every sampled node on 2.5.1.132, including FLiRS locks, so read the Z-Wave Details UI Beaming column when that status matters. route uses hexadecimal ids and includes hub plus destination: 01 -> 57 is direct to node 0x57; only intermediate ids are repeaters.

Zigbee devices[] liveness trap: active is not freshness. Devices silent for years still reported active:true on 2.5.1.132. Use the offset-bearing lastActivity timestamp; a missing timestamp is unknown. A generic name:"Device" / type:"Device" remains the unfinished-join signature.

Timestamp trap (grounded 2026-07-16, 2.5.1.128): lastTime carries a different shape per Z-Wave backend. The legacy backend emits an explicit offset — 2026-07-16T00:49:14+0000, true UTC. The zwaveJS backend emits a naive stamp in the hub's local zone — 2026-07-16T08:28:30.081. Reading a naive stamp as UTC ages every zwaveJS node by the hub's offset (measured: a 70-second-old node read as 5.02 h on America/Chicago). The zone is timeZone in GET /hub/details/json. Zigbee's lastActivity carries +0000 on both. A second backend split beside the lwrRssi scale.

Hub mesh (undocumented — grounded 2026-07-16)

GET /hub2/hubMeshJson — the hub's own peer table (read side). Hub mesh carries commands between hubs, so a peer with a stale record drops them while every radio metric stays green; skills/_scripts/hub_mesh.py analyzes it and the mesh-health skill reads it. The write side — share (addToMesh) and link (createLinked) a device — is in the UI-fired requests section above.

hubId == hubUID: the hubId here is the same identifier as hubUID in GET /hub/details/json (verified across three hubs). Fetching a peer's ipAddress and comparing its hubUID to the recorded hubId is what distinguishes a live peer, a dead address, and an address reassigned to another hub.

The peer fields do not detect a stale record. A peer whose ipAddress pointed at a long-dead address on another subnet reported active:true, offline:false, warning:null, with lastActive refreshing every few seconds, while every command to it was silently dropped for 13.7 h. Only probing the address finds it. The table is asymmetric — each hub keeps its own record of the others, and one side can be correct while the other is stale.

Zigbee devices[] per-device fields: id, name, type, active (bool), ping, messageCount, lastActivity, lastMessage, shortZigbeeId (16-bit), zigbeeId (64-bit IEEE). No per-device LQI or RSSI is exposed here — per-device (router) LQI is in getChildAndRouteInfo above; per-frame LQI+RSSI in the radio log sockets below. Use lastActivity for snapshot liveness; active is not a freshness field.

Live radio log websockets (verified 2026-07-15 on 2.5.1.128, HTTP 101, unmasked text frames, case-sensitive paths) — the per-frame decoded traffic, distinct from the driver /logsocket. Tail via skills/_scripts/hub_radiolog.py:

Backend vs topology — two independent axes, both verified live (the load-bearing gotcha):

• Backend (zwaveJS true/false) sets the lwrRssi scale — absolute dBm (negative, e.g. -78db) on zwaveJS vs dB above the noise floor (positive, e.g. 27dB) on legacy — and whether routeChanges is reported (N/A on zwaveJS, an int on legacy). Higher RSSI is better on both; a fixed numeric cutoff does not transfer.
• Topology sets neighbors and routing: node id ≥ 256 = Z-Wave Long Range (a star — neighbors:0, a direct 01 -> <node> route, no repeaters, dynamic power); id ≤ 232 = classic mesh (neighbors + multi-hop routes). Verified: a classic node and LR nodes on the same zwaveJS hub show neighbors:5 vs 0, so neighbors:0 is LR topology, not the backend.

Field meanings and the LR-vs-mesh remediation split: rules/zwave-zigbee-mesh.md.

Hub management (official — token API)

GET /hub/advanced/getManagementToken → token, then /management/reboot?token=, /management/firmwareUpdate?token=. The Hub Information Driver (HPM) wraps reboot/update as device commands over Maker API.