Skip to main content

REST API

This page is an OpenAPI-style overview for integrators automating provisioning. A machine-readable OpenAPI document will ship alongside the GitHub release; behaviour matches the live hub at openiot.contexus.io.

Base URL

Production: https://openiot.contexus.io/api/v1
Self-hosted:  http://localhost:9001/api/v1

Authentication

Admin and integrator automation use session cookies obtained from POST /api/admin/login or service accounts (partner feature). Include the session cookie on subsequent requests. For server-to-server jobs, use API tokens scoped to a single tenant — see multi-tenancy.

POST /api/admin/login HTTP/1.1
Content-Type: application/json

{ "username": "[email protected]", "password": "***" }

# Response sets HttpOnly session cookie; reuse on:
GET /api/v1/sites HTTP/1.1
Cookie: connect.sid=...

Error envelope

Errors return JSON with a stable code and human-readable message.

{
  "error": {
    "code": "DEVICE_NOT_FOUND",
    "message": "No device with id 'sensor-42' in site 'site-a'",
    "requestId": "6f2c9b1e-7c4a-4c20-9e0a-1b2c3d4e5f60"
  }
}
HTTP statusMeaning
400Validation failed — check Zod field errors in response body
401Missing or expired session
403Tenant scope does not allow the resource
404Unknown site, device, or point
429Rate limit — backoff using Retry-After
500Unexpected failure — include requestId in support tickets

Example: list devices

curl -sS -b cookies.txt \
  'http://localhost:9001/api/v1/sites/site-a/devices?limit=50' \
  | jq '.devices[].id'

Example: ingest telemetry (MQTT preferred)

Prefer protocol-native ingestion for throughput. The REST telemetry endpoint exists for backfill scripts:

POST /api/v1/sites/site-a/devices/sensor-01/telemetry
Content-Type: application/json

{
  "metrics": {
    "temperature_c": 21.8,
    "rh_pct": 47.2
  },
  "timestamp": "2026-11-15T02:45:00Z"
}

Versioning

Breaking changes bump /api/v2. Deprecated routes return Sunset headers for 90 days. Track releases in troubleshooting changelog.

Related

Next steps

Explore a running stack, review the open source repositories, estimate ROI for a deployment, or talk with the CONTEXUS team about integration and licensing.

Module licensing details are summarised on /licensing. Browse reference dashboards in the gallery.