Every action has an HTTP endpoint: POST /api/actions/<id>. The request body is the input of the action, as one JSON object.
curl -X POST "https://www.turboslide.com/api/actions/slide.list?deck=<id>" \ -H "authorization: Bearer <token>" \ -H "content-type: application/json" \ -d '{}'| Part | What to send |
|---|---|
| Presentation | ?deck=<id> names the presentation. A write that names no presentation is refused with 400 and code: "deck_required". A read without it reads the example deck. |
| API key | On a hosted studio, send Authorization: Bearer <key> with an API key from turboslide login. On localhost, the routes respond without a key. |
| Author | Every write is recorded under the key's owner as agent:<tokenId>. The x-turboslide-author header and ?author= only label the run. They never change the author. |
| Force | ?force=1 writes to a slide another author has leased. Without it, that write is refused with 409 and the holder. |
| Size | A request body can be at most 1 MB. |
The scopes of an API key limit what it can do. The scopes are read, comment, write, export, share and admin. A key without the share scope reads the ids of other people as stand-ins. A stand-in is ref_ followed by 22 characters. The account reference lists the actions for API keys.
A picture can be up to 25 MB without an account and up to 50 MB when you are signed in. A hosted studio refuses SVG, re-encodes every picture and flattens an animated GIF to its first frame. Every studio refuses HEIF and JXL.
GET /api/actions/<id> returns the contract of the action. The contract holds the input and output JSON Schema, the transports and whether this studio runs the action. /openapi.json is the OpenAPI 3.1 document of every endpoint. /api/agent describes the studio.
An action error returns { "error": { "name", "status", "message", "code", "pointer", "currentRevision", "current", "holder", "capability" } }. The body contains only the fields that apply.
| Status | Means |
|---|---|
| 400 | The input is wrong. code and pointer name the field. |
| 401 | No key, or a key this studio does not accept. A key from turboslide login that is older than 90 days returns code: "key_expired". |
| 403 | The key may read the presentation but not do this. capability names what is missing. |
| 404 | No such presentation, slide or object, or a presentation the key may not read. Both cases return the same response. |
| 409 | The presentation changed since baseRevision, or another author holds the slide. The response carries the current document. |
| 410 | A revoked publish link, or a download address that expired. |
| 429 | A quota is used up. The body is { "error": "rate_limited", "message", "quota" } and Retry-After says when to try again. |
| 501 | This studio does not run the action. |
| 503 | The admin turned the feature off. The body is { "error": "unavailable", "message" } with Retry-After: 60. |
A write can succeed even when its request times out. To send such a write again safely, use the Idempotency-Key header. Use one value per write, such as a UUID. Send the same key with the same body on the resend. If the first write succeeded, the studio does not apply it again. It returns 200 with the response of the first write and the header idempotent-replayed: true.
| Response | Means |
|---|---|
400 invalid_idempotency_key | The key is not 1 to 255 visible ASCII characters. |
400 idempotency_not_supported | The action does not take a key. |
422 idempotency_key_reused | The key was already sent with another action or another body. |
The writes to slides, objects, text, sections, pictures and the settings of the presentation take the key. version.restore, fix.run and assist.accept also take it. The OpenAPI document names the header on each of these actions. The other writes do not take the key. These are the writes that make, copy, trash or share a presentation, and the writes to templates, named versions, comments, leases, presence, accounts and administration.
GET /api/render/<slideId>?deck=<id>&theme=light&scale=1returns the slide as a PNG.?format=jsonreturns the render record instead. A full size render needs the bearer header.GET /api/render/<slideId>?deck=<id>&w=320returns a thumbnail that is 160, 320 or 640 pixels wide. Anyone who can open the presentation can get it.POST /api/export/<id>?sync=1with theexport.runinput returns the file. Always send?sync=1, because a hosted studio always exports synchronously.- A file over 4.5 MB cannot be returned directly. On a studio with a Blob store, the response is a 302 redirect to
/api/download/s.<token>. This address is signed for the caller and works for ten minutes. After that, it returns 410. On a studio without a Blob store, the response is 413. In that case, export one theme or fewer slides.