List taxonomies (GET alias for POST /list).

List taxonomies with optional filters and pagination.

GET /v1/taxonomies

List taxonomies (GET alias for POST /list).

cURL

curl --request GET \
  --url https://api.mixpeek.com/v1/taxonomies \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <api-key>' \
  --data '
{
  "limit": 500,
  "page_size": 500,
  "offset": 5000,
  "page": 2,
  "search": "<string>",
  "filters": {
    "AND": [
      {
        "field": "name",
        "operator": "eq",
        "value": "John"
      },
      {
        "field": "age",
        "operator": "gte",
        "value": 30
      }
    ],
    "OR": [
      {
        "field": "status",
        "operator": "eq",
        "value": "active"
      },
      {
        "field": "role",
        "operator": "eq",
        "value": "admin"
      }
    ],
    "NOT": [
      {
        "field": "department",
        "operator": "eq",
        "value": "HR"
      },
      {
        "field": "location",
        "operator": "eq",
        "value": "remote"
      }
    ],
    "case_sensitive": true
  },
  "sort": {
    "field": "created_at",
    "direction": "desc"
  },
  "sorts": [
    {}
  ],
  "case_sensitive": false
}
'

200

{
  "results": [
    {
      "config": {
        "default_input_mappings": [
          {
            "input_key": "image_vector",
            "path": "features.clip_vit_l_14",
            "source_type": "vector"
          }
        ],
        "default_retriever_id": "ret_clip_v1",
        "source_collection": {
          "collection_id": "col_products_v1"
        },
        "taxonomy_type": "flat"
      },
      "namespace_id": "ns_123",
      "taxonomy_name": "product_tags",
      "taxonomy_type": "flat"
    }
  ],
  "pagination": {},
  "total_count": 123,
  "stats": {
    "total_taxonomies": 0,
    "flat_taxonomies": 0,
    "hierarchical_taxonomies": 0,
    "taxonomies_with_retrievers": 0
  }
}

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 to list taxonomies.

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

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

search · string | null

Search term for wildcard search across taxonomy_id, taxonomy_name, description, and other text fields

filters · LogicalOperator · object | null

Filters to apply to the taxonomy list. Supports filtering by taxonomy_id or taxonomy_name.

Show child attributes

sort · SortOption · object | null

Sort configuration for the taxonomy list (single-column, legacy)

Show child attributes

sorts · Sorts · object[] | null

Sort configuration 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.

case_sensitive · boolean · default: false

If True, filters and search will be case-sensitive

Response

200

application/json

Successful Response

Response model for listing taxonomies.

results · TaxonomyResponse · object[] · required

Show child attributes

pagination · Pagination · object · required

total_count · integer · required

stats · TaxonomyListStats · object | null

Aggregate statistics across all taxonomies in the result

Show child attributes