---
title: "Search Resources"
method: POST
path: "/v1/resources/search"
tags: ["Resource Search"]
---

# Search Resources

`POST /v1/resources/search`

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.

## Request body

- SearchRequest — 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'.
  - `resource_types` string[], nullable — 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.
  - `limit` integer — Maximum number of results to return. OPTIONAL - Defaults to 20. Minimum: 1, Maximum: 100. Use with offset for pagination.
  - `offset` integer — 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.

## Response `200`

Successful Response

- SearchResponse — 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[], 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.
    - `resource_type` 'bucket' | 'collection' | 'retriever' | 'taxonomy' | 'cluster' | 'published_retriever' | 'namespace', required — Type of resource this result represents. REQUIRED. One of: 'bucket', 'collection', 'retriever', 'taxonomy', 'cluster', 'published_retriever', 'namespace'. Used to identify which resource type was matched and how to navigate to it. Example: 'bucket' indicates this is a bucket resource.
    - `resource_id` string, required — Unique identifier for the resource. REQUIRED. Format depends on resource_type: - bucket: 'bkt_XXXXXXXX' - collection: 'col_XXXXXXXXXX' - retriever: 'ret_XXXXXXXXXXXXXX' - taxonomy: 'tax_XXXXXXXXXXXX' - cluster: 'clust_XXXXXXXXXX' - published_retriever: 'pk_XXXXXXXXXX' - namespace: 'ns_XXXXXXXXXX'. Use this ID to fetch the full resource or perform operations on it.
    - `resource_name` string, required — Human-readable name of the resource. REQUIRED. This is the field that was matched in the search. Corresponds to: bucket_name, collection_name, retriever_name, taxonomy_name, cluster_name, or public_name. Example: 'Production Videos', 'Product Embeddings', 'Recommendation Engine', 'my-public-search'.
    - `description` string, nullable — Description of the resource if provided. OPTIONAL - May be null if no description was set. Provides additional context about the resource's purpose or contents.
    - `created_at` string, date-time, required — Timestamp when the resource was created. REQUIRED. ISO 8601 format with UTC timezone. Used for sorting results by creation time.
    - `updated_at` string, date-time, nullable — Timestamp when the resource was last updated. OPTIONAL - May be null if resource has never been updated. ISO 8601 format with UTC timezone.
  - `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.
  - `limit` integer, required — Results per page (from request). REQUIRED. Echo of the limit parameter from the request. Range: 1-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.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/versions/220a3b263fda/schema)