# The capture endpoint

The capture endpoint adds a card to your board from anywhere: a phone shortcut, a launcher script, `andon add`. It
takes a personal **capture token**, so the card is yours, and puts it in the Backlog.

## Address and token

Make a token under **Settings → Connections → Developer → Capture tokens**. It starts `andon_cap_` and is shown once.
Make one per device, so a lost phone can be revoked alone.

| Board | Capture URL |
|---|---|
| The portable server | `https://<your board>/functions/v1/capture` (also `/api/fn/capture`) |
| Supabase | `https://<project-ref>.supabase.co/functions/v1/capture` |

Send `POST <capture URL>` with `Authorization: Bearer <token>`. On the portable server a machine's own access token
works too, and captures for the machine's owner: that is how `andon add` works there without a capture token.

```sh
curl -X POST "$ANDON_CAPTURE_URL" \
  -H "Authorization: Bearer $ANDON_CAPTURE_TOKEN" \
  -H "content-type: application/json" \
  -d '{"title": "Login button overlaps on iPad", "team": "Web"}'
```

## Fields

Send JSON (`content-type: application/json`), or a multipart form with the same fields plus files.

| Field | What it is |
|---|---|
| `title` | The card's title, up to 500 characters. Optional when you send a `url` or a file. |
| `notes` | The card's notes, up to 100,000 characters. |
| `url` | A link the card is about. A web address becomes one of the card's links (a GitHub issue or pull request, a Linear or Jira issue is recognised as one), and an untitled card takes its title. Anything else goes into the notes. |
| `team` | A team, by name or id. A private team the person capturing isn't on counts as none. |
| `project` | A project, by name or id, in a team the person capturing can see. A project alone brings its team. Without one the card goes to the team's General. |
| `group` | An open PR group of that team or project, by name or id, or `new` for a planned group of its own. Needs `team` or `project`. |
| `recipe` | A recipe slug, such as `code-change`. |
| `template` | A card template, by name or id: the team's first, then the org's. An unknown template refuses the capture. |
| files | Multipart only: up to 10 files, any field name, 25 MB each and 30 MB per capture. Each becomes an attachment. |

With no title, a file-only capture is titled `Capture <date and time>`.

## Responses

`201` with:

| Field | What it is |
|---|---|
| `card_id` | The new card's id. |
| `card_key` | Its key, such as `WEB-12`. |
| `path` | Its address on the board, such as `/o/acme/card/WEB-12`: add it to the board's URL to open the card. |
| `link_id` | The linked work item made from `url`, or `null`. |
| `attachments` | The ids of the files attached. |
| `skipped` | How many files couldn't be stored. |
| `group` | The PR group it joined or started (`id`, `name`, `action`), or `null`. |
| `group_error` | Why it couldn't be grouped, or `null`. The card is still made. |

Errors are `{"error": "…"}`:

| Status | When |
|---|---|
| `400` | Nothing to make a card from, notes too long, an unknown template, or a body that isn't JSON or a form. |
| `401` | No token, or a token that is wrong or revoked. |
| `405` | Not a `POST`. |
| `409` | The org has no Backlog column, or the card was made but its template couldn't fill it (the reply has its `card_id`). |
| `413` | More than 10 files, a file over 25 MB, or more than 30 MB in all. |
| `429` | More than 30 captures in a minute on one token. |
| `500` | The server couldn't check the team or project, or couldn't make the card. Send it again. |
