Create, read and edit slates over HTTP.
A personal token and five routes. Send an edit as a dry run and read the report before anything is saved, then apply it with an idempotency key so a retry cannot add it twice.
Any registered account
The button opens a private slate with the three steps this replay starts from, drawn from one typed line. Read the OpenAPI contract ↗
$ curl --fail-with-body -sS \
-H "Authorization: Bearer $SLATEBOX_TOKEN" \
-H 'Content-Type: application/json' \
--data @preview.json \
"$slate_url/operations"
# HTTP 200: ok, dryRun, shareId, message,
# operations and a report. Nothing is saved.
$ request_id=$(uuidgen)
curl --fail-with-body -sS \
-H "Authorization: Bearer $SLATEBOX_TOKEN" \
-H "Idempotency-Key: $request_id" \
-H 'Content-Type: application/json' \
--data @apply.json \
"$slate_url/operations"
# HTTP 201: a new write
$ curl --fail-with-body -sS \
-H "Authorization: Bearer $SLATEBOX_TOKEN" \
-H "Idempotency-Key: $request_id" \
-H 'Content-Type: application/json' \
--data @apply.json \
"$slate_url/operations"
# HTTP 200: the prior result. The slate
# still has one welcome note.
A slate shows a sign-up flow of three steps. A server sends one edit as a dry run and gets a report back; the slate is unchanged. It sends the same plan with dryRun false and an Idempotency-Key header, and the note “Send the welcome email” is saved on the slate. The reply is lost, so the server sends the same request with the same key and gets the first result back; the slate still has one welcome note. Mara opens the slate and draws an arrow to the new note from “Verify email”.
The routes
Five routes for slates, one for embeds.
Paths are under https://api.slatebox.com/v1 on Slatebox Cloud. The OpenAPI 3.1 document has the request bodies and response schemas, and can be read before you issue a token.
| Request | Use | Access |
|---|---|---|
POST /slates | Create a private diagram or decision map from a brief. | slates:write and an Idempotency-Key |
GET /slates/{shareId} | Read a summary, or the full slate with ?include=full. | slates:read and permission to view the slate |
POST /slates/{shareId}/operations | Preview or apply an edit. | slates:write and permission to edit the slate |
POST /slates/{shareId}/invite | Issue or change the unlisted invitation link. | The owner, with slates:share and an Idempotency-Key |
DELETE /slates/{shareId}/invite/{inviteId} | Withdraw that invitation. | The owner, with slates:share and an Idempotency-Key |
GET /embed/{publishedSlateId} | Show a published presentation snapshot. | A published image |
How it works
Preview, apply, retry.
Create a token
In the app, open Profile, then Developer access, and tick the scopes you need. Send the token in the
Authorization: Bearerheader. Scopes and the account’s access are checked on every request.Preview
Post a plan with
"dryRun": true. The reply is HTTP 200 with the materialized operations and a report. The saved slate is untouched.preview.json { "dryRun": true, "userMessage": "Add the welcome email", "plan": { "message": "Add one step", "operations": [{ "kind": "add_nodes", "count": 1, "shape": "rectangle", "text": "Send the welcome email" }] } }Apply with a key
Post the same plan with
"dryRun": falseand anIdempotency-Keyheader. A new write returns HTTP 201.Retry safely
Send the same request with the same key and you get the prior result with HTTP 200. An HTTP 409 means another save changed the slate: read it again and preview against its current state.
Embedding
Show a published slate on your own page.
Publish a presentation from a slate, then copy the embed code from the published version. Readers step through its views inside your page. For a still preview, an iframe on the embed route shows the published image and links to the presentation player.
<iframe title="Who approves a refund?"
loading="lazy" width="800" height="450"
src="https://api.slatebox.com/embed/
YOUR_PUBLISHED_SLATE_ID"></iframe>- Needs
- A published presentation. Republish to include later edits.
- Plan
- Every plan can publish and embed.
Refund asked leads to: under $50 support approves; $50 and over finance approves.
The same routes on your own instance.
A self-hosted Slatebox serves the API itself, so a script written against the cloud needs one address changed.
- Slatebox Cloud
- Paths under
/v1atapi.slatebox.com. - Your instance
- Paths under
/api/v1on your own origin, with its own/api/v1/openapi.json. - The tools
- The command line and the MCP server take
SLATEBOX_BASE_URLto point at it.
The plan this needs.
- Free
- Any registered account can create a personal token, the free plan included, with the scopes
slates:read,slates:writeandslates:share, and hold up to 10 active tokens. - Pro and Team
- Nothing more is needed for this.
Next
More ways to build on it.
Read the contract first.
The route directory and the OpenAPI document are public. The docs walk through every request with curl.