REST API reference¶
An index of every REST operation, generated from assets/openapi.yaml. Paths are relative to the server base /api/v1. Request and response schemas are in the OpenAPI document itself; authentication, versioning and examples in REST & WebSocket API.
Access is what the operation's security declaration (or the document-wide default it inherits) requires: public needs no credentials, authenticated any signed-in identity, and a role name (viewer, operator, admin) that role or a higher one.
System¶
| Method | Path | Summary | Access |
|---|---|---|---|
| GET | /i18n/entities | The daemon's entity-name vocabulary | viewer |
admin¶
| Method | Path | Summary | Access |
|---|---|---|---|
| POST | /admin/tls/certificate | Replace the TLS server certificate at runtime (admin-only) | admin |
alarm¶
Alarm system zones, arming, sensors, outputs, journal, walk-test
| Method | Path | Summary | Access |
|---|---|---|---|
| GET | /alarm/codes | List alarm codes (operator) | operator |
| POST | /alarm/codes | Create an alarm code (operator) | operator |
| GET | /alarm/codes/{id} | Get one alarm code (operator) | operator |
| PUT | /alarm/codes/{id} | Replace an alarm code (operator) | operator |
| DELETE | /alarm/codes/{id} | Delete an alarm code (operator) | operator |
| GET | /alarm/incidents | List the incident history of one alarm zone | viewer |
| GET | /alarm/incidents/{id} | Get one alarm incident with its full source ledger | viewer |
| GET | /alarm/journal | Query the alarm engine's event journal | viewer |
| GET | /alarm/output-candidates | Channels that can back a device-backed alarm output class | viewer |
| POST | /alarm/outputs/{id}/test | Fire an alarm output briefly for a walk test (operator) | operator |
| GET | /alarm/panels | List the alarm-control-panel entity projections | viewer |
| GET | /alarm/remote-key-candidates | Remote/wall-button key channels usable for remote-key code bindings | viewer |
| POST | /alarm/reset-motion | Clear every latched motion detector across all zones (operator) | operator |
| GET | /alarm/sensor-candidates | List the data points a zone can enrol as alarm sensors | viewer |
| POST | /alarm/silence-all | Silence the active incident on every alarm zone at once (operator) | operator |
| GET | /alarm/state | Current live status of every alarm zone | viewer |
| GET | /alarm/triggered-motion | List the latched motion detectors that a reset would clear | viewer |
| GET | /alarm/zones | List all configured alarm zones | viewer |
| POST | /alarm/zones | Create a new alarm zone (operator) | operator |
| GET | /alarm/zones/{id} | Get a single alarm zone by id | viewer |
| PUT | /alarm/zones/{id} | Replace an alarm zone (operator) | operator |
| DELETE | /alarm/zones/{id} | Delete an alarm zone (operator) | operator |
| POST | /alarm/zones/{id}/acknowledge | Acknowledge (clear) a finished incident on an alarm zone (operator) | operator |
| POST | /alarm/zones/{id}/arm | Arm an alarm zone (operator) | operator |
| POST | /alarm/zones/{id}/disarm | Disarm an alarm zone (operator) | operator |
| GET | /alarm/zones/{id}/outputs | List the outputs enrolled in an alarm zone | viewer |
| PUT | /alarm/zones/{id}/outputs | Replace the full output set of an alarm zone (operator) | operator |
| GET | /alarm/zones/{id}/readiness | Per-mode arm-readiness of an alarm zone | viewer |
| POST | /alarm/zones/{id}/reset-motion | Clear the latched motion detectors of one zone (operator) | operator |
| GET | /alarm/zones/{id}/sensors | List the sensors enrolled in an alarm zone | viewer |
| PUT | /alarm/zones/{id}/sensors | Replace the full sensor set of an alarm zone (operator) | operator |
| POST | /alarm/zones/{id}/silence | Silence the active incident on an alarm zone without disarming (operator) | operator |
| GET | /alarm/zones/{id}/walktest | Live status of an alarm zone's walk-test session | viewer |
| POST | /alarm/zones/{id}/walktest/start | Start a walk-test session on an alarm zone (operator) | operator |
| POST | /alarm/zones/{id}/walktest/stop | Stop the running walk-test session on an alarm zone (operator) | operator |
audit¶
| Method | Path | Summary | Access |
|---|---|---|---|
| GET | /audit | Recent change history (FIFO buffer) | admin |
auth¶
| Method | Path | Summary | Access |
|---|---|---|---|
| POST | /auth/login | Issue session cookie | public |
| POST | /auth/logout | Revoke current session | viewer |
| GET | /auth/me | Current identity probe | viewer |
| PATCH | /auth/me/password | Change the logged-in user's own password | authenticated |
| GET | /auth/oidc/callback | OIDC authorization code callback — exchanges code for session | public |
| GET | /auth/oidc/start | Initiate OIDC authorization code flow (redirect to IdP) | public |
| GET | /auth/tokens | List API tokens with elided fingerprints (admin) | admin |
| POST | /auth/tokens | Issue a new bearer token (admin) | admin |
| DELETE | /auth/tokens/{id} | Revoke an API token (admin) | admin |
| GET | /auth/users | List configured Basic-auth users (admin) | admin |
| GET | /me/preferences/{key} | Read the caller's UI preference for | authenticated |
| PUT | /me/preferences/{key} | Store the caller's UI preference for | authenticated |
| DELETE | /me/preferences/{key} | Delete the caller's UI preference for | authenticated |
| POST | /pairing | Ask for an API token via code pairing | public |
| GET | /pairing-requests | Pending pairing requests, with their codes | admin |
| POST | /pairing-requests/{id}/approve | Approve a pairing by typing its code | admin |
| POST | /pairing-requests/{id}/reject | Reject a pairing request | admin |
| GET | /pairing/{id} | Wait for the pairing decision | public |
| DELETE | /pairing/{id} | Withdraw the pairing request | public |
backup¶
| Method | Path | Summary | Access |
|---|---|---|---|
| GET | /backups | Locally stored CCU backups | admin |
| POST | /backups | Trigger CCU backup (Rega create_backup_start) | admin |
| GET | /backups/storage | Where locally-stored CCU backups are kept | admin |
| DELETE | /backups/{id} | Delete one stored CCU backup | admin |
| GET | /backups/{id}/download | Stream a backup .sbk | admin |
| POST | /backups/{id}/restore | Restore a CCU backup from a previously stored snapshot | admin |
central-admin¶
Central (CCU) CRUD — DB-backed multi-CCU registry
| Method | Path | Summary | Access |
|---|---|---|---|
| GET | /centrals | List all configured centrals | viewer |
| POST | /centrals | Create a new central (admin) | admin |
| GET | /centrals/discovered | List CCUs found via SSDP/UPnP discovery | admin |
| GET | /centrals/discovered/ignored | List the discovered CCUs the operator has ignored | admin |
| POST | /centrals/discovered/{serial}/ignore | Ignore a discovered CCU (admin) | admin |
| DELETE | /centrals/discovered/{serial}/ignore | Un-ignore a discovered CCU (admin) | admin |
| POST | /centrals/pairing | Start client pairing with an openccu-lite box | admin |
| GET | /centrals/pairing/{id} | A pairing's state | admin |
| DELETE | /centrals/pairing/{id} | Withdraw a pairing | admin |
| POST | /centrals/probe | Identify the system at an address (admin) | admin |
| GET | /centrals/{name} | Get a single central by name | viewer |
| PUT | /centrals/{name} | Replace a central (admin) | admin |
| DELETE | /centrals/{name} | Delete a central (admin) | admin |
config¶
Channel configuration export / import (portable snapshots)
| Method | Path | Summary | Access |
|---|---|---|---|
| GET | /devices/{addr}/channels/{no}/config/export | Export a channel's paramset as a portable JSON snapshot | viewer |
| POST | /devices/{addr}/channels/{no}/config/import | Import a previously-exported channel paramset snapshot | operator |
config-admin¶
Live config section read / write / delete + schema introspection
| Method | Path | Summary | Access |
|---|---|---|---|
| GET | /config/effective | Effective merged configuration with source annotations (admin) | admin |
| DELETE | /config/fields/{path} | Reset one config field to its default (admin) | admin |
| GET | /config/schema | Config field schema — section list + typed field descriptors | viewer |
| GET | /config/sections/{section} | Read one config section (admin) | admin |
| PUT | /config/sections/{section} | Replace one config section (admin) | admin |
| DELETE | /config/sections/{section} | Delete one config section (admin) | admin |
| GET | /ui/surfaces | Config-UI surface registry and the live profile | authenticated |
| PUT | /ui/surfaces | Update the surface profiles or the embedded master toggle (admin) | admin |
core¶
| Method | Path | Summary | Access |
|---|---|---|---|
| GET | /config | Sanitized effective configuration | viewer |
| GET | /diagrams | List saved diagram definitions (own + shared) | viewer |
| POST | /diagrams | Create a diagram definition | operator |
| GET | /diagrams/{id} | Read a diagram definition | viewer |
| PUT | /diagrams/{id} | Update a diagram definition (owner or admin) | operator |
| DELETE | /diagrams/{id} | Delete a diagram definition (owner or admin) | operator |
| GET | /groups | Heating-group listing (read-only) | viewer |
| POST | /groups | Create a heating group (admin) | admin |
| GET | /groups/suitable-members | Devices assignable to a group of a given type | viewer |
| GET | /groups/types | Assignable group types for the create form | viewer |
| PUT | /groups/{id} | Edit a heating group (admin) | admin |
| DELETE | /groups/{id} | Delete a heating group (admin) | admin |
| GET | /health | Aggregated health snapshot | public |
| GET | /info | Daemon build + runtime info | public |
| GET | /links | Global direct-link overview (read-only) | viewer |
| GET | /sbom | Software bill of materials of this build | viewer |
| GET | /schedules | Fleet-wide overview of week schedules | viewer |
| GET | /system/ccu | Per-central CCU metadata | viewer |
| GET | /system/config-changes | Config fields changed since the daemon started | viewer |
| GET | /system/restart-pending | Whether a saved config change needs a daemon restart | viewer |
| GET | /system/status | Recent system-status events | viewer |
| POST | /ui/event | SPA telemetry sink (fire-and-forget) | viewer |
| GET | /warnings | Operator warnings, with the caller's silences | viewer |
| PUT | /warnings/{id}/silence | Mute one active warning for the calling user | viewer |
| DELETE | /warnings/{id}/silence | Remove the calling user's silence for one warning | viewer |
devices¶
| Method | Path | Summary | Access |
|---|---|---|---|
| GET | /devices | Paginated device list | viewer |
| POST | /devices/firmware/refresh | Re-read device firmware data from every CCU | operator |
| POST | /devices/refresh | Force CCU re-pull on every backend | operator |
| POST | /devices/values:batch | Batch-read data-point values in one round trip | viewer |
| GET | /devices/{addr} | Single device detail | viewer |
| PATCH | /devices/{addr} | Update mutable device metadata (name, room assignment) | operator |
| DELETE | /devices/{addr} | Remove a device from the registry (admin) | admin |
| POST | /devices/{addr}/accept | Promote a pending pairing into the registry | operator |
| GET | /devices/{addr}/cdps | List all custom data points of a device | viewer |
| GET | /devices/{addr}/cdps/{name} | Get a single custom data point by name | viewer |
| POST | /devices/{addr}/cdps/{name}/{operation} | Invoke an operation on a custom data point (turn_on, set_temperature, open, …) | operator |
| GET | /devices/{addr}/channels | viewer | |
| GET | /devices/{addr}/channels/{no} | viewer | |
| PATCH | /devices/{addr}/channels/{no} | Update a single channel (rename, rooms, functions) | operator |
| GET | /devices/{addr}/channels/{no}/calc-dps | List all calculated data points on a channel | viewer |
| GET | /devices/{addr}/channels/{no}/calc-dps/{name} | Get a single calculated data point by name | viewer |
| GET | /devices/{addr}/channels/{no}/data-points | viewer | |
| GET | /devices/{addr}/channels/{no}/data-points/{param} | viewer | |
| PUT | /devices/{addr}/channels/{no}/data-points/{param}/value | Set a data point value on the CCU | operator |
| GET | /devices/{addr}/channels/{no}/event-groups | List per-Kind event groups for a channel | viewer |
| GET | /devices/{addr}/channels/{no}/flags | Get the operator per-channel overrides (G12) | viewer |
| PUT | /devices/{addr}/channels/{no}/flags | Set the operator per-channel overrides (G12) | operator |
| GET | /devices/{addr}/channels/{no}/linkable-channels | Eligible link partners for the channel | viewer |
| POST | /devices/{addr}/channels/{no}/reload | Re-pull a single channel's config from its CCU | operator |
| PUT | /devices/{addr}/channels/{no}/team | Assign a channel to a team | operator |
| GET | /devices/{addr}/channels/{no}/team-candidates | List team channels a channel may be assigned to | viewer |
| GET | /devices/{addr}/channels/{no}/ui-schema | Renderable form descriptor for a channel paramset | viewer |
| PUT | /devices/{addr}/channels/{no}/week_profile/channel-locks/{key} | Toggle one target channel's week-program participation — the write | operator |
| POST | /devices/{addr}/config/cache-clear | Drop the interface process's cached device configuration (admin-only) | admin |
| POST | /devices/{addr}/config/repair | Rebuild a device's stored MASTER configuration (admin-only) | admin |
| POST | /devices/{addr}/config/restore | Re-transmit stored configuration to a device (admin-only) | admin |
| GET | /devices/{addr}/export-definition | Export a device definition as an aiohomematic-compatible zip | viewer |
| POST | /devices/{addr}/firmware/update | Trigger OTA firmware update for the device | operator |
| GET | /devices/{addr}/icon | Device-type icon image (proxied from the CCU) | viewer |
| POST | /devices/{addr}/install-mode | Open a targeted pairing window for one device | operator |
| POST | /devices/{addr}/release | Finish onboarding and publish the device to the ecosystems | operator |
| POST | /devices/{addr}/reload | Re-pull a single device's config from its CCU | operator |
| POST | /devices/{addr}/replace | Replace a paired device with a new one (admin-only) | admin |
| GET | /devices/{addr}/replace-candidates | List devices the new device may replace | viewer |
| POST | /devices/{addr}/rf-interface | Assign a BidCos-RF device to an RF interface (admin-only) | admin |
| POST | /devices/{addr}/test | Run the per-device communication / function test | operator |
| POST | /devices/{addr}/values-cache/reset | Drop the VALUES-cache rows for one device (admin-only) | admin |
diagnostics¶
| Method | Path | Summary | Access |
|---|---|---|---|
| POST | /admin/cache/clear | Clear CCU-derivable caches and re-pull them fresh (admin-only) | admin |
| POST | /admin/mqtt/reload | Tear down + rebuild the MQTT stack (admin-only) | admin |
| POST | /admin/values-cache/reset | Drop every row from the persistent VALUES cache (admin-only) | admin |
| GET | /admin/values-cache/stats | Persistent VALUES-cache statistics (admin-only) | admin |
| GET | /diagnostics | Composite diagnostics dump (health + interfaces + incidents + metrics + log-levels) | admin |
| GET | /diagnostics/capture | List active + archived captures (admin-only) | admin |
| POST | /diagnostics/capture | Start a RAM-buffered log capture (admin-only) | admin |
| GET | /diagnostics/capture/{id} | Capture metadata (admin-only) | admin |
| GET | /diagnostics/capture/{id}/download | Download capture archive (admin-only) | admin |
| POST | /diagnostics/capture/{id}/stop | Stop a running capture (admin-only) | admin |
| GET | /diagnostics/eventbus/tap | Live event-bus tap (NDJSON, admin-only) | admin |
| GET | /diagnostics/log-level | Current global default log level | viewer |
| PUT | /diagnostics/log-level | Change the global default log level (admin-only) | admin |
| GET | /diagnostics/log-levels | Active per-subsystem log-level overrides | viewer |
| PUT | /diagnostics/log-levels/{path} | Install a per-subsystem log-level override (admin-only) | admin |
| DELETE | /diagnostics/log-levels/{path} | Remove a per-subsystem log-level override (admin-only) | admin |
| GET | /diagnostics/logs | Backfill / download recent log records (admin-only) | admin |
| GET | /diagnostics/logs/stream | Server-Sent-Events live log tail (admin-only) | admin |
| GET | /diagnostics/reliability | Per-interface reliability snapshot (admin-only) | admin |
| GET | /diagnostics/rpc-recording | Current RPC-recorder status per central | admin |
| POST | /diagnostics/rpc-recording | Start the XML/JSON-RPC session recorder (replay capture, admin-only) | admin |
| POST | /diagnostics/rpc-recording/stop | Stop the RPC session recorder (admin-only) | admin |
| GET | /diagnostics/rpc-recording/{central}/download | Download a central's recorded RPC trace as JSON (admin-only) | admin |
| GET | /diagnostics/rssi | Per-device signal quality and battery (admin-only) | admin |
| GET | /diagnostics/rssi/matrix | Pairwise BidCos-RF reception matrix (admin-only) | admin |
| GET | /diagnostics/rssi/receiver-proposal | Best-interface proposal per BidCos-RF device (admin-only) | admin |
| GET | /diagnostics/wiring | Seams the running daemon declared as it wired them (admin-only) | admin |
| GET | /incidents | Diagnostic incidents | viewer |
| DELETE | /incidents | Clear every stored incident across every registered central (admin) | admin |
| GET | /metrics | Prometheus metrics (also at /metrics) | viewer |
events¶
| Method | Path | Summary | Access |
|---|---|---|---|
| GET | /events | Upgrade to the WebSocket event stream | viewer |
history¶
| Method | Path | Summary | Access |
|---|---|---|---|
| GET | /energy | Per-device power/energy breakdown over time | viewer |
| GET | /history | Bucketed measurement history for one data point | viewer |
| GET | /history/recording | Effective per-datapoint recording state (read-only) | viewer |
| PUT | /history/recording | Set or clear a per-datapoint recording override | operator |
hub¶
| Method | Path | Summary | Access |
|---|---|---|---|
| POST | /alarm-messages/ack-all | Acknowledge all alarm messages | operator |
| POST | /alarm-messages/{id}/ack | Acknowledge alarm message | operator |
| GET | /areas | Operator-defined room groupings (areas) with their assigned rooms | viewer |
| POST | /areas | Create an area (operator) | operator |
| PUT | /areas/{id} | Rename/reorder an area (operator) | operator |
| DELETE | /areas/{id} | Delete an area and clear its room assignments (operator) | operator |
| PUT | /areas/{id}/rooms | Replace the full room set of an area (operator) | operator |
| GET | /functions | Aggregated function-group index with device counts | viewer |
| POST | /functions | Create a function/Gewerk on the CCU (operator) | operator |
| PATCH | /functions/{name} | Rename a function/Gewerk (operator) | operator |
| DELETE | /functions/{name} | Delete a function/Gewerk (operator) | operator |
| GET | /hub/data-points | Aggregated hub-singleton snapshot (one entry per central) | viewer |
| GET | /inbox | Pending pairing candidates | viewer |
| GET | /install-mode/interfaces | Per-interface install-mode state. One entry per install-mode data | viewer |
| POST | /install-mode/interfaces | operator | |
| POST | /install-mode/search | Scan the wired bus for new devices (BidCos-Wired) | operator |
| GET | /programs | viewer | |
| GET | /programs/{id} | Fetch a single program by id | viewer |
| PATCH | /programs/{id} | Toggle program active flag | operator |
| DELETE | /programs/{id} | Delete a program from the CCU (admin) | admin |
| POST | /programs/{id}/execute | Triggers a CCU program. Programs typically drive actuators or | operator |
| GET | /rooms | Aggregated room index with device counts | viewer |
| POST | /rooms | Create a room on the CCU (operator) | operator |
| PATCH | /rooms/{name} | Rename a room (operator) | operator |
| DELETE | /rooms/{name} | Delete a room (operator) | operator |
| POST | /service-messages/ack-all | Acknowledge all quittable service messages | operator |
| GET | /service-messages/suppressed | List permanently suppressed service messages | operator |
| POST | /service-messages/unsuppress | Clear a permanent service-message suppression | operator |
| POST | /service-messages/{id}/ack | Acknowledge service message | operator |
| POST | /service-messages/{id}/disable | Disable (permanently suppress) a service message | operator |
| GET | /system/metrics | Hub metric samples per central as JSON — the machine-readable twin | viewer |
| GET | /system/update | CCU system-update info per central — the data behind the reference | viewer |
| POST | /system/update/install | Starts the CCU firmware update. With backup_first a full CCU backup is taken first and the update starts only once it is durably stored; a failed backup aborts and the update does not run, because the point of asking for one is to have something to return to. The call then blocks for as long as the backup takes — minutes on a large configuration — since its response is what tells the operator whether that safety net exists. | admin |
| GET | /sysvars | viewer | |
| POST | /sysvars | Create sysvar on the CCU (Rega create_system_variable) | operator |
| POST | /sysvars/fetch | Force re-pull the CCU system-variable catalogue into the hub model | operator |
| GET | /sysvars/{name} | viewer | |
| PUT | /sysvars/{name} | Set the sysvar runtime value. Idempotent — body carries {value} only. | operator |
| PATCH | /sysvars/{name} | Update the sysvar metadata (name, description, unit, value_list, min, max). Triggers the Rega update_system_variable script via JSON-RPC. All fields are optional — omitted fields leave CCU metadata unchanged. A non-empty name renames the variable in place. Type changes are not supported; delete and recreate the sysvar instead. | operator |
| DELETE | /sysvars/{name} | Delete sysvar on the CCU (Rega delete_system_variable) | operator |
| GET | /sysvars/{name}/usage | Programs referencing a system variable (read-only) | viewer |
| GET | /taxonomy | Every central's taxonomy trees (rooms, functions, and other enums) | viewer |
| POST | /taxonomy/{central}/{enum}/nodes | Create a taxonomy node (operator) | operator |
| PATCH | /taxonomy/{central}/{enum}/nodes | Rename and/or move a taxonomy node (operator) | operator |
| DELETE | /taxonomy/{central}/{enum}/nodes | Delete a taxonomy node and its subtree (operator) | operator |
interfaces¶
| Method | Path | Summary | Access |
|---|---|---|---|
| GET | /interfaces | viewer | |
| GET | /interfaces/{id} | viewer | |
| POST | /interfaces/{id}/reconnect | admin |
links¶
| Method | Path | Summary | Access |
|---|---|---|---|
| GET | /devices/{addr}/central-links | PRESS-event forwarding status for the device | viewer |
| POST | /devices/{addr}/central-links | Enable central click-event forwarding | operator |
| DELETE | /devices/{addr}/central-links | Disable central click-event forwarding | operator |
| GET | /devices/{addr}/link-ps/{peer} | LINK paramset between this channel and a peer | viewer |
| PUT | /devices/{addr}/link-ps/{peer} | Write LINK paramset to a peer | operator |
| GET | /devices/{addr}/links | List direct links of the device | viewer |
| POST | /devices/{addr}/links | Add a direct link (sender → receiver) | operator |
| PATCH | /devices/{addr}/links | Rename a direct link (change name / description) | operator |
| DELETE | /devices/{addr}/links | Remove a direct link | operator |
| POST | /devices/{addr}/links/test | Test a direct link at the device (activate link paramset) | operator |
messages¶
| Method | Path | Summary | Access |
|---|---|---|---|
| GET | /alarm-messages | viewer | |
| GET | /service-messages | viewer |
node¶
| Method | Path | Summary | Access |
|---|---|---|---|
| GET | /node/compatibility | The commissioned ecosystems and known incompatibilities. | viewer |
| GET | /node/endpoints | The bridged endpoints a controller sees. | viewer |
| GET | /node/endpoints/{ep} | One endpoint the node serves, with its attribute values (0.4.1). | viewer |
| GET | /node/endpoints/{ep}/events | The events the node's event log holds for one endpoint (0.4.1). | viewer |
| GET | /node/events | The pairing, session and discovery trace, newest first. | viewer |
| GET | /node/exposure | Every item the host could expose. | viewer |
| PUT | /node/exposure | Apply a batch of item changes and reassemble the endpoints. | admin |
| POST | /node/exposure/preview | The items as a batch of changes would leave them; nothing is written. | admin |
| GET | /node/exposure/schema | How the selection page shows the host's items. | viewer |
| GET | /node/fabrics | The commissioned fabrics. | viewer |
| DELETE | /node/fabrics/{index} | Remove one fabric. | admin |
| POST | /node/maintenance/erase | Erase the node — its store and endpoint records — and end it. The body must name the action. | admin |
| POST | /node/maintenance/factory-reset | Remove every fabric. The body must name the action. | admin |
| POST | /node/maintenance/reassemble | Rebuild the endpoints from the host's current selection; pairings are untouched. | admin |
| GET | /node/mdns | The live DNS-SD advertisement and its diagnosis. | viewer |
| POST | /node/mdns/reannounce | Announce the node's DNS-SD records now. | admin |
| GET | /node/pairing | The pairing codes — of the window this handler opened while it is open, else the configured ones. | admin |
| POST | /node/pairing/window | Open a commissioning window. | admin |
| POST | /node/pairing/window/close | Close the open commissioning window. | admin |
| GET | /node/sessions | The open secure sessions and the session-id occupancy. | viewer |
| GET | /node/status | Health, counts and the commissioning window. | viewer |
| GET | /node/stream | Server-sent events. | viewer |
| GET | /node/surface | The node's surface report. | viewer |
| GET | /node/topology | The node as a graph — its bridge, its fabrics and the sessions on them. | viewer |
paramsets¶
| Method | Path | Summary | Access |
|---|---|---|---|
| POST | /devices/{addr}/channels/{no}/paramsets/{key}/determine | Read one parameter's live value from the device | viewer |
| GET | /devices/{addr}/paramsets/{key} | viewer | |
| PUT | /devices/{addr}/paramsets/{key} | Write a paramset atomically (one wire call) | operator |
| GET | /devices/{addr}/paramsets/{key}/apply-targets | Channels a MASTER paramset may be applied to | viewer |
| POST | /devices/{addr}/paramsets/{key}/apply-to | Apply MASTER values to several description-identical channels | operator |
schedules¶
| Method | Path | Summary | Access |
|---|---|---|---|
| GET | /devices/{addr}/channels/{no}/schedule | Climate or simple schedule of one channel | viewer |
| PUT | /devices/{addr}/channels/{no}/schedule | Replace channel schedule | operator |
| POST | /devices/{addr}/channels/{no}/schedule/active-profile | Pick the active climate profile (P1..P6) | operator |
| GET | /devices/{addr}/channels/{no}/week_profile | Week-profile metadata for one channel | viewer |
| POST | /devices/{addr}/channels/{no}/week_profile/copy | Copy a single climate profile to another channel/profile | operator |
| GET | /devices/{addr}/schedule | Auto-resolves schedule channel from the device | viewer |
| PUT | /devices/{addr}/schedule | Replace device schedule (auto-resolves channel) | operator |
| POST | /devices/{addr}/schedule/active-profile | Pick the active climate profile (auto-resolves channel) | operator |
| POST | /devices/{addr}/schedules/copy | Copy the whole week schedule to another device | operator |
security¶
| Method | Path | Summary | Access |
|---|---|---|---|
| GET | /security | The Security & Safety domain state | viewer |
| GET | /security/classes/{class} | One hazard or fault class with its full source list | viewer |
| GET | /security/faults | The standing fault ledger | viewer |
| POST | /security/faults/{id}/acknowledge | Mark a standing fault as seen (operator) | operator |
| GET | /security/sources | The classified data-point inventory | viewer |
| PUT | /security/sources/{ref} | Override the classification of one data point (operator) | operator |
sessions¶
| Method | Path | Summary | Access |
|---|---|---|---|
| POST | /sessions/edit | Acquire a 5-min edit lock on a resource key | operator |
| DELETE | /sessions/edit | Release an edit lock | operator |
| POST | /sessions/edit/heartbeat | Refresh an edit lock's TTL | operator |
| POST | /sessions/edit/take-over | Force-close another user's edit lock (operator) | operator |
setup¶
| Method | Path | Summary | Access |
|---|---|---|---|
| POST | /setup | Finalize first-run onboarding | public |
| POST | /setup/pairing | Start client pairing with an openccu-lite box | public |
| GET | /setup/pairing/{id} | A pairing's state | public |
| DELETE | /setup/pairing/{id} | Withdraw a pairing | public |
| POST | /setup/probe | Identify the system at an address (first-run wizard) | public |
| GET | /setup/status | First-run onboarding probe | public |
snapshot¶
| Method | Path | Summary | Access |
|---|---|---|---|
| GET | /snapshot | One-shot dump of structural daemon state | viewer |
system¶
Daemon-level system operations (add-on self-update)
| Method | Path | Summary | Access |
|---|---|---|---|
| POST | /backups/upload | Import an externally-supplied CCU backup | admin |
| GET | /system/addon-update | Self-update status of the daemon's own CCU add-on package. | viewer |
| POST | /system/addon-update/check | Trigger an immediate update check against the release feed. | operator |
| POST | /system/addon-update/install | Download, verify (SHA256 against the release checksums), stage | operator |
| PUT | /system/ccu/{central}/position | Set a CCU's astro reference position | admin |
| POST | /system/ccu/{central}/poweroff | Shut a CCU host down | admin |
| POST | /system/ccu/{central}/reboot | Reboot one CCU (admin-only) | admin |
| POST | /system/ccu/{central}/recovery-mode | Restart a CCU into its recovery system | admin |
| POST | /system/ccu/{central}/safe-mode | Restart a CCU into safe mode | admin |
| POST | /system/firmware/download | Download the newest firmware onto a CCU (admin-only) | admin |
| POST | /system/restart | Trigger a graceful daemon shutdown (admin-only) | admin |
| GET | /system/startup-capture | Read the persisted startup-capture toggle (admin-only) | admin |
| PUT | /system/startup-capture | Persist the startup-capture toggle (admin-only) | admin |
token-admin¶
API token management v2 (fingerprint-keyed)
| Method | Path | Summary | Access |
|---|---|---|---|
| GET | /auth/tokens/v2 | List API tokens with fingerprint + metadata (admin) | admin |
| POST | /auth/tokens/v2 | Issue a new bearer token (admin) — plaintext shown exactly once | admin |
| DELETE | /auth/tokens/v2/{fingerprint} | Revoke an API token by fingerprint (admin) | admin |
user-admin¶
Local user management (create, update, delete)
| Method | Path | Summary | Access |
|---|---|---|---|
| GET | /users | List all users (admin) | admin |
| POST | /users | Create a new user (admin) | admin |
| PATCH | /users/{subject} | Update user password or role (admin) | admin |
| DELETE | /users/{subject} | Delete a user (admin) | admin |
visibility¶
| Method | Path | Summary | Access |
|---|---|---|---|
| GET | /visibility/unignore | List currently-active un-ignore patterns per central | viewer |
| PUT | /visibility/unignore | Replace the un-ignore pattern list for a central (admin) | admin |
| GET | /visibility/unignore/candidates | List parameter names that are currently hidden but could be un-ignored | viewer |
webhook¶
| Method | Path | Summary | Access |
|---|---|---|---|
| POST | /webhook/program | Inbound webhook — run a program | operator |
| POST | /webhook/value | Inbound webhook — set a datapoint value | operator |