Pagination, Sorting & Filtering

Most list endpoints in the Public API support pagination, sorting, and filtering through query parameters. This page explains the common patterns used across all resources.

Pagination

List endpoints return paginated results. Use the page and limit query parameters to control pagination.

Parameter	Type	Default	Description
`page`	integer	1	Page number, starting from 1
`limit`	integer	20	Number of items per page

Paginated Response Format

All paginated endpoints return this envelope:

{
  "items": [...],   // Array of resource objects
  "total": 42,      // Total number of matching items
  "page": 1,        // Current page number
  "limit": 20,      // Items per page
  "pages": 3        // Total number of pages
}

Example: Fetching Page 2

curl -H "x-api-key: YOUR_API_KEY" \
  "https://public-api.adaptocms.com/v1/articles?page=2&limit=10"

Sorting

Use field and order to control sort behavior.

Parameter	Type	Values	Description
`field`	string	varies by resource	Field name to sort by (e.g. `created_at`, `title`)
`order`	string	`asc` / `desc`	Sort direction

Example: Latest Articles First

curl -H "x-api-key: YOUR_API_KEY" \
  "https://public-api.adaptocms.com/v1/articles?field=created_at&order=desc"

Filtering

Each resource supports specific filters. Common filters include:

Parameter	Available On	Description
`language`	Articles, Pages, Categories, Collections	Filter by ISO 639-1 language code (e.g. `en`, `fr`, `de`)
`status`	Articles, Pages, Collections	Filter by status (`draft`, `published`, `archived`)
`keyword`	Articles, Categories	Full-text search in title and content
`tag`	Articles, Pages	Filter by tag
`category`	Articles	Filter by category ID
`parent_id`	Categories	Filter by parent category
`translation_of_id`	Collection Items	Filter by translation source ID

Combining Filters

Filters can be combined freely:

curl -H "x-api-key: YOUR_API_KEY" \
  "https://public-api.adaptocms.com/v1/articles?language=en&status=published&tag=tutorial&field=created_at&order=desc&limit=5"

Preview Endpoints

Some resources offer /preview list endpoints that return lightweight responses without the full content body or file URLs. Use these for index pages, navigation menus, and any listing where you don't need the complete content:

GET /v1/articles/preview — Article previews (no content, custom_fields, file_urls, media_objects_placements)
GET /v1/pages/preview — Page previews (no content, custom_fields, file_urls, media_objects_placements)
GET /v1/custom-collections/{id}/items/preview — Collection item previews (no data, file_urls, media_objects_placements)

Preview endpoints accept the same pagination, sorting, and filtering parameters as their full counterparts.