Documentation

HTTP/2 API reference

Three endpoints cover everything the studio and the companion app need: liveness, log synchronisation and build state. All of them speak JSON over HTTP/2 with a bearer token.

Authentication

Every call carries a hardware-bound token issued by the System Administrator. Tokens are re-issued every 2–3 hours without interrupting an active session.

Request header

Authorization: Bearer <token>

Requests without a valid token are rejected with HTTP 401 Unauthorized and a JSON error payload.

GET /api/v2/telemetry/heartbeat

Liveness of the telemetry gateway: current node, uptime, queue depth and the number of render nodes attached to the cluster.

200 OK

{
  "ok": true,
  "node": "eu-ams-01",
  "uptime_s": 4821934,
  "queue_depth": 12,
  "render_nodes": 1024,
  "ts": "2026-10-18T18:42:07Z"
}

POST /api/v2/companion/sync

Uploads debug log chunks captured while the device was offline. Chunks are idempotent: resending the same chunk index and hash is accepted and ignored.

Request body

{
  "device_id": "ios-9f2c1a",
  "platform": "ios",
  "since": "2026-10-18T17:00:00Z",
  "logs": [
    { "chunk": 41, "bytes": 65536, "sha256": "b1c0…9f2e" }
  ]
}

202 Accepted

{
  "accepted": 1,
  "next_since": "2026-10-18T18:42:11Z",
  "token_expires_in": 7200
}

GET /api/v2/builds/status

State of every build currently published to the asset CDN. Archive sizes and checksums here match the repository listing exactly.

200 OK

{
  "builds": [
    {
      "id": "aethelgard-master-0.9.4",
      "state": "ready",
      "size_gb": 54.2,
      "built_at": "2026-10-16",
      "sha256": "efdd3e6d11639a508eff4b4df81706c00175ed932273de91c1cbc5663bda40bb"
    }
  ]
}

Limits and transport

Protocol: HTTP/2 over TLS 1.3, HTTP/1.1 fallback disabled
Rate limit: 120 requests per minute per token
Max body: 8 MB per sync call
Token lifetime: 2–3 hours, renewed in place
Availability: 99.98% rolling 30 days
Pipeline: Dedicated HTTP/2 High-Bitrate Pipeline (HEVC 4:4:4 10-bit / AVC-Intra, up to 85 Mbps per developer stream, periodic session token refresh every 2–3 hours)