Skip to main content
POST
/
v1
/
resources
/
search
Search Resources
curl --request POST \
  --url https://api.mixpeek.com/v1/resources/search \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <x-namespace>' \
  --data '
{
  "query": "<string>",
  "resource_types": [
    "bucket",
    "collection"
  ],
  "limit": 20,
  "offset": 0
}
'
{
  "results": [
    {
      "resource_type": "bucket",
      "resource_id": "<string>",
      "resource_name": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "description": "Video content for production environment",
      "updated_at": "2023-11-07T05:31:56Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 1
}

Headers

​
Authorization
string
required

REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

​
X-Namespace
string
required

REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'

Body

application/json

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. Example: 'prod' matches 'production-videos', 'bkt_prod123', 'Products Collection'.

Minimum string length: 1
​
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'. Example: ['bucket', 'collection'] searches only buckets and collections.

Available options:
bucket,
collection,
retriever,
taxonomy,
cluster,
published_retriever
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
​
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

Response

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.

​
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
​
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
​
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