Skip to main content
If your agent framework is not LangChain or MCP, call Mixpeek’s REST API directly — any language, any framework, one HTTP call.

​
Core Pattern

Your agent calls POST /v1/retrievers/{id}/execute with a query and gets back scored results with metadata. Wrap that call as a tool in whatever framework you use.
1

Set Up Authentication

Grab your API key from mixpeek.com/start and set your namespace. Every request needs two headers:
export MIXPEEK_API_KEY="sk_live_replace_me"
export MIXPEEK_NAMESPACE="ns_xxx"

import requests

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

Execute a Retriever

Replace RETRIEVER_ID with your retriever’s ID.
resp = requests.post(
    f"https://api.mixpeek.com/v1/retrievers/{RETRIEVER_ID}/execute",
    headers=HEADERS,
    json={
        "inputs": {"query_text": "safety regulations for lithium batteries"},
        "limit": 10,
    },
)
results = resp.json()
3

Parse the Response

The response returns a list of scored results:
{
  "results": [
    {
      "document_id": "doc_abc123",
      "score": 0.92,
      "metadata": {
        "filename": "battery_safety_guide.pdf",
        "chunk_index": 14
      },
      "content": "Lithium-ion cells must comply with UN38.3 testing..."
    }
  ]
}
Each result contains a score (relevance), metadata (from ingestion), and content (the matched chunk). Feed these into your agent’s context window.

​
OpenAI Function Calling

Define the retriever as a tool schema, then wire it into the chat completion loop.

​
Function Schema

retriever_tool = {
    "type": "function",
    "function": {
        "name": "search_documents",
        "description": "Search the knowledge base using Mixpeek retriever",
        "parameters": {
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "Natural language search query",
                }
            },
            "required": ["query"],
        },
    },
}

​
Wiring It Up

import json
import openai
import requests

MIXPEEK_API_KEY = "sk_live_replace_me"
MIXPEEK_NAMESPACE = "ns_xxx"
RETRIEVER_ID = "ret_xxx"

def search_documents(query: str) -> list:
    resp = requests.post(
        f"https://api.mixpeek.com/v1/retrievers/{RETRIEVER_ID}/execute",
        headers={
            "Authorization": f"Bearer {MIXPEEK_API_KEY}",
            "X-Namespace": MIXPEEK_NAMESPACE,
            "Content-Type": "application/json",
        },
        json={"inputs": {"query_text": query}, "limit": 5},
    )
    return resp.json()["results"]

client = openai.OpenAI()

messages = [{"role": "user", "content": "What are the safety rules for lithium batteries?"}]

response = client.chat.completions.create(
    model="gpt-4o",
    messages=messages,
    tools=[retriever_tool],
)

tool_call = response.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
results = search_documents(args["query"])

# Feed results back to the model
messages.append(response.choices[0].message)
messages.append({
    "role": "tool",
    "tool_call_id": tool_call.id,
    "content": json.dumps(results),
})

final = client.chat.completions.create(
    model="gpt-4o",
    messages=messages,
    tools=[retriever_tool],
)
print(final.choices[0].message.content)

​
CrewAI

from crewai.tools import tool
import requests

@tool("Search Mixpeek")
def search_mixpeek(query: str) -> str:
    """Search the knowledge base for relevant documents."""
    resp = requests.post(
        f"https://api.mixpeek.com/v1/retrievers/{RETRIEVER_ID}/execute",
        headers=HEADERS,
        json={"inputs": {"query_text": query}, "limit": 5},
    )
    return str(resp.json()["results"])
Assign search_mixpeek to any CrewAI agent’s tools list.

​
Any Framework

The pattern is the same regardless of framework: 
def mixpeek_search(query: str, limit: int = 10) -> list:
    """Generic wrapper -- adapt to your framework's tool interface."""
    resp = requests.post(
        f"https://api.mixpeek.com/v1/retrievers/{RETRIEVER_ID}/execute",
        headers={
            "Authorization": f"Bearer {MIXPEEK_API_KEY}",
            "X-Namespace": MIXPEEK_NAMESPACE,
            "Content-Type": "application/json",
        },
        json={"inputs": {"query_text": query}, "limit": limit},
    )
    resp.raise_for_status()
    return resp.json()["results"]
This wrapper works with LlamaIndex FunctionTool, Haystack @component, Autogen tool registration, or any framework that accepts a Python callable as a tool.