Search Resources

Search across all resource names and IDs within your namespace.

This endpoint performs a case-insensitive search across:

• Buckets (bucket_name, bucket_id)
• Collections (collection_name, collection_id)
• Retrievers (retriever_name, retriever_id)
• Taxonomies (taxonomy_name, taxonomy_id)
• Clusters (cluster_name, cluster_id)
• Namespaces (namespace_name, namespace_id)

Results are sorted by relevance (exact matches first) and creation time (newest first). Use the resource_types parameter to filter searches to specific resource types. Pagination is supported via limit and offset parameters.

POST /v1/resources/search

Search Resources

cURL

curl --request POST \
  --url https://api.mixpeek.com/v1/resources/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <api-key>' \
  --data @- <<EOF
{
  "description": "Search all resources for 'product'",
  "limit": 20,
  "offset": 0,
  "query": "product"
}
EOF

200

{
  "description": "Successful search with multiple results",
  "limit": 20,
  "offset": 0,
  "results": [
    {
      "created_at": "2024-01-15T10:30:00Z",
      "description": "Production video content",
      "resource_id": "bkt_prod123",
      "resource_name": "production-videos",
      "resource_type": "bucket",
      "updated_at": "2024-01-20T14:22:00Z"
    },
    {
      "created_at": "2024-02-01T08:15:00Z",
      "description": "Product catalog embeddings",
      "resource_id": "col_prod456",
      "resource_name": "Product Embeddings",
      "resource_type": "collection"
    }
  ],
  "total": 15
}

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.

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 searching across resource names and IDs.

Search is performed across all resource types within the authenticated namespace. The search is case-insensitive and supports partial matching on both names and IDs.

Use Cases: - Find resources by partial name match - Locate resources by ID prefix - Filter search to specific resource types - Paginate through large result sets

Requirements: - query: REQUIRED - Search term (minimum 1 character) - resource_types: OPTIONAL - Filter by specific types - limit: OPTIONAL - Results per page (1-100, default 20) - offset: OPTIONAL - Pagination offset (default 0)

query · string · required

Search term to match against resource names and IDs. REQUIRED. Minimum 1 character. Case-insensitive partial matching is performed. Matches against: bucket_name, bucket_id, collection_name, collection_id, retriever_name, retriever_id, taxonomy_name, taxonomy_id, cluster_name, cluster_id, namespace_name, namespace_id. Example: 'prod' matches 'production-videos', 'bkt_prod123', 'Products Collection'.

Minimum string length: 1

Examples:

"product"

"bkt_"

"video"

"prod"

resource_types · enum<string>[] | null

Filter search to specific resource types. OPTIONAL - If not provided, searches all resource types. Valid values: 'bucket', 'collection', 'retriever', 'taxonomy', 'cluster', 'published_retriever', 'namespace'. Example: ['bucket', 'collection'] searches only buckets and collections.

Available options: bucket, collection, retriever, taxonomy, cluster, published_retriever, namespace

Example:

["bucket", "collection"]

limit · integer · default: 20

Maximum number of results to return. OPTIONAL - Defaults to 20. Minimum: 1, Maximum: 100. Use with offset for pagination.

Required range: 1 <= x <= 100

Examples:

20

50

100

offset · integer · default: 0

Number of results to skip for pagination. OPTIONAL - Defaults to 0. Minimum: 0. Use with limit for pagination. Example: offset=20 with limit=20 returns results 21-40.

Required range: x >= 0

Examples:

0

20

40

Response

200

application/json

Successful Response

Response model for resource search results.

Contains paginated search results with metadata about total matches and pagination state. Results are sorted by relevance (exact matches first, then partial matches) and creation time (newest first).

Use Cases: - Display search results to users - Implement pagination UI - Show total result counts - Navigate through large result sets

Fields: - results: List of matched resources - total: Total number of matches (before pagination) - limit: Results per page (from request) - offset: Current pagination offset (from request)

results · SearchResultItem · object[] · required

List of matched resources. REQUIRED. May be empty if no matches found. Sorted by: 1) Exact matches first, 2) Partial matches, 3) Created timestamp descending. Length is min(total - offset, limit). Each result contains full resource metadata for display.

Show child attributes

Examples:

[
  {
    "created_at": "2024-01-15T10:30:00Z",
    "description": "Product catalog",
    "resource_id": "bkt_abc123",
    "resource_name": "products",
    "resource_type": "bucket"
  }
]

[]

total · integer · required

Total number of matches across all pages. REQUIRED. Count before pagination is applied. Use to calculate total pages: ceil(total / limit). May be 0 if no matches found. Example: total=50 with limit=20 means 3 pages of results.

Required range: x >= 0

Examples:

0

15

100

limit · integer · required

Results per page (from request). REQUIRED. Echo of the limit parameter from the request. Range: 1-100.

Required range: 1 <= x <= 100

Examples:

20

50

100

offset · integer · required

Current pagination offset (from request). REQUIRED. Echo of the offset parameter from the request. Number of results skipped. Example: offset=20 means results start from the 21st match.

Required range: x >= 0

Examples:

0

20

40