Skip to content
AndonDocs
GitHub
Look something up

The public API and webhooks

View as MarkdownThe same text, at this page's address plus .mdOpen in ClaudeAsk questions about this pageOpen in ChatGPTAsk questions about this page

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:

shell
curl -H "Authorization: Bearer $ANDON_TOKEN" https://andon.example.com/api/v1/cards?q=label:bug

A 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}. Pass limit (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>"}: 400 for a bad parameter or body, 401 for no token or a token that is invalid, expired or revoked, 403 for a missing scope or something the person may not do, 404 for something that doesn’t exist or that the person can’t see, 409 for a conflict, 413 for a body over 1 MB, and 415 for 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 its role (what column takes below).
  • GET /api/v1/projects: org, team, status, archived.
  • GET /api/v1/pr-groups: org, team, project, state (open by 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 with org, team, project, group, column, key (comma-separated keys), updated_since (ISO 8601), archived, and q, which takes the board’s filter bar language (saved views): q=label:bug -role:done priority:>=high login. In q, me is the person the token acts as. A q query 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 in assignee: (me, none and ids do) and cycle:current|next.

    Here column takes a column’s role: backlog, agent_ready, doing, review or done, the value a card’s column_role holds. The words ready and working are refused here (400), though making and moving a card take them: ?column=doing lists 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}. Only team (a key or an id) and title are required. column takes backlog (the default), ready, working, review or done, or the roles agent_ready and doing. Answers 201 with the card.

  • PATCH /api/v1/cards/{card} (cards:write): any of title, notes, priority, labels, project, owner, due_on, estimate, archived. null clears a field; a field left out stays as it is.

  • POST /api/v1/cards/{card}/move (cards:write): {"column": "review", "index": 0}. column takes the same words and roles as making a card. index counts 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 empty body and deleted: 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": "…"}. start is the default. continue sends text to 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), with secret_rotated_at and, during a rotation’s grace period, previous_secret_expires_at.
  • POST /api/v1/webhooks: {"url": "https://…", "events": ["card.created"], "description": "…"}. Answers 201 with the webhook and its secret, shown this once.
  • PATCH /api/v1/webhooks/{webhook}: any of url, events, description, active. Only the admin who added a webhook changes its url (403 for 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 new secret, shown this once, and previous_secret_expires_at: until then deliveries are signed with the old secret too (null with grace_hours: 0, or when there was no old secret).
  • POST /api/v1/webhooks/{webhook}/ping: sends a ping event 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:

JSON
{
"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 two v1s, 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:

JavaScript
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.