Scripts

API

The same things an agent can do over MCP, as JSON for your own scripts: create, read and update walkthroughs and canvases, and nothing more.

Getting an API key

Sign in, and open your account page.
Under API keys, choose A script, through the REST API.
Press Create an API key, and copy it: it is shown once.

Send it with every request as Authorization: Bearer <key>. It is the same kind of key an agent uses, and everything lives under https://walkthrough.page/api/v1.

Routes

Paths are relative to /api/v1. Ids are the UUIDs the list and create routes answer with.

GET /walkthroughs: Every walkthrough the account owns: id, name, title, status, visibility and edit link.
POST /walkthroughs: Creates a private draft from { mdx, diagrams?, seed? }. Answers 201 with { id, name, edit }.
GET /walkthroughs/<id>: One walkthrough: { id, name, title, version, mdx, diagrams, seed }.
PUT /walkthroughs/<id>: Replaces it with { version, mdx, diagrams?, seed? }. A seed left out keeps the one it has.
GET /canvases: Every canvas the account owns: id, title, item count, what it opens on and its edit link.
POST /canvases: Draws one from { title, items, walkthrough? }. Answers 201 with { id, edit }.
GET /canvases/<id>: One canvas: { id, title, version, opens, items }.
PUT /canvases/<id>: Redraws it with { version, items, title? }. A title left out keeps the one it has.
PUT /canvases/<id>/link: { walkthrough } opens it on one of the account's walkthroughs; null detaches it.
GET /guide: The authoring guide, as Markdown.

Creating a walkthrough

A walkthrough is two files, sent as strings. jq is the easy way to put a file into JSON without escaping it by hand.

curl -X POST https://walkthrough.page/api/v1/walkthroughs \
  -H "Authorization: Bearer $WALKTHROUGH_API_KEY" \
  -H "Content-Type: application/json" \
  --data "$(jq -n --rawfile mdx index.mdx --rawfile diagrams diagrams.yml \
    '{ mdx: $mdx, diagrams: $diagrams }')"

{
  "ok": true,
  "id": "4b1c…",
  "name": "rate-limiting-an-api",
  "edit": "https://walkthrough.page/walkthroughs/4b1c…/edit"
}

Changing what is there

A PUT replaces the whole walkthrough or canvas. GET it first and send its version back with the change. If anybody wrote to it in between, you in the editor included, the answer is a 409 and nothing is saved: read it again and redo the change on that version.

A published walkthrough changes for its readers as soon as a write lands.

When it refuses

A refusal is a status and a body of { error, message }. The error is for your code to branch on and the message is for a person to read.

401 unsigned: No API key was sent, or it no longer signs anybody in.
404 gone: Nothing of yours has that id.
409 stale: It changed after you read it. Nothing was saved.
422 invalid: The body is not JSON, or it does not import. The message names what to fix.
503 storage: The database could not be reached. Try again.

{
  "error": "stale",
  "message": "Nothing was saved: it changed after you read it. GET it again and redo the change on that version."
}

What a walkthrough contains

GET /api/v1/guide answers with the authoring guide: both files, every block and diagram kind, the canvas items and their coordinates, and the limits the server enforces. It is tested against the importer, so what it describes is what the server accepts.

Create an API key Connect an agent