Copy page

Concepts

Lists, filters and ordering

Every collection reads the same way. Four parameters — page_size, page_token, order_by, filter — and one envelope, whose array is named after the collection it came from.

Code
curl_json -G "${auth[@]}" "$site/cms_pages" \
  --data-urlencode 'page_size=5' \
  --data-urlencode 'order_by=create_time desc' \
  --data-urlencode 'filter=is_active = true AND title:"Hello"' |
  jq '{total_size, next_page_token, titles: [.cms_pages[].title]}'

Two things worth knowing before you write the query. Which fields you may filter and sort by is per resource, and the reference page for each one lists them: they are the fields with an index behind them, so a query cannot quietly table-scan the platform. And an unknown field is refused, not ignored — a typo comes back as an INVALID_ARGUMENT naming the field, rather than as a full unfiltered page that looks like an answer.

For paging, page_token is the path to take: it survives rows being inserted while you walk. skip exists for a grid that has to jump straight to page 40, and it is capped.

8. Lists

Response shape

Code
{
  "cms_pages": [ { "name": "websites/6a5e.../cms_pages/507f...", "...": "..." } ],
  "next_page_token": "eyJvIjoxMDB9",
  "total_size": 137
}

• The array field is named exactly the collection id (AIP-132). Clients derive it from the last path segment; they do not need a per-endpoint map.
• next_page_token is an opaque string. Empty or absent means "no more". Clients MUST NOT parse it; servers MAY encode an offset, a sort key, or a Typesense cursor in it, and MAY change that encoding without a version bump.
• total_size is the count of the whole filtered collection, not of this page.

Pagination

Param	Type	Meaning
page_size	int	Max results. Default 50, server max 100; a resource MAY lower its max. Over the max is clamped, not rejected.
page_token	string	Opaque token from a previous next_page_token.
skip	int	Results to skip before the page (AIP-158).

skip exists because the admin grid offers direct page jumps and cannot walk tokens to reach page 40. It is bounded (skip + page_size ≤ 10000; beyond that is OUT_OF_RANGE) because a deep Mongo skip is a linear scan. page_token is the path a batch consumer MUST take.

Ordering

order_by=create_time desc, title

• Comma-separated field [asc|desc], default asc, at most 3 keys.
• Only fields the resource declares sortable are accepted; anything else is INVALID_ARGUMENT. A field is sortable only if it is backed by an index — this rule exists so that an admin clicking a column header cannot table-scan production.
• Default order is per resource and MUST be documented and indexed. It is create_time desc unless the resource says otherwise.

Filtering

filter=is_active = true AND title:"launch"

A deliberately small subset of AIP-160:

Code
expr       := term (("AND" | "OR") term)*        ; AND binds tighter than OR
term       := ["NOT"] comparison | "(" expr ")"
comparison := field op value
op         := "=" | "!=" | "<" | "<=" | ">" | ">=" | ":"
field      := ident ("." ident)*
value      := string | number | true | false | null | rfc3339-timestamp

• : is has: case-insensitive substring on a string, membership on an array (visible_view_ids:"68b0c1").
• Only fields the resource declares filterable are accepted; anything else is INVALID_ARGUMENT naming the field. Functions, wildcards and traversals into unindexed subdocuments are not supported.
• A parse failure returns INVALID_ARGUMENT with the byte offset in details[].field_violations[].description.

Free text has no special parameter: the client composes it, e.g. filter=title:"foo" OR content:"foo". Ranked full-text search is a different thing with a different backend (Typesense) and is a custom method, not a filter (§10).