Mixedbread

https://www.mixedbread.com/docs
Admin
Mixedbread is a platform for integrating fast, multimodal search into applications, agents, and AI...
Tokens:54,282
Snippets:483
Trust Score:6.8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install dependencies and configure environment

Source: https://www.mixedbread.com/docs/agent/responses

Setup instructions for the OpenAI SDK and API key configuration.

```bash
pip install openai
```

```bash
npm install openai
```

```bash
export MXBAI_API_KEY=YOUR_API_KEY
```

--------------------------------

### Install Package Command

Source: https://www.mixedbread.com/docs/stores/store-files/generated-metadata

Example command for installing a package as referenced in the markdown documentation.

```bash
pip install package
```

--------------------------------

### Install Mixedbread SDK

Source: https://www.mixedbread.com/docs/quickstart

Install the SDK using your preferred package manager.

```bash
pip install mixedbread
```

```bash
npm install @mixedbread/sdk
```

```bash
pnpm add @mixedbread/sdk
```

```bash
yarn add @mixedbread/sdk
```

```bash
bun add @mixedbread/sdk
```

--------------------------------

### Complete Store Chunk Example

Source: https://www.mixedbread.com/docs/stores/data-models

A comprehensive example showing all standard properties including metadata and file identifiers.

```json
{
  "chunk_index": 3,
  "mime_type": "text/plain",
  "model": "mixedbread-ai/mxbai-omni-v1",
  "score": 0.92,
  "file_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "filename": "product-documentation.pdf",
  "store_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "external_id": "doc-auth-guide-v2",
  "metadata": {
    "category": "documentation",
    "department": "product"
  },
  "type": "text",
  "text": "To authenticate API requests, include your API key in the Authorization header: Authorization: Bearer YOUR_API_KEY. The API key identifies your account and provides access to your organization's resources.",
  "offset": 4096
}
```

--------------------------------

### Install Mixedbread CLI

Source: https://www.mixedbread.com/docs/quickstart

Install the CLI globally using your preferred package manager.

```bash
npm install -g @mixedbread/cli
```

```bash
pnpm add -g @mixedbread/cli
```

```bash
yarn global add @mixedbread/cli
```

```bash
bun add -g @mixedbread/cli
```

--------------------------------

### Install OpenAI SDK dependencies

Source: https://www.mixedbread.com/docs/agent/chat-completions

Install the necessary package for Python or TypeScript environments.

```bash
pip install openai
```

```bash
npm install openai
```

--------------------------------

### Install Mixedbread MCP Server

Source: https://www.mixedbread.com/docs/changelog

Use this command to install the Mixedbread MCP server globally via npm.

```bash
npm install -g @mixedbread/mcp
```

--------------------------------

### Use comparison operators

Source: https://www.mixedbread.com/docs/stores/metadata-filtering

Examples of equality, range, list membership, and string pattern matching operators.

```json
// Equal to
{"key": "status", "operator": "eq", "value": "published"}

// Not equal to
{"key": "status", "operator": "not_eq", "value": "draft"}

// Greater than
{"key": "priority", "operator": "gt", "value": 5}

// Greater than or equal to
{"key": "created_at", "operator": "gte", "value": "2024-01-01"}

// Less than
{"key": "rating", "operator": "lt", "value": 3.0}

// Less than or equal to
{"key": "rating", "operator": "lte", "value": 4.5}

// Value in list
{"key": "tags", "operator": "in", "value": ["tutorial", "guide"]}

// Value not in list
{"key": "language", "operator": "not_in", "value": ["deprecated", "legacy"]}

// Contains: substring match on a text field (case-sensitive)
{"key": "title", "operator": "contains", "value": "guide"}

// Contains: membership in a list/array field (e.g. a "tags" array that includes "tutorial")
{"key": "tags", "operator": "contains", "value": "tutorial"}

// Regex matching (case-sensitive)
{"key": "title", "operator": "regex", "value": "^red.*$"}

// String starts with (case-sensitive)
{"key": "category", "operator": "starts_with", "value": "/Users"}

// String does not start with
{"key": "path", "operator": "not_like", "value": "/tmp/*"}
```

--------------------------------

### Perform a basic semantic search

Source: https://www.mixedbread.com/docs/stores/search

Use these examples to query your store for relevant content chunks using natural language.

```python
from mixedbread import Mixedbread

mxbai = Mixedbread(api_key="YOUR_API_KEY")

response = mxbai.stores.search(
    query="How does authentication work?",
    store_identifiers=["my-knowledge-base"],
    top_k=5,
)

for chunk in response.data:
    print(chunk)
```

```python
from mixedbread import AsyncMixedbread

mxbai = AsyncMixedbread(api_key="YOUR_API_KEY")

response = await mxbai.stores.search(
    query="How does authentication work?",
    store_identifiers=["my-knowledge-base"],
    top_k=5,
)

for chunk in response.data:
    print(chunk)
```

```typescript
import { Mixedbread } from "@mixedbread/sdk";

const mxbai = new Mixedbread({
  apiKey: "YOUR_API_KEY",
});

const response = await mxbai.stores.search({
  query: "How does authentication work?",
  store_identifiers: ["my-knowledge-base"],
  top_k: 5,
});

for (const chunk of response.data) {
  console.log(chunk);
}
```

```bash
curl -X POST https://api.mixedbread.com/v1/stores/search \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "query": "How does authentication work?",
    "store_identifiers": ["my-knowledge-base"],
    "top_k": 5
  }'
```

--------------------------------

### Configure Agentic Search

Source: https://www.mixedbread.com/docs/stores/search/agentic-search

Examples of configuring agentic search using Python, TypeScript, and cURL.

```python
from mixedbread import Mixedbread

mxbai = Mixedbread(api_key="YOUR_API_KEY")

results = mxbai.stores.search(
    query="What are the yearly numbers for 2020, 2021, 2022, 2023, 2024, 2025?",
    store_identifiers=["yearly-reports"],
    search_options={
        "agentic": {
            "strict_top_k": True,
            "instructions": (
                "Search for revenue, profitability, and headcount trends before ranking the results."
            ),
        }
    },
)

print(results)
```

```python
from mixedbread import AsyncMixedbread

mxbai = AsyncMixedbread(api_key="YOUR_API_KEY")

results = await mxbai.stores.search(
    query="What are the yearly numbers for 2020, 2021, 2022, 2023, 2024, 2025?",
    store_identifiers=["yearly-reports"],
    search_options={
        "agentic": {
            "strict_top_k": True,
            "instructions": (
                "Search for revenue, profitability, and headcount trends before ranking the results."
            ),
        }
    },
)

print(results)
```

```typescript
import { Mixedbread } from "@mixedbread/sdk";

const mxbai = new Mixedbread({
  apiKey: "YOUR_API_KEY",
});

const results = await mxbai.stores.search({
  query: "What are the yearly numbers for 2020, 2021, 2022, 2023, 2024, 2025?",
  store_identifiers: ["yearly-reports"],
  search_options: {
    agentic: {
      strict_top_k: true,
      instructions:
        "Search for revenue, profitability, and headcount trends before ranking the results.",
    },
  },
});

console.log(results);
```

```bash
curl -X POST https://api.mixedbread.com/v1/stores/search \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "query": "What are the yearly numbers for 2020, 2021, 2022, 2023, 2024, 2025?",
    "store_identifiers": ["yearly-reports"],
    "search_options": {
      "agentic": {
        "strict_top_k": true,
        "instructions": "Search for revenue, profitability, and headcount trends before ranking the results."
      }
    }
  }'
```

--------------------------------

### Manage Metadata with Python

Source: https://www.mixedbread.com/docs/quickstart

Examples for uploading files with metadata and searching with filters using both synchronous and asynchronous Python clients.

```python
from mixedbread import Mixedbread
from pathlib import Path

# Initialize the client
mxbai = Mixedbread(api_key="YOUR_API_KEY")

# Create a Store
store = mxbai.stores.create(name="my-knowledge-base")

# Upload files with metadata for better organization
file_result = mxbai.stores.files.upload_and_poll(
    store_identifier=store.id,
    file=Path("./document.pdf"),
    metadata={
        "category": "documentation",
        "department": "engineering",
        "tags": ["api", "tutorial"],
    },
)

# Search with metadata filtering to find specific content
results = mxbai.stores.search(
    query="What are the key features?",
    store_identifiers=[store.id],
    top_k=3,
    filters={"key": "category", "operator": "eq", "value": "documentation"},
)

# Display the filtered results
for chunk in results.data:
    print(chunk)
```

```python
from mixedbread import AsyncMixedbread
from pathlib import Path

# Initialize the async client
mxbai = AsyncMixedbread(api_key="YOUR_API_KEY")

# Create a Store
store = await mxbai.stores.create(name="my-knowledge-base")

# Upload files with metadata for better organization
file_result = await mxbai.stores.files.upload_and_poll(
    store_identifier=store.id,
    file=Path("./document.pdf"),
    metadata={
        "category": "documentation",
        "department": "engineering",
        "tags": ["api", "tutorial"],
    },
)

# Search with metadata filtering to find specific content
results = await mxbai.stores.search(
    query="What are the key features?",
    store_identifiers=[store.id],
    top_k=3,
    filters={"key": "category", "operator": "eq", "value": "documentation"},
)

# Display the filtered results
for chunk in results.data:
    print(chunk)
```

--------------------------------

### Install Mixedbread Agent Skills

Source: https://www.mixedbread.com/docs

Use this command to add the Mixedbread skills package to your coding agent environment.

```bash
npx skills add mixedbread-ai/skills
```

--------------------------------

### Configure Question Answering with SDKs and REST API

Source: https://www.mixedbread.com/docs/stores/search/question-answering

Examples demonstrating how to disable citations and multimodal context in Question Answering requests.

```python
from mixedbread import Mixedbread

mxbai = Mixedbread(api_key="YOUR_API_KEY")

response = mxbai.stores.question_answering(
    store_identifiers=["my-knowledge-base"],
    query="What were the key decisions made last quarter?",
    top_k=5,
    qa_options={"cite": False, "multimodal": False},
)

print(response)
```

```python
from mixedbread import AsyncMixedbread

mxbai = AsyncMixedbread(api_key="YOUR_API_KEY")

response = await mxbai.stores.question_answering(
    store_identifiers=["my-knowledge-base"],
    query="What were the key decisions made last quarter?",
    top_k=5,
    qa_options={
        "cite": False,
        "multimodal": False,
    },
)

print(response)
```

```typescript
import { Mixedbread } from "@mixedbread/sdk";

const mxbai = new Mixedbread({
  apiKey: "YOUR_API_KEY",
});

const response = await mxbai.stores.questionAnswering({
  store_identifiers: ["my-knowledge-base"],
  query: "What were the key decisions made last quarter?",
  top_k: 5,
  qa_options: {
    cite: false,
    multimodal: false,
  },
});

console.log(response);
```

```bash
curl -X POST https://api.mixedbread.com/v1/stores/question-answering \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "store_identifiers": ["my-knowledge-base"],
    "query": "What were the key decisions made last quarter?",
    "top_k": 5,
    "qa_options": {
      "cite": false,
      "multimodal": false
    }
  }'
```

--------------------------------

### Video Chunk Example and Schema

Source: https://www.mixedbread.com/docs/stores/store-files/mxjson

Defines the structure for video chunks, requiring a video URL and optional metadata.

```json
{
  "type": "video_url",
  "video_url": {
    "url": "https://bakery.example.com/video/shaping-boule.mp4"
  },
  "mime_type": "video/mp4",
  "generated_metadata": {
    "type": "video",
    "file_type": "video/mp4",
    "file_size": 10485760,
    "total_duration_seconds": 120.0,
    "fps": 30.0,
    "width": 1920,
    "height": 1080,
    "frame_count": 3600,
    "has_audio_stream": true
  }
}
```

```json
{
  "type": "object",
  "required": ["video_url"],
  "properties": {
    "type": { "const": "video_url", "default": "video_url" },
    "video_url": {
      "type": "object",
      "required": ["url"],
      "properties": {
        "url": { "type": "string", "description": "HTTP URL or Data URI" }
      }
    },
    "mime_type": { "type": "string", "default": "video/mp4" },
    "chunk_index": { "type": ["integer", "null"], "default": null },
    "generated_metadata": {
      "type": ["object", "null"],
      "default": null,
      "properties": {
        "type": { "const": "video" },
        "file_type": { "type": "string", "default": "video/mp4" },
        "file_size": { "type": ["integer", "null"] },
        "total_duration_seconds": { "type": ["number", "null"] },
        "fps": { "type": ["number", "null"] },
        "width": { "type": ["integer", "null"] },
        "height": { "type": ["integer", "null"] },
        "frame_count": { "type": ["integer", "null"] },
        "has_audio_stream": { "type": "boolean", "default": false }
      },
      "required": ["type"],
      "additionalProperties": true
    }
  }
}
```

--------------------------------

### Perform Web Search with Mixedbread

Source: https://www.mixedbread.com/docs/stores/search/web-store

Examples of searching the web using the Mixedbread SDKs and direct API requests.

```python
from mixedbread import Mixedbread

mxbai = Mixedbread(api_key="YOUR_API_KEY")

results = mxbai.stores.search(
    query="latest developments in transformer architectures",
    store_identifiers=["mixedbread/web"],
    top_k=10,
)

for chunk in results.data:
    print(f"Title: {chunk.metadata.get('title')}")
    print(f"URL: {chunk.metadata.get('url')}")
    print(f"Content: {chunk.text[:200]}...")
    print()
```

```python
from mixedbread import AsyncMixedbread

mxbai = AsyncMixedbread(api_key="YOUR_API_KEY")

results = await mxbai.stores.search(
    query="latest developments in transformer architectures",
    store_identifiers=["mixedbread/web"],
    top_k=10,
)

for chunk in results.data:
    print(f"Title: {chunk.metadata.get('title')}")
    print(f"URL: {chunk.metadata.get('url')}")
    print(f"Content: {chunk.text[:200]}...")
    print()
```

```typescript
import { Mixedbread } from "@mixedbread/sdk";

const mxbai = new Mixedbread({
  apiKey: "YOUR_API_KEY",
});

const results = await mxbai.stores.search({
  query: "latest developments in transformer architectures",
  store_identifiers: ["mixedbread/web"],
  top_k: 10,
});

for (const chunk of results.data) {
  const metadata = chunk.metadata as
    | { title: string; url: string; text: string }
    | undefined;
  console.log(`Title: ${metadata?.title}`);
  console.log(`URL: ${metadata?.url}`);
  console.log(`Content: ${metadata?.text.slice(0, 200)}...`);
  console.log();
}
```

```bash
curl -X POST https://api.mixedbread.com/v1/stores/search \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "query": "latest developments in transformer architectures",
    "store_identifiers": ["mixedbread/web"],
    "top_k": 10
  }'
```

--------------------------------

### Example of Chunk Metadata Structure

Source: https://www.mixedbread.com/docs/stores/store-files/mxjson

A sample JSON object demonstrating the inclusion of generated_metadata within a chunk.

```json
{
  "type": "text",
  "text": "Autolyse is a rest period after mixing flour and water.",
  "mime_type": "text/plain",
  "generated_metadata": {
    "type": "text",
    "file_type": "text/plain",
    "language": "en",
    "word_count": 10,
    "file_size": 2048
  }
}
```

--------------------------------

### Audio Chunk Example and Schema

Source: https://www.mixedbread.com/docs/stores/store-files/mxjson

Defines the structure for audio chunks, requiring an audio URL and sampling rate.

```json
{
  "type": "audio_url",
  "audio_url": {
    "url": "https://bakery.example.com/audio/kneading-tutorial.mp3"
  },
  "mime_type": "audio/mpeg",
  "sampling_rate": 44100,
  "generated_metadata": {
    "type": "audio",
    "file_type": "audio/mpeg",
    "file_size": 5242880,
    "total_duration_seconds": 180.5,
    "sample_rate": 44100,
    "channels": 2,
    "audio_format": 1
  }
}
```

```json
{
  "type": "object",
  "required": ["audio_url", "sampling_rate"],
  "properties": {
    "type": { "const": "audio_url", "default": "audio_url" },
    "audio_url": {
      "type": "object",
      "required": ["url"],
      "properties": {
        "url": { "type": "string", "description": "HTTP URL or Data URI" }
      }
    },
    "mime_type": { "type": "string", "default": "audio/mpeg" },
    "sampling_rate": { "type": "integer" },
    "chunk_index": { "type": ["integer", "null"], "default": null },
    "generated_metadata": {
      "type": ["object", "null"],
      "default": null,
      "properties": {
        "type": { "const": "audio" },
        "file_type": { "type": "string", "default": "audio/mpeg" },
        "file_size": { "type": ["integer", "null"] },
        "total_duration_seconds": { "type": ["number", "null"] },
        "sample_rate": { "type": ["integer", "null"] },
        "channels": { "type": ["integer", "null"] },
        "audio_format": { "type": ["integer", "null"] }
      },
      "required": ["type"],
      "additionalProperties": true
    }
  }
}
```

--------------------------------

### GET /v1/stores/{store_identifier}/files

Source: https://www.mixedbread.com/docs/stores/store-files/manage-store-files

List all files in a specific store using cursor-based pagination.

```APIDOC
## GET /v1/stores/{store_identifier}/files

### Description
View all files in your Store. The list operation uses cursor-based pagination.

### Method
GET

### Endpoint
https://api.mixedbread.com/v1/stores/{store_identifier}/files

### Parameters
#### Path Parameters
- **store_identifier** (string) - Required - The unique identifier of the store.

#### Query Parameters
- **limit** (integer) - Optional - The number of files to return.
```

--------------------------------

### Text Chunk Example

Source: https://www.mixedbread.com/docs/stores/store-files/mxjson

A sample JSON object representing a single text chunk with associated metadata.

```json
{
  "type": "text",
  "text": "Sourdough fermentation relies on wild yeast and lactic acid bacteria.",
  "mime_type": "text/plain",
  "generated_metadata": {
    "type": "text",
    "file_type": "text/plain",
    "language": "en",
    "word_count": 10,
    "file_size": 512
  }
}
```

--------------------------------

### Delete a Store File

Source: https://www.mixedbread.com/docs/stores/store-files/manage-store-files

Examples for deleting a file from a store using various SDKs and the REST API.

```python
from mixedbread import Mixedbread

mxbai = Mixedbread(api_key="YOUR_API_KEY")

response = mxbai.stores.files.delete(
    store_identifier="my-knowledge-base",
    file_identifier="f47ac10b-58cc-4372-a567-0e02b2c3d479",
)

print(response)
```

```python
from mixedbread import AsyncMixedbread

mxbai = AsyncMixedbread(api_key="YOUR_API_KEY")

response = await mxbai.stores.files.delete(
    store_identifier="my-knowledge-base",
    file_identifier="f47ac10b-58cc-4372-a567-0e02b2c3d479",
)

print(response)
```

```typescript
import { Mixedbread } from "@mixedbread/sdk";

const mxbai = new Mixedbread({
  apiKey: "YOUR_API_KEY",
});

const response = await mxbai.stores.files.delete("f47ac10b-58cc-4372-a567-0e02b2c3d479", {
  store_identifier: "my-knowledge-base",
});

console.log(response);
```

```bash
curl -X DELETE https://api.mixedbread.com/v1/stores/my-knowledge-base/files/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

--------------------------------

### Retrieve Metadata Facets

Source: https://www.mixedbread.com/docs/stores/search/facets

Examples for fetching metadata facets across different SDKs and via direct API request.

```python
from mixedbread import Mixedbread

mxbai = Mixedbread(api_key="YOUR_API_KEY")

response = mxbai.stores.metadata_facets(
    store_identifiers=["docs"],
)

print(response.model_dump_json())
```

```python
from mixedbread import AsyncMixedbread

mxbai = AsyncMixedbread(api_key="YOUR_API_KEY")

response = await mxbai.stores.metadata_facets(
    store_identifiers=["docs"],
)

print(response.model_dump_json())
```

```typescript
import { Mixedbread } from "@mixedbread/sdk";

const mxbai = new Mixedbread({
  apiKey: "YOUR_API_KEY",
});

const response = await mxbai.stores.metadataFacets({
  store_identifiers: ["docs"],
});

console.log(response);
```

```bash
curl -X 'POST' \
  'https://api.mixedbread.com/v1/stores/metadata-facets' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "store_identifiers": ["docs"]
}'
```

--------------------------------

### Manage Metadata with TypeScript

Source: https://www.mixedbread.com/docs/quickstart

Example for uploading files with metadata and performing filtered searches using the TypeScript SDK.

```typescript
import * as fs from "node:fs";
import { Mixedbread } from "@mixedbread/sdk";

// Initialize the client
const mxbai = new Mixedbread({
  apiKey: "YOUR_API_KEY",
});

// Create a Store
const store = await mxbai.stores.create({
  name: "my-knowledge-base",
});

// Upload files with metadata for better organization
const fileResult = await mxbai.stores.files.uploadAndPoll({
  storeIdentifier: store.id,
  file: fs.createReadStream("./document.pdf"),
  body: {
    metadata: {
      category: "documentation",
      department: "engineering",
      tags: ["api", "tutorial"],
    },
  },
});

// Search with metadata filtering to find specific content
const results = await mxbai.stores.search({
  query: "What are the key features?",
  store_identifiers: [store.id],
  top_k: 3,
  filters: { key: "category", operator: "eq", value: "documentation" },
});

// Display the filtered results
for (const chunk of results.data) {
  console.log(chunk);
}
```

--------------------------------

### Store File JSON Representation

Source: https://www.mixedbread.com/docs/stores/data-models

Example of a Store File object showing its structure, including metadata and processing status.

```json
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "filename": "product-documentation.pdf",
  "metadata": {
    "category": "documentation",
    "department": "product",
    "version": "2.1",
    "last_updated": "2024-01-15"
  },
  "status": "completed",
  "last_error": null,
  "store_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "created_at": "2024-01-15T10:30:00Z",
  "version": 1,
  "usage_bytes": 245760,
  "object": "store.file"
}
```

--------------------------------

### Image Chunk Example and Schema

Source: https://www.mixedbread.com/docs/stores/store-files/mxjson

Defines the structure for image chunks, requiring an image URL and optional metadata.

```json
{
  "type": "image_url",
  "image_url": {
    "url": "https://bakery.example.com/images/crumb-structure.png"
  },
  "mime_type": "image/png",
  "generated_metadata": {
    "type": "image",
    "file_type": "image/png",
    "file_size": 204800,
    "width": 1200,
    "height": 800
  }
}
```

```json
{
  "type": "object",
  "required": ["image_url"],
  "properties": {
    "type": { "const": "image_url", "default": "image_url" },
    "image_url": {
      "type": "object",
      "required": ["url"],
      "properties": {
        "url": { "type": "string", "description": "HTTP URL or Data URI" }
      }
    },
    "mime_type": { "type": "string", "default": "image/jpeg" },
    "chunk_index": { "type": ["integer", "null"], "default": null },
    "generated_metadata": {
      "type": ["object", "null"],
      "default": null,
      "properties": {
        "type": { "const": "image" },
        "file_type": { "type": "string", "default": "image/jpeg" },
        "file_size": { "type": ["integer", "null"] },
        "width": { "type": ["integer", "null"] },
        "height": { "type": ["integer", "null"] }
      },
      "required": ["type"],
      "additionalProperties": true
    }
  }
}
```

--------------------------------

### Store JSON Object Representation

Source: https://www.mixedbread.com/docs/stores/data-models

A representative example of a Store object, illustrating the structure of metadata, file counts, and expiration configuration.

```json
{
  "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "name": "product-documentation",
  "description": "Complete product documentation and API reference",
  "is_public": false,
  "metadata": {
    "category": "documentation",
    "language": "en"
  },
  "file_counts": {
    "pending": 2,
    "in_progress": 1,
    "cancelled": 0,
    "completed": 10,
    "failed": 0,
    "total": 13
  },
  "expires_after": {
    "anchor": "last_active_at",
    "days": 30
  },
  "status": "in_progress",
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-20T14:30:00Z",
  "last_active_at": "2024-01-20T14:30:00Z",
  "usage_bytes": 1048576,
  "expires_at": "2024-02-19T14:30:00Z",
  "object": "store"
}
```

--------------------------------

### Create and Search Store with Python

Source: https://www.mixedbread.com/docs/quickstart

Initialize the client, create a store, upload files, and perform a natural language search.

```python
from mixedbread import Mixedbread
from pathlib import Path

# Initialize the client
mxbai = Mixedbread(api_key="YOUR_API_KEY")

# Create a Store
store = mxbai.stores.create(name="my-knowledge-base")

# Upload and process your files (PDFs, images, docs, code)
file_result = mxbai.stores.files.upload_and_poll(
    store_identifier=store.id, file=Path("document.pdf")
)

# Search your data with natural language
results = mxbai.stores.search(
    query="What are the key features?",
    store_identifiers=[store.id],
    top_k=3,
)

# Display the results
for chunk in results.data:
    print(chunk)
```

```python
from mixedbread import AsyncMixedbread
from pathlib import Path

# Initialize the async client
mxbai = AsyncMixedbread(api_key="YOUR_API_KEY")

# Create a Store
store = await mxbai.stores.create(name="my-knowledge-base")

# Upload and process your files (PDFs, images, docs, code)
file_result = await mxbai.stores.files.upload_and_poll(
    store_identifier=store.id, file=Path("document.pdf")
)

# Search your data with natural language
results = await mxbai.stores.search(
    query="What are the key features?",
    store_identifiers=[store.id],
    top_k=3,
)

# Display the results
for chunk in results.data:
    print(chunk)
```

--------------------------------

### Create a Store

Source: https://www.mixedbread.com/docs/stores/stores

Initialize a new store with a name and description using the SDKs or direct API requests.

```python
from mixedbread import Mixedbread

mxbai = Mixedbread(api_key="YOUR_API_KEY")

store = mxbai.stores.create(
    name="product-documentation",
    description="Product documentation and FAQs for customer support",
)

print(store)
```

```python
from mixedbread import AsyncMixedbread

mxbai = AsyncMixedbread(api_key="YOUR_API_KEY")

store = await mxbai.stores.create(
    name="product-documentation",
    description="Product documentation and FAQs for customer support",
)

print(store)
```

```typescript
import { Mixedbread } from "@mixedbread/sdk";

const mxbai = new Mixedbread({
  apiKey: "YOUR_API_KEY",
});

const store = await mxbai.stores.create({
  name: "product-documentation",
  description: "Product documentation and FAQs for customer support",
});

console.log(store);
```

```bash
curl -X POST https://api.mixedbread.com/v1/stores \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "name": "product-documentation",
    "description": "Product documentation and FAQs for customer support"
  }'
```

--------------------------------

### Create and Search Store with TypeScript

Source: https://www.mixedbread.com/docs/quickstart

Initialize the client, create a store, upload files using a read stream, and perform a natural language search.

```typescript
import * as fs from "node:fs";
import { Mixedbread } from "@mixedbread/sdk";

// Initialize the client
const mxbai = new Mixedbread({
  apiKey: "YOUR_API_KEY",
});

// Create a Store
const store = await mxbai.stores.create({
  name: "my-knowledge-base",
});

// Upload and process your files (PDFs, images, docs, code)
const fileResult = await mxbai.stores.files.uploadAndPoll({
  storeIdentifier: store.id,
  file: fs.createReadStream("path/to/file.pdf"),
});

// Search your data with natural language
const results = await mxbai.stores.search({
  query: "What are the key features?",
  store_identifiers: [store.id],
  top_k: 3,
});

// Display the results
for (const chunk of results.data) {
  console.log(chunk);
}
```

--------------------------------

### GET /v1/stores

Source: https://www.mixedbread.com/docs/stores/stores/manage-stores

List all Stores in your organization using cursor-based pagination.

```APIDOC
## GET /v1/stores

### Description
Get all Stores in your organization.

### Method
GET

### Endpoint
https://api.mixedbread.com/v1/stores

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The number of stores to return.
```

--------------------------------

### Configure and Use Mixedbread CLI

Source: https://www.mixedbread.com/docs/quickstart

Commands for setting up the API key, creating a store, uploading documents, and performing searches.

```bash
# Save your API key (one-time setup)
mxbai config keys add YOUR_API_KEY default

# Create a Store
mxbai store create "my-knowledge-base"

# Upload and process your files (PDFs, images, docs, code)
mxbai store upload "my-knowledge-base" ./documents/

# Search your data with natural language
mxbai store search "my-knowledge-base" "What are the key features?"
```

--------------------------------

### GET /v1/schemas/mxjson

Source: https://www.mixedbread.com/docs/stores/store-files/mxjson

Retrieves the JSON schema definition used for validating input data.

```APIDOC
## GET /v1/schemas/mxjson

### Description
Retrieve the JSON Schema programmatically to understand the expected data structure for requests.

### Method
GET

### Endpoint
https://api.mixedbread.com/v1/schemas/mxjson
```

--------------------------------

### Create a Store

Source: https://www.mixedbread.com/docs/stores/stores

Initializes a new store using the provided name. Requires an API key for authentication.

```python
from mixedbread import Mixedbread

mxbai = Mixedbread(api_key="YOUR_API_KEY")

store = mxbai.stores.create(name="my-knowledge-base")

print(store)
```

```python
from mixedbread import AsyncMixedbread

mxbai = AsyncMixedbread(api_key="YOUR_API_KEY")

store = await mxbai.stores.create(name="my-knowledge-base")

print(store)
```

```typescript
import { Mixedbread } from "@mixedbread/sdk";

const mxbai = new Mixedbread({
  apiKey: "YOUR_API_KEY",
});

const store = await mxbai.stores.create({
  name: "my-knowledge-base",
});

console.log(store);
```

```bash
curl -X POST https://api.mixedbread.com/v1/stores \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "name": "my-knowledge-base"
  }'
```

--------------------------------

### MXJSONL Format Example

Source: https://www.mixedbread.com/docs/stores/store-files/mxjson

A JSON Lines format where each line represents an independent data object.

```jsonl
{"type": "text", "text": "Baguette Shaping Guide", "mime_type": "text/plain", "chunk_index": 0, "generated_metadata": {"type": "text", "file_type": "text/plain", "language": "en", "word_count": 3, "file_size": 1024}}
{"type": "text", "text": "Pre-shape the dough into a loose rectangle.", "mime_type": "text/plain", "chunk_index": 1, "generated_metadata": {"type": "text", "file_type": "text/plain", "language": "en", "word_count": 8, "file_size": 1024}}
{"type": "image_url", "image_url": {"url": "https://bakery.example.com/images/baguette-preshape.jpg"}, "mime_type": "image/jpeg", "chunk_index": 2, "generated_metadata": {"type": "image", "file_type": "image/jpeg", "file_size": 153600, "width": 800, "height": 600}}
```

--------------------------------

### Create a public store

Source: https://www.mixedbread.com/docs/stores/stores

Configures a store with public access enabled.

```python
from mixedbread import Mixedbread

mxbai = Mixedbread(api_key="YOUR_API_KEY")

store = mxbai.stores.create(
    name="api-docs-v2",
    description="Public API documentation version 2.0",
    is_public=True,
)

print(store)
```

```python
from mixedbread import AsyncMixedbread

mxbai = AsyncMixedbread(api_key="YOUR_API_KEY")

store = await mxbai.stores.create(
    name="api-docs-v2",
    description="Public API documentation version 2.0",
    is_public=True,
)

print(store)
```

```typescript
import { Mixedbread } from "@mixedbread/sdk";

const mxbai = new Mixedbread({
  apiKey: "YOUR_API_KEY",
});

const store = await mxbai.stores.create({
  name: "api-docs-v2",
  description: "Public API documentation version 2.0",
  is_public: true,
});

console.log(store);
```

```bash
curl -X POST https://api.mixedbread.com/v1/stores \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "name": "api-docs-v2",
    "description": "Public API documentation version 2.0",
    "is_public": true
  }'
```

--------------------------------

### Connect Provider via OpenCode CLI

Source: https://www.mixedbread.com/docs/agent/integrations/opencode

Use the /connect command to authenticate the provider.

```text
/connect
```

--------------------------------

### Video Chunk JSON Representation

Source: https://www.mixedbread.com/docs/stores/data-models

Example of a video-based chunk including transcription and URL information.

```json
{
  "type": "video_url",
  "video_url": {
    "url": "https://signed-url-to-video.com/chunk_video_789"
  },
  "transcription": "Hello everyone, today we're going to demonstrate...",
  "chunk_index": 1,
  "mime_type": "video/mp4",
  "score": 0.88
}
```

--------------------------------

### Audio Chunk JSON Representation

Source: https://www.mixedbread.com/docs/stores/data-models

Example of an audio-based chunk including transcription and sampling rate.

```json
{
  "type": "audio_url",
  "audio_url": {
    "url": "https://signed-url-to-audio.com/chunk_audio_456"
  },
  "transcription": "Welcome to our product overview. In this section, we'll cover...",
  "sampling_rate": 44100,
  "chunk_index": 3,
  "mime_type": "audio/mpeg",
  "score": 0.82
}
```

--------------------------------

### GET /v1/stores/{store_identifier}

Source: https://www.mixedbread.com/docs/stores/stores/manage-stores

Retrieve details about a specific Store using its ID or unique name.

```APIDOC
## GET /v1/stores/{store_identifier}

### Description
Get details about a specific Store, including file counts, status, and usage statistics.

### Method
GET

### Endpoint
https://api.mixedbread.com/v1/stores/{store_identifier}

### Parameters
#### Path Parameters
- **store_identifier** (string) - Required - The unique ID or name of the store.
```

--------------------------------

### Create a store with file contextualization

Source: https://www.mixedbread.com/docs/stores/stores

Enables automatic generation of chunk-specific explanatory context from the original file.

```python
from mixedbread import Mixedbread

mxbai = Mixedbread(api_key="YOUR_API_KEY")

store = mxbai.stores.create(
    name="docs-store",
    config={
        "contextualization": {
            "with_file_context": True,
        }
    },
)

print(store)
```

```python
from mixedbread import AsyncMixedbread

mxbai = AsyncMixedbread(api_key="YOUR_API_KEY")

store = await mxbai.stores.create(
    name="docs-store",
    config={
        "contextualization": {
            "with_file_context": True,
        }
    },
)

print(store)
```

```typescript
import { Mixedbread } from "@mixedbread/sdk";

const mxbai = new Mixedbread({
  apiKey: "YOUR_API_KEY",
});

const store = await mxbai.stores.create({
  name: "docs-store",
  config: {
    contextualization: {
      with_file_context: true,
    },
  },
});

console.log(store);
```

```bash
curl -X POST https://api.mixedbread.com/v1/stores \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "name": "docs-store",
    "config": {
      "contextualization": {
        "with_file_context": true
      }
    }
  }'
```

--------------------------------

### MXJSON Format Example

Source: https://www.mixedbread.com/docs/stores/store-files/mxjson

A standard JSON array structure representing multiple data chunks with metadata.

```json
[
  {
    "type": "text",
    "text": "Baguette Shaping Guide",
    "mime_type": "text/plain",
    "chunk_index": 0,
    "generated_metadata": {
      "type": "text",
      "file_type": "text/plain",
      "language": "en",
      "word_count": 3,
      "file_size": 1024
    }
  },
  {
    "type": "text",
    "text": "Pre-shape the dough into a loose rectangle. Let it rest for 15-20 minutes to relax the gluten before final shaping.",
    "mime_type": "text/plain",
    "chunk_index": 1,
    "generated_metadata": {
      "type": "text",
      "file_type": "text/plain",
      "language": "en",
      "word_count": 20,
      "file_size": 1024
    }
  },
  {
    "type": "image_url",
    "image_url": {"url": "https://bakery.example.com/images/baguette-preshape.jpg"},
    "mime_type": "image/jpeg",
    "chunk_index": 2,
    "generated_metadata": {
      "type": "image",
      "file_type": "image/jpeg",
      "file_size": 153600,
      "width": 800,
      "height": 600
    }
  }
]
```

--------------------------------

### Create a store with metadata contextualization

Source: https://www.mixedbread.com/docs/stores/stores

Includes specific file metadata fields in each chunk to enhance retrieval accuracy.

```python
from mixedbread import Mixedbread

mxbai = Mixedbread(api_key="YOUR_API_KEY")

store = mxbai.stores.create(
    name="docs-store",
    config={
        "contextualization": {
            "with_metadata": ["title", "author.name", "category"]
        }
    },
)

print(store)
```

```python
from mixedbread import AsyncMixedbread

mxbai = AsyncMixedbread(api_key="YOUR_API_KEY")

store = await mxbai.stores.create(
    name="docs-store",
    config={
        "contextualization": {
            "with_metadata": ["title", "author.name", "category"]
        }
    },
)

print(store)
```

```typescript
import { Mixedbread } from "@mixedbread/sdk";

const mxbai = new Mixedbread({
  apiKey: "YOUR_API_KEY",
});

const store = await mxbai.stores.create({
  name: "docs-store",
  config: {
    contextualization: {
      with_metadata: ["title", "author.name", "category"],
    },
  },
});

console.log(store);
```

```bash
curl -X POST https://api.mixedbread.com/v1/stores \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "name": "docs-store",
    "config": {
      "contextualization": {
        "with_metadata": ["title", "author.name", "category"]
      }
    }
  }'
```

--------------------------------

### Image Chunk JSON Representation

Source: https://www.mixedbread.com/docs/stores/data-models

Example of an image-based chunk including URL, format, and OCR text.

```json
{
  "type": "image_url",
  "image_url": {
    "url": "https://signed-url-to-image.com/chunk_img_123",
    "format": "png"
  },
  "ocr_text": "Figure 1: Authentication Flow Diagram",
  "summary": "A diagram showing the authentication flow process",
  "chunk_index": 5,
  "mime_type": "image/png",
  "score": 0.76
}
```

--------------------------------

### Create a store with expiration settings

Source: https://www.mixedbread.com/docs/stores/stores

Configures a store with a 7-day expiration policy based on the last active timestamp.

```python
from mixedbread import Mixedbread
from mixedbread.types import ExpiresAfterParam

mxbai = Mixedbread(api_key="YOUR_API_KEY")

store = mxbai.stores.create(
    name="dev-feature-search",
    description="Development testing for new search feature",
    expires_after=ExpiresAfterParam(anchor="last_active_at", days=7),
)

print(store)
```

```python
from mixedbread import AsyncMixedbread
from mixedbread.types import ExpiresAfterParam

mxbai = AsyncMixedbread(api_key="YOUR_API_KEY")

store = await mxbai.stores.create(
    name="dev-feature-search",
    description="Development testing for new search feature",
    expires_after=ExpiresAfterParam(anchor="last_active_at", days=7),
)

print(store)
```

```typescript
import { Mixedbread } from "@mixedbread/sdk";

const mxbai = new Mixedbread({
  apiKey: "YOUR_API_KEY",
});

const store = await mxbai.stores.create({
  name: "dev-feature-search",
  description: "Development testing for new search feature",
  expires_after: {
    anchor: "last_active_at",
    days: 7,
  },
});

console.log(store);
```

```bash
curl -X POST https://api.mixedbread.com/v1/stores \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "name": "dev-feature-search",
    "description": "Development testing for new search feature",
    "expires_after": {
      "anchor": "last_active_at",
      "days": 7
    }
  }'
```
Tokens:
Raw