Skip to content
AndonDocs
GitHub
Look something up

The capture endpoint

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

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.

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

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.

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