# 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:

```sh
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](https://andon-docs.pages.dev/guide/views.md)): `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`](https://andon-docs.pages.dev/reference/env.md) 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:

```jsonc
{
  "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 `v1`s, 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:

```js
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`](https://andon-docs.pages.dev/reference/env.md) (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](https://andon-docs.pages.dev/reference/cli.md#cards). 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](https://andon-docs.pages.dev/reference/mcp-tools.md) don't use this API: they act as the run, on its own card.
