Skip to content

HTTP REST API Specification

Endpoints

Health

  • Endpoint: GET /api/health
  • Auth: none
  • Response: 200 OK with { "status": "ok" }

Config

  • Endpoint: GET /api/config
  • Auth: Authorization: Bearer <api-key>
  • Description: Returns the server configuration JSON (useful for debugging).
  • Response: 200 OK

Reload Registry

  • Endpoint: POST /api/reload-registry
  • Alias: POST /api/register-device
  • Auth: Authorization: Bearer <api-key>
  • Effect: Reloads device registry from backend and refreshes CoAP resources.
  • Response: 200 OK with { "status": "reloaded" }

Notify Desired Settings (dev)

  • Endpoint: POST /api/notify-settings
  • Alias: POST /api/update-settings
  • Auth: Authorization: Bearer <api-key>
  • Description: Dev-only path that stores an in-memory desired override and notifies the device via CoAP Observe (bypasses DB for now).
  • Body: json { "device_id": "string", "settings": { /* Device Settings */ } } See Device Settings for the settings shape.
  • Response: 200 OK with { "status": "updated" }

Security

  • All endpoints except /api/health require API key via Authorization: Bearer <api-key>
  • In production, run behind HTTPS/TLS (the server itself may be plain HTTP behind a reverse proxy)