Quickstart - Mixpeek

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

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.

MVS Standalone (fastest)
LangChain Agent
MCP (Claude)
REST API

Already have embeddings? Skip extraction — search in under 60 seconds.

pip install mixpeek
export MIXPEEK_API_KEY="sk_live_replace_me"

Create a standalone namespace

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

Upsert your vectors

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

Vectors are searchable within 10–30 seconds of upsert (the index flushes in the background). For immediate verification, add a short poll:

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

MVS infers vector dimensions on first write — no schema needed. When you’re ready for automatic extraction, promote your namespace to Managed.

Build a LangChain agent with a video_search tool backed by Mixpeek.

pip install mixpeek langchain langchain-openai
export MIXPEEK_API_KEY="sk_live_replace_me"
export OPENAI_API_KEY="sk-replace_me"

Create namespace, bucket, and collection

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

Upload and process

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.

Create a retriever and wire it as a tool

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

Add Mixpeek as a tool in Claude Desktop or Claude Code — no code required.

Claude Desktop
Claude Code

Open claude_desktop_config.json and add:

{
  "mcpServers": {
    "mixpeek-retrieval": {
      "url": "https://mcp.mixpeek.com/retrieval/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Add .mcp.json to your project root:

{
  "mcpServers": {
    "mixpeek-retrieval": {
      "url": "https://mcp.mixpeek.com/retrieval/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

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 for per-retriever servers and troubleshooting.

Call POST /v1/retrievers/{id}/execute from any language.

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 for full request and response details.