List Collections

This endpoint allows you to list collections.

POST /v1/collections/list

List Collections

cURL

curl --request POST \
  --url https://api.mixpeek.com/v1/collections/list \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <api-key>' \
  --data '
{
  "limit": 500,
  "page_size": 500,
  "offset": 5000,
  "page": 2,
  "filters": {},
  "sort": {
    "field": "created_at",
    "direction": "desc"
  },
  "sorts": [
    {}
  ],
  "search": "<string>",
  "include_system": false,
  "case_sensitive": false
}
'

200

{
  "results": [
    {
      "collection_id": "col_a1b2c3d4e5",
      "collection_name": "article_embeddings",
      "description": "Simple text collection: News articles with text embeddings from bucket source",
      "enabled": true,
      "feature_extractor": {
        "feature_extractor_name": "text_extractor",
        "field_passthrough": [
          {
            "source_path": "title"
          }
        ],
        "input_mappings": {
          "text": "content"
        },
        "version": "v1"
      },
      "input_schema": {
        "properties": {
          "title": {
            "type": "string"
          },
          "content": {
            "type": "text"
          }
        }
      },
      "output_schema": {
        "properties": {
          "title": {
            "type": "string"
          },
          "text_extractor_v1_embedding": {
            "type": "array"
          }
        }
      },
      "source": {
        "bucket_id": "bkt_articles",
        "type": "bucket"
      }
    }
  ],
  "pagination": {
    "total": 123,
    "page": 123,
    "page_size": 123,
    "total_pages": 123,
    "next_page": "<string>",
    "previous_page": "<string>",
    "next_cursor": "<string>"
  },
  "total_count": 123,
  "stats": {
    "total_documents": 0,
    "avg_documents_per_collection": 0,
    "collections_with_taxonomies": 0,
    "total_feature_extractors": 0,
    "total_taxonomies": 0,
    "total_retrievers": 0
  },
  "warnings": [
    {
      "resource": "taxonomy",
      "reason": "not found in namespace",
      "next_step": "Fix the taxonomy_id on the stage, or create the taxonomy.",
      "id": "tax_abc123",
      "stage": "<string>"
    }
  ]
}

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 refused with 422 extra_forbidden naming the accepted keys (since 2026-11-02).

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)

Show child attributes

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

200

application/json

Successful Response

Response model for listing collections.

results · CollectionResponse · object[] · required

List of collections

Show child attributes

pagination · PaginationResponse · object · required

Pagination information

Show child attributes

total_count · integer · required

Total number of collections matching the query

stats · CollectionListStats · object | null

Aggregate statistics across all collections in the result

Show child attributes

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.

Show child attributes