Cards

List cards

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.

post/api/board/{boardId}/list

Request

Base URL
https://core-api.getaptly.com
Auth
- API key in header x-token
- or API key in header Authorization
- or 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.

Path parameters

boardIdstring required

The board's UUID.

Request body

pageinteger required

Zero-based page number.

pageSizeinteger

Number of cards per page.

updatedAtMinstring date-time

Only return cards updated after this ISO timestamp.

includeArchivedboolean

Include archived cards. If omitted, an explicit archived rule controls archive selection; otherwise active cards only. An explicit false intersects with the rules.

relatedIdstring

Only return cards where references.value contains this ID.

contactEmailstring

Resolves the email to contact IDs, then filters cards referencing those contacts.

keyTermstring

Full-text autocomplete search on card title using the Atlas Search index.

assigneestring

Filter cards by assignee user ID.

segmentIdstring

Existing accessible, active segment on this board; mutually exclusive with rules.

userIdstring

Active company member whose private segments/currentUser values to use. API keys/partners may select a member; delegates cannot select another user.

Response

Paginated list of cards.

countinteger

Total number of matching cards.

pageinteger