---
title: "List items in a collection"
method: GET
path: "/cms/collections/{collectionId}/items"
tags: ["CMS items"]
---

# List items in a collection

`GET /cms/collections/{collectionId}/items`

## Request

- Base URL: `https://api.cactal.ai/v1`
- URL: `https://api.cactal.ai/v1/cms/collections/{collectionId}/items`
- Auth: HTTP bearer

Returns the collection’s active items in manual (drag) order by default, 20 per page (max 100); paginate with `cursor` or with 1-based `page` offsets, not both. Filter with `published` (`true` / `false`) and a JSON-encoded `filter` map of `{ fieldKey: { operator: value } }` — operators `eq`, `neq`, `in`, `nin`, `gt`, `gte`, `lt`, `lte`, `contains`, `startsWith`, `endsWith`, and `exists`, plus `slug` equality on reference fields; metadata keys are `id`, `slug`, `publishedAt`, `publishAt`, `createdAt`, and `updatedAt`. Combine clauses with `filterLogic` (`and` by default, or `or`). `search` accepts a query string (1–200 characters) or JSON `{ "query", "fields" }` to restrict which text fields are searched; `sort` accepts JSON `{ "kind": "field" | "meta", "field", "direction": "asc" | "desc" }`, where sortable metadata fields are `id`, `slug`, `publishedAt`, `publishAt`, `createdAt`, `updatedAt`, and `position`. `depth` (0–3, default 0) embeds referenced items in place of their ids, one level per unit.

## Path parameters

- `collectionId` string, required

## Query parameters

- `cursor` string
- `page` integer
- `limit` integer
- `depth` integer
- `published` union
  - 'true'
  - 'false'
- `filter` string
- `filterLogic` 'and' | 'or'
- `search` string
- `sort` string

## Response `200`

One page of items.

- object
  - `items` object[], required
    - `id` string, required: Unique item id.
    - `collectionId` string, required: Id of the owning collection.
    - `slug` string, required: URL-shaped identifier, unique among the collection’s active items. Lowercase letters, digits, and hyphens; max 256 characters.
    - `publishedAt` string, date-time, nullable, required: `null` while the item is a draft or scheduled; the actual publish timestamp otherwise.
    - `publishAt` string, date-time, nullable, required: Future publication time while the item is scheduled; `null` for drafts and published items.
    - `createdAt` string, date-time, required: Creation timestamp.
    - `updatedAt` string, date-time, required: Last-modification timestamp.
    - `position` string, required: Fractional ordering key; the default list order sorts by this value.
    - `data` object, required: One entry per field of the collection, keyed by field key; optional fields with no value read as `null`. Scalar fields use plain JSON values: `date` as an ISO 8601 string, `color` as normalized hex, `option` as a choice id (or array of ids when multi-select). `reference` values are the referenced item id at depth 0 or an embedded item object (this same item shape) at depth ≥ 1; `multi_reference` values are ordered arrays of the same. `image` and `gallery` values resolve to image objects carrying `id`, delivery `url`, `originalUrl`, `srcSet`, `variants`, dimensions, `filename`, `mimeType`, `byteSize`, and `altText`; `file` values resolve to `{ id, url, filename, mimeType, byteSize }`. Unset asset fields read as `null` (or `[]` for galleries).
  - `nextCursor` string, nullable, required: Opaque cursor for the next page when paginating with `cursor`. `null` on the last page and when paginating with `page`.
  - `nextPage` integer, nullable, required: Next page number when paginating with `page`. `null` on the last page and when paginating with `cursor`.

## Other responses

- `400`: Validation failed. The response `message` names the first invalid field.
- `401`: Missing, invalid, expired, or revoked API key.
- `403`: The authenticated principal lacks the required capability.
- `404`: The resource does not exist or is outside the principal’s access scope.
- `429`: Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header.

---

[API](https://skmtc.dev/cactal/apis/cactal-api.md) · [All operations](https://skmtc.dev/cactal/apis/cactal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cactal/apis/cactal-api/revisions/9cd0fb5eacdd?raw)