> For the complete documentation index, see [llms.txt](https://docs.overflowcms.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.overflowcms.com/api-reference/collections-and-items.md).

# Collections & Items

## Collections & Items

### Collections & Items

#### List items

```
GET /v1/:token/collections/:slug/items
```

Returns a page of published items from one collection, identified by its slug (the same slug used in `data-oc-list`).

**Query parameters**

| Param             | Example                      | Notes                                                                                                                                            |
| ----------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `page`            | `?page=2`                    | 1-indexed. Invalid/missing values fall back to `1` rather than erroring.                                                                         |
| `limit`           | `?limit=24`                  | Default 24, hard max 100 — values outside that range are clamped, not rejected, so a public endpoint can't be made to 500 with `limit=999999`.   |
| `sort`            | `?sort=-publishedDate,title` | Comma-separated field keys; a leading `-` means descending. Only **indexed** fields can be sorted on.                                            |
| `filter[key]`     | `?filter[category]=news`     | Defaults to an `eq` (equals) comparison. **Requires the Pro plan or above** — see below.                                                         |
| `filter[key][op]` | `?filter[rating][gte]=4`     | Explicit operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `contains`, `in` (comma-separated values for `in`). **Requires the Pro plan or above.** |
| `search`          | `?search=webflow`            | Substring match (`LIKE`) over indexed text fields. **Requires the Pro plan or above.**                                                           |

Only fields marked **indexed** on the collection are usable in `sort` or `filter` — see Field Types & Data Shapes.

{% hint style="info" %}
`page`, `limit`, and `sort` work on every plan. Any `filter[...]` param, or `search`, requires the site's workspace to be on **Pro or above** (the `advancedLists` plan feature) — below that tier the whole request 403s with `plan_required` (see Errors) rather than silently ignoring the param. This is checked before the request even reaches the cache, so a gated call never gets cached for a later, entitled retry. The embed script's declarative filter controls (`data-oc-filter`, etc. — see the Guides space's Filtering & Sorting page) hit this same gate.
{% endhint %}

**Response**

```json
{
  "items": [
    {
      "id": "...",
      "slug": "shipping-unlimited-items-on-webflow",
      "collection": "blog",
      "publishedAt": "2026-07-12T12:00:00.000Z",
      "data": {
        "title": "Shipping unlimited items on Webflow",
        "excerpt": "Why item limits shouldn't decide your CMS.",
        "cover": { "mediaId": "...", "url": "...", "srcset": "...", "alt": "" },
        "publishedDate": "2026-07-12T00:00:00.000Z",
        "body": "<p>...</p>"
      }
    }
  ],
  "page": 1,
  "limit": 24,
  "total": 2,
  "totalPages": 1
}
```

`data` is keyed by each field's **key**, exactly as configured on the collection — image/video fields expand to the full MediaRef object rather than a bare URL (see Field Types & Data Shapes). `reference` fields are resolved one level deep automatically, in the same response.

#### Get a single item

```
GET /v1/:token/collections/:slug/items/:itemSlug
```

Returns `{ "item": { ...same shape as above... } }` for one published item by its slug, or a `not_found` error (see Errors) if it doesn't exist or isn't published.

#### Caching

List and item responses are cached at the edge per exact URL (`Cache-Control: public, s-maxage=31536000`). Publishing, unpublishing, or editing a published item invalidates the relevant site's cached responses automatically — you don't send any cache-control headers or busting params yourself; a fresh fetch after publishing just works, typically within seconds.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.overflowcms.com/api-reference/collections-and-items.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.