External Integrations

Device Runtime API

Authenticated endpoints used by the TV player after successful binding.

Runtime Endpoint Reference

Method	Path	Summary	Auth
GET	/devices/:id/playlist	Returns active playlist (Turso, on-demand, or R2 fallback) for the authenticated device context.	Device API key (dak_) in Authorization header
GET	/devices/:id/config	Returns device config or a default config payload with HTTP 200 when no custom config exists.	Device API key (dak_) in Authorization header
POST	/devices/:id/events	Accepts 1-100 telemetry events and returns accepted count.	Device API key (dak_) in Authorization header

Common Runtime Header

Authorization: Bearer <dak_device_api_key>

Playlist Fetch Example

GET /devices/<screen_id>/playlist
Authorization: Bearer <dak_device_api_key>

HTTP/1.1 200 OK
X-Playlist-Version: 42
X-Source: on-demand

{
  "id": "playlist-uuid",
  "tenantId": "tenant-uuid",
  "screenId": "screen-uuid",
  "status": "active",
  "version": 42,
  "validUntil": 1760000000,
  "items": [
    {
      "creativeId": "creative-uuid",
      "creativeUrl": "https://.../media/creatives/...",
      "creativeType": "video",
      "duration": 15
    }
  ]
}

Config Fetch Behavior

GET /devices/:id/config returns 200 for both custom and default config responses. If no persisted config exists, a default payload is returned with X-Config-Source: default.

Telemetry Batch Example

POST /devices/<screen_id>/events
Authorization: Bearer <dak_device_api_key>
Content-Type: application/json

[
  {
    "type": "impression",
    "playlistId": "11111111-1111-1111-1111-111111111111",
    "timestamp": 1760000000,
    "campaignId": "22222222-2222-2222-2222-222222222222",
    "creativeId": "33333333-3333-3333-3333-333333333333"
  }
]

HTTP/1.1 202 Accepted
{ "received": 1 }

Event arrays must contain between 1 and 100 events.

Status and Error Mapping

GET /devices/:id/playlist

200 - Playlist returned (X-Playlist-Version and optional X-Source headers).
401 - Missing, invalid, revoked, or orphaned device API key.
404 - No playlist found for the screen.
500 - Playlist fetch failed.

GET /devices/:id/config

200 - Configuration returned (custom or default).
401 - Device authentication failed.
500 - Config fetch failed.

POST /devices/:id/events

202 - Event batch accepted.
400 - Event payload validation failed.
401 - Device authentication failed.