HTTP Transport

HTTP is the default transport for scripts, web apps, Companion, and Node-RED. The stable playback commands match OSC; extension and maintenance commands are HTTP-only and are not part of the OSC profile.

For command parameters and examples, use the Command Reference—not this page.

When to choose HTTP

You want confirmation that a command passed validation and entered the queue
You are writing curl / Python / Node integrations
You need optional status feedback on the same host

Prefer OSC for QLab/TouchDesigner.

Connection


Default port	`18290` (`network.base_port`)
Stable command route	`POST /api/command`
Extension command route	`POST /api/extensions/command`
Maintenance command route	`POST /api/maintenance/command`
Content-Type	`application/json`

/api/playback/play is a deprecated, unsupported per-command path.

Wire format

POST /api/command

{
  "cmd": "load",
  "params": { "source": "opening.mp4" }
}

Field	Required	Notes
`cmd`	Yes	Registry command name
`params`	No	Object; omit or `{}`

Unknown fields (including request_id and expect) return HTTP 400. The Idempotency-Key header is not supported and also returns HTTP 400.

Minimal example

curl -X POST http://<player-ip>:18290/api/command \
  -H "Content-Type: application/json" \
  -d '{"cmd":"play"}'

curl -X POST http://<player-ip>:18290/api/command \
  -H "Content-Type: application/json" \
  -d '{"cmd":"play_media","params":{"source":"opening.mp4"}}'

Successful queue admission → HTTP 200 with { "ok": true }. This only means the command passed synchronous validation and entered the queue, including commands whose internal execution classification is sync. It does not confirm that loading or playback has completed. If your integration needs that confirmation, observe state, source, and error through GET /api/status.

load: a basic client can optionally poll GET /api/status.
Screenshots: GET /api/screenshot/low.png or GET /api/screenshot/high.png (not a command).

Errors → { "ok": false, "error": "<string>" }. HTTP status expresses the category (400/403/404/415/429/503).

Extension commands use /api/extensions/command; maintenance commands use /api/maintenance/command and require a Maintenance process plus an allowed source. POST /api/command only accepts the ten stable playback commands.

Observation routes (not command aliases)

These stay as real HTTP resources for watching the player:

Method	Path	Purpose
`GET`	`/api/status`	Status snapshot
`GET`	`/api/health`	Health
`GET`	`/api/screenshot/low.png`	Low-resolution on-screen PNG (max 640 px)
`GET`	`/api/screenshot/high.png`	High-resolution on-screen PNG (max 1920 px)

The player does not serve runtime /api/spec, /api/capabilities, or /api/openapi.json (removed). Command metadata lives in the static snapshots web-console/api_spec.json and web-console/openapi.json.

OpenAPI is a secondary machine contract for infrastructure routes plus the three command routes. It is not the human command catalog—use the Command Reference.