--- title: "List cards on a readable board" method: GET path: "/api/boards/{boardId}/cards" tags: ["Cards"] --- # List cards on a readable board `GET /api/boards/{boardId}/cards` ## Request - Base URL: `https://tre-app.com` - URL: `https://tre-app.com/api/boards/{boardId}/cards` - Auth: HTTP bearer Same `titleContains`/`textContains`/`view`/`includeDeleted` contract as MCP `list_cards` (`cardListQuerySchema` in lib/schemas/card.ts validates both). `titleContains` filters server-side, case-insensitively, on card title. `textContains` (W3-D1) matches case-insensitively on title, description, comment bodies, checklist items AND subtask titles — several words mean every word, each anywhere on the card, an `ALIASES:` line searched like any text (since 2026-10-16) — always answers `view=summary` (any other view is refused with 400) and adds `match: { field, snippet }` — the first field holding every word (title, description, comment, checklist, subtask), or, when the words are spread over fields, the first holding one of them, with a snippet of at most 120 characters; combines with `updatedSince` (ISO datetime) and `citing` (a cardKey: cards whose citation graph points at it) — both of which also apply on their own, at every `view` but `lint`, which answers every card that needs care and ignores the filters. `view` defaults to `full` — today's complete card payload, byte-for-byte unchanged. `view=summary` returns only `id`, `cardKey`, `title`, `listId`, `startDate`, `endDate`, `scheduleState`, `actualStartDate`, `actualEndDate`, `verifiedOn`, `updatedAt`, `statusDate`, `stale` (plus `match` under `textContains`) — never `description`, `links`, `verificationSource` or `assigneeUserIds` — to locate a card cheaply before `GET /api/cards/{cardId}`. `statusDate` is the dated STATO (or AGGIORNATO) line read from the description's labelled layout, null when neither carries a date; `stale` is true when that date is more than 14 days old. `includeDeleted=true` is exclusive trash: only cards with `deletedAt` set, `listId` may be null. ## Query parameters - `titleContains` string - `textContains` string - `updatedSince` string, date-time - `citing` string - `view` 'full' | 'summary' | 'lint' - `includeDeleted` boolean ## Response `200` Success - union - CardsResponse - `cards` Card[], required - `id` string, uuid, required - `boardId` string, uuid, required - `listId` string, uuid, required - `cardNumber` integer, required - `cardKey` string, required - `title` string, required - `description` string, required - `color` string, required - `order` integer, required - `startDate` string, date, nullable, required - `endDate` string, date, nullable, required - `scheduleState` 'unclassified' | 'planned' | 'suspended' | 'cancelled', required: Meaning of the retained schedule. Unclassified means its intent has not been reviewed; suspended/cancelled retain the plan for retrospective comparison. - `actualStartDate` string, date, nullable, required: Observed start, explicitly recorded from evidence. Independent of the schedule; null means unknown, never not started. - `actualEndDate` string, date, nullable, required: Observed end, explicitly recorded from evidence. May fall outside the plan. Null means unknown, never incomplete. - `verifiedOn` string, date, nullable, required: Day the named source was actually checked, never later than the server UTC day. Independent of updatedAt and the status date in the description; never advance for editorial work. - `verificationSource` string, nullable, required: Source reference and scope of the last factual verification (document, record, URL or cardKey). Set or clear together with verifiedOn. - `links` object[], required - `label` string, required - `url` string, required - `createdAt` string, date-time, required - `updatedAt` string, date-time, required - `createdByUserId` string, uuid, nullable, required - `assigneeUserIds` string[], required - `kind` 'control' | 'work' | 'reference' | 'decision' | 'digest' | 'guidance', nullable, required - CardSummariesResponse - `cards` CardSummary[], required - `id` string, uuid, required - `cardKey` string, required - `title` string, required - `listId` string, uuid, required - `startDate` string, date, nullable, required - `endDate` string, date, nullable, required - `scheduleState` 'unclassified' | 'planned' | 'suspended' | 'cancelled', required: Meaning of the retained schedule. Unclassified means its intent has not been reviewed; suspended/cancelled retain the plan for retrospective comparison. - `actualStartDate` string, date, nullable, required: Observed start, explicitly recorded from evidence. Independent of the schedule; null means unknown, never not started. - `actualEndDate` string, date, nullable, required: Observed end, explicitly recorded from evidence. May fall outside the plan. Null means unknown, never incomplete. - `verifiedOn` string, date, nullable, required: Day the named source was actually checked, never later than the server UTC day. Independent of updatedAt and the status date in the description; never advance for editorial work. - `updatedAt` string, date-time, required - `statusDate` string, date, nullable, required - `stale` boolean, required - `match` object - `field` 'title' | 'description' | 'comment' | 'checklist' | 'subtask', required - `snippet` string, required - CardLintsResponse - `cards` CardLint[], required - `cardKey` string, required - `title` string, required - `findings` string[], required: Findings from the closed set — advice, never a write refusal. `orphan` means no citation in or out on boards the caller can read; `unresolved_reference` means no card the caller can read resolves a named key — a card on a private board the caller is not a member of reads as absent for both; `missing_status` means neither a STATUS/STATO nor an UPDATED/AGGIORNATO line, on an open card whose kind is not reference, digest, guidance or control. `duplicate_status` names a card with more than one STATUS/STATO section — the most recent date is the one read. `overdue` (since 2026-09-26) means the card itself, or one of its subtasks, has a planned end strictly before today (the server UTC date) with no observed end (`actualEndDate`); `stale_verification` means the card was verified (`verifiedOn`) before the dated STATUS/UPDATED line of a card its description cites — re-read the source or accept the drift in a dated comment. `status_log` (since 2026-10-15) means the STATUS/STATO block reads as a chronology — two or more clock times, or three or more dates inside its text: keep STATUS to where things stand and put the chronology in one dated comment. A closed card — `actualEndDate` set, or `scheduleState: cancelled` — is never `stale_status`, `missing_status`, `overdue`, `stale_verification` or `status_log`. - TrashedCardsResponse - `cards` TrashedCard[], required - `id` string, uuid, required - `boardId` string, uuid, required - `listId` string, uuid, nullable, required - `cardNumber` integer, required - `cardKey` string, required - `title` string, required - `description` string, required - `color` string, required - `order` integer, required - `startDate` string, date, nullable, required - `endDate` string, date, nullable, required - `scheduleState` 'unclassified' | 'planned' | 'suspended' | 'cancelled', required: Meaning of the retained schedule. Unclassified means its intent has not been reviewed; suspended/cancelled retain the plan for retrospective comparison. - `actualStartDate` string, date, nullable, required: Observed start, explicitly recorded from evidence. Independent of the schedule; null means unknown, never not started. - `actualEndDate` string, date, nullable, required: Observed end, explicitly recorded from evidence. May fall outside the plan. Null means unknown, never incomplete. - `verifiedOn` string, date, nullable, required: Day the named source was actually checked, never later than the server UTC day. Independent of updatedAt and the status date in the description; never advance for editorial work. - `verificationSource` string, nullable, required: Source reference and scope of the last factual verification (document, record, URL or cardKey). Set or clear together with verifiedOn. - `links` object[], required - `label` string, required - `url` string, required - `createdAt` string, date-time, required - `updatedAt` string, date-time, required - `createdByUserId` string, uuid, nullable, required - `assigneeUserIds` string[], required - `kind` 'control' | 'work' | 'reference' | 'decision' | 'digest' | 'guidance', nullable, required - `deletedAt` string, date-time, required ## Other responses - `400`: Invalid request - `401`: Unauthenticated - `403`: Forbidden: insufficient role or token scope; scope denials name the held scope and the operation - `404`: Not found - `409`: Conflict - `429`: Rate limited - `500`: Internal server error - `503`: Temporarily unavailable --- [API](https://skmtc.dev/tre-app/apis/tre-rest-api.md) · [All operations](https://skmtc.dev/tre-app/apis/tre-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tre-app/apis/tre-rest-api/revisions/26a7187a05fc?raw)