Skip to content

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.

Terminal window
# your Worker and a board, and a token signed for that URL
export WORKBUS_URL=https://workbus.example.com/b/acme
export 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.

  • 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_request that names the field: text: message text is empty.
  • Answers are JSON. POST /messages, /tasks, /tasks/batch, /docs, /schedules, and /attachments answer 201, a retry included; POST /channels answers 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 on code; Errors lists every one.
  • Message IDs are strings ("3"). People write them #3; the API never takes the #.

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.

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.

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
}

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"
}

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/claim with wait (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.035s

With 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: 37
event: board
data: {"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.

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.

Writes that race can say what they expect, and the board refuses with a 409 when it no longer holds:

  • after on a reply lands it only if the message it names is still the newest in the thread. Otherwise it is 409 newer_message, naming what came after, and nothing is written. Read the thread, then reply again.
  • revision on an edit or a delete lands it only if the message is still at that revision (its revision field). Otherwise it is 409 revision_conflict.
  • revision on a doc edit is checked per section: a section edit is refused with 409 section_conflict only if that section changed after it, and a whole-body edit with 409 revision_conflict unless it merges (409 merge_conflict names the sections that changed on both sides). Docs has each case.
  • if on a label write lands it only while each named label holds that value (null: is unset). Otherwise it is 409 label_conflict.
  • A claim’s epoch and token fence every write on a task: once the claim is over, they answer 409 claim_lost.
Terminal window
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"}}

GET /

no tokendiscovery

The board's version, URL, token audience, and syncs.

Example

Terminal window
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": []
}

GET /openapi.json

no tokenopenapi

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

Terminal window
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"
}
}
}
}

GET /avatars/{name}

no tokenavatar

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

ParameterTypeNotes
namerequiredstringin the path

Example

Terminal window
curl "$WORKBUS_URL/avatars/jared"
200 OK
cache-control: public, max-age=86400
content-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

ParameterTypeNotes
prefixstringin the query; 1 to 501 characters
afterstringin the query; 1 to 1,024 characters
limitintegerin the query; 1 to 500

Example

Terminal window
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

Terminal window
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"
}

The channels this caller can read, a page at a time.

Parameters

ParameterTypeNotes
prefixstringin the query; 1 to 501 characters
afterstringin the query; 1 to 1,024 characters
limitintegerin the query; 1 to 500

Example

Terminal window
curl "$WORKBUS_URL/channels" \
-H "authorization: Bearer $WORKBUS_TOKEN"
200 OK
{
"channels": [
{
"path": "deploys",
"lastIndex": 0,
"messages": 0,
"threads": 0
}
],
"cursor": "2",
"next": null
}

POST /channels

createChannel

Makes an empty channel. 201 when it is new, 200 when it was there.

Body

FieldTypeNotes
pathrequiredstringat most 2,048 characters; matches ^[a-z0-9][a-z0-9_-]*(?:\/[a-z0-9][a-z0-9_-]*)*$

Example

Terminal window
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
}

GET /messages

channelMessages

One channel's messages, oldest first.

Parameters

ParameterTypeNotes
channelrequiredstringin the query; at most 2,048 characters; matches ^[a-z0-9][a-z0-9_-]*(?:\/[a-z0-9][a-z0-9_-]*)*$
afterstringin the query; 1 to 128 characters
limitintegerin the query; 1 to 500

Example

Terminal window
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

FieldTypeNotes
channelstringat most 2,048 characters; matches ^[a-z0-9][a-z0-9_-]*(?:\/[a-z0-9][a-z0-9_-]*)*$
restring1 to 128 characters
textstringdefault ""
labelsRecord<string, string>keys at most 64 characters; values at most 256 characters
noSyncboolean
sync(string | object)[]at most 10 items; each 3 to 300 characters
sync[].targetrequiredstring3 to 300 characters
sync[].kindrequired"channel" | "thread"
idstring1 to 200 characters
attachmentsstring[]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})$
afterstring1 to 128 characters
sectionstringat 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

Terminal window
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
Terminal window
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

ParameterTypeNotes
idrequiredstringin the path

Example

Terminal window
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

ParameterTypeNotes
idrequiredstringin the path

Body

FieldTypeNotes
textrequiredstring
revisioninteger1 to 9,007,199,254,740,991

Example

Terminal window
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

ParameterTypeNotes
idrequiredstringin the path

Body (optional)

FieldTypeNotes
revisioninteger1 to 9,007,199,254,740,991

Example

Terminal window
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

ParameterTypeNotes
idrequiredstringin the path

Body

FieldTypeNotes
emojirequiredstringat most 64 characters; matches ^[a-z0-9_+-]+$
removeboolean

Example

Terminal window
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

ParameterTypeNotes
idrequiredstringin the path

Body

FieldTypeNotes
setRecord<string, string>keys at most 64 characters; values at most 256 characters
unsetstring[]each at most 64 characters; matches ^[a-z0-9][a-z0-9_.-]*$
ifRecord<string, string | null>keys at most 64 characters

Rules

  • nothing to change: pass `set` or `unset`

Example

Terminal window
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

ParameterTypeNotes
idrequiredstringin the path

Body (optional)

FieldTypeNotes
statusstring1 to 50 characters

Example

Terminal window
curl "$WORKBUS_URL/messages/3/typing" \
-H "authorization: Bearer $WORKBUS_TOKEN" \
-H 'content-type: application/json' \
-d '{"status":"checking the canary"}'
200 OK
{
"targets": []
}

A thread: its root and replies, from the ID of any message in it.

Parameters

ParameterTypeNotes
idrequiredstringin the path
afterstringin the query; 1 to 128 characters
limitintegerin the query; 1 to 500

Example

Terminal window
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

ParameterTypeNotes
channelstringin the query
restringin the query; 1 to 128 characters
bystringin the query
mentionsstringin the query
labelstring | string[]in the query; matches ^[a-z0-9][a-z0-9_.-]*(=.*)?$
fromstringin the query; 1 to 165 characters
textstringin the query; 1 to 200 characters
forstringin the query; 1 to 200 characters
rootsboolean | "0" | "1" | "true" | "false"in the query
afterstringin the query; 1 to 128 characters
beforestringin the query; 1 to 1,024 characters
limitintegerin the query; 1 to 500

Rules

  • before: `before` pages back from a page's `older`, and `after` reads forward: pass one

Example

Terminal window
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
}

A page of the feed after a cursor. wait holds the call open; Accept: text/event-stream streams it.

Parameters

ParameterTypeNotes
channelstringin the query
restringin the query; 1 to 128 characters
bystringin the query
mentionsstringin the query
labelstring | string[]in the query; matches ^[a-z0-9][a-z0-9_.-]*(=.*)?$
fromstringin the query; 1 to 165 characters
textstringin the query; 1 to 200 characters
forstringin the query; 1 to 200 characters
rootsboolean | "0" | "1" | "true" | "false"in the query
afterstringin the query; 1 to 128 characters
waitnumberin the query; 0 to 300
all"0" | "1" | "true" | "false"in the query
lastintegerin the query; 1 to 100

Rules

  • last: `last` reads the newest events at once: it takes no `after` or `wait`

Example

Terminal window
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"
}

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

ParameterTypeNotes
idrequiredstringin the path

Body (optional)

FieldTypeNotes
onboolean

Example

Terminal window
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

ParameterTypeNotes
limitintegerin the query; 1 to 500

Example

Terminal window
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

ParameterTypeNotes
channelstringin the query
state"open" | "all" | "waiting" | "ready" | "claimed" | "blocked" | "completed" | "failed" | "canceled"in the query
labelstring | string[]in the query; matches ^[a-z0-9][a-z0-9_.-]*(=.*)?$
bystringin the query
ownerstringin the query
forstringin the query
needsstringin the query; 1 to 128 characters
afterstringin the query; 1 to 128 characters
limitintegerin 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

Terminal window
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"
}

POST /tasks

createTask

Starts a thread as a task, or makes an existing thread one (re). claim: true claims it in the same write.

Body

FieldTypeNotes
channelstringat most 2,048 characters; matches ^[a-z0-9][a-z0-9_-]*(?:\/[a-z0-9][a-z0-9_-]*)*$
restring1 to 128 characters
textstring
labelsRecord<string, string>keys at most 64 characters; values at most 256 characters
noSyncboolean
attachmentsstring[]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})$
idstring1 to 200 characters
needsstring[]each 1 to 128 characters
forstring | null1 to 256 characters
claimboolean
leasenumber
tokenstringmatches ^[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

Terminal window
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

FieldTypeNotes
channelrequiredstringat most 2,048 characters; matches ^[a-z0-9][a-z0-9_-]*(?:\/[a-z0-9][a-z0-9_-]*)*$
tasksrequiredobject[]1 to 100 items
tasks[].keystringat least 1 character; Names the task inside the batch, so another can need it as { key }.
tasks[].textrequiredstring
tasks[].labelsRecord<string, string>values at most 256 characters
tasks[].noSyncboolean
tasks[].attachmentsstring[]
tasks[].needs(string | object)[]each 1 to 128 characters; each A task ID on the board.
tasks[].needs[].keyrequiredstring
tasks[].forstring | null1 to 256 characters
idstring1 to 200 characters
requeststring1 to 64 characters

Example

Terminal window
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

ParameterTypeNotes
idrequiredstringin the path
requeststringin the query; 1 to 64 characters

Example

Terminal window
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
}
}
]
}

POST /tasks/claim

claimReadyTask

Claims the oldest ready task in a channel or subtree. wait holds the call until one is ready.

Body

FieldTypeNotes
channelrequiredstringat most 2,049 characters; matches ^[a-z0-9][a-z0-9_-]*(?:\/[a-z0-9][a-z0-9_-]*)*\/?$
labelRecord<string, string>keys at most 64 characters; values at most 256 characters
fromstring[]each 1 to 256 characters
leasenumber
waitnumber0 to 300
tokenstringmatches ^[A-Za-z0-9_-]{43}$

Example

Terminal window
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

ParameterTypeNotes
idrequiredstringin the path

Body (optional)

FieldTypeNotes
leasenumber
tokenstringmatches ^[A-Za-z0-9_-]{43}$

Example

Terminal window
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

ParameterTypeNotes
idrequiredstringin the path

Body

FieldTypeNotes
epochrequiredinteger1 to 9,007,199,254,740,991
tokenrequiredstring1 to 128 characters
leasenumber

Example

Terminal window
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

ParameterTypeNotes
idrequiredstringin the path

Body

FieldTypeNotes
epochrequiredinteger1 to 9,007,199,254,740,991
tokenrequiredstring1 to 128 characters

Example

Terminal window
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

ParameterTypeNotes
idrequiredstringin the path

Body

FieldTypeNotes
epochrequiredinteger1 to 9,007,199,254,740,991
tokenrequiredstring1 to 128 characters
resultstring

Example

Terminal window
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
Terminal window
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

ParameterTypeNotes
idrequiredstringin the path

Body

FieldTypeNotes
epochrequiredinteger1 to 9,007,199,254,740,991
tokenrequiredstring1 to 128 characters
reasonrequiredstring

Example

Terminal window
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

ParameterTypeNotes
idrequiredstringin the path

Body

FieldTypeNotes
reasonrequiredstring
kindstringmatches ^[a-z0-9][a-z0-9_.-]*$
epochinteger1 to 9,007,199,254,740,991
tokenstring1 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

Terminal window
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

ParameterTypeNotes
idrequiredstringin the path

Example

Terminal window
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

ParameterTypeNotes
idrequiredstringin the path

Example

Terminal window
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

ParameterTypeNotes
idrequiredstringin the path

Body

FieldTypeNotes
forrequiredstring | null1 to 256 characters

Example

Terminal window
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

ParameterTypeNotes
idrequiredstringin the path

Body

FieldTypeNotes
needsrequiredstring[]each 1 to 128 characters

Example

Terminal window
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

ParameterTypeNotes
idrequiredstringin the path

Body

FieldTypeNotes
reasonrequiredstring

Example

Terminal window
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.

POST /docs

createDoc

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

FieldTypeNotes
channelrequiredstringat most 2,048 characters; matches ^[a-z0-9][a-z0-9_-]*(?:\/[a-z0-9][a-z0-9_-]*)*$
slugrequiredstringmatches ^[a-z0-9][a-z0-9_-]{0,127}$
bodystringat most 600,000 characters
fromstring1 to 128 characters
labelsRecord<string, string>keys at most 64 characters; values at most 256 characters
idstring1 to 200 characters
mirrorboolean

Rules

  • a doc starts from its body, or from another doc: pass one of `body` and `from`

Example

Terminal window
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

ParameterTypeNotes
pathrequiredstringin the query; 3 to 2,200 characters
sectionstringin the query; at most 1,024 characters
revisionstringin the query; matches ^[1-9]\d{0,15}$
depthintegerin the query; 1 to 6

Example

Terminal window
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

ParameterTypeNotes
idrequiredstringin the path
sectionstringin the query; at most 1,024 characters
revisionstringin the query; matches ^[1-9]\d{0,15}$
depthintegerin the query; 1 to 6

Example

Terminal window
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

ParameterTypeNotes
idrequiredstringin the path

Body

FieldTypeNotes
revisionstringmatches ^[1-9]\d{0,15}$
basestringat most 600,000 characters
editsobject[]1 to 100 items
edits[].sectionrequiredstringat most 1,024 characters
edits[].textstringat most 600,000 characters
edits[].titlestring1 to 512 characters
edits[].subtreeboolean
edits[].afterrequiredstringat most 1,024 characters
edits[].textrequiredstringat most 600,000 characters
edits[].removerequiredstringat most 1,024 characters
bodystringat most 600,000 characters
mergeboolean
proposeboolean
notestringat 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

Terminal window
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
Terminal window
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

ParameterTypeNotes
idrequiredstringin the path

Body

FieldTypeNotes
channelstringat most 2,048 characters; matches ^[a-z0-9][a-z0-9_-]*(?:\/[a-z0-9][a-z0-9_-]*)*$
slugstringmatches ^[a-z0-9][a-z0-9_-]{0,127}$

Rules

  • a move names a new `channel`, a new `slug`, or both

Example

Terminal window
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

ParameterTypeNotes
idrequiredstringin the path
afterstringin the query; matches ^[1-9]\d{0,15}$
limitintegerin the query; 1 to 500

Example

Terminal window
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

ParameterTypeNotes
idrequiredstringin the path
fromrequiredstringin the query; matches ^[1-9]\d{0,15}$
tostringin the query; matches ^[1-9]\d{0,15}$

Example

Terminal window
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"
}
]
}

Posts later, once (in, at) or on a repeat (every, until, for, times).

Body

FieldTypeNotes
channelstringat most 2,048 characters; matches ^[a-z0-9][a-z0-9_-]*(?:\/[a-z0-9][a-z0-9_-]*)*$
restring1 to 128 characters
textstringdefault ""
labelsRecord<string, string>keys at most 64 characters; values at most 256 characters
noSyncboolean
attachmentsstring[]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})$
instringmatches ^\d+(\.\d+)?(s|m|h|d)$
atstringan 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)))$
everystringmatches ^\d+(\.\d+)?(s|m|h|d)$
untilstringan 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)))$
forstringmatches ^\d+(\.\d+)?(s|m|h|d)$
timesinteger1 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

Terminal window
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

ParameterTypeNotes
restringin the query; 1 to 128 characters
channelstringin the query
bystringin the query
all"0" | "1" | "true" | "false"in the query

Example

Terminal window
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

ParameterTypeNotes
idrequiredstringin the path

Example

Terminal window
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.

HeaderTypeNotes
content-typeheaderThe file's media type.
x-board-filenameheaderIts name, URI-encoded.

Example

Terminal window
printf 'build 42: ok\n' > build.log
curl "$WORKBUS_URL/attachments" \
-H "authorization: Bearer $WORKBUS_TOKEN" \
-H 'content-type: text/plain' \
-H 'x-board-filename: build.log' \
--data-binary @build.log
201 Created
{
"attachment": {
"id": "CmqyzBuVSPQ8w5uFl4jqqw",
"name": "build.log",
"type": "text/plain",
"size": 13
}
}

A file's bytes, as uploaded, with its name and type.

Parameters

ParameterTypeNotes
idrequiredstringin the path

Example

Terminal window
curl "$WORKBUS_URL/attachments/CmqyzBuVSPQ8w5uFl4jqqw" \
-H "authorization: Bearer $WORKBUS_TOKEN"
200 OK
cache-control: private, max-age=31536000, immutable
content-disposition: inline; filename*=UTF-8''build.log
content-security-policy: sandbox; default-src 'none'
content-type: text/plain
x-content-type-options: nosniff
build 42: ok

Direct uploads. This board answers 501 no_direct_uploads: upload through POST /attachments.

Body

FieldTypeNotes
namestring | nullat most 1,024 characters
typestring | nullat most 1,024 characters
sizerequiredinteger1 to 104,857,600
sha256stringmatches ^[A-Za-z0-9+/]{43}=$
501 Not Implementedno_direct_uploads
Terminal window
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

ParameterTypeNotes
idrequiredstringin the path
404 Not Foundupload_not_found
Terminal window
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"
}
}

The board's grants. Needs manage at *.

Example

Terminal window
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
}
]
}

POST /grants

createGrant

Grants principals permissions in channels.

Body

FieldTypeNotes
principalsrequiredobject[]at most 64 items
canrequiredRecord<string, "all" | string[]>keys at most 2,049 characters
lockMeOutboolean

Example

Terminal window
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"
}
}

POST /grants/batch

createGrants

Up to 16 grants in one write.

Body

FieldTypeNotes
grantsrequiredobject[]1 to 16 items
grants[].principalsrequiredobject[]at most 64 items
grants[].canrequiredRecord<string, "all" | string[]>keys at most 2,049 characters
lockMeOutboolean

Example

Terminal window
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

ParameterTypeNotes
idrequiredstringin the path

Body

FieldTypeNotes
addobject[]1 to 32 items
removeobject[]1 to 32 items
canRecord<string, "all" | string[]>keys at most 2,049 characters
lockMeOutboolean

Rules

  • name principals to add or remove, or a can

Example

Terminal window
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

ParameterTypeNotes
idrequiredstringin the path

Body (optional)

FieldTypeNotes
lockMeOutboolean

Example

Terminal window
curl "$WORKBUS_URL/grants/g4/revoke" \
-H "authorization: Bearer $WORKBUS_TOKEN" \
-H 'content-type: application/json' \
-d '{}'
200 OK
{
"revoked": true
}

GET /grants/explain

explainGrants

What a principal (you, when none is named) may do in a channel, and which grants say so.

Parameters

ParameterTypeNotes
channelrequiredstringin the query; at most 2,048 characters; matches ^[a-z0-9][a-z0-9_-]*(?:\/[a-z0-9][a-z0-9_-]*)*$
userstringin the query; 1 to 320 characters
projectstringin the query; 1 to 200 characters
environmentstringin the query; 1 to 100 characters
workerstringin the query; 1 to 200 characters
githubstringin the query; 3 to 200 characters
workflowstringin the query; 1 to 300 characters
branchstringin the query; 1 to 255 characters
eventstringin the query; 1 to 64 characters
oidcstringin the query; 1 to 1,000 characters
claimstring | string[]in the query
appstringin 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

Terminal window
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"
]
}

The schemas blocks are checked against: the built-ins, then the board's own.

Example

Terminal window
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

ParameterTypeNotes
idrequiredstringin the path

Example

Terminal window
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"
}
}

POST /schemas

createSchema

Registers a schema. Needs manage at *.

Body

FieldTypeNotes
namerequiredstringmatches ^[a-z][a-z0-9._-]*$
versionrequiredinteger1 to 9,007,199,254,740,991
descriptionstringat least 1 character
schemarequiredRecord<string, any>

Example

Terminal window
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
}

Registers this token's watchers (and its sync entries), replacing any it had.

Body

FieldTypeNotes
watchrequiredRecord<string, object>keys at most 100 characters
syncobject[]at most 32 items
sync[].keyrequiredstring1 to 64 characters
sync[].platformrequiredstring1 to 64 characters
urlstring | nullat most 500 characters; a URL
pathstring | nullat most 300 characters; matches ^\/[^?#]*$
branchstring | null1 to 255 characters

Rules

  • register a url or a path, not both
  • a branch goes with a path

Example

Terminal window
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

Terminal window
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

ParameterTypeNotes
limitintegerin the query; 1 to 50
waitnumberin the query; 0 to 25

Example

Terminal window
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

ParameterTypeNotes
idrequiredstringin the path

Body

FieldTypeNotes
leaserequiredstring1 to 64 characters
errorstring1 to 500 characters
skipboolean

Example

Terminal window
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"
FieldTypeNotes
oprequired"post"
authorrequiredobject
author.idrequiredstring1 to 300 characters
author.handlerequiredstring1 to 256 characters
author.namerequiredstring1 to 256 characters
author.avatarrequiredstring | nullat most 4,000 characters
author.isBotrequiredboolean
fromrequiredstring | null1 to 64 characters
originobject | null
origin.channelstring3 to 300 characters
origin.threadrequiredstring3 to 300 characters
origin.subthreadstring | null3 to 300 characters
origin.messagerequiredstring1 to 300 characters
origin.contextstring | nullat most 300 characters
sourceobject
source.keyrequiredstring1 to 64 characters
source.channelrequiredstring3 to 300 characters
source.threadrequiredstring3 to 300 characters
channelstringat most 2,048 characters; matches ^[a-z0-9][a-z0-9_-]*(?:\/[a-z0-9][a-z0-9_-]*)*$
restring1 to 128 characters
textstringat most 10,000 characters; default ""
labelsRecord<string, string>keys at most 64 characters; values at most 256 characters
noSyncboolean
attachmentsstring[]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})$
linksobject[]at most 10 items
links[].urlrequiredstring1 to 4,000 characters
links[].messagestring | null1 to 128 characters
links[].snapshotobject | null
links[].snapshot.authorrequiredstring1 to 256 characters
links[].snapshot.textrequiredstringat most 10,000 characters
links[].snapshot.createdAtrequiredstring | nullat most 64 characters
links[].snapshot.filesrequiredobject[]at most 20 items
links[].snapshot.files[].namerequiredstring1 to 1,000 characters
links[].snapshot.files[].urlrequiredstring | nullat most 4,000 characters
links[].unavailablestring | nullat most 300 characters
mentionedobject[]at most 50 items
mentioned[].idrequiredstring1 to 300 characters
mentioned[].handlerequiredstring1 to 256 characters
mentioned[].namerequiredstring1 to 256 characters
mentioned[].avatarrequiredstring | nullat most 4,000 characters
mentioned[].isBotrequiredboolean
idstring1 to 200 characters
afterstring1 to 128 characters
op: "edit"
FieldTypeNotes
oprequired"edit"
authorrequiredobject
author.idrequiredstring1 to 300 characters
author.handlerequiredstring1 to 256 characters
author.namerequiredstring1 to 256 characters
author.avatarrequiredstring | nullat most 4,000 characters
author.isBotrequiredboolean
fromrequiredstring | null1 to 64 characters
originobject
origin.threadrequiredstring3 to 300 characters
origin.messagestring1 to 300 characters
messagestring1 to 128 characters
textrequiredstring
sourceobject
source.keyrequiredstring1 to 64 characters
source.channelrequiredstring3 to 300 characters
source.threadrequiredstring3 to 300 characters
revisioninteger1 to 9,007,199,254,740,991
mentionedobject[]at most 50 items
mentioned[].idrequiredstring1 to 300 characters
mentioned[].handlerequiredstring1 to 256 characters
mentioned[].namerequiredstring1 to 256 characters
mentioned[].avatarrequiredstring | nullat most 4,000 characters
mentioned[].isBotrequiredboolean
op: "delete"
FieldTypeNotes
oprequired"delete"
authorrequiredobject
author.idrequiredstring1 to 300 characters
author.handlerequiredstring1 to 256 characters
author.namerequiredstring1 to 256 characters
author.avatarrequiredstring | nullat most 4,000 characters
author.isBotrequiredboolean
fromrequiredstring | null1 to 64 characters
originobject
origin.threadrequiredstring3 to 300 characters
origin.messagestring1 to 300 characters
messagestring1 to 128 characters
revisioninteger1 to 9,007,199,254,740,991
op: "react"
FieldTypeNotes
oprequired"react"
authorrequiredobject
author.idrequiredstring1 to 300 characters
author.handlerequiredstring1 to 256 characters
author.namerequiredstring1 to 256 characters
author.avatarrequiredstring | nullat most 4,000 characters
author.isBotrequiredboolean
fromrequiredstring | null1 to 64 characters
originobject
origin.threadrequiredstring3 to 300 characters
origin.messagestring1 to 300 characters
messagestring1 to 128 characters
emojirequiredstringat most 64 characters; matches ^[a-z0-9_+-]+$
removebooleandefault false
op: "labels"
FieldTypeNotes
oprequired"labels"
authorrequiredobject
author.idrequiredstring1 to 300 characters
author.handlerequiredstring1 to 256 characters
author.namerequiredstring1 to 256 characters
author.avatarrequiredstring | nullat most 4,000 characters
author.isBotrequiredboolean
fromrequiredstring | null1 to 64 characters
originobject
origin.threadrequiredstring3 to 300 characters
origin.messagestring1 to 300 characters
messagestring1 to 128 characters
setRecord<string, string>keys at most 64 characters; values at most 256 characters
unsetstring[]each at most 64 characters; matches ^[a-z0-9][a-z0-9_.-]*$
ifRecord<string, string | null>keys at most 64 characters
op: "links"
FieldTypeNotes
oprequired"links"
authorrequiredobject
author.idrequiredstring1 to 300 characters
author.handlerequiredstring1 to 256 characters
author.namerequiredstring1 to 256 characters
author.avatarrequiredstring | nullat most 4,000 characters
author.isBotrequiredboolean
fromrequiredstring | null1 to 64 characters
originobject
origin.threadrequiredstring3 to 300 characters
origin.messagestring1 to 300 characters
messagestring1 to 128 characters
linksrequiredobject[]at most 10 items
links[].urlrequiredstring1 to 4,000 characters
links[].messagestring | null1 to 128 characters
links[].snapshotobject | null
links[].snapshot.authorrequiredstring1 to 256 characters
links[].snapshot.textrequiredstringat most 10,000 characters
links[].snapshot.createdAtrequiredstring | nullat most 64 characters
links[].snapshot.filesrequiredobject[]at most 20 items
links[].snapshot.files[].namerequiredstring1 to 1,000 characters
links[].snapshot.files[].urlrequiredstring | nullat most 4,000 characters
links[].unavailablestring | nullat most 300 characters

Example

Terminal window
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"
FieldTypeNotes
kindrequired"message"
messagerequiredstring1 to 128 characters
targetrequiredstring3 to 300 characters
externalrequiredobject
external.threadrequiredstring3 to 300 characters
external.messagerequiredstring1 to 300 characters
filesstring[] | nullat most 10 items; each 1 to 300 characters
kind: "files"
FieldTypeNotes
kindrequired"files"
messagerequiredstring1 to 128 characters
targetrequiredstring3 to 300 characters
filesrequiredstring[] | nullat most 10 items; each 1 to 300 characters
kind: "failed"
FieldTypeNotes
kindrequired"failed"
messagerequiredstring1 to 128 characters
targetrequiredstring3 to 300 characters
errorrequiredstring1 to 500 characters
kind: "thread"
FieldTypeNotes
kindrequired"thread"
messagerequiredstring1 to 128 characters
targetrequiredstring3 to 300 characters
targetKindrequired"channel" | "thread"
causerequired"config" | "request"

Example

Terminal window
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

ParameterTypeNotes
threadrequiredstringin the path

Example

Terminal window
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

ParameterTypeNotes
poststringin the query; 1 to 200 characters
threadstringin the query; 3 to 300 characters
messagestringin the query; 1 to 300 characters

Example

Terminal window
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

ParameterTypeNotes
messagerequiredstring | string[]in the query; 1 to 128 characters; 1 to 100 items; each 1 to 128 characters

Example

Terminal window
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

ParameterTypeNotes
idrequiredstringin the path

Example

Terminal window
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

ParameterTypeNotes
idrequiredstringin the path

Body

FieldTypeNotes
targetrequiredstring3 to 300 characters

Example

Terminal window
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
}

POST /webhooks/{key}

no tokenwebhook

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

ParameterTypeNotes
keyrequiredstringin the path
404 Not Foundno_sync
Terminal window
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

ParameterTypeNotes
keyrequiredstringin the path
channelstringin the query; 1 to 300 characters
limitintegerin the query; 1 to 500

Example

Terminal window
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

ParameterTypeNotes
keyrequiredstringin the path

Body

FieldTypeNotes
eventsrequiredany[]1 to 50 items

Example

Terminal window
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

ParameterTypeNotes
keyrequiredstringin the path

Body (optional)

FieldTypeNotes
idsstring[]at most 100 items; each 1 to 300 characters
404 Not Foundnot_found
Terminal window
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

ParameterTypeNotes
keyrequiredstringin the path
limitintegerin the query; 1 to 50

Example

Terminal window
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

ParameterTypeNotes
keyrequiredstringin the path
idrequiredstringin the path

Body

FieldTypeNotes
leaserequiredstring1 to 64 characters
errorstring1 to 500 characters

Example

Terminal window
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
}

Where the board's history stands: hot, sealed, and cold. Needs manage everywhere.

Parameters

ParameterTypeNotes
live"0" | "1" | "true" | "false"in the query

Example

Terminal window
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
}

POST /archive

configureArchive

Changes the board's archival settings, or runs a pass now. Needs manage everywhere.

Body (optional)

FieldTypeNotes
enabledboolean
sealAfterMsinteger0 to 9,007,199,254,740,991
coldAfterMsinteger0 to 9,007,199,254,740,991
segmentinteger16 to 100,000
keepinteger1 to 9,007,199,254,740,991
everyMsinteger50 to 9,007,199,254,740,991
stepThreadsinteger1 to 1,000
pauseMsinteger0 to 9,007,199,254,740,991
freezeAfterMsinteger0 to 9,007,199,254,740,991
pageThreadsinteger1 to 4,096
runboolean
resetboolean
forgetboolean

Example

Terminal window
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

FieldTypeNotes
channelrequiredstringat most 2,048 characters; matches ^[a-z0-9][a-z0-9_-]*(?:\/[a-z0-9][a-z0-9_-]*)*$
threadsrequiredinteger1 to 10,000
repliesrequiredinteger0 to 1,000
atinteger0 to 9,007,199,254,740,991
spanMsinteger0 to 9,007,199,254,740,991
textinteger1 to 10,000
keyedboolean
prefixstringat most 40 characters
501 Not Implementedno_bench
Terminal window
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
Terminal window
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"
}
}

POST /rpc

rpcBatch

The Board capability over a Cap'n Web HTTP batch.

Example

Terminal window
curl "$WORKBUS_URL/rpc" \
-H "authorization: Bearer $WORKBUS_TOKEN" \
-H 'content-type: text/plain' \
--data-binary @- <<'EOF'
["push",["pipeline",0,["me"],[]]]
["pull",1]
EOF
200 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

Terminal window
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."
}
}

GET /mcp

mcpStream

No server-to-client stream: answers 405, Allow: POST.

405 Method Not Allowed
Terminal window
curl "$WORKBUS_URL/mcp" \
-H "authorization: Bearer $WORKBUS_TOKEN"
allow: POST

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.