---
title: "List cards"
method: POST
path: "/api/board/{boardId}/list"
tags: ["Cards"]
---

# List cards

`POST /api/board/{boardId}/list`

## Request

- Base URL: `https://core-api.getaptly.com`
- URL: `https://core-api.getaptly.com/api/board/{boardId}/list`
- Auth: one of:
  - API key in header `x-token`
  - API key in header `Authorization`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/getaptly/apis/aptly-api/docs/api/board/:boardId/list/post.ts> (a function with typed inputs; its response is checked against the schema)

Returns a paginated list of cards on the board.

Field values are keyed by field UUID — use the schema endpoint to map keys to labels.
Money fields are returned as `{ amount, currency }` where `amount` is a decimal.

All filter params are optional and ANDed together.

Supply segmentId OR rules (a JSON array), never both. Rules use the existing saved-segment format. Invalid rules fail with 400; missing, private-to-another-user, archived, or wrong-board segments return 404.

Auth: API key, delegate token (boards:* or boards:{boardId} read scope), or partner bearer token with board-admin. Mobile tokens are not accepted. Keys/delegates require API-enabled boards; partner access retains its existing API-enabled bypass. API keys/partners may supply userId for an active company member; delegates can only use their token user. Without userId only public segments are visible. Public means company-shared.

This /list POST performs no writes and does not change POST /api/board/{boardId}, which creates/updates cards. Rules are ANDed. Relative dates are evaluated on each request. See the Board segments guide for values, field comparisons, business-hours rules, and examples.

## Path parameters

- `boardId` string, required

## Request body

- BoardCardListRequest: Read-only card listing. Supply segmentId OR rules; existing simple filters intersect with either. Segment/rule queries exclude deleted cards unless explicitly selected by a rule. No filter or card is saved. Saved segments must contain a rules array; missing or malformed rules require re-saving. An explicitly empty rules array matches all cards within the remaining filters.
  - `page` integer, required: Zero-based page number.
  - `pageSize` integer: Number of cards per page.
  - `updatedAtMin` string, date-time: Only return cards updated after this ISO timestamp.
  - `includeArchived` boolean: Include archived cards. If omitted, an explicit archived rule controls archive selection; otherwise active cards only. An explicit false intersects with the rules.
  - `relatedId` string: Only return cards where `references.value` contains this ID.
  - `contactEmail` string: Resolves the email to contact IDs, then filters cards referencing those contacts.
  - `keyTerm` string: Full-text autocomplete search on card title using the Atlas Search index.
  - `assignee` string: Filter cards by assignee user ID.
  - `segmentId` string: Existing accessible, active segment on this board; mutually exclusive with rules.
  - `rules` BoardFilterRule[]: Ad hoc saved-segment rules, ANDed together. Requires an explicit board. Supply rules OR segmentId. Invalid rules are rejected.
    - `fieldUuid` string, required: Field uuid from the board catalog (HIRO: get_board_fields.fields); system fields include assignee, stage, updatedAt.
    - `key` string: Exact filter key from the field's filters array. Required to select a subfield when one uuid has multiple filters.
    - `operator` string, required: Supported operator from the filter's operatorSet in the catalog's operatorSets dictionary. Greater-than is spelled gratherThan for saved-rule compatibility.
    - `value` unknown
    - `valueSource` 'currentUser': For user anyIn/notIn rules, resolves the authenticated/selected user on the server. Omit value.
    - `valueFieldUuid` string: Optional comparison field uuid or catalog key; equal, notEqual, lessThan, gratherThan only. Omit value.
    - `defaultValueField` string: Optional catalog field/key used if the filtered field is missing.
  - `userId` string: Active company member whose private segments/currentUser values to use. API keys/partners may select a member; delegates cannot select another user.

## Response `200`

Paginated list of cards.

- object
  - `data` Card[]
    - `cardId` string: Unique ID of the card.
    - `boardUuid` string: UUID of the board this card belongs to.
    - `archived` boolean
    - `assignee` string: Full name of the assigned user.
    - `lastActivity` object, nullable: Most recent conversation activity on the card (email, SMS or call), or null if the card has none.
      - `content` string, nullable: Body/text preview of the most recent message.
      - `type` string, nullable: Activity type, e.g. `email`, `sms`, `voice`.
      - `direction` 'in' | 'out', nullable: Direction of the message — `in` (inbound) or `out` (outbound).
      - `publishedAt` string, date-time, nullable
      - `conversationUrl` string, nullable: Deep link to the conversation thread in Aptly. Null when the activity is not attached to a thread.
  - `count` integer: Total number of matching cards.
  - `page` integer
  - `pageSize` integer

## Other responses

- `400`: Invalid rules, query parameters, or missing user context.
- `401`: Invalid or missing API key.
- `403`: Read access denied, API disabled, company mismatch, or invalid user selection.
- `404`: Board or accessible active segment not found.

---

[API](https://skmtc.dev/getaptly/apis/aptly-api.md) - [All operations](https://skmtc.dev/getaptly/apis/aptly-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getaptly/apis/aptly-api/revisions/75c367e0b8e5?raw)