> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getaptly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Board Segments

> Read saved filter segments and list cards with saved or ad hoc rules, using the paginated, filterable card-listing endpoint.

Use `POST /api/board/{boardId}/list` to list cards. It performs no card or segment
writes. `POST /api/board/{boardId}` still creates or updates cards.
`GET /api/board/{boardId}` is deprecated but remains supported, using the same
listing implementation and response. On GET, encode `rules` as a JSON query string;
on POST, send a native JSON array in the body.

The deprecated GET retains legacy query parsing: `page` and nonempty `pageSize`
use base-10 `parseInt` (`1.5` and `1e2` both become `1`), and an empty `pageSize`
defaults to 20. An empty `includeArchived` or the exact string `false` excludes
archived cards; any other nonempty string includes them, including `1` and `0`.
Omitting `includeArchived` still allows an explicit archive rule to control
selection. Pagination limits still apply. POST keeps its stricter validation.

## Authentication and private segments

These reads accept `x-token` API keys, `Authorization: DelegateToken ...`, or
`Authorization: Bearer ...` partner tokens with `board-admin`. Mobile access tokens
are not accepted. API keys retain board/read permission restrictions. Delegates need
`boards:*` or `boards:{boardId}` in their read scopes. Keys and delegates require
API-enabled boards; partners retain their existing API-enabled bypass.

API keys and partner tokens may supply `userId` to select an active member of the
board's company. Delegates always use the user in their token and cannot select
someone else. `x-user-id` is also accepted; a query/body `userId` takes precedence.
Supplying `userId` selects private-segment ownership and the meaning of
`currentUser`; it does not grant additional board permissions. Without it,
non-user-bound credentials see only public segments.

## Read saved segments

```http theme={null}
GET /api/board/{boardId}/configuration/filters?visibility=all&name=urgent&userId={userId}
```

`visibility` is `public`, `private`, or `all` (default). Public means company-shared.
All means public plus the selected user's private segments. Private requires a
user identity. `name` performs a case-insensitive literal substring match.
Archived segments and quick views are excluded. The response is `{ data: [...] }`;
each entry includes `_id`, `name`, `scope`, `visibility`, `aptletUuid`, and its saved
`rules` when present.

## List cards

```http theme={null}
POST /api/board/{boardId}/list
Content-Type: application/json
```

```json theme={null}
{
  "page": 0,
  "pageSize": 20,
  "userId": "USER_ID",
  "segmentId": "SEGMENT_ID"
}
```

Supply `segmentId` **or** `rules`, never both. Existing filters (`assignee`,
`updatedAtMin`, `includeArchived`, `relatedId`, `contactEmail`, `keyTerm`) further
narrow either mode. Text-search results and counts apply the complete predicate.
A contact email with no matches returns no cards.

The response remains `{ data, count, page, pageSize }`. `count` is the total number
of matches. `page` is required, zero-based, and at most 9999; `pageSize` defaults to
20 and ranges from 1 to 1000. Results sort by latest update, then name and ID.

Cards are active-only by default. If `includeArchived` is omitted, an explicit
`archived` rule controls selection. An explicit `includeArchived: false` intersects
with the rules. Segment/rule queries also exclude deleted cards unless a `deleted`
rule explicitly selects them. Unfiltered legacy listing behavior is retained.

## Ad hoc rules

This finds the selected user's cards in a stage, updated within the last 24 hours:

```json theme={null}
{
  "page": 0,
  "userId": "USER_ID",
  "rules": [
    { "fieldUuid": "assignee", "operator": "anyIn", "valueSource": "currentUser" },
    { "fieldUuid": "stage", "operator": "anyIn", "value": ["In Progress"] },
    { "fieldUuid": "updatedAt", "operator": "lastCustomDays", "value": 1 }
  ]
}
```

Rules are ANDed. `anyIn` provides alternatives within one field; arbitrary nested
AND/OR expressions and raw MongoDB predicates are not accepted. Up to 100 rules
and 64 KB of serialized rules are allowed. Values and operators are checked against
the current board schema. Stale, unknown, or invalid rules return 400 instead of
silently broadening the query. An inaccessible, archived, or wrong-board segment
returns 404. Saved segments with missing or non-array `rules`, including legacy `filters`-only
records, must be re-saved in the board segment editor before execution. An explicit
empty `rules` array intentionally matches all cards within the normal board filters.

A rule uses `fieldUuid`, `operator`, and usually `value`. `key` selects an exact
filter path when a field has multiple filters, such as an event's date versus
outcome. Preserve these keys when adapting saved rules. In the field catalog, `uuid` maps
to a rule's `fieldUuid`; `key` selects its stored subfield. For example, a money
field uses `fieldUuid: "rent"` and `key: "rent.amount"`. System fields include
`name`, `assignee`, `stage`, `createdAt`, `updatedAt`, `archived`, and `deleted`.
Custom fields use their UUIDs from the board schema.

| Field/value kind | Operators and values |
| - | - |
| Text | `equal`, `notEqual`, `contains`, `notContains`, `startsWith`, `endsWith`; string value. `includesInList` takes a semicolon-separated string. |
| Number and money | `equal`, `notEqual`, `lessThan`, `gratherThan`, `between`; numeric value or `[min,max]`. **`gratherThan` is the stored spelling.** Money uses `{ "amount": 12500, "currency": "USD" }` for \$125, or two such objects for a range. |
| Stage, selects, tags, user | `anyIn`, `notIn`; arrays of stored option labels, or user IDs for user fields. |
| Boolean | `is`, `isNot` with a boolean; `anyIn` with booleans/null. |
| Contacts | `equal`, `anyIn`, `notIn`; contact objects `{ "_id": "PERSON_ID" }` or arrays of these. |
| Dates | `equalDay`, `lessThan`, `gratherThan`, `between` with ISO dates; `equalToday`, `lessThanToday`, `greaterThanToday` need no value. |
| Relative dates | `lastCustomDays`, `nextCustomDays` with a positive number of days; `daysLessThanNow`, `daysGreaterThanNow`, `daysLessThanToday`, `daysGreaterThanToday` accept signed day offsets. |
| Calendar periods | `specificPeriod` takes `{ "period": "month", "adjustment": -1 }`; periods are `dayOfYear`, `week`, `month`, `quarter`, `year`. |
| Waiting time | `timeSinceLessThan`, `timeSinceGreaterThan` take **hours**; fields marked for business hours honor board settings or company hours, holidays, and timezone. |
| Card age | `daysOpenedLessThan`, `daysOpenedGreaterThan` take days. Archived cards use their archived timestamp. |
| Missing/present | `isEmpty`, `isNotEmpty` omit `value`; supported by the corresponding field's catalog. |

Legacy fixed-window operators `last14Days`, `last30Days`, `last90Days`, `last120Days`
and their `next` equivalents remain supported. The historical `14Days` operators
use 15 days; use `lastCustomDays: 14` or `nextCustomDays: 14` for exactly 14 days.
Relative windows use elapsed hours; calendar-day/period operators use the resolved
board/company timezone (UTC when no organization timezone exists).

Field comparison uses `valueFieldUuid` instead of `value`, with a compatible
board field UUID or derived key. Supported operators are `equal`, `notEqual`,
`lessThan`, `gratherThan`. Money/scalar comparisons account for cents. Optional
`defaultValueField` selects a valid catalog field when the primary field is absent.
For user `anyIn`/`notIn` rules, `valueSource: "currentUser"` resolves the authenticated
or selected user server-side and must not be combined with `value`.

For compatibility with existing saved segments, `contains`, `startsWith`, and
`endsWith` are case-sensitive; `notContains` is case-insensitive. These operators
match literal text, not caller-supplied regular expressions. Signed `days*Than*`
offsets are added to now/today before comparison: `daysLessThanNow: 2` means
before two days from now; `daysLessThanNow: -2` means before two days ago.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.