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/v1Authentication
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 status | Meaning |
|---|---|
| 400 | Validation failed — check Zod field errors in response body |
| 401 | Missing or expired session |
| 403 | Tenant scope does not allow the resource |
| 404 | Unknown site, device, or point |
| 429 | Rate limit — backoff using Retry-After |
| 500 | Unexpected 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
- Quickstart — compose on ports 9001 / 5433
- Licensing — redistribution of API clients
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.