Skip to main content
Promotion converts a standalone namespace to managed mode. Existing vectors and documents stay in place. Mixpeek adds auto-embedding for queries and collection-driven processing for new content.
Promotion flow — standalone namespace with vectors becomes managed with inference mappings, no reindexing

​
Promote

Map existing vector indexes to inference services and optionally add new ones. 
from mixpeek import Mixpeek

client = Mixpeek(api_key="sk_live_...")

client.namespaces.promote(
    namespace_id="product-search",
    vector_mappings=[
        {"existing_index": "text_embedding", "inference_service": "openai_text_3_small"}
    ],
    add_vectors=[
        {"name": "image_embedding", "dimension": 512, "metric": "cosine", "inference_service": "clip_vit_b32"}
    ],
)

​
Parameters

​
vector_mappings
array
Map existing indexes to inference services for auto-embedding queries.
FieldDescription
existing_indexName of an existing vector index
inference_serviceModel to auto-embed queries (e.g., openai_text_3_small)
​
add_vectors
array
New vector indexes to create during promotion.
FieldDescription
nameNew index name (must not conflict with existing)
dimensionEmbedding dimension
metriccosine, dot, or euclidean
inference_serviceModel for auto-embedding (optional)

​
Response

{
  "namespace_id": "product-search",
  "previous_mode": "standalone",
  "mode": "managed",
  "status": "active",
  "vector_configs": [
    {"name": "text_embedding", "dimension": 1536, "metric": "cosine"},
    {"name": "image_embedding", "dimension": 512, "metric": "cosine"}
  ],
  "vector_inference_map": {
    "text_embedding": "openai_text_3_small",
    "image_embedding": "clip_vit_b32"
  }
}

​
What Changes

Before (standalone)After (managed)
Search inputMust provide pre-computed vectorsAlso accepts raw text/URLs — auto-embedded
New contentDirect upsert onlyCollections + extractors auto-process
Existing data—Preserved, no reindexing
Direct upsert—Still works alongside collections

​
Rules

Promotion is one-way. Managed namespaces cannot be demoted.
  • Only standalone namespaces can be promoted
  • existing_index must reference an index that exists — errors list available indexes
  • name in add_vectors must not conflict with existing indexes
  • Promotion is atomic — if validation fails, nothing changes
  • Both vector_mappings and add_vectors are optional (promote with just one or neither)

​
Full Workflow

1

Start standalone

Create a namespace and upsert your existing embeddings.
curl -X POST "https://api.mixpeek.com/v1/namespaces/standalone" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"namespace_id": "legal-docs", "vector_configs": [{"name": "text_embedding", "dimension": 1536, "metric": "cosine"}]}'
2

Load and validate

Upsert documents and verify retrieval quality before promoting.
# Upsert
curl -X POST "https://api.mixpeek.com/v1/namespaces/legal-docs/documents/upsert" ...

# Execute a retriever to validate (input_mode: vector — you pass the query embedding)
curl -X POST "https://api.mixpeek.com/v1/retrievers/{retriever_id}/execute" \
  -H "X-Namespace: legal-docs" \
  -d '{"inputs": {"query_vector": [...]}}'
3

Promote

Map your embedding to the matching inference service.
curl -X POST "https://api.mixpeek.com/v1/namespaces/legal-docs/promote" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"vector_mappings": [{"existing_index": "text_embedding", "inference_service": "openai_text_3_small"}]}'
4

Switch queries to text input

Your retrievers already run before and after promotion — no API change. Update the query stage from input_mode: vector (you pass the embedding) to input_mode: text so Mixpeek auto-embeds. See Querying with Retrievers below.
5

Use managed features

Create collections with extractors for new content. Existing documents coexist with extractor-processed documents.

​
Querying with Retrievers

Querying is unified on retrievers in both standalone and managed modes — you learn one query concept regardless of whether you bring your own vectors or let Mixpeek embed for you. Promotion doesn’t change how you query; it only changes what you pass in. A standalone retriever takes the query vector you computed (input_mode: vector); after promotion the same retriever can take raw text and auto-embed it (input_mode: text).

​
Before promotion: pass your own vector

The query stage runs in input_mode: vector — you compute the embedding and pass it in inputs. 
# Step 1 — Create a retriever (one-time)
curl -X POST "https://api.mixpeek.com/v1/retrievers" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "X-Namespace: product-search" \
  -H "Content-Type: application/json" \
  -d '{
    "retriever_name": "product_search",
    "input_schema": {"query_vector": {"type": "array", "required": true}},
    "stages": [{
      "stage_name": "search",
      "stage_type": "filter",
      "config": {
        "stage_id": "feature_search",
        "parameters": {
          "searches": [{
            "feature_uri": "text_embedding",
            "query": {"input_mode": "vector", "value": "{{INPUT.query_vector}}"},
            "filters": {"must": [{"key": "category", "match": {"value": "audio"}}]},
            "top_k": 10
          }],
          "final_top_k": 10
        }
      }
    }]
  }'

# Step 2 — Execute with your query embedding
curl -X POST "https://api.mixpeek.com/v1/retrievers/{retriever_id}/execute" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "X-Namespace: product-search" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {"query_vector": [0.12, -0.34, 0.56, "...1536 floats"]}
  }'

​
After promotion: pass raw text

Once text_embedding is mapped to an inference service, switch the query stage to input_mode: text. Mixpeek embeds the text for you — no vectors needed. 
# Step 1 — Create (or update) the retriever to take text
curl -X POST "https://api.mixpeek.com/v1/retrievers" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "X-Namespace: product-search" \
  -H "Content-Type: application/json" \
  -d '{
    "retriever_name": "product_search",
    "input_schema": {"q": {"type": "string", "required": true}},
    "stages": [{
      "stage_name": "search",
      "stage_type": "filter",
      "config": {
        "stage_id": "feature_search",
        "parameters": {
          "searches": [{
            "feature_uri": "text_embedding",
            "query": {"input_mode": "text", "value": "{{INPUT.q}}"},
            "filters": {"must": [{"key": "category", "match": {"value": "audio"}}]},
            "top_k": 10
          }],
          "final_top_k": 10
        }
      }
    }]
  }'

# Step 2 — Execute with raw text (auto-embedded)
curl -X POST "https://api.mixpeek.com/v1/retrievers/{retriever_id}/execute" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "X-Namespace: product-search" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {"q": "wireless headphones"}
  }'
Each hit in the response exposes document_id plus the document’s payload fields.

​
What Changes

Standalone (input_mode: vector)Managed (input_mode: text)
Query inputRaw vectors you computed (also text/BM25, sparse)Raw text, URLs, filters — auto-embedded
EmbeddingYou compute and pass vectorsRetriever stages auto-embed via inference services
Query pathRetriever create + executeRetriever create + execute — same API
PipelineSingle search stage + optional fusionMulti-stage: search → filter → enrich → rerank → transform
Hybrid searchMultiple feature_search searches + fusionMultiple feature_search stages + sort/reduce stages
Promotion is additive — your retrievers keep working. Flip the query stage to input_mode: text whenever you’re ready to let Mixpeek handle embedding, and layer in multi-stage pipelines as your needs grow.