Promote to Managed

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="mxp_sk_...")

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"}
    ],
)

curl -X POST "https://api.mixpeek.com/v1/namespaces/product-search/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"}
    ],
    "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.

Field	Description
`existing_index`	Name of an existing vector index
`inference_service`	Model to auto-embed queries (e.g., `openai_text_3_small`)

add_vectors

array

New vector indexes to create during promotion.

Field	Description
`name`	New index name (must not conflict with existing)
`dimension`	Embedding dimension
`metric`	`cosine`, `dot`, or `euclidean`
`inference_service`	Model 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 input	Must provide pre-computed vectors	Also accepts raw text/URLs — auto-embedded
New content	Direct upsert only	Collections + 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

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"}]}'

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": [...]}}'

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"}]}'

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.

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 input	Raw vectors you computed (also text/BM25, sparse)	Raw text, URLs, filters — auto-embedded
Embedding	You compute and pass vectors	Retriever stages auto-embed via inference services
Query path	Retriever create + execute	Retriever create + execute — same API
Pipeline	Single search stage + optional fusion	Multi-stage: search → filter → enrich → rerank → transform
Hybrid search	Multiple `feature_search` searches + fusion	Multiple `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.

Vector Store Overview
Namespace Configuration
Collections — set up auto-processing after promotion
Feature Extractors — available extractors

​Promote

​Parameters

​Response

​What Changes

​Rules

​Full Workflow

​Querying with Retrievers

​Before promotion: pass your own vector

​After promotion: pass raw text

​What Changes

​Related

Promote

Parameters

Response

What Changes

Rules

Full Workflow

Querying with Retrievers

Before promotion: pass your own vector

After promotion: pass raw text

What Changes

Related