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 acceptx-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
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
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: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.
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.