This quickstart guide will walk you through creating a simple multimodal search application with Mixpeek. You’ll learn how to ingest content, extract features, and build a search endpoint.
Watch an Intro Video

​
Prerequisites

Before you begin, make sure you have:
  • A Mixpeek account (sign up at mixpeek.com/start)
  • Your API key (found in your dashboard)
  • Basic familiarity with REST APIs

​
Base URL and Headers

All requests use the base URL https://api.mixpeek.com and require an API key. Most endpoints also require a namespace header. 
export API_URL="https://api.mixpeek.com"
export API_KEY="YOUR_API_KEY"

# Common headers (example usage shown in each step)
# Authorization: Bearer $API_KEY
# X-Namespace: <namespace_id>

​
1) Create a Namespace

Namespaces isolate data and queries. You can also use an existing namespace if you have one. 
curl -sS -X POST "$API_URL/v1/namespaces" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace_name": "quickstart",
    "description": "My first Mixpeek project",
    "feature_extractors": [
      { "feature_extractor_name": "video_extractor", "version": "1.0.0" }
    ]
  }'
Note the returned namespace_id and use it in X-Namespace for subsequent calls.

​
2) Create a Bucket

curl -sS -X POST "$API_URL/v1/buckets" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Namespace: <namespace_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "bucket_name": "content-bucket",
    "description": "Storage for our content",
    "bucket_schema": {
      "properties": {
        "my_img": { "type": "image" }
      }
    }
  }'
Capture the bucket_id from the response.

​
3) Create a Collection

Collections define processing lineage and (optionally) feature extractors. 
curl -sS -X POST "$API_URL/v1/collections" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Namespace: <namespace_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_name": "content-collection",
    "description": "Processed content documents",
    "source": { "type": "bucket", "bucket_id": "<bucket_id>" }
  }'
Capture the collection_id.

​
4) Upload an Object

Creating an object registers the files but does not start processing. Processing requires creating and submitting a batch. 
curl -sS -X POST "$API_URL/v1/buckets/<bucket_id>/objects" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Namespace: <namespace_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "key_prefix": "/sample",
    "blobs": [
      {
        "property": "my_img",
        "type": "image",
        "data": "https://example.com/sample-image.jpg"
      }
    ],
    "metadata": { "category": "demo" }
  }'
Capture the object_id from the response.

​
5) Create a Batch

curl -sS -X POST "$API_URL/v1/buckets/<bucket_id>/batches" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Namespace: <namespace_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "object_ids": ["<object_id>"]
  }'
Capture the batch_id from the response.

​
6) Submit the Batch for Processing

curl -sS -X POST "$API_URL/v1/buckets/<bucket_id>/batches/<batch_id>/submit" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Namespace: <namespace_id>"
This returns a task_id you can poll.

​
7) Check Task Status

curl -sS -X GET "$API_URL/v1/tasks/<task_id>" \
  -H "Authorization: Bearer $API_KEY"
Wait for status to become COMPLETED.

​
8) List Documents in the Collection

curl -sS -X POST "$API_URL/v1/collections/<collection_id>/documents/list" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Namespace: <namespace_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 10,
    "return_url": true
  }'

​
(Optional) 9) Create and Execute a Retriever

First, inspect available stages: 
curl -sS -X GET "$API_URL/v1/retrievers/stages" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Namespace: <namespace_id>"
Then create a simple retriever (adapt parameters to the stages you choose): 
curl -sS -X POST "$API_URL/v1/retrievers" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Namespace: <namespace_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "retriever_name": "content-retriever",
    "description": "Search across processed content",
    "input_schema": { "properties": { "query_text": { "type": "string" } } },
    "collection_ids": ["<collection_id>"],
    "stages": [
      {
        "stage_name": "knn_search",
        "version": "1.0.0",
        "parameters": { "k": 10 }
      }
    ]
  }'
Execute it: 
curl -sS -X POST "$API_URL/v1/retrievers/<retriever_id>/execute" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Namespace: <namespace_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": { "query_text": "show me images with people" },
    "limit": 10,
    "return_urls": true
  }'

​
(Optional) 10) Create a Flat Taxonomy

Create a simple flat taxonomy using the same collection as your reference. You can attach it to a collection to materialize enrichment or add it as a join stage in a retriever. 
curl -sS -X POST "$API_URL/v1/taxonomies" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Namespace: <namespace_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "taxonomy_name": "quickstart-taxonomy",
    "description": "Copy selected fields from best-matching documents",
    "config": {
      "taxonomy_type": "flat",
      "retriever_id": "<retriever_id>",
      "input_mappings": [
        { "input_key": "image_vector", "path": "features.clip_vit_l_14", "source_type": "vector" }
      ],
      "source_collection": {
        "collection_id": "<collection_id>",
        "enrichment_fields": [
          { "field_path": "metadata.category", "merge_mode": "replace" }
        ]
      }
    }
  }'
Next step: Learn more about Taxonomies including how to attach and execute on-demand Taxonomies

​
Next Steps

Congratulations! You’ve just built a simple multimodal search application with Mixpeek. To continue your journey:

Learn about Namespaces

Organize your data into isolated environments

Explore Feature Extractors

Discover advanced extraction capabilities

Build Powerful Retrievers

Create sophisticated search experiences