Quickstart

Everything is served from the edge. Requests are authenticated with a bearer token issued by your workspace administrator.

1. Authentication

Send the key in the Authorization header. Missing or unrecognised keys return 401 with a JSON error body.

Authorization: Bearer $LUMEN_KEY

2. Chat completions

Create a completion with POST /api/v1/chat. Set "stream": true to receive incremental deltas.

curl -s https://iot-devicemanagementplatform.pages.dev/api/v1/chat \
  -H "Authorization: Bearer $LUMEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"lumen-1-mini","stream":true,"messages":[{"role":"user","content":"Summarise this trace"}]}'

3. Event streams

GET /api/v2beta/events keeps a connection open and emits text/event-stream frames for agent traces and tool invocations. Resume with Last-Event-ID.

4. Telemetry ingest

Applications push spans to POST /telemetry/ingest. Payloads are newline-delimited JSON and are accepted asynchronously.

curl -s https://iot-devicemanagementplatform.pages.dev/telemetry/ingest \
  -H "Authorization: Bearer $LUMEN_KEY" \
  -H "Content-Type: application/x-ndjson" \
  --data-binary @spans.ndjson

5. Push gateway

GET /push/gateway is a long-poll channel for quota and latency alerts. Subscribe once and keep the connection open.

Reference

Method	Path	Auth	Purpose
GET	/api/v1/models	Public	Model catalogue
POST	/api/v1/chat	Bearer	Completions
GET	/api/v2beta/events	Bearer	Trace event stream
POST	/telemetry/ingest	Bearer	Span and metric ingest
GET	/push/gateway	Bearer	Alert subscription
GET	/health	Public	Liveness probe

Error format

{"error":{"message":"Missing API key.","type":"invalid_request_error","param":null,"code":"missing_api_key"}}