# List the items of a collection

Canonical page: https://docs.ovok.com/cms/list-collection-items

Returns the published documents of one collection, such as `legal-pages`, `translations` or `release-notes`, as a page of results. Your documents and Ovok's shared ones are merged.

| Method | Path |
| --- | --- |
| `GET` | `/v1/public/cms/collections/:collection/items` |

`:collection` is the collection's slug. Collection slugs are case-sensitive, and the `users` and `tenants` collections are never served.

## Who can call it [#who-can-call-it]

An open collection (`legal-pages` and `translations` by default) needs only a tenant. Any other collection needs a CMS API key or a signed-in user of the tenant. See [who can read content](/cms#who-can-read-content).

## Request [#request]

```bash
curl --get 'https://api.sandbox.ovok.com/v1/public/cms/collections/legal-pages/items' \
  --data-urlencode 'tenant=big-health-company' \
  --data-urlencode 'locale=de'
```

A collection that is not open takes a key, from a server:

```bash
curl --get 'https://api.sandbox.ovok.com/v1/public/cms/collections/release-notes/items' \
  --header "x-api-key: ${OVOK_CMS_KEY}" \
  --data-urlencode 'tenant=big-health-company' \
  --data-urlencode 'sort=-publishedAt' \
  --data-urlencode 'limit=10'
```

| Query | Description |
| --- | --- |
| `tenant` | Your tenant code. Or send `x-ovok-tenant-code`. A signed-in user may leave it out. |
| `projectId` | Your project's id, instead of the tenant code. |
| `locale` | A bare two-letter language code, such as `de` or `it`. Leave it out for the default, English. See [languages](/cms#languages). |
| `page` | 1 to 100. Default 1. |
| `limit` | 1 to 50. Default 20. |
| `sort` | A top-level field name, `-` first for descending, such as `-publishedAt`. Leave it out for the CMS's own order. |
| `apiKey` | A CMS API key. Prefer the header; a key in a URL can end up in logs. |

## Response [#response]

```json
{
  "docs": [
    {
      "id": 7,
      "slug": "privacy",
      "title": "Datenschutz",
      "body": { "root": { "type": "root", "children": [] } },
      "effectiveAt": "2026-09-01T00:00:00.000Z",
      "status": "published"
    }
  ],
  "totalDocs": 1,
  "limit": 20,
  "totalPages": 1,
  "page": 1,
  "pagingCounter": 1,
  "hasPrevPage": false,
  "hasNextPage": false,
  "prevPage": null,
  "nextPage": null
}
```

| Field | Meaning |
| --- | --- |
| `docs` | The documents of this page. Only `published` ones. |
| `totalDocs`, `totalPages` | Counts across all pages, **after** the merge with the shared content. |
| `limit`, `page`, `pagingCounter` | The page you asked for. |
| `hasPrevPage`, `hasNextPage`, `prevPage`, `nextPage` | Paging links. `null` when there is none. |

Each document has the fields of its collection:

| Collection | Fields |
| --- | --- |
| `legal-pages` | `slug`, `title` and `body` (both localised; `body` is rich text), `effectiveAt`, `status` |
| `translations` | `slug` (the group), `title`, `strings` (a list of `key` and a localised `value`), `status` |
| `release-notes` | `slug`, `title`, `excerpt` and `body` (localised), `tags` (`announcement`, `new`, `improved`, `fixed`), `publishedAt`, `status` |

Rich text is the editor's JSON structure, not HTML. Your own documents carry a `tenant` field; documents merged in from the shared tenant do not.

## Order [#order]

Without `sort`, your documents come first, in the CMS's order, then the shared ones. With `sort`, the two lists are interleaved by that field: ties go to your document, and an empty value sorts last when ascending and first when descending. When a slug exists on both sides, only yours is listed.

## What can go wrong [#what-can-go-wrong]

The errors in [the overview](/cms#errors) apply. The checks run in this order, so the first failure is the one you see:

1. Authentication: `401`, or `403` for another tenant.
2. The collection: `404` `Not found` for one that is not served.
3. `locale`, `page`, `limit` and `sort`: `400`.
4. The tenant: `400`.
5. The read: the CMS's own status, or `502` if it is unreachable.

## Gotchas [#gotchas]

- **Other query parameters are ignored.** `where[...]`, `depth`, `draft` and `fields` are not forwarded. Filtering is done in your app.
- **`sort` takes one top-level field.** A dotted path, such as `data.title`, answers `400`.
- **A page past the end is empty, not an error**, with `hasPrevPage` `true`.
- **At most 5,000 documents are readable**: 50 per page across 100 pages.
- **The merge stops at 200 documents.** If your tenant or the shared one has more than 200 published documents in the collection, you get your own list, unmerged, with your own paging.
- **A failing shared read does not fail yours.** You get your own documents with a `200`.
- **The first read for a project can be slow.** If the project has no content space yet, Ovok creates it, which can take a moment.
- **An edit takes up to a minute to show**, and longer behind a CDN. See [caching](/cms#caching).

## Related [#related]

- [Get an item by slug](/cms/get-collection-item)
- [Use Ovok CMS with i18n](/cms/use-ovok-cms-with-i18n)
- [CMS](/cms)
