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: