API and webhooks

This document describes the contract an integrator can rely on: what kind of resource each endpoint represents, how the API reports an error, how a repeated request is made safe, and how events are delivered. It does not reproduce paths, field names or payloads, because those are generated from a single source and owned elsewhere. Publishing a hand-written copy here is how a field list and an implementation drift apart.

The authoritative field list, the exact paths and the request and response schemas live in contracts/openapi.yaml, which a second team owns and which is generated from the same schema definitions the service uses. If this page and the contract disagree, the contract is correct.

The shape of the contract

Resources, not endpoints

The API is organised around a small set of resources — the gateway itself, the node registry, schedules and rules, and the event stream. Each resource follows the same conventions: a collection listing, a single-member read, and a create or update that returns a versioned representation. This uniform shape means a client can be written once and pointed at any of them.

The error model

Errors are reported as a problem document rather than as a bare status code: every failure carries a machine-readable type, a human-readable title and detail, and the request identifier that produced it. A client should branch on the problem type, never on the HTTP status alone, so that a new failure classified later does not silently change a client's behaviour.

Idempotency

Any request that changes state accepts an idempotency key. Repeating a request with the same key and the same body returns the original result rather than applying the change twice. This is what makes a retry safe across a flaky uplink, and the gateway enforces it — a client must not assume a duplicate submit is harmless.

Versioning

The base path is versioned (/api/v1) and each representation carries the revision of the data it came from. A client must compare that revision against the document revision it was written for and refuse to act on a mismatch until it has been checked, which is the same rule the documentation pages enforce with the ?firmware= parameter.

Authentication and transport

Local access is intended to be reachable only from inside the site's own management path; the site's uplink is outbound and does not expose the local API to the internet. Credentials are provisioned per site and are not shipped in documentation. HTTP is acceptable only on an isolated local segment; anything crossing a shared network must be protected in transport.

Events and webhooks

Events describe a change, not a snapshot: an endpoint changed state, a rule fired, an alarm was raised, a registry entry was added. A webhook subscriber declares which event categories it wants and where to send them. Delivery is outbound from the gateway, queued when the uplink is unavailable, and retried; a subscriber must therefore be idempotent and must not assume ordering across retries.

The complete event envelope — the field that identifies the category, the field that carries the event identity used for de-duplication, and the payload for each category — is defined once in contracts/openapi.yaml. This page intentionally does not list a payload, because an invented field here would be a contract violation, not documentation.

Failure modes

• Retry creates a duplicate: the client sent a new idempotency key on retry; reuse the original key.
• Client branches on HTTP status: a reclassified problem breaks the client; branch on the problem type.
• Webhook consumer assumes ordering: retries can deliver out of order; de-duplicate on the event identity and treat events as independent.
• Revision ignored: a client applies a response written for a newer revision; check the revision before acting.

Limitations

• This page publishes no path, field name, payload or status code that is not in the contract. Where a value would otherwise sit here, it is stated as a placeholder rather than invented.
• The local API exists on the gateway and edge controller only; a wall switch or sensor is reached through the gateway registry, not directly.

What this document does not cover: the field-bus protocols a building system may prefer over the API are in MQTT, Modbus and BACnet, and the access rules that keep the local API local are in Hardening and access.