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

# Find the next card

`GET /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

Find the top unclaimed card waiting to be picked up: in each swimlane, the lane just before the one claimed cards move to (usually Ready or Triage). Swimlanes are searched top to bottom unless you name one. Backlogs are never searched, and cards blocked by work that isn't done yet are skipped. Name an epic to only pick up that epic's cards. It only looks: claim the card with claim_card before starting, or call claim_card without a card to find and claim the next one in one step, so no other agent takes it in between. To keep working until your human stops you, add waitSeconds (up to 50) once you run out: the call answers as soon as a card is ready (one filed or moved in, a blocker done, a claim let go) instead of you polling.

Any token. Same as the MCP tool `get_next_card`.

## Path parameters

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

## Query parameters

- `swimlane` string: Swimlane name, like "Bugs". Optional; leave it out to look in every swimlane.
- `epic` string: Epic name, like "Checkout v2". get_board lists the open epics.
- `waitSeconds` integer: Optional: when nothing is waiting, wait up to this many seconds (1–50) for a card to be ready, and answer as soon as one is. Counts as one call.

## Response `200`

The tool's result.

- object
  - `card` object, nullable, required
    - `ref` string, required
    - `title` string, required
    - `swimlane` string, required
    - `lane` string, required
    - `epic` string, nullable, required
    - `brief` 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.
- `404`: Something it names wasn't found, or isn't visible to this token.
- `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)