The control API over HTTP

For a script, a Shortcut, or software that can only send a web request, the API also answers plain HTTP: the same state and the same commands, one request and one answer each.

Request	Body	Answer
GET /v2/state	—	the state
POST /v2/action	{"verb": …, "inputID": …, "parameters": …, "withoutAsking": …, "requestID": …}	{"type": "done"} or a refusal
POST /v2/press	{"mappingID": …, "withoutAsking": …, "requestID": …}	the same

The bodies are the WebSocket’s commands without their type.

On the Mac running InterDirector

curl http://127.0.0.1:49721/v2/state
curl -X POST http://127.0.0.1:49721/v2/action -H 'X-Client: Scoreboard' \
  -d '{"verb": "cutPreview"}'

No password, and never from a web page: a request a browser sends is refused.

From another computer

Turn on the Show’s web remote, and send its password with every request:

curl -k https://studio-mac.local:49722/v2/state \
  -H 'Authorization: Bearer <the web remote password>'

-k accepts the Mac’s own certificate. A wrong or missing password is answered 401; after three wrong ones from one computer, InterDirector waits before it listens to that computer again (up to 30 seconds), answering 429 with retryAfter in the meantime.

Status codes

Status	Meaning
200	done, or the state
400	the body is not a command
401	from another computer: a wrong or missing password
403	refused: a web page on this Mac, or another site’s page
404	not one of the routes
405	the wrong method for the route
409	refused as stale: something the Show no longer has
413	a body larger than 64 KB
429	from another computer: wait retryAfter seconds

Name your script with an X-Client header: its commands are written to the Show’s journal as “API (Scoreboard): Cut”. Without one, the first word of its user agent is used.