> ## 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](https://mintcdn.com/mixpeek/PRYIJzrWYd-bekCW/assets/vector-store/promote-flow.svg?fit=max\&auto=format\&n=PRYIJzrWYd-bekCW\&q=85\&s=64ddb66b70acdf8b747aba018d43fd95)

## 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

**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

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

> [!WARNING]
>
> 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.

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

**2. Load and validate**

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

**3. Promote**

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

**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](#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`.

```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": {"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: 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": {"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: 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 |

> [!TIP]
>
> 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](https://docs.mixpeek.com/docs/vector-store/overview.md)
* [Namespace Configuration](https://docs.mixpeek.com/docs/vector-store/namespaces.md)
* [Collections](https://docs.mixpeek.com/docs/ingestion/collections.md) — set up auto-processing after promotion
* [Feature Extractors](https://docs.mixpeek.com/docs/processing/feature-extractors.md) — available extractors


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.