> ## Documentation Index > Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Promote to Managed > Transition from standalone vectors to auto-embedding and collections — no reindexing required 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. ```python Python theme={null} 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"} ], ) ``` ```bash cURL theme={null} 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 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`) | 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 ```json theme={null} { "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 Create a namespace and upsert your existing embeddings. ```bash theme={null} 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"}]}' ``` Upsert documents and verify retrieval quality before promoting. ```bash theme={null} # 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": [...]}}' ``` Map your embedding to the matching inference service. ```bash theme={null} 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"}]}' ``` 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](#querying-with-retrievers) below. 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`. ```bash theme={null} # 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. ```bash theme={null} # 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. ## Related * [Vector Store Overview](/vector-store/overview) * [Namespace Configuration](/vector-store/namespaces) * [Collections](/ingestion/collections) — set up auto-processing after promotion * [Feature Extractors](/processing/feature-extractors) — available extractors