Freedome media server API 1.0.0

Base path /api/v1 on the installation (LAN, mDNS _freedome._tcp); /health and /ready are unversioned. Conventions: docs/conventions.md (errors RFC 9457, merge-patch, ETag / If-Match, Idempotency-Key, cursor pages). Versions before 1.0.0 (0.x previews, 1.0.0-rc.N) are not a stability promise; 1.0.0 freezes the API (M-CT2), then only additive changes within v1 (docs/versioning.md). Other transports: GraphQL /api/v1/graphql (graphql/mediaserver.graphql), WebSocket /api/v1/ws (asyncapi/ws.yaml), socket.io /v1 (asyncapi/socketio.yaml), OSC (osc/addresses.yaml), legacy profile (asyncapi/socketio-legacy.yaml, osc/legacy.yaml). Support: [email protected]. Commercial use → https://freedome.nativemind.us/commercial.

Servers: {scheme}://{host}:{port}/api/v1 · source openapi/mediaserver.yaml

discovery · venues · displays · output · calibration · auth · users · api-keys · system · shows · playback · uploads · assets · audio · engines · gateways · apps · clients · events · scenarios · devices · jobs

discovery

GET /info — getInfo

Server self-description · scope anon

Product, versions, transports, auth methods, venues summary and capabilities. Anonymous.

GET /health — getHealth

Liveness · scope anon

ok while the process serves requests; degraded lists failing dependencies (engines down do not make the server unhealthy).

GET /ready — getReady

Readiness · scope anon

200 when the server accepts API traffic (storage open, venue loaded); 503 problem otherwise.

GET /metrics — getMetrics

Prometheus metrics · scope anon

Prometheus text exposition 0.0.4; metric names are listed in docs/metrics.md. Anonymous by default on the LAN listener; installations may restrict it to system:read (config [metrics] require_auth).

GET /openapi.json — getOpenApi

This API description (OpenAPI 3.1 JSON) · scope anon

The bundled contract document the server implements, with servers set to this instance. Swagger UI at /api/v1/docs.

venues

GET /venues — listVenues

List stored venues · scope info:read

Stored venues (one is active per instance; default marks the alias target).

POST /venues — createVenue

Create a venue · scope venues:write

Body = .dome venue manifest without format / kind. meta.id becomes the venue id (409 if taken).

Request application/json: {"description":"POST /venues and PUT /venues/{venueId} body.","type":"object","allOf":[{"description":"Venue content shared by GET / PUT / POST: the .dome venue

{
  "meta": {
    "id": "7a2b3c4d-5e6f-4a71-8b8c-9d0e1f2a3b4c",
    "title": {
      "en": "Prism M"
    }
  },
  "dome": {
    "mode": "quantum",
    "shape": "pyramid",
    "radius": 0.212
  },
  "displays": [
    {
      "id": "u1",
      "type": "prism_unit",
      "resolution": [
        1920,
        1080
      ],
      "optics": {
        "faces": 4,
        "faceAngle": 45
      },
      "output": {
        "host": "node-1",
        "connector": "HDMI-1"
      }
    }
  ]
}

GET /venues/{venueId} — getVenue

Get a venue · scope info:read

Venue = .dome venue sections + id, revision, status, activeShowId; ETag = revision.

PUT /venues/{venueId} — putVenue

Replace (or create with a client-chosen id) a venue · scope venues:write

Replace needs If-Match; create needs If-None-Match: * and the path id equal to meta.id.

Request application/json: {"description":"POST /venues and PUT /venues/{venueId} body.","type":"object","allOf":[{"description":"Venue content shared by GET / PUT / POST: the .dome venue

{
  "meta": {
    "id": "6f1a2b3c-4d5e-4f60-8a7b-8c9d0e1f2a3b",
    "title": {
      "en": "Fisheye 6 m"
    }
  },
  "dome": {
    "mode": "classical",
    "shape": "hemisphere",
    "radius": 3
  },
  "displays": [
    {
      "id": "p1",
      "type": "projector",
      "resolution": [
        4096,
        2160
      ],
      "lens": {
        "kind": "fisheye",
        "fov": 180
      },
      "output": {
        "host": "node-1",
        "connector": "HDMI-1"
      }
    }
  ]
}

PATCH /venues/{venueId} — patchVenue

Merge-patch a venue · scope venues:write

RFC 7396 merge patch over the venue sections; the merged result is validated like a PUT body.

Request application/merge-patch+json: {"description":"PATCH body (application/merge-patch+json, RFC 7396) over the venue sections; the merged result must be a valid input.","type":"object","minPrope

{
  "meta": {
    "title": {
      "en": "Main dome"
    }
  }
}

DELETE /venues/{venueId} — deleteVenue

Delete a venue · scope venues:write

Refused with 409 while the venue is playing or is the default venue.

GET /venues/{venueId}/export — exportVenue

Export the venue as a .dome · scope content:read

kind: venue .dome (01b v0.2) incl. calibration sidecars; reference-writer layout (mimetype first, deterministic).

POST /venues/{venueId}/activate — activateVenue

Make this the active venue · scope venues:write

One active venue per instance (RC6): pushes displays + applied calibration to the engines; the alias default then resolves to it. Refused (409) while another venue is playing.

displays

GET /venues/{venueId}/displays — listDisplays

List the venue's displays with live state · scope info:read

Configuration (.dome entry) and live state of every display of the venue.

GET /venues/{venueId}/displays/{displayId} — getDisplay

Get a display (config + live state) · scope info:read

Configuration (.dome entry) and live state; ETag = venue revision.

PATCH /venues/{venueId}/displays/{displayId} — patchDisplay

Merge-patch the display configuration · scope venues:write

Patches config (the .dome display entry); bumps the venue revision. If-Match = venue ETag.

Request application/merge-patch+json: {"description":"PATCH body (application/merge-patch+json) over `config`; `id` cannot change.","type":"object","minProperties":1,"not":{"required":["id"]}}

{
  "lens": {
    "fov": 185
  }
}

POST /venues/{venueId}/displays/{displayId}/identify — identifyDisplay

Flash the display id overlay · scope displays:control

Shows the display id over the output for durationS seconds (default 5).

Request application/json: {"description":"POST …/identify body (optional): how long to show the id overlay.","type":"object","properties":{"durationS":{"type":"number","minimum":0.5,"max

{
  "durationS": 5
}

PUT /venues/{venueId}/displays/{displayId}/pattern — setTestPattern

Show a test pattern (or `off`) · scope displays:control

Engine freedome_pattern_*; result also published as event display.pattern on venues/{v}/displays/{d}.

Request application/json: {"description":"PUT /venues/{venueId}/displays/{displayId}/pattern body (engine freedome_pattern_*).","type":"object","required":["kind"],"properties":{"kind":{

{
  "kind": "grid",
  "params": {
    "spacingDeg": 10,
    "lineWidthPx": 2,
    "colour": "#ffffff"
  }
}

POST /venues/{venueId}/displays/{displayId}/power — setDisplayPower

Switch display power / shutter · scope displays:control

Only what state.capabilities lists (PJLink, device agent); otherwise 422 validation-failed.

Request application/json: {"description":"POST …/power body; only what the device supports (state.capabilities).","type":"object","minProperties":1,"properties":{"on":{"type":"boolean"},

{
  "on": true,
  "shutter": "open"
}

output

GET /venues/{venueId}/output — getOutput

Get the venue output state · scope playback:read

Current master brightness, volume, blackout, rotation, lighting and NDI output.

PATCH /venues/{venueId}/output — patchOutput

Change output (brightness, volume, blackout …) · scope playback:control

Last writer wins (playback class, 02e §3.5); published as output.changed on venues/{v}/output.

Request application/merge-patch+json: {"description":"PATCH body (application/merge-patch+json): any subset of the output fields.","type":"object","minProperties":1,"properties":{"brightness":{"desc

{
  "brightness": 0.25,
  "blackout": false
}

calibration

GET /venues/{venueId}/calibration — getCalibration

Get the venue calibration (per display warp / blend / colour / report) · scope info:read

The .dome calibration block of the venue; ETag = venue revision.

GET /venues/{venueId}/calibration/displays/{displayId}/{file} — getCalibrationFile

Download a calibration sidecar · scope info:read

Binary sidecar of one display; media type by file.

PUT /venues/{venueId}/calibration/displays/{displayId}/{file} — putCalibrationFile

Upload / import a calibration sidecar · scope calibration:run

Validated (FDMESH grammar + size, PNG 16-bit grey, .cube 33³ / 65³); updates the venue calibration (revision++). If-Match = venue ETag.

Request application/vnd.nativemind.freedome.fdmesh: {"type":"string","contentMediaType":"application/vnd.nativemind.freedome.fdmesh"}

Request image/png: {"type":"string","contentMediaType":"image/png"}

Request text/plain: {"type":"string"}

GET /venues/{venueId}/calibration/jobs — listCalibrationJobs

List the venue's calibration jobs · scope info:read

Newest first; status filters (e.g. running jobs for a "resume" dialog).

POST /venues/{venueId}/calibration/jobs — startCalibrationJob

Start a calibration job · scope calibration:run

Visual kinds need calibration:run; audio kinds (audio-room, audio-speaker-check) need audio:calibrate. 202 + Location → getCalibrationJob.

Request application/json: {"description":"POST /venues/{venueId}/calibration/jobs body.","type":"object","required":["kind"],"properties":{"kind":{"anyOf":[{"enum":["visual-camera","visu

{
  "kind": "visual-camera",
  "displays": [
    "p1"
  ],
  "options": {
    "grid": 17
  }
}

GET /venues/{venueId}/calibration/jobs/{jobId} — getCalibrationJob

Calibration job state (steps, awaited input, residual errors) · scope info:read

Steps, the input awaited from the operator / camera, residual errors and the proposed result.

POST /venues/{venueId}/calibration/jobs/{jobId}/captures — submitCalibrationCapture

Submit a camera frame for the awaited step · scope calibration:run

JSON with a tus uploadId or multipart/form-data with an image part (≤ 32 MB) for the awaited step; 409 when no capture is awaited.

Request application/json: {"description":"POST …/captures JSON body: a camera frame uploaded before (tus upload id); multipart/form-data with an `image` part is the alternative (≤ 32 MB)

{
  "uploadId": "0192f3a4-5b6c-7d8e-9f01-23456789abd2",
  "stepId": "capture-p1-grid"
}

Request multipart/form-data: {"type":"object","required":["image"],"properties":{"image":{"type":"string","contentMediaType":"image/jpeg","description":"JPEG / PNG frame, ≤ 32 MB"},"stepId"

POST /venues/{venueId}/calibration/jobs/{jobId}/apply — applyCalibrationJob

Apply the solved calibration to the venue · scope calibration:run

Writes result into the venue calibration (revision++); 409 unless the job succeeded.

POST /venues/{venueId}/calibration/jobs/{jobId}/cancel — cancelCalibrationJob

Cancel a calibration job · scope calibration:run

Stops the job and restores the pre-job patterns; the venue calibration is unchanged.

auth

POST /auth/session — createSession

Sign in with a local account · scope anon

{username, password} → access JWT (15 min) + rotating refresh token. Rate limited per IP and username.

Request application/json: {"description":"POST /auth/session (local account).","type":"object","required":["username","password"],"properties":{"username":{"type":"string","minLength":1,

{
  "username": "operator",
  "password": "correct-horse-battery",
  "client": {
    "app": "freedome_manager",
    "appVersion": "4.0.0"
  }
}

DELETE /auth/session — deleteSession

Sign out (revoke the current session and its refresh family) · scope any

Revokes the session of the presented access token; emits session.revoked on auth/sessions.

POST /auth/refresh — refreshSession

Rotate the refresh token · scope anon

Returns a new token pair; presenting an already rotated refresh token revokes every session of that family (401).

Request application/json: {"description":"POST /auth/refresh.","type":"object","required":["refreshToken"],"properties":{"refreshToken":{"type":"string","minLength":16}},"additionalPrope

{
  "refreshToken": "example-refresh-token-not-a-secret"
}

POST /auth/token-exchange — exchangeCloudToken

Exchange a cloud (L7) token for a local session · scope anon

Linked installations only — the L7 JWT is verified offline with the cached JWKS of freedome.nativemind.us and its org role is mapped to a local role. Unlinked → 401 unauthenticated "installation not linked".

Request application/json: {"description":"POST /auth/token-exchange: an L7 (freedome.nativemind.us) access JWT for a local session; linked installations only (JWKS of the cloud).","type"

{
  "subjectToken": "example.cloud-jwt.not-a-secret",
  "client": {
    "app": "freedome_manager"
  }
}

GET /auth/pairings — listPairings

List pending pairings (operator view) · scope users:manage

Pending and recently decided pairings, for the approval dialog in Manager / on the dome.

POST /auth/pairings — createPairing

Ask to pair an ecosystem app (guest token) · scope anon

Returns a 6-digit code to show to the operator (also as QR freedome://pair?host=…&code=…); the app polls getPairing until approved / denied / expired (5 min).

Request application/json: {"description":"POST /auth/pairings (anonymous; ecosystem app asks for a guest token).","type":"object","required":["app","deviceName"],"properties":{"app":{"ty

{
  "app": "net.nativemind.starveda",
  "deviceName": "Anna iPhone"
}

GET /auth/pairings/{pairingId} — getPairing

Poll a pairing · scope anon

Anonymous poll by the requesting app (the unguessable id is the capability). After approval the first poll returns tokens once.

POST /auth/pairings/{pairingId}/approve — approvePairing

Approve (or deny) a pairing · scope users:manage

Operator decision; approve:false denies. The granted role never exceeds the approver's.

Request application/json: {"description":"POST /auth/pairings/{pairingId}/approve body (operator side).","type":"object","properties":{"approve":{"type":"boolean","default":true,"descrip

{
  "approve": true,
  "role": "guest",
  "ttlSec": 2592000
}

GET /auth/me — getMe

Current principal and scopes · scope any

Who is calling (user, API key, pairing, cloud) and the effective scopes.

users

GET /users — listUsers

List local users · scope users:manage

Cursor page of local accounts; ?q= matches username / display name.

POST /users — createUser

Create a local user · scope users:manage

The new user's role cannot exceed the caller's.

Request application/json: {"description":"POST /users.","type":"object","required":["username","password","role"],"properties":{"username":{"type":"string","pattern":"^[a-z0-9][a-z0-9._-

{
  "username": "operator",
  "displayName": "Night operator",
  "password": "correct-horse-battery",
  "role": "operator"
}

GET /users/{userId} — getUser

Get a user · scope users:manage

One local account.

PATCH /users/{userId} — patchUser

Merge-patch a user · scope users:manage

Display name, password, role, disabled. A password change revokes the user's sessions.

Request application/merge-patch+json: {"description":"PATCH /users/{userId} (merge-patch). Changing the password revokes the user's sessions.","type":"object","minProperties":1,"properties":{"displa

{
  "disabled": true
}

DELETE /users/{userId} — deleteUser

Delete a user · scope users:manage

Revokes the user's sessions. The last superadmin cannot be deleted (409).

api-keys

GET /api-keys — listApiKeys

List API keys · scope keys:manage

Metadata only — the secret is never returned after creation. Revoked keys stay listed with revokedAt (audit).

POST /api-keys — createApiKey

Create an API key (token shown once) · scope keys:manage

The key's role cannot exceed the caller's; scopes may narrow the role.

Request application/json: {"description":"POST /api-keys. A key never gets more than the caller's own role.","type":"object","required":["name","role"],"properties":{"name":{"type":"stri

{
  "name": "Lobby kiosk",
  "role": "guest"
}

GET /api-keys/{keyId} — getApiKey

Get API key metadata · scope keys:manage

Metadata of one key. A revoked key → 404 (it is still listed by listApiKeys with revokedAt).

DELETE /api-keys/{keyId} — deleteApiKey

Revoke an API key · scope keys:manage

Immediate; cached verifications are dropped. Idempotent — revoking an already revoked key → 204; an unknown id → 404.

system

GET /system — getSystem

Host and service status · scope system:read

Host, OS, CPU / GPU, temperatures, disks, uptime, component versions.

GET /system/logs — getLogs

Server log (ring buffer) · scope system:read

Newest first; level = minimum level. Live tail = topic system/logs.

DELETE /system/logs — clearLogs

Clear the log ring buffer · scope system:admin

Files written by the OS journal are not touched.

GET /system/config — getConfig

Effective configuration (secrets redacted) · scope system:read

Secrets are always "***" and listed in redacted.

PUT /system/config — putConfig

Replace the configuration (and reload) · scope system:admin

Validated, written atomically, hot-reloaded where possible; "***" keeps the stored secret.

Request application/json: {"description":"PUT /system/config body (If-Match = config revision).","type":"object","required":["values"],"properties":{"values":{"type":"object","additional

{
  "values": {
    "http": {
      "listen": "0.0.0.0:8080",
      "base_path": ""
    },
    "osc": {
      "udp_in": 7000,
      "udp_out": 7001
    },
    "cloud": {
      "link_token": "***"
    },
    "legacy": {
      "enabled": false
    }
  }
}

POST /system/diagnostics — runDiagnostics

Run diagnostics (job) · scope system:read

Checks engines, displays, audio, network, storage, sync, gateways; report in the job result.

Request application/json: {"type":"object","properties":{"checks":{"type":"array","items":{"anyOf":[{"enum":["engines","displays","audio","network","storage","sync","gateways"]},{"type":

{
  "checks": [
    "engines",
    "displays",
    "storage"
  ]
}

POST /system/backup — createBackup

Create a backup (job → downloadable archive) · scope system:admin

The finished job's links.resource points to the archive download.

Request application/json: {"type":"object","properties":{"include":{"type":"array","items":{"anyOf":[{"enum":["config","database","venues","shows","keys","assets"]},{"type":"string"}]},"

{
  "include": [
    "config",
    "database",
    "venues",
    "shows"
  ],
  "note": "before update"
}

POST /system/restore — restoreBackup

Restore a backup (job; service restarts) · scope system:admin

The archive is uploaded first with tus (purpose=restore).

Request application/json: {"type":"object","required":["uploadId","confirm"],"properties":{"uploadId":{"description":"tus upload (purpose restore) holding the backup archive","type":"str

{
  "uploadId": "0192f3a4-5b6c-7d8e-9f01-23456789ad01",
  "confirm": true
}

GET /system/update — getUpdate

Update status · scope system:read

Installed and available versions per component.

POST /system/update — startUpdate

Start a package / firmware update (job) · scope system:admin

From the configured channel, a version, or an uploaded offline package.

Request application/json: {"type":"object","properties":{"channel":{"anyOf":[{"enum":["stable","beta"]},{"type":"string"}]},"version":{"description":"Semantic version 2.0.0.","type":"str

{
  "channel": "stable",
  "version": "1.0.1"
}

POST /system/reboot — rebootSystem

Reboot the host · scope system:admin

Requires {confirm:true}; disabled unless allowed in config (403 otherwise). Emits system.health before going down.

Request application/json: {"description":"POST /system/reboot and /system/shutdown body.","type":"object","required":["confirm"],"properties":{"confirm":{"const":true},"delaySec":{"type"

{
  "confirm": true,
  "delaySec": 5,
  "reason": "driver update"
}

POST /system/shutdown — shutdownSystem

Shut the host down · scope system:admin

Requires {confirm:true}; disabled unless allowed in config (403 otherwise).

Request application/json: {"description":"POST /system/reboot and /system/shutdown body.","type":"object","required":["confirm"],"properties":{"confirm":{"const":true},"delaySec":{"type"

{
  "confirm": true,
  "delaySec": 30
}

GET /nodes — listNodes

Cluster nodes and their clocks · scope info:read

This server and the engine hosts it drives, with PTP / NTP clock status (multi-node sync).

GET /nodes/{nodeId} — getNode

One cluster node · scope info:read

Node status and clock.

shows

GET /shows — listShows

List shows · scope content:read

Summaries (no asset / show bodies); ?q= matches title and tags, ?tag= filters.

POST /shows — createShow

Create a show · scope content:write

Body = .dome show manifest without format / kind; id = meta.id. 409 if it exists (use putShow to replace).

Request application/json: {"description":"POST /shows and PUT /shows/{showId} body. Assets are referenced by .dome asset entries; an entry whose `src` is `asset:<assetId>` points to an a

{
  "meta": {
    "id": "9c4d5e6f-7a8b-4c93-8d0e-1f2a3b4c5d6e",
    "title": {
      "en": "Intro show"
    }
  },
  "assets": [
    {
      "id": "intro",
      "src": "asset:0192f3a4-5b6c-7d8e-9f01-23456789ae01",
      "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "size": 734003200,
      "type": "video",
      "mapping": {
        "projection": "domemaster",
        "fov": 180
      },
      "duration": 600
    }
  ],
  "show": {
    "playlists": [
      {
        "id": "main",
        "items": [
          {
            "asset": "intro"
          }
        ]
      }
    ],
    "cues": [
      {
        "id": "dim",
        "at": {
          "trigger": "go"
        },
        "actions": [
          {
            "do": "setBrightness",
            "target": "main",
            "args": {
              "value": 0.7
            }
          }
        ]
      }
    ],
    "triggers": [
      {
        "id": "go",
        "source": "osc",
        "match": "/dome/go"
      }
    ],
    "startup": {
      "playlist": "main"
    }
  }
}

GET /shows/{showId} — getShow

Get a show · scope content:read

Full show with validation warnings against the active venue.

PUT /shows/{showId} — putShow

Replace (or create with a client-chosen id) · scope content:write

If-Match replaces; If-None-Match: * creates with this id (412 if taken).

Request application/json: {"description":"POST /shows and PUT /shows/{showId} body. Assets are referenced by .dome asset entries; an entry whose `src` is `asset:<assetId>` points to an a

{
  "meta": {
    "id": "9c4d5e6f-7a8b-4c93-8d0e-1f2a3b4c5d6e",
    "title": {
      "en": "Intro show"
    }
  },
  "assets": [
    {
      "id": "intro",
      "src": "asset:0192f3a4-5b6c-7d8e-9f01-23456789ae01",
      "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "size": 734003200,
      "type": "video",
      "mapping": {
        "projection": "domemaster",
        "fov": 180
      },
      "duration": 600
    }
  ],
  "show": {
    "playlists": [
      {
        "id": "main",
        "items": [
          {
            "asset": "intro"
          }
        ]
      }
    ],
    "cues": [
      {
        "id": "dim",
        "at": {
          "trigger": "go"
        },
        "actions": [
          {
            "do": "setBrightness",
            "target": "main",
            "args": {
              "value": 0.7
            }
          }
        ]
      }
    ],
    "triggers": [
      {
        "id": "go",
        "source": "osc",
        "match": "/dome/go"
      }
    ],
    "startup": {
      "playlist": "main"
    }
  }
}

PATCH /shows/{showId} — patchShow

Merge-patch a show · scope content:write

RFC 7396 over the show sections; the result must validate as a show.

Request application/merge-patch+json: {"description":"PATCH /shows/{showId} (application/merge-patch+json): any subset of the sections; arrays are replaced whole (RFC 7396).","type":"object","minPro

{
  "meta": {
    "title": {
      "en": "Intro show (v2)"
    }
  }
}

DELETE /shows/{showId} — deleteShow

Delete a show · scope content:write

Refused (409) while it is the active show of a playing venue. Assets are kept.

GET /shows/{showId}/export — exportShow

Export the show as a .dome · scope content:read

kind: show .dome; ?embedAssets=true stores the media inside (stored entries, ZIP64). Range supported.

GET /shows/{showId}/playlists/{itemId} — getPlaylist

Get a playlist of the show · scope content:read

The .dome show.playlists[] entry with this id; ETag = show revision.

PUT /shows/{showId}/playlists/{itemId} — putPlaylist

Create or replace a playlist of the show · scope content:write

Body id must equal the path id. If-Match = show ETag; bumps the show revision (event show.updated, sub-kind playlist.updated).

Request application/json: {"type":"object","required":["id","items"],"properties":{"id":{"description":"Document-scoped id (02e §3.2).","type":"string","pattern":"^[A-Za-z0-9._-]{1,64}$"

{
  "id": "main",
  "name": "Main",
  "loop": false,
  "items": [
    {
      "asset": "intro",
      "transition": {
        "kind": "fade",
        "duration": 2
      }
    }
  ]
}

DELETE /shows/{showId}/playlists/{itemId} — deletePlaylist

Delete a playlist of the show · scope content:write

409 when other show entries still reference it (e.g. a cue → trigger, startup → playlist).

GET /shows/{showId}/timelines/{itemId} — getTimeline

Get a timeline of the show · scope content:read

The .dome show.timelines[] entry with this id; ETag = show revision.

PUT /shows/{showId}/timelines/{itemId} — putTimeline

Create or replace a timeline of the show · scope content:write

Body id must equal the path id. If-Match = show ETag; bumps the show revision (event show.updated, sub-kind timeline.updated).

Request application/json: {"type":"object","required":["id","tracks"],"properties":{"id":{"description":"Document-scoped id (02e §3.2).","type":"string","pattern":"^[A-Za-z0-9._-]{1,64}$

{
  "id": "tl",
  "fps": 60,
  "duration": 600,
  "tracks": [
    {
      "id": "v",
      "kind": "video",
      "clips": [
        {
          "asset": "intro",
          "start": 0
        }
      ]
    }
  ],
  "markers": [
    {
      "id": "half",
      "time": 300,
      "name": "Half"
    }
  ]
}

DELETE /shows/{showId}/timelines/{itemId} — deleteTimeline

Delete a timeline of the show · scope content:write

409 when other show entries still reference it (e.g. a cue → trigger, startup → playlist).

GET /shows/{showId}/cues/{itemId} — getCue

Get a cue of the show · scope content:read

The .dome show.cues[] entry with this id; ETag = show revision.

PUT /shows/{showId}/cues/{itemId} — putCue

Create or replace a cue of the show · scope content:write

Body id must equal the path id. If-Match = show ETag; bumps the show revision (event show.updated, sub-kind cue.updated).

Request application/json: {"type":"object","required":["id","actions"],"properties":{"id":{"description":"Document-scoped id (02e §3.2).","type":"string","pattern":"^[A-Za-z0-9._-]{1,64}

{
  "id": "dim",
  "at": {
    "trigger": "go"
  },
  "actions": [
    {
      "do": "setBrightness",
      "target": "main",
      "args": {
        "value": 0.7,
        "fade": 3
      }
    }
  ]
}

DELETE /shows/{showId}/cues/{itemId} — deleteCue

Delete a cue of the show · scope content:write

409 when other show entries still reference it (e.g. a cue → trigger, startup → playlist).

GET /shows/{showId}/triggers/{itemId} — getTrigger

Get a trigger of the show · scope content:read

The .dome show.triggers[] entry with this id; ETag = show revision.

PUT /shows/{showId}/triggers/{itemId} — putTrigger

Create or replace a trigger of the show · scope content:write

Body id must equal the path id. If-Match = show ETag; bumps the show revision (event show.updated, sub-kind trigger.updated).

Request application/json: {"type":"object","required":["id","source"],"properties":{"id":{"description":"Document-scoped id (02e §3.2).","type":"string","pattern":"^[A-Za-z0-9._-]{1,64}$

{
  "id": "go",
  "source": "osc",
  "match": "/dome/go"
}

DELETE /shows/{showId}/triggers/{itemId} — deleteTrigger

Delete a trigger of the show · scope content:write

409 when other show entries still reference it (e.g. a cue → trigger, startup → playlist).

GET /shows/{showId}/matrix — getMatrix

Get the show matrix · scope content:read

Screenberry-style matrix (.dome show.matrix); 404 when the show has none.

PUT /shows/{showId}/matrix — putMatrix

Replace the show matrix · scope content:write

If-Match = show ETag; emits matrix.updated.

Request application/json: {"description":"Screenberry-style matrix (compatibility); cells reference row / column ids.","type":"object","required":["rows","columns","cells"],"properties":

{
  "rows": [
    {
      "id": "r1"
    }
  ],
  "columns": [
    {
      "id": "c1"
    },
    {
      "id": "c2"
    }
  ],
  "cells": [
    {
      "row": "r1",
      "column": "c1",
      "asset": "intro"
    },
    {
      "row": "r1",
      "column": "c2",
      "asset": "poster"
    }
  ]
}

POST /imports — startImport

Import a file (job) · scope content:write

Source = a tus upload (purpose=import), an allow-listed URL, or a stored asset. Content sniffing (02e §9.2) wins over format when they disagree (unsupported-format if neither matches).

Request application/json: {"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://freedome.nativemind.us/schemas/api/1.0/import.schema.json","$comment":"NativeMindNONC —

{
  "uploadId": "0192f3a4-5b6c-7d8e-9f01-23456789af01",
  "format": "dome",
  "target": {
    "kind": "auto",
    "activate": true
  }
}

playback

GET /venues/{venueId}/players — listPlayers

List the venue's media players · scope playback:read

Player main always exists; others come from the active show's mediaPlayers.

GET /venues/{venueId}/players/{playerId} — getPlayer

Player state · scope playback:read

Live state; also pushed as player.state / player.position on venues/{v}/players/{p}.

PATCH /venues/{venueId}/players/{playerId} — patchPlayer

Set rate / loop / volume / opacity / brightness / rotation · scope playback:control

Merge-patch of the player's live parameters (UC-P6); last writer wins.

Request application/merge-patch+json: {"description":"PATCH /venues/{venueId}/players/{playerId} (merge-patch; playback is last-writer-wins, no If-Match).","type":"object","minProperties":1,"propert

{
  "volume": 0.6,
  "rate": 1
}

POST /venues/{venueId}/players/{playerId}/play — play

Play (optionally a given source, optionally scheduled) · scope playback:control

Without a body: resume the loaded source or start show.startup. at schedules the start on the server clock (multi-node sync). Playing on playing = no-op success.

Request application/json: {"description":"POST …/play: what to play (absent = resume the loaded source / startup) and when. `at` = scheduled start on the server clock (multi-node sync, 0

{
  "playlistId": "main",
  "itemIndex": 0,
  "position": 0,
  "at": "2026-10-19T12:00:05.000Z"
}

POST /venues/{venueId}/players/{playerId}/pause — pause

Pause · scope playback:control

Pause at the current position (no-op when already paused).

POST /venues/{venueId}/players/{playerId}/resume — resume

Resume · scope playback:control

Resume a paused player.

POST /venues/{venueId}/players/{playerId}/stop — stop

Stop · scope playback:control

Stop and rewind; the player shows the configured idle content.

POST /venues/{venueId}/players/{playerId}/next — next

Next item · scope playback:control

Next playlist item / timeline marker / matrix column.

POST /venues/{venueId}/players/{playerId}/previous — previous

Previous item · scope playback:control

Previous playlist item / timeline marker / matrix column.

POST /venues/{venueId}/players/{playerId}/seek — seek

Seek · scope playback:control

Exactly one of position (s), marker (timeline marker id) or normalized (0..1); optional at for synchronised seeks.

Request application/json: {"description":"POST …/seek: exactly one of position (s), marker (timeline marker id) or normalized (0..1).","type":"object","properties":{"position":{"descript

{
  "position": 120
}

POST /venues/{venueId}/cues/{cueId}/fire — fireCue

Fire a cue (GO) · scope playback:control

Runs the cue actions of the active show (or showId); result per action. Also cue.fired / cue.failed on venues/{v}/cues.

Request application/json: {"type":"object","properties":{"showId":{"description":"default = active show","type":"string","pattern":"^[A-Za-z0-9._-]{1,64}$","examples":["p1","intro.mp4","

{
  "showId": "9c4d5e6f-7a8b-4c93-8d0e-1f2a3b4c5d6e"
}

GET /venues/{venueId}/active-show — getActiveShow

The venue's active show · scope playback:read

Show loaded onto the venue (showId null = none) with mapping warnings.

PUT /venues/{venueId}/active-show — setActiveShow

Load a show onto the venue · scope playback:control

Maps the show onto this venue's geometry (02 §9); autoplay starts show.startup on main; showId: null unloads. Playback-class operation: no If-Match.

Request application/json: {"description":"PUT /venues/{venueId}/active-show: load a show onto the venue (mapped onto its geometry); showId null unloads.","type":"object","required":["sho

{
  "showId": "9c4d5e6f-7a8b-4c93-8d0e-1f2a3b4c5d6e",
  "autoplay": true
}

GET /venues/{venueId}/parameters — listParameters

List node / layer parameters · scope playback:read

Parameter registry (UC-N2): path, type, value, range; ?prefix= narrows (e.g. players.main). Live changes: topic venues/{v}/parameters.

GET /venues/{venueId}/parameters/{path} — getParameter

Get a parameter · scope playback:read

One parameter with type and range.

PUT /venues/{venueId}/parameters/{path} — setParameter

Set a parameter · scope playback:control

Screenberry-compatible parameter surface (UC-N1); optional fadeSec. Read-only parameters → 422.

Request application/json: {"description":"PUT /venues/{venueId}/parameters/{path} body.","type":"object","required":["value"],"properties":{"value":{"anyOf":[{"type":"number"},{"type":"b

{
  "value": 0.8,
  "fadeSec": 2
}

uploads

POST /uploads — createUpload

Create an upload (tus Creation, optionally with the first chunk) · scope content:write

Upload-Length + Upload-Metadata (filename, contentType, sha256, purpose, assetId). With a body (Content-Type: application/offset+octet-stream) the first chunk is stored (Creation-With-Upload) and Upload-Offset returned. Upload-Defer-Length is not supported.

Request application/offset+octet-stream: {"type":"string","contentMediaType":"application/octet-stream"}

OPTIONS /uploads — getUploadCapabilities

tus discovery · scope anon

Returns the tus capability headers (no body). Anonymous so that tus clients can probe before auth.

GET /uploads/{uploadId} — getUpload

Upload status as JSON · scope content:write

For clients without a tus library (progress UIs); also pushed as upload.progress on uploads/{u}.

PATCH /uploads/{uploadId} — appendUpload

Append a chunk (tus PATCH) · scope content:write

Upload-Offset must equal the server offset (409 otherwise); Upload-Checksum: sha256 … per chunk (460 on mismatch, chunk discarded). Concurrency is the offset, not If-Match.

Request application/offset+octet-stream: {"type":"string","contentMediaType":"application/octet-stream"}

DELETE /uploads/{uploadId} — deleteUpload

Terminate an upload (tus Termination) · scope content:write

Frees the stored bytes; later requests → 404.

HEAD /uploads/{uploadId} — getUploadOffset

Current offset (tus HEAD) · scope content:write

Upload-Offset, Upload-Length, Upload-Metadata, Cache-Control: no-store. Expired / unknown → 404 (or 410).

assets

GET /assets — listAssets

List / search assets · scope content:read

Filters type, tag, status, full text q (name, tags).

POST /assets — createAsset

Create an asset from an upload, a URL, or a small multipart file · scope content:write

JSON: {uploadId | url, id?, name?, type?, mapping?, tags}. multipart/form-data with part file for ≤ 100 MB (larger → 413, use tus). Probing (ffprobe, thumbnails) runs in the background: status processing → ready | failed, events on assets/{a}.

Request application/json: {"description":"POST /assets JSON body: register a finished tus upload or an external URL (streams, CDN).","type":"object","properties":{"uploadId":{"descriptio

{
  "uploadId": "0192f3a4-5b6c-7d8e-9f01-23456789ae10",
  "name": "Intro 4K",
  "type": "video",
  "mapping": {
    "projection": "domemaster",
    "fov": 180
  },
  "tags": [
    "intro"
  ]
}

Request multipart/form-data: {"description":"POST /assets multipart/form-data body (simple upload ≤ 100 MB): part `file` + optional JSON fields.","type":"object","required":["file"],"proper

GET /assets/{assetId} — getAsset

Get an asset · scope content:read

Metadata, probe data, thumbnails, shows using it.

PATCH /assets/{assetId} — patchAsset

Merge-patch asset metadata · scope content:write

Name, type, mapping, tags (content is immutable — upload a new asset or re-upload with assetId).

Request application/merge-patch+json: {"type":"object","minProperties":1,"properties":{"name":{"type":"string","minLength":1,"maxLength":512},"type":{"anyOf":[{"enum":["video","image","audio","zelim

{
  "tags": [
    "intro",
    "4k"
  ]
}

DELETE /assets/{assetId} — deleteAsset

Delete an asset · scope content:write

Refused (409) while referenced by a show unless ?force=true (cues referencing it then report failed; a playing show continues).

GET /assets/{assetId}/content — downloadAsset

Download the asset content · scope content:read

Range requests (206), ETag = sha256, If-None-Match → 304. Registered URL assets → 303 to the URL.

GET /assets/{assetId}/thumbnail — getAssetThumbnail

Asset thumbnail · scope content:read

PNG / JPEG / WebP; ?size= = longest edge in px (nearest generated size).

GET /storage — getStorageStats

Storage usage · scope content:read

Disk / quota usage of the content store (replaces /api/v1/content/stats).

GET /venues/{venueId}/texture-sources — listTextureSources

List live texture sources · scope playback:read

Spout / Syphon / DMA-BUF / NDI senders the engines of this venue can see. To show one, register a stream asset with the matching src and play it.

audio

GET /venues/{venueId}/audio — getAudio

Venue audio state · scope playback:read

Mode (digital / hybrid / combined), master gain, mute, engine status.

PATCH /venues/{venueId}/audio — patchAudio

Set mode / master gain / mute · scope audio:control

Mode change re-routes the active show's audio between the engines (02c A8).

Request application/merge-patch+json: {"type":"object","minProperties":1,"properties":{"mode":{"description":"A8: digital = anAntaDigital only; hybrid = anAntaSound (mechanical devices); combined =

{
  "masterGainDb": -9,
  "mute": false
}

GET /venues/{venueId}/audio/layout — getSpeakerLayout

Speaker layout (.dome audio block) · scope info:read

Ambisonics, decoder, speakers, room correction, devices; ETag = venue revision.

PUT /venues/{venueId}/audio/layout — putSpeakerLayout

Replace the speaker layout · scope venues:write

Written into the venue (revision++) and applied to AnantaDigital (decoder rebuilt).

Request application/json: {"description":"AnantaSound layout (01b §4.4).","type":"object","properties":{"ambisonics":{"type":"object","properties":{"order":{"type":"integer","minimum":0,

{
  "ambisonics": {
    "order": 3,
    "normalisation": "SN3D",
    "channelOrder": "ACN"
  },
  "decoder": {
    "kind": "allrad",
    "dualBand": true
  },
  "speakers": [
    {
      "id": "s1",
      "azimuth": 0,
      "elevation": 0,
      "distance": 4
    }
  ],
  "devices": [
    {
      "id": "qrd1",
      "kind": "qrd",
      "address": "osc://10.0.0.20:9000"
    }
  ]
}

GET /venues/{venueId}/audio/zones — listAudioZones

List audio zones · scope playback:read

AnantaDigital zones of the venue.

GET /venues/{venueId}/audio/zones/{zoneId} — getAudioZone

Get a zone · scope playback:read

One zone.

PUT /venues/{venueId}/audio/zones/{zoneId} — putAudioZone

Create or replace a zone · scope audio:control

If-None-Match: * creates, If-Match replaces.

Request application/json: {"type":"object","allOf":[{"type":"object","properties":{"name":{"type":"string","maxLength":128},"speakers":{"type":"array","items":{"description":"Document-sc

{
  "name": "Front",
  "speakers": [
    "s1",
    "s2"
  ],
  "gainDb": -3,
  "delayMs": 2.5
}

PATCH /venues/{venueId}/audio/zones/{zoneId} — patchAudioZone

Live zone change (gain, delay, EQ, mute) · scope audio:control

Last writer wins (OSC /freedome/v1/venue/{v}/audio/zone/{z}/gain).

Request application/merge-patch+json: {"type":"object","allOf":[{"type":"object","properties":{"name":{"type":"string","maxLength":128},"speakers":{"type":"array","items":{"description":"Document-sc

{
  "gainDb": -6
}

DELETE /venues/{venueId}/audio/zones/{zoneId} — deleteAudioZone

Delete a zone · scope audio:control

Speakers fall back to the default zone.

GET /venues/{venueId}/audio/devices — listAudioDevices

List audio devices with live state · scope playback:read

?kind=speaker|microphone|qrd|patefon|karmic_cluster|resonator (replaces get_microphones).

GET /venues/{venueId}/audio/devices/{deviceId} — getAudioDevice

Get an audio device · scope playback:read

Configuration + live state.

PATCH /venues/{venueId}/audio/devices/{deviceId} — patchAudioDevice

Live device change (gain, mute, name, config) · scope audio:control

Gain / mute are live (last writer wins); config changes are written into the venue.

Request application/merge-patch+json: {"type":"object","minProperties":1,"properties":{"name":{"type":"string"},"gainDb":{"description":"Gain in dB (C5: optional companion of linear `volume`).","typ

{
  "gainDb": -3
}

POST /venues/{venueId}/audio/devices/{deviceId}/test — testAudioDevice

Test a device (ping / tone / self-test / strike) · scope audio:control

Bounded by the device limits (actuator self-test is refused while a session runs, 409).

Request application/json: {"type":"object","properties":{"kind":{"anyOf":[{"enum":["ping","tone","selftest","strike"]},{"type":"string"}],"default":"ping"},"frequencyHz":{"type":"number"

{
  "kind": "tone",
  "frequencyHz": 432,
  "gainDb": -30,
  "durationS": 2
}

GET /venues/{venueId}/audio/presets — listAudioPresets

List installed presets · scope content:read

L6 programme / pattern / session presets installed on this server.

GET /venues/{venueId}/audio/presets/{presetId} — getAudioPreset

Get a preset document · scope content:read

The ananta/1.0 document.

PUT /venues/{venueId}/audio/presets/{presetId} — putAudioPreset

Install or replace a preset · scope content:write

Validated against ananta/1.0 (02c); If-None-Match: * creates.

Request application/json: {"description":"PUT /venues/{venueId}/audio/presets/{presetId} body.","type":"object","required":["kind","document"],"properties":{"kind":{"enum":["programme","

{
  "kind": "session",
  "document": {
    "format": "ananta-session",
    "formatVersion": "1.0.0",
    "id": "calm-7",
    "title": {
      "en": "Calm 7"
    },
    "items": [
      {
        "programme": {
          "id": "tone-432"
        }
      }
    ]
  }
}

DELETE /venues/{venueId}/audio/presets/{presetId} — deleteAudioPreset

Remove a preset · scope content:write

Refused (409) while a session runs it.

GET /venues/{venueId}/audio/sessions — listAudioSessions

List audio sessions (running and recent) · scope playback:read

Running first, then finished ones from the last 24 h.

POST /venues/{venueId}/audio/sessions — startAudioSession

Run a preset · scope audio:control

Runs a programme / session preset on the engine(s) the audio mode selects; optional scheduled at.

Request application/json: {"description":"POST /venues/{venueId}/audio/sessions: run an installed preset (programme or session).","type":"object","required":["presetId"],"properties":{"p

{
  "presetId": "calm-7",
  "gainDb": -6,
  "targets": {
    "zones": [
      "front"
    ]
  }
}