HTTP actions

Call any action with one POST request, read its contract, and render slides and export files over HTTP.

Every action has an HTTP endpoint: POST /api/actions/<id>. The body is the action's input as one JSON object.

curl -X POST "https://www.turboslide.com/api/actions/slide.list?deck=<id>" \
  -H "authorization: Bearer <token>" \
  -H "x-turboslide-author: agent:my-run" \
  -H "content-type: application/json" \
  -d '{}'

The request

Part	What to send
Presentation	`?deck=<id>` names the presentation.
Author	The `x-turboslide-author: agent:<runId>` header, or `?author=`. Without it the write is recorded as `agent:http`.
Force	`?force=1` writes to a slide another author has leased. Without it, that write is refused with 409 and the holder.
Token	`Authorization: Bearer <token>` on a hosted studio. On localhost the routes answer without one.
Size	At most 1 MB per write and 25 MB per picture.

GET /api/actions/<id> returns the action's contract: the input and output JSON Schema, the transports and whether this studio runs it. /openapi.json is the OpenAPI 3.1 document of every endpoint, and /api/agent describes the studio.

Errors

An error answers with { "error": { "name", "status", "message", "code", "pointer", "currentRevision", "current", "holder" } }; only the fields that apply are present.

Status	Means
400	The input is wrong. `code` and `pointer` name the field.
401	No token, or a token this studio does not accept.
404	No such presentation, slide or object.
409	The presentation changed since `baseRevision`, or another author holds the slide. The answer carries the current document.
501	This studio does not run the action.

Renders and downloads

GET /api/render/<slideId>?deck=<id>&theme=light&scale=1 answers the slide as a PNG. ?format=json answers the render record instead.
POST /api/export/<id>?sync=1 with the export.run input answers the file. Send ?sync=1 every time: a hosted studio always works that way.
A file over 4.5 MB cannot be returned directly. The studio answers 302 to a stored copy when it has a Blob store, or 413; export one theme or fewer slides then.