Protocol Basics

Lumio's public API uses one versioned base path:

https://api.lumio.vision/v1

There is no /developer/v1 base path. Developer-extension routes are normal /v1 routes under /v1/developer/....

Protocol Endpoints

Surface	Endpoint
REST	https://api.lumio.vision/v1/...
GraphQL	POST https://api.lumio.vision/v1/gql
GraphQL SDL	GET https://api.lumio.vision/v1/schema
GraphiQL	GET https://api.lumio.vision/v1/graphiql
WebSocket	wss://api.lumio.vision/v1/ws
OpenAPI JSON	GET https://api.lumio.vision/v1/openapi.json

Test broadcasts through emitEvent, POST /v1/events/test, or lumio_event_test carry server-set raw.isTest: true and raw.showOnStream (Boolean). The caller passes GraphQL showOnStream, REST/MCP show_on_stream, or the dashboard's Show on stream checkbox; the default is false. Tests are never stored. POST /v1/events/emit strips isTest, is_test and showOnStream from raw before storing a manual event. Overlay and widget browser sources receive a test only when showOnStream is true; dashboard widget previews receive every test. For extension payloads and labeling, see useLumioEvent.

Authentication

API keys are accepted only with the bearer header:

Authorization: Bearer lm_usr_your_key

The bearer scheme is case-sensitive and uses exactly one space. Lumio does not support X-API-Key, and API keys are not accepted through ?token=.

Errors And Rate Limits

REST errors use this shape:

{
  "error": "VALIDATION_ERROR",
  "message": "Validation error: Invalid permission: events:typo",
  "details": null
}

API keys use a flat 1200 requests per minute bucket. Rate-limit responses use 429 RATE_LIMIT_EXCEEDED with Retry-After; expensive paths can return 503 RATE_LIMIT_UNAVAILABLE when rate limiting is unavailable.

For the full public API reference, see Lumio API Overview, REST, GraphQL, and WebSocket.