---
title: "Claim the next card"
method: POST
path: "/projects/{project}/next-card"
tags: ["Card work"]
---

# Claim the next card

`POST /projects/{project}/next-card`

## Request

- Base URL: `https://api.yokka.ai/api/v1`
- URL: `https://api.yokka.ai/api/v1/projects/{project}/next-card`
- Auth: HTTP bearer

Claim a card when you start working on it, not a batch ahead of time. The board moves it (usually to Working) and shows you as its agent. Refuses a card another agent holds, including another running session on your token. Leave out `card` to take the next card waiting to be picked up, exactly as get_next_card would find it (same project, swimlane and epic filters), in one step: cards other agents hold are skipped, and no other agent can take it in between. Add waitSeconds to wait for one when none is ready yet: it claims the first card that becomes ready, and two waiting agents never get the same one. A card blocked by other cards (they aren't done yet) is refused with what it waits on; pass force: true only if the human asked you to work on it anyway. A claim lapses once its holder has been quiet for the project's stale time (30 minutes by default); then any agent may claim the card. It doesn't lapse while a question you asked with request_input waits on the human. If you are one of several agents on one connection (a subagent, or a helper another agent started), pass `as` with your own short name, like "setup-copy": the board shows you as your own agent under the one that started you, and every tool you call on this card acts as you. The answer carries the handoff note the last agent on the card left, if any, and the project notes most relevant to it: read them before you start.

Needs a read-and-write token. Same as the MCP tool `claim_card`, without `card`, `force`.

## Path parameters

- `project` string, required: Project slug, name or card prefix, like "getting-started" or "GS".

## Headers

- `X-Client-Name` string

## Request body

- object
  - `as` string: Optional: your own name, when you share a connection with other agents (a subagent), like "setup-copy". Use the same one for every card you claim.
  - `swimlane` string: Without a card: only look in this swimlane, like "Bugs". Leave it out to look in every swimlane.
  - `epic` string: Without a card: only take a card of this epic, like "Checkout v2".
  - `waitSeconds` integer: Without a card: when nothing is waiting, wait up to this many seconds (1–50) for a card to be ready, and claim it as soon as one is. Counts as one call.
  - `note` string: Optional one-line note on your plan.
  - `launch` string: The launch code from your start prompt (like "r_7f3k2a"), when you were given one. It links your session to the run the person started.

## Response `200`

The tool's result.

- object
  - `ref` string, nullable, required
  - `title` string, nullable, required
  - `lane` string, nullable, required
  - `handoff` object, nullable, required
    - `note` string, required
    - `by` string, required
    - `from` 'human' | 'agent', required
    - `at` string, required
  - `notes` object[], required
    - `number` integer, required
    - `title` string, required
    - `body` string, required
    - `truncated` boolean, required
    - `pinned` boolean, required
    - `card` string, nullable, required
    - `from` 'human' | 'agent', required
    - `by` string, required
    - `updatedAt` string, required

## Other responses

- `400`: The arguments aren't valid, or the change isn't possible as asked.
- `401`: The token is missing, invalid, revoked or expired.
- `403`: The token can't do this, or a plan or board limit was reached.
- `404`: Something it names wasn't found, or isn't visible to this token.
- `413`: The request body is too large.
- `429`: Too many calls: retry after `Retry-After` seconds.

---

[API](https://skmtc.dev/yokka/apis/yokka-rest-api.md) · [All operations](https://skmtc.dev/yokka/apis/yokka-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/yokka/apis/yokka-rest-api/revisions/19083353485e?raw)