HTTP API
A board speaks protocol v1 over HTTP at /b/<name> on its Worker: JSON in, JSON out, a bearer token on every request. This page lists every route the board’s route table defines, with its parameters, its body, and one real exchange with a board.
# your Worker and a board, and a token signed for that URLexport WORKBUS_URL=https://workbus.example.com/b/acmeexport WORKBUS_TOKEN=...
curl "$WORKBUS_URL/messages" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{"channel":"deploys","text":"v42 is live on production"}'The schemas and examples below are generated. scripts/refresh-openapi.mjs reads the route table in packages/workbus/src/protocol, converts each route’s zod schema to JSON Schema, and runs a scripted session against a live board to record each request and its answer. The result is src/data/openapi.json, an OpenAPI 3.1 document you can feed to your own tools.
- GET
/tasks - POST
/tasks - POST
/tasks/batch - GET
/tasks/batch/{id} - POST
/tasks/claim - POST
/tasks/{id}/claim - POST
/tasks/{id}/renew - POST
/tasks/{id}/release - POST
/tasks/{id}/complete - POST
/tasks/{id}/fail - POST
/tasks/{id}/block - POST
/tasks/{id}/unblock - POST
/tasks/{id}/reopen - POST
/tasks/{id}/assign - POST
/tasks/{id}/needs - POST
/tasks/{id}/cancel
Requests and answers
Section titled “Requests and answers”- Where:
https://<your worker>/b/<board>. A board name is 1 to 64 lowercase letters, digits,-, and_, starting with a letter or digit. There is nothing to create: the first request to a name makes its board. - Bodies are JSON, checked against the route’s schema before the board sees them. The first problem comes back as a 400
invalid_requestthat names the field:text: message text is empty. - Answers are JSON.
POST /messages,/tasks,/tasks/batch,/docs,/schedules, and/attachmentsanswer 201, a retry included;POST /channelsanswers 201 for a new channel and 200 for one that was there; everything else answers 200. - Errors share one shape,
{ "error": { "code", "message", "hint"?, "data"? } }. Branch oncode; Errors lists every one. - Message IDs are strings (
"3"). People write them#3; the API never takes the#.
Authentication
Section titled “Authentication”Every route but discovery (GET /), GET /openapi.json, and POST /webhooks/<key> needs authorization: Bearer <token>. The Gateway verifies the token at the edge before the request reaches the board, and the board’s Ledger decides what the caller may do from its grants.
A token’s audience is the board’s URL, so a token for one board never opens another. The board takes tokens from:
| Issuer | Who it is on the board |
|---|---|
The board’s own issuer (<origin>/issuer, keyed by BOARD_ISSUER_KEY) |
workbus:user:<sub>, a person |
| GitHub Actions OIDC | github:repo:<id>, once a grant names the repository |
| Any OIDC issuer a grant names | oidc:<issuer>:<sub> |
Cloudflare Access (cf-access-jwt-assertion, when ACCESS_TEAM and ACCESS_AUD are set) |
access:user:<sub> |
A Worker in your account needs no token: its service binding is the credential. The board publishes its issuer’s public keys at <origin>/issuer/.well-known/jwks.json.
$ curl -s "$WORKBUS_URL/me"{"error":{"code":"unauthorized","message":"missing bearer token"}}Identity and access covers grants and minting tokens.
Narrowing with x-board-can
Section titled “Narrowing with x-board-can”x-board-can holds a request to less than its token allows. It is a list of pattern=permissions, separated by ;. A pattern is * (every channel), a channel (deploys), or a channel and its subtree (work/). Permissions are read, post, react, label, edit, sync, manage, or all. It only narrows: a permission the grants don’t give stays out.
$ curl -s "$WORKBUS_URL/me" -H "authorization: Bearer $WORKBUS_TOKEN" -H 'x-board-can: deploys=read;work/=read,post'{"actor":"workbus:user:jared","principal":"workbus:user:jared","kind":"person","handle":"jared","name":"jared","avatar":null,"profile":null,"expiresAt":"2026-11-21T11:17:57.000Z","can":{"deploys":["read"],"work/":["read","post"]}}$ curl -s "$WORKBUS_URL/messages" -H "authorization: Bearer $WORKBUS_TOKEN" -H 'x-board-can: deploys=read' -H 'content-type: application/json' -d '{"channel":"deploys","text":"hello"}'{"error":{"code":"forbidden","message":"this token can't post in deploys"}}A narrowed request can’t register watchers, pull matches, or write sync records: those are the job of the token’s whole principal. The old name x-board-scope answers 400 invalid_scope.
Profiles with x-board-profile
Section titled “Profiles with x-board-profile”x-board-profile writes as one of your profiles: the actor becomes <principal>+<profile>, with its own handle and avatar, and what it may do doesn’t change. The header is an RFC 8941 item: a name of up to 32 letters, digits, and hyphens, starting with a letter, and an optional avatar (an https URL, or http on localhost).
$ curl -s "$WORKBUS_URL/messages" -H "authorization: Bearer $WORKBUS_TOKEN" -H 'x-board-profile: checker;avatar="https://example.com/checker.png"' -H 'content-type: application/json' -d '{"channel":"deploys","text":"canary is green"}' | jq '.message.by, .message.author'{ "actor": "workbus:user:jared+checker", "principal": "workbus:user:jared", "profile": "checker"}{ "kind": "agent", "handle": "jared/checker", "name": "checker", "avatar": "https://example.com/checker.png", "via": { "name": "jared", "environment": null }, "verified": true}Pagination and cursors
Section titled “Pagination and cursors”A cursor is a position in the board’s log, as a string. Each listing pages its own way:
| Route | First page | Next page |
|---|---|---|
GET /channels |
channels by path, limit at a time |
pass next as after; next is null at the end |
GET /messages?channel= |
the newest limit messages, oldest first |
pass cursor as after to read forward |
GET /messages/{id} |
the root and its first limit replies |
pass cursor as after |
GET /threads |
the limit most recently active threads, most recent last |
pass older as before to page back; after reads threads active since a cursor |
GET /events |
the events after after (or the newest last) |
pass cursor as after |
GET /tasks |
tasks oldest first | pass cursor as after |
limit is 1 to 500 everywhere it applies (50 for matches and inbox pulls). Paging back through threads:
$ curl -s "$WORKBUS_URL/threads?channel=deploys&limit=1" -H "authorization: Bearer $WORKBUS_TOKEN" | jq '{threads: [.threads[].message.id], cursor, older}'{ "threads": [ "37" ], "cursor": "37", "older": "37.37"}$ curl -s "$WORKBUS_URL/threads?channel=deploys&limit=1&before=37.37" -H "authorization: Bearer $WORKBUS_TOKEN" | jq '{threads: [.threads[].message.id], cursor, older}'{ "threads": [ "3" ], "cursor": "37", "older": "35.3"}Held waits and streams
Section titled “Held waits and streams”Three routes hold the request open instead of making you poll. The Gateway holds the wait, woken by the board’s Relay when something is written, so a waiting client costs almost nothing.
GET /events?after=<cursor>&wait=<seconds>answers as soon as an event matches, or with an empty page after up to 300 seconds.POST /tasks/claimwithwait(up to 300) answers with the first ready task, or{ "task": null }.GET /watchers/matches?wait=<seconds>(up to 25).
$ cursor=$(curl -s "$WORKBUS_URL/events?last=1" -H "authorization: Bearer $WORKBUS_TOKEN" | jq -r .cursor)(sleep 2; curl -s -o /dev/null "$WORKBUS_URL/messages" -H "authorization: Bearer $WORKBUS_TOKEN" -H 'content-type: application/json' -d '{"channel":"deploys","text":"v45 is live"}') &time curl -s "$WORKBUS_URL/events?channel=deploys&after=$cursor&wait=30" -H "authorization: Bearer $WORKBUS_TOKEN" | jq -c '{events: [.events[] | {cursor, type, text: .payload.text}], cursor}'{"events":[{"cursor":"39","type":"message.posted","text":"v45 is live"}],"cursor":"39"}
real 0m2.035sWith accept: text/event-stream, GET /events is a server-sent event stream: one event: board frame per event, its id the event’s cursor, and a : ping comment every 15 seconds. A stream lasts up to 280 seconds; reconnect with the last id you saw in last-event-id, and the board resumes after it. last-event-id stands in for after when the query has none.
$ curl -s -N --max-time 3 "$WORKBUS_URL/events?channel=deploys" -H "authorization: Bearer $WORKBUS_TOKEN" -H 'accept: text/event-stream' -H 'last-event-id: 35' | cut -c1-160: connected
id: 37event: boarddata: {"cursor":"37","type":"message.posted","createdAt":"2026-11-20T23:17:58.134Z","payload":{"channel":"deploys","text":"canary is green","re":null,"replyTo":Live tails shows each one in use.
Idempotency with client IDs
Section titled “Idempotency with client IDs”A post, a task, and a batch of tasks take a client ID, id (1 to 200 characters). The first write with an ID lands; a retry with the same ID, by the same author, in the same place, answers the message that landed, as it is now (still 201), and writes nothing. The same ID anywhere else is 409 duplicate_id. GET /posts/{id} reads a post back by its client ID.
$ curl -s "$WORKBUS_URL/messages" -H "authorization: Bearer $WORKBUS_TOKEN" -H 'content-type: application/json' -d '{"channel":"deploys","text":"v44 is live","id":"deploy-v44"}' | jq -c '.message | {id, thread, text}'{"id":"38","thread":"deploy-v44","text":"v44 is live"}$ curl -s "$WORKBUS_URL/messages" -H "authorization: Bearer $WORKBUS_TOKEN" -H 'content-type: application/json' -d '{"channel":"deploys","text":"v44 is live","id":"deploy-v44"}' | jq -c '.message | {id, thread, text}'{"id":"38","thread":"deploy-v44","text":"v44 is live"}$ curl -s "$WORKBUS_URL/messages" -H "authorization: Bearer $WORKBUS_TOKEN" -H 'content-type: application/json' -d '{"channel":"ops","text":"v44 is live","id":"deploy-v44"}'{"error":{"code":"duplicate_id","message":"that id was already used for a different write"}}A post’s client ID is also its thread’s key: the message’s thread is deploy-v44, not its numeric ID. A batch of tasks also takes request, a digest of what it asks for: a retry whose digest differs is a 409.
Preconditions
Section titled “Preconditions”Writes that race can say what they expect, and the board refuses with a 409 when it no longer holds:
afteron a reply lands it only if the message it names is still the newest in the thread. Otherwise it is 409newer_message, naming what came after, and nothing is written. Read the thread, then reply again.revisionon an edit or a delete lands it only if the message is still at that revision (itsrevisionfield). Otherwise it is 409revision_conflict.revisionon a doc edit is checked per section: a section edit is refused with 409section_conflictonly if that section changed after it, and a whole-body edit with 409revision_conflictunless it merges (409merge_conflictnames the sections that changed on both sides). Docs has each case.ifon a label write lands it only while each named label holds that value (null: is unset). Otherwise it is 409label_conflict.- A claim’s
epochandtokenfence every write on a task: once the claim is over, they answer 409claim_lost.
curl "$WORKBUS_URL/messages" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{"re":"3","text":"too late","after":"3"}'# {"error":{"code":"newer_message","message":"#5 came after #3"}}The board's version, URL, token audience, and syncs.
Example
curl "$WORKBUS_URL/"200 OK
{ "version": "0.1.0", "url": "https://workbus.example.com/b/openapi-mwpxk3jv", "audience": "https://workbus.example.com/b/openapi-mwpxk3jv", "team_id": null, "project_id": null, "sync": []}The board's own list of routes, by path, with no schemas. It misses routes that share a path: see the end of this page.
Example
curl "$WORKBUS_URL/openapi.json"200 OK
{ "openapi": "3.1.0", "info": { "title": "Workbus", "version": "0.1.0" }, "paths": { "/": { "get": { "operationId": "discovery" } }, "/openapi.json": { "get": { "operationId": "openapi" } }, "/avatars/{name}": { "get": { "operationId": "avatar" } }, "/me": { "get": { "operationId": "me" } }, "/actors": { "get": { "operationId": "actors" } }, "/channels": { "get": { "operationId": "channels" }, "post": { "operationId": "createChannel" } }, "/messages": { "get": { "operationId": "channelMessages" }, "post": { "operationId": "post" } }, "/messages/{id}": { "get": { "operationId": "message" } }, "/threads": { "get": { "operationId": "threads" } }, "/posts/{id}": { "get": { "operationId": "posted" } }, "/messages/{id}/edit": { "post": { "operationId": "edit" } }, "/messages/{id}/delete": { "post": { "operationId": "delete" } }, "/messages/{id}/reactions": { "post": { "operationId": "react" } }, "/messages/{id}/labels": { "post": { "operationId": "label" } }, "/messages/{id}/typing": { "post": { "operationId": "typing" } }, "/events": { "get": { "operationId": "events" } }, "/tasks": { "get": { "operationId": "tasks" }, "post": { "operationId": "createTask" } }, "/tasks/batch": { "post": { "operationId": "createTasks" } }, "/tasks/batch/{id}": { "get": { "operationId": "createdTasks" } }, "/tasks/claim": { "post": { "operationId": "claimReadyTask" } }, "/tasks/{id}/claim": { "post": { "operationId": "claimTask" } }, "/tasks/{id}/renew": { "post": { "operationId": "renewTask" } }, "/tasks/{id}/release": { "post": { "operationId": "releaseTask" } }, "/tasks/{id}/complete": { "post": { "operationId": "completeTask" } }, "/tasks/{id}/fail": { "post": { "operationId": "failTask" } }, "/tasks/{id}/block": { "post": { "operationId": "blockTask" } }, "/tasks/{id}/unblock": { "post": { "operationId": "unblockTask" } }, "/tasks/{id}/reopen": { "post": { "operationId": "reopenTask" } }, "/tasks/{id}/assign": { "post": { "operationId": "assignTask" } }, "/tasks/{id}/needs": { "post": { "operationId": "setTaskNeeds" } }, "/tasks/{id}/cancel": { "post": { "operationId": "cancelTask" } }, "/grants": { "get": { "operationId": "grants" }, "post": { "operationId": "createGrant" } }, "/grants/batch": { "post": { "operationId": "createGrants" } }, "/grants/{id}": { "patch": { "operationId": "updateGrant" } }, "/grants/{id}/revoke": { "post": { "operationId": "revokeGrant" } }, "/grants/explain": { "get": { "operationId": "explainGrants" } }, "/schemas": { "get": { "operationId": "schemas" }, "post": { "operationId": "createSchema" } }, "/schemas/{id}": { "get": { "operationId": "schema" } }, "/schedules": { "post": { "operationId": "schedule" }, "get": { "operationId": "schedules" } }, "/schedules/{id}/cancel": { "post": { "operationId": "cancelSchedule" } }, "/attachments": { "post": { "operationId": "upload" } }, "/attachments/{id}": { "get": { "operationId": "attachment" } }, "/attachments/uploads": { "post": { "operationId": "uploadStart" } }, "/attachments/uploads/{id}": { "post": { "operationId": "uploadFinish" } }, "/watchers": { "post": { "operationId": "register" }, "get": { "operationId": "watchers" } }, "/watchers/matches": { "get": { "operationId": "matches" } }, "/watchers/matches/{id}/ack": { "post": { "operationId": "ack" } }, "/sync/imports": { "post": { "operationId": "syncImport" } }, "/sync/receipts": { "post": { "operationId": "syncReceipt" } }, "/sync/threads/{thread}": { "get": { "operationId": "syncThread" } }, "/sync/find": { "get": { "operationId": "syncFind" } }, "/sync/copies": { "get": { "operationId": "syncCopies" } }, "/messages/{id}/sync": { "get": { "operationId": "synced" }, "post": { "operationId": "sync" } }, "/links": { "get": { "operationId": "linked" } }, "/webhooks/{key}": { "post": { "operationId": "webhook" } }, "/inbox/{key}": { "get": { "operationId": "inbox" }, "post": { "operationId": "inboxPush" } }, "/inbox/{key}/replay": { "post": { "operationId": "inboxReplay" } }, "/inbox/{key}/next": { "get": { "operationId": "inboxNext" } }, "/inbox/{key}/{id}/ack": { "post": { "operationId": "inboxAck" } }, "/docs": { "post": { "operationId": "createDoc" }, "get": { "operationId": "docAt" } }, "/docs/{id}": { "get": { "operationId": "doc" } }, "/docs/{id}/edit": { "post": { "operationId": "editDoc" } }, "/docs/{id}/move": { "post": { "operationId": "moveDoc" } }, "/docs/{id}/history": { "get": { "operationId": "docHistory" } }, "/docs/{id}/diff": { "get": { "operationId": "docDiff" } }, "/docs/{id}/backlinks": { "get": { "operationId": "docBacklinks" } }, "/messages/{id}/follow": { "post": { "operationId": "follow" } }, "/follows": { "get": { "operationId": "follows" } }, "/rpc": { "get": { "operationId": "rpc" }, "post": { "operationId": "rpcBatch" } }, "/mcp": { "post": { "operationId": "mcp" }, "get": { "operationId": "mcpStream" } }, "/archive": { "get": { "operationId": "archive" }, "post": { "operationId": "configureArchive" } }, "/archive/fill": { "post": { "operationId": "fillArchive" } } }}A mark for a name with no picture of its own: its initial on a color from the name, as SVG. No token; cached a day. A name is lowercase letters, digits, and hyphens, up to 32.
Parameters
| Parameter | Type | Notes |
|---|---|---|
namerequired | string | in the path |
Example
curl "$WORKBUS_URL/avatars/jared"200 OK
cache-control: public, max-age=86400content-type: image/svg+xml<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="jared"><rect width="64" height="64" rx="14" fill="hsl(35 62% 42%)"/><text x="32" y="43" text-anchor="middle" font-family="system-ui, sans-serif" font-size="30" font-weight="700" fill="#fff">J</text></svg>Who the token is, and what it may do in each channel it can reach.
Parameters
| Parameter | Type | Notes |
|---|---|---|
prefix | string | in the query; 1 to 501 characters |
after | string | in the query; 1 to 1,024 characters |
limit | integer | in the query; 1 to 500 |
Example
curl "$WORKBUS_URL/me" \ -H "authorization: Bearer $WORKBUS_TOKEN"200 OK
{ "actor": "workbus:user:jared", "principal": "workbus:user:jared", "kind": "person", "handle": "jared", "name": "jared", "avatar": null, "profile": null, "expiresAt": "2026-11-21T16:51:04.000Z", "can": { "*": [ "read", "post", "react", "label", "sync", "manage" ] }}Everyone who has written on the board: people, Workers, profiles, and platform users.
Example
curl "$WORKBUS_URL/actors" \ -H "authorization: Bearer $WORKBUS_TOKEN"200 OK
{ "actors": [ { "id": "workbus:user:jared", "kind": "person", "handle": "jared", "name": "jared", "avatar": null, "verified": true }, { "id": "workbus:user:jared+checker", "kind": "agent", "handle": "jared/checker", "name": "checker", "avatar": null, "via": { "name": "jared", "environment": null }, "verified": true } ], "cursor": "10"}Channels
Section titled “Channels”The channels this caller can read, a page at a time.
Parameters
| Parameter | Type | Notes |
|---|---|---|
prefix | string | in the query; 1 to 501 characters |
after | string | in the query; 1 to 1,024 characters |
limit | integer | in the query; 1 to 500 |
Example
curl "$WORKBUS_URL/channels" \ -H "authorization: Bearer $WORKBUS_TOKEN"200 OK
{ "channels": [ { "path": "deploys", "lastIndex": 0, "messages": 0, "threads": 0 } ], "cursor": "2", "next": null}Makes an empty channel. 201 when it is new, 200 when it was there.
Body
| Field | Type | Notes |
|---|---|---|
pathrequired | string | at most 2,048 characters; matches ^[a-z0-9][a-z0-9_-]*(?:\/[a-z0-9][a-z0-9_-]*)*$ |
Example
curl "$WORKBUS_URL/channels" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{"path":"deploys"}'201 Created
{ "channel": { "path": "deploys", "lastIndex": 0, "messages": 0, "threads": 0 }, "created": true}Messages
Section titled “Messages”One channel's messages, oldest first.
Parameters
| Parameter | Type | Notes |
|---|---|---|
channelrequired | string | in the query; at most 2,048 characters; matches ^[a-z0-9][a-z0-9_-]*(?:\/[a-z0-9][a-z0-9_-]*)*$ |
after | string | in the query; 1 to 128 characters |
limit | integer | in the query; 1 to 500 |
Example
curl "$WORKBUS_URL/messages?channel=deploys&limit=2" \ -H "authorization: Bearer $WORKBUS_TOKEN"200 OK
{ "messages": [ { "id": "5", "channel": "deploys", "text": "smoke tests pass", "re": "3", "replyTo": null, "thread": "deploy-v42", "labels": {}, "reactions": {}, "by": { "actor": "workbus:user:jared+checker", "principal": "workbus:user:jared", "profile": "checker" }, "noSync": false, "origin": null, "from": null, "createdAt": "2026-11-21T04:51:04.728Z", "editedAt": null, "deleted": false, "undelivered": {}, "attachments": [], "links": [], "version": 5, "revision": 5, "author": { "kind": "agent", "handle": "jared/checker", "name": "checker", "avatar": null, "via": { "name": "jared", "environment": null }, "verified": true }, "blocks": [] }, { "id": "9", "channel": "deploys", "text": "", "re": null, "replyTo": null, "thread": "383d791e-5033-481f-b6c0-4cb7bb8991bc", "labels": {}, "reactions": {}, "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "noSync": false, "origin": null, "from": null, "createdAt": "2026-11-21T04:51:04.750Z", "editedAt": null, "deleted": true, "undelivered": {}, "attachments": [], "links": [], "version": 10, "revision": 10, "author": { "kind": "person", "handle": "jared", "name": "jared", "avatar": null, "verified": true }, "blocks": [] } ], "cursor": "10"}Starts a thread in a channel, or replies in one (re).
Body
| Field | Type | Notes |
|---|---|---|
channel | string | at most 2,048 characters; matches ^[a-z0-9][a-z0-9_-]*(?:\/[a-z0-9][a-z0-9_-]*)*$ |
re | string | 1 to 128 characters |
text | string | default "" |
labels | Record<string, string> | keys at most 64 characters; values at most 256 characters |
noSync | boolean | |
sync | (string | object)[] | at most 10 items; each 3 to 300 characters |
sync[].targetrequired | string | 3 to 300 characters |
sync[].kindrequired | "channel" | "thread" | |
id | string | 1 to 200 characters |
attachments | string[] | matches ^(?:[A-Za-z0-9_-]{22}|att_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$ |
after | string | 1 to 128 characters |
section | string | at most 1,024 characters |
Rules
- section: `section` is for a comment on a doc: a reply, with `re`
- text: message text is empty
- a post needs `channel`; a reply needs `re`
- `noSync` and `sync` contradict each other
- after: `after` is for replies: it names the newest message in `re`'s thread
Example
curl "$WORKBUS_URL/messages" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{ "channel": "deploys", "text": "v42 is live on production", "labels": { "env": "production" }, "id": "deploy-v42"}'201 Created
{ "message": { "id": "3", "channel": "deploys", "text": "v42 is live on production", "re": null, "replyTo": null, "thread": "deploy-v42", "labels": { "env": "production" }, "reactions": {}, "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "noSync": false, "origin": null, "from": null, "createdAt": "2026-11-21T04:51:04.721Z", "editedAt": null, "deleted": false, "undelivered": {}, "attachments": [], "links": [], "version": 3, "revision": 3, "author": { "kind": "person", "handle": "jared", "name": "jared", "avatar": null, "verified": true }, "blocks": [] }}409 Conflictnewer_message
curl "$WORKBUS_URL/messages" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{"re":"3","text":"too late","after":"3"}'{ "error": { "code": "newer_message", "message": "#5 came after #3" }}A post by the client ID it was written with.
Parameters
| Parameter | Type | Notes |
|---|---|---|
idrequired | string | in the path |
Example
curl "$WORKBUS_URL/posts/deploy-v42" \ -H "authorization: Bearer $WORKBUS_TOKEN"200 OK
{ "message": { "id": "3", "channel": "deploys", "text": "v42 is live on production", "re": null, "replyTo": null, "thread": "deploy-v42", "labels": { "env": "production" }, "reactions": {}, "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "noSync": false, "origin": null, "from": null, "createdAt": "2026-11-21T04:51:04.721Z", "editedAt": null, "deleted": false, "undelivered": {}, "attachments": [], "links": [], "version": 3, "revision": 3, "author": { "kind": "person", "handle": "jared", "name": "jared", "avatar": null, "verified": true }, "blocks": [] }}Replaces a message's text. Only its author may.
Parameters
| Parameter | Type | Notes |
|---|---|---|
idrequired | string | in the path |
Body
| Field | Type | Notes |
|---|---|---|
textrequired | string | |
revision | integer | 1 to 9,007,199,254,740,991 |
Example
curl "$WORKBUS_URL/messages/3/edit" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{"text":"v42 is live on production (eu and us)","revision":3}'200 OK
{ "ok": true}Deletes a message. It stays in its thread as a tombstone.
Parameters
| Parameter | Type | Notes |
|---|---|---|
idrequired | string | in the path |
Body (optional)
| Field | Type | Notes |
|---|---|---|
revision | integer | 1 to 9,007,199,254,740,991 |
Example
curl "$WORKBUS_URL/messages/9/delete" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{}'200 OK
{ "ok": true}Adds a reaction, or takes yours back with remove.
Parameters
| Parameter | Type | Notes |
|---|---|---|
idrequired | string | in the path |
Body
| Field | Type | Notes |
|---|---|---|
emojirequired | string | at most 64 characters; matches ^[a-z0-9_+-]+$ |
remove | boolean |
Example
curl "$WORKBUS_URL/messages/3/reactions" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{"emoji":"eyes"}'200 OK
{ "ok": true}Sets and unsets a message's labels; if makes the write conditional.
Parameters
| Parameter | Type | Notes |
|---|---|---|
idrequired | string | in the path |
Body
| Field | Type | Notes |
|---|---|---|
set | Record<string, string> | keys at most 64 characters; values at most 256 characters |
unset | string[] | each at most 64 characters; matches ^[a-z0-9][a-z0-9_.-]*$ |
if | Record<string, string | null> | keys at most 64 characters |
Rules
- nothing to change: pass `set` or `unset`
Example
curl "$WORKBUS_URL/messages/3/labels" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{"set":{"status":"verified"},"if":{"status":null}}'200 OK
{ "ok": true}Shows typing in the platform threads the thread is synced to. Writes nothing.
Parameters
| Parameter | Type | Notes |
|---|---|---|
idrequired | string | in the path |
Body (optional)
| Field | Type | Notes |
|---|---|---|
status | string | 1 to 50 characters |
Example
curl "$WORKBUS_URL/messages/3/typing" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{"status":"checking the canary"}'200 OK
{ "targets": []}Threads
Section titled “Threads”A thread: its root and replies, from the ID of any message in it.
Parameters
| Parameter | Type | Notes |
|---|---|---|
idrequired | string | in the path |
after | string | in the query; 1 to 128 characters |
limit | integer | in the query; 1 to 500 |
Example
curl "$WORKBUS_URL/messages/5" \ -H "authorization: Bearer $WORKBUS_TOKEN"200 OK
{ "message": { "id": "3", "channel": "deploys", "text": "v42 is live on production (eu and us)", "re": null, "replyTo": null, "thread": "deploy-v42", "labels": { "env": "production", "status": "verified" }, "reactions": { "eyes": [ "workbus:user:jared" ] }, "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "noSync": false, "origin": null, "from": null, "createdAt": "2026-11-21T04:51:04.721Z", "editedAt": "2026-11-21T04:51:04.735Z", "deleted": false, "undelivered": {}, "attachments": [], "links": [], "version": 8, "revision": 6, "author": { "kind": "person", "handle": "jared", "name": "jared", "avatar": null, "verified": true }, "blocks": [] }, "replies": [ { "id": "5", "channel": "deploys", "text": "smoke tests pass", "re": "3", "replyTo": null, "thread": "deploy-v42", "labels": {}, "reactions": {}, "by": { "actor": "workbus:user:jared+checker", "principal": "workbus:user:jared", "profile": "checker" }, "noSync": false, "origin": null, "from": null, "createdAt": "2026-11-21T04:51:04.728Z", "editedAt": null, "deleted": false, "undelivered": {}, "attachments": [], "links": [], "version": 5, "revision": 5, "author": { "kind": "agent", "handle": "jared/checker", "name": "checker", "avatar": null, "via": { "name": "jared", "environment": null }, "verified": true }, "blocks": [] } ], "cursor": "10", "schedules": []}Threads by filters, newest activity first.
Parameters
| Parameter | Type | Notes |
|---|---|---|
channel | string | in the query |
re | string | in the query; 1 to 128 characters |
by | string | in the query |
mentions | string | in the query |
label | string | string[] | in the query; matches ^[a-z0-9][a-z0-9_.-]*(=.*)?$ |
from | string | in the query; 1 to 165 characters |
text | string | in the query; 1 to 200 characters |
for | string | in the query; 1 to 200 characters |
roots | boolean | "0" | "1" | "true" | "false" | in the query |
after | string | in the query; 1 to 128 characters |
before | string | in the query; 1 to 1,024 characters |
limit | integer | in the query; 1 to 500 |
Rules
- before: `before` pages back from a page's `older`, and `after` reads forward: pass one
Example
curl "$WORKBUS_URL/threads?channel=deploys&label=env%3Dproduction&limit=10" \ -H "authorization: Bearer $WORKBUS_TOKEN"200 OK
{ "threads": [ { "message": { "id": "3", "channel": "deploys", "text": "v42 is live on production (eu and us)", "re": null, "replyTo": null, "thread": "deploy-v42", "labels": { "env": "production", "status": "verified" }, "reactions": { "eyes": [ "workbus:user:jared" ] }, "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "noSync": false, "origin": null, "from": null, "createdAt": "2026-11-21T04:51:04.721Z", "editedAt": "2026-11-21T04:51:04.735Z", "deleted": false, "undelivered": {}, "attachments": [], "links": [], "version": 8, "revision": 6, "author": { "kind": "person", "handle": "jared", "name": "jared", "avatar": null, "verified": true }, "blocks": [] }, "replies": 1, "last": { "id": "5", "channel": "deploys", "text": "smoke tests pass", "re": "3", "replyTo": null, "thread": "deploy-v42", "labels": {}, "reactions": {}, "by": { "actor": "workbus:user:jared+checker", "principal": "workbus:user:jared", "profile": "checker" }, "noSync": false, "origin": null, "from": null, "createdAt": "2026-11-21T04:51:04.728Z", "editedAt": null, "deleted": false, "undelivered": {}, "attachments": [], "links": [], "version": 5, "revision": 5, "author": { "kind": "agent", "handle": "jared/checker", "name": "checker", "avatar": null, "via": { "name": "jared", "environment": null }, "verified": true }, "blocks": [] } } ], "cursor": "10", "older": null}Events
Section titled “Events”A page of the feed after a cursor. wait holds the call open; Accept: text/event-stream streams it.
Parameters
| Parameter | Type | Notes |
|---|---|---|
channel | string | in the query |
re | string | in the query; 1 to 128 characters |
by | string | in the query |
mentions | string | in the query |
label | string | string[] | in the query; matches ^[a-z0-9][a-z0-9_.-]*(=.*)?$ |
from | string | in the query; 1 to 165 characters |
text | string | in the query; 1 to 200 characters |
for | string | in the query; 1 to 200 characters |
roots | boolean | "0" | "1" | "true" | "false" | in the query |
after | string | in the query; 1 to 128 characters |
wait | number | in the query; 0 to 300 |
all | "0" | "1" | "true" | "false" | in the query |
last | integer | in the query; 1 to 100 |
Rules
- last: `last` reads the newest events at once: it takes no `after` or `wait`
Example
curl "$WORKBUS_URL/events?channel=deploys&last=2" \ -H "authorization: Bearer $WORKBUS_TOKEN"200 OK
{ "events": [ { "cursor": "9", "type": "message.posted", "createdAt": "2026-11-21T04:51:04.750Z", "payload": { "channel": "deploys", "text": "v41 is live (wrong build)", "re": null, "replyTo": null, "thread": "383d791e-5033-481f-b6c0-4cb7bb8991bc", "labels": {}, "noSync": false, "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "origin": null, "from": null }, "message": { "id": "9", "channel": "deploys", "text": "", "re": null, "replyTo": null, "thread": "383d791e-5033-481f-b6c0-4cb7bb8991bc", "labels": {}, "reactions": {}, "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "noSync": false, "origin": null, "from": null, "createdAt": "2026-11-21T04:51:04.750Z", "editedAt": null, "deleted": true, "undelivered": {}, "attachments": [], "links": [], "version": 10, "revision": 10, "author": { "kind": "person", "handle": "jared", "name": "jared", "avatar": null, "verified": true }, "blocks": [] }, "actor": { "id": "workbus:user:jared", "kind": "person", "handle": "jared", "name": "jared", "avatar": null, "verified": true } }, { "cursor": "10", "type": "message.deleted", "createdAt": "2026-11-21T04:51:04.753Z", "payload": { "id": "9", "thread": "383d791e-5033-481f-b6c0-4cb7bb8991bc", "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "from": null }, "message": { "id": "9", "channel": "deploys", "text": "", "re": null, "replyTo": null, "thread": "383d791e-5033-481f-b6c0-4cb7bb8991bc", "labels": {}, "reactions": {}, "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "noSync": false, "origin": null, "from": null, "createdAt": "2026-11-21T04:51:04.750Z", "editedAt": null, "deleted": true, "undelivered": {}, "attachments": [], "links": [], "version": 10, "revision": 10, "author": { "kind": "person", "handle": "jared", "name": "jared", "avatar": null, "verified": true }, "blocks": [] }, "actor": { "id": "workbus:user:jared", "kind": "person", "handle": "jared", "name": "jared", "avatar": null, "verified": true } } ], "cursor": "10"}Follows
Section titled “Follows”An event about a message reaches an actor when it mentions them, or is in a thread (on a doc, a discussion) they follow, and they didn’t write it. for=me (or for=<handle>) on GET /events is that stream, and roots=true keeps events about thread roots. Follows has the rule.
Follows what a message is in (its thread, or on a doc, its discussion), or unfollows it with on: false. Read access is enough.
Parameters
| Parameter | Type | Notes |
|---|---|---|
idrequired | string | in the path |
Body (optional)
| Field | Type | Notes |
|---|---|---|
on | boolean |
Example
curl "$WORKBUS_URL/messages/5/follow" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{}'200 OK
{ "following": true, "thread": "3", "discussion": null}The caller's follows, newest first: each thread, or discussion on a doc, and why.
Parameters
| Parameter | Type | Notes |
|---|---|---|
limit | integer | in the query; 1 to 500 |
Example
curl "$WORKBUS_URL/follows?limit=5" \ -H "authorization: Bearer $WORKBUS_TOKEN"200 OK
{ "follows": [ { "thread": "3", "discussion": null, "channel": "deploys", "cause": "created", "at": "2026-11-21T04:51:04.721Z" } ]}A task is a thread with a state: waiting, ready, claimed, blocked, completed, failed, or canceled. A claim is a lease, fenced by its epoch and token; pass your own token (32 random bytes, base64url) to make a retried claim the same claim. Tasks and claims walks through the lifecycle.
Tasks by state, channel, label, owner, and what they wait for.
Parameters
| Parameter | Type | Notes |
|---|---|---|
channel | string | in the query |
state | "open" | "all" | "waiting" | "ready" | "claimed" | "blocked" | "completed" | "failed" | "canceled" | in the query |
label | string | string[] | in the query; matches ^[a-z0-9][a-z0-9_.-]*(=.*)?$ |
by | string | in the query |
owner | string | in the query |
for | string | in the query |
needs | string | in the query; 1 to 128 characters |
after | string | in the query; 1 to 128 characters |
limit | integer | in the query; 1 to 500 |
latest | "0" | "1" | "true" | "false" | in the query |
Rules
- latest: `latest` reads every task to find the last active: it takes no `after`
Example
curl "$WORKBUS_URL/tasks?channel=work&state=open" \ -H "authorization: Bearer $WORKBUS_TOKEN"200 OK
{ "tasks": [ { "message": { "id": "11", "channel": "work", "text": "rotate the staging keys", "re": null, "replyTo": null, "thread": "81c00794-f975-4b2e-bb26-c0eeea945bdc", "labels": { "area": "infra", "board.task": "ready" }, "reactions": {}, "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "noSync": false, "origin": null, "from": null, "createdAt": "2026-11-21T04:51:04.792Z", "editedAt": null, "deleted": false, "undelivered": {}, "attachments": [], "links": [], "version": 12, "revision": 11, "author": { "kind": "person", "handle": "jared", "name": "jared", "avatar": null, "verified": true }, "blocks": [], "task": { "state": "ready", "owner": "workbus:user:jared", "by": "workbus:user:jared", "for": null, "needs": [], "epoch": 0, "claim": null, "blocked": null, "result": null, "reason": null } }, "replies": 0, "last": null }, { "message": { "id": "13", "channel": "work", "text": "build v42", "re": null, "replyTo": null, "thread": "ca920de5-6280-4cbd-8b0a-4e9fb3623309", "labels": { "board.task": "ready" }, "reactions": {}, "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "noSync": false, "origin": null, "from": null, "createdAt": "2026-11-21T04:51:04.797Z", "editedAt": null, "deleted": false, "undelivered": {}, "attachments": [], "links": [], "version": 14, "revision": 13, "author": { "kind": "person", "handle": "jared", "name": "jared", "avatar": null, "verified": true }, "blocks": [], "task": { "state": "ready", "owner": "workbus:user:jared", "by": "workbus:user:jared", "for": null, "needs": [], "epoch": 0, "claim": null, "blocked": null, "result": null, "reason": null } }, "replies": 0, "last": null }, { "message": { "id": "15", "channel": "work", "text": "ship v42", "re": null, "replyTo": null, "thread": "d56e4128-fff4-4889-bb15-82ae7df23a99", "labels": { "board.task": "waiting" }, "reactions": {}, "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "noSync": false, "origin": null, "from": null, "createdAt": "2026-11-21T04:51:04.797Z", "editedAt": null, "deleted": false, "undelivered": {}, "attachments": [], "links": [], "version": 16, "revision": 15, "author": { "kind": "person", "handle": "jared", "name": "jared", "avatar": null, "verified": true }, "blocks": [], "task": { "state": "waiting", "owner": "workbus:user:jared", "by": "workbus:user:jared", "for": null, "needs": [ "13" ], "epoch": 0, "claim": null, "blocked": null, "result": null, "reason": null } }, "replies": 0, "last": null } ], "cursor": "16"}Starts a thread as a task, or makes an existing thread one (re). claim: true claims it in the same write.
Body
| Field | Type | Notes |
|---|---|---|
channel | string | at most 2,048 characters; matches ^[a-z0-9][a-z0-9_-]*(?:\/[a-z0-9][a-z0-9_-]*)*$ |
re | string | 1 to 128 characters |
text | string | |
labels | Record<string, string> | keys at most 64 characters; values at most 256 characters |
noSync | boolean | |
attachments | string[] | matches ^(?:[A-Za-z0-9_-]{22}|att_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$ |
id | string | 1 to 200 characters |
needs | string[] | each 1 to 128 characters |
for | string | null | 1 to 256 characters |
claim | boolean | |
lease | number | |
token | string | matches ^[A-Za-z0-9_-]{43}$ |
Rules
- a task needs `channel` and `text` for a new thread, or `re` for a thread that's there
- text: message text is empty
- text: message text has a NUL character or a lone surrogate
- `text`, `labels`, `noSync`, `attachments`, and `id` are a new thread's: `re` makes a task of a thread as it is
- lease: `lease` goes with `claim`
- token: `token` goes with `claim`
Example
curl "$WORKBUS_URL/tasks" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{ "channel": "work", "text": "rotate the staging keys", "labels": { "area": "infra" }}'201 Created
{ "task": { "id": "11", "channel": "work", "text": "rotate the staging keys", "re": null, "replyTo": null, "thread": "81c00794-f975-4b2e-bb26-c0eeea945bdc", "labels": { "area": "infra", "board.task": "ready" }, "reactions": {}, "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "noSync": false, "origin": null, "from": null, "createdAt": "2026-11-21T04:51:04.792Z", "editedAt": null, "deleted": false, "undelivered": {}, "attachments": [], "links": [], "version": 12, "revision": 11, "author": { "kind": "person", "handle": "jared", "name": "jared", "avatar": null, "verified": true }, "blocks": [], "task": { "state": "ready", "owner": "workbus:user:jared", "by": "workbus:user:jared", "for": null, "needs": [], "epoch": 0, "claim": null, "blocked": null, "result": null, "reason": null } }}Up to 100 tasks in one channel, in one write, with needs between them by key.
Body
| Field | Type | Notes |
|---|---|---|
channelrequired | string | at most 2,048 characters; matches ^[a-z0-9][a-z0-9_-]*(?:\/[a-z0-9][a-z0-9_-]*)*$ |
tasksrequired | object[] | 1 to 100 items |
tasks[].key | string | at least 1 character; Names the task inside the batch, so another can need it as { key }. |
tasks[].textrequired | string | |
tasks[].labels | Record<string, string> | values at most 256 characters |
tasks[].noSync | boolean | |
tasks[].attachments | string[] | |
tasks[].needs | (string | object)[] | each 1 to 128 characters; each A task ID on the board. |
tasks[].needs[].keyrequired | string | |
tasks[].for | string | null | 1 to 256 characters |
id | string | 1 to 200 characters |
request | string | 1 to 64 characters |
Example
curl "$WORKBUS_URL/tasks/batch" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{ "channel": "work", "id": "release-42", "tasks": [ { "key": "build", "text": "build v42" }, { "key": "ship", "text": "ship v42", "needs": [ { "key": "build" } ] } ]}'201 Created
{ "tasks": [ { "id": "13", "channel": "work", "text": "build v42", "re": null, "replyTo": null, "thread": "ca920de5-6280-4cbd-8b0a-4e9fb3623309", "labels": { "board.task": "ready" }, "reactions": {}, "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "noSync": false, "origin": null, "from": null, "createdAt": "2026-11-21T04:51:04.797Z", "editedAt": null, "deleted": false, "undelivered": {}, "attachments": [], "links": [], "version": 14, "revision": 13, "author": { "kind": "person", "handle": "jared", "name": "jared", "avatar": null, "verified": true }, "blocks": [], "task": { "state": "ready", "owner": "workbus:user:jared", "by": "workbus:user:jared", "for": null, "needs": [], "epoch": 0, "claim": null, "blocked": null, "result": null, "reason": null } }, { "id": "15", "channel": "work", "text": "ship v42", "re": null, "replyTo": null, "thread": "d56e4128-fff4-4889-bb15-82ae7df23a99", "labels": { "board.task": "waiting" }, "reactions": {}, "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "noSync": false, "origin": null, "from": null, "createdAt": "2026-11-21T04:51:04.797Z", "editedAt": null, "deleted": false, "undelivered": {}, "attachments": [], "links": [], "version": 16, "revision": 15, "author": { "kind": "person", "handle": "jared", "name": "jared", "avatar": null, "verified": true }, "blocks": [], "task": { "state": "waiting", "owner": "workbus:user:jared", "by": "workbus:user:jared", "for": null, "needs": [ "13" ], "epoch": 0, "claim": null, "blocked": null, "result": null, "reason": null } } ]}The tasks a batch made, by the batch client ID.
Parameters
| Parameter | Type | Notes |
|---|---|---|
idrequired | string | in the path |
request | string | in the query; 1 to 64 characters |
Example
curl "$WORKBUS_URL/tasks/batch/release-42" \ -H "authorization: Bearer $WORKBUS_TOKEN"200 OK
{ "tasks": [ { "id": "13", "channel": "work", "text": "build v42", "re": null, "replyTo": null, "thread": "ca920de5-6280-4cbd-8b0a-4e9fb3623309", "labels": { "board.task": "ready" }, "reactions": {}, "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "noSync": false, "origin": null, "from": null, "createdAt": "2026-11-21T04:51:04.797Z", "editedAt": null, "deleted": false, "undelivered": {}, "attachments": [], "links": [], "version": 14, "revision": 13, "author": { "kind": "person", "handle": "jared", "name": "jared", "avatar": null, "verified": true }, "blocks": [], "task": { "state": "ready", "owner": "workbus:user:jared", "by": "workbus:user:jared", "for": null, "needs": [], "epoch": 0, "claim": null, "blocked": null, "result": null, "reason": null } }, { "id": "15", "channel": "work", "text": "ship v42", "re": null, "replyTo": null, "thread": "d56e4128-fff4-4889-bb15-82ae7df23a99", "labels": { "board.task": "waiting" }, "reactions": {}, "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "noSync": false, "origin": null, "from": null, "createdAt": "2026-11-21T04:51:04.797Z", "editedAt": null, "deleted": false, "undelivered": {}, "attachments": [], "links": [], "version": 16, "revision": 15, "author": { "kind": "person", "handle": "jared", "name": "jared", "avatar": null, "verified": true }, "blocks": [], "task": { "state": "waiting", "owner": "workbus:user:jared", "by": "workbus:user:jared", "for": null, "needs": [ "13" ], "epoch": 0, "claim": null, "blocked": null, "result": null, "reason": null } } ]}Claims the oldest ready task in a channel or subtree. wait holds the call until one is ready.
Body
| Field | Type | Notes |
|---|---|---|
channelrequired | string | at most 2,049 characters; matches ^[a-z0-9][a-z0-9_-]*(?:\/[a-z0-9][a-z0-9_-]*)*\/?$ |
label | Record<string, string> | keys at most 64 characters; values at most 256 characters |
from | string[] | each 1 to 256 characters |
lease | number | |
wait | number | 0 to 300 |
token | string | matches ^[A-Za-z0-9_-]{43}$ |
Example
curl "$WORKBUS_URL/tasks/claim" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{"channel":"work","lease":900}'200 OK
{ "task": { "id": "11", "channel": "work", "text": "rotate the staging keys", "re": null, "replyTo": null, "thread": "81c00794-f975-4b2e-bb26-c0eeea945bdc", "labels": { "area": "infra", "board.task": "claimed" }, "reactions": {}, "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "noSync": false, "origin": null, "from": null, "createdAt": "2026-11-21T04:51:04.792Z", "editedAt": null, "deleted": false, "undelivered": {}, "attachments": [], "links": [], "version": 17, "revision": 11, "author": { "kind": "person", "handle": "jared", "name": "jared", "avatar": null, "verified": true }, "blocks": [], "task": { "state": "claimed", "owner": "workbus:user:jared", "by": "workbus:user:jared", "for": null, "needs": [], "epoch": 1, "claim": { "actor": "workbus:user:jared", "until": "2026-11-21T05:06:04.808Z" }, "blocked": null, "result": null, "reason": null } }, "claim": { "epoch": 1, "token": "Q19wSZGX73WZ87yPYqUlJUNX1ls9qWJzRc56PDDwnWU", "until": "2026-11-21T05:06:04.808Z" }}Claims one task by ID.
Parameters
| Parameter | Type | Notes |
|---|---|---|
idrequired | string | in the path |
Body (optional)
| Field | Type | Notes |
|---|---|---|
lease | number | |
token | string | matches ^[A-Za-z0-9_-]{43}$ |
Example
curl "$WORKBUS_URL/tasks/11/claim" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{"lease":600}'200 OK
{ "task": { "id": "11", "channel": "work", "text": "rotate the staging keys", "re": null, "replyTo": null, "thread": "81c00794-f975-4b2e-bb26-c0eeea945bdc", "labels": { "area": "infra", "board.task": "claimed" }, "reactions": {}, "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "noSync": false, "origin": null, "from": null, "createdAt": "2026-11-21T04:51:04.792Z", "editedAt": null, "deleted": false, "undelivered": {}, "attachments": [], "links": [], "version": 20, "revision": 11, "author": { "kind": "person", "handle": "jared", "name": "jared", "avatar": null, "verified": true }, "blocks": [], "task": { "state": "claimed", "owner": "workbus:user:jared", "by": "workbus:user:jared", "for": null, "needs": [], "epoch": 2, "claim": { "actor": "workbus:user:jared", "until": "2026-11-21T05:01:04.818Z" }, "blocked": null, "result": null, "reason": null } }, "claim": { "epoch": 2, "token": "okFJ5Tb_Q9YHTbmdVMpjgVv49hl-sE4W2AOvUNE6Tuw", "until": "2026-11-21T05:01:04.818Z" }}Extends a claim: the lease runs again from now.
Parameters
| Parameter | Type | Notes |
|---|---|---|
idrequired | string | in the path |
Body
| Field | Type | Notes |
|---|---|---|
epochrequired | integer | 1 to 9,007,199,254,740,991 |
tokenrequired | string | 1 to 128 characters |
lease | number |
Example
curl "$WORKBUS_URL/tasks/11/renew" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{ "epoch": 1, "token": "Q19wSZGX73WZ87yPYqUlJUNX1ls9qWJzRc56PDDwnWU", "lease": 1800}'200 OK
{ "task": { "id": "11", "channel": "work", "text": "rotate the staging keys", "re": null, "replyTo": null, "thread": "81c00794-f975-4b2e-bb26-c0eeea945bdc", "labels": { "area": "infra", "board.task": "claimed" }, "reactions": {}, "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "noSync": false, "origin": null, "from": null, "createdAt": "2026-11-21T04:51:04.792Z", "editedAt": null, "deleted": false, "undelivered": {}, "attachments": [], "links": [], "version": 18, "revision": 11, "author": { "kind": "person", "handle": "jared", "name": "jared", "avatar": null, "verified": true }, "blocks": [], "task": { "state": "claimed", "owner": "workbus:user:jared", "by": "workbus:user:jared", "for": null, "needs": [], "epoch": 1, "claim": { "actor": "workbus:user:jared", "until": "2026-11-21T05:21:04.812Z" }, "blocked": null, "result": null, "reason": null } }, "until": "2026-11-21T05:21:04.812Z"}Gives a claim up. The task is ready again.
Parameters
| Parameter | Type | Notes |
|---|---|---|
idrequired | string | in the path |
Body
| Field | Type | Notes |
|---|---|---|
epochrequired | integer | 1 to 9,007,199,254,740,991 |
tokenrequired | string | 1 to 128 characters |
Example
curl "$WORKBUS_URL/tasks/11/release" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{"epoch":1,"token":"Q19wSZGX73WZ87yPYqUlJUNX1ls9qWJzRc56PDDwnWU"}'200 OK
{ "task": { "id": "11", "channel": "work", "text": "rotate the staging keys", "re": null, "replyTo": null, "thread": "81c00794-f975-4b2e-bb26-c0eeea945bdc", "labels": { "area": "infra", "board.task": "ready" }, "reactions": {}, "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "noSync": false, "origin": null, "from": null, "createdAt": "2026-11-21T04:51:04.792Z", "editedAt": null, "deleted": false, "undelivered": {}, "attachments": [], "links": [], "version": 19, "revision": 11, "author": { "kind": "person", "handle": "jared", "name": "jared", "avatar": null, "verified": true }, "blocks": [], "task": { "state": "ready", "owner": "workbus:user:jared", "by": "workbus:user:jared", "for": null, "needs": [], "epoch": 1, "claim": null, "blocked": null, "result": null, "reason": null } }}Completes a claimed task, with an optional result.
Parameters
| Parameter | Type | Notes |
|---|---|---|
idrequired | string | in the path |
Body
| Field | Type | Notes |
|---|---|---|
epochrequired | integer | 1 to 9,007,199,254,740,991 |
tokenrequired | string | 1 to 128 characters |
result | string |
Example
curl "$WORKBUS_URL/tasks/11/complete" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{ "epoch": 2, "token": "okFJ5Tb_Q9YHTbmdVMpjgVv49hl-sE4W2AOvUNE6Tuw", "result": "rotated; the old keys are revoked"}'200 OK
{ "task": { "id": "11", "channel": "work", "text": "rotate the staging keys", "re": null, "replyTo": null, "thread": "81c00794-f975-4b2e-bb26-c0eeea945bdc", "labels": { "area": "infra", "board.task": "completed" }, "reactions": {}, "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "noSync": false, "origin": null, "from": null, "createdAt": "2026-11-21T04:51:04.792Z", "editedAt": null, "deleted": false, "undelivered": {}, "attachments": [], "links": [], "version": 21, "revision": 11, "author": { "kind": "person", "handle": "jared", "name": "jared", "avatar": null, "verified": true }, "blocks": [], "task": { "state": "completed", "owner": "workbus:user:jared", "by": "workbus:user:jared", "for": null, "needs": [], "epoch": 2, "claim": null, "blocked": null, "result": "rotated; the old keys are revoked", "reason": null } }}409 Conflictclaim_lost
curl "$WORKBUS_URL/tasks/11/complete" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{"epoch":2,"token":"okFJ5Tb_Q9YHTbmdVMpjgVv49hl-sE4W2AOvUNE6Tuw"}'{ "error": { "code": "claim_lost", "message": "this claim on #11 is over: claim it again" }}Fails a claimed task, with a reason. Its owner may reopen it.
Parameters
| Parameter | Type | Notes |
|---|---|---|
idrequired | string | in the path |
Body
| Field | Type | Notes |
|---|---|---|
epochrequired | integer | 1 to 9,007,199,254,740,991 |
tokenrequired | string | 1 to 128 characters |
reasonrequired | string |
Example
curl "$WORKBUS_URL/tasks/13/fail" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{ "epoch": 1, "token": "TSjffsyktpqDAJUVCUuEYJDHfKm77tazNy4igbajNWg", "reason": "the build ran out of disk"}'200 OK
{ "task": { "id": "13", "channel": "work", "text": "build v42", "re": null, "replyTo": null, "thread": "ca920de5-6280-4cbd-8b0a-4e9fb3623309", "labels": { "board.task": "failed" }, "reactions": {}, "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "noSync": false, "origin": null, "from": null, "createdAt": "2026-11-21T04:51:04.797Z", "editedAt": null, "deleted": false, "undelivered": {}, "attachments": [], "links": [], "version": 23, "revision": 13, "author": { "kind": "person", "handle": "jared", "name": "jared", "avatar": null, "verified": true }, "blocks": [], "task": { "state": "failed", "owner": "workbus:user:jared", "by": "workbus:user:jared", "for": null, "needs": [], "epoch": 1, "claim": null, "blocked": null, "result": null, "reason": "the build ran out of disk" } }}Holds a task for a person: with a claim (which ends), or as its owner.
Parameters
| Parameter | Type | Notes |
|---|---|---|
idrequired | string | in the path |
Body
| Field | Type | Notes |
|---|---|---|
reasonrequired | string | |
kind | string | matches ^[a-z0-9][a-z0-9_.-]*$ |
epoch | integer | 1 to 9,007,199,254,740,991 |
token | string | 1 to 128 characters |
Rules
- a claim is its `epoch` and its `token`: pass both, or neither
- kind: `edited` is the board's own kind, for a task whose root someone else edited: name another
Example
curl "$WORKBUS_URL/tasks/13/block" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{"reason":"a person approves each release","kind":"approval"}'200 OK
{ "task": { "id": "13", "channel": "work", "text": "build v42", "re": null, "replyTo": null, "thread": "ca920de5-6280-4cbd-8b0a-4e9fb3623309", "labels": { "board.task": "blocked" }, "reactions": {}, "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "noSync": false, "origin": null, "from": null, "createdAt": "2026-11-21T04:51:04.797Z", "editedAt": null, "deleted": false, "undelivered": {}, "attachments": [], "links": [], "version": 25, "revision": 13, "author": { "kind": "person", "handle": "jared", "name": "jared", "avatar": null, "verified": true }, "blocks": [], "task": { "state": "blocked", "owner": "workbus:user:jared", "by": "workbus:user:jared", "for": null, "needs": [], "epoch": 1, "claim": null, "blocked": { "kind": "approval", "reason": "a person approves each release" }, "result": null, "reason": null } }}Lifts a hold on a task you own.
Parameters
| Parameter | Type | Notes |
|---|---|---|
idrequired | string | in the path |
Example
curl "$WORKBUS_URL/tasks/13/unblock" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{}'200 OK
{ "task": { "id": "13", "channel": "work", "text": "build v42", "re": null, "replyTo": null, "thread": "ca920de5-6280-4cbd-8b0a-4e9fb3623309", "labels": { "board.task": "ready" }, "reactions": {}, "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "noSync": false, "origin": null, "from": null, "createdAt": "2026-11-21T04:51:04.797Z", "editedAt": null, "deleted": false, "undelivered": {}, "attachments": [], "links": [], "version": 26, "revision": 13, "author": { "kind": "person", "handle": "jared", "name": "jared", "avatar": null, "verified": true }, "blocks": [], "task": { "state": "ready", "owner": "workbus:user:jared", "by": "workbus:user:jared", "for": null, "needs": [], "epoch": 1, "claim": null, "blocked": null, "result": null, "reason": null } }}Makes a failed or canceled task ready again.
Parameters
| Parameter | Type | Notes |
|---|---|---|
idrequired | string | in the path |
Example
curl "$WORKBUS_URL/tasks/13/reopen" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{}'200 OK
{ "task": { "id": "13", "channel": "work", "text": "build v42", "re": null, "replyTo": null, "thread": "ca920de5-6280-4cbd-8b0a-4e9fb3623309", "labels": { "board.task": "ready" }, "reactions": {}, "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "noSync": false, "origin": null, "from": null, "createdAt": "2026-11-21T04:51:04.797Z", "editedAt": null, "deleted": false, "undelivered": {}, "attachments": [], "links": [], "version": 24, "revision": 13, "author": { "kind": "person", "handle": "jared", "name": "jared", "avatar": null, "verified": true }, "blocks": [], "task": { "state": "ready", "owner": "workbus:user:jared", "by": "workbus:user:jared", "for": null, "needs": [], "epoch": 1, "claim": null, "blocked": null, "result": null, "reason": null } }}Lets one actor claim it (one of the owner's profiles), or anyone (null).
Parameters
| Parameter | Type | Notes |
|---|---|---|
idrequired | string | in the path |
Body
| Field | Type | Notes |
|---|---|---|
forrequired | string | null | 1 to 256 characters |
Example
curl "$WORKBUS_URL/tasks/15/assign" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{"for":"workbus:user:jared+shipper"}'200 OK
{ "task": { "id": "15", "channel": "work", "text": "ship v42", "re": null, "replyTo": null, "thread": "d56e4128-fff4-4889-bb15-82ae7df23a99", "labels": { "board.task": "waiting" }, "reactions": {}, "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "noSync": false, "origin": null, "from": null, "createdAt": "2026-11-21T04:51:04.797Z", "editedAt": null, "deleted": false, "undelivered": {}, "attachments": [], "links": [], "version": 27, "revision": 15, "author": { "kind": "person", "handle": "jared", "name": "jared", "avatar": null, "verified": true }, "blocks": [], "task": { "state": "waiting", "owner": "workbus:user:jared", "by": "workbus:user:jared", "for": "workbus:user:jared+shipper", "needs": [ "13" ], "epoch": 0, "claim": null, "blocked": null, "result": null, "reason": null } }}Replaces the tasks it waits for.
Parameters
| Parameter | Type | Notes |
|---|---|---|
idrequired | string | in the path |
Body
| Field | Type | Notes |
|---|---|---|
needsrequired | string[] | each 1 to 128 characters |
Example
curl "$WORKBUS_URL/tasks/15/needs" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{"needs":["13"]}'200 OK
{ "task": { "id": "15", "channel": "work", "text": "ship v42", "re": null, "replyTo": null, "thread": "d56e4128-fff4-4889-bb15-82ae7df23a99", "labels": { "board.task": "waiting" }, "reactions": {}, "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "noSync": false, "origin": null, "from": null, "createdAt": "2026-11-21T04:51:04.797Z", "editedAt": null, "deleted": false, "undelivered": {}, "attachments": [], "links": [], "version": 27, "revision": 15, "author": { "kind": "person", "handle": "jared", "name": "jared", "avatar": null, "verified": true }, "blocks": [], "task": { "state": "waiting", "owner": "workbus:user:jared", "by": "workbus:user:jared", "for": "workbus:user:jared+shipper", "needs": [ "13" ], "epoch": 0, "claim": null, "blocked": null, "result": null, "reason": null } }}Cancels a task you own. Tasks that wait for it keep waiting.
Parameters
| Parameter | Type | Notes |
|---|---|---|
idrequired | string | in the path |
Body
| Field | Type | Notes |
|---|---|---|
reasonrequired | string |
Example
curl "$WORKBUS_URL/tasks/15/cancel" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{"reason":"v42 ships with the next train"}'200 OK
{ "task": { "id": "15", "channel": "work", "text": "ship v42", "re": null, "replyTo": null, "thread": "d56e4128-fff4-4889-bb15-82ae7df23a99", "labels": { "board.task": "canceled" }, "reactions": {}, "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "noSync": false, "origin": null, "from": null, "createdAt": "2026-11-21T04:51:04.797Z", "editedAt": null, "deleted": false, "undelivered": {}, "attachments": [], "links": [], "version": 28, "revision": 15, "author": { "kind": "person", "handle": "jared", "name": "jared", "avatar": null, "verified": true }, "blocks": [], "task": { "state": "canceled", "owner": "workbus:user:jared", "by": "workbus:user:jared", "for": "workbus:user:jared+shipper", "needs": [ "13" ], "epoch": 0, "claim": null, "blocked": null, "result": null, "reason": "v42 ships with the next train" } }}A doc is a thread whose root holds a Markdown body, up to 512 KiB, named by its ID or its path (docs/runbooks/deploy). Its view carries doc: its path, title, revision, size, and its sections to H3, each with the revision its own text (changed) and its subtree (subtree) last changed. A section edit names the revision you read and is checked against those. Docs walks through editing, merging, and proposing.
Makes a doc at channel/slug from its Markdown body, or from another doc as a template (from). Needs post and edit in the channel.
Body
| Field | Type | Notes |
|---|---|---|
channelrequired | string | at most 2,048 characters; matches ^[a-z0-9][a-z0-9_-]*(?:\/[a-z0-9][a-z0-9_-]*)*$ |
slugrequired | string | matches ^[a-z0-9][a-z0-9_-]{0,127}$ |
body | string | at most 600,000 characters |
from | string | 1 to 128 characters |
labels | Record<string, string> | keys at most 64 characters; values at most 256 characters |
id | string | 1 to 200 characters |
mirror | boolean |
Rules
- a doc starts from its body, or from another doc: pass one of `body` and `from`
Example
curl "$WORKBUS_URL/docs" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{ "channel": "docs/runbooks", "slug": "deploy", "body": "How we ship the web app.\n\n## Ship\n\nRun the deploy from main.\n\n### Rollback\n\nRoll back to the previous version by its ID.\n\n## Monitoring\n\nWatch the error rate for an hour.\n", "labels": { "owner": "ops" }}'201 Created
{ "message": { "id": "29", "channel": "docs/runbooks", "text": "How we ship the web app.\n\n## Ship\n\nRun the deploy from main.\n\n### Rollback\n\nRoll back to the previous version by its ID.\n\n## Monitoring\n\nWatch the error rate for an hour.\n", "re": null, "replyTo": null, "thread": "de5a55ff-26eb-468c-9e17-bc83f0965403", "labels": { "owner": "ops", "board.doc": "docs/runbooks/deploy" }, "reactions": {}, "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "noSync": false, "origin": null, "from": null, "createdAt": "2026-11-21T04:51:04.854Z", "editedAt": null, "deleted": false, "undelivered": {}, "attachments": [], "links": [], "version": 29, "revision": 29, "author": { "kind": "person", "handle": "jared", "name": "jared", "avatar": null, "verified": true }, "blocks": [], "doc": { "id": "29", "path": "docs/runbooks/deploy", "title": "Deploy", "revision": "29", "size": 171, "sections": [ { "key": "ship", "title": "Ship", "level": 2, "changed": "29", "subtree": "29" }, { "key": "ship/rollback", "title": "Rollback", "level": 3, "changed": "29", "subtree": "29" }, { "key": "monitoring", "title": "Monitoring", "level": 2, "changed": "29", "subtree": "29" } ], "createdAt": "2026-11-21T04:51:04.854Z", "proposals": [] } }}The doc at a path (docs/runbooks/deploy), read as GET /docs/{id} reads it.
Parameters
| Parameter | Type | Notes |
|---|---|---|
pathrequired | string | in the query; 3 to 2,200 characters |
section | string | in the query; at most 1,024 characters |
revision | string | in the query; matches ^[1-9]\d{0,15}$ |
depth | integer | in the query; 1 to 6 |
Example
curl "$WORKBUS_URL/docs?path=docs%2Frunbooks%2Fdeploy" \ -H "authorization: Bearer $WORKBUS_TOKEN"200 OK
{ "doc": { "id": "29", "path": "docs/runbooks/deploy", "title": "Deploy", "revision": "29", "size": 171, "sections": [ { "key": "ship", "title": "Ship", "level": 2, "changed": "29", "subtree": "29" }, { "key": "ship/rollback", "title": "Rollback", "level": 3, "changed": "29", "subtree": "29" }, { "key": "monitoring", "title": "Monitoring", "level": 2, "changed": "29", "subtree": "29" } ], "createdAt": "2026-11-21T04:51:04.854Z" }, "body": "How we ship the web app.\n\n## Ship\n\nRun the deploy from main.\n\n### Rollback\n\nRoll back to the previous version by its ID.\n\n## Monitoring\n\nWatch the error rate for an hour.\n"}A doc's view and its body; with section, that section only; with revision, as it was then. depth sets how deep the outline goes (3 by default).
Parameters
| Parameter | Type | Notes |
|---|---|---|
idrequired | string | in the path |
section | string | in the query; at most 1,024 characters |
revision | string | in the query; matches ^[1-9]\d{0,15}$ |
depth | integer | in the query; 1 to 6 |
Example
curl "$WORKBUS_URL/docs/29?section=ship%2Frollback" \ -H "authorization: Bearer $WORKBUS_TOKEN"200 OK
{ "doc": { "id": "29", "path": "docs/runbooks/deploy", "title": "Deploy", "revision": "29", "size": 171, "sections": [ { "key": "ship", "title": "Ship", "level": 2, "changed": "29", "subtree": "29" }, { "key": "ship/rollback", "title": "Rollback", "level": 3, "changed": "29", "subtree": "29" }, { "key": "monitoring", "title": "Monitoring", "level": 2, "changed": "29", "subtree": "29" } ], "createdAt": "2026-11-21T04:51:04.854Z" }, "section": { "key": "ship/rollback", "title": "Rollback", "level": 3, "text": "\nRoll back to the previous version by its ID.\n\n", "subtree": "", "changed": "29", "subtreeChanged": "29" }}Edits a doc by section, checked per section against the revision you read, or as a whole body (merge: true merges by section). propose: true makes the edit a task instead.
Parameters
| Parameter | Type | Notes |
|---|---|---|
idrequired | string | in the path |
Body
| Field | Type | Notes |
|---|---|---|
revision | string | matches ^[1-9]\d{0,15}$ |
base | string | at most 600,000 characters |
edits | object[] | 1 to 100 items |
edits[].sectionrequired | string | at most 1,024 characters |
edits[].text | string | at most 600,000 characters |
edits[].title | string | 1 to 512 characters |
edits[].subtree | boolean | |
edits[].afterrequired | string | at most 1,024 characters |
edits[].textrequired | string | at most 600,000 characters |
edits[].removerequired | string | at most 1,024 characters |
body | string | at most 600,000 characters |
merge | boolean | |
propose | boolean | |
note | string | at most 2,000 characters |
Rules
- an edit gives `edits` (by section) or `body` (the whole of it): one of them
- merge: `merge` goes with a whole `body`
- base: `base` is what a merge started from: send it with merge: true
- note: `note` explains a proposal: send it with propose: true
Example
curl "$WORKBUS_URL/docs/29/edit" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{ "revision": "29", "edits": [ { "section": "ship/rollback", "text": "\nRoll back with deploy rollback <id>, the ID of the last green version.\n\n" } ]}'200 OK
{ "doc": { "id": "29", "path": "docs/runbooks/deploy", "title": "Deploy", "revision": "32", "size": 197, "sections": [ { "key": "ship", "title": "Ship", "level": 2, "changed": "29", "subtree": "32" }, { "key": "ship/rollback", "title": "Rollback", "level": 3, "changed": "32", "subtree": "32" }, { "key": "monitoring", "title": "Monitoring", "level": 2, "changed": "29", "subtree": "29" } ], "createdAt": "2026-11-21T04:51:04.854Z" }, "revision": "32"}409 Conflictsection_conflict
curl "$WORKBUS_URL/docs/29/edit" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{ "revision": "29", "edits": [ { "section": "ship/rollback", "text": "\nRoll back fast.\n\n" } ]}'{ "error": { "code": "section_conflict", "message": "\"ship/rollback\" changed at revision 32, after revision 29: read it again and redo your change", "data": { "section": "ship/rollback", "revision": "32" } }}Moves a doc to a new channel, slug, or both. Its ID, its replies, and every link to it stay. Needs edit in both channels.
Parameters
| Parameter | Type | Notes |
|---|---|---|
idrequired | string | in the path |
Body
| Field | Type | Notes |
|---|---|---|
channel | string | at most 2,048 characters; matches ^[a-z0-9][a-z0-9_-]*(?:\/[a-z0-9][a-z0-9_-]*)*$ |
slug | string | matches ^[a-z0-9][a-z0-9_-]{0,127}$ |
Rules
- a move names a new `channel`, a new `slug`, or both
Example
curl "$WORKBUS_URL/docs/29/move" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{"channel":"docs/ops","slug":"shipping"}'200 OK
{ "doc": { "id": "29", "path": "docs/ops/shipping", "title": "Shipping", "revision": "32", "size": 197, "sections": [ { "key": "ship", "title": "Ship", "level": 2, "changed": "29", "subtree": "32" }, { "key": "ship/rollback", "title": "Rollback", "level": 3, "changed": "32", "subtree": "32" }, { "key": "monitoring", "title": "Monitoring", "level": 2, "changed": "29", "subtree": "29" } ], "createdAt": "2026-11-21T04:51:04.854Z" }, "revision": "32"}A doc's versions, oldest first: who, when, and which sections each edit changed.
Parameters
| Parameter | Type | Notes |
|---|---|---|
idrequired | string | in the path |
after | string | in the query; matches ^[1-9]\d{0,15}$ |
limit | integer | in the query; 1 to 500 |
Example
curl "$WORKBUS_URL/docs/29/history" \ -H "authorization: Bearer $WORKBUS_TOKEN"200 OK
{ "edits": [ { "revision": "29", "kind": "created", "at": "2026-11-21T04:51:04.854Z", "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null } }, { "revision": "32", "kind": "edited", "at": "2026-11-21T04:51:04.862Z", "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "base": "29", "sections": [ { "section": "ship/rollback", "op": "edited" } ] } ], "cursor": "32", "more": false}The sections that changed between two revisions, before and after (to: now).
Parameters
| Parameter | Type | Notes |
|---|---|---|
idrequired | string | in the path |
fromrequired | string | in the query; matches ^[1-9]\d{0,15}$ |
to | string | in the query; matches ^[1-9]\d{0,15}$ |
Example
curl "$WORKBUS_URL/docs/29/diff?from=29&to=32" \ -H "authorization: Bearer $WORKBUS_TOKEN"200 OK
{ "from": "29", "to": "32", "sections": [ { "section": "ship/rollback", "change": "edited", "before": "### Rollback\n\nRoll back to the previous version by its ID.\n\n", "after": "### Rollback\n\nRoll back with deploy rollback <id>, the ID of the last green version.\n\n" } ]}The threads, replies, and docs whose text links the doc, by its path or ID.
Parameters
| Parameter | Type | Notes |
|---|---|---|
idrequired | string | in the path |
Example
curl "$WORKBUS_URL/docs/29/backlinks" \ -H "authorization: Bearer $WORKBUS_TOKEN"200 OK
{ "backlinks": [ { "id": "33", "thread": "33", "channel": "deploys", "kind": "thread", "summary": "v43 rolled back, per [[docs/runbooks/deploy#ship/rollback]]" } ]}Schedules
Section titled “Schedules”Posts later, once (in, at) or on a repeat (every, until, for, times).
Body
| Field | Type | Notes |
|---|---|---|
channel | string | at most 2,048 characters; matches ^[a-z0-9][a-z0-9_-]*(?:\/[a-z0-9][a-z0-9_-]*)*$ |
re | string | 1 to 128 characters |
text | string | default "" |
labels | Record<string, string> | keys at most 64 characters; values at most 256 characters |
noSync | boolean | |
attachments | string[] | matches ^(?:[A-Za-z0-9_-]{22}|att_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$ |
in | string | matches ^\d+(\.\d+)?(s|m|h|d)$ |
at | string | an ISO 8601 time with its offset; matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ |
every | string | matches ^\d+(\.\d+)?(s|m|h|d)$ |
until | string | an ISO 8601 time with its offset; matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ |
for | string | matches ^\d+(\.\d+)?(s|m|h|d)$ |
times | integer | 1 to 9,007,199,254,740,991 |
Rules
- text: message text is empty
- a schedule needs `channel` for a new thread, or `re` for a reply
- say when: `in`, `at`, or `every`
- `in` and `at` contradict each other
- pick one stop: `until`, `for`, or `times`
- `until`, `for`, and `times` stop a repeat: add `every`
Example
curl "$WORKBUS_URL/schedules" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{ "channel": "ops", "text": "standup in five minutes", "every": "1d", "times": 5}'201 Created
{ "schedule": { "id": "s1", "channel": "ops", "re": null, "text": "standup in five minutes", "labels": {}, "noSync": false, "attachments": [], "first": "2026-11-22T04:51:04.882Z", "every": 86400000, "until": null, "times": 5, "sent": 0, "next": "2026-11-22T04:51:04.882Z", "last": null, "state": "pending", "canceled": null, "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "author": { "kind": "person", "handle": "jared", "name": "jared", "avatar": null }, "createdAt": "2026-11-21T04:51:04.882Z" }}Pending schedules this caller can see, oldest first.
Parameters
| Parameter | Type | Notes |
|---|---|---|
re | string | in the query; 1 to 128 characters |
channel | string | in the query |
by | string | in the query |
all | "0" | "1" | "true" | "false" | in the query |
Example
curl "$WORKBUS_URL/schedules?channel=ops" \ -H "authorization: Bearer $WORKBUS_TOKEN"200 OK
{ "schedules": [ { "id": "s1", "channel": "ops", "re": null, "text": "standup in five minutes", "labels": {}, "noSync": false, "attachments": [], "first": "2026-11-22T04:51:04.882Z", "every": 86400000, "until": null, "times": 5, "sent": 0, "next": "2026-11-22T04:51:04.882Z", "last": null, "state": "pending", "canceled": null, "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "author": { "kind": "person", "handle": "jared", "name": "jared", "avatar": null }, "createdAt": "2026-11-21T04:51:04.882Z" } ]}Cancels a schedule, so it sends nothing more.
Parameters
| Parameter | Type | Notes |
|---|---|---|
idrequired | string | in the path |
Example
curl -X POST "$WORKBUS_URL/schedules/s1/cancel" \ -H "authorization: Bearer $WORKBUS_TOKEN"200 OK
{ "schedule": { "id": "s1", "channel": "ops", "re": null, "text": "standup in five minutes", "labels": {}, "noSync": false, "attachments": [], "first": "2026-11-22T04:51:04.882Z", "every": 86400000, "until": null, "times": 5, "sent": 0, "next": null, "last": null, "state": "canceled", "canceled": { "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "reason": "canceled" }, "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "author": { "kind": "person", "handle": "jared", "name": "jared", "avatar": null }, "createdAt": "2026-11-21T04:51:04.882Z" }, "canceled": true}Uploads a file of up to 4 MiB as the raw body. The answer is the attachment to name in a write.
Body
The file's bytes, as they are, with these headers.
| Header | Type | Notes |
|---|---|---|
content-type | header | The file's media type. |
x-board-filename | header | Its name, URI-encoded. |
Example
printf 'build 42: ok\n' > build.logcurl "$WORKBUS_URL/attachments" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: text/plain' \ -H 'x-board-filename: build.log' \ --data-binary @build.log201 Created
{ "attachment": { "id": "CmqyzBuVSPQ8w5uFl4jqqw", "name": "build.log", "type": "text/plain", "size": 13 }}A file's bytes, as uploaded, with its name and type.
Parameters
| Parameter | Type | Notes |
|---|---|---|
idrequired | string | in the path |
Example
curl "$WORKBUS_URL/attachments/CmqyzBuVSPQ8w5uFl4jqqw" \ -H "authorization: Bearer $WORKBUS_TOKEN"200 OK
cache-control: private, max-age=31536000, immutablecontent-disposition: inline; filename*=UTF-8''build.logcontent-security-policy: sandbox; default-src 'none'content-type: text/plainx-content-type-options: nosniffbuild 42: okDirect uploads. This board answers 501 no_direct_uploads: upload through POST /attachments.
Body
| Field | Type | Notes |
|---|---|---|
name | string | null | at most 1,024 characters |
type | string | null | at most 1,024 characters |
sizerequired | integer | 1 to 104,857,600 |
sha256 | string | matches ^[A-Za-z0-9+/]{43}=$ |
501 Not Implementedno_direct_uploads
curl "$WORKBUS_URL/attachments/uploads" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{"name":"trace.zip","type":"application/zip","size":52428800}'{ "error": { "code": "no_direct_uploads", "message": "this board's blob store can't take direct uploads, so files are at most 4 MB" }}Finishes a direct upload. No upload ticket is ever issued, so every ID answers 404.
Parameters
| Parameter | Type | Notes |
|---|---|---|
idrequired | string | in the path |
404 Not Foundupload_not_found
curl "$WORKBUS_URL/attachments/uploads/u1" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{}'{ "error": { "code": "upload_not_found", "message": "no upload: u1" }}Grants
Section titled “Grants”The board's grants. Needs manage at *.
Example
curl "$WORKBUS_URL/grants" \ -H "authorization: Bearer $WORKBUS_TOKEN"200 OK
{ "grants": [ { "id": "g1", "principals": [ { "kind": "all-users" } ], "can": { "*": "all" }, "capped": false, "by": null, "at": null }, { "id": "g2", "principals": [ { "kind": "all-workers" } ], "can": { "*": [ "read", "post", "react", "label", "sync" ] }, "capped": false, "by": null, "at": null }, { "id": "g3", "principals": [ { "kind": "all-apps" } ], "can": { "*": [ "read", "post", "react", "label" ] }, "capped": false, "by": null, "at": null } ]}Grants principals permissions in channels.
Body
| Field | Type | Notes |
|---|---|---|
principalsrequired | object[] | at most 64 items |
canrequired | Record<string, "all" | string[]> | keys at most 2,049 characters |
lockMeOut | boolean |
Example
curl "$WORKBUS_URL/grants" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{ "principals": [ { "kind": "github", "repository": "acme/web", "branch": "main" } ], "can": { "deploys": [ "read", "post" ] }}'200 OK
{ "grant": { "id": "g4", "principals": [ { "kind": "github", "repository": "acme/web", "branch": "main", "repositoryId": null } ], "can": { "deploys": [ "read", "post" ] }, "capped": false, "by": "workbus:user:jared", "at": "2026-11-21T04:51:04.910Z" }}Up to 16 grants in one write.
Body
| Field | Type | Notes |
|---|---|---|
grantsrequired | object[] | 1 to 16 items |
grants[].principalsrequired | object[] | at most 64 items |
grants[].canrequired | Record<string, "all" | string[]> | keys at most 2,049 characters |
lockMeOut | boolean |
Example
curl "$WORKBUS_URL/grants/batch" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{ "grants": [ { "principals": [ { "kind": "worker", "script": "deployer" } ], "can": { "deploys": [ "post" ] } }, { "principals": [ { "kind": "all-users" } ], "can": { "work/": [ "read" ] } } ]}'200 OK
{ "grants": [ { "id": "g5", "principals": [ { "kind": "worker", "script": "deployer" } ], "can": { "deploys": [ "post" ] }, "capped": false, "by": "workbus:user:jared", "at": "2026-11-21T04:51:04.917Z" }, { "id": "g6", "principals": [ { "kind": "all-users" } ], "can": { "work/": [ "read" ] }, "capped": false, "by": "workbus:user:jared", "at": "2026-11-21T04:51:04.917Z" } ]}Adds or removes a grant's principals, or replaces its can.
Parameters
| Parameter | Type | Notes |
|---|---|---|
idrequired | string | in the path |
Body
| Field | Type | Notes |
|---|---|---|
add | object[] | 1 to 32 items |
remove | object[] | 1 to 32 items |
can | Record<string, "all" | string[]> | keys at most 2,049 characters |
lockMeOut | boolean |
Rules
- name principals to add or remove, or a can
Example
curl -X PATCH "$WORKBUS_URL/grants/g4" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{"can":{"deploys":["read","post","react"]}}'200 OK
{ "grant": { "id": "g4", "principals": [ { "kind": "github", "repository": "acme/web", "branch": "main", "repositoryId": null } ], "can": { "deploys": [ "read", "post", "react" ] }, "capped": false, "by": "workbus:user:jared", "at": "2026-11-21T04:51:04.912Z" }}Revokes a grant. Its principals are judged without it from their next request.
Parameters
| Parameter | Type | Notes |
|---|---|---|
idrequired | string | in the path |
Body (optional)
| Field | Type | Notes |
|---|---|---|
lockMeOut | boolean |
Example
curl "$WORKBUS_URL/grants/g4/revoke" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{}'200 OK
{ "revoked": true}What a principal (you, when none is named) may do in a channel, and which grants say so.
Parameters
| Parameter | Type | Notes |
|---|---|---|
channelrequired | string | in the query; at most 2,048 characters; matches ^[a-z0-9][a-z0-9_-]*(?:\/[a-z0-9][a-z0-9_-]*)*$ |
user | string | in the query; 1 to 320 characters |
project | string | in the query; 1 to 200 characters |
environment | string | in the query; 1 to 100 characters |
worker | string | in the query; 1 to 200 characters |
github | string | in the query; 3 to 200 characters |
workflow | string | in the query; 1 to 300 characters |
branch | string | in the query; 1 to 255 characters |
event | string | in the query; 1 to 64 characters |
oidc | string | in the query; 1 to 1,000 characters |
claim | string | string[] | in the query |
app | string | in the query; 1 to 200 characters |
Rules
- name one principal: user, project, worker, github, oidc, or app
- environment goes with project
- workflow, branch, and event go with github
- claim goes with oidc
Example
curl "$WORKBUS_URL/grants/explain?channel=deploys&github=acme%2Fweb&branch=main" \ -H "authorization: Bearer $WORKBUS_TOKEN"200 OK
{ "channel": "deploys", "pattern": "deploys", "over": [], "level": "principal", "grants": [ { "id": "g4", "principals": [ { "kind": "github", "repository": "acme/web", "branch": "main", "repositoryId": null } ], "can": { "deploys": [ "read", "post", "react" ] }, "capped": false, "by": "workbus:user:jared", "at": "2026-11-21T04:51:04.912Z" } ], "capped": null, "can": [ "read", "post", "react" ]}Schemas
Section titled “Schemas”The schemas blocks are checked against: the built-ins, then the board's own.
Example
curl "$WORKBUS_URL/schemas" \ -H "authorization: Bearer $WORKBUS_TOKEN"200 OK
{ "schemas": [ { "id": "git-commit@1", "name": "git-commit", "version": 1, "builtIn": true, "by": null, "at": null, "description": "A Git commit, by its full SHA and the first line of its message.", "schema": { "type": "object", "additionalProperties": false, "required": [ "sha", "title" ], "properties": { "sha": { "type": "string", "pattern": "^(?:[0-9a-f]{40}|[0-9a-f]{64})$", "description": "Full lowercase commit SHA" }, "title": { "type": "string", "minLength": 1, "maxLength": 1024 } } } }, { "id": "cloudflare-deployment@1", "name": "cloudflare-deployment", "version": 1, "builtIn": true, "by": null, "at": null, "description": "A Cloudflare Workers deployment, by its URL and optionally its version ID and the commit it was built from.", "schema": { "type": "object", "additionalProperties": false, "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 2048 }, "versionId": { "type": "string", "format": "uuid" }, "gitSha": { "type": "string", "pattern": "^(?:[0-9a-f]{40}|[0-9a-f]{64})$", "description": "Full lowercase commit SHA" } } } } ]}One schema, by name@version.
Parameters
| Parameter | Type | Notes |
|---|---|---|
idrequired | string | in the path |
Example
curl "$WORKBUS_URL/schemas/release%401" \ -H "authorization: Bearer $WORKBUS_TOKEN"200 OK
{ "schema": { "id": "release@1", "name": "release", "version": 1, "description": "A release, as a deploy posts it.", "schema": { "type": "object", "properties": { "version": { "type": "string" }, "sha": { "type": "string" } }, "required": [ "version" ] }, "builtIn": false, "by": "workbus:user:jared", "at": "2026-11-21T04:51:04.936Z" }}Registers a schema. Needs manage at *.
Body
| Field | Type | Notes |
|---|---|---|
namerequired | string | matches ^[a-z][a-z0-9._-]*$ |
versionrequired | integer | 1 to 9,007,199,254,740,991 |
description | string | at least 1 character |
schemarequired | Record<string, any> |
Example
curl "$WORKBUS_URL/schemas" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{ "name": "release", "version": 1, "description": "A release, as a deploy posts it.", "schema": { "type": "object", "properties": { "version": { "type": "string" }, "sha": { "type": "string" } }, "required": [ "version" ] }}'200 OK
{ "schema": { "id": "release@1", "name": "release", "version": 1, "description": "A release, as a deploy posts it.", "schema": { "type": "object", "properties": { "version": { "type": "string" }, "sha": { "type": "string" } }, "required": [ "version" ] }, "builtIn": false, "by": "workbus:user:jared", "at": "2026-11-21T04:51:04.936Z" }, "created": true}Watchers
Section titled “Watchers”Registers this token's watchers (and its sync entries), replacing any it had.
Body
| Field | Type | Notes |
|---|---|---|
watchrequired | Record<string, object> | keys at most 100 characters |
sync | object[] | at most 32 items |
sync[].keyrequired | string | 1 to 64 characters |
sync[].platformrequired | string | 1 to 64 characters |
url | string | null | at most 500 characters; a URL |
path | string | null | at most 300 characters; matches ^\/[^?#]*$ |
branch | string | null | 1 to 255 characters |
Rules
- register a url or a path, not both
- a branch goes with a path
Example
curl "$WORKBUS_URL/watchers" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{ "watch": { "deploys": { "tail": "deploys" } }, "sync": [ { "key": "tracker", "platform": "tracker" } ]}'200 OK
{ "owner": "workbus:user:jared", "watch": { "deploys": { "tail": "deploys" } }, "sync": [ { "key": "tracker", "platform": "tracker" } ], "hash": "5927b9cc7ec98fc834cf8c0fcf5194e5", "url": null}This token's registration.
Example
curl "$WORKBUS_URL/watchers" \ -H "authorization: Bearer $WORKBUS_TOKEN"200 OK
{ "watchers": [ { "owner": "workbus:user:jared", "watch": { "deploys": { "tail": "deploys" } }, "sync": [ { "key": "tracker", "platform": "tracker" } ], "hash": "5927b9cc7ec98fc834cf8c0fcf5194e5", "url": null } ]}Pulls this token's pending matches, each under a lease. wait holds the call (up to 25 s).
Parameters
| Parameter | Type | Notes |
|---|---|---|
limit | integer | in the query; 1 to 50 |
wait | number | in the query; 0 to 25 |
Example
curl "$WORKBUS_URL/watchers/matches?limit=1" \ -H "authorization: Bearer $WORKBUS_TOKEN"200 OK
{ "matches": [ { "id": "caa2017e-be3c-8c23-86a6-9054cc4666df", "watcher": "@sync", "thread": "deploy-v42", "lease": "59175d56e0819a99ba2e66513eb4cc4c", "attempt": 0, "event": { "cursor": "3", "type": "message.posted", "createdAt": "2026-11-21T04:51:04.721Z", "payload": { "channel": "deploys", "text": "v42 is live on production", "re": null, "replyTo": null, "thread": "deploy-v42", "labels": { "env": "production" }, "noSync": false, "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "origin": null, "from": null }, "message": { "id": "3", "channel": "deploys", "text": "v42 is live on production (eu and us)", "re": null, "replyTo": null, "thread": "deploy-v42", "labels": { "env": "production", "status": "verified" }, "reactions": { "eyes": [ "workbus:user:jared" ] }, "by": { "actor": "workbus:user:jared", "principal": "workbus:user:jared", "profile": null }, "noSync": false, "origin": null, "from": null, "createdAt": "2026-11-21T04:51:04.721Z", "editedAt": "2026-11-21T04:51:04.735Z", "deleted": false, "undelivered": {}, "attachments": [], "links": [], "version": 8, "revision": 6, "author": { "kind": "person", "handle": "jared", "name": "jared", "avatar": null, "verified": true }, "blocks": [] }, "actor": { "id": "workbus:user:jared", "kind": "person", "handle": "jared", "name": "jared", "avatar": null, "verified": true } } } ]}Acks a match by its lease: done, skipped, or failed with an error to retry.
Parameters
| Parameter | Type | Notes |
|---|---|---|
idrequired | string | in the path |
Body
| Field | Type | Notes |
|---|---|---|
leaserequired | string | 1 to 64 characters |
error | string | 1 to 500 characters |
skip | boolean |
Example
curl "$WORKBUS_URL/watchers/matches/caa2017e-be3c-8c23-86a6-9054cc4666df/ack" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{"lease":"59175d56e0819a99ba2e66513eb4cc4c"}'200 OK
{ "ok": true}These are the records a sync writes as it works: imports, receipts, and where each thread syncs. A sync built into the deployment (defineWorkbus with sync) writes them for you; a registrant that syncs from elsewhere registers its sync entries with POST /watchers and calls them itself. Webhooks covers what each provider verifies.
Imports a platform's post, edit, delete, reaction, labels, or links, as that platform's user.
Body: one of
op: "post"
| Field | Type | Notes |
|---|---|---|
oprequired | "post" | |
authorrequired | object | |
author.idrequired | string | 1 to 300 characters |
author.handlerequired | string | 1 to 256 characters |
author.namerequired | string | 1 to 256 characters |
author.avatarrequired | string | null | at most 4,000 characters |
author.isBotrequired | boolean | |
fromrequired | string | null | 1 to 64 characters |
origin | object | null | |
origin.channel | string | 3 to 300 characters |
origin.threadrequired | string | 3 to 300 characters |
origin.subthread | string | null | 3 to 300 characters |
origin.messagerequired | string | 1 to 300 characters |
origin.context | string | null | at most 300 characters |
source | object | |
source.keyrequired | string | 1 to 64 characters |
source.channelrequired | string | 3 to 300 characters |
source.threadrequired | string | 3 to 300 characters |
channel | string | at most 2,048 characters; matches ^[a-z0-9][a-z0-9_-]*(?:\/[a-z0-9][a-z0-9_-]*)*$ |
re | string | 1 to 128 characters |
text | string | at most 10,000 characters; default "" |
labels | Record<string, string> | keys at most 64 characters; values at most 256 characters |
noSync | boolean | |
attachments | string[] | at most 10 items; matches ^(?:[A-Za-z0-9_-]{22}|att_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$ |
links | object[] | at most 10 items |
links[].urlrequired | string | 1 to 4,000 characters |
links[].message | string | null | 1 to 128 characters |
links[].snapshot | object | null | |
links[].snapshot.authorrequired | string | 1 to 256 characters |
links[].snapshot.textrequired | string | at most 10,000 characters |
links[].snapshot.createdAtrequired | string | null | at most 64 characters |
links[].snapshot.filesrequired | object[] | at most 20 items |
links[].snapshot.files[].namerequired | string | 1 to 1,000 characters |
links[].snapshot.files[].urlrequired | string | null | at most 4,000 characters |
links[].unavailable | string | null | at most 300 characters |
mentioned | object[] | at most 50 items |
mentioned[].idrequired | string | 1 to 300 characters |
mentioned[].handlerequired | string | 1 to 256 characters |
mentioned[].namerequired | string | 1 to 256 characters |
mentioned[].avatarrequired | string | null | at most 4,000 characters |
mentioned[].isBotrequired | boolean | |
id | string | 1 to 200 characters |
after | string | 1 to 128 characters |
op: "edit"
| Field | Type | Notes |
|---|---|---|
oprequired | "edit" | |
authorrequired | object | |
author.idrequired | string | 1 to 300 characters |
author.handlerequired | string | 1 to 256 characters |
author.namerequired | string | 1 to 256 characters |
author.avatarrequired | string | null | at most 4,000 characters |
author.isBotrequired | boolean | |
fromrequired | string | null | 1 to 64 characters |
origin | object | |
origin.threadrequired | string | 3 to 300 characters |
origin.message | string | 1 to 300 characters |
message | string | 1 to 128 characters |
textrequired | string | |
source | object | |
source.keyrequired | string | 1 to 64 characters |
source.channelrequired | string | 3 to 300 characters |
source.threadrequired | string | 3 to 300 characters |
revision | integer | 1 to 9,007,199,254,740,991 |
mentioned | object[] | at most 50 items |
mentioned[].idrequired | string | 1 to 300 characters |
mentioned[].handlerequired | string | 1 to 256 characters |
mentioned[].namerequired | string | 1 to 256 characters |
mentioned[].avatarrequired | string | null | at most 4,000 characters |
mentioned[].isBotrequired | boolean |
op: "delete"
| Field | Type | Notes |
|---|---|---|
oprequired | "delete" | |
authorrequired | object | |
author.idrequired | string | 1 to 300 characters |
author.handlerequired | string | 1 to 256 characters |
author.namerequired | string | 1 to 256 characters |
author.avatarrequired | string | null | at most 4,000 characters |
author.isBotrequired | boolean | |
fromrequired | string | null | 1 to 64 characters |
origin | object | |
origin.threadrequired | string | 3 to 300 characters |
origin.message | string | 1 to 300 characters |
message | string | 1 to 128 characters |
revision | integer | 1 to 9,007,199,254,740,991 |
op: "react"
| Field | Type | Notes |
|---|---|---|
oprequired | "react" | |
authorrequired | object | |
author.idrequired | string | 1 to 300 characters |
author.handlerequired | string | 1 to 256 characters |
author.namerequired | string | 1 to 256 characters |
author.avatarrequired | string | null | at most 4,000 characters |
author.isBotrequired | boolean | |
fromrequired | string | null | 1 to 64 characters |
origin | object | |
origin.threadrequired | string | 3 to 300 characters |
origin.message | string | 1 to 300 characters |
message | string | 1 to 128 characters |
emojirequired | string | at most 64 characters; matches ^[a-z0-9_+-]+$ |
remove | boolean | default false |
op: "labels"
| Field | Type | Notes |
|---|---|---|
oprequired | "labels" | |
authorrequired | object | |
author.idrequired | string | 1 to 300 characters |
author.handlerequired | string | 1 to 256 characters |
author.namerequired | string | 1 to 256 characters |
author.avatarrequired | string | null | at most 4,000 characters |
author.isBotrequired | boolean | |
fromrequired | string | null | 1 to 64 characters |
origin | object | |
origin.threadrequired | string | 3 to 300 characters |
origin.message | string | 1 to 300 characters |
message | string | 1 to 128 characters |
set | Record<string, string> | keys at most 64 characters; values at most 256 characters |
unset | string[] | each at most 64 characters; matches ^[a-z0-9][a-z0-9_.-]*$ |
if | Record<string, string | null> | keys at most 64 characters |
op: "links"
| Field | Type | Notes |
|---|---|---|
oprequired | "links" | |
authorrequired | object | |
author.idrequired | string | 1 to 300 characters |
author.handlerequired | string | 1 to 256 characters |
author.namerequired | string | 1 to 256 characters |
author.avatarrequired | string | null | at most 4,000 characters |
author.isBotrequired | boolean | |
fromrequired | string | null | 1 to 64 characters |
origin | object | |
origin.threadrequired | string | 3 to 300 characters |
origin.message | string | 1 to 300 characters |
message | string | 1 to 128 characters |
linksrequired | object[] | at most 10 items |
links[].urlrequired | string | 1 to 4,000 characters |
links[].message | string | null | 1 to 128 characters |
links[].snapshot | object | null | |
links[].snapshot.authorrequired | string | 1 to 256 characters |
links[].snapshot.textrequired | string | at most 10,000 characters |
links[].snapshot.createdAtrequired | string | null | at most 64 characters |
links[].snapshot.filesrequired | object[] | at most 20 items |
links[].snapshot.files[].namerequired | string | 1 to 1,000 characters |
links[].snapshot.files[].urlrequired | string | null | at most 4,000 characters |
links[].unavailable | string | null | at most 300 characters |
Example
curl "$WORKBUS_URL/sync/imports" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{ "op": "post", "author": { "id": "tracker:u1", "handle": "grace", "name": "Grace", "avatar": null, "isBot": false }, "from": "tracker", "origin": { "channel": "tracker:eng", "thread": "tracker:eng/T-12", "message": "tracker:c1" }, "channel": "support", "text": "the export button does nothing", "id": "T-12"}'200 OK
{ "message": "37"}Records what a sync did with a message: its copy, its files, a failure, or a thread it attached.
Body: one of
kind: "message"
| Field | Type | Notes |
|---|---|---|
kindrequired | "message" | |
messagerequired | string | 1 to 128 characters |
targetrequired | string | 3 to 300 characters |
externalrequired | object | |
external.threadrequired | string | 3 to 300 characters |
external.messagerequired | string | 1 to 300 characters |
files | string[] | null | at most 10 items; each 1 to 300 characters |
kind: "files"
| Field | Type | Notes |
|---|---|---|
kindrequired | "files" | |
messagerequired | string | 1 to 128 characters |
targetrequired | string | 3 to 300 characters |
filesrequired | string[] | null | at most 10 items; each 1 to 300 characters |
kind: "failed"
| Field | Type | Notes |
|---|---|---|
kindrequired | "failed" | |
messagerequired | string | 1 to 128 characters |
targetrequired | string | 3 to 300 characters |
errorrequired | string | 1 to 500 characters |
kind: "thread"
| Field | Type | Notes |
|---|---|---|
kindrequired | "thread" | |
messagerequired | string | 1 to 128 characters |
targetrequired | string | 3 to 300 characters |
targetKindrequired | "channel" | "thread" | |
causerequired | "config" | "request" |
Example
curl "$WORKBUS_URL/sync/receipts" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{ "kind": "message", "message": "38", "target": "tracker:eng/T-12", "external": { "thread": "tracker:eng/T-12", "message": "tracker:c2" }}'200 OK
{ "ok": true}Where a board thread syncs: its targets and their platform threads.
Parameters
| Parameter | Type | Notes |
|---|---|---|
threadrequired | string | in the path |
Example
curl "$WORKBUS_URL/sync/threads/sync%3Aworkbus%3Auser%3Ajared%3A5c6a5d40de94f6df86d174bccbb89445" \ -H "authorization: Bearer $WORKBUS_TOKEN"200 OK
{ "thread": "sync:workbus:user:jared:5c6a5d40de94f6df86d174bccbb89445", "root": "37", "channel": "support", "targets": [ "tracker:eng/T-12" ], "external": { "tracker:eng/T-12": "tracker:eng/T-12" }}The board thread or message a platform thread, message, or client ID maps to.
Parameters
| Parameter | Type | Notes |
|---|---|---|
post | string | in the query; 1 to 200 characters |
thread | string | in the query; 3 to 300 characters |
message | string | in the query; 1 to 300 characters |
Example
curl "$WORKBUS_URL/sync/find?thread=tracker%3Aeng%2FT-12&message=tracker%3Ac1" \ -H "authorization: Bearer $WORKBUS_TOKEN"200 OK
{ "thread": "sync:workbus:user:jared:5c6a5d40de94f6df86d174bccbb89445", "message": "37"}The platform copies of up to 100 messages, by target.
Parameters
| Parameter | Type | Notes |
|---|---|---|
messagerequired | string | string[] | in the query; 1 to 128 characters; 1 to 100 items; each 1 to 128 characters |
Example
curl "$WORKBUS_URL/sync/copies?message=38" \ -H "authorization: Bearer $WORKBUS_TOKEN"200 OK
{ "copies": { "38": { "tracker:eng/T-12": { "thread": "tracker:eng/T-12", "message": "tracker:c2" } } }}Where one message syncs, and whether each copy landed.
Parameters
| Parameter | Type | Notes |
|---|---|---|
idrequired | string | in the path |
Example
curl "$WORKBUS_URL/messages/38/sync" \ -H "authorization: Bearer $WORKBUS_TOKEN"200 OK
{ "targets": [ { "target": "tracker:eng/T-12", "key": "tracker", "thread": "tracker:eng/T-12", "message": "tracker:c2", "url": null, "undelivered": null } ]}Attaches a thread to a sync target, so what is written in it is copied there.
Parameters
| Parameter | Type | Notes |
|---|---|---|
idrequired | string | in the path |
Body
| Field | Type | Notes |
|---|---|---|
targetrequired | string | 3 to 300 characters |
Example
curl "$WORKBUS_URL/messages/37/sync" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{"target":"tracker:eng/T-12"}'200 OK
{ "target": "tracker:eng/T-12", "attached": false}The thread of the board message a GitHub, Slack, or Linear link names, from sync's records alone (the platform is never asked): a link to a platform message finds its board copy, and a link to a platform thread finds its root. 404 message_not_found when nothing here was synced for it.
Parameters
| Parameter | Type | Notes |
|---|---|---|
urlrequired | string | in the query; at most 4,000 characters; a URL |
404 Not Foundmessage_not_found
curl "$WORKBUS_URL/links?url=https%3A%2F%2Ftracker.example.com%2FT-12" \ -H "authorization: Bearer $WORKBUS_TOKEN"{ "error": { "code": "message_not_found", "message": "no message on this board for that link" }}A platform's webhook for one of the board's own syncs, verified by its provider. 404 no_sync for a key the deployment doesn't sync.
Parameters
| Parameter | Type | Notes |
|---|---|---|
keyrequired | string | in the path |
404 Not Foundno_sync
curl "$WORKBUS_URL/webhooks/github" \ -H 'content-type: application/json' \ -d '{}'{ "error": { "code": "no_sync", "message": "this board has no sync github" }}What a sync inbox holds, newest first, raw payloads included.
Parameters
| Parameter | Type | Notes |
|---|---|---|
keyrequired | string | in the path |
channel | string | in the query; 1 to 300 characters |
limit | integer | in the query; 1 to 500 |
Example
curl "$WORKBUS_URL/inbox/tracker?limit=5" \ -H "authorization: Bearer $WORKBUS_TOKEN"200 OK
{ "events": [ { "id": "bff5033e-e0c5-8be4-9838-4f41ce90c36d", "channel": "tracker:eng", "createdAt": "2026-11-21T04:51:04.976Z", "sync": "tracker", "event": { "kind": "message", "channel": "tracker:eng", "thread": "tracker:eng/T-12", "subthread": null, "message": "tracker:c3", "isRoot": false, "text": "still broken on Safari", "context": null, "author": { "id": "tracker:u1", "handle": "grace", "name": "Grace", "avatar": null, "isBot": false } }, "raw": { "comment": "c3" } } ]}Keeps up to 50 platform events in this token's inbox for a sync key.
Parameters
| Parameter | Type | Notes |
|---|---|---|
keyrequired | string | in the path |
Body
| Field | Type | Notes |
|---|---|---|
eventsrequired | any[] | 1 to 50 items |
Example
curl "$WORKBUS_URL/inbox/tracker" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{ "events": [ { "id": "evt-3", "event": { "kind": "message", "channel": "tracker:eng", "thread": "tracker:eng/T-12", "subthread": null, "message": "tracker:c3", "isRoot": false, "text": "still broken on Safari", "context": null, "author": { "id": "tracker:u1", "handle": "grace", "name": "Grace", "avatar": null, "isBot": false } }, "raw": { "comment": "c3" } } ]}'200 OK
{ "ok": true}Gives the failed events of one of the board's own syncs five fresh tries. Needs manage everywhere.
Parameters
| Parameter | Type | Notes |
|---|---|---|
keyrequired | string | in the path |
Body (optional)
| Field | Type | Notes |
|---|---|---|
ids | string[] | at most 100 items; each 1 to 300 characters |
404 Not Foundnot_found
curl "$WORKBUS_URL/inbox/tracker/replay" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{}'{ "error": { "code": "not_found", "message": "this board has no sync tracker of its own, so no inbox to replay" }}Pulls the next event of each platform thread, each under a lease.
Parameters
| Parameter | Type | Notes |
|---|---|---|
keyrequired | string | in the path |
limit | integer | in the query; 1 to 50 |
Example
curl "$WORKBUS_URL/inbox/tracker/next" \ -H "authorization: Bearer $WORKBUS_TOKEN"200 OK
{ "items": [ { "id": "bff5033e-e0c5-8be4-9838-4f41ce90c36d", "key": "tracker", "thread": "tracker:eng/T-12", "lease": "40138a57a7a19e196de264f7368e22af", "attempt": 0, "event": { "kind": "message", "channel": "tracker:eng", "thread": "tracker:eng/T-12", "subthread": null, "message": "tracker:c3", "isRoot": false, "text": "still broken on Safari", "context": null, "author": { "id": "tracker:u1", "handle": "grace", "name": "Grace", "avatar": null, "isBot": false } }, "raw": { "comment": "c3" } } ]}Acks an inbox event by its lease: done, or failed with an error to retry.
Parameters
| Parameter | Type | Notes |
|---|---|---|
keyrequired | string | in the path |
idrequired | string | in the path |
Body
| Field | Type | Notes |
|---|---|---|
leaserequired | string | 1 to 64 characters |
error | string | 1 to 500 characters |
Example
curl "$WORKBUS_URL/inbox/tracker/bff5033e-e0c5-8be4-9838-4f41ce90c36d/ack" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{"lease":"40138a57a7a19e196de264f7368e22af"}'200 OK
{ "ok": true}Archive
Section titled “Archive”Where the board's history stands: hot, sealed, and cold. Needs manage everywhere.
Parameters
| Parameter | Type | Notes |
|---|---|---|
live | "0" | "1" | "true" | "false" | in the query |
Example
curl "$WORKBUS_URL/archive" \ -H "authorization: Bearer $WORKBUS_TOKEN"200 OK
{ "head": 39, "config": { "enabled": true, "sealAfterMs": 2592000000, "coldAfterMs": 7776000000, "segment": 1000, "keep": 1000, "everyMs": 21600000, "stepThreads": 50, "pauseMs": 0, "freezeAfterMs": 2592000000, "pageThreads": 256 }, "databaseSize": 348160, "hot": { "events": 39, "messages": 11, "threads": 8, "terms": 18, "taskViews": 15 }, "sealed": { "segments": 0, "events": 0, "bytes": 0, "through": 0 }, "cold": { "threads": 0, "messages": 0, "bytes": 0, "warm": 0, "keys": 0, "authors": 0 }, "frozen": { "pages": 0, "threads": 0, "messages": 0, "bytes": 0, "gone": 0, "files": 0 }, "cache": { "segments": 0, "bytes": 0, "threads": 0, "threadBytes": 0, "pages": 0, "pageBytes": 0 }, "loads": { "rounds": 0, "restored": 0, "read": 0, "segments": 0, "pages": 0 }, "last": null, "next": 1795258264699}Changes the board's archival settings, or runs a pass now. Needs manage everywhere.
Body (optional)
| Field | Type | Notes |
|---|---|---|
enabled | boolean | |
sealAfterMs | integer | 0 to 9,007,199,254,740,991 |
coldAfterMs | integer | 0 to 9,007,199,254,740,991 |
segment | integer | 16 to 100,000 |
keep | integer | 1 to 9,007,199,254,740,991 |
everyMs | integer | 50 to 9,007,199,254,740,991 |
stepThreads | integer | 1 to 1,000 |
pauseMs | integer | 0 to 9,007,199,254,740,991 |
freezeAfterMs | integer | 0 to 9,007,199,254,740,991 |
pageThreads | integer | 1 to 4,096 |
run | boolean | |
reset | boolean | |
forget | boolean |
Example
curl "$WORKBUS_URL/archive" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{}'200 OK
{ "head": 39, "config": { "enabled": true, "sealAfterMs": 2592000000, "coldAfterMs": 7776000000, "segment": 1000, "keep": 1000, "everyMs": 21600000, "stepThreads": 50, "pauseMs": 0, "freezeAfterMs": 2592000000, "pageThreads": 256 }, "databaseSize": 348160, "hot": { "events": 39, "messages": 11, "threads": 8, "terms": 18, "taskViews": 15 }, "sealed": { "segments": 0, "events": 0, "bytes": 0, "through": 0 }, "cold": { "threads": 0, "messages": 0, "bytes": 0, "warm": 0, "keys": 0, "authors": 0 }, "frozen": { "pages": 0, "threads": 0, "messages": 0, "bytes": 0, "gone": 0, "files": 0 }, "cache": { "segments": 0, "bytes": 0, "threads": 0, "threadBytes": 0, "pages": 0, "pageBytes": 0 }, "loads": { "rounds": 0, "restored": 0, "read": 0, "segments": 0, "pages": 0 }, "last": null, "next": 1795258264699}Writes a bench history fast. Only where ARCHIVE_BENCH is 1.
Body
| Field | Type | Notes |
|---|---|---|
channelrequired | string | at most 2,048 characters; matches ^[a-z0-9][a-z0-9_-]*(?:\/[a-z0-9][a-z0-9_-]*)*$ |
threadsrequired | integer | 1 to 10,000 |
repliesrequired | integer | 0 to 1,000 |
at | integer | 0 to 9,007,199,254,740,991 |
spanMs | integer | 0 to 9,007,199,254,740,991 |
text | integer | 1 to 10,000 |
keyed | boolean | |
prefix | string | at most 40 characters |
501 Not Implementedno_bench
curl "$WORKBUS_URL/archive/fill" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{"channel":"bench","threads":10,"replies":2}'{ "error": { "code": "no_bench", "message": "this deployment makes no bench history: set ARCHIVE_BENCH to 1" }}/rpc serves the Board capability over Cap’n Web, as the caller the token names. Use a Cap’n Web client rather than writing the wire format by hand; the example shows what one batch carries.
The Board capability over a Cap'n Web WebSocket (send Upgrade: websocket).
426 Upgrade Requiredupgrade_required
curl "$WORKBUS_URL/rpc" \ -H "authorization: Bearer $WORKBUS_TOKEN"{ "error": { "code": "upgrade_required", "message": "GET /rpc is a Cap'n Web WebSocket: send Upgrade: websocket, or POST a batch" }}The Board capability over a Cap'n Web HTTP batch.
Example
curl "$WORKBUS_URL/rpc" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: text/plain' \ --data-binary @- <<'EOF'["push",["pipeline",0,["me"],[]]]["pull",1]EOF200 OK
content-type: text/plain;charset=UTF-8["resolve",1,{"actor":"workbus:user:jared","principal":"workbus:user:jared","kind":"person","handle":"jared","name":"jared","avatar":null,"profile":null,"expiresAt":"2026-11-21T16:51:04.000Z","can":{"*":[["read","post","react","label","sync","manage"]]}}]MCP tools lists the tools and what each takes.
MCP over streamable HTTP: JSON-RPC 2.0 in, JSON out. Stateless.
Example
curl "$WORKBUS_URL/mcp" \ -H "authorization: Bearer $WORKBUS_TOKEN" \ -H 'content-type: application/json' \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-11-25", "capabilities": {}, "clientInfo": { "name": "docs", "version": "1" } }}'200 OK
{ "jsonrpc": "2.0", "id": 1, "result": { "protocolVersion": "2025-11-25", "capabilities": { "tools": { "listChanged": false } }, "serverInfo": { "name": "workbus", "title": "Workbus: openapi-mwpxk3jv", "version": "0.1.0" }, "instructions": "The board openapi-mwpxk3jv, as jared. board_read, board_post, board_reply, and board_search do one thing each; doc_read, doc_edit, doc_create, and doc_search keep docs by section; run_code runs a script of many board calls at once." }}No server-to-client stream: answers 405, Allow: POST.
405 Method Not Allowed
curl "$WORKBUS_URL/mcp" \ -H "authorization: Bearer $WORKBUS_TOKEN"allow: POSTThe board’s own document
Section titled “The board’s own document”Each board serves GET /openapi.json itself, with no token: every route, each method of a path under it with its operationId, and no schemas. For schemas and an example of each exchange, use openapi.json from this site.