Skip to main content
POST
List Collections

Authorizations

Authorization
string
header
required

Mixpeek API key, sent as Authorization: Bearer mxp_sk_.... Create one in Studio under Settings → API Keys, or with an admin key via POST /v1/organizations/users/{user_email}/api-keys. A missing, malformed, unknown, revoked, inactive or expired key returns 401; a key without the permission, scope or plan an operation needs returns 403.

X-Namespace
string
header
required

Namespace id (ns_...), not the namespace name. This scopes the request rather than authenticating it, and it is required on every operation marked x-mixpeek-namespace-scoped.

Query Parameters

limit
integer | null
Required range: 1 <= x <= 1000
page_size
integer | null
Required range: 1 <= x <= 1000
offset
integer | null
Required range: 0 <= x <= 10000
page
integer | null
Required range: x >= 1
cursor
string | null
next_cursor
string | null
after
string | null
include_total
boolean
default:false

Body

application/json

Keys this body does not declare are ignored, and the response's warnings name them, until 2026-11-02; from 2026-11-02 they are refused with 422 extra_forbidden naming the accepted keys.

Request model for listing collections.

Inherits body-level limit/page_size/offset/page — body values win over query pagination via merge_body_pagination.

To filter by taxonomy, use dot notation in filters: filters.AND = [{"field": "taxonomy_applications.taxonomy_id", "operator": "eq", "value": "tax_123"}]

limit
integer | null

Page size. A body value wins over the limit query param.

Required range: 1 <= x <= 1000
page_size
integer | null

Alias for limit (page size). If both are given, limit wins.

Required range: 1 <= x <= 1000
offset
integer | null

Number of results to skip (legacy, use cursor instead). A body value wins over the offset query param.

Required range: 0 <= x <= 10000
page
integer | null

1-indexed page number. Folds to offset = (page-1) * limit. If both page and offset are given, offset wins.

Required range: x >= 1
filters
Filters · object | null

Filters to apply when listing collections. Supports nested field filtering like 'taxonomy_applications.taxonomy_id'. Format: {"AND": [{"field": "field_name", "operator": "eq", "value": "value"}]}

sort
SortOption · object | null

Sort options for the results (single-column, legacy)

sorts
Sorts · object[] | null

Sort options as a list of {field, direction} — the shape Studio datatables and the retriever list send. The first entry is the primary sort. Takes precedence over the singular sort.

search
string | null

Search term for wildcard search across collection_id, collection_name, description, and other text fields

include_system
boolean
default:false

Include the namespace's system collections: today the per-namespace _direct_upsert default that POST /v1/namespaces/{ns}/documents/upsert writes to (it is also addressable by that name at GET /v1/collections/_direct_upsert). Off by default so the list shows the collections you created.

case_sensitive
boolean
default:false

If True, filters and search will be case-sensitive

Response

Successful Response

Response model for listing collections.

results
CollectionResponse · object[]
required

List of collections

pagination
PaginationResponse · object
required

Pagination information

total_count
integer
required

Total number of collections matching the query

stats
CollectionListStats · object | null

Aggregate statistics across all collections in the result

warnings
DegradedEntry · object[]

Why this page may not be the whole answer. An entry with resource 'namespace' and reason 'unresolved' means X-Namespace did not resolve for this API key, so the empty list is not that namespace's contents (the same condition as the X-Namespace-Unresolved response header). Empty when the namespace resolved.