The public API and webhooks
Scripts, CI and other tools read and write cards without the board. They use /api/v1 with an org’s API token, and
webhooks tell them when something changes. The machine-readable contract is the OpenAPI 3.1 document at
/api/v1/openapi.json. This page is the readable one, and a test (apps/server/test/api/docs.test.ts) fails when
the two disagree.
Where it runs: the API is part of the portable server (apps/server: andon up, Docker, Vercel + Postgres).
A board on Supabase has no /api/v1. Webhooks are sent by the portable server’s webhooks-deliver
job.
Tokens
Settings → Connections → Developer → API tokens, owners and admins only. A token has:
- a name, so you know what it’s for (“GitHub Actions”, “nightly report”);
- scopes: what it may do (below). Pick only what the script needs;
- acts as: the member whose access it has. By default that’s you; you can choose another member, but not one whose role is above yours (an admin’s token can’t act as an owner), nor one on a private team you aren’t on (the token would read that team for you). Everything the token does runs as that person, under the same rules the board applies to them. It sees only the teams they see, and a card it makes is owned by them. The token can’t do anything that person couldn’t;
- an optional expiry.
The token (andon_pat_ and 48 hex characters) is shown once, when you make it. Andon keeps only its SHA-256, so a
lost token can’t be shown again: revoke it and make a new one. Revoking takes effect at once. A token also stops
working when the person it acts as leaves the org. Making and revoking tokens go into the audit log
(api_token.create, api_token.revoke), with the scopes and the member each token acts as.
Send it as a bearer token:
curl -H "Authorization: Bearer $ANDON_TOKEN" https://andon.example.com/api/v1/cards?q=label:bugA token reaches its own org only. The board’s session cookie and a person’s or machine’s access token also work on
every route, with every scope, across every org that caller is in; pass org (a slug or an id) to narrow it. A
write on the session cookie must be sent as application/json (else 415), so a form on another site can’t make one.
Scopes
| Scope | Allows |
|---|---|
cards:read |
Read teams, projects, PR groups, cards and their comments |
cards:write |
Create, update and move cards |
comments:write |
Comment on cards |
runs:read |
Read runs and what needs attention |
runs:start |
Start, continue and retry runs |
webhooks |
Manage webhooks and their deliveries |
A card moved (or made) into Working starts a run, so that also needs runs:start. Managing webhooks also needs the
person behind the token to be an owner or admin. A missing scope is a 403 that names it:
{"error": "this token lacks the runs:read scope"}.
Requests and responses
- JSON in and out. Bodies are at most 1 MB and reject unknown fields. A bigger body is refused with
413({"error": "request body too large"}). - Lists return
{"data": [...], "next_offset": n | null}. Passlimit(1 to 500, default 100) and, for the next page,offset=<next_offset>. - Cards are addressed by key (
WEB-12; any key a card had still finds it after a move) or by id. - Errors are
{"error": "<what went wrong>"}:400for a bad parameter or body,401for no token or a token that is invalid, expired or revoked,403for a missing scope or something the person may not do,404for something that doesn’t exist or that the person can’t see,409for a conflict,413for a body over 1 MB, and415for a write on the session cookie that isn’t JSON.
Operations
Reference
GET /api/v1/openapi.json: the OpenAPI document (no token needed).GET /api/v1/events: the events a webhook can subscribe to.
Teams, columns, projects, PR groups (cards:read)
GET /api/v1/teams:org,archived.GET /api/v1/columns:org; the board’s columns in order, each with itsrole(whatcolumntakes below).GET /api/v1/projects:org,team,status,archived.GET /api/v1/pr-groups:org,team,project,state(openby default,all, or a state),implicit.GET /api/v1/pr-groups/{id}: one group with its cards in order.
Cards
-
GET /api/v1/cards(cards:read): filter withorg,team,project,group,column,key(comma-separated keys),updated_since(ISO 8601),archived, andq, which takes the board’s filter bar language (saved views):q=label:bug -role:done priority:>=high login. Inq,meis the person the token acts as. Aqquery reads up to 5,000 of the person’s cards before paging. Two parts of the language don’t work over the API yet: people’s names inassignee:(me,noneand ids do) andcycle:current|next.Here
columntakes a column’s role:backlog,agent_ready,doing,reviewordone, the value a card’scolumn_roleholds. The wordsreadyandworkingare refused here (400), though making and moving a card take them:?column=doinglists the cards in Working. -
GET /api/v1/cards/{card}(cards:read): one card. -
POST /api/v1/cards(cards:write):{"team": "WEB", "title": "…", "notes": "…", "project": "<id>", "column": "backlog", "priority": 0-3, "labels": [], "due_on": "2026-12-01", "estimate": 3}. Onlyteam(a key or an id) andtitleare required.columntakesbacklog(the default),ready,working,reviewordone, or the rolesagent_readyanddoing. Answers201with the card. -
PATCH /api/v1/cards/{card}(cards:write): any oftitle,notes,priority,labels,project,owner,due_on,estimate,archived.nullclears a field; a field left out stays as it is. -
POST /api/v1/cards/{card}/move(cards:write):{"column": "review", "index": 0}.columntakes the same words and roles as making a card.indexcounts from the top of the column, and the card goes to the bottom without it.
A card in a response carries id, org_id, key, number, title, notes, team_id, team_name,
project_id, project_name, pr_group_id, parent_card_id, column_id, column_role, column_name, priority,
labels, owner_id, due_on, estimate, cycle_id, archived, run_id, run_status, created_at and
updated_at.
Comments
GET /api/v1/comments(cards:read):card(required), oldest first. A deleted comment keeps its place, with an emptybodyanddeleted: true.POST /api/v1/comments(comments:write):{"card": "WEB-12", "body": "…", "reply_to": "<comment id>"}. The comment is written by the person the token acts as. A reply to a reply joins its thread, as on the board.
Runs and attention
GET /api/v1/runs(runs:read):org,card,status; newest first.GET /api/v1/runs/{id}(runs:read): one run.POST /api/v1/runs(runs:start):{"card": "WEB-12", "kind": "start" | "retry" | "continue", "text": "…"}.startis the default.continuesendstextto the card’s live session, or resumes it, as the board’s reply box does. The card needs a recipe, and the run waits in the queue for a machine like any other run.GET /api/v1/attention/items(runs:read): the org’s raw attention items (key,kind,severity,card_id,run_id,title,detail,since). This is not/api/v1/attention, which belongs to the instances API that connected instances and the desktop app read. It takes a session, or a connect token while connecting instances is on, and returns the person’s ranked rows.
Connected instances (experimental, off by default)
Connecting one Andon instance to another is experimental, and the server serves it only with
ANDON_INSTANCE_CONNECT set to on. The connect flow (/api/v1/connect/authorize, /api/v1/connect/token),
a home instance’s connections (/api/v1/connections, /api/v1/home) and the rail check (/api/v1/rail/check) answer
404 while it is off. A connect token on /api/v1/attention or /api/v1/attention/action is refused with 403,
including tokens granted while it was on, and works again once it is turned back on. /api/v1/info says which ("connect": true or false). A signed-in session’s
/api/v1/attention and its actions, and the list of grants to revoke (/api/v1/connect/grants), answer either way.
While it is on, a connect token lasts a year. It ends earlier when it is revoked, the person’s password is reset or changed, or their account is banned or deleted.
Webhooks (webhooks, owners and admins)
GET /api/v1/webhooks: the org’s webhooks (never their secrets), withsecret_rotated_atand, during a rotation’s grace period,previous_secret_expires_at.POST /api/v1/webhooks:{"url": "https://…", "events": ["card.created"], "description": "…"}. Answers201with the webhook and itssecret, shown this once.PATCH /api/v1/webhooks/{webhook}: any ofurl,events,description,active. Only the admin who added a webhook changes itsurl(403for anyone else), because it hears what that admin sees.DELETE /api/v1/webhooks/{webhook}: the webhook and its delivery log.POST /api/v1/webhooks/{webhook}/rotate-secret:{"grace_hours": 24}(0 to 168; the body may be left out, for 24). Answers with the webhook and its newsecret, shown this once, andprevious_secret_expires_at: until then deliveries are signed with the old secret too (nullwithgrace_hours: 0, or when there was no old secret).POST /api/v1/webhooks/{webhook}/ping: sends apingevent now.GET /api/v1/webhooks/{webhook}/deliveries: the delivery log, newest first.POST /api/v1/webhook-deliveries/{id}/redeliver: sends a delivery again.
Webhooks
Settings → Connections → Developer → Webhooks, or the routes above. A webhook has a URL (https://, or http:// for a local
receiver), the events it hears, and a signing secret (whsec_…) that is shown once. Each webhook acts as the admin
who made it. It hears only about cards on teams that person can see, and it stops when they leave the org. So only
that admin may point it at another URL, and another owner or admin sees a delivery in its log only when they see the
card’s team too: a private team’s cards stay hidden from owners and admins who aren’t on it.
The signing secret is kept encrypted, as an integration’s token is: in Vault on Supabase, and on the portable server
in andon_private.secrets, encrypted with the server’s ANDON_SECRET_KEY (AES-256-GCM;
andon-server rotate-secrets re-encrypts it after a key change). The webhook’s row holds only a reference to it, and
no person’s request can read it back: only the delivery worker’s claim decrypts it, to sign.
Rotating the secret
Rotate secret on a webhook (or POST /api/v1/webhooks/{webhook}/rotate-secret) makes a new secret and shows it
once. Choose how long the old one keeps signing: for that grace period (an hour, a day by default, or up to a week)
each delivery carries a signature for both secrets, so you can deploy the new secret to your receiver without missing
a delivery. Once it is over the old secret is forgotten. If the old secret leaked, rotate with no grace
(grace_hours: 0): it stops at once. Rotations are in the audit log.
A webhook made on a portable server before secrets were encrypted has no secret: its deliveries fail with “the webhook has no signing secret” until an owner or admin rotates it.
Events
packages/shared’s EVENT_TYPES is the source.
| Event | When |
|---|---|
card.created |
A card was made |
card.updated |
A card’s title, notes, priority, labels, project, owner, due date or estimate changed |
card.moved |
A card moved to another column |
card.archived |
A card was archived |
comment.created |
Someone (or a run’s agent) commented on a card |
run.started |
A run started working |
run.needs_input |
A run is waiting for a person |
run.finished |
A run finished: review, done, ended, failed or cancelled |
pr_group.state_changed |
A PR group was planned, started building, went to review, merged or was abandoned |
ping is the test event. Nobody subscribes to it.
A delivery
A POST with a JSON body:
{ "id": "6c1e…", // the event's id: the same on a redelivery, so dedupe on it "type": "card.moved", "created_at": "2026-11-08T19:10:39Z", "org_id": "…", "data": { "card": { "id": "…", "key": "WEB-12", "title": "…", "column": { "role": "review", "name": "Review" }, … }, "from": { "role": "doing", "name": "Working" } }}data holds card for card events (plus from on card.moved and changed, the fields that changed, on
card.updated). Comment events add comment, run events add run and its card, and pr_group.state_changed holds
pr_group (its previous_state is null when the group was just made).
Headers:
andon-event: the event type;andon-delivery: this delivery’s id (a redelivery gets a new one);andon-signature:t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" with the secret>. During a rotation’s grace period it has twov1s, the new secret’s first:t=…,v1=<new>,v1=<old>.
Check the signature on the raw body before parsing it. Accept it when any v1 matches, and refuse it if t is
more than five minutes away from your clock, so a captured delivery can’t be replayed later:
import { createHmac, timingSafeEqual } from 'node:crypto';
function verify(secret, rawBody, header, now = Math.floor(Date.now() / 1000)) { const parts = header.split(',').map((p) => p.split('=')); const t = Number(parts.find(([k]) => k === 't')?.[1]); if (!Number.isInteger(t) || Math.abs(now - t) > 300) return false; const want = Buffer.from(createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex')); // Compare byte lengths (a non-ASCII v1 is longer in bytes than in characters, and timingSafeEqual throws on a mismatch). return parts.some(([k, v]) => k === 'v1' && Buffer.byteLength(v ?? '') === want.length && timingSafeEqual(want, Buffer.from(v)));}Retries and the delivery log
Answer with any 2xx within 10 seconds. Andon doesn’t follow redirects and keeps only the status of your answer (never
its body). Before each delivery it looks up the receiver’s host, and never posts to a link-local address or a cloud
metadata service, or to a private or loopback address unless the server sets
ANDON_ALLOW_PRIVATE_NETWORK (a self-hosted Andon whose receiver is on its own network). Anything else (another status, a timeout or
a refused connection) is retried after 30 s, 2 min, 8 min, 32 min, about 2 h, then every 6 h. A delivery is marked
failed after 8 attempts, about 15 hours after the first. The delivery log under each webhook keeps 30 days: every delivery’s
status, attempts, last HTTP status and error, and its payload. Redeliver queues any delivery again, as a new
delivery of the same event. A webhook that is switched off keeps its pending deliveries until it is switched back on.
Deliveries go out as soon as the change commits: the database queues them and wakes the sender. A once-a-minute tick picks up retries. On Vercel’s Hobby plan, that tick runs only as often as the server’s cron or a machine’s heartbeat.
The andon CLI
On the portable server, the card commands (andon show, edit, move, archive, comment, list and the rest)
wrap these routes: see the andon command. They send a personal API token when one is saved
(andon api-token, or ANDON_API_TOKEN), so the board shows the person. Without one they use the machine’s own
token, which reads the org’s cards but can’t change them (a 403). A
run’s MCP tools don’t use this API: they act as the run, on its own card.
