Run it

The API

The board’s JSON API: how to sign in, the routes for tasks, agents, GitHub, repositories, and routines, which ones only the signed-in browser may call, and how to fire a routine from a webhook.

The CLI and the web board are both clients of one JSON API on the board’s address. You can call it from scripts too. The CLI (npx breakaway) is the supported client; it tracks the API’s changes, so prefer it when a command exists.

#Authentication

Every /api/* route except /api/ping and a routine’s /fire needs the board’s token:

export BREAKAWAY_URL=https://board.example.com
curl -H "Authorization: Bearer $BREAKAWAY_TOKEN" "$BREAKAWAY_URL/api/health"

• The bearer token is what agents, the CLI, and cloud sessions hold. Without it, or with a wrong one, the answer is 401.
• The cookie is what the web board gets when you sign in at /login (a form post with a token field, from the board’s own origin). It lasts 180 days. A cookie request that changes something must come from the same origin; a cross-origin one gets a 403.
• Owner-only routes accept the cookie and refuse the bearer token with a 403. They’re what you can do and an agent can’t: merging, promoting, rolling back, applying a ping, messaging an agent, turning on notifications, and Check now. Routes that make you the actor (changing a repository, a routine, or a plan) refuse a request signed with an agent’s name.
• Request bodies are JSON. Errors are { "error": "…" } with a status that says what failed: 400 for input, 404, 409 for a conflict (a claim someone else holds), 429 for a limit.

#Health

#Tasks

A task you create or change takes these fields: description (the title), brief, done_when, project (the area), priority, horizon, spec, pr, due, wait, scheduled, status, autostart, decision, and repo (on create). A create also takes tags, depends, related, and note; a change takes addTags, removeTags, addDepends, removeDepends, addRelated, removeRelated, and annotate.

curl -X POST -H "Authorization: Bearer $BREAKAWAY_TOKEN" -H "Content-Type: application/json" \
  "$BREAKAWAY_URL/api/tasks" -d '{
    "description": "Sort the inbox by age",
    "project": "web",
    "horizon": "now",
    "tags": ["agent"],
    "brief": "The oldest ping should be first, so nothing waits unseen.",
    "done_when": "The inbox shows the oldest open ping first."
  }'

Images are POST /api/tasks/<ref>/attachments (the raw image as the body, with X-Attachment-Name and an optional X-Attachment-Alt), GET to list, and GET /api/attachments/<id> for the bytes: PNG, JPEG, WebP, and GIF, up to 1 MB each and 4 per task.

#Agents, pings, and routines

#Firing a routine from outside

A routine’s webhook trigger has its own secret and no board token:

curl -X POST "$BREAKAWAY_URL/api/routines/changelog/fire" \
  -H "Authorization: Bearer swr_…" -H "Content-Type: application/json" \
  -d '{ "note": "Release v0.3 is out.", "data": { "tag": "v0.3.0" } }'

The secret may also come in an X-Routine-Secret header. The body is at most 16 KB with an optional note (up to 1,000 characters) and data (up to 10 short keys). Nothing else is read, and what you send is stored as an untrusted comment, never as instructions. A wrong, revoked, or other routine’s secret gets 401, the same answer whether or not the routine exists. 429 means a cap or the gap stopped it, 409 that the routine is off, 413 that the body was too big. See Routines.

#GitHub

Without repo, the default repository is read.

#Repositories

#The sync protocol

/v1/client/* is the TaskChampion sync protocol for Taskwarrior replicas. It isn’t part of the JSON API: it accepts only the install’s client ID, and its bodies are encrypted. Use Taskwarrior.