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

# Quickstart

> Start searching in under 60 seconds with BYO vectors, or index multimodal content with the managed platform

Get a Mixpeek API key from [mixpeek.com/start](https://mixpeek.com/start), then pick your path — BYO vectors for instant search, or managed pipelines for automatic extraction.

<Tip>
  **New to Mixpeek?** Follow the first tab — **MVS Standalone** — end to end. It's the shortest path to a working search (under 60 seconds) and needs nothing but an API key. The other tabs wire that same search into an agent (LangChain, MCP) or call it over REST once you've created a retriever.
</Tip>

<Tabs>
  <Tab title="MVS Standalone (fastest)">
    Already have embeddings? Skip extraction — search in under 60 seconds.

    ```bash theme={null}
    pip install mixpeek
    export MIXPEEK_API_KEY="sk_live_replace_me"
    ```

    <Steps>
      <Step title="Create a standalone namespace">
        ```python theme={null}
        import os
        from mixpeek import Mixpeek

        client = Mixpeek(api_key=os.environ["MIXPEEK_API_KEY"])

        client.namespaces.create(
            namespace_id="my-search",   # you choose this id in standalone mode
            mode="standalone",
        )
        ```
      </Step>

      <Step title="Upsert your vectors">
        ```python theme={null}
        client.namespaces.documents.upsert(
            namespace_id="my-search",
            documents=[{
                "document_id": "doc-001",
                "vectors": {"embedding": [0.12, -0.34, 0.56]},  # your embedding
                "payload": {"title": "First document", "category": "demo"},
            }],
        )
        ```
      </Step>

      <Step title="Search">
        Vectors are searchable within **10–30 seconds** of upsert (the index flushes in the background). For immediate verification, add a short poll:

        ```python theme={null}
        import time

        # Wait for indexing
        time.sleep(15)

        results = client.search(
            namespace_id="my-search",
            queries=[{
                "vector_name": "embedding",
                "vector": [0.15, -0.28, 0.44],  # query embedding
                "top_k": 10,
            }],
        )
        for hit in results["results"]:
            print(f"{hit['score']:.3f} | {hit['payload']['title']}")
        ```
      </Step>
    </Steps>

    <Tip>
      MVS infers vector dimensions on first write — no schema needed. When you're ready for automatic extraction, [promote your namespace to Managed](/vector-store/promote).
    </Tip>
  </Tab>

  <Tab title="LangChain Agent">
    Build a LangChain agent with a `video_search` tool backed by Mixpeek.

    ```bash theme={null}
    pip install mixpeek langchain langchain-openai
    export MIXPEEK_API_KEY="sk_live_replace_me"
    export OPENAI_API_KEY="sk-replace_me"
    ```

    <Steps>
      <Step title="Create namespace, bucket, and collection">
        ```python theme={null}
        import os
        from mixpeek import Mixpeek

        client = Mixpeek(api_key=os.environ["MIXPEEK_API_KEY"])

        ns = client.namespaces.create(
            namespace_name="agent-video-demo",
            feature_extractors=[
                {"feature_extractor_name": "multimodal_extractor", "version": "v1"}
            ]
        )

        bucket = client.buckets.create(
            bucket_name="demo-videos",
            namespace_id=ns.namespace_id,
            bucket_schema={"properties": {"video_url": {"type": "video"}}}
        )

        col = client.collections.create(
            collection_name="video-scenes",
            namespace_id=ns.namespace_id,
            source={"type": "bucket", "bucket_ids": [bucket.bucket_id]},
            feature_extractor={
                "feature_extractor_name": "multimodal_extractor",
                "version": "v1",
                "input_mappings": {"video": "video_url"},
            }
        )
        ```
      </Step>

      <Step title="Upload and process">
        ```python theme={null}
        obj = client.objects.create(
            bucket_id=bucket.bucket_id,
            namespace_id=ns.namespace_id,
            key_prefix="/samples",
            blobs=[{"property": "video_url", "type": "video", "data": "https://storage.googleapis.com/mixpeek-public-demo/videos/sample-product-demo.mp4"}]
        )

        batch = client.batches.create(bucket_id=bucket.bucket_id, namespace_id=ns.namespace_id, object_ids=[obj.object_id])
        result = client.batches.submit(bucket_id=bucket.bucket_id, batch_id=batch.batch_id, namespace_id=ns.namespace_id)
        ```

        Poll `client.tasks.get(task_id=result.task_id)` until the status is terminal — `COMPLETED` or `COMPLETED_WITH_ERRORS` (1-5 min). Don't wait only for `COMPLETED`, or a batch that finished with some failed items will hang your loop.
      </Step>

      <Step title="Create a retriever and wire it as a tool">
        ```python theme={null}
        from langchain.tools import Tool
        from langchain_openai import ChatOpenAI
        from langchain.agents import AgentExecutor, create_openai_tools_agent
        from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder

        ret = client.retrievers.create(
            retriever_name="agent-video-search",
            namespace_id=ns.namespace_id,
            input_schema={"query_text": {"type": "text", "required": True}},
            collection_identifiers=[col.collection_id],
            stages=[{
                "stage_name": "search",
                "stage_type": "filter",
                "config": {
                    "stage_id": "feature_search",
                    "parameters": {
                        "searches": [{
                            "feature_uri": "mixpeek://multimodal_extractor@v1/vertex_multimodal_embedding",
                            "query": {"input_mode": "text", "value": "{{INPUT.query_text}}"},
                            "top_k": 50
                        }],
                        "final_top_k": 20
                    }
                }
            }]
        )

        def search_video(query: str) -> str:
            results = client.retrievers.execute(
                retriever_id=ret.retriever_id, namespace_id=ns.namespace_id,
                inputs={"query_text": query}, limit=5
            )
            return "\n".join(
                f"[{r.metadata.get('start_time','?')}s] (score: {r.score:.3f}) {r.metadata.get('description','')}"
                for r in results.results
            ) or "No results found."

        video_tool = Tool(name="video_search", description="Search indexed video by natural language", func=search_video)
        llm = ChatOpenAI(model="gpt-4o", temperature=0)
        prompt = ChatPromptTemplate.from_messages([
            ("system", "You answer questions about video content. Use video_search to find relevant moments."),
            ("human", "{input}"), MessagesPlaceholder(variable_name="agent_scratchpad"),
        ])
        agent = create_openai_tools_agent(llm, [video_tool], prompt)
        executor = AgentExecutor(agent=agent, tools=[video_tool], verbose=True)
        print(executor.invoke({"input": "What product features are shown?"})["output"])
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="MCP (Claude)">
    Add Mixpeek as a tool in Claude Desktop or Claude Code — no code required.

    <Tabs>
      <Tab title="Claude Desktop">
        Open `claude_desktop_config.json` and add:

        ```json theme={null}
        {
          "mcpServers": {
            "mixpeek-retrieval": {
              "url": "https://mcp.mixpeek.com/retrieval/mcp",
              "headers": {
                "Authorization": "Bearer YOUR_API_KEY"
              }
            }
          }
        }
        ```
      </Tab>

      <Tab title="Claude Code">
        Add `.mcp.json` to your project root:

        ```json theme={null}
        {
          "mcpServers": {
            "mixpeek-retrieval": {
              "url": "https://mcp.mixpeek.com/retrieval/mcp",
              "headers": {
                "Authorization": "Bearer YOUR_API_KEY"
              }
            }
          }
        }
        ```
      </Tab>
    </Tabs>

    Restart Claude and ask: *"What Mixpeek tools do you have access to?"*

    | Scope         | URL                                     | Tools |
    | ------------- | --------------------------------------- | ----- |
    | **Full**      | `https://mcp.mixpeek.com/mcp`           | 48    |
    | **Ingestion** | `https://mcp.mixpeek.com/ingestion/mcp` | 20    |
    | **Retrieval** | `https://mcp.mixpeek.com/retrieval/mcp` | 11    |
    | **Admin**     | `https://mcp.mixpeek.com/admin/mcp`     | 17    |

    See the [full MCP reference](/agent-integrations/mcp) for per-retriever servers and troubleshooting.
  </Tab>

  <Tab title="REST API">
    Call `POST /v1/retrievers/{id}/execute` from any language.

    ```python theme={null}
    import os
    import requests

    MIXPEEK_API_KEY = os.environ["MIXPEEK_API_KEY"]
    MIXPEEK_NAMESPACE = os.environ["MIXPEEK_NAMESPACE"]  # the namespace_id (ns_...) returned at creation
    RETRIEVER_ID = os.environ["MIXPEEK_RETRIEVER_ID"]    # the retriever_id (ret_...) from retrievers.create

    HEADERS = {
        "Authorization": f"Bearer {MIXPEEK_API_KEY}",
        "X-Namespace": MIXPEEK_NAMESPACE,
        "Content-Type": "application/json",
    }

    resp = requests.post(
        f"https://api.mixpeek.com/v1/retrievers/{RETRIEVER_ID}/execute",
        headers=HEADERS,
        json={"inputs": {"query_text": "safety regulations"}},
    )
    results = resp.json()["results"]
    ```

    Each result contains `score`, `metadata`, and `content`. Wrap this call as a tool in any agent framework — OpenAI function calling, CrewAI, LlamaIndex, or plain HTTP.

    See the [API reference](/api-reference/retrievers/execute-retriever-auto-optimized) for full request and response details.
  </Tab>
</Tabs>