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

const res = await fetch("https://api.mixpeek.com/v1/namespaces/product-search/promote", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MIXPEEK_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "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"
      }
    ]
  }),
});
const data = await res.json();

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

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`)

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	n/a	Preserved, no reindexing
Direct upsert	n/a	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, where 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 with 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, so 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: ns_your_namespace_id" \
  -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": {"AND": [{"field": "metadata.category", "operator": "eq", "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: ns_your_namespace_id" \
  -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, so no vectors are 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: ns_your_namespace_id" \
  -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": {"AND": [{"field": "metadata.category", "operator": "eq", "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: ns_your_namespace_id" \
  -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