---
title: "Find cards"
method: GET
path: "/cards"
tags: ["Board"]
---

# Find cards

`GET /cards`

## Request

- Base URL: `https://api.yokka.ai/api/v1`
- URL: `https://api.yokka.ai/api/v1/cards`
- Auth: HTTP bearer

Search cards by text in the title or brief, label, epic, swimlane or lane, across every active project unless you name one (name an archived project to search it). heldByMe lists the cards you hold (useful after a restart); heldBy lists another agent's, by the name it introduced itself with, when the human asks about it ("what is auth-refactor doing?"). needsHuman lists cards waiting on the human. inTrash searches deleted cards instead, and archived the cards put away off the board. Backlogs are included. Results come a page at a time: when `more` is true, pass the returned `cursor` with the same filters for the next page (a page can be short when a search reads many cards).

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

## Query parameters

- `project` string: Optional project slug, name or card prefix. Omit to search every active project.
- `text` string: Words to look for in the title or brief.
- `label` string: Only cards with this label.
- `epic` string: Only cards in this epic.
- `swimlane` string: Only cards in this swimlane.
- `lane` string: Only cards in lanes with this name, like "Ready".
- `heldByMe` boolean: Only cards you hold, and your helpers' (agents that claimed with `as`).
- `as` string: Optional: the name you claim with (`as` on claim_card), so held_by_me lists only your cards.
- `heldBy` string: Only cards held by this agent, including ones it finished: its name ("auth-refactor") or its client's ("codex"). Agents seen today only.
- `needsHuman` boolean: Only cards flagged for the human.
- `inTrash` boolean: Search deleted cards instead of live ones.
- `archived` boolean: Search archived cards instead of live ones.
- `limit` integer: Optional, 1–100 cards a page (default 30).
- `cursor` string: Optional: the cursor a previous page returned, to read the next one.

## Response `200`

The tool's result.

- object
  - `cards` object[], required
    - `ref` string, required
    - `title` string, required
    - `project` string, required
    - `swimlane` string, nullable, required
    - `lane` string, nullable, required
    - `backlog` boolean, required
    - `labels` string[], required
    - `epic` string, nullable, required
    - `priority` string, nullable, required
    - `attention` string, nullable, required
    - `holder` string, nullable, required
    - `heldByYou` boolean, required
    - `blocked` boolean, required
    - `deletedAt` string, nullable, required
    - `archivedAt` string, nullable, required
  - `more` boolean, required
  - `cursor` string, nullable, 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)