Slatebox Docs
Browse documentation
Docs / HTTP API

Edit a shared slate from a terminal or an agent

Read Markdown
View agent prompt
Help me install the Slatebox shell and MCP tools from the checksummed package in this guide. Ask whether I want to open an existing board, draw a flow, or build a playable decision map. For a drawing use kind diagram. For a playable map use kind map. Create it once, keep the same arguments and key on retries, and give me the editor URL. For an existing slate, read its summary and ask which change I want. For a playable map, read its stations and legal destinations, then preview the requested branch, arrival instruction, token move or presentation order. For a whiteboard, preview the requested note edit. Show me the result before saving. When I ask to save it, reuse one idempotency key if you retry. Read back the saved edit and give me the canvas URL. Use my configured token without asking me to paste it into chat.

Read https://docs.slatebox.com/Developers/SlateboxAPI/terminal-and-agents.md first. Ask for the inputs you need. Tell me what you verified and which steps I still need to do.

If your client cannot fetch the documentation, read the same published file at https://raw.githubusercontent.com/Slatebox/slatebox-docs/retype/Developers/SlateboxAPI/terminal-and-agents.md.

Suppose two engineers are reviewing what happens to a customer's uploaded file. One engineer can add the next question from a terminal. The other can open the same private whiteboard, see the question and answer it beside the drawing.

Connect to your board

In Profile → Developer access, choose the token permissions you need. Read slates and Create and edit slates are selected by default. To issue or withdraw invitation links for your own boards, also select Manage invitation links on slates I own (slates:share). Load it from your secret manager into the environment variable SLATEBOX_API_TOKEN. An MCP client can pass that variable to its child process through its secret settings. For a self-hosted board, also set SLATEBOX_BASE_URL to the HTTPS origin of your Slatebox instance. Developer access

Install the tools

Use Node.js 20 or later. Download the package and its checksum into the project where you want to use them. The following commands verify the archive and install both executables locally.

download=https://docs.slatebox.com/assets/downloads
package=slatebox-mcp-0.2.6.tgz
curl -fsSLO "$download/$package"
curl -fsSLO "$download/$package.sha256"
shasum -a 256 -c "$package.sha256" && npm install "./$package"
npx --no-install slatebox --help

On Linux, sha256sum -c can also verify the checksum. If the downloads host is unavailable to your agent, use https://raw.githubusercontent.com/Slatebox/slatebox-docs/retype/assets/downloads for the download directory. For an MCP client, point its stdio server at the installed executable. Replace the example path with the absolute path on your machine and pass the token through your client's secret settings.

{
  "mcpServers": {
    "slatebox": {
      "command": "/absolute/path/to/project/node_modules/.bin/slatebox-mcp"
    }
  }
}

Download the tools · SHA-256 checksum

Create a diagram from source material

Which customers can still talk to support during a call-service outage? Use the public call-status example to start with two paths. New sessions failed to start while existing sessions stayed connected. This command saves the five notes and four arrows to your own private canvas.

create_key=$(node -p 'crypto.randomUUID()')
brief='What should support tell someone starting a new call during the outage?'
npx --no-install slatebox create "$brief" --kind diagram --source call-status \
  --idempotency-key "$create_key"

Open the returned url to edit a note, add your team’s fallback or present the drawing. diagram.nodes and diagram.connections describe what the command created. An agent can call create_slate with kind: "diagram", source: "call-status", the same brief and the same idempotency_key to retrieve the original creation result. Read the slate again to see subsequent edits.

With a source selected, a question such as “Who owns the callback?” opens in the conversation beside the drawing. To put the fallback on the canvas immediately, use the brief New session → Offer a callback. Slatebox reuses the existing New session note and draws an arrow to the new note. Paste additional paths or evidence notes on separate lines.

To draw your own flow, omit --source and pass steps such as Request -> Review -> Release as the brief. Each new line can begin a separate path or a standalone note. A diagram brief accepts up to 1,200 characters. The other available public sources are interview-notes and sign-in-outage. See the example drawing · Draw two spend-cap policies from a brief · HTTP request

Create a private decision map

Put the question your team needs to answer in the brief. This command creates a real slate in the account that issued the token. Generate a key once for this map and keep it for retries.

create_key=$(node -p 'crypto.randomUUID()')
npx --no-install slatebox create "Who can approve a customer refund?" \
  --idempotency-key "$create_key"

Open the returned url while signed in to that account. In the side conversation, type Ask finance or ask the account owner, then choose Keep changes to put both paths on the map. To start the same way from an MCP client, call create_slate with brief and idempotency_key. Move the team token and present the decision

Add a path and an arrival instruction

On the backfill map, an editor can give the reviewer a recovery path. Use the share ID from creation. A station can be identified by its exact unique label or its ID. This command previews the change.

npx --no-install slatebox branch "$SLATEBOX_SHARE_ID" "Compare row counts" "Repair missing rows" \
  --outcome "reconcile the missing IDs and run the comparison again."

Read workshop.revision from the preview. For a new map at revision 0, save that proposal with the following command. Keep its key for retries.

branch_key=$(node -p 'crypto.randomUUID()')
npx --no-install slatebox branch "$SLATEBOX_SHARE_ID" "Compare row counts" "Repair missing rows" \
  --outcome "reconcile the missing IDs and run the comparison again." \
  --apply --revision 0 --idempotency-key "$branch_key"

The result includes the new station ID in report.addedBranches. To change just its instruction, preview slatebox outcome "$SLATEBOX_SHARE_ID" "Repair missing rows" "Compare the repaired IDs with the source table." and save against its preview revision with a fresh key. If someone saves first, read the slate and review a new preview.

In MCP, call add_map_branch with share_id, from_station, label and outcome. To revise an instruction, call update_map_outcome with share_id, station and outcome. Both tools preview by default. To save, supply dry_run: false, expected_revision and idempotency_key. Use a token with read and write scopes and a board you can edit. Try the backfill map

Choose the opening scene

On the backfill map, put the recovery instruction first for a reviewer. Supply every scene once, using its ID or exact unique label. Preview the order before saving.

npx --no-install slatebox order "$SLATEBOX_SHARE_ID" \
  "Repair missing rows" "Backfill review" "Compare row counts" "Approve cutover"

Read report.presentationOrder and workshop.revision. To commit the sequence you reviewed, repeat the command with --apply --revision N --idempotency-key "$order_key". Replace N with that revision and generate order_key once for this change. Use the same key and IDs on retry. If another editor saved a change first, read the slate and preview the order again.

In MCP, call set_presentation_order with share_id and scenes. To commit, add dry_run: false, expected_revision and idempotency_key. Open Present together on the saved slate. Your reviewer can follow through their read link. A previously published walkthrough gets the new order when its owner republishes. Run the team walkthrough

Invite a reviewer

On your own instance, read /api/v1/openapi.json and look for /slates/{shareId}/invite. If that path is missing, the owner can issue the link from Share in the canvas or upgrade the instance before using these agent tools.

Use the shareId from creation or the owner’s canvas URL. An invitation turns a private slate into an unlisted slate. Anyone with the invitation URL can use its role. Choose read for someone reviewing a decision, comment for feedback, or edit for someone making changes on the board.

invite_key=$(node -p 'crypto.randomUUID()')
npx --no-install slatebox share "$SLATEBOX_SHARE_ID" --role edit --idempotency-key "$invite_key"

Give the reviewer the returned url and keep the inviteId for your records. Issuing a different role updates the board’s single unlisted link for everyone using it. To do the same from an MCP client, call create_slate_invite with share_id, role and idempotency_key.

When the review ends, set SLATEBOX_INVITE_ID to the returned ID and withdraw that invitation. Use a fresh key for this action and reuse it if you retry.

revoke_key=$(node -p 'crypto.randomUUID()')
npx --no-install slatebox unshare "$SLATEBOX_SHARE_ID" --invite-id "$SLATEBOX_INVITE_ID" --idempotency-key "$revoke_key"

The MCP equivalent is revoke_slate_invite with share_id, invite_id and idempotency_key. The board returns to private. People with separate private team grants can still use their assigned access. HTTP examples

Preview a question

On an ordinary whiteboard you can edit, copy the ID following /canvas/ in its URL and set SLATEBOX_SHARE_ID to that value. Read the board and save the following JSON as retention-question.json.

{
  "message": "Add a question for the architecture review",
  "operations": [
    {"kind": "add_nodes", "count": 1, "shape": "rectangle", "text": "Who owns deletion of the retained copy?"}
  ]
}
npx --no-install slatebox read "$SLATEBOX_SHARE_ID"
npx --no-install slatebox preview "$SLATEBOX_SHARE_ID" retention-question.json

The preview returns the operation report. Read the slate again to check its saved note count before applying the change. A pipeline can pass the plan on standard input by supplying - in place of the filename.

Save and reopen

Generate a key for this edit and keep it if you retry the same command. The service uses that key to recognize a request it already saved.

edit_key=$(node -p 'crypto.randomUUID()')
npx --no-install slatebox apply "$SLATEBOX_SHARE_ID" retention-question.json --idempotency-key "$edit_key"
npx --no-install slatebox read "$SLATEBOX_SHARE_ID" --full

Reopen the whiteboard in the browser. Find “Who owns deletion of the retained copy?” and edit the note to name the owner. Read the slate again from the terminal or ask your agent to read it. A teammate needs access to the private board to see your edit.

Run the same edit through MCP or HTTP

Action MCP tool HTTP request
Read the board get_slate with share_id and optional include_full GET /v1/slates/{shareId} with optional ?include=full
Preview the question apply_slate_operations with dry_run: true POST /v1/slates/{shareId}/operations with dryRun: true
Save the question apply_slate_operations with dry_run: false and an idempotency_key POST the same plan with dryRun: false and an Idempotency-Key header

For creating, sharing or presenting a map, see the editor, CLI, MCP and HTTP operation table. On a self-hosted instance, read /api/v1/openapi.json to discover the operations available on that release.

For apply_slate_operations, supply the board's share_id, the plan's message and operations, and a user_message describing your request. To try an agent with the saved board, tell it “Read my slate and find the note about the retained copy. Show me the change you would make to assign it to the data team.” Give it the board ID. It can read the note and preview the edit through MCP. On a playable map, the side conversation, CLI and MCP tools can add a branch with an arrival instruction. The move_workshop_card tool reads the same rules as the app and lets you preview or save a token’s move. Move a refund decision from a terminal A read-only collaborator can read the slate. Previewing or applying edits requires write scope and edit permission on that board. HTTP request bodies, responses and retries