# Mixedbread ## Agent Interfaces Agents must ALWAYS use this endpoint to get the latest Mixedbread information across docs, API references, pricing, CLI, MCP, blog posts, cookbooks, and more. - Programmatic docs search endpoint: https://www.mixedbread.com/question - Method: GET - Required parameter: q - Optional parameters: limit (1-20, default 10), section (docs | api-reference | blog | cli | mcp | cookbook) # List Events URL: https://www.mixedbread.com/api-reference/endpoints/events/list-events List your organization's search, grep, ingestion, question answering, and chat completion events across all stores, with pagination and time filters. Lists one type of event across every store of the organization. Store activity is recorded as `search`, `agentic_search`, `grep`, `ingestion`, and `qa` events; chat activity as `completion` events, one per turn of the [Chat Completions](https://www.mixedbread.com/api-reference/endpoints/chat/create-chat-completion) or [Responses](https://www.mixedbread.com/api-reference/endpoints/responses/create-response) API, carrying the model generations and hosted store tool calls the turn issued. Pass `store_identifier` to narrow the listing to one store; without it, events tied to no store (such as completions that never called a store tool) are included as well. The event shapes are the same as on the [store events endpoint](https://www.mixedbread.com/api-reference/endpoints/stores/events/list-store-events). A [question answering](https://www.mixedbread.com/docs/stores/search/question-answering) request produces a single `qa` event covering both its retrieval and its answer generation. That retrieval is **not** listed again under `event_type=search` or `event_type=agentic_search`, so a `qa` request is counted once rather than appearing as both a search and an answer. ```json { "paths": { "/v1/events": { "get": { "tags": [ "events" ], "summary": "List Events", "description": "Covers store activity (`search`, `agentic_search`, `grep`, `ingestion`) and\nchat completions (`completion`, one event per Chat Completions or Responses\nturn). Without `store_identifier` the listing spans every store and also\nreturns events tied to none, such as completions that never called a\nstore tool.", "operationId": "list_events", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Maximum number of items to return per page (1-100)", "examples": [ 10, 20, 50 ], "default": 20, "title": "Limit" }, "description": "Maximum number of items to return per page (1-100)" }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for forward pagination - get items after this position. Use last_cursor from previous response.", "examples": [ "eyJjcmVhdGVkX2F0IjoiMjAyNC0xMi0zMVQyMzo1OTo1OS4wMDBaIiwiaWQiOiJhYmMxMjMifQ==" ], "title": "After" }, "description": "Cursor for forward pagination - get items after this position. Use last_cursor from previous response." }, { "name": "before", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for backward pagination - get items before this position. Use first_cursor from previous response.", "examples": [ "eyJjcmVhdGVkX2F0IjoiMjAyNC0xMi0zMVQyMzo1OTo1OS4wMDBaIiwiaWQiOiJhYmMxMjMifQ==" ], "title": "Before" }, "description": "Cursor for backward pagination - get items before this position. Use first_cursor from previous response." }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Whether to include total count in response (expensive operation)", "examples": [ false, true ], "default": false, "title": "Include Total" }, "description": "Whether to include total count in response (expensive operation)" }, { "name": "filter_before", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time to filter events before", "title": "Filter Before" }, "description": "Time to filter events before" }, { "name": "filter_after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time to filter events after", "title": "Filter After" }, "description": "Time to filter events after" }, { "name": "event_type", "in": "query", "required": true, "schema": { "enum": [ "ingestion", "search", "agentic_search", "grep", "completion", "qa" ], "type": "string", "description": "The type of event to list", "examples": [ "ingestion", "search", "agentic_search", "grep" ], "title": "Event Type" }, "description": "The type of event to list" }, { "name": "store_identifier", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Restrict to one store by ID or name; omit to span every store", "title": "Store Identifier" }, "description": "Restrict to one store by ID or name; omit to span every store" } ], "responses": { "200": { "description": "The organization's events of the requested type, newest first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventListResponse" }, "example": { "object": "list", "data": [ { "id": "evt_abc123", "type": "completion", "created_at": "2025-01-15T14:30:04.000Z", "store_ids": [ "vs_abc123" ], "completion_id": "chatcmpl_9f2c1", "endpoint": "chat_completions", "model": "toast-1", "title": "Refund policy", "previous_completion_id": null, "root_completion_id": "chatcmpl_9f2c1", "persisted": true, "finish_reason": "stop", "started_at": "2025-01-15T14:30:00.000Z", "total_time": "PT4.2S", "user_message": "What is the refund window for annual plans?", "answer": "Annual plans can be refunded within 30 days of purchase .", "token_usage": { "prompt_tokens": 1840, "completion_tokens": 96, "total_tokens": 1936 }, "tool_calls": [ { "tool_call_id": "generation-1", "tool_name": "generation", "tool_type": "function", "started_at": "2025-01-15T14:30:00.000Z", "duration": "PT1.1S", "arguments": { "messages_count": 2, "model": "toast-1" }, "result": { "content": null, "tool_calls": [ { "id": "call_1", "name": "store_search" } ], "usage": { "prompt_tokens": 900, "completion_tokens": 24 } } }, { "tool_call_id": "ss_7d1e", "tool_name": "store_search", "tool_type": "datastore", "started_at": "2025-01-15T14:30:01.100Z", "duration": "PT0.6S", "arguments": { "queries": [ "refund window annual plan" ] }, "result": { "result_count": 1, "results": [ { "store_id": "vs_abc123", "file_id": "file_4b2a", "filename": "billing-faq.md", "chunk_index": 3, "score": 0.91 } ] } }, { "tool_call_id": "generation-2", "tool_name": "generation", "tool_type": "function", "started_at": "2025-01-15T14:30:01.700Z", "duration": "PT2.5S", "arguments": { "messages_count": 4, "model": "toast-1" }, "result": { "content": "Annual plans can be refunded within 30 days of purchase .", "tool_calls": [], "usage": { "prompt_tokens": 940, "completion_tokens": 72 } } } ] } ], "pagination": { "has_more": false, "first_cursor": "eyJpZCI6ImV2dF9hYmMxMjMifQ==", "last_cursor": "eyJpZCI6ImV2dF9hYmMxMjMifQ==" } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "EventListResponse": { "properties": { "pagination": { "$ref": "#/components/schemas/CursorPaginationResponse" }, "object": { "type": "string", "const": "list", "title": "Object", "description": "The object type of the response", "default": "list" }, "data": { "items": { "oneOf": [ { "$ref": "#/components/schemas/StoreIngestionEvent" }, { "$ref": "#/components/schemas/StoreSearchEvent" }, { "$ref": "#/components/schemas/StoreAgenticSearchEvent" }, { "$ref": "#/components/schemas/StoreGrepEvent" }, { "$ref": "#/components/schemas/StoreCompletionEvent" }, { "$ref": "#/components/schemas/StoreQAEvent" } ], "discriminator": { "propertyName": "type", "mapping": { "agentic_search": "#/components/schemas/StoreAgenticSearchEvent", "completion": "#/components/schemas/StoreCompletionEvent", "grep": "#/components/schemas/StoreGrepEvent", "ingestion": "#/components/schemas/StoreIngestionEvent", "qa": "#/components/schemas/StoreQAEvent", "search": "#/components/schemas/StoreSearchEvent" } } }, "type": "array", "title": "Data", "description": "The list of events" } }, "type": "object", "required": [ "pagination", "data" ], "title": "EventListResponse" }, "CursorPaginationResponse": { "properties": { "has_more": { "type": "boolean", "title": "Has More", "description": "Contextual direction-aware flag: True if more items exist in the requested pagination direction. For 'after': more items after this page. For 'before': more items before this page.", "examples": [ true, false ] }, "first_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Cursor", "description": "Cursor of the first item in this page. Use for backward pagination. None if page is empty.", "examples": [ "eyJjcmVhdGVkX2F0IjoiMjAyNC0xMi0zMVQyMzo1OTo1OS4wMDBaIiwiaWQiOiJhYmMxMjMifQ==", null ] }, "last_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Cursor", "description": "Cursor of the last item in this page. Use for forward pagination. None if page is empty.", "examples": [ "eyJjcmVhdGVkX2F0IjoiMjAyNC0xMi0zMFQyMzo1OTo1OS4wMDBaIiwiaWQiOiJ4eXo3ODkifQ==", null ] }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total", "description": "Total number of items available across all pages. Only included when include_total=true was requested. Expensive operation - use sparingly.", "examples": [ 42, 0, null ] } }, "type": "object", "required": [ "has_more", "first_cursor", "last_cursor" ], "title": "CursorPaginationResponse", "description": "Response model for cursor-based pagination." }, "StoreIngestionEvent": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Unique identifier for the event" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when the event was created" }, "type": { "type": "string", "const": "ingestion", "title": "Type", "default": "ingestion" }, "store_id": { "type": "string", "format": "uuid", "title": "Store Id", "description": "ID of the vector store" }, "store_file_id": { "type": "string", "title": "Store File Id", "description": "ID of the vector store file" }, "total_time": { "type": "string", "format": "duration", "title": "Total Time", "description": "Total time taken to ingest the file, including queue time" }, "queue_time": { "type": "string", "format": "duration", "title": "Queue Time", "description": "Time spent in the queue" }, "ingestion_time": { "type": "string", "format": "duration", "title": "Ingestion Time", "description": "Time taken to ingest the file, excluding queue time" }, "chunk_count": { "type": "integer", "title": "Chunk Count", "description": "Number of chunks ingested" }, "contextualization": { "type": "boolean", "title": "Contextualization", "description": "Whether contextualization was used" }, "mode": { "$ref": "#/components/schemas/StoreFileParsingStrategy", "description": "Strategy used to ingest the file" }, "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Filename", "description": "Name of the file if the event is tied to a file" } }, "type": "object", "required": [ "id", "created_at", "store_id", "store_file_id", "total_time", "queue_time", "ingestion_time", "chunk_count", "contextualization", "mode" ], "title": "StoreIngestionEvent", "description": "Represents an ingestion event in a vector store." }, "StoreFileParsingStrategy": { "type": "string", "enum": [ "fast", "high_quality" ], "title": "StoreFileParsingStrategy", "description": "Strategy for adding a file to a store." }, "StoreSearchEvent": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Unique identifier for the event" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when the event was created" }, "type": { "type": "string", "const": "search", "title": "Type", "default": "search" }, "store_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "title": "Store Ids", "description": "IDs of the vector stores searched" }, "search_time": { "type": "string", "format": "duration", "title": "Search Time", "description": "Time taken to search the vector store", "default": "PT0S" }, "query": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Query", "description": "Query used to search the vector store" }, "rewritten_query": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rewritten Query", "description": "Rewritten query if query rewriting was enabled" }, "rewritten_filters": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Output" }, { "$ref": "#/components/schemas/SearchFilterCondition" }, { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Output" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Rewritten Filters", "description": "Filters used after query rewriting" }, "rewrite_rank_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rewrite Rank By", "description": "Metadata field used for ranking" }, "rewrite_rank_direction": { "anyOf": [ { "type": "string", "enum": [ "asc", "desc" ] }, { "type": "null" } ], "title": "Rewrite Rank Direction", "description": "Ranking direction" }, "rewrite_rank_mode": { "anyOf": [ { "type": "string", "enum": [ "post_search", "metadata" ] }, { "type": "null" } ], "title": "Rewrite Rank Mode", "description": "Ranking mode" }, "rerank": { "type": "boolean", "title": "Rerank", "description": "Whether to rerank the results", "default": false }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Output" }, { "$ref": "#/components/schemas/SearchFilterCondition" }, { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Output" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Filters", "description": "Metadata filters submitted with the search request" }, "results": { "items": { "$ref": "#/components/schemas/StoreSearchEventResult" }, "type": "array", "title": "Results", "description": "Chunks returned by the search" } }, "type": "object", "required": [ "id", "created_at", "store_ids" ], "title": "StoreSearchEvent", "description": "Represents a search event in a vector store." }, "SearchFilter-Output": { "properties": { "all": { "anyOf": [ { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Output" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "All", "description": "List of conditions or filters to be ANDed together", "examples": [ [ { "key": "price", "operator": "gt", "value": "100" }, { "key": "color", "operator": "eq", "value": "red" } ], null ] }, "any": { "anyOf": [ { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Output" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Any", "description": "List of conditions or filters to be ORed together", "examples": [ [ { "key": "price", "operator": "gt", "value": "100" }, { "key": "color", "operator": "eq", "value": "red" } ], null ] }, "none": { "anyOf": [ { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Output" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "None", "description": "List of conditions or filters to be NOTed", "examples": [ [ { "key": "price", "operator": "gt", "value": "100" }, { "key": "color", "operator": "eq", "value": "red" } ], null ] } }, "type": "object", "title": "SearchFilter", "description": "Represents a filter with AND, OR, and NOT conditions." }, "SearchFilterCondition": { "properties": { "key": { "type": "string", "title": "Key", "description": "The field to apply the condition on", "examples": [ "price", "color" ] }, "value": { "title": "Value", "description": "The value to compare against", "examples": [ "100", "red" ] }, "operator": { "$ref": "#/components/schemas/ConditionOperator", "description": "The operator for the condition", "examples": [ "eq", "gt" ] } }, "type": "object", "required": [ "key", "value", "operator" ], "title": "SearchFilterCondition", "description": "Represents a condition with a field, operator, and value." }, "ConditionOperator": { "type": "string", "enum": [ "eq", "not_eq", "gt", "gte", "lt", "lte", "in", "not_in", "like", "contains", "starts_with", "not_like", "regex" ], "title": "ConditionOperator", "description": "Operator for a filter condition." }, "StoreSearchEventResult": { "properties": { "store_id": { "type": "string", "title": "Store Id", "description": "ID of the store the chunk belongs to" }, "file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Id", "description": "ID of the file the chunk belongs to" }, "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Filename", "description": "Name of the file the chunk belongs to" }, "chunk_index": { "type": "integer", "title": "Chunk Index", "description": "Index of the chunk within its file" }, "score": { "type": "number", "title": "Score", "description": "Final score assigned to the chunk" }, "first_stage_position": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "First Stage Position", "description": "Position of the chunk in the first-stage ranking" }, "first_stage_source": { "anyOf": [ { "type": "string", "enum": [ "dense", "sparse", "both" ] }, { "type": "null" } ], "title": "First Stage Source", "description": "Which first-stage retriever surfaced the chunk" } }, "type": "object", "required": [ "store_id", "chunk_index", "score" ], "title": "StoreSearchEventResult", "description": "A single result captured on a search event." }, "StoreAgenticSearchEvent": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Unique identifier for the event" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when the event was created" }, "type": { "type": "string", "const": "agentic_search", "title": "Type", "default": "agentic_search" }, "store_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "title": "Store Ids", "description": "IDs of the vector stores searched" }, "started_at": { "type": "string", "format": "date-time", "title": "Started At", "description": "Time when the agentic search began" }, "search_time": { "type": "string", "format": "duration", "title": "Search Time", "description": "Total wall-clock time of the agent loop", "default": "PT0S" }, "query": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Query", "description": "Original query submitted by the user" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions", "description": "Custom instructions provided with the agentic search, if any" }, "ranking_strategy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ranking Strategy", "description": "Agent-submitted explanation of how chunks were ranked" }, "rounds_executed": { "type": "integer", "title": "Rounds Executed", "description": "Number of search rounds the agent executed", "default": 0 }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Output" }, { "$ref": "#/components/schemas/SearchFilterCondition" }, { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Output" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Filters", "description": "Metadata filters submitted with the search request" }, "token_usage": { "$ref": "#/components/schemas/AgenticSearchTokenUsage", "description": "Token usage for LLM calls during the agentic search" }, "tool_calls": { "items": { "$ref": "#/components/schemas/AgenticToolCall" }, "type": "array", "title": "Tool Calls", "description": "Ordered tool calls issued by the agent" }, "results": { "items": { "$ref": "#/components/schemas/StoreSearchEventResult" }, "type": "array", "title": "Results", "description": "Chunks returned by the agentic search" } }, "type": "object", "required": [ "id", "created_at", "store_ids", "started_at" ], "title": "StoreAgenticSearchEvent", "description": "Represents an agentic search trace in a vector store.\n\nUnlike StoreSearchEvent, this captures the full sequence of tool calls the\nagent issued (name, arguments, result) so developers can inspect what the\nagent did, along with the token usage." }, "AgenticSearchTokenUsage": { "properties": { "prompt_tokens": { "type": "integer", "title": "Prompt Tokens", "description": "Number of prompt tokens consumed", "default": 0 }, "completion_tokens": { "type": "integer", "title": "Completion Tokens", "description": "Number of completion tokens generated", "default": 0 }, "total_tokens": { "type": "integer", "title": "Total Tokens", "description": "Total tokens consumed (prompt + completion)", "default": 0 } }, "type": "object", "title": "AgenticSearchTokenUsage", "description": "Token usage for LLM calls made during an agentic search." }, "AgenticToolCall": { "properties": { "tool_call_id": { "type": "string", "title": "Tool Call Id", "description": "Unique identifier for the tool call (gen_ai.tool.call.id)" }, "tool_name": { "type": "string", "title": "Tool Name", "description": "Name of the tool invoked (gen_ai.tool.name)", "examples": [ "search_batch" ] }, "tool_type": { "type": "string", "enum": [ "function", "extension", "datastore" ], "title": "Tool Type", "description": "Category of the tool (gen_ai.tool.type)", "default": "function" }, "started_at": { "type": "string", "format": "date-time", "title": "Started At", "description": "Time when the tool call began" }, "duration": { "type": "string", "format": "duration", "title": "Duration", "description": "Time taken to execute the tool call" }, "arguments": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Arguments", "description": "Arguments passed to the tool (gen_ai.tool.call.arguments)" }, "result": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Result", "description": "Result returned to the model (gen_ai.tool.call.result). None if the tool errored." }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Error message if the tool call failed" }, "error_kind": { "anyOf": [ { "type": "string", "enum": [ "provider", "agent" ] }, { "type": "null" } ], "title": "Error Kind", "description": "Failure classification when the tool call errored: `provider` is an infrastructure failure outside the agent's control, `agent` is feedback the agent received and can recover from." } }, "type": "object", "required": [ "tool_call_id", "tool_name", "started_at", "duration" ], "title": "AgenticToolCall", "description": "Represents a single tool call made by the agent during an agentic search.\n\nFields follow the OpenTelemetry GenAI semantic conventions for tool calls:\nhttps://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/" }, "StoreGrepEvent": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Unique identifier for the event" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when the event was created" }, "type": { "type": "string", "const": "grep", "title": "Type", "default": "grep" }, "store_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "title": "Store Ids", "description": "IDs of the vector stores grepped" }, "pattern": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pattern", "description": "Regular expression matched against chunk text" }, "case_sensitive": { "type": "boolean", "title": "Case Sensitive", "description": "Whether the pattern was matched case-sensitively", "default": false }, "search_time": { "type": "string", "format": "duration", "title": "Search Time", "description": "Time taken to grep the vector store", "default": "PT0S" }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Output" }, { "$ref": "#/components/schemas/SearchFilterCondition" }, { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Output" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Filters", "description": "Metadata filters submitted with the grep request" }, "results": { "items": { "$ref": "#/components/schemas/StoreSearchEventResult" }, "type": "array", "title": "Results", "description": "Chunks that matched the pattern" } }, "type": "object", "required": [ "id", "created_at", "store_ids" ], "title": "StoreGrepEvent", "description": "Represents a grep event in a vector store.\n\nGrep matches chunks against a regular expression rather than running a\nsemantic search, so it has no ranking, rewrite, or rerank fields." }, "StoreCompletionEvent": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Unique identifier for the event" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when the event was created" }, "type": { "type": "string", "const": "completion", "title": "Type", "default": "completion" }, "store_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "title": "Store Ids", "description": "IDs of the stores the completion's hosted tools touched" }, "completion_id": { "type": "string", "title": "Completion Id", "description": "ID of the completion; retrievable while it is persisted" }, "endpoint": { "type": "string", "enum": [ "chat_completions", "responses" ], "title": "Endpoint", "description": "API the completion was created through", "default": "chat_completions" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "Model that served the completion" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title", "description": "Conversation title" }, "previous_completion_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previous Completion Id", "description": "Completion this turn continued from, if the conversation was resumed" }, "root_completion_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Root Completion Id", "description": "First completion of the conversation this turn belongs to; groups the turns of one chat" }, "persisted": { "type": "boolean", "title": "Persisted", "description": "Whether the completion was stored for later retrieval", "default": true }, "finish_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Finish Reason", "description": "Why generation ended" }, "started_at": { "type": "string", "format": "date-time", "title": "Started At", "description": "Time when the completion began" }, "total_time": { "type": "string", "format": "duration", "title": "Total Time", "description": "Wall-clock time of the completion turn", "default": "PT0S" }, "user_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Message", "description": "Text of the last user message in the request, truncated" }, "answer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Answer", "description": "Text of the generated answer, truncated" }, "token_usage": { "$ref": "#/components/schemas/AgenticSearchTokenUsage", "description": "Token usage for the model calls of the turn" }, "tool_calls": { "items": { "$ref": "#/components/schemas/AgenticToolCall" }, "type": "array", "title": "Tool Calls", "description": "Ordered model generations and hosted tool calls of the turn" } }, "type": "object", "required": [ "id", "created_at", "store_ids", "completion_id", "started_at" ], "title": "StoreCompletionEvent", "description": "Represents a chat completion or response that used the store through its hosted tools.\n\nOne event per completion turn, shared by the Chat Completions and Responses\nendpoints. It records the model calls and the hosted store tool calls the\nturn issued, in the same trace shape as agentic search events." }, "StoreQAEvent": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Unique identifier for the event" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when the event was created" }, "type": { "type": "string", "const": "qa", "title": "Type", "default": "qa" }, "store_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "title": "Store Ids", "description": "IDs of the stores the answer was grounded in" }, "started_at": { "type": "string", "format": "date-time", "title": "Started At", "description": "Time when the question answering began" }, "total_time": { "type": "string", "format": "duration", "title": "Total Time", "description": "Wall-clock time of the request, retrieval and generation included", "default": "PT0S" }, "search_time": { "type": "string", "format": "duration", "title": "Search Time", "description": "Time spent on the retrieval half", "default": "PT0S" }, "query": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Query", "description": "Question submitted by the user" }, "answer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Answer", "description": "Answer generated by the model" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions", "description": "Custom instructions provided with the request, if any" }, "cite": { "type": "boolean", "title": "Cite", "description": "Whether citations were requested", "default": false }, "cited_chunk_indices": { "items": { "type": "integer" }, "type": "array", "title": "Cited Chunk Indices", "description": "Indices into `results` the answer cited" }, "agentic": { "type": "boolean", "title": "Agentic", "description": "Whether the retrieval ran as an agentic search", "default": false }, "rounds_executed": { "type": "integer", "title": "Rounds Executed", "description": "Number of search rounds of the agentic retrieval, when agentic", "default": 0 }, "token_usage": { "$ref": "#/components/schemas/AgenticSearchTokenUsage", "description": "Token usage of the answer generation; retrieval usage is on its tool calls" }, "tool_calls": { "items": { "$ref": "#/components/schemas/AgenticToolCall" }, "type": "array", "title": "Tool Calls", "description": "Retrieval tool calls followed by the answer generation" }, "results": { "items": { "$ref": "#/components/schemas/StoreSearchEventResult" }, "type": "array", "title": "Results", "description": "Chunks the answer was grounded in" } }, "type": "object", "required": [ "id", "created_at", "store_ids", "started_at" ], "title": "StoreQAEvent", "description": "Represents a question-answering request over one or more stores.\n\nCaptures both halves of the request in one record: the retrieval (a plain\nor agentic search, recorded as tool calls) and the answer generation (a\n`generation` tool call carrying the model and its token usage)." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` cURL: ```bash curl 'https://api.mixedbread.com/v1/events?event_type=completion&limit=20' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` # Create a Response URL: https://www.mixedbread.com/api-reference/endpoints/responses/create-response Create an OpenAI-compatible response with text input or client-executed function tools. ```json { "paths": { "/v1/responses": { "post": { "tags": [ "responses" ], "summary": "Create a Response", "operationId": "create_response", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseCreateParams", "description": "OpenAI-compatible response parameters" } } }, "required": true }, "responses": { "200": { "description": "The generated response, or a semantic server-sent event stream", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" }, "example": { "id": "resp_abc123", "object": "response", "created_at": 1786622400, "status": "completed", "completed_at": 1786622401, "error": null, "incomplete_details": null, "instructions": null, "model": "toast-1", "output": [ { "type": "message", "id": "msg_abc123", "status": "completed", "role": "assistant", "content": [ { "type": "output_text", "annotations": [], "text": "A search agent plans queries, gathers evidence with tools, and synthesizes an answer.", "logprobs": [] } ] } ], "parallel_tool_calls": true, "temperature": null, "tool_choice": "auto", "tools": [], "top_p": null, "background": false, "max_output_tokens": null, "previous_response_id": null, "reasoning": null, "service_tier": "default", "text": null, "truncation": "disabled", "usage": { "input_tokens": 15, "input_tokens_details": { "cached_tokens": 0 }, "output_tokens": 19, "output_tokens_details": { "reasoning_tokens": 0 }, "total_tokens": 34 }, "metadata": null, "safety_identifier": null, "prompt_cache_key": null, "user": null, "title": "What is a search agent?" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } } }, "components": { "schemas": { "ResponseCreateParams": { "properties": { "model": { "type": "string", "title": "Model", "default": "toast-1" }, "input": { "anyOf": [ { "type": "string" }, { "items": { "oneOf": [ { "$ref": "#/components/schemas/ResponseMessageInput" }, { "$ref": "#/components/schemas/ResponseFunctionCallInput" }, { "$ref": "#/components/schemas/ResponseFunctionCallOutputInput" }, { "$ref": "#/components/schemas/ResponseReasoningInput" }, { "$ref": "#/components/schemas/ResponseAgentMessageInput" }, { "$ref": "#/components/schemas/ResponseMcpApprovalResponseInput" }, { "$ref": "#/components/schemas/ResponseMcpApprovalRequestInput" }, { "$ref": "#/components/schemas/ResponseMcpCallInput" }, { "$ref": "#/components/schemas/ResponseMcpListToolsInput" } ], "discriminator": { "propertyName": "type", "mapping": { "agent_message": "#/components/schemas/ResponseAgentMessageInput", "function_call": "#/components/schemas/ResponseFunctionCallInput", "function_call_output": "#/components/schemas/ResponseFunctionCallOutputInput", "mcp_approval_request": "#/components/schemas/ResponseMcpApprovalRequestInput", "mcp_approval_response": "#/components/schemas/ResponseMcpApprovalResponseInput", "mcp_call": "#/components/schemas/ResponseMcpCallInput", "mcp_list_tools": "#/components/schemas/ResponseMcpListToolsInput", "message": "#/components/schemas/ResponseMessageInput", "reasoning": "#/components/schemas/ResponseReasoningInput" } } }, "type": "array", "minItems": 1 } ], "title": "Input" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions" }, "tools": { "items": { "oneOf": [ { "$ref": "#/components/schemas/ResponseFunctionTool" }, { "$ref": "#/components/schemas/ResponseNamespaceTool" }, { "$ref": "#/components/schemas/McpTool" }, { "$ref": "#/components/schemas/SearchCorpusTool" }, { "$ref": "#/components/schemas/GrepTool" }, { "$ref": "#/components/schemas/FilterChunksTool" }, { "$ref": "#/components/schemas/InspectMetadataTool" }, { "$ref": "#/components/schemas/GetChunksTool" }, { "$ref": "#/components/schemas/StoreSearchTool" }, { "$ref": "#/components/schemas/StoreGrepTool" }, { "$ref": "#/components/schemas/StoreListChunksTool" }, { "$ref": "#/components/schemas/MetadataFacetsTool" }, { "$ref": "#/components/schemas/ListStoresTool" } ], "discriminator": { "propertyName": "type", "mapping": { "filter_chunks": "#/components/schemas/FilterChunksTool", "function": "#/components/schemas/ResponseFunctionTool", "get_chunks": "#/components/schemas/GetChunksTool", "grep": "#/components/schemas/GrepTool", "inspect_metadata": "#/components/schemas/InspectMetadataTool", "list_stores": "#/components/schemas/ListStoresTool", "mcp": "#/components/schemas/McpTool", "namespace": "#/components/schemas/ResponseNamespaceTool", "search_corpus": "#/components/schemas/SearchCorpusTool", "store_grep": "#/components/schemas/StoreGrepTool", "store_list_chunks": "#/components/schemas/StoreListChunksTool", "store_metadata_facets": "#/components/schemas/MetadataFacetsTool", "store_search": "#/components/schemas/StoreSearchTool" } } }, "type": "array", "title": "Tools" }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "$ref": "#/components/schemas/ResponseToolChoiceFunction" }, { "$ref": "#/components/schemas/ToolChoiceMcp" }, { "$ref": "#/components/schemas/ToolChoiceSearchCorpus" }, { "$ref": "#/components/schemas/ToolChoiceGrep" }, { "$ref": "#/components/schemas/ToolChoiceFilterChunks" }, { "$ref": "#/components/schemas/ToolChoiceInspectMetadata" }, { "$ref": "#/components/schemas/ToolChoiceStoreSearch" }, { "$ref": "#/components/schemas/ToolChoiceStoreGrep" }, { "$ref": "#/components/schemas/ToolChoiceStoreListChunks" }, { "$ref": "#/components/schemas/ToolChoiceMetadataFacets" }, { "$ref": "#/components/schemas/ToolChoiceListStores" } ], "title": "Tool Choice", "default": "auto" }, "store": { "type": "boolean", "title": "Store", "default": true }, "previous_response_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previous Response Id" }, "context_management": { "anyOf": [ { "$ref": "#/components/schemas/ContextManagementConfig" }, { "type": "null" } ] }, "stream": { "type": "boolean", "title": "Stream", "default": false }, "stream_options": { "anyOf": [ { "$ref": "#/components/schemas/ResponseStreamOptions" }, { "type": "null" } ] }, "temperature": { "anyOf": [ { "type": "number", "maximum": 2, "minimum": 0 }, { "type": "null" } ], "title": "Temperature" }, "top_p": { "anyOf": [ { "type": "number", "maximum": 1, "minimum": 0 }, { "type": "null" } ], "title": "Top P" }, "max_output_tokens": { "anyOf": [ { "type": "integer", "minimum": 16 }, { "type": "null" } ], "title": "Max Output Tokens" }, "max_tool_calls": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Max Tool Calls" }, "parallel_tool_calls": { "type": "boolean", "title": "Parallel Tool Calls", "default": true }, "metadata": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "include": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Include" }, "text": { "anyOf": [ { "$ref": "#/components/schemas/ResponseTextConfig" }, { "type": "null" } ] }, "background": { "type": "boolean", "title": "Background", "default": false }, "truncation": { "type": "string", "enum": [ "auto", "disabled" ], "title": "Truncation", "default": "disabled" }, "reasoning": { "anyOf": [ { "$ref": "#/components/schemas/ResponseReasoningConfig" }, { "type": "null" } ] }, "service_tier": { "anyOf": [ { "type": "string", "enum": [ "auto", "default", "flex", "scale", "priority" ] }, { "type": "null" } ], "title": "Service Tier" }, "safety_identifier": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "title": "Safety Identifier" }, "prompt_cache_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prompt Cache Key" }, "user": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User" }, "client_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Client Metadata" } }, "additionalProperties": false, "type": "object", "required": [ "input" ], "title": "ResponseCreateParams", "description": "Request body for POST /v1/responses." }, "ResponseMessageInput": { "properties": { "type": { "type": "string", "const": "message", "title": "Type", "default": "message" }, "role": { "type": "string", "enum": [ "user", "assistant", "system", "developer" ], "title": "Role" }, "content": { "anyOf": [ { "type": "string" }, { "items": { "oneOf": [ { "$ref": "#/components/schemas/ResponseInputTextPart" }, { "$ref": "#/components/schemas/ResponseOutputTextPartInput" }, { "$ref": "#/components/schemas/ResponseRefusalPartInput" } ], "discriminator": { "propertyName": "type", "mapping": { "input_text": "#/components/schemas/ResponseInputTextPart", "output_text": "#/components/schemas/ResponseOutputTextPartInput", "refusal": "#/components/schemas/ResponseRefusalPartInput" } } }, "type": "array" } ], "title": "Content" }, "status": { "anyOf": [ { "type": "string", "enum": [ "in_progress", "completed", "incomplete" ] }, { "type": "null" } ], "title": "Status" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "phase": { "anyOf": [ { "type": "string", "enum": [ "commentary", "final_answer" ] }, { "type": "null" } ], "title": "Phase" } }, "type": "object", "required": [ "role", "content" ], "title": "ResponseMessageInput", "description": "An easy input message or a previously returned output message." }, "ResponseInputTextPart": { "properties": { "type": { "type": "string", "const": "input_text", "title": "Type", "default": "input_text" }, "text": { "type": "string", "title": "Text" } }, "type": "object", "required": [ "text" ], "title": "ResponseInputTextPart", "description": "A text input content part." }, "ResponseOutputTextPartInput": { "properties": { "type": { "type": "string", "const": "output_text", "title": "Type", "default": "output_text" }, "text": { "type": "string", "title": "Text" }, "annotations": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Annotations" } }, "type": "object", "required": [ "text" ], "title": "ResponseOutputTextPartInput", "description": "A prior assistant text part passed back as input." }, "ResponseRefusalPartInput": { "properties": { "type": { "type": "string", "const": "refusal", "title": "Type", "default": "refusal" }, "refusal": { "type": "string", "title": "Refusal" } }, "type": "object", "required": [ "refusal" ], "title": "ResponseRefusalPartInput", "description": "A prior assistant refusal passed back as input." }, "ResponseFunctionCallInput": { "properties": { "type": { "type": "string", "const": "function_call", "title": "Type", "default": "function_call" }, "call_id": { "type": "string", "title": "Call Id" }, "name": { "type": "string", "title": "Name" }, "arguments": { "type": "string", "title": "Arguments" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "status": { "anyOf": [ { "type": "string", "enum": [ "in_progress", "completed", "incomplete" ] }, { "type": "null" } ], "title": "Status" } }, "type": "object", "required": [ "call_id", "name", "arguments" ], "title": "ResponseFunctionCallInput", "description": "A previously returned client function call passed back as input." }, "ResponseFunctionCallOutputInput": { "properties": { "type": { "type": "string", "const": "function_call_output", "title": "Type", "default": "function_call_output" }, "call_id": { "type": "string", "title": "Call Id" }, "output": { "anyOf": [ { "type": "string" }, { "items": { "$ref": "#/components/schemas/ResponseInputTextPart" }, "type": "array" } ], "title": "Output" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "status": { "anyOf": [ { "type": "string", "enum": [ "in_progress", "completed", "incomplete" ] }, { "type": "null" } ], "title": "Status" } }, "type": "object", "required": [ "call_id", "output" ], "title": "ResponseFunctionCallOutputInput", "description": "The caller-provided output of a function call." }, "ResponseReasoningInput": { "properties": { "type": { "type": "string", "const": "reasoning", "title": "Type", "default": "reasoning" }, "id": { "type": "string", "title": "Id" }, "summary": { "items": { "$ref": "#/components/schemas/ResponseReasoningSummaryInput" }, "type": "array", "title": "Summary" }, "content": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ResponseReasoningTextInput" }, "type": "array" }, { "type": "null" } ], "title": "Content" }, "encrypted_content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Encrypted Content" }, "status": { "anyOf": [ { "type": "string", "enum": [ "in_progress", "completed", "incomplete" ] }, { "type": "null" } ], "title": "Status" } }, "type": "object", "required": [ "id" ], "title": "ResponseReasoningInput", "description": "A reasoning item accepted when callers manually replay prior output." }, "ResponseReasoningSummaryInput": { "properties": { "type": { "type": "string", "const": "summary_text", "title": "Type", "default": "summary_text" }, "text": { "type": "string", "title": "Text" } }, "type": "object", "required": [ "text" ], "title": "ResponseReasoningSummaryInput" }, "ResponseReasoningTextInput": { "properties": { "type": { "type": "string", "const": "reasoning_text", "title": "Type", "default": "reasoning_text" }, "text": { "type": "string", "title": "Text" } }, "type": "object", "required": [ "text" ], "title": "ResponseReasoningTextInput" }, "ResponseAgentMessageInput": { "properties": { "type": { "type": "string", "const": "agent_message", "title": "Type", "default": "agent_message" }, "author": { "type": "string", "title": "Author" }, "recipient": { "type": "string", "title": "Recipient" }, "content": { "items": { "oneOf": [ { "$ref": "#/components/schemas/ResponseInputTextPart" }, { "$ref": "#/components/schemas/ResponseAgentMessageEncryptedContent" } ], "discriminator": { "propertyName": "type", "mapping": { "encrypted_content": "#/components/schemas/ResponseAgentMessageEncryptedContent", "input_text": "#/components/schemas/ResponseInputTextPart" } } }, "type": "array", "minItems": 1, "title": "Content" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "internal_chat_message_metadata_passthrough": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Internal Chat Message Metadata Passthrough" } }, "type": "object", "required": [ "author", "recipient", "content" ], "title": "ResponseAgentMessageInput", "description": "A Codex multi-agent message replayed as Responses input." }, "ResponseAgentMessageEncryptedContent": { "properties": { "type": { "type": "string", "const": "encrypted_content", "title": "Type", "default": "encrypted_content" }, "encrypted_content": { "type": "string", "title": "Encrypted Content" } }, "type": "object", "required": [ "encrypted_content" ], "title": "ResponseAgentMessageEncryptedContent", "description": "Opaque agent-to-agent content that only the originating runtime can decrypt." }, "ResponseMcpApprovalResponseInput": { "properties": { "type": { "type": "string", "const": "mcp_approval_response", "title": "Type", "default": "mcp_approval_response" }, "approval_request_id": { "type": "string", "title": "Approval Request Id" }, "approve": { "type": "boolean", "title": "Approve" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" } }, "type": "object", "required": [ "approval_request_id", "approve" ], "title": "ResponseMcpApprovalResponseInput", "description": "The caller's answer to an `mcp_approval_request` of the previous response." }, "ResponseMcpApprovalRequestInput": { "properties": { "type": { "type": "string", "const": "mcp_approval_request", "title": "Type", "default": "mcp_approval_request" }, "id": { "type": "string", "title": "Id" }, "server_label": { "type": "string", "title": "Server Label" }, "name": { "type": "string", "title": "Name" }, "arguments": { "type": "string", "title": "Arguments" } }, "type": "object", "required": [ "id", "server_label", "name", "arguments" ], "title": "ResponseMcpApprovalRequestInput", "description": "A prior approval request replayed as input by a caller that holds no previous_response_id." }, "ResponseMcpCallInput": { "properties": { "type": { "type": "string", "const": "mcp_call", "title": "Type", "default": "mcp_call" }, "id": { "type": "string", "title": "Id" }, "server_label": { "type": "string", "title": "Server Label" }, "name": { "type": "string", "title": "Name" }, "arguments": { "type": "string", "title": "Arguments" }, "output": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Output" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "approval_request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Approval Request Id" }, "status": { "anyOf": [ { "type": "string", "enum": [ "in_progress", "completed", "incomplete", "calling", "failed" ] }, { "type": "null" } ], "title": "Status" } }, "type": "object", "required": [ "id", "server_label", "name", "arguments" ], "title": "ResponseMcpCallInput", "description": "A prior MCP call replayed as input; its output becomes the tool result the model saw." }, "ResponseMcpListToolsInput": { "properties": { "type": { "type": "string", "const": "mcp_list_tools", "title": "Type", "default": "mcp_list_tools" }, "id": { "type": "string", "title": "Id" }, "server_label": { "type": "string", "title": "Server Label" }, "tools": { "items": { "$ref": "#/components/schemas/McpListToolsTool" }, "type": "array", "title": "Tools" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" } }, "type": "object", "required": [ "id", "server_label", "tools" ], "title": "ResponseMcpListToolsInput", "description": "A prior tool listing replayed as input; it stands in for asking the server again." }, "McpListToolsTool": { "properties": { "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "input_schema": { "additionalProperties": true, "type": "object", "title": "Input Schema" }, "annotations": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Annotations" } }, "type": "object", "required": [ "name", "input_schema" ], "title": "McpListToolsTool", "description": "One tool an MCP server listed." }, "ResponseFunctionTool": { "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "parameters": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Parameters" }, "strict": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Strict" }, "type": { "type": "string", "const": "function", "title": "Type", "default": "function" } }, "type": "object", "required": [ "name" ], "title": "ResponseFunctionTool", "description": "A Responses API function tool, whose definition is flat rather than nested." }, "ResponseNamespaceTool": { "properties": { "type": { "type": "string", "const": "namespace", "title": "Type", "default": "namespace" }, "name": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "tools": { "items": { "$ref": "#/components/schemas/ResponseFunctionTool" }, "type": "array", "minItems": 1, "title": "Tools" } }, "type": "object", "required": [ "name", "tools" ], "title": "ResponseNamespaceTool", "description": "A Codex tool namespace containing client-executed functions." }, "McpTool": { "properties": { "type": { "type": "string", "const": "mcp", "title": "Type", "default": "mcp" }, "server_label": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$", "title": "Server Label", "description": "Label identifying this server in tool calls" }, "server_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Server Url", "description": "URL of the server's Streamable HTTP endpoint" }, "connector_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Connector Id", "description": "OpenAI service connectors are not supported" }, "server_description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Server Description", "description": "Shown to the model beside the server's tools" }, "headers": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Headers", "description": "HTTP headers sent to the server" }, "authorization": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization", "description": "OAuth access token sent as a bearer token" }, "require_approval": { "anyOf": [ { "type": "string", "enum": [ "always", "never" ] }, { "$ref": "#/components/schemas/McpApprovalFilter" } ], "title": "Require Approval", "description": "Which tools need the caller's approval before running; defaults to all of them", "default": "always" }, "allowed_tools": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "$ref": "#/components/schemas/McpToolFilter" }, { "type": "null" } ], "title": "Allowed Tools", "description": "Tool names or a filter restricting the offer" } }, "type": "object", "required": [ "server_label" ], "title": "McpTool", "description": "Hosted tool: the tools of a remote MCP server, executed server-side.\n\nFollows the OpenAI Responses API `mcp` tool: the server's tools are listed\nwhen the request starts and offered to the model; a call runs against the\nserver unless it needs the caller's approval first, in which case the turn\nends with an approval request the caller answers on the next request.\n\n`headers` and `authorization` are credentials: they are never stored nor\nechoed back, so a continuation must declare the server again." }, "McpApprovalFilter": { "properties": { "always": { "anyOf": [ { "$ref": "#/components/schemas/McpToolFilter" }, { "type": "null" } ] }, "never": { "anyOf": [ { "$ref": "#/components/schemas/McpToolFilter" }, { "type": "null" } ] } }, "type": "object", "title": "McpApprovalFilter", "description": "Which of an MCP server's tools need the caller's approval before they run." }, "McpToolFilter": { "properties": { "tool_names": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tool Names", "description": "Tool names the filter matches" }, "read_only": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Read Only", "description": "Match tools whose `readOnlyHint` annotation equals this value" } }, "type": "object", "title": "McpToolFilter", "description": "Selects tools of an MCP server by name and/or by their read-only annotation.\n\nShared by `allowed_tools` and the `require_approval` filters, as in the\nOpenAI Responses API." }, "SearchCorpusTool": { "properties": { "store_identifiers": { "anyOf": [ { "items": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ] }, "type": "array", "minItems": 1 }, { "type": "null" } ], "title": "Store Identifiers", "description": "IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)" }, "type": { "type": "string", "const": "search_corpus", "title": "Type", "default": "search_corpus" }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" }, { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Filters", "description": "Optional filter conditions applied to every search" }, "score_threshold": { "type": "number", "maximum": 1, "minimum": 0, "title": "Score Threshold", "description": "Minimum similarity score threshold", "default": 0 }, "citations": { "type": "boolean", "title": "Citations", "description": "Have the model cite its evidence inline; the answer ships with the markers removed and an annotations list of file_citation entries pointing at the cited chunks", "default": false } }, "type": "object", "title": "SearchCorpusTool", "description": "Hosted tool: semantic search over the caller's stores, executed server-side." }, "SearchFilter-Input": { "properties": { "all": { "anyOf": [ { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "All", "description": "List of conditions or filters to be ANDed together", "examples": [ [ { "key": "price", "operator": "gt", "value": "100" }, { "key": "color", "operator": "eq", "value": "red" } ], null ] }, "any": { "anyOf": [ { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Any", "description": "List of conditions or filters to be ORed together", "examples": [ [ { "key": "price", "operator": "gt", "value": "100" }, { "key": "color", "operator": "eq", "value": "red" } ], null ] }, "none": { "anyOf": [ { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "None", "description": "List of conditions or filters to be NOTed", "examples": [ [ { "key": "price", "operator": "gt", "value": "100" }, { "key": "color", "operator": "eq", "value": "red" } ], null ] } }, "type": "object", "title": "SearchFilter", "description": "Represents a filter with AND, OR, and NOT conditions." }, "SearchFilterCondition": { "properties": { "key": { "type": "string", "title": "Key", "description": "The field to apply the condition on", "examples": [ "price", "color" ] }, "value": { "title": "Value", "description": "The value to compare against", "examples": [ "100", "red" ] }, "operator": { "$ref": "#/components/schemas/ConditionOperator", "description": "The operator for the condition", "examples": [ "eq", "gt" ] } }, "type": "object", "required": [ "key", "value", "operator" ], "title": "SearchFilterCondition", "description": "Represents a condition with a field, operator, and value." }, "ConditionOperator": { "type": "string", "enum": [ "eq", "not_eq", "gt", "gte", "lt", "lte", "in", "not_in", "like", "contains", "starts_with", "not_like", "regex" ], "title": "ConditionOperator", "description": "Operator for a filter condition." }, "GrepTool": { "properties": { "store_identifiers": { "anyOf": [ { "items": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ] }, "type": "array", "minItems": 1 }, { "type": "null" } ], "title": "Store Identifiers", "description": "IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)" }, "type": { "type": "string", "const": "grep", "title": "Type", "default": "grep" }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" }, { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Filters", "description": "Optional filter conditions applied to every grep" }, "citations": { "type": "boolean", "title": "Citations", "description": "Have the model cite its evidence inline; the answer ships with the markers removed and an annotations list of file_citation entries pointing at the cited chunks", "default": false } }, "type": "object", "title": "GrepTool", "description": "Hosted tool: regular-expression match over stores' chunks, executed server-side.\n\ngrep runs the pattern against the literal chunk text — no embeddings, no\nreranker. Each call searches all pinned stores, or the store selected by the\nmodel when no stores are pinned, with one global result limit." }, "FilterChunksTool": { "properties": { "store_identifiers": { "anyOf": [ { "items": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ] }, "type": "array", "minItems": 1 }, { "type": "null" } ], "title": "Store Identifiers", "description": "IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)" }, "type": { "type": "string", "const": "filter_chunks", "title": "Type", "default": "filter_chunks" }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" }, { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Filters", "description": "Optional filter conditions applied to every listing" }, "citations": { "type": "boolean", "title": "Citations", "description": "Have the model cite its evidence inline; the answer ships with the markers removed and an annotations list of file_citation entries pointing at the cited chunks", "default": false } }, "type": "object", "title": "FilterChunksTool", "description": "Hosted tool: metadata-driven listing of stores' chunks, executed server-side.\n\nNo embeddings and no reranker: chunks are selected by metadata filters and\noptionally ordered globally by a numeric metadata field. Each call covers all\npinned stores, or the store selected by the model when no stores are pinned." }, "InspectMetadataTool": { "properties": { "store_identifiers": { "anyOf": [ { "items": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ] }, "type": "array", "minItems": 1 }, { "type": "null" } ], "title": "Store Identifiers", "description": "IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)" }, "type": { "type": "string", "const": "inspect_metadata", "title": "Type", "default": "inspect_metadata" }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" }, { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Filters", "description": "Optional filter conditions restricting the files the facets are computed over" } }, "type": "object", "title": "InspectMetadataTool", "description": "Hosted tool: metadata field/value overview of the caller's stores, executed server-side.\n\nFacets tell the model which metadata keys exist and what their values look\nlike, so it can filter (`grep`, `filter_chunks`) and phrase queries\nagainst real values instead of guessing." }, "GetChunksTool": { "properties": { "store_identifiers": { "anyOf": [ { "items": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ] }, "type": "array", "minItems": 1 }, { "type": "null" } ], "title": "Store Identifiers", "description": "IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)" }, "type": { "type": "string", "const": "get_chunks", "title": "Type", "default": "get_chunks" } }, "type": "object", "title": "GetChunksTool", "description": "Hosted tool: re-fetch of already-seen chunks by their `file_id:chunk_index` ids.\n\nThe recovery half of the per-chunk payload clip: a chunk a search returned\ntruncated can be re-read at a much larger budget. Configuration is the\nshared store scope only; the per-call id bound is the tool schema's own\n`maxItems`." }, "StoreSearchTool": { "properties": { "store_identifiers": { "anyOf": [ { "items": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ] }, "type": "array", "minItems": 1 }, { "type": "null" } ], "title": "Store Identifiers", "description": "IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)" }, "type": { "type": "string", "const": "store_search", "title": "Type", "default": "store_search" }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" }, { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Filters", "description": "Optional filter conditions applied to every search" }, "score_threshold": { "type": "number", "maximum": 1, "minimum": 0, "title": "Score Threshold", "description": "Minimum similarity score threshold", "default": 0 }, "citations": { "type": "boolean", "title": "Citations", "description": "Have the model cite its evidence inline; the answer ships with the markers removed and an annotations list of file_citation entries pointing at the cited chunks", "default": false } }, "type": "object", "title": "StoreSearchTool", "description": "Deprecated alias of `search_corpus`; parses to the same tool, echoed as sent.", "deprecated": true }, "StoreGrepTool": { "properties": { "store_identifiers": { "anyOf": [ { "items": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ] }, "type": "array", "minItems": 1 }, { "type": "null" } ], "title": "Store Identifiers", "description": "IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)" }, "type": { "type": "string", "const": "store_grep", "title": "Type", "default": "store_grep" }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" }, { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Filters", "description": "Optional filter conditions applied to every grep" }, "citations": { "type": "boolean", "title": "Citations", "description": "Have the model cite its evidence inline; the answer ships with the markers removed and an annotations list of file_citation entries pointing at the cited chunks", "default": false } }, "type": "object", "title": "StoreGrepTool", "description": "Deprecated alias of `grep`; parses to the same tool, echoed as sent.", "deprecated": true }, "StoreListChunksTool": { "properties": { "store_identifiers": { "anyOf": [ { "items": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ] }, "type": "array", "minItems": 1 }, { "type": "null" } ], "title": "Store Identifiers", "description": "IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)" }, "type": { "type": "string", "const": "store_list_chunks", "title": "Type", "default": "store_list_chunks" }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" }, { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Filters", "description": "Optional filter conditions applied to every listing" }, "citations": { "type": "boolean", "title": "Citations", "description": "Have the model cite its evidence inline; the answer ships with the markers removed and an annotations list of file_citation entries pointing at the cited chunks", "default": false } }, "type": "object", "title": "StoreListChunksTool", "description": "Deprecated alias of `filter_chunks`; parses to the same tool, echoed as sent.", "deprecated": true }, "MetadataFacetsTool": { "properties": { "store_identifiers": { "anyOf": [ { "items": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ] }, "type": "array", "minItems": 1 }, { "type": "null" } ], "title": "Store Identifiers", "description": "IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)" }, "type": { "type": "string", "const": "store_metadata_facets", "title": "Type", "default": "store_metadata_facets" }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" }, { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Filters", "description": "Optional filter conditions restricting the files the facets are computed over" } }, "type": "object", "title": "MetadataFacetsTool", "description": "Deprecated alias of `inspect_metadata`; parses to the same tool, echoed as sent.", "deprecated": true }, "ListStoresTool": { "properties": { "type": { "type": "string", "const": "list_stores", "title": "Type", "default": "list_stores" }, "limit": { "type": "integer", "maximum": 100, "minimum": 1, "title": "Limit", "description": "Number of stores returned per listing call", "default": 20 } }, "type": "object", "title": "ListStoresTool", "description": "Hosted tool: paginated listing of the caller's stores, executed server-side.\n\nPair it with the store-scoped tools that are left unpinned, so the model can\ndiscover which stores it may name." }, "ResponseToolChoiceFunction": { "properties": { "type": { "type": "string", "const": "function", "title": "Type", "default": "function" }, "name": { "type": "string", "title": "Name" } }, "type": "object", "required": [ "name" ], "title": "ResponseToolChoiceFunction", "description": "Force a Responses API function tool by name." }, "ToolChoiceMcp": { "properties": { "type": { "type": "string", "const": "mcp", "title": "Type", "default": "mcp" }, "server_label": { "type": "string", "title": "Server Label" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" } }, "type": "object", "required": [ "server_label" ], "title": "ToolChoiceMcp", "description": "Force a call to one MCP server's tools, or to one named tool of it." }, "ToolChoiceSearchCorpus": { "properties": { "type": { "type": "string", "const": "search_corpus", "title": "Type", "default": "search_corpus" } }, "type": "object", "title": "ToolChoiceSearchCorpus", "description": "Force a call to the hosted search tool (Mixedbread extension)." }, "ToolChoiceGrep": { "properties": { "type": { "type": "string", "const": "grep", "title": "Type", "default": "grep" } }, "type": "object", "title": "ToolChoiceGrep", "description": "Force a call to the hosted grep tool (Mixedbread extension)." }, "ToolChoiceFilterChunks": { "properties": { "type": { "type": "string", "const": "filter_chunks", "title": "Type", "default": "filter_chunks" } }, "type": "object", "title": "ToolChoiceFilterChunks", "description": "Force a call to the hosted chunk-listing tool (Mixedbread extension)." }, "ToolChoiceInspectMetadata": { "properties": { "type": { "type": "string", "const": "inspect_metadata", "title": "Type", "default": "inspect_metadata" } }, "type": "object", "title": "ToolChoiceInspectMetadata", "description": "Force a call to the hosted metadata-overview tool (Mixedbread extension)." }, "ToolChoiceStoreSearch": { "properties": { "type": { "type": "string", "const": "store_search", "title": "Type", "default": "store_search" } }, "type": "object", "title": "ToolChoiceStoreSearch", "description": "Deprecated alias of the `search_corpus` tool choice.", "deprecated": true }, "ToolChoiceStoreGrep": { "properties": { "type": { "type": "string", "const": "store_grep", "title": "Type", "default": "store_grep" } }, "type": "object", "title": "ToolChoiceStoreGrep", "description": "Deprecated alias of the `grep` tool choice.", "deprecated": true }, "ToolChoiceStoreListChunks": { "properties": { "type": { "type": "string", "const": "store_list_chunks", "title": "Type", "default": "store_list_chunks" } }, "type": "object", "title": "ToolChoiceStoreListChunks", "description": "Deprecated alias of the `filter_chunks` tool choice.", "deprecated": true }, "ToolChoiceMetadataFacets": { "properties": { "type": { "type": "string", "const": "store_metadata_facets", "title": "Type", "default": "store_metadata_facets" } }, "type": "object", "title": "ToolChoiceMetadataFacets", "description": "Deprecated alias of the `inspect_metadata` tool choice.", "deprecated": true }, "ToolChoiceListStores": { "properties": { "type": { "type": "string", "const": "list_stores", "title": "Type", "default": "list_stores" } }, "type": "object", "title": "ToolChoiceListStores", "description": "Force a call to the hosted list stores tool (Mixedbread extension)." }, "ContextManagementConfig": { "properties": { "edits": { "items": { "$ref": "#/components/schemas/ContextManagementEdit" }, "type": "array", "minItems": 1, "title": "Edits", "description": "The context edits enabled for this completion" } }, "type": "object", "required": [ "edits" ], "title": "ContextManagementConfig", "description": "Opt-in context editing for one completion (Mixedbread extension)." }, "ContextManagementEdit": { "properties": { "type": { "type": "string", "const": "prune_context", "title": "Type", "default": "prune_context" } }, "type": "object", "title": "ContextManagementEdit", "description": "One enabled context edit. `prune_context` gives the model a tool to clear\nold tool results when the conversation approaches the context window." }, "ResponseStreamOptions": { "properties": { "include_obfuscation": { "type": "boolean", "title": "Include Obfuscation", "default": true } }, "type": "object", "title": "ResponseStreamOptions" }, "ResponseTextConfig": { "properties": { "format": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/ResponseTextFormatText" }, { "$ref": "#/components/schemas/ResponseTextFormatJSONObject" }, { "$ref": "#/components/schemas/ResponseTextFormatJSONSchema" } ], "discriminator": { "propertyName": "type", "mapping": { "json_object": "#/components/schemas/ResponseTextFormatJSONObject", "json_schema": "#/components/schemas/ResponseTextFormatJSONSchema", "text": "#/components/schemas/ResponseTextFormatText" } } }, { "type": "null" } ], "title": "Format" }, "verbosity": { "anyOf": [ { "type": "string", "enum": [ "low", "medium", "high" ] }, { "type": "null" } ], "title": "Verbosity" } }, "type": "object", "title": "ResponseTextConfig" }, "ResponseTextFormatText": { "properties": { "type": { "type": "string", "const": "text", "title": "Type", "default": "text" } }, "type": "object", "title": "ResponseTextFormatText" }, "ResponseTextFormatJSONObject": { "properties": { "type": { "type": "string", "const": "json_object", "title": "Type", "default": "json_object" } }, "type": "object", "title": "ResponseTextFormatJSONObject" }, "ResponseTextFormatJSONSchema": { "properties": { "type": { "type": "string", "const": "json_schema", "title": "Type", "default": "json_schema" }, "name": { "type": "string", "title": "Name" }, "schema": { "additionalProperties": true, "type": "object", "title": "Schema" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "strict": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Strict" } }, "type": "object", "required": [ "name", "schema" ], "title": "ResponseTextFormatJSONSchema" }, "ResponseReasoningConfig": { "properties": { "effort": { "anyOf": [ { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh" ] }, { "type": "null" } ], "title": "Effort" }, "summary": { "anyOf": [ { "type": "string", "enum": [ "auto", "concise", "detailed" ] }, { "type": "null" } ], "title": "Summary" }, "generate_summary": { "anyOf": [ { "type": "string", "enum": [ "auto", "concise", "detailed" ] }, { "type": "null" } ], "title": "Generate Summary" } }, "type": "object", "title": "ResponseReasoningConfig" }, "Response": { "properties": { "id": { "type": "string", "title": "Id" }, "object": { "type": "string", "const": "response", "title": "Object", "default": "response" }, "created_at": { "type": "number", "title": "Created At" }, "status": { "type": "string", "enum": [ "completed", "failed", "in_progress", "cancelled", "queued", "incomplete" ], "title": "Status" }, "completed_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Completed At" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ResponseError" }, { "type": "null" } ] }, "incomplete_details": { "anyOf": [ { "$ref": "#/components/schemas/ResponseIncompleteDetails" }, { "type": "null" } ] }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions" }, "model": { "type": "string", "title": "Model", "default": "toast-1" }, "output": { "items": { "oneOf": [ { "$ref": "#/components/schemas/ResponseOutputMessage" }, { "$ref": "#/components/schemas/ResponseFunctionToolCall" }, { "$ref": "#/components/schemas/ResponseReasoningItem" }, { "$ref": "#/components/schemas/ResponseMcpListTools" }, { "$ref": "#/components/schemas/ResponseMcpCall" }, { "$ref": "#/components/schemas/ResponseMcpApprovalRequest" } ], "discriminator": { "propertyName": "type", "mapping": { "function_call": "#/components/schemas/ResponseFunctionToolCall", "mcp_approval_request": "#/components/schemas/ResponseMcpApprovalRequest", "mcp_call": "#/components/schemas/ResponseMcpCall", "mcp_list_tools": "#/components/schemas/ResponseMcpListTools", "message": "#/components/schemas/ResponseOutputMessage", "reasoning": "#/components/schemas/ResponseReasoningItem" } } }, "type": "array", "title": "Output" }, "parallel_tool_calls": { "type": "boolean", "title": "Parallel Tool Calls", "default": true }, "temperature": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Temperature" }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "$ref": "#/components/schemas/ResponseToolChoiceFunction" }, { "$ref": "#/components/schemas/ToolChoiceMcp" } ], "title": "Tool Choice", "default": "auto" }, "tools": { "items": { "anyOf": [ { "$ref": "#/components/schemas/ResponseFunctionTool" }, { "$ref": "#/components/schemas/ResponseNamespaceTool" }, { "$ref": "#/components/schemas/McpTool" } ] }, "type": "array", "title": "Tools" }, "top_p": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Top P" }, "background": { "type": "boolean", "title": "Background", "default": false }, "max_output_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Output Tokens" }, "max_tool_calls": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Tool Calls" }, "previous_response_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previous Response Id" }, "reasoning": { "anyOf": [ { "$ref": "#/components/schemas/ResponseReasoningConfig" }, { "type": "null" } ] }, "service_tier": { "type": "string", "enum": [ "auto", "default", "flex", "scale", "priority" ], "title": "Service Tier", "default": "default" }, "text": { "anyOf": [ { "$ref": "#/components/schemas/ResponseTextConfig" }, { "type": "null" } ] }, "truncation": { "type": "string", "enum": [ "auto", "disabled" ], "title": "Truncation", "default": "disabled" }, "usage": { "anyOf": [ { "$ref": "#/components/schemas/ResponseUsage" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "safety_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Safety Identifier" }, "prompt_cache_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prompt Cache Key" }, "user": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User" }, "hosted_tool_calls": { "items": { "oneOf": [ { "$ref": "#/components/schemas/SearchCorpusCallItem" }, { "$ref": "#/components/schemas/GrepCallItem" }, { "$ref": "#/components/schemas/FilterChunksCallItem" }, { "$ref": "#/components/schemas/InspectMetadataCallItem" }, { "$ref": "#/components/schemas/GetChunksCallItem" }, { "$ref": "#/components/schemas/StoreSearchCallItem" }, { "$ref": "#/components/schemas/StoreGrepCallItem" }, { "$ref": "#/components/schemas/StoreListChunksCallItem" }, { "$ref": "#/components/schemas/MetadataFacetsCallItem" }, { "$ref": "#/components/schemas/ListStoresCallItem" } ], "discriminator": { "propertyName": "type", "mapping": { "filter_chunks_call": "#/components/schemas/FilterChunksCallItem", "get_chunks_call": "#/components/schemas/GetChunksCallItem", "grep_call": "#/components/schemas/GrepCallItem", "inspect_metadata_call": "#/components/schemas/InspectMetadataCallItem", "list_stores_call": "#/components/schemas/ListStoresCallItem", "search_corpus_call": "#/components/schemas/SearchCorpusCallItem", "store_grep_call": "#/components/schemas/StoreGrepCallItem", "store_list_chunks_call": "#/components/schemas/StoreListChunksCallItem", "store_metadata_facets_call": "#/components/schemas/MetadataFacetsCallItem", "store_search_call": "#/components/schemas/StoreSearchCallItem" } } }, "type": "array", "title": "Hosted Tool Calls" }, "hosted_tools": { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchCorpusTool" }, { "$ref": "#/components/schemas/GrepTool" }, { "$ref": "#/components/schemas/FilterChunksTool" }, { "$ref": "#/components/schemas/InspectMetadataTool" }, { "$ref": "#/components/schemas/GetChunksTool" }, { "$ref": "#/components/schemas/StoreSearchTool" }, { "$ref": "#/components/schemas/StoreGrepTool" }, { "$ref": "#/components/schemas/StoreListChunksTool" }, { "$ref": "#/components/schemas/MetadataFacetsTool" }, { "$ref": "#/components/schemas/ListStoresTool" } ] }, "type": "array", "title": "Hosted Tools" }, "tool_tickets": { "items": { "$ref": "#/components/schemas/ToolTicket" }, "type": "array", "title": "Tool Tickets" }, "context_management": { "anyOf": [ { "$ref": "#/components/schemas/ContextManagementResult" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" } }, "type": "object", "required": [ "id", "created_at", "status" ], "title": "Response", "description": "A completed or in-progress OpenAI-compatible Response object." }, "ResponseError": { "properties": { "code": { "type": "string", "title": "Code" }, "message": { "type": "string", "title": "Message" } }, "type": "object", "required": [ "code", "message" ], "title": "ResponseError" }, "ResponseIncompleteDetails": { "properties": { "reason": { "anyOf": [ { "type": "string", "enum": [ "max_output_tokens", "content_filter", "max_tool_calls", "context_window" ] }, { "type": "null" } ], "title": "Reason" } }, "type": "object", "title": "ResponseIncompleteDetails" }, "ResponseOutputMessage": { "properties": { "type": { "type": "string", "const": "message", "title": "Type", "default": "message" }, "id": { "type": "string", "title": "Id" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "incomplete" ], "title": "Status" }, "role": { "type": "string", "const": "assistant", "title": "Role", "default": "assistant" }, "content": { "items": { "$ref": "#/components/schemas/ResponseOutputText" }, "type": "array", "title": "Content" } }, "type": "object", "required": [ "id", "status", "content" ], "title": "ResponseOutputMessage" }, "ResponseOutputText": { "properties": { "type": { "type": "string", "const": "output_text", "title": "Type", "default": "output_text" }, "annotations": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Annotations" }, "text": { "type": "string", "title": "Text" }, "logprobs": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Logprobs" } }, "type": "object", "required": [ "text" ], "title": "ResponseOutputText" }, "ResponseFunctionToolCall": { "properties": { "type": { "type": "string", "const": "function_call", "title": "Type", "default": "function_call" }, "id": { "type": "string", "title": "Id" }, "call_id": { "type": "string", "title": "Call Id" }, "name": { "type": "string", "title": "Name" }, "namespace": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Namespace" }, "arguments": { "type": "string", "title": "Arguments" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "incomplete" ], "title": "Status", "default": "completed" } }, "type": "object", "required": [ "id", "call_id", "name", "arguments" ], "title": "ResponseFunctionToolCall" }, "ResponseReasoningItem": { "properties": { "type": { "type": "string", "const": "reasoning", "title": "Type", "default": "reasoning" }, "id": { "type": "string", "title": "Id" }, "summary": { "items": { "$ref": "#/components/schemas/ResponseReasoningSummaryInput" }, "type": "array", "title": "Summary" }, "content": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ResponseReasoningText" }, "type": "array" }, { "type": "null" } ], "title": "Content" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "incomplete" ], "title": "Status", "default": "completed" } }, "type": "object", "required": [ "id" ], "title": "ResponseReasoningItem" }, "ResponseReasoningText": { "properties": { "type": { "type": "string", "const": "reasoning_text", "title": "Type", "default": "reasoning_text" }, "text": { "type": "string", "title": "Text" } }, "type": "object", "required": [ "text" ], "title": "ResponseReasoningText" }, "ResponseMcpListTools": { "properties": { "type": { "type": "string", "const": "mcp_list_tools", "title": "Type", "default": "mcp_list_tools" }, "id": { "type": "string", "title": "Id" }, "server_label": { "type": "string", "title": "Server Label" }, "tools": { "items": { "$ref": "#/components/schemas/McpListToolsTool" }, "type": "array", "title": "Tools" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" } }, "type": "object", "required": [ "id", "server_label" ], "title": "ResponseMcpListTools", "description": "The tools one MCP server offered this response." }, "ResponseMcpCall": { "properties": { "type": { "type": "string", "const": "mcp_call", "title": "Type", "default": "mcp_call" }, "id": { "type": "string", "title": "Id" }, "server_label": { "type": "string", "title": "Server Label" }, "name": { "type": "string", "title": "Name" }, "arguments": { "type": "string", "title": "Arguments" }, "output": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Output" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "approval_request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Approval Request Id" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "failed" ], "title": "Status", "default": "completed" } }, "type": "object", "required": [ "id", "server_label", "name", "arguments" ], "title": "ResponseMcpCall", "description": "One tool call run against an MCP server." }, "ResponseMcpApprovalRequest": { "properties": { "type": { "type": "string", "const": "mcp_approval_request", "title": "Type", "default": "mcp_approval_request" }, "id": { "type": "string", "title": "Id" }, "server_label": { "type": "string", "title": "Server Label" }, "name": { "type": "string", "title": "Name" }, "arguments": { "type": "string", "title": "Arguments" } }, "type": "object", "required": [ "id", "server_label", "name", "arguments" ], "title": "ResponseMcpApprovalRequest", "description": "A tool call waiting for the caller's `mcp_approval_response` on the next request." }, "ResponseUsage": { "properties": { "input_tokens": { "type": "integer", "title": "Input Tokens", "default": 0 }, "input_tokens_details": { "$ref": "#/components/schemas/ResponseInputTokensDetails" }, "output_tokens": { "type": "integer", "title": "Output Tokens", "default": 0 }, "output_tokens_details": { "$ref": "#/components/schemas/ResponseOutputTokensDetails" }, "total_tokens": { "type": "integer", "title": "Total Tokens", "default": 0 } }, "type": "object", "title": "ResponseUsage" }, "ResponseInputTokensDetails": { "properties": { "cached_tokens": { "type": "integer", "title": "Cached Tokens", "default": 0 } }, "type": "object", "title": "ResponseInputTokensDetails" }, "ResponseOutputTokensDetails": { "properties": { "reasoning_tokens": { "type": "integer", "title": "Reasoning Tokens", "default": 0 } }, "type": "object", "title": "ResponseOutputTokensDetails" }, "SearchCorpusCallItem": { "properties": { "type": { "type": "string", "const": "search_corpus_call", "title": "Type", "default": "search_corpus_call" }, "id": { "type": "string", "title": "Id" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "failed" ], "title": "Status", "default": "completed" }, "queries": { "items": { "type": "string" }, "type": "array", "title": "Queries" }, "metadata_filters": { "anyOf": [ { "items": { "$ref": "#/components/schemas/MetadataFilter" }, "type": "array" }, { "type": "null" } ], "title": "Metadata Filters" }, "filter_mode": { "type": "string", "enum": [ "all", "any" ], "title": "Filter Mode", "default": "all" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Store" }, "results": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Results" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ToolCallError" }, { "type": "null" } ] } }, "type": "object", "required": [ "id" ], "title": "SearchCorpusCallItem", "description": "Record of one server-side search execution." }, "MetadataFilter": { "properties": { "key": { "type": "string", "minLength": 1, "title": "Key", "description": "Metadata field key" }, "operator": { "$ref": "#/components/schemas/ConditionOperator", "description": "Comparison operator" }, "value": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" } ] }, "type": "array" }, { "type": "null" } ], "title": "Value", "description": "Value to compare against. Use a list for `in`/`not_in`." } }, "type": "object", "required": [ "key", "operator", "value" ], "title": "MetadataFilter", "description": "One metadata filter condition the model may attach to a hosted tool call." }, "ToolCallError": { "properties": { "code": { "type": "string", "enum": [ "permission_denied", "invalid_arguments", "server_error" ], "title": "Code" }, "message": { "type": "string", "title": "Message" } }, "type": "object", "required": [ "code", "message" ], "title": "ToolCallError", "description": "Machine-readable reason a hosted tool call failed (Mixedbread extension)." }, "GrepCallItem": { "properties": { "type": { "type": "string", "const": "grep_call", "title": "Type", "default": "grep_call" }, "id": { "type": "string", "title": "Id" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "failed" ], "title": "Status", "default": "completed" }, "pattern": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pattern" }, "targets": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StoreChunkGrepTarget" }, "type": "array" }, { "type": "null" } ], "title": "Targets" }, "case_sensitive": { "type": "boolean", "title": "Case Sensitive", "default": false }, "metadata_filters": { "anyOf": [ { "items": { "$ref": "#/components/schemas/MetadataFilter" }, "type": "array" }, { "type": "null" } ], "title": "Metadata Filters" }, "filter_mode": { "type": "string", "enum": [ "all", "any" ], "title": "Filter Mode", "default": "all" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Store" }, "results": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Results" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ToolCallError" }, { "type": "null" } ] } }, "type": "object", "required": [ "id" ], "title": "GrepCallItem", "description": "Record of one server-side grep execution." }, "StoreChunkGrepTarget": { "type": "string", "enum": [ "text", "generated" ], "title": "StoreChunkGrepTarget", "description": "Logical chunk content groups the grep tool can match against.\n\nThese map to one or more underlying chunk fields:\n\n- ``text`` → text chunks' ``text`` field (original text content).\n- ``generated`` → fields produced during ingestion (``transcription`` for audio/video,\n ``ocr_text`` for images, and ``summary`` across modalities)." }, "FilterChunksCallItem": { "properties": { "type": { "type": "string", "const": "filter_chunks_call", "title": "Type", "default": "filter_chunks_call" }, "id": { "type": "string", "title": "Id" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "failed" ], "title": "Status", "default": "completed" }, "metadata_filters": { "anyOf": [ { "items": { "$ref": "#/components/schemas/MetadataFilter" }, "type": "array" }, { "type": "null" } ], "title": "Metadata Filters" }, "filter_mode": { "type": "string", "enum": [ "all", "any" ], "title": "Filter Mode", "default": "all" }, "rank_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rank By" }, "direction": { "type": "string", "enum": [ "asc", "desc" ], "title": "Direction", "default": "desc" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Store" }, "results": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Results" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ToolCallError" }, { "type": "null" } ] } }, "type": "object", "required": [ "id" ], "title": "FilterChunksCallItem", "description": "Record of one server-side metadata-driven chunk listing." }, "InspectMetadataCallItem": { "properties": { "type": { "type": "string", "const": "inspect_metadata_call", "title": "Type", "default": "inspect_metadata_call" }, "id": { "type": "string", "title": "Id" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "failed" ], "title": "Status", "default": "completed" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Store" }, "facets": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Facets" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ToolCallError" }, { "type": "null" } ] } }, "type": "object", "required": [ "id" ], "title": "InspectMetadataCallItem", "description": "Record of one server-side metadata facets lookup." }, "GetChunksCallItem": { "properties": { "type": { "type": "string", "const": "get_chunks_call", "title": "Type", "default": "get_chunks_call" }, "id": { "type": "string", "title": "Id" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "failed" ], "title": "Status", "default": "completed" }, "chunk_ids": { "items": { "type": "string" }, "type": "array", "title": "Chunk Ids" }, "results": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Results" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ToolCallError" }, { "type": "null" } ] } }, "type": "object", "required": [ "id" ], "title": "GetChunksCallItem", "description": "Record of one server-side re-fetch of already-seen chunks." }, "StoreSearchCallItem": { "properties": { "type": { "type": "string", "const": "store_search_call", "title": "Type", "default": "store_search_call" }, "id": { "type": "string", "title": "Id" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "failed" ], "title": "Status", "default": "completed" }, "queries": { "items": { "type": "string" }, "type": "array", "title": "Queries" }, "metadata_filters": { "anyOf": [ { "items": { "$ref": "#/components/schemas/MetadataFilter" }, "type": "array" }, { "type": "null" } ], "title": "Metadata Filters" }, "filter_mode": { "type": "string", "enum": [ "all", "any" ], "title": "Filter Mode", "default": "all" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Store" }, "results": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Results" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ToolCallError" }, { "type": "null" } ] } }, "type": "object", "required": [ "id" ], "title": "StoreSearchCallItem", "description": "Deprecated `store_search_call` form, emitted for requests that declared the alias.", "deprecated": true }, "StoreGrepCallItem": { "properties": { "type": { "type": "string", "const": "store_grep_call", "title": "Type", "default": "store_grep_call" }, "id": { "type": "string", "title": "Id" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "failed" ], "title": "Status", "default": "completed" }, "pattern": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pattern" }, "targets": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StoreChunkGrepTarget" }, "type": "array" }, { "type": "null" } ], "title": "Targets" }, "case_sensitive": { "type": "boolean", "title": "Case Sensitive", "default": false }, "metadata_filters": { "anyOf": [ { "items": { "$ref": "#/components/schemas/MetadataFilter" }, "type": "array" }, { "type": "null" } ], "title": "Metadata Filters" }, "filter_mode": { "type": "string", "enum": [ "all", "any" ], "title": "Filter Mode", "default": "all" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Store" }, "results": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Results" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ToolCallError" }, { "type": "null" } ] } }, "type": "object", "required": [ "id" ], "title": "StoreGrepCallItem", "description": "Deprecated `store_grep_call` form, emitted for requests that declared the alias.", "deprecated": true }, "StoreListChunksCallItem": { "properties": { "type": { "type": "string", "const": "store_list_chunks_call", "title": "Type", "default": "store_list_chunks_call" }, "id": { "type": "string", "title": "Id" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "failed" ], "title": "Status", "default": "completed" }, "metadata_filters": { "anyOf": [ { "items": { "$ref": "#/components/schemas/MetadataFilter" }, "type": "array" }, { "type": "null" } ], "title": "Metadata Filters" }, "filter_mode": { "type": "string", "enum": [ "all", "any" ], "title": "Filter Mode", "default": "all" }, "rank_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rank By" }, "direction": { "type": "string", "enum": [ "asc", "desc" ], "title": "Direction", "default": "desc" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Store" }, "results": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Results" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ToolCallError" }, { "type": "null" } ] } }, "type": "object", "required": [ "id" ], "title": "StoreListChunksCallItem", "description": "Deprecated `store_list_chunks_call` form, emitted for requests that declared the alias.", "deprecated": true }, "MetadataFacetsCallItem": { "properties": { "type": { "type": "string", "const": "store_metadata_facets_call", "title": "Type", "default": "store_metadata_facets_call" }, "id": { "type": "string", "title": "Id" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "failed" ], "title": "Status", "default": "completed" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Store" }, "facets": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Facets" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ToolCallError" }, { "type": "null" } ] } }, "type": "object", "required": [ "id" ], "title": "MetadataFacetsCallItem", "description": "Deprecated `store_metadata_facets_call` form, emitted for requests that declared the alias.", "deprecated": true }, "ListStoresCallItem": { "properties": { "type": { "type": "string", "const": "list_stores_call", "title": "Type", "default": "list_stores_call" }, "id": { "type": "string", "title": "Id" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "failed" ], "title": "Status", "default": "completed" }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" }, "stores": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ListStoresResult" }, "type": "array" }, { "type": "null" } ], "title": "Stores" }, "has_more": { "type": "boolean", "title": "Has More", "default": false }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ToolCallError" }, { "type": "null" } ] } }, "type": "object", "required": [ "id" ], "title": "ListStoresCallItem", "description": "Record of one server-side store listing execution." }, "ListStoresResult": { "properties": { "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "connectors": { "items": { "type": "string" }, "type": "array", "title": "Connectors", "description": "Providers of the connectors ingesting into this store, e.g. slack or notion" } }, "type": "object", "required": [ "name" ], "title": "ListStoresResult", "description": "One store entry returned by the hosted list stores tool." }, "ToolTicket": { "properties": { "tool_call_id": { "type": "string", "title": "Tool Call Id", "description": "ID of the tool call in `choices[].message.tool_calls` this covers" }, "ticket": { "type": "string", "title": "Ticket", "description": "Opaque token to send as the X-Mxbai-Tool-Ticket header" }, "expires_at": { "type": "integer", "title": "Expires At", "description": "Unix timestamp after which the ticket no longer redeems" } }, "type": "object", "required": [ "tool_call_id", "ticket", "expires_at" ], "title": "ToolTicket", "description": "Proof that one client-executed tool call belongs to this completion." }, "ContextManagementResult": { "properties": { "applied_edits": { "items": { "oneOf": [ { "$ref": "#/components/schemas/AppliedPruneContextEdit" }, { "$ref": "#/components/schemas/AppliedTruncateToolResultEdit" } ], "discriminator": { "propertyName": "type", "mapping": { "prune_context": "#/components/schemas/AppliedPruneContextEdit", "truncate_tool_result": "#/components/schemas/AppliedTruncateToolResultEdit" } } }, "type": "array", "minItems": 1, "title": "Applied Edits" } }, "type": "object", "required": [ "applied_edits" ], "title": "ContextManagementResult", "description": "Context edits applied while serving one request (Mixedbread extension).\n\nOnly ever emitted non-empty: a request whose context was never edited\ncarries no `context_management` object at all." }, "AppliedPruneContextEdit": { "properties": { "type": { "type": "string", "const": "prune_context", "title": "Type", "default": "prune_context" }, "calls": { "type": "integer", "title": "Calls", "description": "Number of prune_context calls the model made in this request" }, "cleared_input_tokens": { "type": "integer", "title": "Cleared Input Tokens", "description": "Input tokens cleared from the model's context" } }, "type": "object", "required": [ "calls", "cleared_input_tokens" ], "title": "AppliedPruneContextEdit", "description": "Aggregate of the model's prune_context calls in one request." }, "AppliedTruncateToolResultEdit": { "properties": { "type": { "type": "string", "const": "truncate_tool_result", "title": "Type", "default": "truncate_tool_result" }, "tool_call_id": { "type": "string", "title": "Tool Call Id", "description": "ID of the tool call whose result was shortened" }, "cleared_input_tokens": { "type": "integer", "title": "Cleared Input Tokens", "description": "Input tokens cleared from the model's context" } }, "type": "object", "required": [ "tool_call_id", "cleared_input_tokens" ], "title": "AppliedTruncateToolResultEdit", "description": "One caller tool result shortened by the server's context-overflow recovery." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` Python: ```python from openai import OpenAI client = OpenAI( base_url="https://api.mixedbread.com/v1", api_key="YOUR_API_KEY", ) response = client.responses.create( model="toast-1", input="What is a search agent?", ) print(response.output_text) ``` Python (async): ```python from openai import AsyncOpenAI client = AsyncOpenAI( base_url="https://api.mixedbread.com/v1", api_key="YOUR_API_KEY", ) response = await client.responses.create( model="toast-1", input="What is a search agent?", ) print(response.output_text) ``` TypeScript: ```ts import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://api.mixedbread.com/v1", apiKey: "YOUR_API_KEY", }); const response = await client.responses.create({ model: "toast-1", input: "What is a search agent?", }); console.log(response.output_text); ``` cURL: ```bash curl https://api.mixedbread.com/v1/responses \ -H "Authorization: Bearer $MXBAI_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "model": "toast-1", "input": "What is a search agent?" }' ``` ## Stored response lifecycle Responses created with `store: true` can also use the OpenAI-compatible retrieve, delete, and input-items endpoints. These operations use the same REST paths and OpenAI SDK method names. Use the Mixedbread base URL and API key shown in the examples above. | Operation | REST endpoint | Python | TypeScript | Supported query parameters | | --- | --- | --- | --- | --- | | [Retrieve a response](https://developers.openai.com/api/reference/typescript/resources/responses/methods/retrieve) | `GET /v1/responses/{response_id}` | `client.responses.retrieve(response_id)` | `client.responses.retrieve(responseId)` | `stream`, `starting_after` | | [Delete a response](https://developers.openai.com/api/reference/typescript/resources/responses/methods/delete) | `DELETE /v1/responses/{response_id}` | `client.responses.delete(response_id)` | `client.responses.delete(responseId)` | None | | [List input items](https://developers.openai.com/api/reference/typescript/resources/responses/subresources/input_items/methods/list) | `GET /v1/responses/{response_id}/input_items` | `client.responses.input_items.list(response_id)` | `client.responses.inputItems.list(responseId)` | `limit`, `order`, `after` | Mixedbread supports the OpenAI lifecycle shape for text messages and client-executed function items. OpenAI options or item types not documented on this page are not supported. Deleting a stored response also deletes its persisted conversation chain. # Copy Store URL: https://www.mixedbread.com/api-reference/endpoints/stores/manage/copy-store Copy a store into a new store without re-parsing or re-embedding anything. Copies a store into a new store with the given name. The copy keeps every file, its metadata and its indexed chunks; nothing is parsed or embedded again. The request returns `202 Accepted` with the new store right away and the copy runs in the background: the new store's `status` is `in_progress` until it completes, and both stores report progress in `copy_state`. Neither store accepts file changes while the copy runs, and the source must have no files still being processed. > **Note** > > The SDKs ship a `copy_and_poll` / `copyAndPoll` helper that starts the copy and waits until the new store leaves `in_progress`. See [Copy Store](https://www.mixedbread.com/docs/stores/stores/manage-stores#copy-store). ## Errors Besides `422` for an invalid request, a copy fails before it starts with: | Status | When | | --- | --- | | `409` | The source is already part of a copy, still has files being processed, or lives in a different storage bucket than new stores of your organization; or the name is already taken | | `403` | Your plan's store limit is reached, or a scope-restricted API key gives the copy other tags | ```json { "paths": { "/v1/stores/{store_identifier}/copy": { "post": { "tags": [ "stores" ], "summary": "Copy Store", "description": "The copy keeps every file, its metadata and its indexed chunks, without\nre-parsing or re-embedding anything. It runs in the background: both stores\nreport the progress in `copy_state`, and the new store's `status` is\n`in_progress` until the copy completes. Neither store accepts file changes\nwhile the copy runs, and the source must have no files still being processed.", "operationId": "copy_store", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "store_identifier", "in": "path", "required": true, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ], "description": "The ID or name of the store to copy", "title": "Store Identifier" }, "description": "The ID or name of the store to copy" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCopyParams", "description": "Name and optional overrides for the copy" } } } }, "responses": { "202": { "description": "The new store; its contents arrive in the background", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Store" }, "example": { "id": "vs_def456", "name": "my-store-copy", "description": "Product documentation", "is_public": false, "metadata": {}, "tags": [], "file_counts": { "pending": 0, "in_progress": 0, "cancelled": 0, "completed": 0, "failed": 0, "total": 0 }, "expires_after": null, "status": "in_progress", "copy_state": { "role": "target", "status": "in_progress", "peer_store_id": "vs_abc123", "started_at": "2024-01-20T14:30:00Z", "error": null }, "created_at": "2024-01-20T14:30:00Z", "updated_at": "2024-01-20T14:30:00Z", "last_active_at": "2024-01-20T14:30:00Z", "usage_bytes": 0, "expires_at": null, "object": "store" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "StoreCopyParams": { "properties": { "name": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Name", "description": "Name for the copy. Can only contain lowercase letters, numbers, periods (.), and hyphens (-).", "examples": [ "technical-documentation-copy" ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Description of the copy; defaults to the source store's description" }, "metadata": { "anyOf": [ {}, { "type": "null" } ], "title": "Metadata", "description": "Metadata for the copy; defaults to the source store's metadata" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "maxItems": 32 }, { "type": "null" } ], "title": "Tags", "description": "Tags for the copy; defaults to the source store's tags" } }, "type": "object", "required": [ "name" ], "title": "StoreCopyParams", "description": "Parameters for copying a store into a new one." }, "Store": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier for the store", "examples": [ "1b8b486e-16d0-400b-8868-04cd75217a7e" ] }, "name": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Name", "description": "Name of the store", "examples": [ "customer-support-kb", "product-documentation" ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "null" } ], "title": "Description", "description": "Detailed description of the store's purpose and contents", "examples": [ "Contains customer support articles and FAQs" ] }, "is_public": { "type": "boolean", "title": "Is Public", "description": "Whether the store can be accessed by anyone with valid login credentials", "default": false, "examples": [ false ] }, "license": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License", "description": "License for public stores" }, "metadata": { "anyOf": [ {}, { "type": "null" } ], "title": "Metadata", "description": "Additional metadata associated with the store", "examples": [ { "category": "support", "language": "en" } ] }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags", "description": "Tags for organizing stores", "examples": [ [ "production", "docs" ] ] }, "config": { "anyOf": [ { "$ref": "#/components/schemas/StoreConfig" }, { "type": "null" } ], "description": "Store-level configuration defaults" }, "bucket_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Bucket Id", "description": "Customer bucket backing this store's storage; null = platform default" }, "file_counts": { "$ref": "#/components/schemas/FileCounts", "description": "Counts of files in different states" }, "expires_after": { "anyOf": [ { "$ref": "#/components/schemas/ExpiresAfter" }, { "type": "null" } ], "description": "Optional expiration policy" }, "status": { "$ref": "#/components/schemas/StoreStatus", "description": "Processing status of the store", "default": "completed" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when the store was created", "examples": [ "2024-01-01T00:00:00Z" ] }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Timestamp when the store was last updated", "examples": [ "2024-01-01T00:00:00Z" ] }, "last_active_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Active At", "description": "Timestamp when the store was last used" }, "usage_bytes": { "type": "integer", "title": "Usage Bytes", "description": "Total storage usage in bytes", "default": 0, "examples": [ 1024000 ] }, "usage_tokens": { "type": "integer", "title": "Usage Tokens", "description": "Total storage usage in tokens", "default": 0, "examples": [ 1024000 ] }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At", "description": "Optional expiration timestamp for the store", "examples": [ "2024-01-01T00:00:00Z" ] }, "copy_state": { "anyOf": [ { "$ref": "#/components/schemas/StoreCopyInfo" }, { "type": "null" } ], "description": "Set while the store is being copied from or into, and when a copy into it failed" }, "object": { "type": "string", "const": "store", "title": "Object", "description": "Type of the object", "default": "store" } }, "type": "object", "required": [ "id", "name", "created_at", "updated_at" ], "title": "Store", "description": "Model representing a store with its metadata and timestamps." }, "StoreConfig": { "properties": { "contextualization": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/ContextualizationConfig" } ], "title": "Contextualization", "description": "Include additional context when embedding chunks.", "default": false }, "lsf": { "anyOf": [ { "$ref": "#/components/schemas/LsfStoreConfig" }, { "type": "null" } ], "description": "Learn a scoring function for this store. Searches are captured as training data, a model is trained from reranking and answer signals, and once trained, searches apply it by default (override per search with the lsf option). Pass an empty object to enable it." } }, "type": "object", "title": "StoreConfig", "description": "Configuration for a store." }, "ContextualizationConfig": { "properties": { "with_metadata": { "anyOf": [ { "type": "boolean" }, { "items": { "type": "string" }, "type": "array" } ], "title": "With Metadata", "description": "Include all metadata or specific fields in the contextualization. Supports dot notation for nested fields (e.g., 'author.name'). When True, all metadata is included (flattened). When a list, only specified fields are included.", "default": false, "examples": [ true, false, [ "title", "author.name", "author.email", "tags" ] ] }, "with_file_context": { "type": "boolean", "title": "With File Context", "description": "Use an LLM to generate a short context for each chunk that situates it within the full document, improving retrieval accuracy.", "default": false } }, "type": "object", "title": "ContextualizationConfig" }, "LsfStoreConfig": { "properties": {}, "type": "object", "title": "LsfStoreConfig", "description": "Learned-scoring-function settings a store opts into; an empty object enables it." }, "FileCounts": { "properties": { "pending": { "type": "integer", "title": "Pending", "description": "Number of files waiting to be processed", "default": 0, "examples": [ 5 ] }, "in_progress": { "type": "integer", "title": "In Progress", "description": "Number of files currently being processed", "default": 0, "examples": [ 5 ] }, "cancelled": { "type": "integer", "title": "Cancelled", "description": "Number of files whose processing was cancelled", "default": 0, "examples": [ 2 ] }, "completed": { "type": "integer", "title": "Completed", "description": "Number of successfully processed files", "default": 0, "examples": [ 42 ] }, "failed": { "type": "integer", "title": "Failed", "description": "Number of files that failed processing", "default": 0, "examples": [ 1 ] }, "total": { "type": "integer", "title": "Total", "description": "Total number of files", "default": 0, "examples": [ 50 ] } }, "type": "object", "title": "FileCounts", "description": "Tracks counts of files in different states within a store." }, "ExpiresAfter": { "properties": { "anchor": { "type": "string", "const": "last_active_at", "title": "Anchor", "description": "Anchor date for the expiration policy", "default": "last_active_at" }, "days": { "type": "integer", "title": "Days", "description": "Number of days after which the store expires", "default": 30 } }, "type": "object", "title": "ExpiresAfter", "description": "Represents an expiration policy for a store." }, "StoreStatus": { "type": "string", "enum": [ "expired", "in_progress", "completed", "failed" ], "title": "StoreStatus", "description": "Status of a store." }, "StoreCopyInfo": { "properties": { "role": { "type": "string", "enum": [ "source", "target" ], "title": "Role", "description": "Whether this store is copied from or into" }, "status": { "type": "string", "enum": [ "in_progress", "failed" ], "title": "Status", "description": "Progress of the copy" }, "peer_store_id": { "type": "string", "title": "Peer Store Id", "description": "The other store of the copy" }, "started_at": { "type": "string", "format": "date-time", "title": "Started At", "description": "When the copy was requested" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Why the copy failed, when it did" } }, "type": "object", "required": [ "role", "status", "peer_store_id", "started_at" ], "title": "StoreCopyInfo", "description": "Progress of a store copy, present on both the source and the target while it runs." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") copy = mxbai.stores.copy( store_identifier="my-knowledge-base", name="my-store-copy", ) print(copy) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") copy = await mxbai.stores.copy( store_identifier="my-knowledge-base", name="my-store-copy", ) print(copy) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const copy = await mxbai.stores.copy("my-knowledge-base", { name: "my-store-copy", }); console.log(copy); ``` cURL: ```bash curl -X POST https://api.mixedbread.com/v1/stores/my-knowledge-base/copy \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "name": "my-store-copy" }' ``` # Search Chunks URL: https://www.mixedbread.com/api-reference/endpoints/stores/search/search-chunks Perform semantic search across store chunks. This endpoint searches through store chunks using semantic similarity matching. It supports complex search queries with filters and returns relevance-scored results. ```json { "paths": { "/v1/stores/search": { "post": { "tags": [ "stores" ], "summary": "Search Chunks", "description": "This endpoint searches through store chunks using semantic similarity matching.\nIt supports complex search queries with filters and returns relevance-scored results.\nAgentic searches can set `stream=true` to receive live trace events as\nserver-sent events while the search runs, followed by the final search response.\n\nFor the special 'mixedbread/web' store, this endpoint performs web search using\na mixture of different providers instead of semantic search. Web search results are always\nreranked for consistent scoring.", "operationId": "search_store_chunks", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "X-Mxbai-Tool-Ticket", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Ticket from a chat completion's `tool_tickets`, proving this call runs a tool call that completion asked for. Redeems once, and bills the operation at the discounted agent rate.", "title": "X-Mxbai-Tool-Ticket" }, "description": "Ticket from a chat completion's `tool_tickets`, proving this call runs a tool call that completion asked for. Redeems once, and bills the operation at the discounted agent rate." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreChunkSearchParams", "description": "Search parameters including query text, filters and pagination options" } } } }, "responses": { "200": { "description": "List of semantically similar chunks with relevance scores and pagination details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreSearchResponse" }, "example": { "object": "list", "data": [ { "chunk_index": 0, "mime_type": "text/plain", "model": "mxbai-omni", "score": 0.8512, "file_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "filename": "auth_guide.pdf", "store_id": "c3d4e5f6-a7b8-9012-cdef-345678901234", "metadata": { "source": "upload", "page": 1 }, "type": "text", "text": "Authentication is handled through JWT tokens. First, the user provides credentials..." }, { "chunk_index": 2, "mime_type": "image/jpeg", "model": "mxbai-omni", "score": 0.8234, "file_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012", "filename": "security_diagram.pdf", "store_id": "c3d4e5f6-a7b8-9012-cdef-345678901234", "metadata": { "category": "security", "year": 2024 }, "type": "image_url", "image_url": { "url": "https://example.com/auth-flow.jpg", "format": "jpeg" }, "ocr_text": "Authentication Flow Diagram", "summary": "A diagram showing the OAuth 2.0 authentication flow" } ] } }, "text/event-stream": { "schema": { "type": "string" }, "example": "data: {\"type\":\"search.started\",\"started_at\":\"2026-08-19T12:00:00Z\",\"query\":\"How does authentication work?\"}\n\ndata: {\"type\":\"search.completed\",\"response\":{\"object\":\"list\",\"data\":[]}}\n\ndata: [DONE]\n\n" } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "StoreChunkSearchParams": { "properties": { "store_identifiers": { "items": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ] }, "type": "array", "maxItems": 64, "minItems": 1, "title": "Store Identifiers", "description": "IDs or names of stores" }, "top_k": { "type": "integer", "maximum": 10000, "minimum": 1, "title": "Top K", "description": "Number of results to return", "default": 10 }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" }, { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Filters", "description": "Optional filter conditions" }, "file_ids": { "anyOf": [ { "prefixItems": [ { "$ref": "#/components/schemas/ConditionOperator" }, { "items": { "type": "string", "format": "uuid" }, "type": "array" } ], "type": "array", "maxItems": 2, "minItems": 2 }, { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "File Ids", "description": "Optional list of file IDs to filter chunks by (inclusion filter)", "examples": [ [ "123e4567-e89b-12d3-a456-426614174000", "123e4567-e89b-12d3-a456-426614174001" ], [ "in", [ "123e4567-e89b-12d3-a456-426614174000" ] ], [ "not_in", [ "123e4567-e89b-12d3-a456-426614174000" ] ] ] }, "query": { "$ref": "#/components/schemas/MultiModalQuery", "description": "Search query text", "examples": [ "how to configure SSL" ] }, "search_options": { "$ref": "#/components/schemas/StoreChunkSearchOptions", "description": "Search configuration options" }, "stream": { "type": "boolean", "title": "Stream", "description": "When true, return the search as a server-sent event stream: live agentic-search trace events when the search is agentic, and nothing before the results otherwise. A successful stream ends with a search.completed event containing the final search response, followed by [DONE].", "default": false } }, "type": "object", "required": [ "store_identifiers", "query" ], "title": "StoreChunkSearchParams", "description": "Query parameters for searching store chunks." }, "SearchFilter-Input": { "properties": { "all": { "anyOf": [ { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "All", "description": "List of conditions or filters to be ANDed together", "examples": [ [ { "key": "price", "operator": "gt", "value": "100" }, { "key": "color", "operator": "eq", "value": "red" } ], null ] }, "any": { "anyOf": [ { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Any", "description": "List of conditions or filters to be ORed together", "examples": [ [ { "key": "price", "operator": "gt", "value": "100" }, { "key": "color", "operator": "eq", "value": "red" } ], null ] }, "none": { "anyOf": [ { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "None", "description": "List of conditions or filters to be NOTed", "examples": [ [ { "key": "price", "operator": "gt", "value": "100" }, { "key": "color", "operator": "eq", "value": "red" } ], null ] } }, "type": "object", "title": "SearchFilter", "description": "Represents a filter with AND, OR, and NOT conditions." }, "SearchFilterCondition": { "properties": { "key": { "type": "string", "title": "Key", "description": "The field to apply the condition on", "examples": [ "price", "color" ] }, "value": { "title": "Value", "description": "The value to compare against", "examples": [ "100", "red" ] }, "operator": { "$ref": "#/components/schemas/ConditionOperator", "description": "The operator for the condition", "examples": [ "eq", "gt" ] } }, "type": "object", "required": [ "key", "value", "operator" ], "title": "SearchFilterCondition", "description": "Represents a condition with a field, operator, and value." }, "ConditionOperator": { "type": "string", "enum": [ "eq", "not_eq", "gt", "gte", "lt", "lte", "in", "not_in", "like", "contains", "starts_with", "not_like", "regex" ], "title": "ConditionOperator", "description": "Operator for a filter condition." }, "MultiModalQuery": { "anyOf": [ { "type": "string", "minLength": 1, "description": "The text input document to create embeddings for.", "examples": [ "This is a sample text input." ] }, { "oneOf": [ { "$ref": "#/components/schemas/ImageUrlInput" }, { "$ref": "#/components/schemas/TextInput" } ], "description": "The input to create embeddings for.", "discriminator": { "propertyName": "type", "mapping": { "image_url": "#/components/schemas/ImageUrlInput", "text": "#/components/schemas/TextInput" } } } ] }, "ImageUrlInput": { "properties": { "type": { "type": "string", "const": "image_url", "title": "Type", "description": "Input type identifier", "default": "image_url" }, "image_url": { "$ref": "#/components/schemas/ImageUrl-Input", "description": "The image input specification." } }, "type": "object", "required": [ "image_url" ], "title": "ImageUrlInput", "description": "Model for image input validation." }, "ImageUrl-Input": { "properties": { "url": { "anyOf": [ { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri" }, { "type": "string", "pattern": "data:(?P[\\w]+\\/[\\w\\-\\+\\.]+)?(?:\\;name\\=(?P[\\w\\.\\-%!*'~\\(\\)]+))?(?:\\;charset\\=(?P[\\w\\-\\+\\.]+))?(?P\\;base64)?,(?P.*)", "examples": [ "data:text/plain;charset=utf-8;base64,VGhlIHF1aWNrIGJyb3duIGZveCBqdW1wZWQgb3ZlciB0aGUgbGF6eSBkb2cu" ] } ], "title": "Url", "description": "The image URL. Can be either a URL or a Data URI." }, "format": { "type": "string", "title": "Format", "description": "The image format/mimetype", "default": "" } }, "type": "object", "required": [ "url" ], "title": "ImageUrl", "description": "Model for image URL validation." }, "TextInput": { "properties": { "type": { "type": "string", "const": "text", "title": "Type", "description": "Input type identifier", "default": "text" }, "text": { "type": "string", "minLength": 1, "title": "Text", "description": "Text content to process" } }, "type": "object", "required": [ "text" ], "title": "TextInput", "description": "Model for text input validation.\n\nAttributes:\n type: Input type identifier, always \"text\"\n text: The actual text content, with length and whitespace constraints" }, "StoreChunkSearchOptions": { "properties": { "score_threshold": { "type": "number", "maximum": 1, "minimum": 0, "title": "Score Threshold", "description": "Minimum similarity score threshold", "default": 0 }, "rewrite_query": { "type": "boolean", "title": "Rewrite Query", "description": "Whether to rewrite the query. Ignored when agentic is enabled (the agent handles query decomposition).", "default": false }, "rerank": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/RerankConfig" }, { "type": "null" } ], "title": "Rerank", "description": "Whether to rerank results and optional reranking configuration. Ignored when agentic is enabled (the agent handles ranking)." }, "agentic": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/AgenticSearchConfig" }, { "type": "null" } ], "title": "Agentic", "description": "Whether to use agentic multi-query search with automatic query decomposition and ranking. When enabled, rewrite_query and rerank options are ignored." }, "lsf": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Lsf", "description": "Whether to apply the learned scoring function to second-stage scoring. Requires weights configured for the searched stores; silently skipped otherwise." }, "return_metadata": { "type": "boolean", "title": "Return Metadata", "description": "Whether to return file metadata", "default": true }, "apply_search_rules": { "type": "boolean", "title": "Apply Search Rules", "description": "Whether to apply search rules", "default": true } }, "type": "object", "title": "StoreChunkSearchOptions", "description": "Options for configuring store chunk searches." }, "RerankConfig": { "properties": { "model": { "type": "string", "maxLength": 500, "minLength": 1, "title": "Model", "description": "The name of the reranking model", "default": "mixedbread-ai/mxbai-rerank-v3.1-listwise", "examples": [ "rerank_model" ] }, "with_metadata": { "anyOf": [ { "type": "boolean" }, { "items": { "type": "string" }, "type": "array" } ], "title": "With Metadata", "description": "Whether to include metadata in the reranked results", "default": false, "examples": [ true, false, [ "metadata1", "metadata2" ] ] }, "top_k": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "title": "Top K", "description": "Maximum number of results to return after reranking. If None, returns all reranked results.", "examples": [ 10, 50, 100 ] } }, "type": "object", "title": "RerankConfig", "description": "Represents a reranking configuration." }, "AgenticSearchConfig": { "properties": { "max_rounds": { "type": "integer", "maximum": 10, "minimum": 1, "title": "Max Rounds", "description": "Maximum number of search rounds", "default": 3 }, "queries_per_round": { "type": "integer", "maximum": 10, "minimum": 1, "title": "Queries Per Round", "description": "Maximum queries per round", "default": 4 }, "strict_top_k": { "type": "boolean", "title": "Strict Top K", "description": "Whether the agent fills the final ranking to top_k chunks from what it retrieved, capped at top_k, instead of returning only the chunks it judged relevant", "default": false }, "media_content": { "type": "string", "enum": [ "auto", "never", "always" ], "title": "Media Content", "description": "Controls when retrieved image content is provided to the agent. `auto` sends images only when no OCR text or summary is available, `never` disables image content, and `always` sends image content when available. Currently not forwarded: the search agent runs without image content.", "default": "auto" }, "instructions": { "anyOf": [ { "type": "string", "maxLength": 5000, "minLength": 1 }, { "type": "null" } ], "title": "Instructions", "description": "Additional custom instructions (followed only when not in conflict with existing rules)" }, "verbose": { "type": "boolean", "title": "Verbose", "description": "Internal: when set, the response includes a `trace` field with the full tool-call timeline. Used by the Mixedbread playground; not part of the documented public API.", "default": false } }, "type": "object", "title": "AgenticSearchConfig", "description": "Configuration for agentic multi-query search." }, "StoreSearchResponse": { "properties": { "object": { "type": "string", "const": "list", "title": "Object", "description": "The object type of the response", "default": "list" }, "data": { "items": { "oneOf": [ { "$ref": "#/components/schemas/mxbai_omni__core__store__models__chunk_types__ScoredTextInputChunk" }, { "$ref": "#/components/schemas/mxbai_omni__core__store__models__chunk_types__ScoredImageUrlInputChunk" }, { "$ref": "#/components/schemas/mxbai_omni__core__store__models__chunk_types__ScoredAudioUrlInputChunk" }, { "$ref": "#/components/schemas/mxbai_omni__core__store__models__chunk_types__ScoredVideoUrlInputChunk" } ], "discriminator": { "propertyName": "type", "mapping": { "audio_url": "#/components/schemas/mxbai_omni__core__store__models__chunk_types__ScoredAudioUrlInputChunk", "image_url": "#/components/schemas/mxbai_omni__core__store__models__chunk_types__ScoredImageUrlInputChunk", "text": "#/components/schemas/mxbai_omni__core__store__models__chunk_types__ScoredTextInputChunk", "video_url": "#/components/schemas/mxbai_omni__core__store__models__chunk_types__ScoredVideoUrlInputChunk" } } }, "type": "array", "title": "Data", "description": "The list of scored store file chunks" } }, "additionalProperties": true, "type": "object", "required": [ "data" ], "title": "StoreSearchResponse" }, "mxbai_omni__core__store__models__chunk_types__ScoredTextInputChunk": { "properties": { "chunk_index": { "type": "integer", "title": "Chunk Index", "description": "position of the chunk in a file", "examples": [ 0, 1, 2, 3, 4 ] }, "mime_type": { "type": "string", "title": "Mime Type", "description": "mime type of the chunk", "default": "text/plain", "examples": [ "text/plain" ] }, "generated_metadata": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/MarkdownChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/TextChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/EmailChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CsvChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/PDFChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CodeChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/AudioChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/VideoChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/ImageChunkGeneratedMetadata" } ], "discriminator": { "propertyName": "type", "mapping": { "audio": "#/components/schemas/AudioChunkGeneratedMetadata", "code": "#/components/schemas/CodeChunkGeneratedMetadata", "csv": "#/components/schemas/CsvChunkGeneratedMetadata", "email": "#/components/schemas/EmailChunkGeneratedMetadata", "image": "#/components/schemas/ImageChunkGeneratedMetadata", "markdown": "#/components/schemas/MarkdownChunkGeneratedMetadata", "pdf": "#/components/schemas/PDFChunkGeneratedMetadata", "text": "#/components/schemas/TextChunkGeneratedMetadata", "video": "#/components/schemas/VideoChunkGeneratedMetadata" } } }, { "type": "null" } ], "title": "Generated Metadata", "description": "metadata of the chunk", "examples": [ { "file_size": 1024, "file_type": "text/plain", "language": "en", "type": "text", "word_count": 100 } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "model used for this chunk", "examples": [ "text-embedding-ada-002", "clip-vit-large-patch14" ] }, "score": { "type": "number", "title": "Score", "description": "score of the chunk", "examples": [ 0.5 ] }, "file_id": { "type": "string", "title": "File Id", "description": "file id", "examples": [ "file1" ] }, "filename": { "type": "string", "title": "Filename", "description": "filename", "examples": [ "file1" ] }, "store_id": { "type": "string", "title": "Store Id", "description": "store id", "examples": [ "store1" ] }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Id", "description": "external identifier for this file", "examples": [ "ext-123" ] }, "metadata": { "anyOf": [ {}, { "type": "null" } ], "title": "Metadata", "description": "file metadata", "examples": [ { "key": "value" } ] }, "file_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Url", "description": "Presigned URL to download the file this chunk belongs to; null when there is no stored file", "examples": [ "https://storage.mixedbread.com/org1/files/file1.pdf?X-Amz-Signature=..." ] }, "type": { "type": "string", "const": "text", "title": "Type", "description": "Input type identifier", "default": "text" }, "offset": { "type": "integer", "title": "Offset", "description": "The offset of the text in the file relative to the start of the file.", "default": 0, "examples": [ 0, 13, 42 ] }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text", "description": "Text content" }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context", "description": "LLM-generated context that situates this chunk within its source document", "examples": [ "This chunk is from an SEC filing on ACME corp's Q2 2023 performance." ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "summary of the text chunk", "examples": [ "A short overview of ACME's Q2 2023 performance." ] } }, "type": "object", "required": [ "chunk_index", "score", "file_id", "filename", "store_id" ], "title": "ScoredTextInputChunk" }, "MarkdownChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "markdown", "title": "Type", "default": "markdown" }, "file_type": { "type": "string", "const": "text/markdown", "title": "File Type", "default": "text/markdown" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "chunk_headings": { "items": { "$ref": "#/components/schemas/MarkdownHeading" }, "type": "array", "title": "Chunk Headings" }, "heading_context": { "items": { "$ref": "#/components/schemas/MarkdownHeading" }, "type": "array", "title": "Heading Context" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" }, "frontmatter": { "additionalProperties": true, "type": "object", "title": "Frontmatter" } }, "additionalProperties": true, "type": "object", "title": "MarkdownChunkGeneratedMetadata" }, "MarkdownHeading": { "properties": { "level": { "type": "integer", "title": "Level" }, "text": { "type": "string", "title": "Text" } }, "type": "object", "required": [ "level", "text" ], "title": "MarkdownHeading" }, "TextChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "text", "title": "Type", "default": "text" }, "file_type": { "type": "string", "enum": [ "text/plain", "message/rfc822" ], "title": "File Type", "default": "text/plain" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "title": "TextChunkGeneratedMetadata" }, "EmailChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "email", "title": "Type", "default": "email" }, "file_type": { "type": "string", "title": "File Type", "default": "message/rfc822" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subject" }, "from_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From Email" }, "to_emails": { "items": { "type": "string" }, "type": "array", "title": "To Emails" }, "cc_emails": { "items": { "type": "string" }, "type": "array", "title": "Cc Emails" }, "bcc_emails": { "items": { "type": "string" }, "type": "array", "title": "Bcc Emails" }, "date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Date" }, "attachment_names": { "items": { "type": "string" }, "type": "array", "title": "Attachment Names" } }, "additionalProperties": true, "type": "object", "title": "EmailChunkGeneratedMetadata" }, "CsvChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "csv", "title": "Type", "default": "csv" }, "file_type": { "type": "string", "const": "text/csv", "title": "File Type", "default": "text/csv" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "start_row": { "type": "integer", "title": "Start Row", "default": 0 }, "num_rows": { "type": "integer", "title": "Num Rows", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "title": "CsvChunkGeneratedMetadata" }, "PDFChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "pdf", "title": "Type", "default": "pdf" }, "file_type": { "type": "string", "const": "application/pdf", "title": "File Type", "default": "application/pdf" }, "total_pages": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Pages" }, "total_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Size" }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" }, "layout": { "anyOf": [ { "$ref": "#/components/schemas/LayoutMetadata" }, { "type": "null" } ] } }, "additionalProperties": true, "type": "object", "title": "PDFChunkGeneratedMetadata" }, "LayoutMetadata": { "properties": { "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Width" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Height" }, "elements": { "items": { "$ref": "#/components/schemas/LayoutElement" }, "type": "array", "title": "Elements" } }, "type": "object", "title": "LayoutMetadata", "description": "Per-page layout for chunks parsed in high-quality (visual) mode.\n\n``elements`` are ordered by reading order (list position == reading order).\n``width``/``height`` are the page-image dimensions the ``bbox`` coords are\nrelative to, so consumers can normalize/render without a second fetch.\n\nLayout is part of the generated metadata payload and is returned with the\nchunk whenever present." }, "LayoutElement": { "properties": { "bbox": { "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" }, { "type": "number" } ], "type": "array", "maxItems": 4, "minItems": 4, "title": "Bbox" }, "type": { "type": "string", "title": "Type" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text" } }, "type": "object", "required": [ "bbox", "type" ], "title": "LayoutElement", "description": "A single detected layout element and its location on the page image." }, "CodeChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "code", "title": "Type", "default": "code" }, "file_type": { "type": "string", "title": "File Type" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "required": [ "file_type" ], "title": "CodeChunkGeneratedMetadata" }, "AudioChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "audio", "title": "Type", "default": "audio" }, "file_type": { "type": "string", "title": "File Type", "default": "audio/mpeg" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "total_duration_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Duration Seconds" }, "sample_rate": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Sample Rate" }, "channels": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Channels" }, "audio_format": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Audio Format" }, "bpm": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bpm" }, "speakers": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Speakers" }, "speaker_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Speaker Count" }, "speaker_turns": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SpeakerTurn" }, "type": "array" }, { "type": "null" } ], "title": "Speaker Turns" }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "title": "AudioChunkGeneratedMetadata" }, "SpeakerTurn": { "properties": { "speaker": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Speaker" }, "text": { "type": "string", "title": "Text" }, "start_time_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Start Time Seconds" }, "end_time_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "End Time Seconds" } }, "type": "object", "required": [ "text" ], "title": "SpeakerTurn" }, "VideoChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "video", "title": "Type", "default": "video" }, "file_type": { "type": "string", "title": "File Type", "default": "video/mp4" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "total_duration_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Duration Seconds" }, "fps": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Fps" }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Width" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Height" }, "frame_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Frame Count" }, "has_audio_stream": { "type": "boolean", "title": "Has Audio Stream", "default": false }, "bpm": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bpm" }, "speakers": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Speakers" }, "speaker_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Speaker Count" }, "speaker_turns": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SpeakerTurn" }, "type": "array" }, { "type": "null" } ], "title": "Speaker Turns" }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "title": "VideoChunkGeneratedMetadata" }, "ImageChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "image", "title": "Type", "default": "image" }, "file_type": { "type": "string", "title": "File Type", "default": "image/jpeg" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Width" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Height" }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" }, "layout": { "anyOf": [ { "$ref": "#/components/schemas/LayoutMetadata" }, { "type": "null" } ] } }, "additionalProperties": true, "type": "object", "title": "ImageChunkGeneratedMetadata" }, "mxbai_omni__core__store__models__chunk_types__ScoredImageUrlInputChunk": { "properties": { "chunk_index": { "type": "integer", "title": "Chunk Index", "description": "position of the chunk in a file", "examples": [ 0, 1, 2, 3, 4 ] }, "mime_type": { "type": "string", "title": "Mime Type", "description": "mime type of the chunk", "default": "image/jpeg", "examples": [ "image/jpeg" ] }, "generated_metadata": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/MarkdownChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/TextChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/EmailChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CsvChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/PDFChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CodeChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/AudioChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/VideoChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/ImageChunkGeneratedMetadata" } ], "discriminator": { "propertyName": "type", "mapping": { "audio": "#/components/schemas/AudioChunkGeneratedMetadata", "code": "#/components/schemas/CodeChunkGeneratedMetadata", "csv": "#/components/schemas/CsvChunkGeneratedMetadata", "email": "#/components/schemas/EmailChunkGeneratedMetadata", "image": "#/components/schemas/ImageChunkGeneratedMetadata", "markdown": "#/components/schemas/MarkdownChunkGeneratedMetadata", "pdf": "#/components/schemas/PDFChunkGeneratedMetadata", "text": "#/components/schemas/TextChunkGeneratedMetadata", "video": "#/components/schemas/VideoChunkGeneratedMetadata" } } }, { "type": "null" } ], "title": "Generated Metadata", "description": "metadata of the chunk", "examples": [ { "file_size": 1024, "file_type": "text/plain", "language": "en", "type": "text", "word_count": 100 } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "model used for this chunk", "examples": [ "text-embedding-ada-002", "clip-vit-large-patch14" ] }, "score": { "type": "number", "title": "Score", "description": "score of the chunk", "examples": [ 0.5 ] }, "file_id": { "type": "string", "title": "File Id", "description": "file id", "examples": [ "file1" ] }, "filename": { "type": "string", "title": "Filename", "description": "filename", "examples": [ "file1" ] }, "store_id": { "type": "string", "title": "Store Id", "description": "store id", "examples": [ "store1" ] }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Id", "description": "external identifier for this file", "examples": [ "ext-123" ] }, "metadata": { "anyOf": [ {}, { "type": "null" } ], "title": "Metadata", "description": "file metadata", "examples": [ { "key": "value" } ] }, "file_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Url", "description": "Presigned URL to download the file this chunk belongs to; null when there is no stored file", "examples": [ "https://storage.mixedbread.com/org1/files/file1.pdf?X-Amz-Signature=..." ] }, "type": { "type": "string", "const": "image_url", "title": "Type", "description": "Input type identifier", "default": "image_url" }, "ocr_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ocr Text", "description": "ocr text of the image", "examples": [ "2025 Financial Report" ] }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context", "description": "LLM-generated context that situates this image within its source document", "examples": [ "This page contains ACME's Q2 2023 financial results." ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "summary of the image", "examples": [ "A financial report for 2025" ] }, "image_url": { "anyOf": [ { "$ref": "#/components/schemas/ImageUrl-Output" }, { "type": "null" } ], "description": "Image URL" } }, "type": "object", "required": [ "chunk_index", "score", "file_id", "filename", "store_id" ], "title": "ScoredImageUrlInputChunk" }, "ImageUrl-Output": { "properties": { "url": { "type": "string", "title": "Url", "description": "The image URL. Can be either a URL or a Data URI." }, "format": { "type": "string", "title": "Format", "description": "The image format/mimetype", "default": "" } }, "type": "object", "required": [ "url" ], "title": "ImageUrl", "description": "Model for image URL validation." }, "mxbai_omni__core__store__models__chunk_types__ScoredAudioUrlInputChunk": { "properties": { "chunk_index": { "type": "integer", "title": "Chunk Index", "description": "position of the chunk in a file", "examples": [ 0, 1, 2, 3, 4 ] }, "mime_type": { "type": "string", "title": "Mime Type", "description": "mime type of the chunk", "default": "audio/mpeg", "examples": [ "audio/mpeg" ] }, "generated_metadata": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/MarkdownChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/TextChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/EmailChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CsvChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/PDFChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CodeChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/AudioChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/VideoChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/ImageChunkGeneratedMetadata" } ], "discriminator": { "propertyName": "type", "mapping": { "audio": "#/components/schemas/AudioChunkGeneratedMetadata", "code": "#/components/schemas/CodeChunkGeneratedMetadata", "csv": "#/components/schemas/CsvChunkGeneratedMetadata", "email": "#/components/schemas/EmailChunkGeneratedMetadata", "image": "#/components/schemas/ImageChunkGeneratedMetadata", "markdown": "#/components/schemas/MarkdownChunkGeneratedMetadata", "pdf": "#/components/schemas/PDFChunkGeneratedMetadata", "text": "#/components/schemas/TextChunkGeneratedMetadata", "video": "#/components/schemas/VideoChunkGeneratedMetadata" } } }, { "type": "null" } ], "title": "Generated Metadata", "description": "metadata of the chunk", "examples": [ { "file_size": 1024, "file_type": "text/plain", "language": "en", "type": "text", "word_count": 100 } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "model used for this chunk", "examples": [ "text-embedding-ada-002", "clip-vit-large-patch14" ] }, "score": { "type": "number", "title": "Score", "description": "score of the chunk", "examples": [ 0.5 ] }, "file_id": { "type": "string", "title": "File Id", "description": "file id", "examples": [ "file1" ] }, "filename": { "type": "string", "title": "Filename", "description": "filename", "examples": [ "file1" ] }, "store_id": { "type": "string", "title": "Store Id", "description": "store id", "examples": [ "store1" ] }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Id", "description": "external identifier for this file", "examples": [ "ext-123" ] }, "metadata": { "anyOf": [ {}, { "type": "null" } ], "title": "Metadata", "description": "file metadata", "examples": [ { "key": "value" } ] }, "file_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Url", "description": "Presigned URL to download the file this chunk belongs to; null when there is no stored file", "examples": [ "https://storage.mixedbread.com/org1/files/file1.pdf?X-Amz-Signature=..." ] }, "type": { "type": "string", "const": "audio_url", "title": "Type", "description": "Input type identifier", "default": "audio_url" }, "transcription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transcription", "description": "speech recognition (sr) text of the audio", "examples": [ "The year 2025 reports for .." ] }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context", "description": "LLM-generated context that situates this audio chunk within its source file", "examples": [ "This segment introduces ACME's quarterly earnings call." ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "summary of the audio", "examples": [ "A financial report audio for 2025" ] }, "audio_url": { "anyOf": [ { "$ref": "#/components/schemas/AudioUrl" }, { "type": "null" } ], "description": "Audio URL" }, "sampling_rate": { "type": "integer", "title": "Sampling Rate", "description": "The sampling rate of the audio." } }, "type": "object", "required": [ "chunk_index", "score", "file_id", "filename", "store_id", "sampling_rate" ], "title": "ScoredAudioUrlInputChunk" }, "AudioUrl": { "properties": { "url": { "type": "string", "title": "Url", "description": "The audio URL. Can be either a URL or a Data URI." } }, "type": "object", "required": [ "url" ], "title": "AudioUrl", "description": "Model for audio URL validation." }, "mxbai_omni__core__store__models__chunk_types__ScoredVideoUrlInputChunk": { "properties": { "chunk_index": { "type": "integer", "title": "Chunk Index", "description": "position of the chunk in a file", "examples": [ 0, 1, 2, 3, 4 ] }, "mime_type": { "type": "string", "title": "Mime Type", "description": "mime type of the chunk", "default": "video/mp4", "examples": [ "video/mp4" ] }, "generated_metadata": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/MarkdownChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/TextChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/EmailChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CsvChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/PDFChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CodeChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/AudioChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/VideoChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/ImageChunkGeneratedMetadata" } ], "discriminator": { "propertyName": "type", "mapping": { "audio": "#/components/schemas/AudioChunkGeneratedMetadata", "code": "#/components/schemas/CodeChunkGeneratedMetadata", "csv": "#/components/schemas/CsvChunkGeneratedMetadata", "email": "#/components/schemas/EmailChunkGeneratedMetadata", "image": "#/components/schemas/ImageChunkGeneratedMetadata", "markdown": "#/components/schemas/MarkdownChunkGeneratedMetadata", "pdf": "#/components/schemas/PDFChunkGeneratedMetadata", "text": "#/components/schemas/TextChunkGeneratedMetadata", "video": "#/components/schemas/VideoChunkGeneratedMetadata" } } }, { "type": "null" } ], "title": "Generated Metadata", "description": "metadata of the chunk", "examples": [ { "file_size": 1024, "file_type": "text/plain", "language": "en", "type": "text", "word_count": 100 } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "model used for this chunk", "examples": [ "text-embedding-ada-002", "clip-vit-large-patch14" ] }, "score": { "type": "number", "title": "Score", "description": "score of the chunk", "examples": [ 0.5 ] }, "file_id": { "type": "string", "title": "File Id", "description": "file id", "examples": [ "file1" ] }, "filename": { "type": "string", "title": "Filename", "description": "filename", "examples": [ "file1" ] }, "store_id": { "type": "string", "title": "Store Id", "description": "store id", "examples": [ "store1" ] }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Id", "description": "external identifier for this file", "examples": [ "ext-123" ] }, "metadata": { "anyOf": [ {}, { "type": "null" } ], "title": "Metadata", "description": "file metadata", "examples": [ { "key": "value" } ] }, "file_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Url", "description": "Presigned URL to download the file this chunk belongs to; null when there is no stored file", "examples": [ "https://storage.mixedbread.com/org1/files/file1.pdf?X-Amz-Signature=..." ] }, "type": { "type": "string", "const": "video_url", "title": "Type", "description": "Input type identifier", "default": "video_url" }, "transcription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transcription", "description": "speech recognition (sr) text of the video", "examples": [ "The year 2025 reports for .." ] }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context", "description": "LLM-generated context that situates this video chunk within its source file", "examples": [ "This segment demonstrates the product's document search workflow." ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "summary of the video", "examples": [ "A financial report video for 2025" ] }, "video_url": { "anyOf": [ { "$ref": "#/components/schemas/VideoUrl" }, { "type": "null" } ], "description": "Video URL" } }, "type": "object", "required": [ "chunk_index", "score", "file_id", "filename", "store_id" ], "title": "ScoredVideoUrlInputChunk" }, "VideoUrl": { "properties": { "url": { "type": "string", "title": "Url", "description": "The video URL. Can be either a URL or a Data URI." } }, "type": "object", "required": [ "url" ], "title": "VideoUrl", "description": "Model for video URL validation." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` Python: ```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 (async): ```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: ```ts 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); } ``` cURL: ```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 }' ``` ## Streaming events When you search chunks with `search_options.agentic: true` and `stream: true`, the server emits server-sent events as the Agentic Search runs. This section contains the events emitted by the server. ### search.started Emitted when the Agentic Search starts. | Field | Type | Required | Description | | --- | --- | --- | --- | | `type` | "search.started" | yes | The event type. Always `search.started`. | | `started_at` | string (date-time) | yes | Time when the Agentic Search began. | | `query` | string | yes | Original query submitted by the user. | **search.started** JSON: ```json { "type": "search.started", "started_at": "2026-08-19T12:00:00Z", "query": "How did revenue change from 2024 to 2025?" } ``` ### tool_call.started Emitted when the agent starts a retrieval, metadata, or generation step. | Field | Type | Required | Description | | --- | --- | --- | --- | | `type` | "tool_call.started" | yes | The event type. Always `tool_call.started`. | | `tool_call_id` | string | yes | Identifier that pairs this event with its `tool_call.completed` event. | | `tool_name` | string | yes | Name of the tool being invoked. | | `started_at` | string (date-time) | yes | Time when the tool call began. | | `arguments` | object | null | no | Compact summary of the arguments passed to the tool. | **tool_call.started** JSON: ```json { "type": "tool_call.started", "tool_call_id": "live-a1b2c3d4e5f6", "tool_name": "search_corpus", "started_at": "2026-08-19T12:00:00.120Z", "arguments": { "query": "2025 annual revenue", "top_k": 10 } } ``` ### tool_call.completed Emitted when a retrieval, metadata, or generation step finishes. The `tool_call_id` matches the preceding `tool_call.started` event. | Field | Type | Required | Description | | --- | --- | --- | --- | | `type` | "tool_call.completed" | yes | The event type. Always `tool_call.completed`. | | `tool_call` | object | yes | The finished live tool-call span, with the fields below. | Fields of `tool_call`: | Field | Type | Required | Description | | --- | --- | --- | --- | | `tool_call_id` | string | yes | Identifier shared with the matching `tool_call.started` event. | | `tool_name` | string | yes | Name of the tool that was invoked. | | `tool_type` | "function" | "extension" | "datastore" | yes | Category of the tool. | | `started_at` | string (date-time) | yes | Time when the tool call began. | | `duration` | string | yes | Time taken to execute the tool call, as an ISO 8601 duration. | | `arguments` | object | null | no | Arguments passed to the tool. | | `result` | object | null | no | Compact result summary. Null when the tool errored. | | `error` | string | null | no | Error message when the tool call failed. | | `error_kind` | "provider" | "agent" | null | no | Failure classification. `provider` indicates an infrastructure failure; `agent` indicates feedback the agent can recover from. | **tool_call.completed** JSON: ```json { "type": "tool_call.completed", "tool_call": { "tool_call_id": "live-a1b2c3d4e5f6", "tool_name": "search_corpus", "tool_type": "function", "started_at": "2026-08-19T12:00:00.120Z", "duration": "PT0.42S", "arguments": { "query": "2025 annual revenue", "top_k": 10 }, "result": { "result_count": 10 }, "error": null, "error_kind": null } } ``` ### search.completed Emitted when the Agentic Search succeeds. Its `response` field contains the final search response and the authoritative trace for the completed run. After this event, the server emits `data: [DONE]` and closes the stream. | Field | Type | Required | Description | | --- | --- | --- | --- | | `type` | "search.completed" | yes | The event type. Always `search.completed`. | | `response` | StoreSearchResponse | yes | The final ranked search response, including the authoritative Agentic Search trace. | **search.completed** JSON: ```json { "type": "search.completed", "response": { "object": "list", "data": [], "trace": { "started_at": "2026-08-19T12:00:00Z", "search_time": "PT1.84S", "query": "How did revenue change from 2024 to 2025?", "instructions": null, "rounds_executed": 1, "tool_calls": [], "results": [] } } } ``` ### search.failed Emitted when the Agentic Search stops with an error. The stream closes after this event and does not emit `[DONE]`. | Field | Type | Required | Description | | --- | --- | --- | --- | | `type` | "search.failed" | yes | The event type. Always `search.failed`. | | `error` | string | yes | User-safe failure message. | **search.failed** JSON: ```json { "type": "search.failed", "error": "The search could not be completed." } ``` # Error Handling URL: https://www.mixedbread.com/api-reference/error-handling Documentation on error handling with the Mixedbread API. Learn about common status codes, how to handle them, and best practices for error handling. ## Common Status Codes Understanding the status codes returned by the API is the first step in handling responses correctly. Here are the most common codes you might encounter: | Code | Meaning | Description | | :--- | :------------------ | :--------------------------------------------------------------------------- | | 200 | OK | Request successful. The response contains the requested data. | | 201 | Created | Resource successfully created. Common for POST requests. | | 400 | Bad Request | Malformed request or missing required parameters. | | 401 | Unauthorized | Invalid, expired, or missing API key. | | 402 | Payment Required | Insufficient credit balance for the request. | | 403 | Forbidden | Valid credentials but insufficient permissions for this resource. | | 404 | Not Found | The requested resource doesn't exist. | | 409 | Conflict | Operation conflicts with current resource state. | | 422 | Unprocessable Entity| Request format is correct but cannot be processed. | | 429 | Rate Limit Exceeded | Too many requests. Wait before retrying. | | 500 | Internal Server Error | Unexpected server error. Retry after a brief wait. | | 503 | Service Unavailable | Service temporarily down for maintenance or overloaded. Retry later. | ## Best Practices Build reliable applications with these error handling patterns: 1. **Catch specific errors first** - Handle specialized error types before generic exceptions 2. **Check status codes early** - Validate response status before processing the body 3. **Implement smart retries** - Use exponential backoff for transient errors ## Code Examples **Error Handling** Python: ```python from mixedbread import ( Mixedbread, AuthenticationError, RateLimitError ) mxbai = Mixedbread(api_key="YOUR_API_KEY") try: res = mxbai.stores.search( query="How to implement authentication?", store_identifiers=["docs", "knowledge-base"], top_k=5 ) for chunk in res.data: print(f"Score: {chunk.score:.4f}, File: {chunk.filename}") except AuthenticationError as e: print(f"Authentication failed: {e.message}") except RateLimitError as e: print(f"Rate limit exceeded: {e.message}") except Exception as e: print(f"Unexpected error: {e}") ``` Python (async): ```python import asyncio from mixedbread import ( AsyncMixedbread, AuthenticationError, RateLimitError ) mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") async def main(): try: res = await mxbai.stores.search( query="How to implement authentication?", store_identifiers=["docs", "knowledge-base"], top_k=5 ) for chunk in res.data: print(f"Score: {chunk.score:.4f}, File: {chunk.filename}") except AuthenticationError as e: print(f"Authentication failed: {e.message}") except RateLimitError as e: print(f"Rate limit exceeded: {e.message}") except Exception as e: print(f"Unexpected error: {e}") if __name__ == "__main__": asyncio.run(main()) ``` TypeScript: ```ts import { Mixedbread, AuthenticationError, RateLimitError, } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); try { const res = await mxbai.stores.search({ query: "How to implement authentication?", store_identifiers: ["docs", "knowledge-base"], top_k: 5, }); for (const chunk of res.data) { console.log( `Score: ${chunk.score.toFixed(4)}, File: ${chunk.filename}`, ); } } catch (error) { if (error instanceof AuthenticationError) { console.error(`Authentication failed: ${error.message}`); } else if (error instanceof RateLimitError) { console.error(`Rate limit exceeded: ${error.message}`); } else { console.error(`Unexpected error: ${error}`); } } ``` # Introduction URL: https://www.mixedbread.com/api-reference The Mixedbread API enables powerful semantic search and document intelligence capabilities for AI-powered applications. ## Overview Welcome to the Mixedbread API Reference. This comprehensive guide provides detailed technical specifications for all our endpoints, including request/response schemas, code examples, and best practices. ### Base URL All API requests should be made to: ``` https://api.mixedbread.com/ ``` ### Creating Your API Key 1. Log in to your [Mixedbread account](https://platform.mixedbread.com/platform?next=api-keys) 2. Create a new API key 3. Copy your key and save it to your `.env` file ### Authentication Include your API key in the `Authorization` header of all requests: ```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", }' ``` ### SDK Quick Starts For a seamless integration experience, use our official SDKs: - **[Python](https://www.mixedbread.com/api-reference/sdks/python)**: Get started with our Python SDK. - **[TypeScript](https://www.mixedbread.com/api-reference/sdks/typescript)**: Get started with our TypeScript SDK. ## Need Help? - Check our [documentation](https://www.mixedbread.com/docs) for more information - Contact [support@mixedbread.com](mailto:support@mixedbread.com) for assistance # Vercel URL: https://www.mixedbread.com/api-reference/integrations/vercel The Mixedbread Vercel integration makes it easy to add our powerful Search API to your Vercel projects. The Mixedbread Vercel integration makes it easy to add our powerful Search API to your Vercel projects. It allows you to create organizations and Stores directly from Vercel and connect them with your projects. You can start with a [template](https://vercel.com/templates/next.js/mixedbread-starter), connect the environment variables and manage everything from the Vercel dashboard. ## How It Works The Mixedbread Vercel integration provides a streamlined workflow for working with our Search API: - **Team Installation** → Creates a Mixedbread organization linked to your Vercel account - **Install Products** → Each product creates a Store in your organization - **Connect Projects** → Link Stores to Vercel projects with automatic environment variable injection - **Unified Billing** → All usage is billed through your Vercel account ## Getting Started ### Install the Integration 1. Navigate to the [Mixedbread Integration](https://vercel.com/marketplace/mixedbread) 2. Click **Install** and choose your team or personal account scope 3. Accept the permissions to allow Mixedbread to manage resources The installation flow includes the creation of your Mixedbread organization and your first Store. You are granted the **owner** role with full access to manage Stores and team members. ## Create a Store ### Install Your First Product 1. From the Mixedbread integration page in Vercel, click **Install** to add a new product 2. Configure your Store: - **Name** - A descriptive identifier for your Store - **Description** - Optional context about the Store's purpose (optional) - **Public Read** - Enable public read access without authentication (optional) 3. Confirm to provision the Store The product creator is granted the **admin** role in the Mixedbread organization if they are not the **owner**. The Store is immediately available for connecting to projects. ### Add More Stores You can create multiple Stores from the Vercel integration page to organize different use cases, environments, or applications. Each Store can be independently configured and connected to different projects. > **Note** > > Stores for Vercel-managed organizations can only be created through the Vercel integration page, not from the Mixedbread dashboard. ## Connect to Projects ### Link Stores to Vercel Projects 1. In the Mixedbread integration page, click **Connect Project** 2. Select one or more Vercel projects to link 3. Environment variables are automatically added to your selected projects: - `MXBAI_API_KEY` - Authentication key for API requests - `MXBAI_STORE_ID` - The unique identifier for your Store 4. Redeploy your projects to access the new environment variables ### Multi-Project Connections A single Store can be connected to multiple Vercel projects, making it ideal for: - Sharing data between staging and production environments - Connecting multiple microservices to the same knowledge base - Providing consistent search across different applications Each connected project receives the same environment variables for seamless access. ## Managing the Integration ### Team Permissions Permissions are automatically synchronized between Vercel and Mixedbread: - **Integration Creator** → Mixedbread Organization Owner - **Resource Creators** → Mixedbread Organization Admins Team members can access and manage Stores based on their assigned roles in the Mixedbread organization. ### Monitor Usage and Billing - **Billing**: All usage is billed through your Vercel account - **Usage Metrics**: View detailed usage statistics and analytics in both [Vercel dashboard](https://vercel.com/dashboard) and [Mixedbread dashboard](https://www.platform.mixedbread.com/platform?next=settings/billing/invoices) - **Cost Tracking**: Monitor consumption across all stores and projects in the Vercel billing dashboard ## Uninstalling the Integration When you uninstall the Mixedbread integration from Vercel: - The associated Mixedbread organization is deleted - All Stores in the organization become inaccessible - Connected applications will fail API requests **Before uninstalling**, ensure no production applications depend on the Stores and remove environment variables from your projects if necessary. # Pagination URL: https://www.mixedbread.com/api-reference/pagination Understanding cursor-based pagination across Mixedbread API endpoints. Learn how to navigate through large result sets efficiently using cursors, handle pagination parameters, and implement robust pagination logic. ## Overview Mixedbread API uses cursor-based pagination for endpoints that return large result sets. This approach provides consistent performance regardless of dataset size and ensures reliable pagination even when data is being modified. ## Supported Endpoints Cursor-based pagination is used for: - **[List Stores](https://www.mixedbread.com/api-reference/endpoints/stores/manage/list-stores)** - **[List Files](https://www.mixedbread.com/api-reference/endpoints/files/list-files)** ## Pagination Parameters ### Request Parameters Include these query parameters in your requests: | Parameter | Type | Description | Default | |-----------|------|-------------|---------| | `before` | string | Cursor for pagination. Returns items before this cursor. | - | | `after` | string | Cursor for pagination. Returns items after this cursor. | - | | `limit` | integer | Maximum number of items to return (1-100). | 20 | **Important Notes:** - Use either `before` OR `after`, not both - Cursors are opaque strings - don't parse or modify them - Always include `limit` to control result size ### Response Format All paginated responses include: ```json { "data": [...], "pagination": { "first_cursor": "eyJpZCI6InZzXzEyMyJ9", "last_cursor": "eyJpZCI6InZzXzQ1NiJ9", "has_more": true } } ``` | Field | Type | Description | |-------|------|-------------| | `data` | array | The actual results for the current page | | `first_cursor` | string | Cursor pointing to the first item in current page | | `last_cursor` | string | Cursor pointing to the last item in current page | | `has_more` | boolean | Whether more results are available | ## Navigation Patterns ### Forward Pagination Start with no cursor to get the first page: ```bash GET /v1/stores?limit=10 ``` Continue with `last_cursor` from the previous response: ```bash GET /v1/stores?after=eyJpZCI6InZzXzQ1NiJ9&limit=10 ``` ### Backward Pagination Use `first_cursor` with `before` parameter: ```bash GET /v1/stores?before=eyJpZCI6InZzXzEyMyJ9&limit=10 ``` > **Diagram**: Cursor pagination demo: 13 stores listed with a demo limit of 4 (the API default is 20). The first request, GET /v1/stores?limit=4, sends no cursor and returns the first 4 stores with a pagination object whose first_cursor and last_cursor point at the first and last store on the page, and has_more: true. Next sends GET /v1/stores?limit=4&after={last_cursor} for the following 4 stores; Previous sends GET /v1/stores?limit=4&before={first_cursor} for the 4 before them. Each request uses only one of before or after, and cursors are opaque strings copied from the previous response. The fourth page holds only the last store and returns has_more: false, so there is no next request. has_more follows the direction of the request: after a before request it tells whether more stores exist before the page. # Rate Limiting URL: https://www.mixedbread.com/api-reference/rate-limits Learn about API rate limits based on operation types. Understand token bucket policies, burst capacity, and how to handle rate limiting responses effectively. ## Overview Rate limits are applied per operation type, with each having its own limit and burst capacity. Exceeding these limits will result in a `429 Too Many Requests` response. If you consistently need higher limits, please [contact us](https://www.mixedbread.com/contact). ## Rate Limits by Operation Type We apply different rate limits based on the type of operation you're performing: | Operation Type | Limit | Burst Capacity | Window | |----------------|-------------------|----------------|---------| | **Read** | 1,200 | 1,000 | 1 minute | | **List** | 600 | 200 | 1 minute | | **Write** | 360 | 120 | 1 minute | | **Update** | 480 | 160 | 1 minute | | **Delete** | 240 | 80 | 1 minute | ## Handling Rate Limits When you hit a rate limit: 1. You'll receive a `429 Too Many Requests` response 2. The response will include a `Retry-After` header 3. Wait for the specified time before retrying Example error response: ```json { "type": "too_many_requests_error", "url": "https://www.mixedbread.com/api-reference", "message": "Rate limit exceeded. Please try again later.", "details": { "retry_after": 60, "limit": "1200", "remaining": "0", "reset": "1730000000" } } ``` # Python URL: https://www.mixedbread.com/api-reference/sdks/python Learn how to install and configure Mixedbread's Python SDK for interacting with our API services. ## Introduction The Mixedbread Python SDK provides a convenient interface for accessing our API with built-in error handling, retries, and type safety. ## Installation ```bash title="Installation" pip install mixedbread ``` ## Quick Start Get started with a simple example: ```python title="Basic Usage" from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") store = mxbai.stores.create( name='my-knowledge-base', description='Product documentation and guides' ) print(f"Created store: {store.id}") ``` ## Configuration The `Mixedbread` constructor accepts the following parameters: ```python class Mixedbread: def __init__( self, api_key: str, max_retries: int = 3, timeout: float = 30.0, base_url: str = "https://api.mixedbread.com" ): # ... ``` - `api_key`: Your Mixedbread API key (required) - `max_retries`: Maximum number of retries for failed requests (default: 3) - `timeout`: Request timeout in seconds (default: 30.0) - `base_url`: Custom base URL for API requests (default: https://api.mixedbread.com) ## Async Support For async applications, use the async client: ```python title="Async client" from mixedbread import AsyncMixedbread async_mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") ``` ## Error Handling Use try/except blocks to handle errors: ```python from mixedbread.exceptions import MixedbreadError, RateLimitError try: results = mxbai.stores.search( query="How does authentication work?", store_identifiers=["your-store-id"], top_k=5, search_options={ 'return_metadata': True, 'rerank': True } ) for chunk in results.data: print(chunk) except RateLimitError as e: print(f"Rate limit exceeded. Retry after {e.retry_after} seconds") except MixedbreadError as e: print(f"API Error: {e}") print(f"Status Code: {e.status_code}") except Exception as e: print(f"Unexpected error: {e}") ``` ## Environment Setup ### Using Environment Variables ```bash title="Environment Configuration" export MXBAI_API_KEY="your_api_key_here" export MXBAI_BASE_URL="https://api.mixedbread.com" ``` ```python title="Environment-based Initialization" from mixedbread import Mixedbread mxbai = Mixedbread( api_key=os.getenv("MXBAI_API_KEY"), base_url=os.getenv("MXBAI_BASE_URL") ) ``` # TypeScript URL: https://www.mixedbread.com/api-reference/sdks/typescript Learn how to install and configure Mixedbread's TypeScript SDK for interacting with our API services. ## Introduction The Mixedbread TypeScript SDK provides a convenient interface for accessing our API with built-in error handling, retries, and type safety. ## Installation ```npm title="Installation" npm install @mixedbread/sdk ``` ## Quick Start Get started with a simple example: ```typescript title="Basic Usage" import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: process.env.MXBAI_API_KEY!, }); const store = await mxbai.stores.create({ name: 'my-knowledge-base', description: 'Product documentation and guides' }); console.log(`Created store: ${store.id}`); ``` ## Configuration The `Mixedbread` constructor accepts the following options: ```typescript interface MixedbreadOptions { apiKey: string; maxRetries?: number; timeout?: number; baseURL?: string; } ``` - `apiKey`: Your Mixedbread API key (required) - `maxRetries`: Maximum number of retries for failed requests (default: 3) - `timeout`: Request timeout in milliseconds (default: 30000) - `baseURL`: Custom base URL for API requests (default: https://api.mixedbread.com) ## Error Handling Use try/catch blocks to handle errors: ```typescript import { MixedbreadError, RateLimitError } from "@mixedbread/sdk"; try { const results = await mxbai.stores.search({ query: "How does authentication work?", store_identifiers: ["your-store-id"], top_k: 5, search_options: { return_metadata: true, rerank: true } }); for (const chunk of results.data) { console.log(chunk); } } catch (err) { if (err instanceof RateLimitError) { console.error(`Rate limit exceeded. Retry after ${err.retryAfter} seconds`); } else if (err instanceof MixedbreadError) { console.error(`API Error: ${err.message}`); console.error(`Status Code: ${err.statusCode}`); } else { console.error(`Unexpected error: ${err}`); } } ``` ## Environment Setup ### Using Environment Variables ```bash title="Environment Configuration" export MXBAI_API_KEY="your_api_key_here" export MXBAI_BASE_URL="https://api.mixedbread.com" ``` ```typescript title="Environment-based Configuration" import { Mixedbread } from "@mixedbread/sdk"; if (!process.env.MXBAI_API_KEY) { throw new Error("MXBAI_API_KEY environment variable is required"); } if (!process.env.MXBAI_BASE_URL) { throw new Error("MXBAI_BASE_URL environment variable is required"); } const mxbai = new Mixedbread({ apiKey: process.env.MXBAI_API_KEY, baseURL: process.env.MXBAI_BASE_URL, }); ``` # Configuration URL: https://www.mixedbread.com/cli/configuration Manage CLI settings, defaults, and aliases to customize your mxbai experience. The mxbai CLI provides flexible configuration management to set defaults, store credentials, and create aliases for common operations. Configuration is stored in platform-specific locations and can be managed using the `mxbai config` commands. ## Configuration File Location ```text tab="macOS" ~/Library/Application Support/mixedbread/config.json ``` ```text tab="Linux" ~/.config/mixedbread/config.json or $XDG_CONFIG_HOME/mixedbread/config.json ``` ```text tab="Windows" %APPDATA%\mixedbread\config.json ``` ### Custom location Override the default location by setting the `MXBAI_CONFIG_PATH` environment variable: ```bash export MXBAI_CONFIG_PATH=/path/to/your/config.json ``` ## Configuration Precedence When using the CLI, configuration values are resolved in the following order (highest to lowest priority): 1. **Command-line flags** - Direct CLI options (e.g., `--strategy high_quality`) 2. **Environment variables** - System environment settings (e.g., `MXBAI_API_KEY`, `MXBAI_BASE_URL`, `MXBAI_CONFIG_PATH`, `MXBAI_DEBUG`) 3. **Manifest entry** - File-specific settings in manifest files (only applies to manifest uploads) 4. **Manifest defaults** - Default settings in manifest files (only applies to manifest uploads) 5. **Config file** - User configuration file settings 6. **Built-in defaults** - CLI default values This allows flexible configuration while maintaining predictable behavior. For example: - If you set `defaults.upload.strategy = "high_quality"` in your config file, but use `--strategy fast` on the command line, the command-line flag takes precedence. - When using manifest files, individual file settings override the manifest defaults, which in turn override your config file settings. ## Add API Key ### Command ```bash mxbai config keys add [name] ``` ### Options - `` - The API key to add (required, must start with `mxb_`) - `[name]` - Optional name for the API key (if not provided, you will be prompted) ### Examples ```bash # Add API key with a name mxbai config keys add mxb_xxxxx work # Add API key without name (will prompt for name) mxbai config keys add mxb_xxxxx ``` ## List API Keys ### Command ```bash mxbai config keys list ``` ### Examples ```bash # List all stored API keys mxbai config keys list # Output: # work # * personal (default) ``` ## Remove API Key ### Command ```bash mxbai config keys remove ``` ### Options - `` - The name of the API key to remove (required) - `--yes`, `-y` - Skip confirmation prompt ### Examples ```bash # Remove an API key by name mxbai config keys remove personal # Remove an API key by name without confirmation mxbai config keys remove personal --yes ``` ## Set Default API Key ### Command ```bash mxbai config keys set-default ``` ### Options - `` - The name of the API key to set as default (required) ### Examples ```bash # Set default API key mxbai config keys set-default work # Use a specific saved API key for a command (overrides default) mxbai store upload "My Docs" "*.md" --saved-key personal mxbai store search "Knowledge Base" "query" --saved-key work # Or use an actual API key directly mxbai store upload "My Docs" "*.md" --api-key mxb_xxxxx ``` ## Set Configuration Values ### Command ```bash mxbai config set ``` ### Examples ```bash # Set upload defaults mxbai config set defaults.upload.strategy high_quality mxbai config set defaults.upload.parallel 10 # Deprecated - contextualization is now configured at the store level # mxbai config set defaults.upload.contextualization true # Set search defaults mxbai config set defaults.search.top_k 20 mxbai config set defaults.search.rerank true # Create store aliases mxbai config set aliases.docs "My Documentation" mxbai config set aliases.kb "Knowledge Base" ``` ## Get Configuration Values ### Command ```bash mxbai config get [key] ``` ### Examples ```bash # View all configuration mxbai config get # View specific configuration section mxbai config get defaults.upload # View specific setting mxbai config get api_key ``` ## Configuration Options ### API Authentication The CLI supports multiple API keys for different organizations or environments. Use the `keys` subcommand to manage them: ```bash mxbai config keys add mxb_xxxxx ``` - Required format: Must start with `mxb_` - Security: Stored locally in your user directory - Multi-key support: Add multiple keys with names for easy switching ### Upload Defaults Configure default options for file uploads: #### Processing Strategy Choose between fast processing for speed or high quality processing for better search results. - Config key: `defaults.upload.strategy` - Default: `fast` - Valid values: `fast`, `high_quality` ```bash mxbai config set defaults.upload.strategy high_quality ``` #### Contextualization > **Note** > > **Deprecated**: Contextualization is now configured at the store level using `mxbai store create --contextualization`, not per-upload. This setting is ignored by the CLI and will be removed in a future version. Include metadata in chunk embeddings to improve search relevance. - Config key: `defaults.upload.contextualization` - Default: `false` - Valid values: `true`, `false` ```bash # Deprecated - this setting is now ignored mxbai config set defaults.upload.contextualization true ``` #### Parallel Uploads Control how many files are uploaded simultaneously to optimize for your network and system resources. - Config key: `defaults.upload.parallel` - Default: `100` - Valid range: `1` to `200` ```bash mxbai config set defaults.upload.parallel 10 ``` ### Search Defaults Configure default search behavior: #### Number of Results Set how many search results to return by default when searching your stores. - Config key: `defaults.search.top_k` - Default: `10` - Valid range: `1` to `100` ```bash mxbai config set defaults.search.top_k 20 ``` #### Result Reranking Enable AI-powered reranking to reorder search results based on relevance, improving the quality of top results. - Config key: `defaults.search.rerank` - Default: `false` - Valid values: `true`, `false` ```bash mxbai config set defaults.search.rerank true ``` ### Store Aliases Create shortcuts for frequently used stores: ```bash # Create aliases for long store names mxbai config set aliases.docs "My Documentation Store" mxbai config set aliases.kb "Company Knowledge Base" mxbai config set aliases.proj "Project Files" ``` Then use aliases in commands: ```bash # Instead of: mxbai store upload "My Documentation Store" "*.md" mxbai store upload docs "*.md" # Instead of: mxbai store search "Company Knowledge Base" "how to get started" mxbai store search kb "how to get started" ``` ## Default Configuration When no configuration is set, the CLI uses these default values: ```json { "api_keys": {}, "defaults": { "upload": { "strategy": "fast", "contextualization": false, // Deprecated - now configured at store level "parallel": 100 }, "search": { "top_k": 10, "rerank": false }, "api_key": undefined }, "aliases": {} } ``` ## Configuration File Structure After customization, your configuration file might look like: ```json { "api_keys": { "work": "mxb_xxxxx", "personal": "mxb_xxxxx" }, "defaults": { "upload": { "strategy": "high_quality", "contextualization": true, // Deprecated - now configured at store level "parallel": 10 }, "search": { "top_k": 20, "rerank": true }, "api_key": "work" }, "aliases": { "docs": "My Documentation Store", "kb": "Company Knowledge Base" } } ``` ## Common Configuration Examples ### Development Setup Optimize for speed during development: ```bash # Fast uploads for quick iterations mxbai config set defaults.upload.strategy fast mxbai config set defaults.upload.parallel 5 # More search results for exploration mxbai config set defaults.search.top_k 15 # Create development aliases mxbai config set aliases.dev "Development Docs" mxbai config set aliases.test "Test Data" ``` ### Production Setup Optimize for quality and accuracy: ```bash # High quality processing for better results mxbai config set defaults.upload.strategy high_quality # Note: contextualization is now configured at the store level, not per-upload # mxbai config set defaults.upload.contextualization true # Balanced search configuration mxbai config set defaults.search.top_k 10 mxbai config set defaults.search.rerank true # Production aliases mxbai config set aliases.prod "Production Knowledge Base" mxbai config set aliases.docs "Official Documentation" ``` ### CI/CD Setup Configure for automated environments: ```bash # Store API key (usually from environment variable) mxbai config keys add $MXBAI_API_KEY ci # Fast processing for CI pipelines mxbai config set defaults.upload.strategy fast mxbai config set defaults.upload.parallel 10 ``` ## Debugging Enable debug output to troubleshoot issues: ```bash # Via command flag mxbai store list --debug # Via environment variable export MXBAI_DEBUG=true mxbai store list # Debug shows: # - Configuration resolution # - Error stack traces ``` # File Management URL: https://www.mixedbread.com/cli/files Upload files and manage files within stores. Files serve as the foundation for all content processing workflows in Mixedbread. They provide secure upload, storage, and retrieval of documents with support for various file types including PDFs, images, and structured data. Manage files within your stores with version management, metadata support, and unique ID referencing. ## Upload Files ### Command ```bash mxbai store upload [options] ``` ### Options - `--strategy fast|high_quality` - Processing strategy (default: `fast`) - `--contextualization` - **Deprecated**: Now configured at store level using `mxbai store create --contextualization`. This flag is ignored and will be removed in a future version. - `--metadata ` - JSON metadata for uploaded files - `--dry-run` - Preview what would be uploaded without uploading - `--parallel ` - Number of concurrent uploads (default: `100`, range: `1` - `200`) - `--unique` - Update existing files instead of creating duplicates - `--manifest ` - Upload using manifest file - `--multipart-threshold ` - File size threshold in MB to trigger multipart upload - `--multipart-part-size ` - Size of each part in MB for multipart upload - `--multipart-concurrency ` - Number of concurrent part uploads for multipart upload ### Manifest File Format The manifest file allows you to define complex upload configurations with different settings for different file patterns. Both JSON (`.json`) and YAML (`.yaml` or `.yml`) formats are supported. **JSON format:** ```json { "version": "1.0", "defaults": { "strategy": "fast", // "contextualization": false, // Deprecated - now configured at store level "metadata": { "project": "my-project" } }, "files": [ { "path": "docs/**/*.md", "metadata": { "category": "documentation" } }, { "path": "README.md", "strategy": "high_quality", // contextualization is deprecated - configure at store level instead "metadata": { "importance": "high" } } ] } ``` **YAML format:** ```yaml version: "1.0" defaults: strategy: fast # contextualization: false # Deprecated - now configured at store level metadata: project: my-project files: - path: "docs/**/*.md" metadata: category: documentation - path: README.md strategy: high_quality # contextualization is deprecated - configure at store level instead metadata: importance: high ``` **Manifest properties:** - `version` - Manifest format version (currently "1.0") - `defaults` - Default settings applied to all files - `strategy` - Default processing strategy - `contextualization` - *(Deprecated)* Include metadata in chunk embeddings to improve search relevance - now configured at store level - `metadata` - Default metadata for all files - `files` - Array of file upload configurations - `path` - Glob pattern for files to upload - `strategy` - Specific strategy for this pattern - `contextualization` - *(Deprecated)* Contextualization for this pattern - now configured at store level - `metadata` - Additional metadata for this pattern (merged with defaults) ### Examples ```bash # Upload markdown files mxbai store upload "my-knowledge-base" "*.md" # Upload multiple file types mxbai store upload "my-knowledge-base" "*.md" "docs/**/*.pdf" # Upload with high quality processing mxbai store upload "my-knowledge-base" "*.pdf" --strategy high_quality # Deprecated: contextualization is now configured at the store level # mxbai store upload "my-knowledge-base" "*.md" --contextualization # Upload with metadata mxbai store upload "my-knowledge-base" "*.md" --metadata '{"category": "docs"}' # Dry run to preview upload mxbai store upload "my-knowledge-base" "*.md" --dry-run # Upload with manifest file (JSON or YAML) mxbai store upload "my-knowledge-base" --manifest upload-manifest.json mxbai store upload "my-knowledge-base" --manifest upload-manifest.yaml # Upload large files with multipart upload mxbai store upload "my-knowledge-base" "*.pdf" \ --multipart-threshold 50 \ --multipart-part-size 25 \ --multipart-concurrency 10 ``` ## Upload Summary Information The upload command displays strategy information in the summary after completion: ```bash ✓ 5 files uploaded successfully Strategy: fast Total size: 25.3 KB ``` For manifest uploads, configuration is shown beside each file: ```bash ✓ docs/api.md (15.2 KB) [fast] ✓ README.md (8.5 KB) [high_quality] ✓ guide.md (1.6 KB) [fast] ``` This allows you to see exactly which strategy was applied to each file, making it easy to verify that your manifest configuration is working as expected. ## List Files ### Command ```bash mxbai store files list [options] ``` **Alias:** `mxbai store files ls ` ### Options - `--status ` - Filter by status: pending, in_progress, cancelled, completed, failed - `--limit ` - Limit number of results ### Examples ```bash # List all files in store mxbai store files list "my-knowledge-base" # List using alias mxbai store files ls "my-knowledge-base" # List only completed files mxbai store files list "my-knowledge-base" --status completed # List with limit mxbai store files list "my-knowledge-base" --limit 50 # List failed files for troubleshooting mxbai store files list "my-knowledge-base" --status failed ``` ## Get File Details ### Command ```bash mxbai store files get ``` ### Options None ### Examples ```bash # Get details of a specific file mxbai store files get "my-knowledge-base" "f47ac10b-58cc-4372-a567-0e02b2c3d479" # Get file details using store ID mxbai store files get "my-knowledge-base" "b2c3d4e5-f6a7-8901-bcde-f23456789012" ``` ## Delete File ### Command ```bash mxbai store files delete [options] ``` **Alias:** `mxbai store files rm ` ### Options - `--yes`, `-y` - Skip confirmation prompt ### Examples ```bash # Delete file with confirmation mxbai store files delete "my-knowledge-base" "f47ac10b-58cc-4372-a567-0e02b2c3d479" # Delete file without confirmation mxbai store files delete "my-knowledge-base" "f47ac10b-58cc-4372-a567-0e02b2c3d479" --yes # Delete using alias mxbai store files rm "my-knowledge-base" "f47ac10b-58cc-4372-a567-0e02b2c3d479" --yes # Delete from store by ID mxbai store files delete "my-knowledge-base" "b2c3d4e5-f6a7-8901-bcde-f23456789012" --yes ``` # Introduction URL: https://www.mixedbread.com/cli The mxbai CLI provides a powerful command-line interface for managing Mixedbread stores and files directly from your terminal. ## Overview The mxbai CLI is a comprehensive tool for managing stores, uploading documents, and performing AI-powered search and question-answering operations. Built on top of the Mixedbread SDK, it provides an efficient command-line interface for all core platform features. > **Note** > > New to Mixedbread? Check out our [API documentation](https://www.mixedbread.com/api-reference) to understand the underlying services that power the CLI. ## Key Features - **[Store Management](https://www.mixedbread.com/cli/stores)**: Create, list, update, and manage your stores with comprehensive control. - **[File Upload & Processing](https://www.mixedbread.com/cli/files)**: Upload files with intelligent processing strategies, metadata, and batch operations. - **[Semantic Search](https://www.mixedbread.com/cli/search)**: Search through your stores using natural language queries with advanced filtering. - **[Question Answering](https://www.mixedbread.com/cli/qa)**: Ask questions and get AI-powered answers based on your store content. - **[Intelligent Sync](https://www.mixedbread.com/cli/sync)**: Sync files with Git-based change detection and intelligent processing strategies. - **[Shell Completion](https://www.mixedbread.com/cli/installation#shell-completion)**: Set up tab completion for commands and subcommands to improve your CLI experience. ## Quick Start ### 1. Install the CLI ```npm npm install -g @mixedbread/cli ``` ### 2. Set your API key ```bash # Option 1: Environment variable export MXBAI_API_KEY=mxb_xxxxx # Option 2: Config file (persistent) mxbai config keys add mxb_xxxxx ``` ### 3. Install shell completion (optional but recommended) ```bash mxbai completion install ``` ### 4. Create a store ```bash mxbai store create "my-knowledge-base" ``` ### 5. Upload files ```bash # Basic upload mxbai store upload "my-knowledge-base" "*.md" "docs/**/*.pdf" # Upload with high-quality processing mxbai store upload "my-knowledge-base" "**/*.md" --strategy high_quality ``` ### 6. Search your content ```bash mxbai store search "my-knowledge-base" "how to get started" ``` ## Command Structure The mxbai CLI is organized around store operations using the `store` subcommand: ### Configuration Management - `mxbai config set ` - Set configuration values - `mxbai config get [key]` - Get configuration values - `mxbai config keys add [name]` - Add a new API key - `mxbai config keys list` - List all API keys - `mxbai config keys remove ` - Remove an API key - `mxbai config keys set-default ` - Set the default API key ### Shell Completion - `mxbai completion install` - Install shell completion - `mxbai completion uninstall` - Uninstall shell completion - `mxbai completion refresh` - Refresh completion cache for store names ### Store Management - `mxbai store list` - List all stores - `mxbai store create ` - Create a new store - `mxbai store get ` - Get store details - `mxbai store update ` - Update store settings - `mxbai store delete ` - Delete a store ### File Operations - `mxbai store upload ` - Upload files - `mxbai store files list ` - List files in store - `mxbai store files get ` - Get file details - `mxbai store files delete ` - Delete a file ### Search & Query - `mxbai store search ` - Search store - `mxbai store qa ` - Ask questions about content ### Intelligent Sync - `mxbai store sync ` - Intelligent sync with change detection ## Global Options All commands support these global options: - `--api-key ` - Actual API key for authentication - `--saved-key ` - Name of saved API key from config - `--base-url ` - Custom API base URL - `--format ` - Output format: `table`, `json`, or `csv` (default: `table`) - `--debug` - Enable debug output (equivalent to `MXBAI_DEBUG=true`) - `--help` - Show help information for commands ## Environment Variables The CLI supports the following environment variables: - `MXBAI_API_KEY` - API key for authentication (must start with `mxb_`) - `MXBAI_BASE_URL` - Custom API base URL - `MXBAI_DEBUG` - Enable debug output (set to `true` or `1`) - `MXBAI_CONFIG_PATH` - Override default config file location ## Authentication The CLI looks for your API key in this order: 1. `--api-key` or `--saved-key` command line flags 2. `MXBAI_API_KEY` environment variable 3. Default API key from config file (platform-specific location): - Linux/Unix: `~/.config/mixedbread/config.json` (or `$XDG_CONFIG_HOME/mixedbread/config.json`) - macOS: `~/Library/Application Support/mixedbread/config.json` - Windows: `%APPDATA%\mixedbread\config.json` - Custom: Set `MXBAI_CONFIG_PATH` environment variable to override ### Multi-Organization Support The CLI supports multiple API keys for different organizations or environments: ```bash # Add API keys with descriptive names mxbai config keys add mxb_xxxxx work mxbai config keys add mxb_xxxxx personal # Use a specific saved API key for a command mxbai store upload "My Docs" "*.md" --saved-key work mxbai store search "Knowledge Base" "query" --saved-key personal # Or use an actual API key directly mxbai store upload "My Docs" "*.md" --api-key mxb_xxxxx # The last added key becomes default automatically # Or explicitly set a default mxbai config keys set-default personal ``` ## Getting Help Use the `--help` flag to get detailed information about any command: ```bash # General help mxbai --help # Help for store commands mxbai store --help # Help for specific commands mxbai store create --help mxbai store upload --help mxbai store search --help ``` # Installation & Setup URL: https://www.mixedbread.com/cli/installation Install the mxbai CLI on your system and get started with Mixedbread's AI services. ## Prerequisites Before installing the mxbai CLI, ensure you have: - **Node.js** version 20.0 or higher - A package manager - A Mixedbread API key ([get one here](https://platform.mixedbread.com/platform?next=/api-keys)) ## Installation Methods ### Global Installation (Recommended) Install the CLI globally to use it from any directory: ```npm npm install -g @mixedbread/cli ``` ### Local Installation For project-specific installations: ```npm npm install --save-dev @mixedbread/cli ``` When installed locally, use `npx mxbai` or add scripts to your `package.json`: ```json { "scripts": { "mxbai": "mxbai" } } ``` ## Verify Installation After installation, verify the CLI is working: ```bash mxbai --version ``` ## Upgrading the CLI ### Global Upgrade To upgrade a globally installed CLI to the latest version: ```npm npm install -g @mixedbread/cli@latest ``` ### Local Upgrade For project-specific installations: ```npm npm install --save-dev @mixedbread/cli@latest ``` ## Authentication To use the CLI, you need a Mixedbread API key. The CLI checks for authentication in this order: 1. **Command line flag**: `--api-key mxb_xxxxx` 2. **Environment variable**: `export MXBAI_API_KEY=mxb_xxxxx` 3. **Configuration file**: `mxbai config set api_key mxb_xxxxx` ### Quick Setup The easiest way to get started is with an environment variable: ```bash export MXBAI_API_KEY=mxb_xxxxx ``` For persistent configuration across sessions, use the config file: ```bash mxbai config set api_key mxb_xxxxx ``` Learn more about configuration options in the [Configuration Guide](https://www.mixedbread.com/cli/configuration). ## Shell Completion The CLI supports intelligent tab completion for commands, subcommands, and **store names**. ### Installation ```bash # Install completion (auto-detects your shell) mxbai completion install # Install completion for a specific shell mxbai completion install --shell bash mxbai completion install --shell zsh mxbai completion install --shell fish mxbai completion install --shell pwsh ``` **Supported shells:** bash, zsh, fish, pwsh (PowerShell) After installation, restart your shell or reload your shell configuration: - **bash**: `source ~/.bashrc` or restart terminal - **zsh**: `source ~/.zshrc` or restart terminal - **fish**: Completion is ready to use (fish auto-loads completions) - **pwsh**: `. $PROFILE` or restart terminal ### Dynamic Store Name Completion The CLI provides intelligent tab completion for store names in commands: ```bash # Tab completion shows your store names mxbai store get [TAB] # Shows: store1 store2 my-docs ... mxbai store delete [TAB] # Shows: store1 store2 my-docs ... mxbai store sync [TAB] # Shows: store1 store2 my-docs ... mxbai store upload [TAB] # Shows: store1 store2 my-docs ... # Also works with files subcommands mxbai store files list [TAB] # Shows: store1 store2 my-docs ... ``` **How it works:** - Store names are cached locally for instant completion (no API latency) - Cache updates automatically when you create, update, delete, or list stores - Supports multiple API keys - completions show stores for your current default key - Manual refresh available: `mxbai completion refresh` **Cache management:** - Caches up to 50 most recent store names per API key - Cache location follows your config directory: - Linux/Unix: `~/.config/mixedbread/completion-cache.json` - macOS: `~/Library/Application Support/mixedbread/completion-cache.json` - Windows: `%APPDATA%\mixedbread\completion-cache.json` ### Managing Completion ```bash # Remove completion mxbai completion uninstall # Refresh store name cache mxbai completion refresh ``` # Question Answering URL: https://www.mixedbread.com/cli/qa Ask questions about content in your stores and get AI-powered answers. Get AI-powered answers to questions about your store content. The system searches through your documents, retrieves the most relevant chunks, and generates context-aware responses with source file metadata for transparency. Perfect for building Q&A systems and knowledge bases from your document collections. ## Command ```bash mxbai store qa [options] ``` ## Options - `--top-k ` - Number of context chunks to use (default: `10`) - `--threshold ` - Minimum relevance score for context chunks - `--return-metadata` - Include source file metadata in the response **Note:** Default values for `--top-k` can be configured using `mxbai config`. See the [Configuration Guide](https://www.mixedbread.com/cli/configuration#search-defaults) for details. ## Examples ```bash # Ask a basic question mxbai store qa "my-knowledge-base" "How do I configure authentication?" # Ask for more results mxbai store qa "my-knowledge-base" "What are the deployment steps?" --top-k 15 # Ask with relevance threshold mxbai store qa "my-knowledge-base" "What is the API rate limit?" --threshold 0.8 # Ask and include metadata in results mxbai store qa "my-knowledge-base" "How to handle errors?" --return-metadata # Combine options mxbai store qa "my-knowledge-base" "Best practices for security" --top-k 20 --return-metadata ``` # Search URL: https://www.mixedbread.com/cli/search Search through store content using natural language queries. Perform semantic search that understands meaning rather than just keywords. Uses advanced multimodal embedding models to find relevant content based on context and intent with sub-second response times. Search across text chunks within stores using natural language queries like "comfortable running shoes" to find "cushioned athletic sneakers". ## Command ```bash mxbai store search [options] ``` ## Options - `--top-k ` - Number of results to return (default: `10`, range: `1` - `100`) - `--threshold ` - Minimum similarity score (range: `0.0` - `1.0`) - `--return-metadata` - Include file metadata in results - `--rerank` - Enable result reranking for better relevance (default: `false`) - `--file-search` - Search files instead of chunks **Note:** Default values for `--top-k` and `--rerank` can be configured using `mxbai config`. See the [Configuration Guide](https://www.mixedbread.com/cli/configuration#search-defaults) for details. ## Examples ```bash # Basic search mxbai store search "my-knowledge-base" "how to get started" # Search with more results mxbai store search "my-knowledge-base" "authentication" --top-k 20 # Search with similarity threshold mxbai store search "my-knowledge-base" "configuration" --threshold 0.8 # Search and include metadata in results mxbai store search "my-knowledge-base" "deployment" --return-metadata # Search and rerank results mxbai store search "my-knowledge-base" "best practices" --rerank # Search showing text chunks mxbai store search "my-knowledge-base" "error handling" --file-search # Combine multiple options mxbai store search "my-knowledge-base" "API usage" --top-k 15 --rerank --return-metadata ``` # Store Management URL: https://www.mixedbread.com/cli/stores Create, list, get, update, and delete stores. Stores transform any data into AI-native search engines that understand meaning, not just keywords. They act as containers for your files, automatically generating embeddings and enabling advanced search capabilities. Use these commands to create, manage, and organize your stores. Learn more about stores in the [documentation](https://www.mixedbread.com/docs). ## List Stores ### Command ```bash mxbai store list [options] ``` ### Options - `--filter ` - Filter by name pattern - `--limit ` - Limit number of results ### Examples ```bash # List all stores mxbai store list # Filter stores by name mxbai store list --filter "docs" # Limit results mxbai store list --limit 5 ``` ## Create Store ### Command ```bash mxbai store create [options] ``` ### Arguments - `` - Name for the store (lowercase letters, numbers, periods, and hyphens only) ### Options - `--description ` - Description for the store - `--expires-after ` - Auto-delete after specified days - `--metadata ` - JSON metadata for the store - `--public [value]` - Make store publicly accessible (requestor pays for usage) - `--contextualization [fields]` - Include metadata in chunk embeddings to improve search relevance. Can be used as a flag to enable globally, or with comma-separated metadata field names for targeted contextualization (e.g., `--contextualization=title,author`). ### Examples ```bash # Create a basic store mxbai store create my-knowledge-base # Create with description mxbai store create my-knowledge-base --description "Project documentation" # Create with expiration mxbai store create temp-store --expires-after 30 # Create with metadata mxbai store create project-store --metadata '{"project": "web-app", "team": "engineering"}' # Create a public store mxbai store create my-public-store --public # Create with contextualization enabled mxbai store create my-knowledge-base --contextualization # Create with contextualization using specific metadata fields mxbai store create my-knowledge-base --contextualization=title,author,date ``` ## Get Store Details ### Command ```bash mxbai store get ``` ### Options None ### Examples ```bash # Get store by name mxbai store get "my-knowledge-base" # Get store by ID mxbai store get "my-knowledge-base" ``` ## Update Store ### Command ```bash mxbai store update [options] ``` ### Options - `--name ` - New name for the store (lowercase letters, numbers, periods, and hyphens only) - `--description ` - New description - `--expires-after ` - Update expiration - `--metadata ` - Update metadata - `--public [value]` - Make store publicly accessible (requestor pays for usage) ### Examples ```bash # Update description mxbai store update my-knowledge-base --description "Updated description" # Rename store mxbai store update old-name --name new-name # Update metadata mxbai store update my-store --metadata '{"version": "2.0"}' # Make store public mxbai store update my-store --public # Make store private mxbai store update my-store --public=false ``` ## Delete Store ### Command ```bash mxbai store delete [options] ``` **Alias:** `mxbai store rm ` ### Options - `--yes`, `-y` - Skip confirmation prompt ### Examples ```bash # Delete with confirmation prompt mxbai store delete "my-knowledge-base" # Delete without confirmation mxbai store delete "my-knowledge-base" --yes # Delete using alias mxbai store rm "my-knowledge-base" --yes # Delete by ID mxbai store delete "my-knowledge-base" --yes ``` # Sync URL: https://www.mixedbread.com/cli/sync Sync files with intelligent change detection using Git-based analysis. Intelligently sync files to your store with two methods of change detection: Git-based (fastest) and hash-based (most accurate). Only uploads files that have changed since the last sync, making it efficient for large document collections and perfect for CI/CD workflows. ## Command ```bash mxbai store sync [options] ``` ## Options - `--strategy ` - Processing strategy: `fast` or `high_quality` (default: `fast`) - `--contextualization` - **Deprecated**: Now configured at store level using `mxbai store create --contextualization`. This flag is ignored and will be removed in a future version. - `--from-git ` - Git reference for change detection (e.g., `HEAD~1`, `main`) - `--dry-run` - Preview changes without syncing - `--yes`, `-y` - Skip confirmation prompt - `--force`, `-f` - Force upload regardless of whether content has changed or not - `--metadata ` - JSON metadata to attach to synced files - `--parallel ` - Number of concurrent operations (default: `100`, range: `1` - `200`) ## Change Detection The sync command provides two methods of change detection: 1. **Git-based** (fast): Uses `git diff` to detect changes since a specific commit 2. **Hash-based** (accurate): Compares file hashes with stored metadata ## Examples ```bash # Sync with git-based detection mxbai store sync "my-knowledge-base" "docs/**" --from-git HEAD~1 # Sync with hash-based detection and custom parallel processing mxbai store sync "my-knowledge-base" "**/*.md" --parallel 10 # Sync with high-quality processing mxbai store sync "my-knowledge-base" "**/*.md" --strategy high_quality # Deprecated: contextualization is now configured at the store level # mxbai store sync "my-knowledge-base" "**/*.md" --strategy high_quality --contextualization # Dry run to preview changes mxbai store sync "my-knowledge-base" "docs/**/*.md" --dry-run # Skip confirmation prompt mxbai store sync "my-knowledge-base" "**/*.md" --yes # Force sync all files regardless of changes mxbai store sync "my-knowledge-base" "**/*.md" --force # Sync and set metadata mxbai store sync "my-knowledge-base" "docs/**" --metadata '{"updated": "2024-01-15"}' # Sync in CI/CD environment mxbai store sync "my-knowledge-base" "docs/**" --yes --from-git HEAD~1 ``` # Build an AI Agent with Memory URL: https://www.mixedbread.com/cookbook/agent-memory Build AI agents with infinite, searchable memory using Mixedbread Stores as a semantic file system. AI agents need persistent memory to maintain context across conversations, remember user preferences, and build knowledge over time. Traditional databases require exact queries, but agents think in concepts and semantics. {/* TODO: Add architecture diagram */} > **Figure**: Agent Memory In this cookbook, we build a **semantic file system** for AI agents on top of Mixedbread stores. The agent can write memories as files, organize them into virtual folders, and retrieve relevant context through natural language search - giving your agent infinite, searchable memory. ## Core: Semantic File System Mixedbread stores can function as a semantic file system where: - **Paths as IDs** - Use [`external_id`](https://www.mixedbread.com/docs/stores/store-files#external-id) to store and retrieve files by path (e.g., `/memories/user.md`) - **Folders are virtual** - Scope searches to "folders" with [prefix filters](https://www.mixedbread.com/docs/stores/metadata-filtering#comparison-operators) on path metadata - **Search is semantic** - Find memories using natural language with [store search](https://www.mixedbread.com/docs/stores/search#basic-search) ``` # Virtual folder view /memories/ user.md people/ alice.md # Stored as flat files with path-based IDs { external_id: "/memories/user.md", metadata: { path: "/memories/user.md" } } { external_id: "/memories/people/alice.md", metadata: { path: "/memories/people/alice.md" } } ``` ## Prerequisites & Setup Before you begin, make sure you have: 1. API Key: Get your API key from the [API Keys](https://platform.mixedbread.com/platform?next=api-keys) page 2. SDK: Install the Mixedbread SDK for your preferred language: ```bash tab="Python" pip install mixedbread ``` ```bash tab="TypeScript" npm install @mixedbread/sdk ``` 3. For the [Agent Integration](#building-an-agent-with-memory) section, you'll need an [OpenAI API key](https://platform.openai.com/api-keys): ```bash export OPENAI_API_KEY="your-openai-api-key" ``` ```bash tab="Python" pip install openai ``` ```bash tab="TypeScript" npm install ai @ai-sdk/openai zod ``` ## Define the SemanticFS Class Wrap all operations in a `SemanticFS` class that provides file system-like methods: **SemanticFS Implementation** Python: ```python from mixedbread import Mixedbread class SemanticFS: """A semantic file system backed by Mixedbread stores.""" def __init__(self, store_name: str, api_key: str = None): self.mxbai = Mixedbread(api_key=api_key) self.store_name = store_name self.mxbai.stores.create(name=store_name) def write(self, path: str, content: str, metadata: dict = None): """Write content to a path.""" file_metadata = {"path": path, **(metadata or {})} filename = path.split("/")[-1] self.mxbai.stores.files.upload( store_identifier=self.store_name, file=(filename, content, "text/plain"), external_id=path, metadata=file_metadata, overwrite=True ) def read(self, path: str) -> str | None: """Read content from a path.""" try: file = self.mxbai.stores.files.retrieve( store_identifier=self.store_name, file_identifier=path ) content = self.mxbai.files.content(file_id=file.id) return content.read().decode("utf-8") except Exception: return None def search(self, query: str, folder: str = None, top_k: int = 5) -> list[dict]: """Semantic search across files, optionally within a folder.""" filters = {"key": "path", "operator": "starts_with", "value": folder} if folder else None results = self.mxbai.stores.search( store_identifiers=[self.store_name], query=query, filters=filters, top_k=top_k ) return [{"path": r.metadata.get("path"), "content": r.text, "score": r.score} for r in results.data] def list(self, folder: str) -> list[str]: """List all files under a folder.""" files = self.mxbai.stores.files.list( store_identifier=self.store_name, metadata_filter={"key": "path", "operator": "starts_with", "value": folder} ) return [f.metadata.get("path") for f in files.data] def delete(self, path: str): """Delete a file by path.""" self.mxbai.stores.files.delete( store_identifier=self.store_name, file_identifier=path ) # Initialize fs = SemanticFS("agent-memory", api_key="YOUR_API_KEY") ``` TypeScript: ```ts import Mixedbread from "@mixedbread/sdk"; class SemanticFS { private mxbai: Mixedbread; private storeName: string; constructor(storeName: string, apiKey: string) { this.mxbai = new Mixedbread({ apiKey }); this.storeName = storeName; } async init() { await this.mxbai.stores.create({ name: this.storeName }); return this; } async write(path: string, content: string, metadata?: Record) { const filename = path.split("/").pop()!; const file = new File([content], filename, { type: "text/plain" }); await this.mxbai.stores.files.upload(this.storeName, file, { external_id: path, metadata: { path, ...metadata }, overwrite: true }); } async read(path: string): Promise { try { const file = await this.mxbai.stores.files.retrieve(path, { store_identifier: this.storeName }); const content = await this.mxbai.files.content(file.id); return await content.text(); } catch { return null; } } async search(query: string, folder?: string, topK = 5) { const filters = folder ? { key: "path", operator: "starts_with" as const, value: folder } : undefined; const results = await this.mxbai.stores.search({ store_identifiers: [this.storeName], query, filters, top_k: topK }); return results.data.map(r => ({ path: r.metadata?.path as string, content: r.text!, score: r.score })); } async list(folder: string): Promise { const files = await this.mxbai.stores.files.list(this.storeName, { metadata_filter: { key: "path", operator: "starts_with", value: folder } }); return files.data.map(f => f.metadata?.path as string); } async delete(path: string) { await this.mxbai.stores.files.delete(path, { store_identifier: this.storeName }); } } // Initialize const fs = await new SemanticFS("agent-memory", "YOUR_API_KEY").init(); ``` ### Method Reference - **`write(path, content, metadata?)`** - Store content at a path. Uses [`external_id`](https://www.mixedbread.com/docs/stores/store-files#external-id) for upsert behavior. - **`read(path)`** - Retrieve file content by exact path. - **`search(query, folder?, top_k?)`** - Semantic search across files, optionally scoped to a folder. - **`list(folder)`** - List all file paths under a folder prefix. - **`delete(path)`** - Remove a file by path. ### Usage Examples **Using SemanticFS** Python: ```python # Write files fs.write("/memories/user.md", """# User Profile - Name: Alice - Role: Software Engineer - Interests: AI, distributed systems """, {"type": "profile"}) fs.write("/chats/2024-01-15.md", """# Chat - January 15 Discussed Redis caching strategy. """, {"type": "chat", "date": "2024-01-15"}) # Read a specific file profile = fs.read("/memories/user.md") # Semantic search results = fs.search("caching strategy") results = fs.search("auth tokens", folder="/chats/") # List files in a folder chats = fs.list("/chats/") # Delete a file fs.delete("/chats/2024-01-10.md") ``` TypeScript: ```ts // Write files await fs.write("/memories/user.md", `# User Profile - Name: Alice - Role: Software Engineer - Interests: AI, distributed systems `, { type: "profile" }); await fs.write("/chats/2024-01-15.md", `# Chat - January 15 Discussed Redis caching strategy. `, { type: "chat", date: "2024-01-15" }); // Read a specific file const profile = await fs.read("/memories/user.md"); // Semantic search const results = await fs.search("caching strategy"); const chatResults = await fs.search("auth tokens", "/chats/"); // List files in a folder const chats = await fs.list("/chats/"); // Delete a file await fs.delete("/chats/2024-01-10.md"); ``` ## Build an Agent with Memory Now let's integrate `SemanticFS` with an AI agent: 1. **Initialize** a `SemanticFS` instance 2. **Define tools** that wrap the `fs` methods 3. **Create an agent** with the tools attached We use the [OpenAI Responses API](https://platform.openai.com/docs/api-reference/responses) for Python and [AI SDK](https://ai-sdk.dev/) for TypeScript: **Agent with Semantic Memory** Python: ```python import json from openai import OpenAI from datetime import datetime # Initialize SemanticFS (from previous section) fs = SemanticFS("agent-memory", api_key="YOUR_MIXEDBREAD_API_KEY") # Initialize OpenAI client client = OpenAI() # Define tools as OpenAI function schemas tools = [ { "type": "function", "name": "search", "description": "Search memories using natural language.", "parameters": { "type": "object", "properties": { "query": {"type": "string", "description": "Natural language search query"}, "folder": {"type": "string", "description": "Optional folder to search within (e.g., '/chats/', '/memories/')"} }, "required": ["query"] } }, { "type": "function", "name": "read", "description": "Read a specific file by path.", "parameters": { "type": "object", "properties": { "path": {"type": "string", "description": "Path to read (e.g., '/memories/user.md')"} }, "required": ["path"] } }, { "type": "function", "name": "write", "description": "Save content to a file path.", "parameters": { "type": "object", "properties": { "path": {"type": "string", "description": "Path to store the file"}, "content": {"type": "string", "description": "Content to save"} }, "required": ["path", "content"] } }, { "type": "function", "name": "list_files", "description": "List all files in a folder.", "parameters": { "type": "object", "properties": { "folder": {"type": "string", "description": "Folder path (e.g., '/chats/')"} }, "required": ["folder"] } } ] # Tool handlers handlers = { "search": lambda args: fs.search(args["query"], args.get("folder"))[:3], "read": lambda args: fs.read(args["path"]) or "File not found", "write": lambda args: (fs.write(args["path"], args["content"]), f"Saved to {args['path']}")[1], "list_files": lambda args: fs.list(args["folder"]) } def chat(user_message: str, max_iterations: int = 10) -> str: """Run the agent loop with memory.""" user_profile = fs.read("/memories/user.md") or "No user profile yet." instructions = f"""You are a helpful assistant with persistent memory. User Profile: {user_profile} Today's date: {datetime.now().strftime('%Y-%m-%d')}""" input_list = [{"role": "user", "content": user_message}] for _ in range(max_iterations): response = client.responses.create( model="gpt-4.1", instructions=instructions, tools=tools, input=input_list ) input_list.extend(response.output) # Check for function calls has_function_calls = False for item in response.output: if item.type == "function_call": has_function_calls = True args = json.loads(item.arguments) handler = handlers.get(item.name) result = handler(args) if handler else {"error": f"Unknown function: {item.name}"} input_list.append({ "type": "function_call_output", "call_id": item.call_id, "output": json.dumps(result, default=str) }) if not has_function_calls: return response.output_text return "Max iterations reached." # Example usage response = chat("What caching strategy did we discuss last time?") print(response) ``` TypeScript: ```ts import { ToolLoopAgent, tool } from "ai"; import { openai } from "@ai-sdk/openai"; import { z } from "zod"; // Initialize SemanticFS (from previous section) const fs = await new SemanticFS("agent-memory", "YOUR_API_KEY").init(); // Agent tools const tools = { search: tool({ description: "Search memories using natural language.", inputSchema: z.object({ query: z.string().describe("Natural language search query"), folder: z.string().optional().describe("Folder to search within (e.g., '/chats/')") }), execute: async ({ query, folder }) => { const results = await fs.search(query, folder); return results.slice(0, 3); } }), read: tool({ description: "Read a specific file by path.", inputSchema: z.object({ path: z.string().describe("Path to read (e.g., '/memories/user.md')") }), execute: async ({ path }) => { return await fs.read(path) ?? "File not found"; } }), write: tool({ description: "Save content to a file path.", inputSchema: z.object({ path: z.string().describe("Path to store the file"), content: z.string().describe("Content to save") }), execute: async ({ path, content }) => { await fs.write(path, content); return `Saved to ${path}`; } }), list: tool({ description: "List all files in a folder.", inputSchema: z.object({ folder: z.string().describe("Folder path (e.g., '/chats/')") }), execute: async ({ folder }) => { return await fs.list(folder); } }) }; async function chat(userMessage: string): Promise { const userProfile = await fs.read("/memories/user.md") ?? "No user profile yet."; const agent = new ToolLoopAgent({ model: openai("gpt-5"), instructions: `You are a helpful assistant with persistent memory. User Profile: ${userProfile} Today's date: ${new Date().toISOString().split("T")[0]}`, tools }); const { text } = await agent.generate({ prompt: userMessage }); return text; } // Example usage const response = await chat("What caching strategy did we discuss last time?"); console.log(response); ``` ### Organize with Folders On top of `SemanticFS`, use folders to let agents organize different types of content: - **`/memories/user.md`** - User profile loaded into system prompt (preferences, name, role) - **`/memories/people/`** - Information about contacts (details about Alice, Bob) - **`/chats/`** - Conversation summaries by date (key decisions, action items) - **`/notes/`** - User-created documents (project ideas, meeting notes) - **`/todos/`** - Task items and reminders (pending tasks with due dates) ## Next Steps You now have the building blocks for AI agents with infinite memory. See Bernd for a full implementation with calendar, todos, and web search: - **[Try Bernd](https://bernd.mixedbread.com/chat)**: Live demo of an agent with persistent memory - **[Bernd on GitHub](https://github.com/mixedbread-ai/bernd)**: Full source code and implementation details ### References - [OpenAI Responses API](https://platform.openai.com/docs/api-reference/responses) - Python agent loop pattern used in this cookbook - [AI SDK ToolLoopAgent](https://ai-sdk.dev/docs/reference/ai-sdk-core/tool-loop-agent) - TypeScript agent framework used in this cookbook - [Metadata Filtering](https://www.mixedbread.com/docs/stores/metadata-filtering) - Advanced filtering for precise memory retrieval # Chat with PDFs URL: https://www.mixedbread.com/cookbook/chat-with-pdfs Build a document Q&A system with PDFs, slides, and rich media using Mixedbread's native search and question answering. If you have a lot of documents like PDFs and slides in the company knowledge base, you might want to find a specific page or figure by describing it. > **Figure**: Chat with PDFs In this cookbook, we build a document search engine with Q&A using Mixedbread. It shows **rich document support** (PDFs, scanned files, PPTX), **high quality parsing** and **native question answering** - everything you need to find and chat with your documents. ## Prerequisites & Setup Before you begin, make sure you have: 1. API Key: Get your API key from the [API Keys](https://platform.mixedbread.com/platform?next=api-keys) page 2. SDK: Install the Mixedbread SDK for your preferred language: ```bash tab="Python" pip install mixedbread ``` ```bash tab="TypeScript" npm install @mixedbread/sdk ``` 3. (Optional) For the [RAG with OpenAI](#rag-with-openai) section, you'll need an [OpenAI API key](https://platform.openai.com/api-keys) and the OpenAI SDK: ```bash tab="Python" pip install openai ``` ```bash tab="TypeScript" npm install ai @ai-sdk/openai ``` ## Get Sample Documents We'll use a sample of 3 documents (PDFs, scanned files, and PPTX). Download and extract: ```bash curl -L -o doc-qa-sample.zip https://github.com/mixedbread-ai/cookbook-assets/releases/download/v1.0.0/doc-qa-sample.zip unzip doc-qa-sample.zip ``` The sample includes: - `attention.pdf` - 3 PDF pages from the paper "Attention Is All You Need" - `UFO.pdf` - 3 PDF pages of a scanned UFO document released by FOIA - `OBGYN.pptx` - 3 PPTX pages from a RCSI presentation on Obstetrics and Gynecology ## Create a Store First, create a Mixedbread store for your documents: **Create Document Store** Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") store = mxbai.stores.create( name="doc-qa-cookbook" ) ``` TypeScript: ```ts import Mixedbread from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY" }); const store = await mxbai.stores.create({ name: "doc-qa-cookbook" }); ``` ## Upload Documents Upload your PDFs and slides: **Upload PDFs and Slides** Python: ```python from pathlib import Path for filename in ["attention.pdf", "UFO.pdf", "OBGYN.pptx"]: mxbai.stores.files.upload( store_identifier="doc-qa-cookbook", file=Path(filename) ) print(f"Uploaded: {filename}") ``` TypeScript: ```ts import fs from "fs"; for (const filename of ["attention.pdf", "UFO.pdf", "OBGYN.pptx"]) { await mxbai.stores.files.upload( "doc-qa-cookbook", { file: fs.createReadStream(filename) } ); console.log(`Uploaded: ${filename}`); } ``` ### (Optional) High Quality Parsing Search works on visual content (screenshots of pages) directly - Mixedbread stores can find relevant pages regardless of quality. For downstream tasks, Mixedbread stores return [image chunks](https://www.mixedbread.com/docs/stores/data-models#content-specific-properties) per page with `image_url` and `ocr_text` fields. When LLMs don't support images or struggle with complex visuals, you can use `ocr_text` field to provide more context. Enable high quality parsing to automatically get better OCR text: **Upload with High Quality Parsing** Python: ```python mxbai.stores.files.upload( store_identifier="doc-qa-cookbook", file=Path(filename), config={ "parsing_strategy": "high_quality", } ) ``` TypeScript: ```ts await mxbai.stores.files.upload( "doc-qa-cookbook", { file: fs.createReadStream(filename), config: { parsing_strategy: "high_quality", }, } ); ``` - **Fast** (default): Standard PDF text extraction, fast and efficient - **High quality**: Runs advanced OCR to extract cleaner, more accurate text ## Search Documents Once your documents are uploaded and indexed, search using natural language: **Search Documents** Python: ```python results = mxbai.stores.search( store_identifiers=["doc-qa-cookbook"], query="architecture diagram showing the transformer model layers", top_k=1 ) for result in results.data: print(f"{result.score:.3f} - {result.filename}") print(f" {result.ocr_text[:200]}...") ``` TypeScript: ```ts const results = await mxbai.stores.search({ store_identifiers: ["doc-qa-cookbook"], query: "architecture diagram showing the transformer model layers", top_k: 1 }); for (const result of results.data) { console.log(`${result.score.toFixed(3)} - ${result.filename}`); console.log(` ${result.ocr_text?.slice(0, 200)}...`); } ``` Try searching for content in the scanned UFO document or the RCSI slides: **Search Scanned Documents** Python: ```python ufo_results = mxbai.stores.search( store_identifiers=["doc-qa-cookbook"], query="Eastern Air Line pilots UFO sighting", top_k=1 ) rcsi_results = mxbai.stores.search( store_identifiers=["doc-qa-cookbook"], query="Acceptable MCA Doppler shift waveform", top_k=1 ) ``` TypeScript: ```ts const ufo_results = await mxbai.stores.search({ store_identifiers: ["doc-qa-cookbook"], query: "Eastern Air Line pilots UFO sighting", top_k: 1 }); const rcsi_results = await mxbai.stores.search({ store_identifiers: ["doc-qa-cookbook"], query: "Acceptable MCA Doppler shift waveform", top_k: 1 }); ``` ## Build Q&A with LLMs Now for the main event: getting AI-powered answers from your documents. ### Native Question Answering Mixedbread stores provide question answering capabilities out of the box: **Native Question Answering** Python: ```python response = mxbai.stores.question_answering( store_identifiers=["doc-qa-cookbook"], query="What date and location did each sighting of UFO occur?", top_k=2 ) print("Answer:", response.answer) print("\nSources:") for i, source in enumerate(response.sources): print(f" [{i}] {source.filename} - {source.ocr_text[:200]}...") ``` TypeScript: ```ts const response = await mxbai.stores.question_answering({ store_identifiers: ["doc-qa-cookbook"], query: "What date and location did each sighting of UFO occur?", top_k: 2 }); console.log("Answer:", response.answer); console.log("\nSources:"); response.sources?.forEach((source, i) => { console.log(` [${i}] ${source.filename} - ${source.ocr_text?.slice(0, 200)}...`); }); ``` The response includes: - **`answer`**: AI-generated answer with citation tags like `` - **`sources`**: The document [chunks](https://www.mixedbread.com/docs/stores/data-models#store-chunk) used to generate the answer Citations map directly to sources - `` refers to `sources[0]`. ### RAG with OpenAI Want more control? Use Mixedbread stores for retrieval and OpenAI or other LLM providers for generation: 1. **Retrieve** - Call Mixedbread to search documents with your query 2. **Build context** - Convert chunks to messages with image URLs and OCR text 3. **Generate** - Call the LLM with the query and context to get an answer **RAG with OpenAI** Python: ```python from openai import OpenAI openai = OpenAI(api_key="YOUR_OPENAI_KEY") # Step 1: Retrieve relevant context from Mixedbread query = "Explain the self-attention mechanism" results = mxbai.stores.search( store_identifiers=["doc-qa-cookbook"], query=query, top_k=2 ) # Step 2: Build multimodal content with images and text content = [{"type": "input_text", "text": f"Question: {query}\n\nHere are the relevant document pages:"}] for i, r in enumerate(results.data): # Add the page image for visual context content.append({ "type": "input_image", "image_url": r.image_url.url }) # Add OCR text and source info content.append({ "type": "input_text", "text": f"[Source {i}: {r.filename}]\n{r.ocr_text}" }) # Step 3: Generate answer with OpenAI Responses API response = openai.responses.create( model="gpt-5", instructions="Answer questions based on the provided document pages. Cite sources when possible.", input=content ) print(response.output_text) ``` TypeScript: ```ts import { createOpenAI } from "@ai-sdk/openai"; import { generateText } from "ai"; const openai = createOpenAI({ apiKey: "YOUR_OPENAI_KEY" }); // Step 1: Retrieve relevant context from Mixedbread const query = "Explain the self-attention mechanism"; const results = await mxbai.stores.search({ store_identifiers: ["doc-qa-cookbook"], query, top_k: 2 }); // Step 2: Build multimodal content with images and text const content: Parameters[0]["messages"][0]["content"] = [ { type: "text", text: `Question: ${query}\n\nHere are the relevant document pages:` } ]; for (const [i, r] of results.data.entries()) { // Add the page image for visual context content.push({ type: "image", image: new URL(r.image_url!.url) }); // Add OCR text and source info content.push({ type: "text", text: `[Source ${i}: ${r.filename}]\n${r.ocr_text}` }); } // Step 3: Generate answer with AI SDK const { text } = await generateText({ model: openai("gpt-5"), system: "Answer questions based on the provided document pages. Cite sources when possible.", messages: [{ role: "user", content }] }); console.log(text); ``` This pattern gives you full control over: - The prompt template and system message - Which model to use (GPT-5, Claude, etc.) - How to format and present citations - Streaming responses ## Next Steps You now have a working document Q&A system. Here are ways to extend it: - **Add more documents**: Upload your own PDFs, Word docs, or presentations - **Filter by metadata**: Create document collections by topic, date, or author - **Build a chat interface**: Create a conversational UI with chat history - **[Supported File Types](https://www.mixedbread.com/docs/stores/store-files/file-types)**: Learn more about supported file types - **[Metadata Filtering](https://www.mixedbread.com/docs/stores/metadata-filtering)**: Filter search results by document properties # Text-to-Image Search URL: https://www.mixedbread.com/cookbook/image-search Build a semantic image search engine using Mixedbread's multimodal and multilingual capabilities. {/* TODO: Add demo video here */} > **Figure**: Farmers in the Field In this cookbook, we build a text-to-image search system using Mixedbread. It demonstrates **native image understanding** and **multilingual search** of Mixedbread stores - query images using text in any language. ## Prerequisites & Setup Before you begin, make sure you have: 1. API Key: Get your API key from the [API Keys](https://platform.mixedbread.com/platform?next=api-keys) page 2. SDK: Install the Mixedbread SDK for your preferred language: ```bash tab="Python" pip install mixedbread ``` ```bash tab="TypeScript" npm install @mixedbread/sdk ``` ## Get Sample Images We'll use 20 sample artworks from the [National Gallery of Art Open Data](https://github.com/NationalGalleryOfArt/opendata). Download and extract: ```bash curl -L -o nga-artworks-sample.zip https://github.com/mixedbread-ai/cookbook-assets/releases/download/v1.0.0/nga-artworks-sample.zip unzip nga-artworks-sample.zip ``` The sample includes a `metadata.json` keyed by filename: ```json { "daubigny_charles_françois_moonlit_landscape.jpg": { "title": "Moonlit Landscape", "artist_name": "Daubigny, Charles-François", "artist_nationality": "French", "medium": "cliché-verre", "classification": "Print" } } ``` ## Create a Store First, we need to create a Mixedbread store for our image files: **Create Store with Metadata Contextualization** Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") store = mxbai.stores.create( name="image-search-cookbook", config={ "contextualization": { "with_metadata": ["title", "artist_name"] } } ) ``` TypeScript: ```ts import Mixedbread from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY" }); const store = await mxbai.stores.create({ name: "image-search-cookbook", config: { contextualization: { with_metadata: ["title", "artist_name"] } } }); ``` By default, Mixedbread stores index images by their visual content. With [metadata contextualization](https://www.mixedbread.com/docs/stores/stores#store-configuration), metadata fields are also included in the embedding - so searching "Daubigny landscape" matches both visual content and artist name. ## Upload Images Now that you have a store, it's time to upload your images with their metadata. The sample includes a `metadata.json` with artwork details (title, artist, medium, etc.): **Upload Images with Metadata** Python: ```python import json from pathlib import Path with open("metadata.json") as f: metadata = json.load(f) for filename in Path("./images").iterdir(): file_metadata = metadata.get(filename.name, {}) mxbai.stores.files.upload( store_identifier="image-search-cookbook", file=filename, metadata=file_metadata ) print(f"Uploaded: {file_metadata.get('title', filename.name)}") ``` TypeScript: ```ts import fs from "fs"; import path from "path"; const metadata = JSON.parse(fs.readFileSync("metadata.json", "utf-8")); for (const filename of fs.readdirSync("./images")) { const fileMetadata = metadata[filename] || {}; await mxbai.stores.files.upload( "image-search-cookbook", { file: fs.createReadStream(path.join("./images", filename)), metadata: fileMetadata } ); console.log(`Uploaded: ${fileMetadata.title || filename}`); } ``` All metadata fields are uploaded and stored. The `title` and `artist_name` fields we specified in contextualization are included in embeddings, while other fields remain available for [filtering](https://www.mixedbread.com/docs/stores/metadata-filtering) and display in search results. ## Search Images Once all images are uploaded and indexed, you can search as you would describe them (e.g., "ship on the ocean"): **Search by Visual Content** Python: ```python results = mxbai.stores.search( store_identifiers=["image-search-cookbook"], query="ship on the ocean", top_k=3 ) for result in results.data: meta = result.metadata print(f"{result.score:.3f} - {meta.get('title')} by {meta.get('artist_name')}") print(f" URL: {result.image_url.url}") ``` TypeScript: ```ts const results = await mxbai.stores.search({ store_identifiers: ["image-search-cookbook"], query: "ship on the ocean", top_k: 3 }); for (const result of results.data) { const meta = result.metadata; console.log(`${result.score.toFixed(3)} - ${meta?.title} by ${meta?.artist_name}`); console.log(` URL: ${result.image_url.url}`); } ``` > **Figure**: Ship on the Ocean *You can also run the same query in your store's dashboard to see results visually.* Since we enabled contextualization with `artist_name`, you can combine visual description and artist in one query - matching both image content and metadata: **Search by Visual Content + Artist** Python: ```python results = mxbai.stores.search( store_identifiers=["image-search-cookbook"], query="Daubigny night landscape", top_k=3 ) ``` TypeScript: ```ts const results = await mxbai.stores.search({ store_identifiers: ["image-search-cookbook"], query: "Daubigny night landscape", top_k: 3 }); ``` Mixedbread returns the most relevant results based on the query. You can set `top_k` to configure the number of images returned. For image files, each result is an [image chunk](https://www.mixedbread.com/docs/stores/data-models#store-chunk) containing `image_url.url`. You can also use `metadata` to map results back to your original files. > **Figure**: Daubigny night landscape ## Multilingual Search The same images can be searched in any language, such as Chinese and German: **Search Images in Different Languages** Python: ```python # Chinese results = mxbai.stores.search( store_identifiers=["image-search-cookbook"], query="海上的船只", # Chinese for "ship on the ocean" top_k=3 ) # German results = mxbai.stores.search( store_identifiers=["image-search-cookbook"], query="Schiffe auf dem Meer", # German for "ship on the ocean" top_k=3 ) ``` TypeScript: ```ts // Chinese const results = await mxbai.stores.search({ store_identifiers: ["image-search-cookbook"], query: "海上的船只", // Chinese for "ship on the ocean" top_k: 3 }); // German const results = await mxbai.stores.search({ store_identifiers: ["image-search-cookbook"], query: "Schiffe auf dem Meer", // German for "ship on the ocean" top_k: 3 }); ``` > **Figure**: Ship on the Ocean in Chinese Mixedbread supports all [300+ languages](https://en.wikipedia.org/wiki/List_of_Wikipedias#) out of the box with zero configuration. ## Try It Live See text-to-image search at scale with the NGA Art Search - 50,000+ artworks from the National Gallery of Art, built with Mixedbread and Next.js. - **[Live Demo](https://nga.demo.mixedbread.com)**: Search the National Gallery of Art collection - **[Source Code](https://github.com/mixedbread-ai/nga-art-search)**: View the full implementation on GitHub # Cookbook URL: https://www.mixedbread.com/cookbook Practical guides and examples for building with Mixedbread's AI search and embedding capabilities. Welcome to the Mixedbread Cookbook. Here you'll find practical, end-to-end guides for building real-world applications with our APIs. ## What's Inside Each cookbook is a complete, working example that you can follow along with and adapt to your own use case. - **[Chat with PDFs](https://www.mixedbread.com/cookbook/chat-with-pdfs)**: Build a document Q&A system with PDFs and slides - **[Text-to-Image Search](https://www.mixedbread.com/cookbook/image-search)**: Build a semantic image search system of artworks - **[AI Agent with Memory](https://www.mixedbread.com/cookbook/agent-memory)**: Build AI agents with persistent, searchable memory # Build Your Own Harness URL: https://www.mixedbread.com/docs/agent/build-your-own-harness Recommendations for building custom Toast 1 search harnesses with the Chat Completions API. Toast is a deep search and lookup agent, trained end-to-end to gather evidence and to answer from it: as a ranked evidence list, as ranked evidence plus an answer, or as a plain-text answer. You can use Toast with our [Toast 1 harness](https://github.com/mixedbread-ai/toast-harness) directly via our [Search API with agentic search feature](https://www.mixedbread.com/docs/stores/search/agentic-search), or let the API run the search loop for you with the [hosted store tools](https://www.mixedbread.com/docs/agent/hosted-tools). Like most agents, Toast is only as good as its tools. It performs best with a late-interaction style semantic search, but has no issues working with your other search backends. The search agent adapts well to new tools and custom harnesses: file search tools, tools to access domain knowledge, or custom answer tools. This guide collects recommendations and guidance for defining custom harnesses with our Completions API so you can make best use of Toast 1's strengths for your use case. Toast 1 is trained for deep evidence gathering and for answering from what it found. It prefers to fan out searches via parallel search calls, resulting in high exploration for minimal latency. It's the perfect multilingual exploration agent for knowledge work: a substitute for GPT-5.6 Luna/Terra or Claude Haiku/Sonnet as a look-up or grounded question-answering subagent. If these characteristics match your use case, follow this guide to create your own fast searcher. ## Platform constraints - Toast has thinking disabled. It was trained without thinking and is only served without thinking to have state-of-the-art retrieval performance at minimum latency. - Sampling parameters are configurable; we recommend `temperature 0.7, top_p 0.95`. - Toast is served at `seq_len = 131072`: every input message needs to stay below 130k tokens. - Generation defaults to `4096` tokens per completion; raise `max_completion_tokens` if you need more. Context management comes in two modes: - **Pass-through** (the default): manage and compact your context against the 130k input limit yourself (for example, use it for a Pi harness internal compaction). The API adds nothing and edits nothing; an oversized request is an honest `422 context_length_exceeded`, never a silent truncation. - **Declared `context_management`**: in our [Toast 1 harness](https://github.com/mixedbread-ai/toast-harness), Toast uses pruning as its context management: a `prune_context` tool the agent calls to remove chunks it considers irrelevant, invoked as it approaches the context limit. The API offers the same mechanism as an opt-in: declare `{"context_management": {"edits": [{"type": "prune_context"}]}}` and the server offers the model the harness's `prune_context` tool over every tool result, yours included ([details](https://www.mixedbread.com/docs/agent/hosted-tools#manage-the-context-window)). Prefer declaring it over hand-rolling your own pruning; our inference and latency are optimized for prune-style removal of stale tool results over summarizing compaction. Do **not** use `previous_completion_id` after **your application** has edited the history; it only works when the history you resend extends the stored one. After client-side pruning, just resend the full edited messages list (see the loop example at the end of this guide). Server-side edits are different: prunes applied under declared `context_management` never invalidate `previous_completion_id`, because the server holds the authoritative edited context. ## Harness design & Completions API guidance The Completions API is an OpenAI-compatible chat completions endpoint: provide your prompt, messages, tool definitions, and sampling params exactly the way you would with the standard OpenAI client. You send a messages list plus your tool schemas in `tools`, and Toast answers with either text or tool calls. The API is stateless unless you use `previous_completion_id`: every request resends the full message history, and the server executes none of your tools. When Toast calls one of your tools, the completion ends with `finish_reason: "tool_calls"`; your harness executes the calls, appends one tool message per call, and sends the next request. That loop is your whole harness. The API adds nothing on its own: no injected prompt, no injected tools, one generation per request. The one server-side feature this guide recommends is declared [`context_management`](https://www.mixedbread.com/docs/agent/hosted-tools#manage-the-context-window) (see Platform constraints above), strictly opt-in. The following guidelines are design choices inspired by our Toast 1 harness. Treat them as recommendations, not requirements. - Toast is trained to work within a bounded number of turns and a bounded number of parallel tool calls. Communicate those boundaries in the harness. Our Toast 1 harness defaults to 4 turns with up to 8 parallel calls per turn, but this is a soft recommendation; Toast can easily go up to 8, 12, or more turns. - For similar retrieval performance, enable parallel tool calls in your harness and make your tools safe to execute concurrently. Parallel tool latency is bounded by the slowest tool you include. - Do not overflow the 130k token context limit when providing the full results of many parallel calls back to the agent. With up to 8 parallel calls per turn, uncapped tool returns fill the context quickly. If your tools return docs with many tokens, truncate them. - Return short stable handles with your search tools' results, like a short `chunk_id`. Every result your search tools return needs a stable id, and any tool that takes other tools' outputs as inputs must accept exactly the ids you emitted. Tools that operate on retrieved results are easy to define this way. - Deduplicate if you want: filtering already seen search results out of the tool call results leads to less context rot and higher recall. - Give Toast a terminal: a tool to end the searching and report its findings, or a plain-text answer turn. Our Toast 1 harness uses a `submit_ranking` tool that takes the `chunk_ids` your search tools emitted plus a relevance score per chunk and a short `ranking_strategy` (see Terminal modes below). - Define your tools to return a dict, not prose text. Our Toast 1 harness tool results are JSON envelopes: `{"query": ..., "results": [...], "candidate_count": N}` with per-result entries like `{"chunk_id": ..., "text": ..., "score": ..., "metadata": {...}}`. Prefer returning a similar shape from your functions. - Communicate tool schema errors back to Toast instead of raising them. If you provide the tool error in the tool response, Toast can retry the call in the next turn; we trained Toast to recover well from structured errors. Example: catch the exception and return `{"error": "date must be ISO format, got '3/5/24'"}`. ### Terminal modes Toast was trained on three terminal modes (three ways to end a run). Pick the one that matches what your application consumes and keep your wording close to ours: - `submit_ranking`, ranking only (our harness default): Toast ends with a `submit_ranking` call carrying `chunks` (`chunk_id` plus `relevance_score`) and a `ranking_strategy`; your application generates the answer from the ranked chunks. - `submit_ranking` with `answer`: add a required `answer` string to the reporting tool. Our parameter description: "Your final answer to the original user query, based only on retrieved evidence. Required on every submit_ranking call: give your single best answer even when uncertain; if the evidence is insufficient to answer, say so." Toast returns evidence and answer in one structured call. - Plain-text answer: offer no reporting tool at all and leave `tool_choice` on `auto`. Instruct Toast that every response must contain tool calls until it answers, and that a plain-text reply with no tool calls ends the run: "Do not report chunk lists or rankings; deliver the answer itself." The completion's `content` with `finish_reason: "stop"` is the answer. In every mode, tell Toast to base the answer only on retrieved evidence and to say so when the evidence is insufficient. When the round budget runs out, force the terminal turn with a short user message ("You have reached the search limit. Do NOT search further. ..."). ### Phrasing of instructions Toast performs best writing human-style questions for a semantic search tool and writing regex for grep tools. Be precise in your custom tool definitions and give clear instructions on how to use the tool (see the example at the end of this guide). When adding custom search tools, providing instructions on how to formulate queries helped a lot to boost retrieval performance. An example for a BM25 tool: "this BM25 tool is matching keywords, write only keyword-heavy queries". ### Build your own harness with Python For a custom searcher harness in Python, write the tool descriptions directly in the docstrings and type hints of your tool functions. Docstrings and type hints are the interface Toast sees: generate the JSON tool schema from them with any docstring-based schema helper: the docstring becomes the tool description, and `Annotated` strings become the parameter descriptions. - Toast follows tool descriptions as instructions. Say what the tool matches on, when to prefer it, and how to phrase input ("this tool matches keywords only. Send keyword-heavy queries, not questions"). - Keep tool signatures flat and JSON-native. Toast was trained on flat argument objects: `str`, `float`, `bool`, `list[str]`, and one level of typed dicts. - Prefer `snake_case` names. Mark what's essential as required and give defaults for the rest of your parameters. - Use `Literal`/`Enum` for closed choices. Trained tools express modes as enums (`filter_mode: Literal["all", "any"]`, `direction: Literal["asc", "desc"]`). Example 1: a simple semantic search tool with just a `query` and a `top_k` parameter. ```python from typing import Annotated def semantic_search( query: Annotated[str, "Natural-language query for a single search aspect; " "avoid Boolean syntax, regex, and keyword dumps."], top_k: Annotated[int, "Number of chunks to return, max 20."] = 5, ) -> dict: """Execute a meaning-based semantic search query over the corpus and return the most relevant chunks. Use natural language; phrase queries as human-style questions. Do not use for keyword, regex, or literal-string matching. Returns up to top_k chunks with stable chunk_id handles.""" hits = my_search_backend(query, top_k=top_k) # your implementation return { "query": query, "candidate_count": len(hits), "results": [ {"chunk_id": h.id, # short stable handle, e.g. "c12" "score": round(h.score, 4), "text": h.text, # clipped, not the whole document "metadata": h.metadata} for h in hits ], } ``` Example 2: a custom BM25 keyword-search tool. ```python from typing import Annotated, Literal def bm25_search( query: Annotated[str, "Space-separated keywords, no natural-language questions, " "no boolean operators. Example: 'jordan international goals caps'"], top_k: Annotated[int, "Number of chunks to return, max 20."] = 5, mode: Literal["chunks", "documents"] = "chunks", ) -> dict: """Keyword-based BM25 search over the corpus. This tool matches keywords only. Send keyword-heavy queries, not questions. Use for rare terms, names, codes, and exact vocabulary; Returns up to top_k chunks with stable chunk_id handles.""" hits = bm25_index.search(query, k=top_k, mode=mode) # your implementation return { "query": query, "candidate_count": len(hits), "results": [ {"chunk_id": h.id, # short stable handle, e.g. "c12" "score": round(h.score, 4), "text": h.text, # clipped, not the whole document "metadata": h.metadata} for h in hits ], } ``` Note how the description tells Toast what the tool is for, how to phrase input, when not to use it (and which tool to use instead), and how many results to expect. The return value is a JSON envelope with short stable handles and a score. ### Build your own harness with Pi If you use [Pi](https://github.com/earendil-works/pi) as your agent framework, the harness loop already exists: Pi runs the tool-call loop, executes your tools, and manages the context for you. You only need to connect Toast and register your tools. - Point Pi at the Completions API by adding Toast as a custom model in `~/.pi/agent/models.json`: an `openai-completions` provider with `baseUrl` `https://api.mixedbread.com/v1`, your `MXBAI_API_KEY`, a context window of `131072`, and max output tokens of `4096`. Set the recommended sampling parameters (`temperature 0.7, top_p 0.95`) and leave thinking off. - Define your search tools as a Pi extension: `pi.registerTool({name, description, parameters, execute})`, where `parameters` is the JSON schema for the arguments. All the guidelines from the Python section apply unchanged: the description is the instruction Toast follows, keep parameters flat and JSON-native, return the JSON envelope with stable `chunk_id` handles, and return errors as data instead of throwing. - Pi's built-in compaction summarizes the history. That works, but budget it against the 130k input limit, and prefer prune-style removal of stale tool results where you can. ### Example: the tool-call loop over the Completions API A minimal harness loop wiring a custom tool (the `bm25_search` above) to Toast over the Completions API. The tool schema is exactly what a harness would generate from the function's docstring and Annotated hints (see the Python section above); the raw API always takes the explicit JSON schema. Your own tools come back to you, with `finish_reason: "tool_calls"`: ```python import json from openai import OpenAI client = OpenAI(base_url="https://api.mixedbread.com/v1", api_key=MXBAI_API_KEY) tools = [ { "type": "function", "function": { "name": "bm25_search", "description": "Keyword-based BM25 search over the corpus. This tool matches " "keywords only. Send keyword-heavy queries, not questions. " "Use for rare terms, names, codes, and exact vocabulary. " "Returns up to top_k chunks with stable chunk_id handles.", "parameters": { "type": "object", "properties": { "query": { "type": "string", "description": "Space-separated keywords, no natural-language " "questions, no boolean operators. Example: " "'jordan international goals caps'", }, "top_k": { "type": "integer", "description": "Number of chunks to return, max 20.", "default": 5, }, "mode": { "type": "string", "enum": ["chunks", "documents"], "default": "chunks", }, }, "required": ["query"], }, }, }, ] messages = [{"role": "user", "content": "Which suppliers had recalls in 2023?"}] completion = client.chat.completions.create( model="toast-1", messages=messages, tools=tools, parallel_tool_calls=True, temperature=0.7, top_p=0.95, ) choice = completion.choices[0] while choice.finish_reason == "tool_calls": messages.append(choice.message) # the assistant turn carrying the tool calls for call in choice.message.tool_calls: # may be several; execute all of them result = bm25_search(**json.loads(call.function.arguments)) messages.append({ "role": "tool", "tool_call_id": call.id, "content": json.dumps(result), # errors go here as data too }) completion = client.chat.completions.create( model="toast-1", messages=messages, tools=tools, parallel_tool_calls=True, temperature=0.7, top_p=0.95, ) choice = completion.choices[0] print(choice.message.content) # the final answer ``` Three properties of the loop to keep in mind: - The API is stateless: every request resends the full message history, and each turn appends the assistant tool-call message plus one tool message per call. The next section removes the resend. - One turn can carry several parallel calls: answer every `tool_call_id`, then send the next request. - The loop is deliberately minimal: no round bound, and it ends on the plain-text terminal. In your harness, cap the rounds and, once the cap is hit, force the terminal turn as described under Terminal modes. ### Continue a stored completion The loop above resends the full message history on every request. With `store` left at its default of `true`, the API stores each completion, and the next request can continue it instead: name the completion in `previous_completion_id` and send only the new messages. The server restores the stored model context, hosted tool calls and server-side context edits included, and appends your messages to it. The loop changes in two places: `messages` shrinks to the new tool results, and each request names the completion it continues. ```python completion = client.chat.completions.create( model="toast-1", messages=messages, tools=tools, parallel_tool_calls=True, temperature=0.7, top_p=0.95, extra_body={"context_management": {"edits": [{"type": "prune_context"}]}}, ) choice = completion.choices[0] while choice.finish_reason == "tool_calls": results = [ { "role": "tool", "tool_call_id": call.id, "content": json.dumps(bm25_search(**json.loads(call.function.arguments))), } for call in choice.message.tool_calls ] completion = client.chat.completions.create( model="toast-1", messages=results, # only the new messages; the server holds the rest tools=tools, parallel_tool_calls=True, temperature=0.7, top_p=0.95, extra_body={ "context_management": {"edits": [{"type": "prune_context"}]}, "previous_completion_id": completion.id, }, ) choice = completion.choices[0] print(choice.message.content) # the final answer ``` - Do not resend the assistant turn: the stored completion already contains it. Your tool messages answer its `tool_call_id`s. - The server stores the conversation, not the request configuration: `tools`, sampling parameters and `context_management` go with every request, as in the stateless loop. - This is where declared `context_management` pays off across turns: prunes Toast applied in an earlier request stay applied, and each `usage.prompt_tokens` reflects them. A full-history resend rebuilds the context from your messages, and pruned content comes back. - `previous_completion_id` requires the stored history to be extended, never edited (see Platform constraints above). After your application edits the history, resend the full messages list without it. - Completions in a chain group into one conversation for listing and deletion. # Chat Completions URL: https://www.mixedbread.com/docs/agent/chat-completions Send messages to Mixedbread models with an OpenAI-compatible API. The Mixedbread Chat Completions API is an OpenAI Chat Completions-compatible endpoint for Mixedbread specialized models and agentic workflows. It supports text conversations, streaming, stored continuations, and client-executed function tools. It is the surface for bringing your own harness: your application owns the message list and the tool loop, and the API adds nothing you did not ask for; see [Build Your Own Harness](https://www.mixedbread.com/docs/agent/build-your-own-harness) for the complete guide. The [hosted store tools](https://www.mixedbread.com/docs/agent/hosted-tools) work here too, mirrored into the Chat shape. You can use the OpenAI SDK by changing `base_url` and `api_key`, then selecting a `model` from the [supported models](https://www.mixedbread.com/docs/agent/models). ## Prerequisite Get a Mixedbread API key from the [API Keys](https://platform.mixedbread.com/platform?next=api-keys) page. A scope-restricted key needs the **Completions** scope for these endpoints; see [API keys](https://www.mixedbread.com/docs/platform/api-keys). You can install the OpenAI SDK or use cURL directly. ```bash tab="Python" pip install openai ``` ```bash tab="TypeScript" npm install openai ``` ```bash tab="cURL" export MXBAI_API_KEY=YOUR_API_KEY ``` ## Make your first request Point `base_url` to Mixedbread, use your Mixedbread API key, and select one [supported model](https://www.mixedbread.com/docs/agent/models). **Create a chat completion** Python: ```python from openai import OpenAI client = OpenAI( base_url="https://api.mixedbread.com/v1", api_key="YOUR_API_KEY", ) completion = client.chat.completions.create( model="toast-1", messages=[ { "role": "user", "content": "What is a search agent?", } ], ) print(completion.choices[0].message.content) ``` Python (async): ```python from openai import AsyncOpenAI client = AsyncOpenAI( base_url="https://api.mixedbread.com/v1", api_key="YOUR_API_KEY", ) completion = await client.chat.completions.create( model="toast-1", messages=[ { "role": "user", "content": "What is a search agent?", } ], ) print(completion.choices[0].message.content) ``` TypeScript: ```ts import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://api.mixedbread.com/v1", apiKey: "YOUR_API_KEY", }); const completion = await client.chat.completions.create({ model: "toast-1", messages: [ { role: "user", content: "What is a search agent?", }, ], }); console.log(completion.choices[0]?.message.content); ``` cURL: ```bash curl https://api.mixedbread.com/v1/chat/completions \ -H "Authorization: Bearer $MXBAI_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "model": "toast-1", "messages": [ { "role": "user", "content": "What is a search agent?" } ] }' ``` Read the generated message from `choices[0].message`. ## OpenAI compatibility Mixedbread accepts the OpenAI Chat Completions shape for supported fields. The tables below cover important Mixedbread behavior: ### Request fields | Field or value | Behavior | | --- | --- | | `previous_completion_id` | Continues a stored completion and restores its prior model context, hosted tool calls and server-side context edits included, when the supplied messages extend the stored history. | | Function definitions in `tools` | Gives the model client-executed functions it can call. | | Hosted tool types in `tools` | Opts into server-executed store tools such as `search_corpus`; see [Hosted Tools](https://www.mixedbread.com/docs/agent/hosted-tools). | | `tool_choice` | Lets the model choose automatically, prevents function calls, requires one, or forces a named function or hosted tool. With hosted tools it applies to the first model turn; later turns of the server loop use `auto`. | | `max_tool_calls` | Caps the server-executed tool calls of one completion (default 16); ignored when no hosted tool is declared. | | `response_format` | Constrains the answer to JSON, as in [OpenAI structured outputs](https://platform.openai.com/docs/guides/structured-outputs): `json_object` for any JSON object, or `json_schema` for JSON matching your schema. The final answer is grammar-constrained to the format; tool calls run as usual before it. `strict` is accepted without effect, and the schema is not narrowed to OpenAI's strict subset. | | `context_management` | Opts into server-side context editing; see [managing the context window](https://www.mixedbread.com/docs/agent/hosted-tools#manage-the-context-window). | | `store` | Set to `false` to enable zero data retention. Completion content is not retained, and no retrievable completion is created. Operational model and token metadata is still recorded. | | `include` | Adds hidden fields to hosted call items, e.g. `search_corpus_call.results`. Unsupported values are ignored. | ### Response fields | Field | Behavior | | --- | --- | | `title` | Returns the generated title of a stored conversation. | | `choices[].message.tool_calls` | Returns function calls your application must execute before continuing the conversation. | | `choices[].finish_reason` | `length` also reports a JSON `response_format` the answer still missed after its one regeneration; that answer is withheld and `content` is `null`. | | `choices[].message.reasoning_content` | The model's reasoning content; always `null` for `toast-1`. See [reasoning and thinking](#reasoning-and-thinking). | | `hosted_tool_calls` | Records the server-executed tool calls of a hosted run, in execution order. | | `context_management` | The context edits applied while serving the request; only present when at least one was applied. | | `usage.completion_tokens_details.reasoning_tokens` | Tokens spent on model reasoning; `0` for `toast-1`. | See every request and response field in the [API reference](https://www.mixedbread.com/api-reference/endpoints/chat/create-chat-completion). ## Hosted tools on Chat Completions Declare a hosted store tool and the server runs the whole search loop inside one completion: the model searches your stores, reads the results, and answers in plain text. ```python completion = client.chat.completions.create( model="toast-1", messages=[{"role": "user", "content": "Which suppliers had recalls in 2023?"}], tools=[{"type": "search_corpus", "store_identifiers": ["my-store"]}], ) print(completion.choices[0].message.content) ``` The answer arrives in `choices[].message.content`; the calls the server ran are recorded in `hosted_tool_calls` beside `choices`. The tools behave the same on both APIs: the [Hosted Tools](https://www.mixedbread.com/docs/agent/hosted-tools) page documents the tools, the store scope, `context_management`, and how a run ends, with every request shown in the Chat shape as well. ## Reasoning and thinking Toast 1 has no thinking channel: thinking is disabled at the chat template, and `chat_template_kwargs` is not a parameter of this API (unknown fields are ignored). `reasoning_content` is therefore always `null`, and `usage.completion_tokens_details.reasoning_tokens` is always `0`. A hosted run returns the model's answer in `choices[].message.content`; the tools it ran to get there are recorded in `hosted_tool_calls`. # Hosted Tools URL: https://www.mixedbread.com/docs/agent/hosted-tools Let the server run the search loop over your Stores from the Responses API or Chat Completions. Hosted tools are server-executed store tools. Declare one and the server runs the whole search loop: Toast 1 searches your [Stores](https://www.mixedbread.com/docs/stores/stores), reads the results, searches again if it needs to, and answers in plain text. You send one request and receive the final answer; no tool calls come back for you to execute. The tools behave the same on the [Responses API](https://www.mixedbread.com/docs/agent/responses) and [Chat Completions](https://www.mixedbread.com/docs/agent/chat-completions). This page documents the tools, their scope, the context window, and how a run ends, and shows each request in both shapes. To run the tool loop yourself instead, see [Build Your Own Harness](https://www.mixedbread.com/docs/agent/build-your-own-harness). > **Diagram**: A sequence diagram of the messages between your app, the Mixedbread API and Toast 1, with a toggle between three modes. Hosted tools: your app sends one request declaring `search_corpus`; in a server loop inside the API the model calls `search_corpus`, the API runs it and feeds the results back, again if the model needs to, until the model answers in plain text; one response returns the answer plus `hosted_tool_calls` (one item per call with a `type` such as `search_corpus_call`, an `id` and a `status` of `in_progress`, `completed` or `failed`), and no tool calls come back to you. Function tools: the loop lives in your app; the call comes back as a `function_call` item (Responses API) or a completion with `finish_reason: "tool_calls"` (Chat Completions), your app runs it and sends back `function_call_output` with the same `call_id` or one `role: "tool"` message per `tool_call_id`, and the API adds nothing: no injected prompt or tools, one generation per request. Mixed: hosted calls loop inside the API until the model calls one of your functions, which exits back to your app. At most 8 server-executed calls run per model turn, and `max_tool_calls` (default 16) budgets them all. ## Declare a hosted tool Add a hosted tool type to `tools`. Everything else about the request stays as documented for the endpoint you call. ```python tab="Responses API" response = client.responses.create( model="toast-1", input="Which suppliers had recalls in 2023?", tools=[{"type": "search_corpus", "store_identifiers": ["my-store"]}], ) print(response.output_text) ``` ```python tab="Chat Completions" completion = client.chat.completions.create( model="toast-1", messages=[{"role": "user", "content": "Which suppliers had recalls in 2023?"}], tools=[{"type": "search_corpus", "store_identifiers": ["my-store"]}], ) print(completion.choices[0].message.content) ``` The hosted tools are opt-in: a request that declares none of them is a single model turn, exactly as sent. When they run, every server-executed call is recorded in `hosted_tool_calls`, beside `output` on the Responses API and beside `choices` on Chat Completions: one item per call with its `type` (for example `search_corpus_call`), `id`, `status` (`in_progress`, `completed`, or `failed`), and the call's arguments echoed as fields named for the tool (`queries` for a search, `pattern` for a grep). The chunk results of a call are stored but not returned by default; request them with `include`, e.g. `include=["search_corpus_call.results"]`. Function tools and hosted tools combine freely: your functions still come back as tool calls for your application to execute, while the hosted calls run server-side in the same loop. A function tool that duplicates a hosted tool's name is rejected with a `duplicate_tool_name` validation error. `tool_choice` can force a hosted tool by its type. With hosted tools it applies to the first model turn; later turns of the server loop use `auto`. ## Store scope Every store-scoped tool takes `store_identifiers`, the IDs or names of the stores it runs against, and all declared store tools must share one scope; mixed scopes are rejected with a validation error. An API key restricted to specific stores must cover the scope. To let the model pick the store itself, omit `store_identifiers` and declare `list_stores` alongside (required; the request is rejected without it): ```python tools=[{"type": "search_corpus"}, {"type": "list_stores"}] ``` Each store-scoped tool then takes a required `store` argument: the model discovers your stores with `list_stores` and names exactly one store on every call. `get_chunks` never takes one; its chunk IDs already identify where the run saw them. ## Instructions Your `instructions` (or system/developer messages) are the model's system prompt, passed through as written. A request that declares a hosted tool but sends no instruction text gets this default system message: > You are a search agent over the user's connected stores. Use the search > tools you were given to explore the corpus regarding the user's query. The default is strictly a fallback: any instruction text you send replaces it entirely, and requests without hosted tools never receive it. ## The hosted tools The hosted tools share their names, schemas, and behavior with the open-source [toast-harness repository](https://github.com/mixedbread-ai/toast-harness), the reference for exact schemas, defaults, and truncation behavior. Tool calls are budgeted together by [`max_tool_calls`](#how-a-hosted-run-ends), and at most 8 server-executed calls run per model turn (extra calls receive a structured error result instead of running). Result counts are fixed to the values the model was trained with and are not configurable per request. | Tool | What it does | Per-call limits | | --- | --- | --- | | `search_corpus` | The primary tool: semantic search over the scoped stores. The model phrases natural-language queries. Your `filters` and `score_threshold` apply to every call, invisibly to the model. | 5 chunks per call, each clipped to roughly 2,000 tokens. | | `grep` | Matches a regular expression against the literal chunk text: no embeddings, no reranker. The model reaches for it for rare terms, codes, names, and exact vocabulary. The pattern runs over the full stored text; returned text is windowed to ~100 tokens around each match, with overlapping windows merged. When a grep restricted to one `targets` bucket finds nothing, the other bucket is probed with one result, reported in `targets_note`. | 10 chunks per call. | | `filter_chunks` | Lists chunks by metadata conditions, optionally ordered by a numeric metadata field; no embeddings are involved. A `rank_by` field that turns out non-numeric degrades gracefully: the payload reports `rank_by_applied` and how many values could not be ranked instead of failing the call. | The model picks how many chunks it wants per call (schema default 10, at most 30). Chunk text is clipped to ~2,000 tokens. | | `inspect_metadata` | An overview of the metadata fields and values that exist in the scoped stores, so the model can filter and phrase queries against real values instead of guessing. Reports sampled value types from 100 chunks and lists which fields are numerically rankable (`rankable_fields`) for `filter_chunks`. | 8 representative values per field. | | `get_chunks` | Re-fetches chunks the run has already seen, by their `chunk_id`. The model uses it to re-read a chunk a search returned truncated. Unknown or pruned IDs come back as structured per-ID errors, never a failed call. It has no configuration beyond the shared store scope. | Up to 20 IDs, each chunk returning roughly 8,000 tokens (4× the search clip). | | `list_stores` | A Mixedbread platform tool with no harness counterpart: a paginated listing of the stores the API key can see. | `limit` stores (default 20). | `search_corpus` and `grep` results are deduplicated across the run: chunks the model has already seen come back as compact references, in `deduped_existing_or_deleted` for a search and as `seen: true` entries for a grep. ## Chunk references Every chunk reference in hosted payloads (result entries and the IDs `get_chunks` accepts) has one uniform shape, `chunk_id = ":"`, stable across requests. The `` prefix resolves directly against the [store files API](https://www.mixedbread.com/api-reference/endpoints/stores/files/get-store-file), so your application can fetch the underlying file or chunk with one exact lookup. Each chunk also carries a `document_id` shared by all chunks of the same document, so results can be grouped by it. ## Cited answers Set `citations: true` on `search_corpus`, `grep` or `filter_chunks` and the model cites its evidence as it writes. The markers never reach you: the answer ships as clean text, and the message carries an `annotations` list saying which evidence stood where. ```json { "content": "Create the store from the dashboard or the CLI.", "annotations": [ { "type": "file_citation", "file_id": "5d4c287d-cb15-4b86-a851-8d3e3068a68a", "filename": "blob-overview.md", "index": 46, "chunk_id": "5d4c287d-cb15-4b86-a851-8d3e3068a68a:2", "store_id": "29cd9db8-ea80-48d5-b7af-867f95251914" } ] } ``` The annotation is OpenAI's `file_citation` (`file_id`, `filename`, `index`, the character offset in `content` where the citation sits) plus the chunk it points at: `chunk_id` in the same [chunk reference](#chunk-references) shape every hosted result uses, and `store_id`, which hosted results now carry as well. The cited text and score are on the hosted results; request them with `include` and join on `chunk_id`. A hit of the `mixedbread/web` store is a page, not a file, so it is cited the way OpenAI cites its own web search, as a `url_citation`: ```json { "type": "url_citation", "url": "https://docs.aws.amazon.com/AmazonS3/latest/userguide/example-walkthroughs-managing-access-example2.html", "title": "Example 2: Bucket owner granting cross-account bucket permissions", "start_index": 46, "end_index": 46, "chunk_id": "9c1d0b52-4e1a-5c6f-8a2b-3d4e5f607182:0" } ``` The marker is a point in the answer, so `start_index` and `end_index` coincide. A web hit is not stored, so its `chunk_id` only joins the citation to the hosted result in the same response and cannot be fetched later. A marker on your own function tool's or an MCP server's output is accepted and removed, but carries no annotation. Citations are audited: a marker naming evidence no tool returned is dropped rather than shipped as a pointer to nothing. On the Responses API the annotations sit on the `output_text` part and stream as `response.output_text.annotation.added` events; on Chat Completions they ride the `message` and its streamed `delta`. Send a cited answer back as history with its `annotations` and the model reads it as it wrote it. ## Manage the context window Toast 1 is served with a 131,072-token context window. A long hosted run can approach it; opt-in context editing gives the model room to keep exploring: ```python tab="Responses API" response = client.responses.create( model="toast-1", input="Compare the recall policies of all our suppliers.", tools=[{"type": "search_corpus", "store_identifiers": ["my-store"]}], context_management={"edits": [{"type": "prune_context"}]}, ) ``` ```python tab="Chat Completions" completion = client.chat.completions.create( model="toast-1", messages=[{"role": "user", "content": "Compare the recall policies of all our suppliers."}], tools=[{"type": "search_corpus", "store_identifiers": ["my-store"]}], extra_body={"context_management": {"edits": [{"type": "prune_context"}]}}, ) ``` With it declared, the model gets a `prune_context` tool and calls it to clear tool results it considers stale as the conversation approaches the window. Every tool result it has read, server or client, can be pruned. `context_management` is accepted with any tool set, including pure function-tool requests, and is a no-op until something prunable accumulates. What was edited is reported on the response, and this is the only trace of it you see: - `context_management.applied_edits` carries one `prune_context` entry aggregating the model's prune calls and the input tokens they cleared, and one `truncate_tool_result` entry per **client** tool result the server had to shorten in overflow recovery (with its `tool_call_id`). - The internal result ids and renderings the model prunes by are never returned; your conversation, transcripts, and continuations keep every tool result exactly as sent. - Your function results are never capped by the server outside of overflow recovery, and pruning never rewrites what is stored, only what the model sees. Prune calls count against `max_tool_calls` like every server-handled call. ## How a hosted run ends The loop ends when the model answers in plain text or calls one of your function tools; those calls always come back to you, the search limit included. Two bounds apply to server-executed calls: `max_tool_calls` (default 16) and the context window. When either is reached, the model receives this message once: > You have reached the search limit. Do NOT search further. You must now reply > with your final answer to the user query as plain text, with NO tool calls. > Base it only on retrieved evidence; if the evidence is insufficient to > answer, say so. A plain-text reply completes the response normally with whatever evidence it gathered; a call to one of your function tools is returned to you as usual. If the model does neither, the run ends as it stands: on the Responses API, `status: "incomplete"` with `incomplete_details.reason` set to `"max_tool_calls"` or `"context_window"`; on Chat Completions, `finish_reason: "length"` on the last choice. Either way the response carries whatever text the model produced. The API never writes an answer for the model. > **Diagram**: A decision tree of how a hosted run ends. In the server loop Toast 1 calls hosted tools until it answers in plain text, which completes the response normally, or calls one of your function tools, which returns the call to your app. When a bound on server-executed calls is reached, `max_tool_calls` (default 16, prune calls count) or the 131,072-token context window, the model receives the search limit message once: a plain-text reply completes normally, a function call is returned to your app, and if it does neither the run ends as it stands, with `status: "incomplete"` and `incomplete_details.reason` `"max_tool_calls"` or `"context_window"` on the Responses API, or `finish_reason: "length"` on Chat Completions, carrying whatever text the model produced. The API never writes an answer for the model. A `context_window` ending means the run filled the window before it finished exploring. If your runs hit it, declare [`context_management`](#manage-the-context-window) alongside your search tools to give the model room to prune. ## Streaming Hosted runs stream their progress alongside the endpoint's standard events. When a server-executed call is dispatched, an event carries the call item with `status: "in_progress"`; when its round returns, another carries the finished item. On the Responses API these are `response.output_item.added` and `response.output_item.done` events. The items are a Mixedbread extension: they claim an `output_index` in the shared item order but appear in `hosted_tool_calls`, not `output`, in the terminal payload. On Chat Completions, each call item arrives on a chunk once as `in_progress` and once finished, and `context_management` rides on the final usage chunk. Non-streaming and streaming report identical final content; the hosted call items and their `include` behavior are the same on both surfaces. # OpenCode URL: https://www.mixedbread.com/docs/agent/integrations/opencode Use Toast 1 as a primary model or subagent in OpenCode. Add [Toast 1](https://www.mixedbread.com/docs/agent/models) as a subagent in OpenCode for fast, cheap, and accurate search. ## Prerequisites - [OpenCode](https://opencode.ai/docs/) installed - A Mixedbread API key from the [API Keys](https://platform.mixedbread.com/platform?next=api-keys) page ## Configure Mixedbread ### 1. Add the Mixedbread provider Create or update `opencode.json` in your project root (the directory you open with OpenCode, typically alongside `.git`, `package.json`, or `pyproject.toml`): ```json { "$schema": "https://opencode.ai/config.json", "provider": { "mixedbread": { "npm": "@ai-sdk/openai-compatible", "name": "Mixedbread", "options": { "baseURL": "https://api.mixedbread.com/v1" }, "models": { "toast-1": { "name": "Toast 1", "limit": { "context": 131072, "output": 4096 } } } } } } ``` The provider ID is `mixedbread`, and the model ID is `toast-1`. Together, OpenCode refers to the model as `mixedbread/toast-1`. To make Mixedbread available in every project, put the same configuration in `~/.config/opencode/opencode.json` instead. A project-level `opencode.json` overrides the global configuration. ### 2. Add your API key Start OpenCode and enter: ```text /connect ``` Select **Other**, enter `mixedbread` as the provider ID, then paste your Mixedbread API key. The provider ID must exactly match the key in `opencode.json`. ### 3. Select Toast 1 Enter `/models`, then select **Mixedbread → Toast 1**. To make Toast 1 the default for the project, add the top-level `model` field to `opencode.json`: ```json { "$schema": "https://opencode.ai/config.json", "model": "mixedbread/toast-1" } ``` Merge this field into the provider configuration from the first step. ## Use Toast 1 as a subagent You can keep another model as your primary OpenCode model and use Toast 1 for focused repository investigations. Merge this `agent` entry into your existing `opencode.json`: ```json { "$schema": "https://opencode.ai/config.json", "agent": { "toast": { "description": "Investigates complex repository questions and returns concise, evidence-backed findings", "mode": "subagent", "model": "mixedbread/toast-1", "permission": { "edit": "deny", "bash": "deny" } } } } ``` Invoke the subagent directly with an `@` mention: ```text @toast Trace the authentication flow in this repository and summarize the key files. ``` OpenCode can also delegate to the subagent when its description matches the task. An explicit `@toast` mention is the most predictable way to select it. # Models URL: https://www.mixedbread.com/docs/agent/models Models available through the Mixedbread Agent APIs. Choose a Mixedbread specialized model for knowledge tasks based on your needs. ## Available models **Toast 1** (Specialized search model): Built for knowledge-intensive questions, multi-step retrieval, and evidence synthesis. Toast 1 can work with any backend exposed through function calling. | Model ID | Input | Output | Context window | Max output | | --- | --- | --- | --- | --- | | `toast-1` | Text | Text | 131K tokens | 4K tokens | See [pricing](https://www.mixedbread.com/pricing#pricing-rates) and [hosted tools](https://www.mixedbread.com/docs/agent/hosted-tools). The context window includes input messages, tool definitions, tool results, and generated output. Use `max_output_tokens` with the Responses API or `max_completion_tokens` with Chat Completions to limit generated output. The Responses API and Chat Completions default to `toast-1` when `model` is omitted. # Responses API URL: https://www.mixedbread.com/docs/agent/responses Build agentic workflows with Mixedbread models and the OpenAI-compatible Responses API. The Mixedbread Responses API is an OpenAI-compatible Responses endpoint for Mixedbread specialized models and agentic workflows. It provides a simpler input and output model than Chat Completions, supports stored multi-turn conversations, and works with client-executed function tools. It is also the primary surface for the [hosted store tools](https://www.mixedbread.com/docs/agent/hosted-tools): declare them in `tools` and the server runs the whole search loop for you. You can use the OpenAI SDK by changing `base_url` and `api_key`, then selecting a `model` from the [supported models](https://www.mixedbread.com/docs/agent/models). For message-based integrations, see the [Chat Completions API](https://www.mixedbread.com/docs/agent/chat-completions); to run the tool loop yourself, see [Build Your Own Harness](https://www.mixedbread.com/docs/agent/build-your-own-harness). ## Prerequisite Get a Mixedbread API key from the [API Keys](https://platform.mixedbread.com/platform?next=api-keys) page. A scope-restricted key needs the **Completions** scope for these endpoints; see [API keys](https://www.mixedbread.com/docs/platform/api-keys). You can install the OpenAI SDK or use cURL directly. ```bash tab="Python" pip install openai ``` ```bash tab="TypeScript" npm install openai ``` ```bash tab="cURL" export MXBAI_API_KEY=YOUR_API_KEY ``` ## Make your first request Point `base_url` to Mixedbread, use your Mixedbread API key, and select one [supported model](https://www.mixedbread.com/docs/agent/models). Pass a string or a list of input items to `input`. **Create a response** Python: ```python from openai import OpenAI client = OpenAI( base_url="https://api.mixedbread.com/v1", api_key="YOUR_API_KEY", ) response = client.responses.create( model="toast-1", input="What is a search agent?", ) print(response.output_text) ``` Python (async): ```python from openai import AsyncOpenAI client = AsyncOpenAI( base_url="https://api.mixedbread.com/v1", api_key="YOUR_API_KEY", ) response = await client.responses.create( model="toast-1", input="What is a search agent?", ) print(response.output_text) ``` TypeScript: ```ts import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://api.mixedbread.com/v1", apiKey: "YOUR_API_KEY", }); const response = await client.responses.create({ model: "toast-1", input: "What is a search agent?", }); console.log(response.output_text); ``` cURL: ```bash curl https://api.mixedbread.com/v1/responses \ -H "Authorization: Bearer $MXBAI_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "model": "toast-1", "input": "What is a search agent?" }' ``` The Python and TypeScript SDKs expose the generated text through `response.output_text`. On the wire, generated messages and function calls are separate items in `output`. ## OpenAI compatibility Mixedbread accepts the OpenAI Responses shape for supported fields. The tables below cover important request and response behavior. ### Request fields | Field or value | Behavior | | --- | --- | | `previous_response_id` | Continues a stored response without resending its earlier input items. The new response must also use `store: true` to continue the chain later. | | Function definitions in `tools` | Gives the model client-executed functions it can call. Responses function definitions use a flat shape with `name`, `description`, `parameters`, and `strict`. | | Hosted tool types in `tools` | Opts into server-executed store tools such as `search_corpus`; see [Hosted Tools](https://www.mixedbread.com/docs/agent/hosted-tools). | | `mcp` tools in `tools` | Connects a remote MCP server. Its tools are listed at the start of the response and executed server-side; see [MCP servers](#mcp-servers). | | `tool_choice` | Lets the model choose automatically, prevents tool calls, requires a tool call, or forces a named function, hosted tool, or MCP server's tools (`{"type": "mcp", "server_label": "...", "name": "..."}`). With hosted tools it applies to the first model turn; later turns of the server loop use `auto`. | | `max_tool_calls` | Caps the server-executed tool calls of one response (default 16), MCP calls included; ignored when no hosted tool is declared. | | `text.format` | Constrains the answer to JSON, as in [OpenAI structured outputs](https://platform.openai.com/docs/guides/structured-outputs): `json_object` for any JSON object, or `json_schema` for JSON matching your schema. The final answer is grammar-constrained to the format and `output_text` is the JSON; tool calls run as usual before it. `strict` is accepted without effect, and the schema is not narrowed to OpenAI's strict subset. | | `context_management` | Opts into server-side context editing; see [managing the context window](https://www.mixedbread.com/docs/agent/hosted-tools#manage-the-context-window). | | `store` | Defaults to `true`. Set it to `false` to enable zero data retention. Response content is not retained, and no retrievable response is created. Operational model and token metadata is still recorded. | | `include` | Adds hidden fields to hosted call items, e.g. `search_corpus_call.results`. Unsupported values are ignored. | ### Response fields | Field | Behavior | | --- | --- | | `output` | Contains generated messages, client function calls, and the MCP items `mcp_list_tools`, `mcp_call`, and `mcp_approval_request` in emission order. | | `output_text` | SDK convenience property that joins the generated text from message output items. | | `hosted_tool_calls` | Records the server-executed tool calls of a hosted run, in execution order, beside `output`. | | `error` | Why a response `failed`. With a JSON `text.format`, an answer that still misses the format after its one regeneration is withheld and the response fails with code `response_format` and no message item. | | `incomplete_details.reason` | Why a response ended with `status: "incomplete"`: `max_output_tokens`, `max_tool_calls`, or `context_window`; see [how a hosted run ends](https://www.mixedbread.com/docs/agent/hosted-tools#how-a-hosted-run-ends). | | `context_management` | The context edits applied while serving the request; only present when at least one was applied. | | `usage.output_tokens_details.reasoning_tokens` | Tokens spent on model reasoning; `0` for `toast-1`. See [reasoning and thinking](#reasoning-and-thinking). | | `title` | Returns the generated title of a stored conversation. | Mixedbread currently supports text input and output, JSON output via `text.format`, client-executed function tools, hosted store tools, remote MCP servers, opt-in context editing via `context_management`, and streaming. Background responses, multimodal input, and OpenAI service connectors (`connector_id`) are not supported. Unsupported options return a validation error instead of being ignored. See the advertised request and response fields in the [API reference](https://www.mixedbread.com/api-reference/endpoints/responses/create-response). ## Continue a conversation Responses are stored by default. Pass the previous response ID with only the new input to continue the conversation. Replace `resp_123` with the `id` returned by the previous request. **Continue a response** Python: ```python response = client.responses.create( model="toast-1", input="When should I use one?", previous_response_id="resp_123", ) print(response.output_text) ``` Python (async): ```python response = await client.responses.create( model="toast-1", input="When should I use one?", previous_response_id="resp_123", ) print(response.output_text) ``` TypeScript: ```ts const response = await client.responses.create({ model: "toast-1", input: "When should I use one?", previous_response_id: "resp_123", }); console.log(response.output_text); ``` cURL: ```bash curl https://api.mixedbread.com/v1/responses \ -H "Authorization: Bearer $MXBAI_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "model": "toast-1", "input": "When should I use one?", "previous_response_id": "resp_123" }' ``` Set `store=False` when you do not need retrieval or continuation. Stored responses can be retrieved with `client.responses.retrieve(response.id)`, and their input items can be listed with `client.responses.input_items.list(response.id)`. ## Tool use Toast 1 takes three kinds of tools in `tools`, and they combine freely in one request: functions your application executes, hosted tools the server runs against your Stores, and the tools of a remote MCP server. `tool_choice` applies across all of them, and `max_tool_calls` budgets every server-executed call, hosted and MCP alike. ### Your own tools Function tools let Toast 1 request data or actions from your application. The model returns a `function_call` output item with JSON-encoded arguments. Execute the function in your application, then send a `function_call_output` item with the same `call_id` to receive the final answer. **Connect a search function** Python: ```python import json from openai import OpenAI client = OpenAI( base_url="https://api.mixedbread.com/v1", api_key="YOUR_API_KEY", ) def search_documents(query: str) -> list[dict[str, str]]: return [ { "title": "Search agents", "text": f'Search agents plan queries like "{query}", inspect evidence, and synthesize an answer.', } ] tools = [ { "type": "function", "name": "search_documents", "description": "Search the application's documents for relevant passages.", "parameters": { "type": "object", "properties": { "query": { "type": "string", "description": "The search query.", } }, "required": ["query"], }, "strict": False, } ] response = client.responses.create( model="toast-1", input="What is a search agent? Use search_documents.", tools=tools, tool_choice={"type": "function", "name": "search_documents"}, parallel_tool_calls=False, ) tool_call = next(item for item in response.output if item.type == "function_call") result = search_documents(**json.loads(tool_call.arguments)) final_response = client.responses.create( model="toast-1", previous_response_id=response.id, input=[ { "type": "function_call_output", "call_id": tool_call.call_id, "output": json.dumps(result), } ], tools=tools, tool_choice="none", ) print(final_response.output_text) ``` Python (async): ```python import json from openai import AsyncOpenAI client = AsyncOpenAI( base_url="https://api.mixedbread.com/v1", api_key="YOUR_API_KEY", ) async def search_documents(query: str) -> list[dict[str, str]]: return [ { "title": "Search agents", "text": f'Search agents plan queries like "{query}", inspect evidence, and synthesize an answer.', } ] tools = [ { "type": "function", "name": "search_documents", "description": "Search the application's documents for relevant passages.", "parameters": { "type": "object", "properties": { "query": { "type": "string", "description": "The search query.", } }, "required": ["query"], }, "strict": False, } ] response = await client.responses.create( model="toast-1", input="What is a search agent? Use search_documents.", tools=tools, tool_choice={"type": "function", "name": "search_documents"}, parallel_tool_calls=False, ) tool_call = next(item for item in response.output if item.type == "function_call") result = await search_documents(**json.loads(tool_call.arguments)) final_response = await client.responses.create( model="toast-1", previous_response_id=response.id, input=[ { "type": "function_call_output", "call_id": tool_call.call_id, "output": json.dumps(result), } ], tools=tools, tool_choice="none", ) print(final_response.output_text) ``` TypeScript: ```ts import OpenAI from "openai"; import type { Responses } from "openai/resources/responses/responses"; const client = new OpenAI({ baseURL: "https://api.mixedbread.com/v1", apiKey: "YOUR_API_KEY", }); function searchDocuments(query: string): Array> { return [ { title: "Search agents", text: `Search agents plan queries like "${query}", inspect evidence, and synthesize an answer.`, }, ]; } const tools: Responses.Tool[] = [ { type: "function", name: "search_documents", description: "Search the application's documents for relevant passages.", parameters: { type: "object", properties: { query: { type: "string", description: "The search query.", }, }, required: ["query"], }, strict: false, }, ]; const response = await client.responses.create({ model: "toast-1", input: "What is a search agent? Use search_documents.", tools, tool_choice: { type: "function", name: "search_documents" }, parallel_tool_calls: false, }); const toolCall = response.output.find((item) => item.type === "function_call"); if (!toolCall) { throw new Error("The model did not call search_documents."); } const { query } = JSON.parse(toolCall.arguments) as { query: string }; const result = searchDocuments(query); const finalResponse = await client.responses.create({ model: "toast-1", previous_response_id: response.id, input: [ { type: "function_call_output", call_id: toolCall.call_id, output: JSON.stringify(result), }, ], tools, tool_choice: "none", }); console.log(finalResponse.output_text); ``` The example forces one call for a deterministic first turn, executes the application-owned search function, and sets `tool_choice="none"` on the second turn so Toast 1 produces the answer from the returned results. In production, the function can call any search engine, database, or internal API. ### Hosted tools Declare a hosted store tool and the server runs the whole search loop: Toast 1 searches your [Stores](https://www.mixedbread.com/docs/stores/stores), reads the results, searches again if it needs to, and answers in plain text. You send one request and receive the final answer; no tool calls come back for you to execute. ```python response = client.responses.create( model="toast-1", input="Which suppliers had recalls in 2023?", tools=[{"type": "search_corpus", "store_identifiers": ["my-store"]}], ) print(response.output_text) ``` The answer arrives as `message` output items; the calls the server ran are recorded in `hosted_tool_calls` beside `output`. The [Hosted Tools](https://www.mixedbread.com/docs/agent/hosted-tools) page documents the tools, the store scope, `context_management`, and how a run ends. ### MCP servers The `mcp` tool gives Toast 1 the tools of a remote [Model Context Protocol](https://modelcontextprotocol.io) server over its Streamable HTTP transport. Declare the server with a `server_label` and an HTTPS `server_url`; pass `headers` or an OAuth `authorization` token when the server needs them. Mixedbread lists the server's tools when the response starts, offers them to the model, and runs the calls the model makes. **Use an MCP server** Python: ```python response = client.responses.create( model="toast-1", input="What does the mixedbread-ai/mixedbread repo do?", tools=[ { "type": "mcp", "server_label": "deepwiki", "server_url": "https://mcp.deepwiki.com/mcp", "require_approval": "never", } ], ) print(response.output_text) ``` Python (async): ```python response = await client.responses.create( model="toast-1", input="What does the mixedbread-ai/mixedbread repo do?", tools=[ { "type": "mcp", "server_label": "deepwiki", "server_url": "https://mcp.deepwiki.com/mcp", "require_approval": "never", } ], ) print(response.output_text) ``` TypeScript: ```ts const response = await client.responses.create({ model: "toast-1", input: "What does the mixedbread-ai/mixedbread repo do?", tools: [ { type: "mcp", server_label: "deepwiki", server_url: "https://mcp.deepwiki.com/mcp", require_approval: "never", }, ], }); console.log(response.output_text); ``` cURL: ```bash curl https://api.mixedbread.com/v1/responses \ -H "Authorization: Bearer $MXBAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "toast-1", "input": "What does the mixedbread-ai/mixedbread repo do?", "tools": [{ "type": "mcp", "server_label": "deepwiki", "server_url": "https://mcp.deepwiki.com/mcp", "require_approval": "never" }] }' ``` The response records the MCP work as output items: one `mcp_list_tools` item per server, then an `mcp_call` item for each call with its `arguments`, `output`, and `error`. Streaming emits the `response.mcp_list_tools.*` and `response.mcp_call.*` events around them. Use `allowed_tools` to offer only some of the server's tools, by name or with `{"read_only": true}`. Mixedbread speaks the MCP Streamable HTTP transport and the `initialize`, `tools/list` and `tools/call` methods. The legacy HTTP+SSE transport, MCP resources, prompts and elicitation, and OpenAI service connectors (`connector_id`) are not supported. #### Approve calls As in the OpenAI API, `require_approval` defaults to `always`: instead of running a call, the response ends with an `mcp_approval_request` item carrying the tool name and arguments. Answer it on the next request with an `mcp_approval_response` item. An approved call runs before the model continues; a rejected one is reported to the model with your `reason`. **Approve an MCP call** Python: ```python # The first response ends with an approval request instead of running the call. approval = next(item for item in response.output if item.type == "mcp_approval_request") print(approval.name, approval.arguments) # Approve (or reject) it on the next request; the call runs before the model continues. response = client.responses.create( model="toast-1", previous_response_id=response.id, input=[{"type": "mcp_approval_response", "approval_request_id": approval.id, "approve": True}], tools=[{"type": "mcp", "server_label": "deepwiki", "server_url": "https://mcp.deepwiki.com/mcp"}], ) print(response.output_text) ``` TypeScript: ```ts // The first response ends with an approval request instead of running the call. const approval = response.output.find((item) => item.type === "mcp_approval_request"); console.log(approval.name, approval.arguments); // Approve (or reject) it on the next request; the call runs before the model continues. const next = await client.responses.create({ model: "toast-1", previous_response_id: response.id, input: [{ type: "mcp_approval_response", approval_request_id: approval.id, approve: true }], tools: [{ type: "mcp", server_label: "deepwiki", server_url: "https://mcp.deepwiki.com/mcp" }], }); console.log(next.output_text); ``` Set `require_approval` to `never`, or to a filter such as `{"never": {"tool_names": ["ask_question"]}}`, for tools that can run without a check. Declare the server on every request, including continuations: the `headers` and `authorization` values are used for that response only and are never stored or echoed back. ## Streaming Set `stream: true` to receive the standard OpenAI semantic events (`response.created`, `response.output_item.added`, `response.output_text.delta`, …) and a terminal `response.completed` (or `response.incomplete`) event carrying the full final response, `context_management` included. Hosted runs also stream their progress as `response.output_item.added` and `response.output_item.done` events carrying the call items; see [streaming hosted runs](https://www.mixedbread.com/docs/agent/hosted-tools#streaming). ## Reasoning and thinking Toast 1 has no thinking channel: thinking is disabled at the chat template, and `chat_template_kwargs` is not a parameter of this API. The response emits no `reasoning` output items, and `usage.output_tokens_details.reasoning_tokens` is always `0`. A hosted run returns the model's answer as `message` output items in `output`; the tools it ran to get there are recorded in `hosted_tool_calls`. # Bridge URL: https://www.mixedbread.com/docs/bridge Connect your users' Gmail, Google Drive, Slack, and Granola accounts under your own OAuth apps and drive sync and search from your platform. Bridge runs Gmail, Google Drive, Slack, and Granola connections for your users under your own OAuth apps. Your backend calls the API with one organization API key; users consent on Google or Slack and return to your platform. > **Note** > > Bridge is in beta and available on request. > [Request access](mailto:support@mixedbread.com?subject=Enable%20data%20sources) and we'll enable it for your organization. > **Diagram**: Sequence diagram of the Gmail connect flow between the user's browser, your backend, the Mixedbread API, and Google. 1. Your backend to Mixedbread API: Get the OAuth URL with your organization API key (GET /v1/integrations/gmail/oauth/authorize?store_name=mail-42&reference=user-42), which returns a redirect URL. 2. Your backend to User's browser: Send the browser to that URL. 3. User's browser to Google: The user consents. 4. Google to Mixedbread API: Call the Mixedbread callback (https://api.mixedbread.com/v1/integrations/gmail/oauth/callback). 5. Mixedbread API to User's browser: Redirect to your Return URL. 6. User's browser to Your backend: Arrive at your Return URL (https://platform.example.com/connected?provider=gmail&status=connected&installation_id=…&reference=user-42). On failure (?status=error&error=access_denied&reference=user-42). 7. Your backend: Store installation_id against your user. Mixedbread keeps no link between your users and their installations. 8. Your backend to Mixedbread API: Read the store id (GET /v1/integrations/installations/{installation_id}), which returns store_id and status: "active". 9. Your backend to Mixedbread API: Start the sync (POST /v1/integrations/installations/{installation_id}/sync with {"sync_all": true}). Or select resources by id (PUT /v1/integrations/installations/{installation_id}/resources). 10. Your backend to Mixedbread API: Monitor the sync, then search the user's store (POST /v1/stores/search). ## OAuth setup Register your apps once per organization under **Bridge → Apps** in the dashboard. Each card's dialog shows the redirect URI and, for Slack, the manifest to copy. The scopes and events each app needs are listed under [Scopes and events](#scopes-and-events) and returned by [List OAuth Clients](https://www.mixedbread.com/api-reference/endpoints/integrations/list-oauth-clients) as `required_scopes`. | App | Secrets you enter | Where they come from | | --- | --- | --- | | Gmail | Client ID, Client secret, Return URL | A [Google Auth Platform OAuth client](https://console.cloud.google.com/auth/clients) (Web application) with the [Gmail API enabled](https://console.cloud.google.com/apis/library/gmail.googleapis.com) and the dialog's redirect URI authorized. | | Google Drive | Client ID, Client secret, Return URL | The same Google client or another one, with the [Google Drive API enabled](https://console.cloud.google.com/apis/library/drive.googleapis.com) and the Drive redirect URI authorized. | | Slack | Client ID, Client secret, Signing secret, Return URL | A Slack app created **From a manifest** on [Slack's app creation page](https://api.slack.com/apps?new_app=1) with the manifest in the dialog. Credentials are under **Basic Information → App Credentials** in the [Slack app dashboard](https://api.slack.com/apps). | | Granola | None | Each user pastes a personal Granola API key into your platform. | Gmail and Google Drive are separate apps: enter one Google client on both cards or a different client on each. A shared client needs both redirect URIs authorized. Set the user type and publish the app on [Google Auth Platform's Audience page](https://console.cloud.google.com/auth/audience); an app left in Testing gets refresh tokens that expire after 7 days. ### Use an existing app You can register an OAuth app you already operate instead of creating a new one. Configure it at the provider first, keeping everything the app already has, then enter its credentials under **Bridge → Apps**. Connections made through another app must reconnect afterwards. #### Google (Gmail, Google Drive) #### 1. Check the client type In [Google Auth Platform → Clients](https://console.cloud.google.com/auth/clients), open the client. It must be a **Web application** client. #### 2. Add the redirect URI Under **Authorized redirect URIs**, add the URI for each connector the client serves: | Connector | Redirect URI | | --- | --- | | Gmail | `https://api.mixedbread.com/v1/integrations/gmail/oauth/callback` | | Google Drive | `https://api.mixedbread.com/v1/integrations/google_drive/oauth/callback` | Google can take a few minutes to apply the change. #### 3. Enable the API Enable the [Gmail API](https://console.cloud.google.com/apis/library/gmail.googleapis.com) or the [Google Drive API](https://console.cloud.google.com/apis/library/drive.googleapis.com) on the client's project. #### 4. Add the scope For an External app, add the scope under [Google Auth Platform → Data Access](https://console.cloud.google.com/auth/scopes) and complete verification if Google requires it: | Connector | Scope | | --- | --- | | Gmail | `https://www.googleapis.com/auth/gmail.readonly` | | Google Drive | `https://www.googleapis.com/auth/drive.readonly` | An Internal app needs no scope list. Either way, publish the app on the [Audience page](https://console.cloud.google.com/auth/audience): an app left in Testing gets refresh tokens that expire after 7 days. #### Slack #### 1. Add the redirect URL In the [Slack app dashboard](https://api.slack.com/apps), open the app, then **OAuth & Permissions → Redirect URLs**, and add: ``` https://api.mixedbread.com/v1/integrations/slack/oauth/callback ``` #### 2. Add the scopes On the same page, under **Scopes**: | Section | Scopes | | --- | --- | | User Token Scopes | `channels:history`, `channels:read`, `files:read`, `groups:history`, `groups:read`, `im:history`, `im:read`, `mpim:history`, `mpim:read`, `users:read` | | Bot Token Scopes | `users:read`, `users:read.email` | #### 3. Subscribe to events Under **Event Subscriptions**, enable events and set the **Request URL** to: ``` https://api.mixedbread.com/v1/integrations/slack/events ``` Slack verifies the URL when you save it. Then, under **Subscribe to events on behalf of users**, add: `message.channels`, `message.groups`, `message.im`, `message.mpim`, `channel_created`, `channel_rename`, `channel_archive`, `channel_unarchive`, `channel_deleted`, `member_joined_channel`, `member_left_channel`. #### 4. Reinstall the app Slack requires a reinstall after scopes change. Existing Bridge connections must then reconnect. ### Return URL The page on your platform where users land after consent, for example `https://platform.example.com/connected` (`http://localhost` is allowed for development). The callback appends these query parameters: | Parameter | Value | | --- | --- | | `provider` | `gmail`, `google_drive`, or `slack` | | `status` | `connected` or `error` | | `installation_id` | The installation that was created or reconnected, when `status=connected`. Store it against your user. | | `error` | Why consent failed, when `status=error` | | `reference` | The `reference` you passed to authorize, unchanged, on both outcomes | | `error` | Meaning | | --- | --- | | `access_denied` | The user declined consent | | `missing_code` | The provider returned no authorization code | | `workspace_already_connected` | Slack workspace bot (dashboard only): another Mixedbread organization installed the workspace's bot. Personal installations are not affected. | | `store_in_use` | The store already receives data from another installation of the same account | | `store_exists` | `new_store` was set and a store named `store_name` already exists | | `new_store_on_refresh` | `new_store` was set on a connect that refreshes an existing installation | | `store_change_on_refresh` | `store_name` named a store other than the installation's own on a connect that refreshes it | | `reconnect_account_mismatch` | A reconnect was authorized with a different account than the installation's | | `scope_not_granted` | The user unticked a scope on Google's consent screen. Start again and leave every scope ticked. | | `invalid_state` | The consent link expired or was reused. Start again. | | `token_exchange_failed` | Google rejected the code. Check the client secret and the redirect URI. | | `callback_failed` | Anything else | ### Scopes and events Consent asks for exactly these scopes. A Google app requests them at authorization time, so nothing is configured on the client, but the consent screen must list them if it is published with a scope list. A Slack app must declare them on the app itself; the manifest does. | App | Scopes | | --- | --- | | Gmail | `https://www.googleapis.com/auth/gmail.readonly` | | Google Drive | `https://www.googleapis.com/auth/drive.readonly` | | Slack, user token | `channels:history`, `channels:read`, `files:read`, `groups:history`, `groups:read`, `im:history`, `im:read`, `mpim:history`, `mpim:read`, `users:read` | | Slack, bot token | `users:read`, `users:read.email` | Slack is not polled. After the first sync, new and edited messages reach a user's store only through the [Slack Events API](https://docs.slack.dev/apis/events-api/), so the app must also deliver events to Mixedbread: | Setting | Value | | --- | --- | | Request URL | `https://api.mixedbread.com/v1/integrations/slack/events` | | User events | `message.channels`, `message.groups`, `message.im`, `message.mpim`, `channel_created`, `channel_rename`, `channel_archive`, `channel_unarchive`, `channel_deleted`, `member_joined_channel`, `member_left_channel` | An app created from the manifest in the dashboard has the scopes and the events already. See [Slack's app manifest guide](https://docs.slack.dev/app-manifests/configuring-apps-with-app-manifests/) if you need to review or update the configuration. If you create the app by hand or reuse an existing app, open it in the [Slack app dashboard](https://api.slack.com/apps), keep the required scopes and redirect URL under **OAuth & Permissions**, and keep the request URL and events under **Event Subscriptions**; Slack verifies the request URL when it is saved. Every event is checked against the signing secret you registered, so after rotating the secret in Slack, update the app under **Bridge → Apps** or events are rejected and stores stop receiving new messages. ## API reference ### OAuth clients | Endpoint | Method | Path | | --- | --- | --- | | [List OAuth Clients](https://www.mixedbread.com/api-reference/endpoints/integrations/list-oauth-clients) | `GET` | `/v1/integrations/oauth-clients` | | [Register OAuth Client](https://www.mixedbread.com/api-reference/endpoints/integrations/register-oauth-client) | `PUT` | `/v1/integrations/oauth-clients/{provider}` | | [Delete OAuth Client](https://www.mixedbread.com/api-reference/endpoints/integrations/delete-oauth-client) | `DELETE` | `/v1/integrations/oauth-clients/{provider}` | | [List OAuth Client Connections](https://www.mixedbread.com/api-reference/endpoints/integrations/list-oauth-client-connections) | `GET` | `/v1/integrations/oauth-clients/{provider}/connections` | ### Connect | Endpoint | Method | Path | | --- | --- | --- | | [Authorize Gmail](https://www.mixedbread.com/api-reference/endpoints/integrations/authorize-gmail) | `GET` | `/v1/integrations/gmail/oauth/authorize` | | [Authorize Google Drive](https://www.mixedbread.com/api-reference/endpoints/integrations/authorize-google-drive) | `GET` | `/v1/integrations/google_drive/oauth/authorize` | | [Authorize Slack](https://www.mixedbread.com/api-reference/endpoints/integrations/authorize-slack) | `GET` | `/v1/integrations/slack/oauth/authorize` | | [Connect Granola](https://www.mixedbread.com/api-reference/endpoints/integrations/connect-granola) | `POST` | `/v1/integrations/granola/connect` | | [Reconnect Granola](#reconnect-granola) | `POST` | `/v1/integrations/granola/installations/{installation_id}/reconnect` | | [Reconnect Gmail](https://www.mixedbread.com/api-reference/endpoints/integrations/reconnect-gmail) | `GET` | `/v1/integrations/gmail/installations/{installation_id}/oauth/authorize` | | [Reconnect Google Drive](https://www.mixedbread.com/api-reference/endpoints/integrations/reconnect-google-drive) | `GET` | `/v1/integrations/google_drive/installations/{installation_id}/oauth/authorize` | | [Reconnect Slack](https://www.mixedbread.com/api-reference/endpoints/integrations/reconnect-slack) | `GET` | `/v1/integrations/slack/installations/{installation_id}/oauth/authorize` | ### Installations | Endpoint | Method | Path | | --- | --- | --- | | [List Installations](https://www.mixedbread.com/api-reference/endpoints/integrations/list-installations) | `GET` | `/v1/integrations/installations` | | [Get Installation](https://www.mixedbread.com/api-reference/endpoints/integrations/get-installation) | `GET` | `/v1/integrations/installations/{installation_id}` | | [Disconnect Installation](https://www.mixedbread.com/api-reference/endpoints/integrations/disconnect-installation) | `DELETE` | `/v1/integrations/installations/{installation_id}` | | [Sync Installation](https://www.mixedbread.com/api-reference/endpoints/integrations/sync-installation) | `POST` | `/v1/integrations/installations/{installation_id}/sync` | | [Update Installation Schedule](https://www.mixedbread.com/api-reference/endpoints/integrations/update-installation-schedule) | `PUT` | `/v1/integrations/installations/{installation_id}/schedule` | | [Replace Resources](https://www.mixedbread.com/api-reference/endpoints/integrations/replace-resources) | `PUT` | `/v1/integrations/installations/{installation_id}/resources` | | [List Failed Resources](https://www.mixedbread.com/api-reference/endpoints/integrations/list-failed-resources) | `GET` | `/v1/integrations/installations/{installation_id}/resources/failed` | | [Refresh Resources](https://www.mixedbread.com/api-reference/endpoints/integrations/refresh-resources) | `POST` | `/v1/integrations/installations/{installation_id}/resources/refresh` | ### Stores | Endpoint | Method | Path | | --- | --- | --- | | [Get Store](https://www.mixedbread.com/api-reference/endpoints/stores/manage/get-store) | `GET` | `/v1/stores/{store_identifier}` | | [List Store Files](https://www.mixedbread.com/api-reference/endpoints/stores/files/list-store-files) | `POST` | `/v1/stores/{store_identifier}/files/list` | | [Search Chunks](https://www.mixedbread.com/api-reference/endpoints/stores/search/search-chunks) | `POST` | `/v1/stores/search` | ## Stores and installations An installation is one connected account feeding one store. Every connect creates an installation; to refresh an existing one, [reconnect](#reconnect) it. Every connect endpoint takes `store_name` and `new_store`. ### Shared stores Stores are shared. `store_name` may name a store that already exists, including one that other data sources already feed. Connect a user's Gmail and Slack with the same `store_name` and both ingest into one store, searched with one store id: ```bash curl -s -o /dev/null -w '%{redirect_url}' \ 'https://api.mixedbread.com/v1/integrations/gmail/oauth/authorize?store_name=user-42&reference=user-42' \ -H 'Authorization: Bearer YOUR_API_KEY' curl -s -o /dev/null -w '%{redirect_url}' \ 'https://api.mixedbread.com/v1/integrations/slack/oauth/authorize?store_name=user-42&reference=user-42' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` The one exception: two installations of the same account cannot feed the same store, because every item would be ingested twice. That connect fails with `409`, or `error=store_in_use` on the return URL. Without `store_name`, the installation ingests into the account's default store, for example `gmail-`. Connecting the same account again without `store_name` numbers the default (`gmail--2`, `-3`, …) past any store another installation of the account feeds. ### Several installations of one account Each installation has its own store and its own selection, so one account can be split across stores. A Slack user can, for example, keep public channels in one store and direct and group messages in another: connect twice with different `store_name`s, then select the `public_channels` alias on the first installation and the `direct_messages` and `group_messages` aliases on the second (see [Replace Resources](https://www.mixedbread.com/api-reference/endpoints/integrations/replace-resources)). Slack events fan out to every installation whose selection covers the conversation, each ingesting into its own store. The same account can also be connected in several Mixedbread organizations; each organization's installation is its own, with its own store and selection. Disconnecting one installation keeps the provider grant while another installation of the account still uses it, in any organization. ### New stores `new_store=true` ingests into a store created for this connection. When `store_name` names a store that already exists, the connect fails with `409`, or `error=store_exists` on the return URL. Without `store_name`, the default name is numbered past every store that exists. A reconnect keeps the installation's store, so it cannot set `new_store` (`422`, or `error=new_store_on_refresh` on the return URL) or name another store in `store_name` (`422`, or `error=store_change_on_refresh`). ### Reconnect Reconnecting refreshes one installation's credentials and keeps its store, for example after the installation reports `status: "needs_reauth"`: ```bash curl -s -o /dev/null -w '%{redirect_url}' \ 'https://api.mixedbread.com/v1/integrations/gmail/installations/INSTALLATION_ID/oauth/authorize?reference=user-42' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` Google Drive and Slack have the same route under `google_drive` and `slack`. The user must authorize the account already connected to the installation; consent for any other account returns `error=reconnect_account_mismatch`. The `installation_id` query parameter on [Authorize Gmail](https://www.mixedbread.com/api-reference/endpoints/integrations/authorize-gmail) and [Authorize Google Drive](https://www.mixedbread.com/api-reference/endpoints/integrations/authorize-google-drive) still reconnects but is deprecated in favour of this route. Granola reconnects with a new API key instead of consent; see [Reconnect Granola](#reconnect-granola). ## Gmail ### 1. Get the OAuth URL ```bash curl -s -o /dev/null -w '%{redirect_url}' \ 'https://api.mixedbread.com/v1/integrations/gmail/oauth/authorize?store_name=mail-42&reference=user-42' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` Redirect the browser to the printed URL. `store_name` names the user's store; omit it for `gmail-`. It may name a store the user's other data sources already feed; see [Shared stores](#shared-stores). `reference` is any value up to 255 characters, for example your user id; it comes back unchanged on the return URL, so the return can be matched to the user who started the flow without depending on a browser session. ### 2. Handle the return The browser arrives at `https://platform.example.com/connected?provider=gmail&status=connected&installation_id=…&reference=user-42`. Store `installation_id` against your user, then read the store id: ```bash curl https://api.mixedbread.com/v1/integrations/installations/INSTALLATION_ID \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ```json { "data": { "installation_id": "2f1c9a8e-6b4d-4e3a-9c1f-7d8e5b6a4c21", "provider": "gmail", "status": "active", "account": { "id": "olivia@example.com", "name": "olivia@example.com", "email": "olivia@example.com", "workspace": null }, "store_id": "5d3e7f9a-1b2c-4d6e-8f0a-9c8b7a6d5e4f", "store_name": "mail-42", "sync": { "failed_resource_count": 0, "last_error": null, "last_error_operation": null, "last_error_at": null } } } ``` Keep `installation_id` and `store_id` per user. Mixedbread keeps no link between your users and their installations. ### 3. Start the sync ```bash curl -X POST https://api.mixedbread.com/v1/integrations/installations/INSTALLATION_ID/sync \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -d '{"sync_all": true}' ``` Every message outside spam, trash, and drafts is imported, and new mail is picked up every ten minutes. To sync selected labels instead, list them and replace the selection: ```bash curl https://api.mixedbread.com/v1/integrations/installations/INSTALLATION_ID/resources \ -H 'Authorization: Bearer YOUR_API_KEY' curl -X PUT https://api.mixedbread.com/v1/integrations/installations/INSTALLATION_ID/resources \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -d '{"resource_ids": ["INBOX", "Label_12"]}' ``` ### 4. Monitor the sync ```bash # installation status and account-level errors curl https://api.mixedbread.com/v1/integrations/installations/INSTALLATION_ID \ -H 'Authorization: Bearer YOUR_API_KEY' # per-resource outcome in resources[].sync.last_run curl https://api.mixedbread.com/v1/integrations/installations/INSTALLATION_ID/resources \ -H 'Authorization: Bearer YOUR_API_KEY' # resources whose last job failed curl https://api.mixedbread.com/v1/integrations/installations/INSTALLATION_ID/resources/failed \ -H 'Authorization: Bearer YOUR_API_KEY' # files ingested so far, in file_counts curl https://api.mixedbread.com/v1/stores/STORE_ID \ -H 'Authorization: Bearer YOUR_API_KEY' ``` `status: "needs_reauth"` on the installation means the user must consent again: [reconnect](#reconnect) the installation through `/v1/integrations/gmail/installations/INSTALLATION_ID/oauth/authorize`, which keeps its store. `last_run.status` is `in_progress`, `completed`, `failed`, or `stale`; a large mailbox stays `in_progress` across slices until the label is done. To list individual files, use [List Store Files](https://www.mixedbread.com/api-reference/endpoints/stores/files/list-store-files). ### 5. Search ```bash curl -X POST https://api.mixedbread.com/v1/stores/search \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -d '{"query": "renewal terms", "store_identifiers": ["STORE_ID"], "top_k": 10}' ``` Pass only the store ids that belong to the signed-in user. The organization key can search every store. ## Google Drive Same flow as Gmail with `/v1/integrations/google_drive/oauth/authorize`. Sync the whole Drive: ```bash curl -X POST https://api.mixedbread.com/v1/integrations/installations/INSTALLATION_ID/sync \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -d '{"sync_all": true}' ``` Differences: - `sync_all` runs one job over the whole Drive, *Shared with me* included, and registers push notifications for changes. `queued_resource_ids` is empty and the root folders keep `last_run: null`; watch `file_counts` on the store instead. Shared drives are not part of it: select the *Shared drives* resource to sync those. - Resources are hierarchical: list a folder's children with `?parent_id=FOLDER_ID`. Selecting a folder syncs its subtree. - The root listing holds *My Drive*, *Shared with me*, and *Shared drives* when the account is a member of any. The last two are folders like the others: selecting one syncs everything it holds now and later, and selecting a single shared drive under it syncs only that drive. The two do not overlap — a file that lives in a shared drive is synced through that drive, even when it was also shared with the account directly. - `google_drive.folder_path` on a store file is the location the user recognises, rooted at the scope the file came from: `My Drive/Reports/2026` or `Shared drives/Engineering/Specs`. - Files Drive cannot export (unsupported types, empty files) are skipped, not failed. - Reconnect after `needs_reauth` through `/v1/integrations/google_drive/installations/INSTALLATION_ID/oauth/authorize` with the same Google account. ## Slack Same flow with `/v1/integrations/slack/oauth/authorize`. Sync every conversation the user can read: ```bash curl -X POST https://api.mixedbread.com/v1/integrations/installations/INSTALLATION_ID/sync \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -d '{"sync_all": true}' ``` Differences: - Users connect as themselves (`access_mode=user`, the default), each with their own installation and store. `account.workspace` holds the workspace name. Only user mode is accepted over the API: a request with `access_mode=bot` is rejected with `403`, because a bot installation joins the whole workspace and every selected channel, which your users cannot see or consent to. Workspace bots are installed from the dashboard only. - `sync_all` selects all four conversation kinds below. Public channels are ingested whether or not the user has joined them, as the user can read them in Slack. - New messages arrive only through [Slack events](#scopes-and-events); there is no schedule to set. - Reconnect through `/v1/integrations/slack/installations/INSTALLATION_ID/oauth/authorize` as the same Slack user. ### Conversation kinds A Slack selection is made of aliases, one per kind of conversation, plus any individual conversations. An alias covers every conversation of its kind the user can read, including ones that appear later. The listing's `aliases` names them: | Alias | Covers | |---|---| | `public_channels` | Every public channel in the workspace, joined or not | | `private_channels` | Private channels the user is in | | `direct_messages` | The user's direct messages | | `group_messages` | Group direct messages | To sync only private conversations, plus one public channel the user cares about: ```bash curl -X PUT https://api.mixedbread.com/v1/integrations/installations/INSTALLATION_ID/resources \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -d '{ "resource_aliases": ["private_channels", "direct_messages", "group_messages"], "resource_ids": ["C0123ABC"] }' ``` The request replaces the whole selection: aliases and conversations not listed stop syncing, and what was already imported stays in the store. The listing reports the result as `selected_resource_aliases`, flags each alias with `is_selected`, and sets `sync_all` to `true` only while all four are selected: ```json { "aliases": [ { "id": "public_channels", "name": "Public channels", "kind": "channel", "is_selected": false }, { "id": "private_channels", "name": "Private channels", "kind": "private_channel", "is_selected": true }, { "id": "direct_messages", "name": "Direct messages", "kind": "direct_message", "is_selected": true }, { "id": "group_messages", "name": "Group messages", "kind": "group_message", "is_selected": true } ], "selected_resource_aliases": ["private_channels", "direct_messages", "group_messages"], "selected_resource_ids": ["C0123ABC"], "sync_all": false } ``` How conversations enter a selected alias: - Right after connecting, the conversation catalog is still being built: the listing reports `listing_status: "loading"`, and a selection saved meanwhile is applied when the walk completes. - Channels the user creates, joins, or unarchives are added from Slack events, their history is imported, and they stay current. A private channel the user leaves stops syncing the same way. - A public channel the user has not joined is imported in full and kept current from Slack events, like any other selected conversation. - Slack sends no event when a direct message or group message is opened, so one is added when its first message arrives. That message and the rest of the conversation are imported with it. - A channel that turns private or public moves to the other kind: it starts syncing if that alias is selected and stops if not. A conversation selected by ID keeps syncing whatever its kind. - [Refresh Resources](https://www.mixedbread.com/api-reference/endpoints/integrations/refresh-resources) rebuilds the whole catalog on demand, for example after a long outage of your events endpoint. ## Granola No OAuth. Connect with the user's API key and state who it belongs to: ```bash curl -X POST https://api.mixedbread.com/v1/integrations/granola/connect \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -d '{ "api_key": "GRANOLA_API_KEY", "account_name": "Olivia Chen", "account_email": "olivia@example.com", "store_name": "notes-42" }' ``` The response has the shape of [Get Installation](https://www.mixedbread.com/api-reference/endpoints/integrations/get-installation): `data.installation_id` and `data.store_id`. An invalid key returns `422`. Sync every note: ```bash curl -X POST https://api.mixedbread.com/v1/integrations/installations/INSTALLATION_ID/sync \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -d '{"sync_all": true}' ``` Then monitor and search as in steps 4 and 5 of the Gmail flow. Differences: - `sync_all` imports every note the key can see. Mixedbread registers and manages a Granola webhook for each installation, so generated and edited notes arrive as Granola sends them; your platform configures nothing. Deleted notes, which Granola sends no event for, are caught by polling every ten minutes by default; change the cadence with [Update Installation Schedule](https://www.mixedbread.com/api-reference/endpoints/integrations/update-installation-schedule): `off`, `ten_minutes`, `hourly`, `daily`, or `weekly`. - Resources are folders, listed hierarchically like Drive. - Personal keys expire on Granola's side. The installation then records `sync.last_error` until it is reconnected with a new key. ### Reconnect Granola Replace an installation's API key, for example after the user's personal key expired: ```bash curl -X POST https://api.mixedbread.com/v1/integrations/granola/installations/INSTALLATION_ID/reconnect \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -d '{"api_key": "NEW_GRANOLA_API_KEY"}' ``` The installation keeps its store, folder selection and sync schedule, and the response has the shape of [Get Installation](https://www.mixedbread.com/api-reference/endpoints/integrations/get-installation). Granola cannot tell whose key it is, so the new key is not checked against the old one: pass the key of the user the installation belongs to. An invalid key returns `422`, and an unknown installation `404`. Connecting the new key through [Connect Granola](https://www.mixedbread.com/api-reference/endpoints/integrations/connect-granola) instead creates a second installation next to the old one. ## Disconnect ```bash curl -X DELETE https://api.mixedbread.com/v1/integrations/installations/INSTALLATION_ID \ -H 'Authorization: Bearer YOUR_API_KEY' ``` Stops the sync and revokes the grant at the provider. Google revokes the whole authorization for a client, so a Google grant is kept while another installation of the same account uses the same OAuth client, for example Gmail and Drive on one client. The store and its files remain; delete the store separately if the data should go too. # Changelog URL: https://www.mixedbread.com/docs/changelog Track the latest improvements to Mixedbread's platform, models, and API, including new models, feature launches, and performance enhancements. --- ## Spending Limits Are Now Monthly Budgets {{ date: '2026-10-06T00:00Z' }} Spending limits are now monthly budgets, set for usage after your included credits. When the budget is reached, choose to pause API requests or keep serving. Both send an alert to your billing email. > **Figure**: The Budget card on the dashboard with a $10 monthly budget and the Pause requests and Keep serving options --- ## Download Links in Search Results {{ date: '2026-10-06T00:00Z' }} Chunks returned by search, grep, and list chunks now include a `file_url`, a download link to the source file that stays valid for one hour. You no longer need a second call to fetch the original document. See the [Search Chunks](https://www.mixedbread.com/api-reference/endpoints/stores/search/search-chunks) API reference. --- ## Scope API Keys by Store Tag {{ date: '2026-09-26T00:00Z' }} You can now scope an API key to every Store with a specific tag. Tag your Stores with `dev` or `prod`, then create a key scoped to `dev`. It can access every `dev` Store, including Stores you create or tag later, but none of your `prod` Stores. This makes it easy to keep permissions separate across environments. > **Figure**: The Create API Key dialog on the dashboard with Read store scoped by the dev tag See [Scoping by Store tag](https://www.mixedbread.com/docs/platform/api-keys#scoping-by-store-tag). --- ## Try Toast 1 in the Agent Playground {{ date: '2026-09-24T00:00Z' }} The [agent playground](https://platform.mixedbread.com/platform?next=agents) lets you try Toast 1 deep search over your Stores, the web, MCP servers, and your own custom tools. Ask a question and watch it pick its search tools as it works. Open the code view to learn how to build it into your app. > **Figure**: The agent playground with Toast 1, a sample Store selected, and example prompts for Store, Web, MCP, and custom tool search --- ## Zero Data Retention Attestation for BYOB {{ date: '2026-09-24T00:00Z' }} Every [bring your own bucket](https://www.mixedbread.com/docs/production/bring-your-own-bucket) deployment runs under Mixedbread's Zero Data Retention architecture. Once your bucket is connected, download the Zero Data Retention attestation from **Settings → Buckets** and share it with your security, legal, or procurement team. See [Zero Data Retention](https://www.mixedbread.com/docs/production/bring-your-own-bucket#zero-data-retention). --- ## SVG and GIF Support {{ date: '2026-09-18T00:00Z' }} Stores now accept `.svg` and `.gif` files. SVGs are rendered to an image first, so logos, diagrams, and vector artwork are searched like any other image. See the supported [file types](https://www.mixedbread.com/docs/stores/store-files/file-types). --- ## Tag Stores for Easy Tracking {{ date: '2026-09-16T00:00Z' }} Now you can assign tags to Stores to easily track and filter them based on environments, sources, and tenants. A copied Store inherits the tags from its source. > **Figure**: The Update Store dialog on the dashboard with a dev tag assigned See the [Create Store](https://www.mixedbread.com/api-reference/endpoints/stores/manage/create-store), [Update Store](https://www.mixedbread.com/api-reference/endpoints/stores/manage/update-store), and [List Stores](https://www.mixedbread.com/api-reference/endpoints/stores/manage/list-stores) API references. --- ## Copy Store for Testing and Branching {{ date: '2026-09-15T00:00Z' }} You can copy all the files from one Store into a new one in a single call without reprocessing. It is designed for snapshotting before a risky change or giving a second environment the same content. By default, the new Store inherits all the configuration from the source Store. Until the copy finishes, neither Store accepts file changes. > **Figure**: The Copy Store dialog on the dashboard, naming the copy of a Store See the [Copy Store guide](https://www.mixedbread.com/docs/stores/stores/manage-stores#copy-store) or the [Copy Store API reference](https://www.mixedbread.com/api-reference/endpoints/stores/manage/copy-store). --- ## Structured Output for Toast 1 {{ date: '2026-09-14T00:00Z' }} The Responses API and Chat Completions API now support [OpenAI structured outputs](https://platform.openai.com/docs/guides/structured-outputs). Ask Toast 1 to deep search and extract information into structured formats. See the [Chat Completions](https://www.mixedbread.com/api-reference/endpoints/chat/create-chat-completion) and [Responses](https://www.mixedbread.com/api-reference/endpoints/responses/create-response) API references. --- ## MCP Tools in the Responses API {{ date: '2026-09-10T00:00Z' }} You can define MCP servers in the Responses API to let Toast 1 search via external MCP tools. Declare a server with its URL and Toast 1 lists its tools, calls them as it searches, and records every call on the response. It follows the OpenAI [remote MCP tool](https://developers.openai.com/api/docs/guides/tools-connectors-mcp) shape, including call approval. See [MCP servers](https://www.mixedbread.com/docs/agent/responses#mcp-servers) in the Responses guide. --- ## Context Management for Toast 1 {{ date: '2026-09-07T00:00Z' }} Long tool-calling runs can fill the Toast 1 context window before the model is done. Declare `context_management` on a Responses or Chat Completions request and the model prunes stale tool results itself as the conversation approaches the window. It works with any tool set: hosted search tools, your own function tools, or both. Every applied edit is reported on the response. > **Figure**: Declaring context_management with a hosted search_corpus tool on the Responses API See [Manage the context window](https://www.mixedbread.com/docs/agent/hosted-tools#manage-the-context-window) for the Chat Completions shape and what the response reports. --- ## Hosted Search Tools for Toast 1 {{ date: '2026-09-03T00:00Z' }} The Chat Completions and Responses APIs now run the full Toast 1 search harness server-side. Declare a hosted tool and the API executes the search loop against your Stores, with the exact tool schemas, defaults, and truncation behavior of the open-source [toast-harness](https://github.com/mixedbread-ai/toast-harness). > **Figure**: Declaring a hosted search_corpus tool on the Responses API with the OpenAI Python SDK See the [Hosted Tools guide](https://www.mixedbread.com/docs/agent/hosted-tools) for the tools, store scope, and streaming. --- ## Connect to Your OpenTelemetry Provider {{ date: '2026-08-28T00:00Z' }} Export every agent action as OpenTelemetry spans to Langfuse, Braintrust, or any OTLP collector. Trace each search and tool call, debug agent behavior, and find latency bottlenecks. > **Figure**: Tracing settings with a Langfuse and an OTLP destination connected Set it up under **Settings → Tracing**. See the [Trace Export guide](https://www.mixedbread.com/docs/production/tracing) and the [announcement](https://x.com/mixedbreadai/status/2093435197060493779). --- ## Stream Agentic Search Traces {{ date: '2026-08-19T00:00Z' }} You can now set `stream: true` on an Agentic Search request to receive live server-sent trace events while the search runs. > **Figure**: Streaming an Agentic Search trace for a force majeure research query Streaming requires `search_options.agentic` to be enabled. Learn more in the [Agentic Search guide](https://www.mixedbread.com/docs/stores/search/agentic-search) or see the complete [Search Chunks API reference](https://www.mixedbread.com/api-reference/endpoints/stores/search/search-chunks). See the [announcement](https://x.com/mixedbreadai/status/2090145693998453020). --- ## Introducing Toast 1 {{ date: '2026-08-13T00:00Z' }} We released Toast 1, our specialized search model for knowledge tasks, co-designed with Mixedbread Search. It provides frontier search quality, matching or outperforming Claude Opus 5 and GPT-5.6 Sol while being up to 10× cheaper and 12× faster. > **Figure**: Using Toast 1 through the Chat Completions API with the OpenAI Python SDK Toast 1 is available through our [Chat Completions API](https://www.mixedbread.com/docs/agent/chat-completions). [Read more](https://www.mixedbread.com/blog/toast-1). --- ## Faster search with a Wholembed v3 query engine {{ date: '2026-07-31T00:00Z' }} We built a query engine specifically for Wholembed v3 and extended it to cover the long-query tail we see in production. Query encoding p50 latency is now 39% lower, reducing end-to-end search p50 latency by 21%. See the [performance results](https://x.com/mixedbreadai/status/2083143592990695607). --- ## Faster, higher-quality reranking with mxbai-rerank-v3.1-listwise {{ date: '2026-07-27T00:00Z' }} **mxbai-rerank-v3.1-listwise** is now available as the default reranker. It delivers gpt-5.6-sol-level ranking quality with substantially improved latency over mxbai-rerank-v3-listwise (~25–54% faster). > **Figure**: Using mxbai-rerank-v3.1-listwise with Mixedbread Search Learn more in our [blog](https://www.mixedbread.com/blog/mxbai-rerank-v3-1-listwise). --- ## Bring Your Own Bucket {{ date: '2026-06-23T00:00Z' }} Enterprise organizations can now keep all their content in object storage they own. With [bring your own bucket](https://www.mixedbread.com/docs/production/bring-your-own-bucket), Mixedbread indexes and searches your AWS S3 bucket with ephemeral compute, retaining nothing beyond memory. Your documents and every derived artifact stay in your cloud account. Authenticate with an IAM role or access keys, optionally with your own KMS key, and [contact us](mailto:support@mixedbread.ai) to enable it. --- ## Store Chunk Grep and Listing {{ date: '2026-05-22T00:00Z' }} We added two lower-level chunk retrieval APIs: - [`stores.grep`](https://www.mixedbread.com/api-reference/endpoints/stores/search/grep-store-chunks) for exact regex matching against chunk text and generated content. - [`stores.list_chunks`](https://www.mixedbread.com/api-reference/endpoints/stores/search/list-store-chunks) for retrieving chunks by metadata filters with optional numeric sorting. --- ## Instruction-following listwise reranking with mxbai-rerank-v3-listwise {{ date: '2026-05-08T00:00Z' }} **mxbai-rerank-v3-listwise** is now available in preview through Mixedbread Search. It evaluates a candidate list as a whole, excellent at complex tasks like recency-aware ranking, source-priority resolution, and multi-step composite instructions. On top of Wholembed v3, it improves retrieval quality by 11% and outperforms leading pointwise rerankers at instruction following. > **Figure**: Using mxbai-rerank-v3-listwise with Mixedbread Search Learn more in our [release blog post](https://www.mixedbread.com/blog/listwise-rerank). **Update:** mxbai-rerank-v3-listwise is no longer supported. Use [mxbai-rerank-v3.1-listwise](https://www.mixedbread.com/blog/mxbai-rerank-v3-1-listwise) instead. --- ## Agentic Search Observability {{ date: '2026-05-04T00:00Z' }} We improved observability for agentic search so you can see what the agent actually did and trace the quality of its results. Inspect agent runs directly from the dashboard to understand and tune retrieval behavior. > **Figure**: Agentic search trace showing the agent's retrieval steps and query rewriting --- ## Auto File Contextualization {{ date: '2026-04-22T00:00Z' }} Enable `with_file_context` to improve retrieval for long documents (topping ConTEB with 82.1 nDCG@10). During ingestion, Mixedbread generates chunk-specific explanatory context from the original file and prepends it to each chunk before embedding. See [Anthropic's introduction to contextual retrieval](https://www.anthropic.com/engineering/contextual-retrieval). > **Figure**: Creating a Store with automatic file contextualization enabled --- ## Startup Accelerator Credits {{ date: '2026-04-17T00:00Z' }} Mixedbread is partnering with the [Startup Accelerator](https://www.tinyfish.ai/accelerator) to offer credits for eligible early-stage startups. Apply through the program to get Mixedbread Search credits and build AI-native search into your product from day one. --- ## Mixedbread Search Skill {{ date: '2026-04-07T00:00Z' }} We released the [Mixedbread Search skill](https://www.mixedbread.com/docs/skills), an agent skill that gives your coding agent the context it needs to integrate Mixedbread perfectly into your apps. Drop it into your agent and skip the back-and-forth of piecing together SDK patterns, shortening development time from exploration to working integration. --- ## Wholembed v3 {{ date: '2026-03-12T00:00Z' }} We released Wholembed v3, our new unified omnimodal multilingual late-interaction retrieval model for Mixedbread Search. It is now the default model for new stores and improves retrieval quality across languages, modalities, and real-world search tasks, with built-in support for audio and video. ### Key Features - **Higher retrieval quality**: Wholembed v3 delivers state-of-the-art retrieval performance across benchmarks and real-world industrial test cases, including strong results on LIMIT and BrowseComp-Plus. - **Audio and video support**: Mixedbread Search can now index and retrieve audio and video content directly, alongside text and images, in new stores by default. - **Unified omnimodal retrieval**: Wholembed v3 is designed to retrieve across text, audio, and vision in one system, improving robustness on noisy, heterogeneous real-world data. Read more in the [Wholembed v3 release post](https://www.mixedbread.com/blog/wholembed-v3). --- ## New Cookbooks {{ date: '2026-01-19T00:00Z' }} We published three new cookbooks to help you build with Mixedbread Search. The [Image Search](https://www.mixedbread.com/cookbook/image-search) cookbook guides you through building visual search applications. [Chat with PDFs](https://www.mixedbread.com/cookbook/chat-with-pdfs) demonstrates how to create conversational interfaces over your documents. [Agent Memory](https://www.mixedbread.com/cookbook/agent-memory) shows how to use Mixedbread as persistent memory for AI agents. --- ## Agentic Search {{ date: '2025-12-23T00:00Z' }} Agentic search is now available, designed for AI agents that need to retrieve information autonomously. The rewritten query is exposed in responses so you can see how the system interprets your searches. Read more in the [agentic search documentation](https://www.mixedbread.com/docs/stores/search). --- ## Web Search {{ date: '2025-12-11T00:00Z' }} Stores now support [web search](https://www.mixedbread.com/docs/stores/search/web-store) as a data source. You can retrieve web results directly via the store compatible API, enabling search across both uploaded documents and web content in a single query. --- ## Search-only API Keys {{ date: '2025-12-08T00:00Z' }} You can now create API keys with search-only scope. These restricted keys can perform searches but cannot modify stores, upload files, or access other endpoints. This is useful for client-side applications where you want to limit what the key can do. --- ## Free Tier {{ date: '2025-12-03T00:00Z' }} We launched a free plan that lets you explore Mixedbread Search without commitment. Free tier users get up to 1000 store files and access to core platform features. Token-based pricing is now displayed on the pricing page with an interactive calculator to estimate costs. --- ## Spending Limits {{ date: '2025-11-27T00:00Z' }} Spending limits give you control over your API costs. Set a maximum spend and the system will automatically pause requests when you approach the limit, preventing unexpected charges. Cost tracking is visible in the dashboard with breakdowns by store and product. --- ## MCP OAuth {{ date: '2025-11-14T00:00Z' }} The MCP integration now supports OAuth authentication, making it easier to connect Claude Desktop and other MCP-compatible tools to your Mixedbread stores securely. Users can authorize access through the standard OAuth flow rather than manually configuring API keys. --- ## Vercel Marketplace Integration {{ date: '2025-10-24T00:00Z' }} Mixedbread is now available on the [Vercel Marketplace](https://vercel.com/marketplace/mixedbread) as a Vercel Native integration in the Searching (and Agents) categories. Install it to: - Connect projects in one click: we’ll add the required `MXBAI_API_KEY` and `MXBAI_STORE_ID` env vars to your Vercel projects automatically. - Manage from the Vercel dashboard: monitor usage and costs with unified Vercel billing and access controls alongside your other integrations. Read more about it in our [Vercel integration docs](https://www.mixedbread.com/api-reference/integrations/vercel). - Ship faster with a starter: deploy our [example Next.js app](https://github.com/mixedbread-ai/vercel-integration-ecommerce) to see Mixedbread Search in action and customize from there. Mixedbread remains fully available as a standalone platform. Use it directly or via Vercel, whichever fits your workflow. --- ## Mixedbread Search Public Beta {{ date: '2025-10-01T00:00Z' }} We're excited to announce the public beta of Mixedbread Search, the easy-to-use search API built from the ground up for the AI era. It is a fully-managed search engine that allows you to upload your data and start searching in minutes. ### Key Features - **AI-native**: Built for the AI era, with both humans and AI in mind - **Multi-modal**: Search through text, images, tables, audio, and complex layouts. Video is coming soon - **Multi-lingual**: Support for 100+ languages - **Fully-managed**: No complex configuration, no complex setup, no complex code - **Low latency**: Because you need results now, not in 5700 milliseconds - **Meaningfully state-of-the-art Search**: On realistic BrowseComp-Plus benchmarks, LLM assistants are able to reach significantly better response accuracy with Mixedbread Search over existing search systems --- ## Ingestion Speed Optimization (fast track) {{ date: '2025-09-06T00:00Z' }} Today we're excited to announce that we've optimized the ingestion speed and concurrency of our Mixedbread Search. We can ingest 1000s of files concurrently with sub 1 second latency. This is a significant improvement over the previous 20 files concurrency limit. ### Key Features - **High concurrency**: 1000s of files can be ingested concurrently - **Minimal latency**: most files get ingested one second after they are uploaded --- ## Public Stores {{ date: '2025-08-21T00:00Z' }} Mixedbread public stores allow users to make stores publicly accessible, so that anyone with an API key can search them. This is useful for public documentation, public knowledge bases, and other use cases where you want to share your data with the world. --- ## Search Latency Optimization {{ date: '2025-07-31T00:00Z' }} We've optimized the hot path for the search latency of our search system, achieving sub 90ms latency without reranking and sub 120ms with reranking. This includes embedding generation, first stage single-vector retrieval, second stage multi-vector retrieval, and (optionally) reranking. ### Key Features - **Minimal latency**: latency so low that it's virtually undetectable by users in most scenarios. --- ## MaxSim CPU {{ date: '2025-07-15T00:00Z' }} MaxSim CPU is a CPU-optimized version of MaxSim, a state-of-the-art similarity search operator for late-interaction models such as ColBERT and ColPali. It powers our multi-vector retrieval system, achieving sub 5ms latency on AVX2 machines. ### Key Features - **CPU-optimized**: Optimized for CPU-based multi-vector retrieval. - **Low latency**: Sub 5ms latency on AVX2 machines. - **High throughput**: 10x speedup over existing CPU-based maxsim implementations. - **Open-source**: Fully accessible and customizable. --- ## Mixedbread MCP {{ date: '2025-06-28T00:00Z' }} Introducing the Mixedbread Model Context Protocol (MCP) server, a TypeScript-based integration that exposes powerful **store** capabilities to AI assistants like Claude Desktop. Built as an open standard, it enables secure and controlled access to external data sources. ### Key Features - **Claude Desktop Integration**: Seamless integration with Claude and other MCP-compatible AI assistants - **Store Operations**: Direct interaction with stores through standardized MCP tools - **Semantic Search**: Enable AI assistants to search and retrieve information using natural language - **File Management**: Upload, manage, and search through documents in stores - **Secure Data Access**: Controlled interface for AI systems to access external data sources ### Installation ```bash npm install -g @mixedbread/mcp ``` --- ## mxbai CLI {{ date: '2025-06-20T00:00Z' }} Introducing the Mixedbread CLI, a command-line interface for managing Mixedbread's services directly from your terminal. Built on top of the Mixedbread SDK, it provides efficient command-line access to all core platform features. ### Key Features - **Store Management**: Create, list, update, and manage stores with comprehensive control - **Store File Upload & Processing**: Upload files with intelligent processing strategies, metadata, and batch operations - **Semantic Search**: Search through stores using natural language queries with advanced filtering - **Question Answering**: Get AI-powered answers based on your store content - **Intelligent Sync**: Sync files with change detection and smart processing strategies to stores ### Installation ```bash npm install -g @mixedbread/cli ``` --- ## Platform Alpha {{ date: '2025-06-01T00:00Z' }} Today we're excited to announce the alpha of the Mixedbread platform, bringing together all our capabilities in a unified API. Experience state-of-the-art embeddings, reranking, document parsing, and stores in one integrated solution. ### Now Available in Alpha - **Embeddings API**: Transform text into semantic vectors with our award-winning models - **Reranking API**: Boost search relevance with advanced cross-encoder models - **Document Parsing API**: Extract LLM-ready content from PDFs, DOCX, PPTX, and more - **Stores API**: Fully-managed multi-modal search with automatic ingestion pipelines --- ## mxbai-rerank-v2 {{ date: '2025-03-13T00:00Z' }} The second generation of our reranking models features reinforcement learning (GRPO), extended context handling, and support for 100+ languages. These models are 8x faster than comparable alternatives while achieving higher accuracy across all benchmarks. ### Models - **mxbai-rerank-base-v2** (0.5B): Balanced performance for production use - **mxbai-rerank-large-v2** (1.5B): Maximum accuracy for critical applications --- ## mxbai-embed-xsmall-v1 {{ date: '2024-10-14T00:00Z' }} Our smallest and most efficient English embedding model. Perfect for edge deployments and resource-constrained environments, it delivers competitive performance in an extra small footprint. --- ## Batched - Dynamic Batching Library {{ date: '2024-09-16T00:00Z' }} We've open-sourced Batched, our dynamic batching library that powers Mixedbread's inference infrastructure. Achieve up to 10x throughput improvements with minimal latency impact. --- ## Baguetter - Retrieval Testing Framework {{ date: '2024-08-23T00:00Z' }} Introducing Baguetter, our open-source framework for testing and evaluating retrieval systems. Make your search better with comprehensive testing tools designed for real-world scenarios. --- ## BMX Algorithm {{ date: '2024-08-12T00:00Z' }} We've developed BMX, a modern take on the classic BM25 algorithm. Combining lexical and semantic signals, BMX delivers superior hybrid search performance. --- ## deepset-mxbai-embed-de-large-v1 {{ date: '2024-07-18T00:00Z' }} In collaboration with deepset, we've released a German/English embedding model that sets new performance standards among open source alternatives. --- ## mxbai-colbert-large-v1 {{ date: '2024-03-19T00:00Z' }} Our ColBERT model brings late interaction capabilities. Built on our mxbai-embed-large-v1 architecture, it achieves state-of-the-art performance on 13 BEIR benchmarks. --- ## mxbai-embed-large-v1 {{ date: '2024-03-08T00:00Z' }} Our flagship English embedding model delivers state-of-the-art performance, outperforming closed source alternatives like OpenAI's text-embedding-v3. --- ## mxbai-embed-2d-large-v1 {{ date: '2024-03-04T00:00Z' }} The world's first 2D-Matryoshka embedding model. This innovative approach allows you to reduce both the number of layers and dimensions while maintaining competitive performance. --- ## mxbai-rerank-v1 {{ date: '2024-02-29T00:00Z' }} We're launching our first generation of reranking models, available in three sizes. These models add a powerful semantic layer to existing search systems, dramatically improving result relevance. ### Models - **mxbai-rerank-xsmall-v1**: Ultra-efficient for high-volume applications - **mxbai-rerank-base-v1**: Balanced performance and speed - **mxbai-rerank-large-v1**: Maximum accuracy for critical applications # Concepts URL: https://www.mixedbread.com/docs/concepts Understand the core concepts behind Mixedbread Search - Stores, Store Files, Chunks, Search, and Agentic Search - and how they fit together. Mixedbread Search has a small number of core concepts. This page walks through each one and shows how they connect. ## High-Level Architecture Files get split into chunks and ingested into a Store. You query the Store with natural language, and it returns the relevant chunks. > **Diagram**: Files of any modality are sent to Mixedbread, where a Store splits them into chunks and ingests them. A search against the Store returns the matching chunks. The API exposes three objects: **Store**, **Store File**, and **Chunk**. You read from it through **Search** and **Agentic Search**. ## Store A **Store** holds a searchable collection of files. Every search runs against one or more Stores. Common uses: - A product's documentation - A customer knowledge base - A codebase - A research library > **Diagram**: A Store named product-docs contains six files: handbook.pdf, api-reference.md, onboarding.mp4, release-notes.md, architecture.pdf, and faq.md. Each Store has a unique ID and an optional human-readable name. Either works as an identifier in API calls. The object also exposes file counts by processing state, total storage used, and an optional expiration policy. See [Data Models → Store](https://www.mixedbread.com/docs/stores/data-models#store) for the full object, or [Create Stores](https://www.mixedbread.com/docs/stores/stores) to make one. ## Store File A **Store File** represents an uploaded file. It tracks the original filename, any metadata you attached, the processing status, and a version number. Each file is split into chunks, and those chunks are what search runs against. When you upload a file, it moves through a small lifecycle: > **Diagram**: A Store File moves through four lifecycle states: upload, pending, in_progress, and completed. If parsing fails, the file ends up in a `failed` state instead of `completed`. The specific error is available on `last_error`. While `in_progress`, Mixedbread parses the file, splits it into chunks, and generates embeddings. Parsing covers OCR for scans, layout understanding for PDFs, and transcription for audio and video. Once a file reaches `completed`, its chunks are searchable. File metadata propagates to every chunk produced from the file. That means you can filter searches by file-level attributes like `category` or `version` without attaching metadata to each chunk individually. For the full object, see [Data Models → Store File](https://www.mixedbread.com/docs/stores/data-models#store-file). To upload files, see [Create Files](https://www.mixedbread.com/docs/stores/store-files). ## Chunk A **Chunk** is a searchable segment of content produced from a Store File. Every search response is a ranked list of chunks. How a file splits depends on its type. A PDF usually produces one chunk per page. Long text files split into several text chunks, videos split into timed segments, and so on. > **Diagram**: A four-page PDF file splits into four chunks, one chunk per page. There are four chunk types: - Text: a passage with a character offset into the source file - Image: a page region or figure with OCR text and an optional AI-generated summary - Audio: an audio segment, optionally with transcription and AI-generated summary - Video: a video segment, optionally with transcription and AI-generated summary Each chunk references its source file via `file_id` and `filename`. It inherits the file's metadata. Search results also include a relevance `score` on each chunk. For the full object, see [Data Models → Store Chunk](https://www.mixedbread.com/docs/stores/data-models#store-chunk). ## Search **Search** queries a Store with natural language. Mixedbread returns the top chunks ranked by semantic relevance. The basic flow for a single search request looks like this: > **Diagram**: A natural-language query is sent to a Store on Mixedbread, which returns the top-k chunks ranked by relevance. Search supports a few extensions on top of the basic flow: - Metadata filters: narrow results by file or chunk metadata before ranking - File filters: restrict to a specific set of `file_id`s - Multi-store search: query several Stores at once and merge results - Rerank: apply a second-stage model for sharper ranking on hard queries - Query rewriting: let a model rewrite the query into a more search-friendly form - Web Store: include `mixedbread/web` alongside your Stores for hybrid internal and web search For the full API, see [Search](https://www.mixedbread.com/docs/stores/search). ## Agentic Search **Agentic Search** handles questions that a single search can't answer well. That includes questions that need to be broken into sub-questions, and ones where the best query phrasing isn't obvious upfront. An agent plans multiple searches, refines queries based on what it finds, and returns the merged results. > **Diagram**: A query enters a feedback loop where an agent plans a search, searches the Store, and evaluates the results. The loop iterates until it has enough context, and the best-matching chunks from the run are returned as top chunks. Each iteration of the loop produces candidate chunks, and only the best-matching ones make it into the final response. The response shape matches normal Search (a ranked list of chunks), so Agentic Search is a drop-in upgrade for quality-sensitive queries. You can steer the agent with `search_options.agentic.instructions`, for example "prioritize recent results" or "prefer primary sources". It's slower and more expensive than a single search, so reach for it when a single search falls short. For the full API, see [Agentic Search](https://www.mixedbread.com/docs/stores/search/agentic-search). ## Putting It Together An end-to-end flow uses all five concepts: ### Create a Store A named, searchable container for your content. ### Upload files Each upload becomes a Store File. Mixedbread parses it, splits it into chunks, and embeds them. ### Files become chunks Text, image, audio, and video chunks, each searchable on its own. ### Query the Store Use Search for fast lookups, or Agentic Search when a single query isn't enough. ### Use the chunks as context Pass the chunks to an LLM, show them in your UI, or process them further. > **Note** > > The [Quickstart](https://www.mixedbread.com/docs/quickstart) is a good starting point. You can also skip straight to [Create Stores](https://www.mixedbread.com/docs/stores/stores), [Create Files](https://www.mixedbread.com/docs/stores/store-files), or [Search](https://www.mixedbread.com/docs/stores/search). # GitHub Connector URL: https://www.mixedbread.com/docs/connectors/github Import repository files, issues, and pull requests from selected GitHub repositories into a Mixedbread Store and keep them synchronized. The GitHub connector imports the files, issues, and pull requests of selected repositories into a Store. Use it to search code, design discussions, review comments, and the decisions tracked across your GitHub organization. ## Before you begin You need permission to install GitHub Apps on the account or organization that owns the repositories, plus a Mixedbread organization with access to Data sources. ## Connect GitHub ### 1. Choose GitHub In the Mixedbread Platform, open **Data sources**, select **Create**, and choose **GitHub**. ### 2. Choose the destination Store Enter an optional Store name and review the Store configuration. Leave the name blank to use `github-{your-account}`. ### 3. Install the GitHub App Select **Install GitHub App**, pick the account or organization, and choose whether the app may see all repositories or only selected ones. GitHub returns you to Mixedbread once the installation is authorized. ### 4. Select repositories and resources Back in Mixedbread, choose the repositories to synchronize and which resources to import: **Files**, **Issues**, and **Pull requests**. Saving the selection starts the initial import. Mixedbread keeps the selected repositories up to date through GitHub webhooks: pushes to the default branch re-import the changed files, and issue and pull request activity re-imports the affected item. ## What is imported - **Files** from the default branch: source code, Markdown, plain-text configuration, CSV, PDF, and Office documents. Lock files, minified bundles, dependency directories, binaries, and text files over 1 MB are skipped. - **Issues** with their comments. - **Pull requests** with their conversation, reviews, and review comments. Every imported file carries metadata you can filter on, including `github.resource_type` (`file`, `issue`, or `pull_request`), `github.repository_full_name`, and, depending on the type, `github.path`, `github.language`, `github.number`, `github.state`, `github.labels`, and `github.author`. ## Manage the connector Open the GitHub data source to: - search, filter, and sort repositories; - synchronize or exclude repositories; - switch the imported resource types on or off; - monitor import status; - use **Sync now** to re-read all selected repositories; or - disconnect the installation. Excluding a repository, or switching a resource type off, removes the matching Store files. Disconnecting stops Mixedbread from receiving GitHub events; the app stays installed on GitHub until you uninstall it there. Previously imported Store files remain available. ## Troubleshooting ### A repository is missing Verify that the GitHub App has access to the repository in your GitHub settings (**Settings → Applications → Installed GitHub Apps**), then reload the connector page. ### Files are not updating Only pushes to the repository's default branch are imported. Confirm that the repository is marked **Syncing** and **Files** is enabled, then run **Sync now**. ### An import failed Review the repository's import status and error. Resolve any access issue on GitHub, then retry with **Sync now**. # Gmail Connector URL: https://www.mixedbread.com/docs/connectors/gmail Import Gmail messages from selected labels into a Mixedbread Store and keep matching mail synchronized. The Gmail connector imports messages that match selected Gmail labels. Use it to build a searchable Store from focused mailboxes such as support, partnerships, customer feedback, or project correspondence. ## Before you begin You need a Google account with access to the Gmail mailbox and a Mixedbread organization with access to Data sources. ## Connect Gmail ### 1. Choose Gmail In the Mixedbread Platform, open **Data sources**, select **Create**, and choose **Gmail**. ### 2. Choose the destination Store Enter an optional Store name and review the Store configuration. Leave the name blank to use `gmail-{your - account}`. ### 3. Authorize Gmail Select **Connect Gmail**, choose the Google account that owns the mailbox, and approve the requested access. ### 4. Select labels Back in Mixedbread, select the system or custom labels whose matching messages should be synchronized. Saving the label selection starts the initial message import. Mixedbread keeps messages matching the selected labels up to date. ## Choose labels The connector shows useful system labels, including **Inbox**, **Important**, **Sent**, and **Starred**, alongside your custom labels. Select only the labels needed for the Store to avoid importing unrelated mail. ## Manage the connector Open the Gmail data source to: - search available labels; - synchronize or exclude labels; - compare total and unread message counts; - run **Sync now** to re-check selected labels; or - disconnect Gmail. Excluding a label stops future synchronization for that selection. Disconnecting removes the saved Gmail credentials. Previously imported Store files remain available. ## Troubleshooting ### Gmail needs to be reconnected Google credentials can expire or be revoked. Select **Reconnect Gmail** and authorize the same Google account to resume synchronization into the existing Store. ### A label is missing Confirm that the label still exists in Gmail, then reload the connector page. Some Gmail category and state labels are intentionally hidden because they are not useful connector selections. ### Messages have not appeared Verify that they match at least one selected label, then run **Sync now**. # Google Drive Connector URL: https://www.mixedbread.com/docs/connectors/google-drive Import selected Google Drive files and folders into a Mixedbread Store and keep them synchronized. The Google Drive connector imports selected files and folders into a Store. Selecting a folder includes its files and subfolders, while individual file selection lets you keep the import narrowly scoped. ## Before you begin You need a Google account that can access the Drive content you want to import and a Mixedbread organization with access to Data sources. ## Connect Google Drive ### 1. Choose Google Drive In the Mixedbread Platform, open **Data sources**, select **Create**, and choose **Google Drive**. ### 2. Choose the destination Store Enter an optional Store name. Leave it blank to use `google-drive- {your - account}`. ### 3. Review the Store configuration Google Drive uses metadata contextualization with fast ingestion by default. Expand **Store configuration** only if you need different behavior. ### 4. Authorize Google Drive Select **Connect Google Drive**, choose a Google account, and approve the requested access. ### 5. Select files and folders Browse Drive from the connector page. Select the files and folders to synchronize, then confirm the selection. The first selection queues an import. Mixedbread keeps selected files and folders up to date as their contents change. > **Note** > > Selecting a folder synchronizes all files and subfolders inside it. Exclude a > child item separately when it should not inherit the parent folder's > synchronization state. ## Manage the connector Open the Google Drive data source to browse folders, search the current folder, and review each item's status. - Select **Sync** to import an excluded file or folder. - Select **Unsync** to stop future updates for an item. - Use **Sync now** to re-check selected files and folders for new or changed content. - Use **Disconnect** to remove the saved Google credentials and stop receiving Drive changes. Unsyncing or disconnecting does not delete previously imported Store files. ## Filter files Select **File filter** on the connector page to sync only some of the selected files, for example only PDFs, or everything except drafts. - **Only sync**: a file must match one of these patterns. Leave it empty to sync every selected file. - **Never sync**: a file that matches one of these patterns is skipped, even when it also matches **Only sync**. Patterns match a file's path in Drive, such as `My Drive/Reports/2026/q1.pdf`. A pattern matches the file itself or any folder it is in, so matching a folder covers everything inside it. As you add patterns, the dialog spells out what will sync and what will be skipped. - `*` matches any characters within a file or folder name. - A pattern without a `/` matches a name in any folder. - A pattern with a `/` starts at the top of Drive, so it begins with `My Drive`, `Shared drives`, or `Shared with me`. - A trailing `/` matches a folder and everything in it. - Matching ignores case. ### Examples | Pattern | Matches | | ------------------------ | ------------------------------------------------------- | | `*.pdf` | PDFs in any folder | | `*.docx` | Word files and Google Docs in any folder | | `*draft*` | Any file or folder with "draft" in its name | | `Archive` | Any file or folder named Archive, and everything in it | | `My Drive/Reports/` | Everything in the Reports folder of My Drive | | `My Drive/Reports/*.pdf` | PDFs directly in the Reports folder of My Drive | | `Shared with me/` | Files shared with you that are not in your own Drive | Paths start with `My Drive`, `Shared drives/`, or `Shared with me`. A file shared with you sits under `Shared with me`, starting at the highest folder you can open. Google Docs, Sheets, and Slides match by the format they are imported as: `.docx`, `.xlsx`, and `.pdf`. > **Note** > > Saving a filter re-checks the selected files, so files it now allows are > imported. Files it now skips stay in the Store but stop updating. Skipped files > show as **Filtered** when you browse the connector. ## Troubleshooting ### A file or folder is missing Confirm that the connected Google account can open it. Shared Drive and shared folder content only appears when the account has access. ### A nested item has the wrong status Check whether it inherits synchronization from a selected parent folder. You can explicitly exclude or reselect the child item. ### Changes have not appeared Run **Sync now** to re-check all selected files and folders. Review the item status for unsupported content or access errors. ### A selected file shows as Filtered The file filter skips it. Open **File filter** and check whether a **Never sync** pattern matches the file, or whether **Only sync** has patterns and none of them match. Patterns also match the folders a file is in, so renaming or moving a folder above your selection can change the result. Run **Sync now** to re-check the selected files after such a change. # Granola Connector URL: https://www.mixedbread.com/docs/connectors/granola Import selected Granola notes and folders into a Mixedbread Store with manual or scheduled synchronization. The Granola connector imports selected meeting notes and folders into a Store. It authenticates with a Granola Personal API key, receives note changes through a Granola webhook that Mixedbread manages, and supports manual or scheduled synchronization. ## Before you begin You need: - a Granola account with access to the notes you want to import; - permission to create a Personal API key; and - a Mixedbread organization with access to Data sources. ## Create a Granola API key ### 1. Open Granola settings In Granola, open **Settings → Connectors**. ### 2. Open Personal API keys Under **API**, select **Personal API keys**. ### 3. Create the key Create a new key and grant the access scopes required for the folders and notes you intend to synchronize. ### 4. Copy the key Copy the key when Granola displays it. Store it securely because it grants access to the selected Granola data. > **Figure**: Granola Settings Connectors page showing Personal API keys under API ## Connect Granola ### 1. Choose Granola In the Mixedbread Platform, open **Data sources**, select **Create**, and choose **Granola**. ### 2. Enter the API key Paste the Granola Personal API key, which begins with `grn_`. ### 3. Choose a sync schedule Select **Manual**, **Every 10 minutes**, **Hourly**, **Daily**, or **Weekly**. ### 4. Choose the destination Store Enter an optional Store name and review the Store configuration. Leave the name blank to use `granola-notes-{key - id}`. ### 5. Finish the connection Select **Connect Granola**. ### 6. Select notes and folders Browse the Granola catalog and select the folders and individual notes to import. ## Manage synchronization Open the Granola data source to: - browse and search folders and notes; - synchronize or exclude selected items; - refresh the Granola catalog; - change the synchronization schedule; - run **Sync now**; or - disconnect the account. Turning off periodic synchronization leaves **Sync now** available. Excluding an item or disconnecting Granola does not delete notes already imported into the Store. ## How updates arrive Mixedbread registers a Granola webhook for the connected API key and manages it for you, so there is nothing to configure in Granola. The webhook is created when you connect, replaced when you reconnect with a new key, and removed when you disconnect. Data sources connected before webhooks were available receive one automatically once they have notes or folders selected. When a selected note is generated, edited, or shared with the key's owner, Granola notifies Mixedbread and the note is imported again, whatever the synchronization schedule. Granola sends no event when a note is deleted, so the synchronization schedule removes deleted notes and catches any change a webhook missed. Granola plans or workspace settings that do not allow webhooks leave the data source on its synchronization schedule alone. ## Troubleshooting ### No folders or notes appear Confirm that the Personal API key has the required access scopes. Refresh the catalog after changing scopes or making new notes available. ### The API key no longer works Create a new Personal API key in Granola and reconnect the data source. Treat the key as a secret and revoke keys that are no longer used. ### Edited notes only update on the schedule Your Granola plan may not include webhooks. Otherwise, Granola switches off a webhook after its deliveries fail for several days; reconnect the data source to register a new one. ### Scheduled updates are not running Open the connector and verify that the schedule is not set to **Manual**. Run **Sync now** to test access immediately. # Connectors URL: https://www.mixedbread.com/docs/connectors Connect Slack, Google Drive, Gmail, Granola, Linear, Notion, Salesforce, and GitHub to keep Mixedbread Stores synchronized with your source data. Connectors import content from the tools your team already uses into a [Store](https://www.mixedbread.com/docs/stores/stores). After the initial import, each connector can keep the selected content up to date without requiring repeated uploads. > **Note** > > Connectors are in beta and available on request. > [Request access](mailto:support@mixedbread.com?subject=Enable%20data%20sources) and we'll enable them for your organization. ## Available connectors | Connector | Imported content | Authentication | | --------------------------------------------- | ------------------------------------------------------ | -------------------------------------- | | [Slack](https://www.mixedbread.com/docs/connectors/slack) | Selected channels, threads, and supported shared files | OAuth or a customer-provided Slack app | | [Google Drive](https://www.mixedbread.com/docs/connectors/google-drive) | Selected files and folders | Google OAuth | | [Gmail](https://www.mixedbread.com/docs/connectors/gmail) | Messages matching selected labels | Google OAuth | | [Granola](https://www.mixedbread.com/docs/connectors/granola) | Selected folders and notes | Personal API key | | [Linear](https://www.mixedbread.com/docs/connectors/linear) | Issues from selected teams | Linear OAuth | | [Notion](https://www.mixedbread.com/docs/connectors/notion) | Shared pages and databases | OAuth or an integration token | | [Salesforce](https://www.mixedbread.com/docs/connectors/salesforce) | Records from selected object types | External Client App credentials | | [GitHub](https://www.mixedbread.com/docs/connectors/github) | Files, issues, and pull requests of selected repos | GitHub App installation | ## Connect a data source ### 1. Open Data sources Sign in to the [Mixedbread Platform](https://platform.mixedbread.com), select your organization, and open **Data sources**. ### 2. Choose a connector Select **Create**, then choose the provider you want to connect. ### 3. Choose a Store Enter an optional Store name. Leave it blank to use the connector's default naming scheme. ### 4. Review the Store configuration Keep the recommended configuration or expand **Store configuration** to change contextualization and ingestion settings. Salesforce does not expose these settings during connection. ### 5. Authenticate Complete the provider-specific authorization steps. Mixedbread redirects you to the connector page after a successful connection. ### 6. Select content Choose the channels, files, folders, labels, teams, pages, notes, or object types that should feed the Store. Saving the selection starts the initial import. ## Store configuration New connector Stores use settings intended to produce useful search results without additional configuration: - **Metadata contextualization** adds source details such as titles and authors to chunks before embedding. - **File contextualization** situates chunks within their full document. - **Ingestion mode** controls the balance between processing speed and retrieval quality. Most connectors default to metadata and file contextualization with high-quality ingestion. Google Drive defaults to metadata contextualization with fast ingestion and no file contextualization. If the Store name already exists, the connector adds imported data to that Store. The existing Store keeps its configuration; only the selected ingestion mode applies to newly imported files. > **Note** > > A connector can only import content that the connected account or app is > allowed to access. Grant the minimum provider permissions needed for the > content you intend to synchronize. ## Manage synchronized content Open a connected data source to review its selected resources and import status. From the connector page, you can: - add or remove resources from synchronization; - run a manual sync; - retry supported import failures; - open the destination Store; or - disconnect the provider. Removing a resource from synchronization stops future updates but does not delete data that was already imported, with two exceptions: excluding a GitHub repository removes its Store files, and Gmail removes a thread once it changes while none of its labels is selected. Disconnecting leaves imported Store files in place. Delete those files separately if you no longer want them in the Store. After the import finishes, use [Search](https://www.mixedbread.com/docs/stores/search) or [Question Answering](https://www.mixedbread.com/docs/stores/search/question-answering) with the destination Store. # Linear Connector URL: https://www.mixedbread.com/docs/connectors/linear Import issues from selected Linear teams into a Mixedbread Store and keep them synchronized. The Linear connector imports issues from selected teams into a Store. Use it to search project decisions, issue descriptions, and the work tracked across your Linear workspace. ## Before you begin You need access to the Linear workspace and teams you want to import, plus a Mixedbread organization with access to Data sources. ## Connect Linear ### 1. Choose Linear In the Mixedbread Platform, open **Data sources**, select **Create**, and choose **Linear**. ### 2. Choose the destination Store Enter an optional Store name and review the Store configuration. Leave the name blank to use `linear-{your - workspace}`. ### 3. Authorize Linear Select **Connect Linear**, choose the target workspace, and approve the requested access. ### 4. Select teams Back in Mixedbread, choose the Linear teams whose issues should be synchronized. Saving the selection starts the initial issue import. Mixedbread keeps issues from selected teams up to date as they change. ## Manage the connector Open the Linear data source to: - search, filter, and sort workspace teams; - synchronize or exclude teams; - monitor issue import status; - use **Sync now** to re-check all selected teams for new or changed issues; or - disconnect the Linear workspace. Excluding a team stops future synchronization for its issues. Disconnecting removes the saved Linear credentials and stops receiving Linear events. Previously imported Store files remain available. ## Troubleshooting ### A team is missing Verify that the connected Linear account can access the team, then reload the connector page. ### Issues are not updating Confirm that the team is marked **Syncing** and run **Sync now**. If access was revoked, reconnect Linear with an account that can access the selected teams. ### An import failed Review the team's import status and error. Resolve any provider access issue, then retry with **Sync now**. # Notion Connector URL: https://www.mixedbread.com/docs/connectors/notion Import shared Notion pages and databases into a Mixedbread Store using OAuth or an integration token. The Notion connector imports pages and databases shared with Mixedbread into a Store. OAuth is the recommended setup because it provides Notion's page picker and a simpler authorization flow. ## Before you begin You need permission to add a connection to the Notion pages you want to import and a Mixedbread organization with access to Data sources. ## Connect with OAuth ### 1. Choose Notion In the Mixedbread Platform, open **Data sources**, select **Create**, and choose **Notion**. ### 2. Keep OAuth selected Select **OAuth (recommended)**. ### 3. Choose the destination Store Enter an optional Store name and review the Store configuration. Leave the name blank to use `notion-{your - workspace}`. ### 4. Authorize Notion Select **Connect Notion**, choose the workspace, and use Notion's page picker to grant access to the pages and databases you want to import. ### 5. Finish the import Return to Mixedbread. The connector imports the content shared through the page picker. Use **Manage access** from the connector page to reopen Notion's page picker. Newly shared pages are imported, while pages removed from the connection stop appearing in future synchronization. ## Connect with an integration token ### 1. Create a Notion integration Open [Notion integrations](https://www.notion.so/my-integrations), create an integration of type **Access token**, and copy its access token. ### 2. Configure capabilities Under **Capabilities**, enable **Read content** and **Read user information including email addresses**. **Read comments** is optional. > **Figure**: Notion connection Configuration tab showing the access token and capabilities ### 3. Share content with the integration Open the connection's **Content access** tab, select **Edit access**, and choose the pages and databases to import. Mixedbread only imports content shared with the integration. > **Figure**: Notion connection Content access tab with the Edit access button ### 4. Enter the token In Mixedbread, choose **Notion → Integration token** and paste the token, which begins with `ntn_`. ### 5. Choose the destination Store Enter an optional Store name, review the Store configuration, and select **Connect Notion**. ## Enable real-time updates for token setup After connecting with an integration token, open the Notion data source in Mixedbread. Copy its workspace-specific webhook URL and verification token, then add them on the integration's **Webhooks** tab in Notion. The webhook values are only available after Mixedbread has connected the workspace. > **Note** > > Without the optional webhook, use the connector's manual synchronization > action to import changes. ## Manage the connector Open the Notion data source to review imported resources, search them by name or path, monitor the latest import, manage OAuth page access, or disconnect the workspace. Disconnecting stops Notion events and removes the saved credentials. Previously imported Store files remain available. ## Troubleshooting ### A page or database is missing Confirm that it was shared through the OAuth page picker or the integration's **Content access** settings. ### Token setup is not receiving updates Verify the webhook URL and verification token in Notion. If no webhook is configured, run a manual synchronization after content changes. ### The last import failed Check that the connection still has access to all selected content, then retry the import. # Salesforce Connector URL: https://www.mixedbread.com/docs/connectors/salesforce Import selected Salesforce object records into a Mixedbread Store with manual or scheduled synchronization. The Salesforce connector imports records from selected object types into a Store. It uses Salesforce's Client Credentials Flow and accesses data as a configured **Run As** user. ## Before you begin You need: - access to Salesforce Setup and External Client App Manager; - permission to create and configure an External Client App; - a Salesforce user whose record access matches the data you want to import; and - a Mixedbread organization with access to Data sources. ## Create the Salesforce External Client App ### Open External Client App Manager In Salesforce, open **Setup**. From Quick Settings, select **Open Advanced Setup**, then open **External Client App Manager**. > **Figure**: Salesforce Quick Settings menu showing Open Advanced Setup > **Figure**: Salesforce Setup sidebar showing External Client App Manager ### Create an External Client App Create an app, provide its name and contact email, and continue to the API settings. ### Enable OAuth settings Under **API**, enable **OAuth Settings** and enter this callback URL: `https://api.mixedbread.com/v1/integrations/salesforce/oauth/callback` Add the **Manage user data via APIs (`api`)** scope. > **Figure**: Salesforce External Client App OAuth settings with callback URL and API scope selected ### Enable Client Credentials Flow Under **Flow Enablement**, turn on **Client Credentials Flow**, then create the app. > **Figure**: Salesforce OAuth Flow Enablement setting for Client Credentials Flow ### Set the Run As user In External Client App Manager, open the app's **Policies** tab and edit its policies. Enable Client Credentials Flow, then choose the **Run As** username. > **Figure**: Salesforce External Client App policies showing Client Credentials Flow and Run As user ### Copy the consumer credentials Open the app's **Settings** tab. Under **OAuth Settings**, select **Consumer Key and Secret**, then copy the Consumer Key and Consumer Secret. > **Figure**: Salesforce External Client App Settings tab showing the Consumer Key and Secret button > **Note** > > Mixedbread can only access records available to the Salesforce Run As user. > Use a dedicated user with the minimum permissions required for the selected > object types. ## Connect Salesforce ### 1. Choose Salesforce In the Mixedbread Platform, open **Data sources**, select **Create**, and choose **Salesforce**. ### 2. Enter the consumer credentials Paste the Consumer Key and Consumer Secret from the External Client App. ### 3. Enter the My Domain URL Enter your organization's My Domain login URL, for example `https://yourcompany.my.salesforce.com`. ### 4. Choose a sync schedule Select **Manual**, **Every 10 minutes**, **Hourly**, **Daily**, or **Weekly**. ### 5. Choose the destination Store Enter an optional Store name. Leave it blank to use `salesforce-{your - org} `. ### 6. Finish the connection Select **Connect Salesforce**. ### 7. Select object types Choose the Salesforce object types whose records should be imported. ## Manage synchronization Open the Salesforce data source to: - search and filter available object types; - synchronize or exclude object types; - change the synchronization schedule; - use **Sync now** to check selected object types for new, changed, and deleted records; or - disconnect the Salesforce organization. Turning off periodic synchronization leaves manual synchronization available. Excluding an object type or disconnecting Salesforce does not delete records already imported into the Store. ## Troubleshooting ### Authentication fails Check the Consumer Key, Consumer Secret, and My Domain URL. Confirm that Client Credentials Flow is enabled both in the app settings and its policies. ### No object types or records appear Verify the Run As user and its object- and record-level permissions. Mixedbread cannot import data that user cannot access. ### Changes are not appearing Confirm that a periodic schedule is enabled or run **Sync now**. The manual sync checks selected object types for created, updated, and deleted records. # Slack Connector URL: https://www.mixedbread.com/docs/connectors/slack Import selected Slack channels into a Mixedbread Store and ask source-grounded questions from Slack. The Slack connector imports selected channel history, threads, and supported shared files into a Store. It keeps selected channels current as messages are posted, edited, or deleted. Once Slack content is imported, workspace members can ask questions by mentioning the Mixedbread app, sending it a direct message, or running `/mixedbread ask `. Answers include links to relevant Slack messages. ## Before you begin You need: - a Mixedbread organization with access to Data sources; - permission to install apps in the Slack workspace; and - access to the channels you want to import. OAuth is the recommended installation method. Use manual setup when your organization requires a customer-managed Slack app. ## Connect with OAuth [> **Figure**: Add to Slack](https://slack.com/oauth/v2/authorize?client_id=6248643280645.11306954536806&scope=groups:history,app_mentions:read,assistant:write,channels:history,channels:join,channels:read,chat:write,commands,files:read,groups:read,im:history,users:read,users:read.email,mpim:read&user_scope=) ### 1. Choose Slack In the Mixedbread Platform, open **Data sources**, select **Create**, and choose **Slack**. ### 2. Keep OAuth selected Select **OAuth (recommended)**. ### 3. Choose the destination Store Enter an optional Store name and review the Store configuration. Leave the name blank to use `slack-{your - workspace}`. ### 4. Authorize Slack Select **Connect Slack**, choose the workspace, review the requested permissions, and approve the installation. ### 5. Select channels Back in Mixedbread, select the channels to synchronize. The Slack bot joins selected public channels so it can read new messages. Saving the selection queues a historical import and enables updates for new messages. Use **Sync now** to re-check every selected channel. ## Connect with a customer-managed Slack app ### Open manual setup Choose **Slack**, then select **Manual setup**. Mixedbread generates a deployment-specific Slack app manifest in JSON and YAML. ### Create or choose the Slack app For a new app, open [Slack's app creation page](https://api.slack.com/apps?new_app=1), choose **From an app manifest**, select the workspace, and paste the manifest from Mixedbread. To reuse an app, select it in the [Slack app dashboard](https://api.slack.com/apps) and use the manifest as the configuration checklist. See [Slack's app manifest guide](https://docs.slack.dev/app-manifests/configuring-apps-with-app-manifests/) for details. ### Copy the signing secret In the [Slack app dashboard](https://api.slack.com/apps), select the app and open **Basic Information**. Under **App Credentials**, copy the **Signing Secret** into Mixedbread. > **Figure**: Slack Basic Information page with the Signing Secret field highlighted ### Install the app In the [Slack app dashboard](https://api.slack.com/apps), open **OAuth & Permissions**, select **Install to Workspace**, and approve the installation. ### Copy the bot token Copy the **Bot User OAuth Token**, which begins with `xoxb-`, into Mixedbread. > **Figure**: Slack OAuth and Permissions page with the Bot User OAuth Token highlighted ### Finish the connection Choose an optional Store name and configuration, then select **Connect Slack**. ### Select channels Choose the channels to import. Saving the selection starts the historical import. > **Note** > > For a new app, keep the generated manifest unchanged. If you reuse an existing > app, use the manifest as a checklist: preserve the app's other configuration, > but add every generated scope and redirect URL under **OAuth & Permissions**. > Under **Event Subscriptions**, use the generated request URL and add every > generated event. Reinstall the app after adding scopes so Slack grants them > to the workspace. ## Ask questions in Slack After at least one selected channel has finished importing, workspace members can use any of these entry points: - mention `@Mixedbread` followed by a question; - send the Mixedbread app a direct message; or - run `/mixedbread ask ` in a channel. Mixedbread searches the Slack Store, returns a generated answer, and links back to source messages when available. Answers are filtered using the requester's workspace identity and the source content's access controls. > **Note** > > Mixedbread uses generative AI to create answers. Responses may be inaccurate > or incomplete. Verify important information using the linked Slack sources. ## Manage the connector Open the Slack data source to: - search, filter, and sort available channels; - synchronize or exclude channels; - refresh the channel catalog; - run a manual sync; - retry channel or item-level failures; or - disconnect the workspace. Excluding a channel stops future imports. Disconnecting removes the saved Slack credentials and stops event delivery. Previously imported Store files remain available until you delete them. ## Troubleshooting ### A channel is missing Select **Refresh channels**. If the channel still does not appear, verify that the connected app can access it and that the channel is not archived. ### A channel is not receiving updates Confirm that it is marked **Syncing** and that the Mixedbread app is a channel member. Run **Sync now** to re-check the channel. ### An import completed with warnings Open the warning details to view the affected Slack items. Use **Retry** for recoverable failures. # Overview URL: https://www.mixedbread.com/docs The Search API that makes all your unstructured data understandable and usable for AI. Upload any file format and search it with natural language. **Mixedbread** is an API for integrating fast, multimodal search into your applications, agents, and AI systems. Upload PDFs, images, documents, code, or video in any format and instantly make it searchable with natural language queries. No document parsing, no embedding models to manage, no vector databases to set up. Just upload your files and start searching. ## How It Works ### 1. Create a Store Create a store (your search index) and upload any file format: PDFs, images, documents, code, videos. No preprocessing required. ### 2. Automatic Processing Mixedbread automatically understands your content, including text, images, tables, and complex layouts across 100+ languages. ### 3. Search with Natural Language Query your store using natural language. Find relevant content by meaning, not just keywords. ### 4. Get AI-Ready Context Receive precisely ranked results optimized for AI applications, reducing hallucinations and improving response accuracy. ## Why Mixedbread **Understands Any Format** — Upload PDFs, images, Word documents, PowerPoint, Excel, code files, or videos. Mixedbread processes and understands the content, including visual elements, tables, and complex layouts. **Multilingual by Default** — Search across 100+ languages seamlessly. Query in English, find relevant content in German, Japanese, or any other language without translation layers. **AI-Native Search** — Optimized for AI applications, not just human search. Provides precise, verifiable context that reduces hallucinations and improves AI response accuracy. **Zero Infrastructure** — No servers to manage, no models to deploy, no databases to maintain. Scales automatically from prototype to enterprise production. ## Get Started - **[Quickstart](https://www.mixedbread.com/docs/quickstart)** — Create your first Store and start searching - **[Concepts](https://www.mixedbread.com/docs/concepts)** — Learn how Stores work and what makes them unique ## Agent Skills Installable skills for coding agents that use Mixedbread. They reduce repeated prompt setup, cut down on product-specific guesswork, and point agents to the right workflows and docs faster. ```bash npx skills add mixedbread-ai/skills ``` Available through [skills.sh](https://skills.sh/) for Claude Code, Cursor, Codex, Gemini CLI, and other supported tools. - **[Overview](https://www.mixedbread.com/docs/skills)** — What the package includes and how to install it - **[Browse the package on skills.sh](https://skills.sh/mixedbread-ai/skills)** ## CLI We built our CLI to streamline Store operations for developers. Handle bulk file uploads, sync entire directories, and integrate Store capabilities into your CI/CD pipelines - all from terminal. - **[Introduction](https://www.mixedbread.com/cli)** - Get to know our CLI and its capabilities - **[Installation & Setup](https://www.mixedbread.com/cli/installation)** - Setup the CLI in your terminal ## MCP (Model Context Protocol) Our MCP Server bridges the gap between AI assistants and your Stores. Enable Claude Desktop, Cursor, Claude Code and other AI assistants to directly search and retrieve context from your knowledge bases during conversations. - **[Introduction](https://www.mixedbread.com/mcp)** - Understand how our MCP Server enhances your AI workflows - **[Integration Guides](https://www.mixedbread.com/mcp/integrations/claude-desktop)** - Connect your AI assistant to the MCP Server ## Community Get help and connect with other developers building with Mixedbread. Join our [Discord](https://www.mixedbread.com/urls/discord) for support, follow us on [X](https://www.mixedbread.com/urls/x) for updates, or connect on [LinkedIn](https://www.mixedbread.com/urls/linked-in). # Legacy Embedding and Reranking Models URL: https://www.mixedbread.com/docs/legacy-models Find the maintained resources for earlier Mixedbread embedding and reranking models and migrate to current search workflows. Mixedbread previously published standalone documentation for direct embedding and reranking APIs and for each open-source model generation. Those reference pages are no longer part of the current documentation, but the model artifacts and their technical release posts remain available. ## Embedding models | Model family | Release post | Resources | | --- | --- | --- | | `mxbai-embed-large-v1` | [Technical overview](https://www.mixedbread.com/blog/mxbai-embed-large-v1) | [Hugging Face](https://huggingface.co/mixedbread-ai/mxbai-embed-large-v1) | | `mxbai-embed-2d-large-v1` | [Technical overview](https://www.mixedbread.com/blog/mxbai-embed-2d-large-v1) | [Hugging Face](https://huggingface.co/mixedbread-ai/mxbai-embed-2d-large-v1) | | `mxbai-embed-xsmall-v1` | [Technical overview](https://www.mixedbread.com/blog/mxbai-embed-xsmall-v1) | [Hugging Face](https://huggingface.co/mixedbread-ai/mxbai-embed-xsmall-v1) | | `deepset-mxbai-embed-de-large-v1` | [Technical overview](https://www.mixedbread.com/blog/deepset-mxbai-embed-de-large-v1) | [Hugging Face](https://huggingface.co/mixedbread-ai/deepset-mxbai-embed-de-large-v1) | | `mxbai-colbert-large-v1` | [Technical overview](https://www.mixedbread.com/blog/mxbai-colbert-large-v1) | [Hugging Face](https://huggingface.co/mixedbread-ai/mxbai-colbert-large-v1) | ## Reranking models | Model family | Release post | Resources | | --- | --- | --- | | `mxbai-rerank-*-v1` | [Technical overview](https://www.mixedbread.com/blog/mxbai-rerank-v1) | [Hugging Face](https://huggingface.co/mixedbread-ai/mxbai-rerank-large-v1) | | `mxbai-rerank-*-v2` | [Technical overview](https://www.mixedbread.com/blog/mxbai-rerank-v2) | [Hugging Face](https://huggingface.co/mixedbread-ai/mxbai-rerank-large-v2) | ## Current search workflow For new managed-search integrations, start with [Stores](https://www.mixedbread.com/docs/quickstart). Stores handle parsing, indexing, retrieval, and reranking as one workflow. See [Store search](https://www.mixedbread.com/docs/stores/search) for retrieval options and [reranking](https://www.mixedbread.com/docs/stores/search/rerank) for current model configuration. If you maintain an integration with the earlier direct embedding or reranking APIs and need migration help, contact [support@mixedbread.com](mailto:support@mixedbread.com). # Account URL: https://www.mixedbread.com/docs/platform/account All information about accounts. ## Overview A Mixedbread account represents an individual user and provides access to the platform's services. Each account includes a display name, profile picture, and email address, with the email serving as the unique identifier. Account details can be updated at any time. Accounts can be associated with multiple organizations or none at all. By default, each account is automatically assigned to its own organization. Organizations handle resource management including billing, Stores, and other platform features, rather than individual accounts. See [organizations](https://www.mixedbread.com/docs/platform/organization). # API Keys URL: https://www.mixedbread.com/docs/platform/api-keys Create Mixedbread API keys and restrict what they can do with scopes for Stores and the completions APIs. ## Overview API keys authenticate your requests to the Mixedbread API. Every key belongs to an [organization](https://www.mixedbread.com/docs/platform/organization) and inherits its Stores, billing, and limits. Pass a key as a bearer token: ```bash curl https://api.mixedbread.com/v1/stores \ -H "Authorization: Bearer $MXBAI_API_KEY" ``` Create and manage keys on the [API Keys](https://platform.mixedbread.com/platform?next=api-keys) page of your dashboard. ## Access modes When you create a key you choose how much of the API it can reach: - **Full access** — the key can use every endpoint available to the organization. This is the default. - **Custom** — the key carries a list of scopes, and every request is checked against them. Anything you do not grant is refused. A custom key is the right choice whenever a key leaves your own backend: a search-only key for a client-side app, a write-only key for an ingestion pipeline, or a key that may answer questions but never delete a Store. ## Available scopes | Scope | Grants | Applies to | | --- | --- | --- | | **List stores** | View the Stores in the organization | Organization-wide | | **Create store** | Create new Stores | Organization-wide | | **Read store** | View files and chunks in a Store | Selected Stores, tags, or all | | **Write store** | Upload and modify files in a Store | Selected Stores, tags, or all | | **Delete store** | Delete Stores | Selected Stores, tags, or all | | **Search store** | Read a Store's indexed content: search, agentic search, grep, list chunks, question answering, metadata facets, and query enhancement | Selected Stores, tags, or all | | **Completions** | Use the Chat Completions and Responses APIs | Organization-wide | ### Scoping to specific Stores **Read store**, **Write store**, **Delete store**, and **Search store** can be granted either across every Store in the organization or against an explicit list of Stores. A key restricted to a list may only touch those Stores — a request naming any other Store is refused, and so is a request that names no Store at all, since there is nothing to match the grant against. Grant a scope organization-wide when the key should keep working for Stores you create later; grant it per Store when the key belongs to one workload. ### Scoping by Store tag The same four scopes can also be granted for a [Store tag](https://www.mixedbread.com/api-reference/endpoints/stores/manage/update-store) instead of a list of Stores. A key that may **Search store** on the tag `prod` can search every Store tagged `prod`, including Stores created or tagged later, and is refused for any Store without the tag. A scope can combine tags and Stores: a Store is covered when it is in the list or carries one of the tags. Access follows the Store's tags at request time, so removing a tag from a Store also removes the access that tag granted. For that reason a key with any scopes cannot change a Store's tags or give a copy other tags than its source; only dashboard users and unscoped keys can. ## The completions scope The **Completions** scope gates the agent-facing endpoints, separately from anything a key may do with Stores: | Method | Endpoints | | --- | --- | | `create` | `POST /v1/chat/completions`, `POST /v1/responses` | | `read` | `GET /v1/chat/completions`, `GET /v1/chat/completions/{id}`, `GET /v1/chat/completions/{id}/turns`, `GET /v1/chat/completions/{id}/messages`, `GET /v1/responses/{id}`, `GET /v1/responses/{id}/input_items` | | `delete` | `DELETE /v1/chat/completions/{id}`, `DELETE /v1/responses/{id}` | The dashboard exposes this as a single **Completions** checkbox, which grants all three methods together. > **Note** > > The Completions scope is independent of the Store scopes. A key that may run > completions still needs **Search store** on a Store before the > [hosted search tools](https://www.mixedbread.com/docs/agent/chat-completions) can retrieve from it, and > a key with only **Completions** can generate but never search. Keys created before the Completions scope existed keep working unchanged: scope-restricted keys were granted all three completions methods, and full-access keys were never restricted in the first place. ## Scopes over the API The `/v1/api-keys` endpoint takes the same scopes as a list of entries. Each entry has a `method`, a `resource_type` of `store` or `completions`, and a `resource_id` that names one Store or is `null` for organization-wide. A Store entry may instead carry a `tag` to cover every Store with that tag; `tag` and `resource_id` cannot be combined in one entry, and tags are only accepted for the `read`, `write`, `delete`, and `search` methods: ```json { "name": "Search and answer", "scope": [ { "method": "search", "resource_type": "store", "resource_id": "8f2b…" }, { "method": "search", "resource_type": "store", "tag": "prod" }, { "method": "create", "resource_type": "completions", "resource_id": null }, { "method": "read", "resource_type": "completions", "resource_id": null } ] } ``` Omit `scope` entirely to create a full-access key. > **Note** > > `null` **and an empty list both create a full-access key** — an empty array is > stored as "no restrictions", not as "no permissions". To lock a key down, send > the scopes you want to grant; there is no way to express a key that may do > nothing. ## When a scope is missing A request the key's scopes do not cover fails with `403` and the error type `permission_denied_error`, naming the scope that was missing: ```json { "type": "permission_denied_error", "code": "permission_create_required_error", "message": "Missing the create scope for completions." } ``` Scopes are fixed when the key is created. To change what a key may do, create a replacement with the scopes you want and revoke the old one. # Billing URL: https://www.mixedbread.com/docs/platform/billing Information related to billing ## Overview The Starter plan is free and comes with \$5 in one-time credits, no card required. When the credits are used up, upgrade to Scale to keep going. The Scale plan is \$20 a month, included as \$20 of credits every month, with usage beyond that billed pay-as-you-go. For detailed pricing information, visit our [pricing page](https://www.mixedbread.com/pricing). ## Payment Methods We accept major credit cards including Visa and American Express for all transactions. To add a payment method, go to the **Billing Settings / Overview** page and click **Add Payment Method**. ## Credits You can view your current credit balance on the **Billing Settings / Overview** page. Credits are issued through plan allowances, promo codes, or directly by Mixedbread. If you have a promo code, redeem it in the **Credits** card on the same page. ## Billing Information You can configure a dedicated email address to receive billing statements and invoices. Additionally, billing information must be provided for the person or company responsible for payment. You can do this under the **Billing Settings / Usage & Invoices** page. ## Usage Overview You can view your usage and billing history on the **Billing Settings / Usage & Invoices** page. The usage metrics may be delayed by up to 10 minutes to ensure accurate tracking. The system allows for small overdrafts to prevent service interruptions during usage spikes. The Usage & Invoices page also displays a cost breakdown of your usage based on the services you are using. ## Vercel Integration Billing If your Mixedbread organization is managed through the Vercel integration, all usage is billed through your Vercel account instead of directly through Mixedbread. For Vercel-managed organizations: - Billing and payments are handled entirely through Vercel - Usage metrics are available in both the Vercel dashboard and Mixedbread dashboard - Cost tracking and invoices are managed in the Vercel billing dashboard For complete details on setting up and managing billing with the Vercel integration, see [Vercel Integration](https://www.mixedbread.com/api-reference/integrations/vercel). # Limits URL: https://www.mixedbread.com/docs/platform/limits Current Mixedbread store and file limits. ## Overview This page lists the current limits that apply across Mixedbread Stores and files. Unless noted otherwise, the values below reflect the default paid experience. None of these limits are hard walls. If you're bumping into one, or expect to, [contact us](https://www.mixedbread.com/contact) — we routinely raise limits for teams with real workloads, and we'd rather hear from you early than have you design around a number on this page. ## Current Limits ### Stores | Metric | Current Limit | |------|-------| | Max stores per organization | Unlimited* | | Max store name length | 60 characters | | Max store description length | 256 characters | ### Files | Metric | Current Limit | |------|-------| | Max files per store | Unlimited* | | Max store file external ID length | 256 characters | ### Search | Metric | Current Limit | |------|-------| | Max stores per search | 64 | | Max agentic search instructions length | 5,000 characters | | Max question answering instructions length | 8,000 characters | ### Metadata | Metric | Current Limit | |------|-------| | Max metadata keys | 256 † | | Max metadata key size | 128 bytes † | | Max metadata value size | 8 KiB ‡ | | Max total metadata size | 128 KiB | | Max metadata nesting depth | 5 | \* Free/basic organizations may have lower plan-specific limits. † Counted against flattened leaf keys when metadata is nested. For example, `{ "a": { "b": 1, "c": 2 } }` counts as two keys (`a.b`, `a.c`), and the key size limit applies to the full flattened path. ‡ Applies to leaf values (strings, numbers, booleans, arrays, etc.). Objects are not leaves — their contents are. # Organization URL: https://www.mixedbread.com/docs/platform/organization Learn about organizations in Mixedbread, including how to create them, manage members, and understand their role in resource management and team collaboration. ## Overview Organizations in Mixedbread serve as the primary container for managing resources, billing, and team collaboration. Each organization represents a workspace where multiple users can collaborate on Stores, manage API keys, and share resources. Organizations are essential for team-based workflows and enterprise use cases. ## Creating an Organization When you first sign up for Mixedbread, an organization is automatically created for you. This default organization uses your account name as the organization name and serves as your personal workspace. Each organization is uniquely identified by an organization slug. ### Manual Organization Creation To create additional organizations: #### 1. Navigate to the Organizations section in your dashboard Navigate to the **Organizations** section in your dashboard #### 2. Click Create Organization Click **Create Organization** to create a new organization #### 3. Provide an organization name and organization slug Provide an organization name and organization slug #### 4. Click Create to finalize Click **Create** to finalize ### Organization Naming Choose descriptive names that reflect your use case by using company names for business organizations, including project identifiers for specific initiatives, and considering environment suffixes such as "Production" or "Development" to clearly distinguish between different organizational contexts. ## Organization Structure ### Members and Roles Organizations support multiple user roles with different permission levels: | Role | Manage Resources | Manage Members | Manage Settings | |------|------------------|----------------|-----------------| | Owner | ✅ Full control | ✅ Full control | ✅ Full control | | Admin | ✅ Create and manage all resources | ✅ Add/remove members, change roles | ❌ Cannot modify billing or transfer ownership | | Member | ✅ Create and manage own resources | ❌ No access | ❌ No access | ### Inviting Members To invite users to your organization: #### 1. Go to Organization Settings > Team Go to **Organization Settings** > **Team** #### 2. Click Invite Member Click **Invite Member** #### 3. Enter the email address of the person you want to invite Enter the email address of the person you want to invite #### 4. Select their role in the organization Select their role in the organization #### 5. Send the invitation Send the invitation Invited users will receive an email with a link to join the organization. They must accept the invitation to gain access. # Bring Your Own Bucket URL: https://www.mixedbread.com/docs/production/bring-your-own-bucket Keep your content in object storage you own. Mixedbread indexes and searches it in memory and persists every artifact in your bucket. Nothing is retained on Mixedbread infrastructure, and every deployment comes with a downloadable Zero Data Retention attestation. > **Diagram**: Your data stays in your bucket and Mixedbread searches it for you. Your cloud persists source documents, chunks, metadata, and the index, encrypted with your own key. Mixedbread writes to and reads from your bucket only in memory—ingesting, preprocessing, embedding, and retrieving on ephemeral compute with zero content retention—and stores only usage metering, never your content. By default, your data lives in Mixedbread-managed object storage. Bring your own bucket (BYOB) lets [enterprise customers](https://www.mixedbread.com/pricing) use object storage they own and control as the backend instead. With BYOB, your bucket holds all user content (documents, metadata) and derived artifacts (chunks, generated content, the search index). Mixedbread reads and writes it with ephemeral compute and retains nothing beyond memory: we keep only usage metering for billing. > **Note** > > BYOB is enabled per organization. [Contact > us](mailto:support@mixedbread.ai) and we'll turn it on for your account. ## Supported providers | Provider | Status | Authentication | |----------|--------|----------------| | AWS S3 | Available | IAM role (recommended) or access keys | | Google Cloud Storage | Coming soon | N/A | | Azure Blob Storage | Coming soon | N/A | Other S3-compatible services can work via access keys and a custom endpoint, but aren't officially supported yet. [Contact us](mailto:support@mixedbread.ai) if you need one, or a provider that isn't listed. ## Authentication For AWS S3, authenticate one of two ways: - **IAM role (recommended).** Mixedbread [assumes a cross-account role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_manage-assume.html) in your account via STS, scoped with a unique external ID. We do not store any long-lived secrets. Access can be granted or revoked entirely through the role's trust policy. - **Access keys.** An access key ID and secret. Keys are encrypted at rest, never returned by the API, and can be rotated at any time. Use this for S3-compatible endpoints. ## Encryption Data is encrypted in transit and at rest. If your bucket uses [SSE-KMS](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html), provide the KMS key ARN and grant the role or identity Mixedbread uses `kms:Decrypt` and `kms:GenerateDataKey` on that key. Mixedbread encrypts writes with your key, so you hold the encryption material and can revoke it at any time. Omit the key to use the bucket's default encryption. The KMS key is fixed when you connect the bucket and can't be changed afterward, because objects stay encrypted under the key they were written with. To switch keys, recreate the connection. ## Zero Data Retention Every BYOB deployment runs under Mixedbread's Zero Data Retention (ZDR) architecture automatically. There is nothing to enable. Because your documents, derived artifacts, and index live in your bucket, Mixedbread-controlled storage never holds your content, and our logging and observability systems are configured not to retain it. Once your bucket is connected, Mixedbread issues a ZDR attestation for the deployment. Download it from the **Bucket** page in your organization settings and hand it to your security, legal, or procurement team. It names your organization and deployment, carries a unique attestation ID, and stays in effect for as long as the deployment uses BYOB. Mixedbread keeps only operational telemetry (request and trace IDs, timestamps, status codes, latency, and the usage counters that drive billing), none of which contains your content. ### What Mixedbread does not retain Nothing in the list below is written to Mixedbread-controlled persistent storage: - Source documents, files, images, audio, or video - Extracted text or document chunks - Embeddings or other content-derived representations - Search queries or natural-language prompts - Metadata fields you supply with indexed documents or search requests - Search results or retrieved passages - Model inputs, prompts, outputs, or generated responses containing your content - Intermediate model representations containing your content - Temporary copies of your content after processing has completed - Your content in application logs, traces, debugging, analytics, or observability tooling Your content may be held transiently in memory or other ephemeral compute only for the time required to process the operation, and is never written to Mixedbread-controlled persistent storage. It is not used for model training, human review, or product improvement. ## Setup ### 1. Request access [Contact us](mailto:support@mixedbread.ai) to enable BYOB for your organization. We'll confirm once it's on. ### 2. Prepare your bucket Create a dedicated S3 bucket in **us-east-1** (see [performance](#does-byob-affect-performance)). Optionally set a key prefix to namespace Mixedbread's objects, and configure SSE-KMS to use your own key. ### 3. Grant access Create an IAM role Mixedbread can assume with the external ID we provide, or create access keys. If the bucket uses SSE-KMS, grant the same identity access to your KMS key. ### 4. Connect the bucket In the dashboard, add the bucket with its name, region, optional prefix, the role ARN or access keys, and the KMS key ARN if applicable. ### 5. Validation Mixedbread validates the bucket before storing anything, checking reachability and running a write/delete probe, so a misconfigured or unreachable bucket is rejected immediately. Once connected, new stores point to your bucket automatically. ## Does BYOB affect performance? No. Keep your bucket in **us-east-1**, colocated with Mixedbread's compute, and indexing and search perform the same as without BYOB. Buckets in other regions work but add cross-region latency and data-transfer cost. ## What happens to my existing stores? Connecting a bucket changes where *new* content lives; it does not move existing data. - **Stores created after setup** persist all content in your bucket. - **Stores created before setup** keep reading and writing from the Mixedbread-owned bucket; they are not migrated. To move existing data into your bucket today, recreate those stores after connecting it. Automated migration of existing stores is coming soon. ## What does it cost? - **Mixedbread** charges for the compute cost of indexing and search. - **You** pay your cloud provider directly for the bucket's storage, requests, data transfer, and any encryption services you use (such as KMS). ## How do I revoke access? You control access from your own cloud and can revoke it at any time. How quickly Mixedbread loses access depends on how you revoke it: - **Access keys.** Once you deactivate or delete the key, Mixedbread loses access within a few minutes (AWS IAM is eventually consistent). - **IAM role.** Once you remove the trust policy, Mixedbread can no longer obtain new credentials. Because it uses short-lived STS sessions, any session it already holds expires shortly after; to cut access immediately, use IAM's *revoke active sessions*. After Mixedbread loses access, your stores and files are no longer reachable from our service. Content already loaded into the retrieval engine may stay in an ephemeral in-memory cache for a short period until it is evicted. ## What if Mixedbread loses access by accident? If your IAM role refuses Mixedbread, for example after a trust policy change, the bucket's status in the dashboard switches to **Error**. While it is in that state, uploads and new stores are rejected with a `bucket_unavailable_error` instead of being written to Mixedbread-owned storage. Restore the trust policy, then use **Re-check access** in your organization's bucket settings. Mixedbread repeats the validation probe and the bucket becomes active again. # Security & Compliance URL: https://www.mixedbread.com/docs/production/security How Mixedbread protects your data. SOC 2 Type 2 and ISO 27001 certified, GDPR compliant, with encryption everywhere and the option to keep content in storage you own. Security is foundational to how we build Mixedbread. We hold independent certifications, encrypt your data in transit and at rest, and never use your content to train models. Enterprise customers can also keep all content in [object storage they own and control](https://www.mixedbread.com/docs/production/bring-your-own-bucket). ## Certifications & compliance | Standard | Status | |----------|--------| | **SOC 2 Type 2** | Certified for the Security trust services criterion. Report available on request. | | **ISO 27001** | Certified. Certificate available on request. | | **GDPR** | Compliant. A [Data Processing Addendum](https://www.mixedbread.com/pages/dpa) with EU, UK, and Swiss Standard Contractual Clauses is available. | > **Note** > > Need our SOC 2 Type 2 report, ISO 27001 certificate, or a completed security > questionnaire? [Contact us](mailto:support@mixedbread.com) and we'll share them > under NDA. ## Encryption Your data is encrypted at every stage. - **In transit.** All connections use TLS 1.2 or higher. - **At rest.** Stored data is encrypted with AES-256. With [Bring Your Own Bucket](https://www.mixedbread.com/docs/production/bring-your-own-bucket) you can go further and supply your own SSE-KMS key, so you hold the encryption material and can revoke it at any time. ## Data residency All processing and Mixedbread-managed storage currently happen in the United States. EU data residency is coming soon. [Contact us](mailto:support@mixedbread.com) if this is a requirement for your organization. With [Bring Your Own Bucket](https://www.mixedbread.com/docs/production/bring-your-own-bucket), content at rest lives in the bucket you provide and control. ## How we handle your data - **No training on your data.** Your content and usage are never used to train models, for any user on any plan. - **Access controls.** Access to customer data is restricted, authenticated, and monitored. - **You stay in control.** Delete a store or your account and the associated content is removed. With [Bring Your Own Bucket](https://www.mixedbread.com/docs/production/bring-your-own-bucket), content lives in storage you own. Mixedbread reads and writes it with ephemeral compute and retains nothing beyond memory. Every BYOB deployment runs under Zero Data Retention and comes with a [downloadable attestation](https://www.mixedbread.com/docs/production/bring-your-own-bucket#zero-data-retention) for your security and procurement teams. ## Vulnerability disclosure We welcome reports from security researchers and treat them as a priority. - **Report it.** Email [support@mixedbread.com](mailto:support@mixedbread.com) with steps to reproduce, affected endpoints, and any proof of concept. Please report privately and give us a reasonable window to remediate before public disclosure. - **What to expect.** We acknowledge reports promptly, keep you updated on our progress, and let you know when the issue is resolved. - **Safe harbor.** We won't pursue legal action for good-faith research that respects user privacy, avoids data destruction or service degradation, and stays within the scope of your own account or test data. ## Questions? For security reviews, documentation requests, or anything else, [reach out to us](mailto:support@mixedbread.com). # Trace Export URL: https://www.mixedbread.com/docs/production/tracing Send your agent traces to Langfuse, Braintrust, or any OTLP collector you own. Every agentic search, chat completion, and Q&A run is exported as OpenTelemetry spans, the same trace the dashboard shows. Every search and generation on Mixedbread produces a structured trace: the query, the tool calls the agent issued with their arguments and results, the model turns with their token usage, and the chunks that came back. The dashboard renders these traces, and trace export pushes the same data to an observability backend you own, as OpenTelemetry spans, moments after each run finishes. Traces land next to the rest of your LLM observability, so you can search them, score them, and alert on them with the tooling you already use. > **Figure**: The Tracing settings page in the dashboard, showing a Langfuse and an OTLP destination, both with a green Delivering status. ## What gets exported Each exported trace is one run, with a root span for the request and a child span per recorded step: `execute_tool` spans for retrieval tool calls (with their arguments and results) and `chat` spans for model turns (with their token usage). Attributes follow the [OpenTelemetry GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/), so Langfuse and Braintrust classify them as tool and generation observations automatically and other OTel tooling reads them without configuration. The export is exactly the customer-facing trace you see in the dashboard and the [events API](https://www.mixedbread.com/api-reference/endpoints/stores/events/list-store-events). Mixedbread's internal spans (databases, retrieval backends, inference infrastructure) are never sent. You choose per destination which trace kinds to export: | Trace kind | Contents | Exported by default | |------------|----------|---------------------| | Agentic search | The agent's rounds, tool calls, and model turns | Yes | | Chat completions | Completion and Responses turns, grouped per conversation | Yes | | Question answering | Each Q&A request's retrieval and answer generation | Yes | | Search | Every plain search (high volume) | No | | Grep | Regex matches over your stores | No | Chat completion turns in the same conversation share a session id, so a resumed chat reads as one thread in Langfuse instead of unrelated traces. Large runs are kept deliverable rather than dropped: a trace carries up to 50 result chunks, chunk text is truncated to 2,000 characters, and any single span field is capped at 128 kB. ## Setup ### 1. Connect a destination In the dashboard, go to **Settings → Tracing** and click **Connect destination**. Pick **Langfuse**, or **OpenTelemetry (OTLP)** for Braintrust and everything else. ### 2. Choose what to export Agentic search, chat completions, and question answering are on by default; plain searches and grep are off because of their volume. ### 3. Save and run a search Saving checks the credentials against the destination, so a wrong key fails here instead of silently dropping traces later. Traces then arrive within seconds of each run, and the destination card shows the delivery status. > **Figure**: The Connect a destination dialog with Langfuse selected, showing host, public key, and secret key fields and the list of trace kinds to export. ### Langfuse Langfuse Cloud or a self-hosted instance. Three fields, all from **Project settings → API keys** in Langfuse: | Field | Value | |-------|-------| | Host | `https://cloud.langfuse.com`, or your self-hosted URL | | Public key | `pk-lf-…` | | Secret key | `sk-lf-…` | Here is an exported agentic search in Langfuse: the root span with the query and final ranking, tool spans for each retrieval call, and generations with their token usage: > **Figure**: An exported agentic search trace in Langfuse, showing the span tree with search and generation spans, the input query, the output ranking, and token usage. ### Braintrust Braintrust ingests OpenTelemetry directly, so connect it as an **OpenTelemetry (OTLP)** destination: set the traces URL, and the two headers Braintrust authenticates and routes with. | Field | Value | |-------|-------| | Traces endpoint | `https://api.braintrust.dev/otel/v1/traces` (EU: `https://api-eu.braintrust.dev/otel/v1/traces`) | | Headers | `Authorization` and `x-bt-parent`, one per line | ``` Authorization: Bearer x-bt-parent: project_name:My Project ``` - **Authorization** carries a Braintrust API key from **Settings → API keys**. - **x-bt-parent** decides which project the traces land in. Use `project_name:` or `project_id:`. Braintrust has no default project for OTLP, so leave it out and the connection check fails. Traces arrive under the project's **Logs**, one row per run. Braintrust reads the GenAI attributes, so retrieval calls render as tool spans and model turns as generations with their token usage: > **Figure**: An exported agentic search trace in Braintrust's Logs view, showing the span tree with tool and generation spans and the selected tool span's GenAI metadata. The connection check shows up there too, as a `mixedbread.connection_test` trace: Braintrust rejects an OTLP request that carries no spans, so the check sends a single empty one instead. It is safe to delete. ### Other OTLP collectors Phoenix, Traceloop, Grafana, or your own collector connect the same way as Braintrust: the OTLP/HTTP traces path as the endpoint, plus whatever headers it authenticates with. gRPC collectors are not supported. ## Delivery Export is best-effort by design: a slow or failing destination never affects the request that produced the trace. Deliveries are batched and usually arrive within seconds of the run finishing. - **Status.** Each destination card shows one of *Delivering*, *Waiting for traces*, *Failing* (with the destination's last error), or *Paused*. - **No duplicates.** Trace and span ids are derived deterministically from the event, so a retried delivery overwrites the previous one instead of creating a duplicate trace. - **Pause and resume.** Pausing stops exports without forgetting the configuration. Traces produced while paused are not backfilled. ## Security Traces contain your queries, retrieved content, and generated answers, so only connect backends you control. Credentials are encrypted at rest and write-only: the API returns only a non-secret hint (the Langfuse public key, or the auth header name). For organizations using [Bring Your Own Bucket](https://www.mixedbread.com/docs/production/bring-your-own-bucket), customer content is blanked from exported traces, matching the events API. ## Troubleshooting **A destination shows Failing**: the card displays the destination's last error response. After fixing the cause (rotated keys, changed endpoint), use **Update credentials** on the destination; delivery resumes with the next trace and the status clears on the first success. **Traces are missing**: check that the trace kind is enabled on the destination. Plain searches and grep are not exported unless you turn them on. # Quickstart URL: https://www.mixedbread.com/docs/quickstart Build your AI Search Engine in minutes. Create Stores that understand any data format and provide precise context for your AI applications. This quickstart walks you through building powerful Search with Mixedbread's Stores. You'll turn your files into a searchable knowledge base and explore it using natural language queries. Pick the approach that fits your workflow: use our SDKs for seamless programmatic control and integration into your applications, or run everything directly in your terminal with the CLI for streamlined scripting and automation. Agent tip: ALWAYS use `GET /question?q=...&limit=...` to get the latest Mixedbread information across docs, API references, pricing, CLI, MCP, blog posts, cookbooks, and more. Example: `/question?q=reranking&limit=5`. For broader agent-readable docs, see `/llms.txt` and `/llms-full.txt`. ## Using the SDK Before you begin, make sure you have: 1. **API Key**: Get your API key from the [API Keys](https://platform.mixedbread.com/platform?next=api-keys) page 2. **SDK Installed**: Install the Mixedbread SDK for your preferred language **Python** ```bash pip install mixedbread ``` **TypeScript** ```npm npm install @mixedbread/sdk ``` Create a Store, upload your files, and search with natural language: **Store Workflow** Python: ```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 (async): ```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) ``` TypeScript: ```ts 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); } ``` ### Working with Metadata Add metadata during upload to categorize files and filter during search: **Store Workflow with Metadata Filtering** Python: ```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 (async): ```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) ``` TypeScript: ```ts 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); } ``` Use metadata to organize files by category, department, or any custom attribute, then search only the relevant subsets. ## Using the CLI Before you begin, make sure you have: 1. **API Key**: Get your API key from the [API Keys](https://platform.mixedbread.com/platform?next=api-keys) page 2. **CLI Installed**: Install the Mixedbread CLI using your preferred package manager ```npm npm install -g @mixedbread/cli ``` ```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?" ``` # Agent Skills URL: https://www.mixedbread.com/docs/skills Installable skills that help coding agents work with Mixedbread Search and the CLI without guessing. Agent note: For current Mixedbread product information, use `GET /question?q=...&limit=...`. Example: `/question?q=reranking&limit=5`. For broader machine-readable docs, use `/llms.txt` and `/llms-full.txt`. The Mixedbread skills package gives coding agents product-specific guidance for working with Mixedbread. If you use Mixedbread through an agent, this is the fastest way to stop it from guessing its way through Stores and the CLI. The package is useful because agents are usually good at general coding and weak at product-specific workflows. Without that extra context, they tend to spend time rediscovering how Mixedbread works, pick the wrong integration path, or answer with stale details. The skills narrow that gap. ## What Problems The Skills Solve - Repeated prompt setup. You do not need to explain Mixedbread concepts and workflows from scratch in every session. - Wrong first step. The agent gets help choosing between Stores and the CLI instead of reaching for the wrong API or tool. - Product-specific guesswork. The skill steers the agent toward the right Mixedbread patterns, terminology, and docs instead of generic vector database assumptions. - Better use of live docs. When exact parameters or examples matter, the skill points the agent back to current references instead of relying on memory. ## Why Install Them Install the skills if you want an agent to get to useful Mixedbread work faster. They improve the first draft of code and commands, reduce back-and-forth prompt correction, and make it more likely the agent will use the right Mixedbread feature on the first pass. ## Installation Install the package with: ```bash npx skills add mixedbread-ai/skills ``` To make it available across projects: ```bash npx skills add mixedbread-ai/skills -g ``` You can inspect the package here before installing it: - [Browse the package on skills.sh](https://skills.sh/mixedbread-ai/skills) - [View the source on GitHub](https://github.com/mixedbread-ai/skills) ## Included Skills ### `mixedbread-search` Use this when an agent needs to work with Stores. It covers creating stores, uploading content, running semantic search, filtering by metadata, reranking results, and wiring Mixedbread into Python or TypeScript projects. ### `mxbai-cli` Use this when an agent should work from the terminal instead of the SDKs. It covers CLI setup, authentication, uploads, search, syncing directories, and scriptable workflows for local development or CI. ### `mixedbread-search-agent` Use this when an agent should use our [own search agent](https://www.mixedbread.com/docs/agent/chat-completions) that offers the completions API. ### `mixedbread-search-agent-harness` Use this when an agent wants to design and [build their own harnes](https://www.mixedbread.com/docs/agent/build-your-own-harness) with our search agent. ## What a Skill Contains Each skill is a small `SKILL.md` file written for agent tooling. In practice, that usually means: - when the skill should activate - the workflows or APIs an agent should reach for first - task-specific rules and common gotchas - links back to the relevant Mixedbread docs The skills stay intentionally small. They do not duplicate the full API reference or product docs. Their job is to make the agent start in the right place. When exact parameters or examples matter, it should fetch them from the docs, MCP, or other live Mixedbread sources. ## Source Code The skills are [open source on GitHub](https://github.com/mixedbread-ai/skills) under the Apache-2.0 license. # Data Models URL: https://www.mixedbread.com/docs/stores/data-models Understand the core data structures in Mixedbread Stores - Store Files and Chunks - and how they relate to your workflows. Understanding the core data structures in Mixedbread Stores helps you work effectively with the API and understand how your content is organized and retrieved. ## Store A **Store** is the primary container for your searchable content. It holds your files, manages access permissions, and provides the foundation for semantic search operations. ### Store Properties | Property | Type | Description | |----------|------|-------------| | `id` | string | Unique identifier for the Store | | `name` | string | User-defined name that serves as an identifier | | `description` | string | Optional description of the Store's purpose | | `is_public` | boolean | Whether the Store is publicly accessible | | `metadata` | object | Additional metadata associated with the Store | | `file_counts` | object | Counts of files in different processing states | | `expires_after` | object | Expiration configuration based on activity | | `status` | enum | Current status: `expired`, `in_progress`, `completed`, `failed`. A Store is `in_progress` while a copy fills it | | `created_at` | string | ISO timestamp when the Store was created | | `updated_at` | string | ISO timestamp when the Store was last updated | | `last_active_at` | string | ISO timestamp of the last activity | | `usage_bytes` | integer | Total storage space used by indexed content | | `expires_at` | string | Computed expiration timestamp (if expires_after is set) | | `copy_state` | object | Present while the Store is the source or target of a [copy](https://www.mixedbread.com/docs/stores/stores/manage-stores#copy-store), and on a target whose copy failed | | `object` | string | Always "store" | ### File Counts Object The `file_counts` object provides detailed breakdown of file processing states: | Property | Type | Description | |----------|------|-------------| | `pending` | integer | Number of files waiting to be processed | | `in_progress` | integer | Number of files currently being processed | | `cancelled` | integer | Number of files whose processing was cancelled | | `completed` | integer | Number of successfully processed files | | `failed` | integer | Number of files that failed processing | | `total` | integer | Total number of files | For detailed configuration options including expiration policies and public access, see [Store Configuration](https://www.mixedbread.com/docs/stores/stores#configuration-options). ### Copy State Object Set on both Stores while a copy runs, and kept on a target whose copy failed: | Property | Type | Description | |----------|------|-------------| | `role` | enum | `source` (this Store is being copied) or `target` (this Store is being filled) | | `status` | enum | `in_progress` or `failed` | | `peer_store_id` | string | The other Store of the copy | | `started_at` | string | ISO timestamp when the copy was requested | | `error` | string | Why the copy failed, when it did | ### Store Example ```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" } ``` ## Store File A **Store File** represents a complete file that you've uploaded to a Store. It tracks the file's processing status, metadata, and relationship to the searchable chunks created from its content. ### File Properties | Property | Type | Description | |----------|------|-------------| | `id` | string | Unique identifier for the file within the Store | | `filename` | string | Original name of the uploaded file | | `metadata` | object | Custom key-value pairs you've attached to the file | | `status` | enum | Current processing status of the file | | `last_error` | object | Details about any processing errors that occurred | | `store_id` | string | ID of the Store containing this file | | `created_at` | string | ISO timestamp when the file was added to the Store | | `version` | integer | Version number of the file within the Store | | `usage_bytes` | integer | Storage space used by the file's indexed data | | `object` | string | Always "store.file" | For detailed information on file processing lifecycle and status meanings, see [Store File Status](https://www.mixedbread.com/docs/stores/store-files#store-file-status). For guidance on metadata structure and types, see [Metadata Types](https://www.mixedbread.com/docs/stores/store-files/metadata-types). ### File Example ```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" } ``` ## Store Chunk A **Store Chunk** represents a searchable segment of content created from a Store File. When you search, you get back chunks that contain the most relevant portions of your files. ### Chunk Properties | Property | Type | Description | |----------|------|-------------| | `chunk_index` | integer | Position of this chunk within the source file | | `mime_type` | string | Content type of the chunk (text/plain, image/png, etc.) | | `model` | string | Model used to generate the chunk's vector | | `score` | number | Relevance score for this chunk (in search results) | | `file_id` | string | ID of the file this chunk came from | | `filename` | string | Name of the source file | | `store_id` | string | ID of the Store containing this chunk | | `external_id` | string | Optional external identifier for the source file | | `metadata` | object | User-defined metadata inherited from the source file | | `generated_metadata` | object | Ingestion-time structured metadata e.g. chunk size | | `type` | enum | Type of content: `text`, `image_url`, `audio_url`, `video_url` | ### Content-Specific Properties **Text Chunks** | Property | Type | Description | |----------|------|-------------| | `text` | string | Text content of the chunk | | `summary` | string | AI-generated summary of the text chunk † | | `offset` | integer | Character offset of this chunk relative to the start of the file | **Image Chunks** | Property | Type | Description | |----------|------|-------------| | `image_url` | object | Image URL and format information | | `ocr_text` | string | Text extracted from images via OCR | | `summary` | string | AI-generated summary of the image content † | **Audio Chunks** | Property | Type | Description | |----------|------|-------------| | `audio_url` | object | Audio URL and format information | | `transcription` | string | Speech-to-text transcription of the audio † | | `summary` | string | AI-generated summary of the audio content † | | `sampling_rate` | integer | Audio sampling rate in Hz | **Video Chunks** | Property | Type | Description | |----------|------|-------------| | `video_url` | object | Video URL and format information | | `transcription` | string | Speech-to-text transcription of the video † | | `summary` | string | AI-generated summary of the video clip † | † The `summary`, `ocr_text` and `transcription` fields are only populated when the file was ingested with the `high_quality` [parsing strategy](https://www.mixedbread.com/docs/stores/store-files#parsing-strategy). ### Chunk Types **Text Chunks** ```json { "type": "text", "text": "User authentication in our API requires a valid API key...", "summary": "API authentication requires a valid API key and uses request headers to identify callers.", "chunk_index": 2, "offset": 1024, "mime_type": "text/plain", "score": 0.89 } ``` **Image Chunks** ```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 } ``` **Audio Chunks** ```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 } ``` **Video Chunks** ```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 } ``` ### Complete Chunk Example ```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 } ``` # Metadata Filtering URL: https://www.mixedbread.com/docs/stores/metadata-filtering Learn how to filter Store files and search results using powerful metadata queries with logical and comparison operators. Metadata filtering provides a powerful way to narrow down results based on the metadata attached to your files. > **Note** > > **Need to understand metadata types?** This page covers filtering syntax and operations. For supported metadata types and structure, see [Metadata Types](https://www.mixedbread.com/docs/stores/store-files/metadata-types). ## Quick Example Here's a simple example of filtering files by category: **Basic Metadata Filter** Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") response = mxbai.stores.files.list( store_identifier="my-knowledge-base", limit=10, metadata_filter={"key": "category", "value": "documentation", "operator": "eq"}, ) for file in response.data: print(file) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") response = await mxbai.stores.files.list( store_identifier="my-knowledge-base", limit=10, metadata_filter={"key": "category", "value": "documentation", "operator": "eq"}, ) for file in response.data: print(file) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const response = await mxbai.stores.files.list("my-knowledge-base", { limit: 10, metadata_filter: { key: "category", value: "documentation", operator: "eq", }, }); for (const file of response.data) { console.log(file); } ``` cURL: ```bash curl -X POST https://api.mixedbread.com/v1/stores/my-knowledge-base/files/list \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -d '{ "limit": 10, "metadata_filter": { "key": "category", "value": "documentation", "operator": "eq" } }' ``` ## Filter Structure Filters can be structured in two ways depending on your needs: ### Single Field Filter (Direct Condition) For simple single-field filtering, you can use a direct condition: ```json {"key": "metadata_key", "operator": "comparison", "value": "target_value"} ``` Example: ```json {"key": "category", "operator": "eq", "value": "documentation"} ``` ### Multiple Field Filter (Logical Operators) For complex filtering with multiple conditions, use logical operators: ```json { "logical_operator": [ {"key": "metadata_key", "operator": "comparison", "value": "target_value"} ] } ``` Example filter structure: ```json { "all": [ {"key": "category", "operator": "eq", "value": "documentation"} ] } ``` ### Generated Metadata Fields You can target auto-generated chunk metadata by prefixing the key with `generated_metadata.`. This works the same way as regular metadata filters and is especially useful for filtering on values described in [Generated Metadata](https://www.mixedbread.com/docs/stores/store-files/generated-metadata). ```json { "any": [ {"key": "generated_metadata.file_type", "operator": "eq", "value": "text/markdown"}, {"key": "generated_metadata.language", "operator": "eq", "value": "en"} ] } ``` Use dot notation to drill into nested structures, e.g. `generated_metadata.chunk_headings.level`. ### System Fields In addition to file metadata and generated metadata, you can filter on a small set of indexed system fields by referencing them directly (without any prefix): - `file_id` — the file the chunk belongs to - `chunk_index` — the position of the chunk within its file ```json { "all": [ {"key": "file_id", "operator": "eq", "value": "f3c1..."}, {"key": "chunk_index", "operator": "lt", "value": 10} ] } ``` This is useful for restricting search to a specific file or to the leading chunks of each file (e.g. titles or introductions). ## Logical Operators Combine multiple conditions using logical operators to create sophisticated filters. Groups can sit side by side in one filter object: `all`, `any` and `none` at the same level must all hold. ### All (AND Operation) All conditions must be true: ```json { "all": [ {"key": "category", "operator": "eq", "value": "documentation"}, {"key": "language", "operator": "eq", "value": "python"}, {"key": "status", "operator": "eq", "value": "published"} ] } ``` ### Any (OR Operation) At least one condition must be true: ```json { "any": [ {"key": "language", "operator": "eq", "value": "python"}, {"key": "language", "operator": "eq", "value": "javascript"}, {"key": "language", "operator": "eq", "value": "typescript"} ] } ``` ### None (NOT Operation) None of the conditions should be true: ```json { "none": [ {"key": "status", "operator": "eq", "value": "deprecated"}, {"key": "status", "operator": "eq", "value": "draft"} ] } ``` ## Comparison Operators ### Equality and Comparison 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"} // Pattern matching: case-insensitive, anywhere in the value {"key": "title", "operator": "like", "value": "quarterly%report"} // Pattern not matching (files without the field are kept) {"key": "path", "operator": "not_like", "value": "/tmp/%"} // 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: wrap starts_with in a none group {"none": [{"key": "path", "operator": "starts_with", "value": "/tmp/"}]} ``` > **Note** > > **`like` patterns:** `%` matches any run of characters and `_` matches exactly one; `*` and `?` > are ordinary characters. A pattern matches anywhere in the value and ignores case, so `"report"` > matches `"Q3 Report.pdf"`. Escape a literal `%`, `_` or backslash with a backslash > (`"100\\%"` in JSON). For an anchored or case-sensitive match, use `starts_with` or `regex`. > **Note** > > **`contains` vs `in`:** `in` checks whether a field's value is one of the values you provide > (`field ∈ [a, b, c]`). `contains` is the reverse — it checks whether the field itself contains the > value you provide. On a **text** field it matches a substring; on a **list/array** field (such as > `tags` or an `acl` array) it matches when the array includes that exact element. Both are > case-sensitive. ## Data Type Filtering ### String Values Case-sensitive by default - ensure consistent casing in your metadata: ```json // String Values (case-sensitive) {"key": "category", "operator": "eq", "value": "Documentation"} // Won't match "documentation" // Use consistent casing in metadata { "category": "documentation", // lowercase "status": "published", // lowercase "team": "engineering" // lowercase } ``` ### Numeric Values Support integer and float comparisons: ```json // Numeric Values {"key": "priority", "operator": "gt", "value": 5} {"key": "score", "operator": "gte", "value": 0.8} ``` ### Boolean Values Support true/false conditions: ```json // Boolean Values {"key": "is_public", "operator": "eq", "value": true} {"key": "deprecated", "operator": "eq", "value": false} ``` ### Date Values Recommend ISO 8601 format: ```json // Date Values (ISO 8601 format recommended) {"key": "created_at", "operator": "gte", "value": "2024-01-01"} {"key": "last_updated", "operator": "lt", "value": "2024-12-31T23:59:59Z"} ``` ### Array/List Values Support membership filtering: ```json // Array/List Values { "tags": ["tutorial", "python", "web"], "authors": ["alice", "bob"] } // Filter by array membership {"key": "tags", "operator": "in", "value": ["tutorial", "guide"]} // eq / not_eq on an array compare against its elements {"key": "authors", "operator": "eq", "value": "alice"} ``` On an array field, `eq`, `in` and `contains` match when any element matches, and `not_eq` / `not_in` match when no element does. ## Combined Logical Operations ### Nested Conditions Complex multi-level filtering example: ```json { "all": [ {"key": "category", "operator": "eq", "value": "documentation"}, { "any": [ {"key": "language", "operator": "eq", "value": "python"}, {"key": "language", "operator": "eq", "value": "javascript"} ] } ], "none": [ {"key": "status", "operator": "eq", "value": "deprecated"} ] } ``` ### Advanced Filtering Example Here's a practical example demonstrating complex nested filters: **Advanced Metadata Filter** Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") metadata_filter = { "all": [ {"key": "status", "value": "published", "operator": "eq"}, { "any": [ {"key": "priority", "value": 3, "operator": "gte"}, { "all": [ {"key": "category", "value": "important", "operator": "eq"}, {"key": "reviewed", "value": True, "operator": "eq"}, ] }, ] }, ] } response = mxbai.stores.files.list( store_identifier="my-knowledge-base", limit=10, metadata_filter=metadata_filter, ) for file in response.data: print(file) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") metadata_filter = { "all": [ {"key": "status", "value": "published", "operator": "eq"}, { "any": [ {"key": "priority", "value": 3, "operator": "gte"}, { "all": [ {"key": "category", "value": "important", "operator": "eq"}, {"key": "reviewed", "value": True, "operator": "eq"}, ] }, ] }, ] } response = await mxbai.stores.files.list( store_identifier="my-knowledge-base", limit=10, metadata_filter=metadata_filter, ) for file in response.data: print(file) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; import type { FileListParams } from "@mixedbread/sdk/resources/stores"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const metadataFilter: FileListParams["metadata_filter"] = { all: [ { key: "status", value: "published", operator: "eq", }, { any: [ { key: "priority", value: 3, operator: "gte", }, { all: [ { key: "category", value: "important", operator: "eq", }, { key: "reviewed", value: true, operator: "eq", }, ], }, ], }, ], }; const response = await mxbai.stores.files.list("my-knowledge-base", { limit: 10, metadata_filter: metadataFilter, }); for (const file of response.data) { console.log(file); } ``` cURL: ```bash curl -X POST https://api.mixedbread.com/v1/stores/my-knowledge-base/files/list \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -d '{ "limit": 10, "metadata_filter": { "all": [ {"key": "status", "value": "published", "operator": "eq"}, { "any": [ {"key": "priority", "value": 3, "operator": "gte"}, { "all": [ {"key": "category", "value": "important", "operator": "eq"}, {"key": "reviewed", "value": true, "operator": "eq"} ] } ] } ] } }' ``` > **Diagram**: Interactive playground that runs preset metadata filters against six sample files. The files are quickstart.md (category documentation, language python, status published, priority 4, reviewed, tags tutorial and python), js-sdk.md (documentation, javascript, draft, priority 2, not reviewed, tag guide), types.md (documentation, typescript, published, priority 1, reviewed, tag reference), security.md (important, python, published, priority 2, reviewed, tag audit), v1-api.md (important, javascript, deprecated, priority 5, not reviewed, tag tutorials) and Setup.md (category "Documentation" with a capital D, python, published, priority 2, not reviewed, tag tutorial). An all group of category eq documentation and an any group of language eq python or javascript matches quickstart.md and js-sdk.md; types.md is typescript and Setup.md fails the case-sensitive category check. The advanced filter, status eq published and either priority gte 3 or an all group of category eq important and reviewed eq true, matches quickstart.md through its priority and security.md through the inner all group; v1-api.md has priority 5 but is deprecated. A none group of status eq deprecated and status eq draft matches every file except js-sdk.md and v1-api.md. language in ["java", "python"] matches the three python files, because in requires the field to equal a listed value, while language contains "java" is a substring match and matches the two javascript files. tags contains "tutorial" matches quickstart.md and Setup.md but not v1-api.md, because array membership needs the exact element. category eq "Documentation" matches only Setup.md, because string matching is case-sensitive. # Agentic Search with Toast 1 URL: https://www.mixedbread.com/docs/stores/search/agentic-search Multi-round search driven by Toast 1 that decomposes complex questions, runs follow-up queries, and ranks the merged results. A single search returns the chunks closest to one query. That works for lookups, but breaks down on questions that need multiple sources, span several time periods, or hide their best phrasing from the user. Agentic Search wraps the search endpoint in a loop driven by [Toast 1](https://www.mixedbread.com/docs/agent/models), our specialized search model: the agent runs parallel sub-queries, analyzes metadata facets, inspects retrieved results, and decides whether to search again before submitting a final ranked chunk list. The response shape is identical to a normal search (a ranked list of scored chunks), so Agentic Search is a drop-in upgrade for quality-sensitive queries. If you want to run Toast 1 against your own tools instead of the hosted loop, see [Build your own harness](https://www.mixedbread.com/docs/agent/build-your-own-harness). ## When to use it Reach for Agentic Search when one search is not enough. Typical signals: - The question fans out across multiple entities, years, or sources (e.g. *"Compare revenue, headcount, and churn across 2020 to 2025"*). - The user phrasing is conversational and underspecified, but the underlying answer needs precise terminology. - A single top-k list keeps missing relevant chunks and/or includes irrelevant chunks because the right query isn't obvious upfront. It is slower than a single search because of the extra LLM calls and retrievals, so use plain [Search](https://www.mixedbread.com/docs/stores/search) for narrow lookups and reach for Agentic Search when quality matters more than latency. ## Basic Usage Agentic Search is powered by [Toast 1](https://www.mixedbread.com/docs/agent/models), our specialized search agent. Enable it by setting `search_options.agentic` to `true`: **Agentic Search** Python: ```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": True}, ) print(results) ``` Python (async): ```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": True}, ) print(results) ``` TypeScript: ```ts 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: true, }, }); console.log(results); ``` cURL: ```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": True } }' ``` The output uses the same shape as the normal search response. When `agentic` is enabled, `rewrite_query` and `rerank` are ignored, since the agent handles query decomposition and ranking itself. ## Stream traces Set `stream` to `true` to watch the agent's trace while the search is running, instead of waiting for the entire search to finish. Streaming is available only for Agentic Search, so `search_options.agentic` must also be enabled. **Stream an Agentic Search Trace** Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") events = mxbai.stores.search( query="How did revenue change from 2024 to 2025?", store_identifiers=["yearly-reports"], search_options={"agentic": True}, stream=True, ) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") events = await mxbai.stores.search( query="How did revenue change from 2024 to 2025?", store_identifiers=["yearly-reports"], search_options={"agentic": True}, stream=True, ) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const events = await mxbai.stores.search({ query: "How did revenue change from 2024 to 2025?", store_identifiers: ["yearly-reports"], search_options: { agentic: true, }, stream: true, }); ``` cURL: ```bash curl --no-buffer -X POST https://api.mixedbread.com/v1/stores/search \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -d '{ "query": "How did revenue change from 2024 to 2025?", "store_identifiers": ["yearly-reports"], "search_options": { "agentic": true }, "stream": true }' ``` For a full list of event types, see [streaming events](https://www.mixedbread.com/api-reference/endpoints/stores/search/search-chunks#streaming-events). ## How it Works Each agentic search runs as a bounded loop: 1. **Initial search and metadata.** The original query is run as-is while compact metadata facets are fetched for the selected stores. This guarantees the exact phrasing is always represented in the candidate pool, even if the agent later goes off in a different direction. 2. **Plan and retrieve.** The agent inspects results, then either submits a ranking or issues up to 8 parallel retrieval calls: `search_corpus` for focused semantic sub-queries, `grep` for exact tokens, codes, identifiers, and regex patterns, and `filter_chunks` for metadata-first filtering and sorting. A `prune_context` tool lets the agent drop chunks it has ruled out to stay within its context budget. 3. **Iterate.** Step 2 repeats until the agent has enough context or exhausts its budget of 3 rounds (the final ranking turn included). New chunks are merged into a deduplicated pool. 4. **Submit ranking.** The agent calls `submit_ranking` with the chunks it considers most relevant. With `strict_top_k=true`, the agent fills the ranking to `top_k` chunks and the result is capped at `top_k`. If the agent stops without submitting a ranking, the service forces one final ranking call so you always get a result back. > **Diagram**: Animated diagram of one Agentic Search run over its budget of 3 rounds (the final ranking turn included), for the query "Compare revenue, headcount, and churn across 2020 to 2025" with top_k 5, strict_top_k true and score_threshold 0.5. First, the initial search and metadata: side by side, the original query runs as-is and adds 6 chunks to the candidate pool while metadata facets (year, doc_type) are fetched for the store. Round 1, plan and retrieve: Toast 1 inspects the results and issues 3 parallel retrieval calls (up to 8 are allowed): search_corpus for a semantic sub-query, grep for an exact-token regex and filter_chunks for metadata filtering and sorting. New chunks merge into the deduplicated pool, which grows to 11; chunks found again are not added twice. Round 2 repeats step 2: prune_context drops 3 ruled-out chunks while new search_corpus and grep calls add 3. Round 3 is the final ranking turn: the agent calls submit_ranking with 5 chunks, filled to top_k because strict_top_k is true (the service forces this call if the agent stops without ranking). score_threshold then filters last and removes the chunk scoring below 0.5, so 4 chunks are returned, fewer than top_k. ## Configuration Pass an object instead of `true` to steer the agent: **Agentic Search Config** Python: ```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 (async): ```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: ```ts 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); ``` cURL: ```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." } } }' ``` ### Parameters All fields under `search_options.agentic` are optional. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `instructions` | string | `null` | Free-form guidance appended to the agent's system prompt (up to 5,000 characters). Use it to bias the agent toward specific entities, metrics, source types, or ranking criteria. Followed only when not in conflict with the built-in search rules. | | `strict_top_k` | boolean | `false` | When `true`, the agent fills the ranking to `top_k` chunks from what it retrieved and the result is capped at `top_k`; fewer are returned when the agent retrieved fewer. When `false`, the agent can return all the chunks it considers relevant. | #### Example instructions - `"Prefer primary sources over summaries when both are available."` - `"Prioritize the most recent fiscal year, then compare year-over-year."` - `"Treat tables and figures as authoritative; treat marketing copy as weak signal."` ## Combining with other features The fields outside `search_options.agentic` still affect the agentic run: - **`top_k`**: target result size, and the size the result is capped at when `strict_top_k=true`. - **`filters`**: applied to local store retrievals, not just the original. - **`file_ids`**: local store retrievals are constrained to these files. - **`store_identifiers`**: semantic and wide retrievals search across all listed stores. Include `mixedbread/web` to let the agent pull in [web search](https://www.mixedbread.com/docs/stores/search/web-store) results alongside your own stores. - **`search_options.score_threshold`**: applied as a final filter after ranking; can return fewer than `top_k` chunks even with `strict_top_k=true`. `search_options.rewrite_query` and `search_options.rerank` are ignored when agentic is enabled, since the agent owns query decomposition and ranking. ## Observability Every agentic search emits a structured trace. The dashboard renders it as a waterfall view of LLM generations, metadata inspection, retrieval tool calls, and sub-queries, with timing and round numbers, so you can see exactly what the agent did and where time was spent: > **Figure**: Agentic Search trace in the dashboard, showing a waterfall of search and generation spans across multiple rounds for a single query. The same data is available programmatically by listing store events with `event_type=agentic_search`. Each event captures the original query, instructions, rounds executed, token usage, and the ordered list of tool calls the agent issued (with `arguments`, `result`, `duration`, and any `error`). Tool call fields follow the [OpenTelemetry GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/), so traces interoperate with standard observability tooling. For the full response schema, see [List Store Events](https://www.mixedbread.com/api-reference/endpoints/stores/events/list-store-events). Use these events to debug unexpected results ("why didn't the agent find X?") or build dashboards on top of the agent's behavior. You can also have these traces pushed to your own observability backend (Langfuse, or any OTLP collector) as they happen; see [Trace Export](https://www.mixedbread.com/docs/production/tracing). ## Tips - **Start with the defaults.** `agentic: true` with no instructions is a strong baseline for most workloads. - **Use `instructions` to encode domain knowledge** the agent can't infer from the query (e.g. preferred source types, entity disambiguation rules). - **Keep `strict_top_k=false`** when you need high precision, as the agent will not include irrelevant chunks in its output. - **Combine with `mixedbread/web`** for hybrid runs that mix internal stores with the open web in a single ranked list. - **Inspect the trace when results surprise you.** The dashboard waterfall and the events feed show every round, sub-query, and tool call, so you can see which searches the agent ran and why a chunk was or wasn't found. # Metadata Facets URL: https://www.mixedbread.com/docs/stores/search/facets Learn how to use metadata facets to group search results by metadata values. Metadata facets allow you to group search results by metadata values. This is useful for exploring your data based on metadata properties like category, language, or author. You can retrieve facets for a single Store or across multiple Stores. ## Basic Metadata Facets To get all metadata facets for one or more Stores, you can call: **Get Metadata Facets** Python: ```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 (async): ```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: ```ts 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); ``` cURL: ```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"] }' ``` This returns the unnested metadata values with their respective counts: ```json { "facets": { "author": { "John Doe": 1, "Jane Doe": 2 }, "language": { "english": 2, "spanish": 1 } } } ``` > **Note** > > If you want to get the facets for a specific field, you can pass the field > name to the `facets` parameter. We recommend this if your metadata contains > many unique values for a field. ## Nested Metadata Facets For complex metadata structures with nested objects, you can access specific nested fields by using dot notation (`.`) to separate the field hierarchy. This allows you to create facets for deeply nested properties without flattening your entire metadata structure. For example, if your documents have metadata like: **Get Nested Metadata Facets** Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") response = mxbai.stores.metadata_facets( store_identifiers=["docs"], facets=["city.name", "city.country"], ) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") response = await mxbai.stores.metadata_facets( store_identifiers=["docs"], facets=["city.name", "city.country"], ) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const response = await mxbai.stores.metadataFacets({ store_identifiers: ["docs"], facets: ["city.name", "city.country"], }); ``` cURL: ```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"], "facets": ["city.name", "city.country"] }' ``` This returns the nested metadata values with their respective counts: ```json { "facets": { "city.name": { "New York": 2, "London": 1 }, "city.country": { "United States": 2, "United Kingdom": 1 } } } ``` ## Multi-Store Facets You can retrieve facets across multiple Stores by providing an array of Store identifiers. This is useful when you want to explore metadata across different data sources or Store versions. ```python facets = client.stores.metadata_facets( store_identifiers=["docs-v1", "docs-v2", "blog-posts"], facets=["category", "language"] ) ``` The response will aggregate facet counts across all specified Stores, giving you a unified view of your metadata distribution. ## Filtering Search Results Metadata facets can be obtained for search results by using the same parameters as the search endpoint. For example, to get the facets for a specific query, you can call: **Get Metadata Facets for a Query** Python: ```python from mixedbread import Mixedbread from mixedbread.types import ( SearchFilter, SearchFilterCondition, ) mxbai = Mixedbread(api_key="YOUR_API_KEY") response = mxbai.stores.metadata_facets( store_identifiers=["docs"], query="What are the main features of the product?", top_k=5, filters=SearchFilter( all=[SearchFilterCondition(key="city.name", value="New York", operator="eq")] ), ) ``` Python (async): ```python from mixedbread import AsyncMixedbread from mixedbread.types import ( SearchFilter, SearchFilterCondition, ) mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") response = await mxbai.stores.metadata_facets( store_identifiers=["docs"], query="What are the main features of the product?", top_k=5, filters=SearchFilter( all=[SearchFilterCondition(key="city.name", value="New York", operator="eq")] ), ) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const response = await mxbai.stores.metadataFacets({ store_identifiers: ["docs"], query: "What are the main features of the product?", top_k: 5, filters: { all: [{ key: "city.name", value: "New York", operator: "eq" }], }, }); ``` cURL: ```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"], "query": "What are the main features of the product?", "top_k": 5, "filters": { "all": [ { "key": "city.name", "value": "New York", "operator": "eq" }, ], }, }' ``` # Search URL: https://www.mixedbread.com/docs/stores/search Learn how to search your Store with semantic queries, configuration options, and advanced filtering capabilities. Search your Store using natural language to find exactly what you need. Stores understand the meaning behind your queries, not just keywords, making it perfect for conversational search and complex questions. ## Basic Search Search for chunks of content across your Store: **Search Store** Python: ```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 (async): ```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: ```ts 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); } ``` cURL: ```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 }' ``` When you search, Stores understand your natural language query and find the most relevant content across all your files. Results are automatically ranked by relevance with confidence scores. For complete details on chunk object structure including all content types and properties, see [Data Models](https://www.mixedbread.com/docs/stores/data-models#store-chunk). ## Search Options ### Top-k Results Control the number of results returned: **Top-k Results** Python: ```python results1 = mxbai.stores.search( query="API authentication methods", store_identifiers=["docs"], top_k=5 ) results2 = mxbai.stores.search( query="deployment strategies", store_identifiers=["docs"], top_k=20 ) ``` TypeScript: ```ts const results1 = await mxbai.stores.search({ query: "API authentication methods", store_identifiers: ["docs"], top_k: 5, }); const results2 = await mxbai.stores.search({ query: "deployment strategies", store_identifiers: ["docs"], top_k: 20, }); ``` **Optimization Tips:** - Start with `top_k=10` for most use cases - Increase for comprehensive searches - Decrease for faster response times ### Filter Filter search results to narrow down your search scope. Store search supports two types of filtering: **Metadata Filtering** Python: ```python results = mxbai.stores.search( query="user authentication", store_identifiers=["docs"], filters={ "all": [ {"key": "category", "operator": "eq", "value": "documentation"}, {"key": "difficulty", "operator": "in", "value": ["beginner", "intermediate"]} ] } ) ``` TypeScript: ```ts const results = await mxbai.stores.search({ query: "user authentication", store_identifiers: ["docs"], filters: { all: [ { key: "category", operator: "eq", value: "documentation" }, { key: "difficulty", operator: "in", value: ["beginner", "intermediate"], }, ], }, }); ``` For complete metadata filtering capabilities and advanced patterns, see [Metadata Filtering](https://www.mixedbread.com/docs/stores/metadata-filtering). **File Filtering** Python: ```python results1 = mxbai.stores.search( query="authentication methods", store_identifiers=["docs"], file_ids=["123e4567-e89b-12d3-a456-426614174000", "123e4567-e89b-12d3-a456-426614174001"] ) results2 = mxbai.stores.search( query="authentication methods", store_identifiers=["docs"], file_ids=("in", ["123e4567-e89b-12d3-a456-426614174000"]) ) results3 = mxbai.stores.search( query="authentication methods", store_identifiers=["docs"], file_ids=("not_in", ["123e4567-e89b-12d3-a456-426614174000"]) ) ``` TypeScript: ```ts const results1 = await mxbai.stores.search({ query: "authentication methods", store_identifiers: ["docs"], file_ids: [ "123e4567-e89b-12d3-a456-426614174000", "123e4567-e89b-12d3-a456-426614174001", ], }); const results2 = await mxbai.stores.search({ query: "authentication methods", store_identifiers: ["docs"], file_ids: ["in", ["123e4567-e89b-12d3-a456-426614174000"]], }); const results3 = await mxbai.stores.search({ query: "authentication methods", store_identifiers: ["docs"], file_ids: ["not_in", ["123e4567-e89b-12d3-a456-426614174000"]], }); ``` ### Rerank Improve search result quality by reranking results with specialized models: **Reranking Examples** Python: ```python results = mxbai.stores.search( query="API rate limiting best practices", store_identifiers=["docs"], search_options={ "rerank": True } ) ``` TypeScript: ```ts const results = await mxbai.stores.search({ query: "API rate limiting best practices", store_identifiers: ["docs"], search_options: { rerank: true, }, }); ``` Reranking applies a second-stage ranking model to improve relevance, especially useful for complex queries or when initial results need refinement. You can use simple boolean (`True`) or configure advanced options with model selection and metadata inclusion. Learn more about [Rerank](https://www.mixedbread.com/docs/stores/search/rerank) for advanced reranking strategies and model options. ### Rewrite Query Let a specialized AI model rewrite your query to get the most optimal semantic search experience. It automatically applies best practices like adding more context and using full semantic qualifiers instead of keywords. **Rewrite Query** Python: ```python results = mxbai.stores.search( query="machine learning deployment", store_identifiers=["documentation"], top_k=15, search_options={ "rewrite_query": True }, ) ``` TypeScript: ```ts const results = await mxbai.stores.search({ query: "machine learning deployment", store_identifiers: [ "documentation", ], top_k: 15, search_options: { rewrite_query: true }, }); ``` You can get the rewritten query by calling the `/v1/stores/{store_identifier}/events` endpoint. **Considerations:** - The latency increases due to additional agent calls - Not every query needs to be rewritten ### Multi Store Search Search across multiple Stores simultaneously: **Multi Store Search** Python: ```python results = mxbai.stores.search( query="machine learning deployment", store_identifiers=[ "documentation", "research-papers", "tutorials", "code-examples" ], top_k=15 ) ``` TypeScript: ```ts const results = await mxbai.stores.search({ query: "machine learning deployment", store_identifiers: [ "documentation", "research-papers", "tutorials", "code-examples", ], top_k: 15, }); ``` **Considerations:** - Results are merged and re-ranked together - May need higher top_k for diverse results - Different Stores may have different metadata schemas ### Agentic Search For complex questions that need multiple sources, an agent can plan, run, and rank a series of searches for you in a single call: **Agentic Search** Python: ```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": True}, ) print(results) ``` Python (async): ```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": True}, ) print(results) ``` TypeScript: ```ts 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: true, }, }); console.log(results); ``` cURL: ```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": True } }' ``` The response shape matches a normal search. See [Agentic Search](https://www.mixedbread.com/docs/stores/search/agentic-search) for the full parameter reference, configuration examples, and how to inspect the agent's tool calls and token usage via the events endpoint. Additional options let you steer the agent and the result shape: - `strict_top_k` (default `false`): return only chunks the agent considers relevant. Set to `true` to fill the result with the `top_k` most relevant chunks the agent found. - `instructions`: free-form guidance for the agent, e.g. preferred source types or ranking criteria. ### Web Search Search the web using the same API by including `mixedbread/web` as a store identifier. You can use it standalone or combine it with your own stores for hybrid search that merges web results with your internal knowledge base. **Web Search** Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") results = mxbai.stores.search( query="latest AI research papers", store_identifiers=["mixedbread/web", "internal-docs"], top_k=10, ) print(results) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") results = await mxbai.stores.search( query="latest AI research papers", store_identifiers=["mixedbread/web", "internal-docs"], top_k=10, ) print(results) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const results = await mxbai.stores.search({ query: "latest AI research papers", store_identifiers: ["mixedbread/web", "internal-docs"], top_k: 10, }); console.log(results); ``` cURL: ```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 AI research papers", "store_identifiers": ["mixedbread/web", "internal-docs"], "top_k": 10 }' ``` For detailed web search capabilities and response format, see [Web Store](https://www.mixedbread.com/docs/stores/search/web-store). # Question Answering URL: https://www.mixedbread.com/docs/stores/search/question-answering Get AI-powered answers to your questions using Store content as context, with optional citations and multimodal support. Question Answering turns your store into an AI-powered knowledge base. Instead of returning raw content like search, it generates complete answers based on the retrieved context. ## Basic Question Answering Ask questions and get augmented answers based on your Store content: **Question Answering** Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") response = mxbai.stores.question_answering( store_identifiers=["my-knowledge-base"], query="What are the main features of the product?", top_k=5, instructions=( "Answer for an API evaluator. Use concise bullets and cite the most relevant sources." ), qa_options={"cite": True, "multimodal": True}, ) print(response) ``` Python (async): ```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 are the main features of the product?", top_k=5, instructions=( "Answer for an API evaluator. Use concise bullets and cite the most relevant sources." ), qa_options={"cite": True, "multimodal": True}, ) print(response) ``` TypeScript: ```ts 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 are the main features of the product?", top_k: 5, instructions: "Answer for an API evaluator. Use concise bullets and cite the most relevant sources.", qa_options: { cite: true, multimodal: true }, }); console.log(response); ``` cURL: ```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 are the main features of the product?", "top_k": 5, "instructions": "Answer for an API evaluator. Use concise bullets and cite the most relevant sources.", "qa_options": { "cite": true, "multimodal": true } }' ``` Multimodal support enables: - **Image understanding**: Answers based on diagrams, charts, and visuals - **OCR text**: Extracted text from images contributes to answers Pass `instructions` when you want to control answer style, scope, or formatting. Typical uses include enforcing concise bullet points, prioritizing specific facts, or asking the model to cite only the strongest supporting passages. ## Defaults and configuration By default, Question Answering uses citations and multimodal context. To change behavior, pass `qa_options` explicitly. **Disable citations and multimodal** Python: ```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 (async): ```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: ```ts 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); ``` cURL: ```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 } }' ``` ## Example Response **QA Response** JSON: ```json { "answer": "Based on the provided source, the key decision made last quarter involved finalizing the budget for Project Alpha .", "sources": [ { "chunk_index": 2, "mime_type": "text/plain", "model": "mxbai-omni", "score": 0.92, "file_id": "your_file_id_1", "filename": "meeting_notes_q1.docx", "store_id": "{{STORE_ID}}", "metadata": {}, "type": "text", "text": "In the Q1 board meeting, we agreed to finalize the budget for Project Alpha with a total allocation of $2.5M..." } ] } ``` - **Answer**: AI-generated answer. May include citation tags like ``. - **Sources**: Context used for the answer. Each entry includes: - `chunk_index`, `score`, `file_id`, `filename` - Content fields: `text`, `image_url`, with optional `ocr_text` - Use indices from `` to map to `sources[n]` ## Inspecting requests Every Question Answering request is recorded as a `qa` event. Each event covers the whole request in one record: the retrieval that gathered the context (as tool calls, whether it ran as a plain or an agentic search) and the answer generation, with the chunks the answer was grounded in and the indices it cited. List them with `event_type=qa` on the [store events](https://www.mixedbread.com/api-reference/endpoints/stores/events/list-store-events) or [organization events](https://www.mixedbread.com/api-reference/endpoints/events/list-events) endpoint, or open a Store's **Metrics** tab in the dashboard and switch to **Q&A Events**. > **Note** > > The retrieval half of a Question Answering request does not also appear under > `event_type=search` or `event_type=agentic_search`. Each request shows up > exactly once, as a `qa` event. # Reranking URL: https://www.mixedbread.com/docs/stores/search/rerank Learn how to use reranking to improve search result quality and relevance in your Store searches. Reranking is an advanced feature that improves the quality and relevance of search results by using specialized models to re-evaluate and reorder the initial results. This second-pass approach significantly enhances result accuracy at the cost of slightly increased latency. ## Basic Configuration The simplest way to enable reranking is to set `rerank=True` in your search request: **Enable Reranking** Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") results = mxbai.stores.search( query="API authentication methods", store_identifiers=["docs"], top_k=10, search_options={ "rerank": True } ) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") results = await mxbai.stores.search( query="API authentication methods", store_identifiers=["docs"], top_k=10, search_options={ "rerank": True } ) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const results = await mxbai.stores.search({ query: "API authentication methods", store_identifiers: ["docs"], top_k: 10, search_options: { rerank: true, }, }); ``` cURL: ```bash curl -X POST https://api.mixedbread.com/v1/stores/search -H 'Content-Type: application/json' -H 'Authorization: Bearer YOUR_API_KEY' -d '{ "query": "API authentication methods", "store_identifiers": ["docs"], "top_k": 10, "search_options": { "rerank": true } }' ``` This uses our default reranking model (`mixedbread-ai/mxbai-rerank-v3.1-listwise`) with standard settings to improve your search results. ## Advanced Configuration **Rerank with Configuration** Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") results = mxbai.stores.search( query="database optimization techniques", store_identifiers=["docs"], search_options={ "rerank": { "model": "mixedbread-ai/mxbai-rerank-v3.1-listwise", "top_k": 15, "with_metadata": ["category", "difficulty"] } } ) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") results = await mxbai.stores.search( query="database optimization techniques", store_identifiers=["docs"], search_options={ "rerank": { "model": "mixedbread-ai/mxbai-rerank-v3.1-listwise", "top_k": 15, "with_metadata": ["category", "difficulty"] } } ) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const results = await mxbai.stores.search({ query: "database optimization techniques", store_identifiers: ["docs"], search_options: { rerank: { model: "mixedbread-ai/mxbai-rerank-v3.1-listwise", top_k: 15, with_metadata: ["category", "difficulty"], }, }, }); ``` cURL: ```bash curl -X POST https://api.mixedbread.com/v1/stores/search -H 'Content-Type: application/json' -H 'Authorization: Bearer YOUR_API_KEY' -d '{ "query": "database optimization techniques", "store_identifiers": ["docs"], "search_options": { "rerank": { "model": "mixedbread-ai/mxbai-rerank-v3.1-listwise", "top_k": 15, "with_metadata": ["category", "difficulty"] } } }' ``` **Configuration Options:** - **Reranking Models**: Use any supported reranking model. Defaults to `"mixedbread-ai/mxbai-rerank-v3.1-listwise"` when not specified. See [Available Models](#available-models) below. - **Top-k Constraint**: The `top_k` value must be smaller than or equal to the first-stage retrieval count (your main `top_k` parameter). Defaults to `null`, which returns all results from the first stage (respects your main `top_k` parameter). - **Metadata Inclusion**: Defaults to `false`. Set to `true` to include all metadata, or provide a list of specific metadata keys to include. ## Available Models | Model | Type | Notes | | --- | --- | --- | | `mixedbread-ai/mxbai-rerank-v3.1-listwise` | Listwise | Default. Reads the candidate set as a whole and follows natural-language instructions. See the [announcement](https://www.mixedbread.com/blog/mxbai-rerank-v3-1-listwise). | | `mixedbread-ai/mxbai-rerank-v3-listwise` | Listwise | No longer supported. Requests using this name are served by `mixedbread-ai/mxbai-rerank-v3.1-listwise`; use that model instead. | | `mixedbread-ai/mxbai-rerank-large-v2` | Pointwise | 1.5B-parameter model tuned for accuracy across 100+ languages. | # Web Store URL: https://www.mixedbread.com/docs/stores/search/web-store Search the web using the same API as your stores. Combine web results with your own data for comprehensive search. The Web Store lets you search the web using the same familiar Store API. Instead of searching your uploaded documents, it searches the internet and returns results in the same format as regular store searches. ## Basic Web Search Search the web by using `mixedbread/web` as a store identifier: **Web Search** Python: ```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 (async): ```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: ```ts 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(); } ``` cURL: ```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 }' ``` Each result includes the page title, the source URL (available in both the `filename` field and `metadata.url`), and a relevant excerpt from the page content. ## Filtering by Domain Restrict web results to specific sites, or exclude sites, with a metadata filter on the `domain` key: **Domain Filter** Python: ```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, filters={"key": "domain", "operator": "in", "value": ["arxiv.org", "nature.com"]}, ) for chunk in results.data: print(f"{chunk.metadata.get('domain')}: {chunk.metadata.get('url')}") ``` Python (async): ```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, filters={"key": "domain", "operator": "in", "value": ["arxiv.org", "nature.com"]}, ) for chunk in results.data: print(f"{chunk.metadata.get('domain')}: {chunk.metadata.get('url')}") ``` TypeScript: ```ts 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, filters: { key: "domain", operator: "in", value: ["arxiv.org", "nature.com"], }, }); for (const chunk of results.data) { const metadata = chunk.metadata as | { domain: string; url: string } | undefined; console.log(`${metadata?.domain}: ${metadata?.url}`); } ``` cURL: ```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, "filters": { "key": "domain", "operator": "in", "value": ["arxiv.org", "nature.com"] } }' ``` - `eq` and `in` only return results from the listed domains; listing several domains under `any` works the same way - `not_eq` and `not_in` exclude the listed domains, as do `eq` and `in` under `none` - A domain also matches its subdomains: `wikipedia.org` covers `en.wikipedia.org`. You can add a path (`nature.com/articles`) or filter by top-level domain (`.gov`) - A search accepts at most 20 domains. When you both include and exclude domains, the excluded ones are removed from the included list. Excluding part of an included domain (such as `en.wikipedia.org` from `wikipedia.org`) removes those results after the search, so the search can return fewer than `top_k` results - Combining two included lists keeps what both match: `wikipedia.org` and `en.wikipedia.org` together only return `en.wikipedia.org` Other operators on `domain`, such as `like` or `regex`, return a validation error. Every result carries its host in `metadata.domain`. ## Hybrid Search: Web + Your Data Combine web results with your own stores for comprehensive search. This is useful when you want to augment your internal knowledge base with up-to-date information from the web. **Hybrid Search** Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") results = mxbai.stores.search( query="how to implement rate limiting", store_identifiers=[ "mixedbread/web", # Search the web "internal-docs", # Your documentation store "code-examples", # Your code examples store ], top_k=15, ) print(results) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") results = await mxbai.stores.search( query="how to implement rate limiting", store_identifiers=[ "mixedbread/web", # Search the web "internal-docs", # Your documentation store "code-examples", # Your code examples store ], top_k=15, ) print(results) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const results = await mxbai.stores.search({ query: "how to implement rate limiting", store_identifiers: [ "mixedbread/web", // Search the web "internal-docs", // Your documentation store "code-examples", // Your code examples store ], top_k: 15, }); console.log(results); ``` cURL: ```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 to implement rate limiting", "store_identifiers": ["mixedbread/web", "internal-docs", "code-examples"], "top_k": 15 }' ``` When combining web search with regular stores, results from all sources are merged together and reranked for consistent relevance scoring. The final response contains the top results based on combined relevance across all sources. ## Response Format Web search results follow the same structure as regular store search results: **Response** JSON: ```json { "object": "list", "data": [ { "type": "text", "text": "Page title\n\nA relevant excerpt from the page content...", "chunk_index": 0, "score": 0.95, "file_id": "generated-uuid-from-url", "filename": "https://example.com/article", "store_id": "00000000-0000-0000-0000-000000000001", "metadata": { "title": "Page Title", "url": "https://example.com/article", "domain": "example.com", "source": "web_search" } } ] } ``` - `text`: Contains the page title followed by a relevant excerpt - `filename`: The source URL - `metadata.url`: The source URL (same as filename) - `metadata.title`: The page title - `metadata.domain`: The host of the source URL - `metadata.source`: Always `"web_search"` for web results - `store_id`: Fixed ID for the web store ## Considerations Web search results are always reranked for optimal relevance. Usage counts toward your API rate limits like any other store search. A single search returns at most 20 web results, whatever `top_k` you ask for; in a hybrid search, `top_k` still applies in full to your own stores. Apart from conditions on `domain`, metadata filters and `file_ids` do not apply to web search results. In a hybrid search, filters still apply to your own stores, so a `domain` condition also filters their chunks by a `domain` metadata field. Results reflect current web content at search time, providing fresh information for your queries. # Supported File Types URL: https://www.mixedbread.com/docs/stores/store-files/file-types File formats supported by Mixedbread Stores for ingestion and search. Stores natively understand a wide range of file formats through multimodal AI. No extraction needed, the system directly understands text, images, and complex layouts for semantic search. ## Documents | Format | Extensions | |--------|------------| | **PDF** | `.pdf` | | **Word** | `.doc`, `.docx`, `.dotx`, `.docm`, `.dotm` | | **OpenDocument Text** | `.odt` | | **Rich Text Format** | `.rtf` | | **Text** | `.txt` | | **Markdown** | `.md`, `.mdx` | | **HTML** | `.html`, `.htm` | | **Email** | `.eml` | | **Outlook Message** | `.msg` | HTML pages are indexed by their readable content: scripts, styles, navigation and link URLs are dropped, headings, lists and simple tables are kept as markdown, and tables with merged cells are kept as minimal HTML. ## Presentations | Format | Extensions | |--------|------------| | **PowerPoint** | `.ppt`, `.pptx` | | **PowerPoint Slideshow** | `.ppsx` | | **PowerPoint Add-in** | `.ppam` | | **PowerPoint Macro-Enabled** | `.pptm`, `.potm`, `.ppsm` | | **OpenDocument Presentation** | `.odp` | | **Keynote (6.5+)** | `.key` | ## Spreadsheets | Format | Extensions | |--------|------------| | **Excel Workbook** | `.xlsx` | | **Excel Macro-Enabled Workbook** | `.xlsm` | | **CSV** | `.csv`, `.tsv` | ## Code | Language | Extensions | |----------|------------| | **Python** | `.py` | | **JavaScript** | `.js` | | **TypeScript** | `.ts` | | **Java** | `.java` | | **C#** | `.cs` | | **C** | `.c`, `.h` | | **C++** | `.cpp`, `.cxx`, `.cc`, `.hpp`, `.hxx` | | **Go** | `.go` | | **Ruby** | `.rb` | | **Rust** | `.rs` | ## Images | Format | Extensions | |--------|------------| | **JPEG** | `.jpg`, `.jpeg` | | **PNG** | `.png` | | **WebP** | `.webp` | | **AVIF** | `.avif` | | **GIF** | `.gif` | | **SVG** | `.svg` | SVG files are rendered to a bitmap before they are embedded, so vector artwork is searched the same way as any other image. ## Structured Data | Format | Extensions | |--------|------------| | **JSON** | `.json` | | **JSON Lines** | `.jsonl`, `.ndjson` | | **XML** | `.xml` | JSON and XML are indexed as readable `key: value` text rather than raw syntax. XBRL instances are indexed one fact per line, with each fact's period, dimensions and unit. To control chunking yourself, use the [Mixedbread JSON format](https://www.mixedbread.com/docs/stores/store-files/mxjson). ## Specialized Formats | Format | Extensions | Notes | |--------|------------|-------| | **Mixedbread JSON** | `.mxjson` | [Pre-chunked content format](https://www.mixedbread.com/docs/stores/store-files/mxjson) | | **Mixedbread JSONL** | `.mxjsonl` | [Pre-chunked content format](https://www.mixedbread.com/docs/stores/store-files/mxjson) | The [Mixedbread JSON format](https://www.mixedbread.com/docs/stores/store-files/mxjson) allows direct ingestion of pre-chunked content. Use it when you have custom chunking logic, need to preserve specific chunk boundaries, or want to include pre-computed metadata like OCR text or transcriptions. ## Audio | Format | Extensions | |--------|------------| | **MP3** | `.mp3` | | **WAV** | `.wav` | | **OGG** | `.ogg`, `.oga` | | **M4A** | `.m4a` | | **WebM Audio** | `.weba` | | **AAC** | `.aac` | | **FLAC** | `.flac` | > **Note** > > Audio files require the `mixedbread-ai/mxbai-wholembed-v3` encoder. ## Video | Format | Extensions | |--------|------------| | **MP4** | `.mp4` | | **WebM** | `.webm` | | **QuickTime** | `.mov` | | **AVI** | `.avi` | | **OGG Video** | `.ogv` | > **Note** > > Video files require the `mixedbread-ai/mxbai-wholembed-v3` encoder. # Generated Metadata URL: https://www.mixedbread.com/docs/stores/store-files/generated-metadata Learn about the metadata generated by Mixedbread Stores for ingestion and search. Mixedbread Stores automatically generate metadata for each file ingested. This generated metadata provides structured information about the content of the file, including language, size, headings, number of pages, and more. The generated metadata can be retrieved using the `generated_metadata` chunk field. ## Metadata Types The `generated_metadata` object is a typed structure discriminated by the `type` field. If `type` is not present, it is inferred from `file_type` (MIME); otherwise it defaults to `text`. Supported `type` values: `markdown`, `text`, `email`, `csv`, `pdf`, `code`, `audio`, `video`, `image`. Every metadata object includes a `file_extension` field (e.g., `".mp3"`, `".pdf"`) reflecting the original file extension. For a full list of supported file formats, see [Supported File Types](https://www.mixedbread.com/docs/stores/store-files/file-types). ## Markdown - Heading Extraction When processing markdown files, the system automatically extracts and preserves heading structure to enhance search relevance and provide context. This feature works for all markdown formats (`.md`, `.markdown`, `.mdx`). ### What You Get Each markdown chunk’s `generated_metadata` includes: 1. `type`: Always `"markdown"`. 2. `file_type`: Always `"text/markdown"`. 3. `language`: Detected language of the text. 4. `word_count`: Word count for the chunk. 5. `file_size`: File size in bytes. 6. `chunk_headings`: Headings found within the current chunk (`[{ level: number, text: string }]`). 7. `heading_context`: The document structure context leading up to this chunk (`[{ level: number, text: string }]`). 8. `start_line`: Starting line number of the chunk in the source file. 9. `num_lines`: Number of lines in the chunk. ### Example Output Consider this markdown document: ````markdown # Getting Started ## Installation ### Prerequisites You need Python 3.8+ installed. ... ### Setup Run the following command: ```bash pip install package ``` ... ## Configuration ### Environment Variables Set these variables in your `.env` file. ### Database Setup Configure your database connection. ```` When processed, the chunks would have `generated_metadata` like this: **Chunk 1 (Prerequisites section):** ```json { "type": "markdown", "file_type": "text/markdown", "language": "en", "word_count": 6, "file_size": 1234, "chunk_headings": [ {"level": 1, "text": "Getting Started"}, {"level": 2, "text": "Installation"}, {"level": 3, "text": "Prerequisites"} ], "heading_context": [] } ``` **Chunk 2 (Setup section):** ```json { "type": "markdown", "file_type": "text/markdown", "language": "en", "word_count": 12, "file_size": 1234, "chunk_headings": [ {"level": 3, "text": "Setup"} ], "heading_context": [ {"level": 1, "text": "Getting Started"}, {"level": 2, "text": "Installation"}, {"level": 3, "text": "Prerequisites"} ] } ``` **Chunk 3 (Configuration section):** ```json { "type": "markdown", "file_type": "text/markdown", "language": "en", "word_count": 20, "file_size": 1234, "chunk_headings": [ {"level": 2, "text": "Configuration"}, {"level": 3, "text": "Environment Variables"}, {"level": 3, "text": "Database Setup"} ], "heading_context": [ {"level": 1, "text": "Getting Started"}, {"level": 2, "text": "Installation"}, {"level": 3, "text": "Setup"} ] } ``` ## Text - Common Fields Plain text chunks include a simpler `generated_metadata` shape: - `type`: `"text"` - `file_type`: `"text/plain"` - `language`: Detected language of the text - `word_count`: Word count for the chunk - `file_size`: File size in bytes - `start_line`: Starting line number of the chunk in the source file - `num_lines`: Number of lines in the chunk ### Example ```json { "type": "text", "file_type": "text/plain", "language": "en", "word_count": 57, "file_size": 2048, "start_line": 0, "num_lines": 15 } ``` ## Email - Headers Email files (`.eml` and Outlook `.msg`) carry their headers on every chunk, so a chunk deep in a long email can still be filtered by sender, recipient or date. Alongside the common text fields: - `type`: `"email"` - `file_type`: `"message/rfc822"` or `"application/vnd.ms-outlook"` - `subject`: The email subject - `from_email`: The sender's address - `to_emails`, `cc_emails`, `bcc_emails`: Recipient addresses - `date`: The sent date in ISO 8601, in UTC - `attachment_names`: File names of the attachments ### Example ```json { "type": "email", "file_type": "message/rfc822", "language": "en", "word_count": 182, "file_size": 1210, "start_line": 0, "num_lines": 14, "subject": "Quarterly update", "from_email": "jane@example.com", "to_emails": ["team@example.com"], "cc_emails": [], "bcc_emails": [], "date": "2026-07-01T09:15:00+00:00", "attachment_names": ["report.pdf"] } ``` ## CSV - Row Positions CSV files are rendered as markdown tables. Each chunk repeats the header row and holds as many data rows as fit the chunk's token budget, so a chunk always reads as a complete table. A row is only split when it cannot fit a chunk on its own: it is then broken into column groups, each led by the row's first column, and a single oversized cell is broken into pieces. Alongside the common text fields, each chunk records where its rows live in the source file. Rows and lines are 1-based, and the header is row 1. An Excel `sep=` line or a lone title above the header is skipped but still counted. Tab-separated `.tsv` files use the same parser and metadata. - `type`: `"csv"` - `file_type`: `"text/csv"` - `start_line`: Line of the chunk's first data row in the source file - `num_lines`: Number of source lines the chunk's rows span (a quoted cell may span several lines) - `start_row`: Row number of the chunk's first data row - `num_rows`: Number of rows the chunk spans The chunk's `offset` field is the character offset of the first data row. ### Example ```json { "type": "csv", "file_type": "text/csv", "language": "en", "word_count": 1240, "file_size": 18320, "start_line": 42, "num_lines": 40, "start_row": 42, "num_rows": 40 } ``` ## Code - Language and Size For supported source files (e.g., Python, TypeScript, Java, C#), `generated_metadata` includes: - `type`: `"code"` - `file_type`: One of `text/x-python`, `text/x-script.python`, `application/typescript`, `text/typescript`, `text/x-java-source`, `text/x-csharp`, or `application/javascript` - `language`: Detected programming language - `word_count`: Tokenized word count approximation for code - `file_size`: File size in bytes - `start_line`: Starting line number of the chunk in the source file - `num_lines`: Number of lines in the chunk ### Example ```json { "type": "code", "file_type": "text/x-python", "language": "python", "word_count": 120, "file_size": 8192, "start_line": 0, "num_lines": 42 } ``` ## PDF - Document Stats PDF chunks have specialized document-level stats: - `type`: `"pdf"` - `file_type`: `"application/pdf"` - `total_pages`: Total number of pages in the document - `total_size`: Total size of the original file in bytes ### Example ```json { "type": "pdf", "file_type": "application/pdf", "total_pages": 42, "total_size": 1048576 } ``` ## Image - Dimensions Image chunks include basic dimensional metadata: - `type`: `"image"` - `file_type`: String (MIME type, e.g., `image/jpeg`, `image/png`) - `file_size`: File size in bytes - `width`: Image width in pixels - `height`: Image height in pixels ### Example ```json { "type": "image", "file_type": "image/jpeg", "file_size": 204800, "width": 1920, "height": 1080 } ``` ## Audio - Media Information Audio chunks include specialized media metadata: - `type`: `"audio"` - `file_type`: String (MIME type, e.g., `audio/mpeg`, `audio/wav`) - `file_size`: File size in bytes - `total_duration_seconds`: Total duration of the audio in seconds - `sample_rate`: Audio sample rate in Hz - `channels`: Number of audio channels - `audio_format`: Audio format code - `bpm`: Detected beats per minute (optional, only present when detected) - `speakers`: Labels of the speakers heard in the chunk, such as `["Speaker 1", "Speaker 3"]` (optional, see [Speakers](#speakers)) - `speaker_count`: Number of speakers in the whole file (optional) - `speaker_turns`: The chunk's transcription as `{"speaker", "text", "start_time_seconds", "end_time_seconds"}` turns, timed in seconds from the start of the file (optional) - `start_time_seconds`: Start time of the chunk in seconds - `end_time_seconds`: End time of the chunk in seconds - `duration_seconds`: Duration of the chunk in seconds - `chunk_size_bytes`: Size of the chunk in bytes ### Example ```json { "type": "audio", "file_type": "audio/mpeg", "file_size": 5242880, "total_duration_seconds": 180.5, "sample_rate": 44100, "channels": 2, "audio_format": 1, "speakers": ["Speaker 1", "Speaker 2"], "speaker_count": 4, "speaker_turns": [ { "speaker": "Speaker 1", "text": "Welcome back to the show.", "start_time_seconds": 0.12, "end_time_seconds": 1.84 }, { "speaker": "Speaker 2", "text": "Thanks for having me.", "start_time_seconds": 2.3, "end_time_seconds": 3.51 } ], "start_time_seconds": 0, "end_time_seconds": 38.93, "duration_seconds": 38.93, "chunk_size_bytes": 650736 } ``` ### Speakers With the `high_quality` parsing strategy, an audio file or a video with an audio track is transcribed as a whole, and every word is attributed to a speaker. Speakers are numbered in the order they first speak, and a label means the same person in every chunk of the file, so you can filter on `generated_metadata.speakers` to find the chunks where one speaker talks. Each turn in `speaker_turns` runs from the start of its first word to the end of its last, so you can cite the moment a passage was said. Files longer than 4 hours or of 2 GB or more are transcribed one chunk at a time without speaker fields. ## Video - Media Information Video chunks include specialized media metadata: - `type`: `"video"` - `file_type`: String (MIME type, e.g., `video/mp4`, `video/webm`) - `file_size`: File size in bytes - `total_duration_seconds`: Total duration of the video in seconds - `fps`: Frames per second - `width`: Video width in pixels - `height`: Video height in pixels - `frame_count`: Total number of frames - `has_audio_stream`: Whether the video contains an audio track - `bpm`: Detected beats per minute (optional, only present when detected) - `speakers`: Labels of the speakers heard in the chunk, such as `["Speaker 1", "Speaker 3"]` (optional, see [Speakers](#speakers)) - `speaker_count`: Number of speakers in the whole file (optional) - `speaker_turns`: The chunk's transcription as `{"speaker", "text", "start_time_seconds", "end_time_seconds"}` turns, timed in seconds from the start of the file (optional) - `start_time_seconds`: Start time of the chunk in seconds - `end_time_seconds`: End time of the chunk in seconds - `duration_seconds`: Duration of the chunk in seconds - `chunk_size_bytes`: Size of the chunk in bytes ### Example ```json { "type": "video", "file_type": "video/mp4", "file_size": 15728640, "total_duration_seconds": 120.0, "fps": 30.0, "width": 1920, "height": 1080, "frame_count": 3600, "has_audio_stream": true, "start_time_seconds": 0.0, "end_time_seconds": 120.0, "duration_seconds": 120.0, "chunk_size_bytes": 2097152 } ``` ## Type Inference and Flexibility - If `type` is not present in `generated_metadata`, it is inferred from `file_type` when possible. - If neither `type` nor a recognized `file_type` is present, the `type` defaults to `"text"`. - The system may include additional fields as needed for future enhancements; clients should read the documented fields and ignore unknown ones. # Create Files URL: https://www.mixedbread.com/docs/stores/store-files Learn how to ingest files into your Store with basic upload, metadata configuration, and file processing for semantic search. Upload files to your Stores to make them instantly searchable. Stores support a variety of file formats and languages—you just upload your data and we take care of the optimal processing. Let's start with the upload method. ## Basic File Ingestion Upload a single file to your Store: **Upload File to Store** Python: ```python from pathlib import Path from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") file = mxbai.stores.files.upload( store_identifier="my-knowledge-base", file=Path("./document.pdf"), ) print(file) ``` Python (async): ```python from pathlib import Path from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") file = await mxbai.stores.files.upload( store_identifier="my-knowledge-base", file=Path("./document.pdf"), ) print(file) ``` TypeScript: ```ts import * as fs from "node:fs"; import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const file = await mxbai.stores.files.upload({ storeIdentifier: "my-knowledge-base", file: fs.createReadStream("./document.pdf"), }); console.log(file); ``` cURL: ```bash curl -X POST "https://api.mixedbread.com/v1/stores/my-knowledge-base/files/upload" \ -H 'Authorization: Bearer YOUR_API_KEY' \ -F 'params={};type=application/json' \ -F 'file=@./document.pdf' ``` For complete details on the file object structure including all properties and status values, see [Data Models](https://www.mixedbread.com/docs/stores/data-models#store-file). ## Ingestion Options ### External ID You can optionally assign a unique external ID to the file. This identifier lets you reference the file later and makes it easy to replace or update the same file by using the same external ID. The ID can be any string value, though we recommend using a relative file path to mirror your repository's structure. **Upload File to Store with External ID** Python: ```python from pathlib import Path from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") file = mxbai.stores.files.upload( store_identifier="my-knowledge-base", file=Path("./document.pdf"), external_id="path/to/my-file.pdf" ) print(file) ``` Python (async): ```python from pathlib import Path from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") file = await mxbai.stores.files.upload( store_identifier="my-knowledge-base", file=Path("./document.pdf"), external_id="path/to/my-file.pdf" ) print(file) ``` TypeScript: ```ts import * as fs from "node:fs"; import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const file = await mxbai.stores.files.upload({ storeIdentifier: "my-knowledge-base", file: fs.createReadStream("./document.pdf"), body: { external_id: "path/to/my-file.pdf", }, }); console.log(file); ``` cURL: ```bash curl -X POST "https://api.mixedbread.com/v1/stores/my-knowledge-base/files/upload" \ -H 'Authorization: Bearer YOUR_API_KEY' \ -F 'params={ "external_id": "path/to/my-file.pdf" };type=application/json' \ -F 'file=@./document.pdf' ``` **Overwrite Behavior**: By default, uploading a file with an existing `external_id` will overwrite the previous file. You can control this behavior with the `overwrite` parameter: - `overwrite: true` (default): Replaces the existing file with the same `external_id` - `overwrite: false`: Prevents overwriting and returns an error if the `external_id` already exists This makes it easy to update files in your Store while preventing accidental overwrites when needed. ### File Types Stores understand any data format: - **Documents**: PDFs (including scanned), Word docs, text files, Markdown - **Presentations**: PowerPoint slides with images and text - **Code**: Python, JavaScript, TypeScript, Java, C# - **Images**: Photos, diagrams, charts with OCR and visual understanding - **Specialized**: Pre-structured JSON/JSONL formats Each file type is automatically processed to understand both text and visual content, preserving context and meaning. For the complete list of supported formats and processing details, see [Supported File Types](https://www.mixedbread.com/docs/stores/store-files/file-types). ### Metadata Enhance your files with structured metadata for better organization and filtering: **File Ingestion with Metadata** Python: ```python from pathlib import Path from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") file = mxbai.stores.files.upload( store_identifier="my-knowledge-base", file=Path("./document.pdf"), metadata={ "category": "documentation", "department": "product", "difficulty": "beginner", "last_updated": "2024-01-15", "tags": ["user-guide", "onboarding"], "version": "2.1", }, ) print(file) ``` Python (async): ```python from pathlib import Path from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") file = await mxbai.stores.files.upload( store_identifier="my-knowledge-base", file=Path("./document.pdf"), metadata={ "category": "documentation", "department": "product", "difficulty": "beginner", "last_updated": "2024-01-15", "tags": ["user-guide", "onboarding"], "version": "2.1", }, ) print(file) ``` TypeScript: ```ts import * as fs from "node:fs"; import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const file = await mxbai.stores.files.upload({ storeIdentifier: "my-knowledge-base", file: fs.createReadStream("./document.pdf"), body: { metadata: { category: "documentation", department: "product", difficulty: "beginner", last_updated: "2024-01-15", tags: ["user-guide", "onboarding"], version: "2.1", }, }, }); console.log(file); ``` cURL: ```bash curl -X POST "https://api.mixedbread.com/v1/stores/my-knowledge-base/files/upload" \ -H 'Authorization: Bearer YOUR_API_KEY' \ -F 'params={ "metadata": { "category": "documentation", "department": "product", "difficulty": "beginner", "last_updated": "2024-01-15", "tags": ["user-guide", "onboarding"], "version": "2.1" } };type=application/json' \ -F 'file=@./document.pdf' ``` Metadata is structured information about your files that enables powerful filtering, organization, and search capabilities. It's inherited by all chunks created from the file, enabling precise filtering during search operations. **Supported Metadata Types:** - **String values**: Categories, names, tags, status values - **Numeric values**: Scores, versions, counts, measurements - **Boolean values**: Flags, permissions, feature toggles - **Date/time values**: Timestamps, deadlines, publishing dates - **Array values**: Multiple values, collections, tags For supported metadata types, see [Supported Metadata Types](https://www.mixedbread.com/docs/stores/store-files/metadata-types). Learn more about [Metadata Filtering](https://www.mixedbread.com/docs/stores/metadata-filtering) to search with metadata filtering. ### Parsing Strategy Control how your files are processed with parsing strategy options (see examples above): **File Ingestion with Parsing Options** Python: ```python from pathlib import Path from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") file = mxbai.stores.files.upload( store_identifier="my-knowledge-base", file=Path("./manual.pdf"), metadata={ "category": "technical-manual", "complexity": "high", }, config={ "parsing_strategy": "high_quality", }, ) print(file) ``` Python (async): ```python from pathlib import Path from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") file = await mxbai.stores.files.upload( store_identifier="my-knowledge-base", file=Path("./manual.pdf"), metadata={ "category": "technical-manual", "complexity": "high", }, config={ "parsing_strategy": "high_quality", }, ) print(file) ``` TypeScript: ```ts import * as fs from "node:fs"; import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const file = await mxbai.stores.files.upload({ storeIdentifier: "my-knowledge-base", file: fs.createReadStream("./manual.pdf"), body: { metadata: { category: "technical-manual", complexity: "high", }, config: { parsing_strategy: "high_quality", }, }, }); console.log(file); ``` cURL: ```bash curl -X POST "https://api.mixedbread.com/v1/stores/my-knowledge-base/files/upload" \ -H 'Authorization: Bearer YOUR_API_KEY' \ -F 'params={ "metadata": { "category": "technical-manual", "complexity": "high" }, "config": { "parsing_strategy": "high_quality" } };type=application/json' \ -F 'file=@./manual.pdf' ``` **Available Parsing Strategies:** - **`fast`** (default): Optimized for speed, good quality for most documents - **`high_quality`**: Enhanced processing for complex layouts, including OCR, transcription, and summaries for text, audio and visual content ## Upload Helpers The SDK provides two convenient helpers for file ingestion: - `upload`: Uploads the file and immediately returns the created Store File. The file's `status` begins as `pending` and progresses to `in_progress` and `completed` in the background. Use this when you want to upload files asynchonisly and as fast as possible - `uploadAndPoll` / `upload_and_poll`: Uploads the file and polls until processing completes. Use this when you want to proceed only after complete processing. For example if the upload is directly followed by a search method. To monitor progress without blocking, retrieve the file by ID and check its `status` using [Retrieve Store File](https://www.mixedbread.com/docs/stores/store-files/manage-store-files#retrieve-store-file). ## Store File Status - **`pending`**: File uploaded and queued for processing - **`in_progress`**: Active processing (extraction, chunking, embedding, indexing) - **`completed`**: Successfully processed and searchable - **`failed`**: Processing error (check `last_error` for details) - **`cancelled`**: Processing stopped manually or automatically You can retrieve the status of any file using [Retrieve Store File](https://www.mixedbread.com/docs/stores/store-files/manage-store-files#retrieve-store-file). # Manage Files URL: https://www.mixedbread.com/docs/stores/store-files/manage-store-files Inspect, retrieve, filter, update, and delete files in your Store, including how to return parsed chunks from a file. Once files are uploaded to your Store, you can inspect and manage them using these core operations. All operations work with either the file ID or the file's external ID (if provided during upload). > **Note** > > **File Identifiers**: You can reference files using either their UUID > (`file_id`) or their external ID. External IDs support slashes, making it easy > to use file paths as identifiers (e.g., `docs/api/authentication.md`). ## Retrieve Store File Get detailed information about a specific file using either its ID or external ID: **Retrieve Store File Metadata** Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") file = mxbai.stores.files.retrieve( store_identifier="my-knowledge-base", file_identifier="f47ac10b-58cc-4372-a567-0e02b2c3d479", ) print(file) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") file = await mxbai.stores.files.retrieve( store_identifier="my-knowledge-base", file_identifier="f47ac10b-58cc-4372-a567-0e02b2c3d479", ) print(file) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const file = await mxbai.stores.files.retrieve("f47ac10b-58cc-4372-a567-0e02b2c3d479", { store_identifier: "my-knowledge-base", }); console.log(file); ``` cURL: ```bash curl https://api.mixedbread.com/v1/stores/my-knowledge-base/files/f47ac10b-58cc-4372-a567-0e02b2c3d479 \ -H 'Authorization: Bearer YOUR_API_KEY' ``` By default, `retrieve` returns the file object and its file-level metadata. The `chunks` field is `null` unless you explicitly request chunks with `return_chunks`. The response includes processing status, metadata, usage statistics, and error details if applicable. For complete details on file object properties, see [Data Models](https://www.mixedbread.com/docs/stores/data-models#store-file). ## Retrieve File Chunks Use `return_chunks` when you want the parsed, searchable representation of a file instead of only the file-level metadata. **Retrieve All Chunks from a File** Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") file = mxbai.stores.files.retrieve( store_identifier="my-knowledge-base", file_identifier="f47ac10b-58cc-4372-a567-0e02b2c3d479", return_chunks=True, ) for chunk in file.chunks or []: print(chunk.chunk_index, chunk.type) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") file = await mxbai.stores.files.retrieve( store_identifier="my-knowledge-base", file_identifier="f47ac10b-58cc-4372-a567-0e02b2c3d479", return_chunks=True, ) for chunk in file.chunks or []: print(chunk.chunk_index, chunk.type) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY" }); const file = await mxbai.stores.files.retrieve("f47ac10b-58cc-4372-a567-0e02b2c3d479", { store_identifier: "my-knowledge-base", return_chunks: true, }); for (const chunk of file.chunks ?? []) { console.log(chunk.chunk_index, chunk.type); } ``` cURL: ```bash curl "https://api.mixedbread.com/v1/stores/my-knowledge-base/files/f47ac10b-58cc-4372-a567-0e02b2c3d479?return_chunks=true" \ -H 'Authorization: Bearer YOUR_API_KEY' ``` Use this when you want to inspect parsed text, OCR output, transcriptions, or chunk-level `generated_metadata`. > **Note** > > **File Metadata vs. Chunk Metadata**: `metadata` is your file-level metadata > and is shared across all chunks from that file. `generated_metadata` is > produced during parsing and can differ for each chunk. For complete details on chunk fields and chunk types, see [Data Models](https://www.mixedbread.com/docs/stores/data-models#store-chunk). ### Retrieve Specific Chunks by Index `return_chunks` also accepts a list of chunk indices. This is useful when you want a small, exact slice of a file instead of every chunk. **Retrieve Specific Chunks by Index** Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") file = mxbai.stores.files.retrieve( store_identifier="my-knowledge-base", file_identifier="f47ac10b-58cc-4372-a567-0e02b2c3d479", return_chunks=[0, 3, 7], ) for chunk in file.chunks or []: print(chunk.chunk_index) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") file = await mxbai.stores.files.retrieve( store_identifier="my-knowledge-base", file_identifier="f47ac10b-58cc-4372-a567-0e02b2c3d479", return_chunks=[0, 3, 7], ) for chunk in file.chunks or []: print(chunk.chunk_index) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY" }); const file = await mxbai.stores.files.retrieve("f47ac10b-58cc-4372-a567-0e02b2c3d479", { store_identifier: "my-knowledge-base", return_chunks: [0, 3, 7], }); for (const chunk of file.chunks ?? []) { console.log(chunk.chunk_index); } ``` cURL: ```bash curl "https://api.mixedbread.com/v1/stores/my-knowledge-base/files/f47ac10b-58cc-4372-a567-0e02b2c3d479?return_chunks=0&return_chunks=3&return_chunks=7" \ -H 'Authorization: Bearer YOUR_API_KEY' ``` Chunk indices are zero-based and correspond to the file's parsed chunk order. ### Retrieve the Exact Chunk Returned by Search Search results include both `file_id` and `chunk_index`, so you can use them to load the exact source chunk that matched a query. **Hydrate a Search Result Back to Its Source Chunk** Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") results = mxbai.stores.search( query="authentication timeout", store_identifiers=["my-knowledge-base"], top_k=1, ) match = results.data[0] file = mxbai.stores.files.retrieve( store_identifier="my-knowledge-base", file_identifier=match.file_id, return_chunks=[match.chunk_index], ) chunk = file.chunks[0] print(chunk) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") results = await mxbai.stores.search( query="authentication timeout", store_identifiers=["my-knowledge-base"], top_k=1, ) match = results.data[0] file = await mxbai.stores.files.retrieve( store_identifier="my-knowledge-base", file_identifier=match.file_id, return_chunks=[match.chunk_index], ) chunk = file.chunks[0] print(chunk) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY" }); const results = await mxbai.stores.search({ query: "authentication timeout", store_identifiers: ["my-knowledge-base"], top_k: 1, }); const match = results.data[0]; if (!match) { throw new Error("No matching chunk found."); } const file = await mxbai.stores.files.retrieve(match.file_id, { store_identifier: "my-knowledge-base", return_chunks: [match.chunk_index], }); const chunk = file.chunks?.[0]; console.log(chunk); ``` This is the easiest way to go from a semantic search hit back to the precise chunk in the original file. ## File Status and Availability To reliably inspect chunks, wait until the file reaches `completed` status. - `pending`: The file was accepted and queued for processing - `in_progress`: Parsing, chunking, embedding, and indexing are still running - `completed`: Chunks are ready to inspect and search - `failed`: Processing failed; inspect `last_error` for details - `cancelled`: Processing stopped before completion If you need a file to be ready before continuing, use `uploadAndPoll` / `upload_and_poll` during ingestion or poll `retrieve` until the status becomes `completed`. ## List Store Files View all files in your Store. The list operation uses cursor-based pagination: **List Store Files** Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") response = mxbai.stores.files.list("my-knowledge-base", limit=20) for file in response.data: print(file) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") response = await mxbai.stores.files.list("my-knowledge-base", limit=20) for file in response.data: print(file) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const response = await mxbai.stores.files.list("my-knowledge-base", { limit: 20, }); for (const file of response.data) { console.log(file); } ``` cURL: ```bash curl -X GET 'https://api.mixedbread.com/v1/stores/my-knowledge-base/files?limit=20' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` > **Note** > > **Pagination Details**: For complete information about cursor-based pagination including parameters, response format, and advanced usage patterns, see the [Pagination Reference](https://www.mixedbread.com/api-reference/pagination). ### Metadata Filtering Filter Store Files based on their metadata. **List Files with Metadata Filter** Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") response = mxbai.stores.files.list( store_identifier="my-knowledge-base", limit=10, metadata_filter={ "key": "category", "value": "documentation", "operator": "eq", }, ) for file in response.data: print(file) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") response = await mxbai.stores.files.list( store_identifier="my-knowledge-base", limit=10, metadata_filter={ "key": "category", "value": "documentation", "operator": "eq", }, ) for file in response.data: print(file) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const response = await mxbai.stores.files.list("my-knowledge-base", { limit: 10, metadata_filter: { key: "category", value: "documentation", operator: "eq", }, }); for (const file of response.data) { console.log( `${file.id}: ${file.filename} - ${JSON.stringify(file.metadata)}` ); } ``` cURL: ```bash curl -X POST https://api.mixedbread.com/v1/stores/my-knowledge-base/files/list \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -d '{ "limit": 10, "metadata_filter": { "key": "category", "value": "documentation", "operator": "eq" } }' ``` > **Note** > > **Complete Filtering Guide**: For detailed information about filter operators, logical operations, data types, and advanced patterns, see [Metadata Filtering](https://www.mixedbread.com/docs/stores/metadata-filtering). ## Paginate and Filter Files List all available files and filter them by status. This operation combines cursor-based pagination with the status filter to retrieve only the subsets of files you care about. For a complete explanation of cursor-based pagination options, see the [Pagination Reference](https://www.mixedbread.com/api-reference/pagination). **Paginate Files with Status Filter** Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") all_files = [] files = mxbai.stores.files.list( store_identifier="my-knowledge-base", limit=100, # change status to get different subsets statuses=["failed"], ) all_files += files.data while files.pagination.has_more: files = mxbai.stores.files.list( store_identifier="my-knowledge-base", limit=100, after=files.pagination.last_cursor, statuses=["failed"], ) all_files += files.data print(len(all_files), "files matched") ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") all_files = [] files = await mxbai.stores.files.list( store_identifier="my-knowledge-base", limit=100, # change status to get different subsets statuses=["failed"], ) all_files += files.data while files.pagination.has_more: files = await mxbai.stores.files.list( store_identifier="my-knowledge-base", limit=100, after=files.pagination.last_cursor, statuses=["failed"], ) all_files += files.data print(len(all_files), "files matched") ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; import type { StoreFile } from "@mixedbread/sdk/resources/stores"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY" }); const files: StoreFile[] = []; let response = await mxbai.stores.files.list("my-knowledge-base", { limit: 100, // change status to get different subsets statuses: ["failed"], }); files.push(...response.data); while (response.pagination.has_more) { response = await mxbai.stores.files.list("my-knowledge-base", { limit: 100, after: response.pagination.last_cursor, statuses: ["failed"], }); files.push(...response.data); } console.log(files); ``` ## Update File Metadata Change the metadata of a file without re-uploading it: **Update Store File Metadata** Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") file = mxbai.stores.files.update( store_identifier="my-knowledge-base", file_identifier="f47ac10b-58cc-4372-a567-0e02b2c3d479", metadata={"category": "documentation"}, ) print(file) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") file = await mxbai.stores.files.update( store_identifier="my-knowledge-base", file_identifier="f47ac10b-58cc-4372-a567-0e02b2c3d479", metadata={"category": "documentation"}, ) print(file) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const file = await mxbai.stores.files.update("f47ac10b-58cc-4372-a567-0e02b2c3d479", { store_identifier: "my-knowledge-base", metadata: { category: "documentation" }, }); console.log(file); ``` cURL: ```bash curl -X PATCH https://api.mixedbread.com/v1/stores/my-knowledge-base/files/f47ac10b-58cc-4372-a567-0e02b2c3d479 \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -d '{ "metadata": {"category": "documentation"} }' ``` > **Note** > > **Updates replace the whole metadata object.** The `metadata` you send > becomes the file's complete metadata; keys you leave out are removed, not > kept. To change one key, retrieve the file, modify its `metadata`, and send > the full object back. The new metadata is applied to the file and to every chunk created from it, so filters on search, grep, and listing endpoints see the updated values. ## Delete Store File Remove files from your Store: **Delete Store File** Python: ```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 (async): ```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: ```ts 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); ``` cURL: ```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' ``` **Important**: Deleting a file permanently removes: - The original file from storage - All generated chunks and embeddings - Associated metadata and search indexes - Processing history and logs If you want to replace a file instead of deleting it first, upload new content with the same `external_id`. By default, uploads with the same `external_id` overwrite the previous version. For details, see [File Ingestion](https://www.mixedbread.com/docs/stores/store-files#external-id). # Supported Metadata Types URL: https://www.mixedbread.com/docs/stores/store-files/metadata-types Learn about supported metadata types and how to structure metadata for optimal search performance, filtering capabilities, and content organization in Mixedbread Stores. Metadata is structured information about your files that enables powerful filtering, organization, and search capabilities. This page covers **what types of metadata you can store** and how to structure them effectively. > **Note** > > **Looking for filtering syntax?** This page covers metadata types and structure. For filtering operations and syntax, see [Metadata Filtering](https://www.mixedbread.com/docs/stores/metadata-filtering). ## Understanding Metadata - **File-Level**: Metadata attached to entire files - **Inheritance**: Chunks inherit metadata from their parent file - **Filtering**: Use metadata to narrow search results ([learn more](https://www.mixedbread.com/docs/stores/metadata-filtering)) - **Content Organization**: Structure content for easier discovery ## Metadata Types ### String Values **String Values** JSON: ```json { "category": "documentation", "author": "john.doe", "department": "engineering", "status": "published" } ``` **Best For**: Categories, names, tags, status values **Filtering**: Equality (`eq`, `not_eq`), lists (`in`, `not_in`), substring (`contains`), prefix (`starts_with`), and `regex` ### Numeric Values **Numeric Values** JSON: ```json { "priority": 8, "version": 2.1, "page_count": 45, "file_size": 1048576 } ``` **Best For**: Scores, versions, counts, measurements **Filtering**: Comparisons (`>`, `<`, `>=`, `<=`) ### Boolean Values **Boolean Values** JSON: ```json { "is_public": true, "requires_auth": false, "is_deprecated": false, "featured": true } ``` **Best For**: Flags, permissions, feature toggles **Filtering**: True/false conditions ### Date/Time Values **Date/Time Values** JSON: ```json { "created_at": "2024-01-15T10:30:00Z", "last_updated": "2024-01-20", "expires_on": "2024-12-31", "published_date": "2024-01-15" } ``` **Best For**: Timestamps, deadlines, publishing dates **Filtering**: Comparisons (`>`, `<`, `>=`, `<=`) **Format**: ISO 8601 recommended ### Array/List Values **Array/List Values** JSON: ```json { "tags": [ "python", "web", "api" ], "authors": [ "alice", "bob" ], "categories": [ "tutorial", "guide" ], "languages": [ "en", "es" ] } ``` **Best For**: Multiple values, collections # Multipart Upload URL: https://www.mixedbread.com/docs/stores/store-files/multipart-upload Automatically upload large files in parallel chunks using the SDK's built-in multipart upload support for upload and uploadAndPoll. Both `upload` and `uploadAndPoll` / `upload_and_poll` automatically use multipart upload for large files. The file is split into chunks and uploaded in parallel, improving reliability and speed. No extra configuration is needed — it just works. ## Default Behavior Files over 100MB automatically use multipart upload. The existing upload calls work without any changes: **Multipart Upload Default Behavior** Python: ```python file = mxbai.stores.files.upload( store_identifier="my-knowledge-base", file=Path("./large-document.pdf"), ) ``` TypeScript: ```ts const file = await mxbai.stores.files.upload({ storeIdentifier: "my-knowledge-base", file: fs.createReadStream("./large-document.pdf"), }); ``` ## Custom Threshold Lower the threshold to trigger multipart upload for smaller files: **Multipart Upload with Custom Threshold** Python: ```python from mixedbread.lib.multipart_upload import MultipartUploadOptions file = mxbai.stores.files.upload( store_identifier="my-knowledge-base", file=Path("./document.pdf"), multipart_upload=MultipartUploadOptions( threshold=50 * 1024 * 1024, # 50MB instead of default 100MB ), ) ``` TypeScript: ```ts const file = await mxbai.stores.files.upload({ storeIdentifier: "my-knowledge-base", file: fs.createReadStream("./document.pdf"), multipartUpload: { threshold: 50 * 1024 * 1024, // 50MB instead of default 100MB }, }); ``` ## Custom Concurrency Control how many parts upload in parallel. The default is 5 concurrent uploads: **Multipart Upload with Custom Concurrency** Python: ```python from mixedbread.lib.multipart_upload import MultipartUploadOptions file = mxbai.stores.files.upload( store_identifier="my-knowledge-base", file=Path("./large-document.pdf"), multipart_upload=MultipartUploadOptions( concurrency=10, ), ) ``` TypeScript: ```ts const file = await mxbai.stores.files.upload({ storeIdentifier: "my-knowledge-base", file: fs.createReadStream("./large-document.pdf"), multipartUpload: { concurrency: 10, }, }); ``` ## Custom Part Size Control the size of each chunk. The default part size is 100MB. Every part except the last must be at least 5MB, and an upload has at most 10,000 parts, so the default covers files up to about 1TB: **Multipart Upload with Custom Part Size** Python: ```python from mixedbread.lib.multipart_upload import MultipartUploadOptions file = mxbai.stores.files.upload( store_identifier="my-knowledge-base", file=Path("./large-document.pdf"), multipart_upload=MultipartUploadOptions( part_size=50 * 1024 * 1024, # 50MB parts ), ) ``` TypeScript: ```ts const file = await mxbai.stores.files.upload({ storeIdentifier: "my-knowledge-base", file: fs.createReadStream("./large-document.pdf"), multipartUpload: { partSize: 50 * 1024 * 1024, // 50MB parts }, }); ``` ## Progress Tracking Get notified after each part finishes uploading. Works with both `upload` and `uploadAndPoll` / `upload_and_poll`: **Progress Tracking with uploadAndPoll** Python: ```python from pathlib import Path from mixedbread import Mixedbread from mixedbread.lib.multipart_upload import MultipartUploadOptions mxbai = Mixedbread(api_key="YOUR_API_KEY") def on_part_upload(event): pct = round((event.uploaded_bytes / event.total_bytes) * 100) print(f"Part {event.part_number}/{event.total_parts} done — {pct}%") file = mxbai.stores.files.upload_and_poll( store_identifier="my-knowledge-base", file=Path("./large-document.pdf"), multipart_upload=MultipartUploadOptions( on_part_upload=on_part_upload, ), ) print(file) ``` Python (async): ```python from pathlib import Path from mixedbread import AsyncMixedbread from mixedbread.lib.multipart_upload import MultipartUploadOptions mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") def on_part_upload(event): pct = round((event.uploaded_bytes / event.total_bytes) * 100) print(f"Part {event.part_number}/{event.total_parts} done — {pct}%") file = await mxbai.stores.files.upload_and_poll( store_identifier="my-knowledge-base", file=Path("./large-document.pdf"), multipart_upload=MultipartUploadOptions( on_part_upload=on_part_upload, ), ) print(file) ``` TypeScript: ```ts import * as fs from "node:fs"; import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const file = await mxbai.stores.files.uploadAndPoll({ storeIdentifier: "my-knowledge-base", file: fs.createReadStream("./large-document.pdf"), multipartUpload: { onPartUpload: ({ partNumber, totalParts, uploadedBytes, totalBytes }) => { const pct = Math.round((uploadedBytes / totalBytes) * 100); console.log(`Part ${partNumber}/${totalParts} done — ${pct}%`); }, }, }); console.log(file); ``` The callback receives a `PartUploadEvent` with the following fields: | Field | Description | | --- | --- | | `partNumber` / `part_number` | 1-based part number that completed | | `totalParts` / `total_parts` | Total number of parts in this upload | | `partSize` / `part_size` | Size of this part in bytes | | `uploadedBytes` / `uploaded_bytes` | Cumulative bytes uploaded so far | | `totalBytes` / `total_bytes` | Total file size in bytes | > **Diagram**: Multipart upload planner: choose a file size, threshold, partSize and concurrency to see how upload and uploadAndPoll split a file. A file larger than threshold (default 100 MB) is uploaded in parts; a smaller one goes up in a single request and onPartUpload is never called. The number of parts is ceil(file size / partSize): with the default partSize of 100 MB, a 1 GB file becomes 11 parts, ten of 100 MB and a last one of 24 MB. Up to concurrency parts (default 5) upload at the same time, and each lane takes the next part as soon as its current one finishes, so the 11 parts run as 5, 5 and 1. After every part, onPartUpload receives a PartUploadEvent with partNumber, totalParts, partSize (bytes in that part), uploadedBytes (cumulative) and totalBytes. Python uses the same options in snake_case: part_size and on_part_upload. ## All Options Together Combine threshold, part size, concurrency, and progress tracking: **All Multipart Upload Options** Python: ```python from pathlib import Path from mixedbread import Mixedbread from mixedbread.lib.multipart_upload import MultipartUploadOptions mxbai = Mixedbread(api_key="YOUR_API_KEY") def on_part_upload(event): pct = round((event.uploaded_bytes / event.total_bytes) * 100) print(f"Part {event.part_number}/{event.total_parts} — {pct}%") file = mxbai.stores.files.upload( store_identifier="my-knowledge-base", file=Path("./large-document.pdf"), multipart_upload=MultipartUploadOptions( threshold=50 * 1024 * 1024, # 50MB threshold part_size=25 * 1024 * 1024, # 25MB parts concurrency=10, on_part_upload=on_part_upload, ), ) print(file) ``` Python (async): ```python from pathlib import Path from mixedbread import AsyncMixedbread from mixedbread.lib.multipart_upload import MultipartUploadOptions mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") def on_part_upload(event): pct = round((event.uploaded_bytes / event.total_bytes) * 100) print(f"Part {event.part_number}/{event.total_parts} — {pct}%") file = await mxbai.stores.files.upload( store_identifier="my-knowledge-base", file=Path("./large-document.pdf"), multipart_upload=MultipartUploadOptions( threshold=50 * 1024 * 1024, # 50MB threshold part_size=25 * 1024 * 1024, # 25MB parts concurrency=10, on_part_upload=on_part_upload, ), ) print(file) ``` TypeScript: ```ts import * as fs from "node:fs"; import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const file = await mxbai.stores.files.upload({ storeIdentifier: "my-knowledge-base", file: fs.createReadStream("./large-document.pdf"), multipartUpload: { threshold: 50 * 1024 * 1024, // 50MB threshold partSize: 25 * 1024 * 1024, // 25MB parts concurrency: 10, onPartUpload: ({ partNumber, totalParts, uploadedBytes, totalBytes }) => { const pct = Math.round((uploadedBytes / totalBytes) * 100); console.log(`Part ${partNumber}/${totalParts} — ${pct}%`); }, }, }); console.log(file); ``` ## Options Reference | Option | Default | Description | | --- | --- | --- | | `threshold` | `100MB` | Minimum file size to trigger multipart upload | | `partSize` / `part_size` | `100MB` | Size of each upload chunk, at least 5MB | | `concurrency` | `5` | Number of parts uploaded in parallel | | `onPartUpload` / `on_part_upload` | — | Callback invoked after each part completes | # Mixedbread JSON Format URL: https://www.mixedbread.com/docs/stores/store-files/mxjson Pre-chunked content format for direct ingestion into Mixedbread Stores without parsing overhead. > **Note** > > **This format is for specialized use cases** where you need complete control over chunking. For most workflows, use the standard [file upload](https://www.mixedbread.com/docs/stores/store-files) — it handles chunking, metadata generation, and indexing automatically. The Mixedbread JSON format (`.mxjson` / `.mxjsonl`) allows you to ingest pre-chunked content directly into Stores. Use this format when you have already processed your content into chunks, want to preserve specific chunk boundaries, or need to include pre-computed metadata. ## Schema Checker Validate your mxjson files before uploading. Drop a `.mxjson` or `.mxjsonl` file below to check it against the current schema. You can also [download the JSON Schema](https://api.mixedbread.com/v1/schemas/mxjson). ## File Formats | Format | Extension | MIME Type | Structure | |--------|-----------|-----------|-----------| | **JSON** | `.mxjson` | `application/vnd-mxbai.chunks-json` | Array of chunk objects | | **JSON Lines** | `.mxjsonl` | `application/vnd-mxbai.chunks-jsonl` | One chunk object per line | ## Chunk Structure Each chunk in an mxjson file follows the same structure as [Store Chunks](https://www.mixedbread.com/docs/stores/data-models#store-chunk). The `type` field determines which properties are required: - `text` - Text content - `image_url` - Image reference - `audio_url` - Audio reference - `video_url` - Video reference Each chunk contains exactly one modality. To represent a document with text and images, use separate chunks for each. ### Input Properties When creating chunks for mxjson files, these properties control ingestion: | Property | Type | Required | Description | |----------|------|----------|-------------| | `type` | string | Yes | Chunk type: `text`, `image_url`, `audio_url`, `video_url` | | `mime_type` | string | No | Content MIME type (defaults per chunk type) | | `chunk_index` | integer | No | Position in file. Auto-generated sequentially if omitted | | `generated_metadata` | object | No | Typed metadata structure — see [Generated Metadata](https://www.mixedbread.com/docs/stores/store-files/generated-metadata) | ### Text Chunks | Property | Type | Required | |----------|------|----------| | `text` | string | Yes (1-65536 characters) | | `offset` | integer | No (default: 0) | ```json tab="Example" { "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 } } ``` ```json tab="JSON Schema" { "type": "object", "required": ["text"], "properties": { "type": { "const": "text", "default": "text" }, "text": { "type": "string", "minLength": 1, "maxLength": 65536 }, "mime_type": { "type": "string", "default": "text/plain" }, "offset": { "type": "integer", "default": 0 }, "chunk_index": { "type": ["integer", "null"], "default": null }, "generated_metadata": { "type": ["object", "null"], "default": null, "properties": { "type": { "const": "text" }, "file_type": { "const": "text/plain" }, "language": { "type": ["string", "null"] }, "word_count": { "type": ["integer", "null"] }, "file_size": { "type": ["integer", "null"] } }, "required": ["type"], "additionalProperties": true } } } ``` ### Image Chunks | Property | Type | Required | |----------|------|----------| | `image_url.url` | string | Yes (HTTP URL or data URI) | ```json tab="Example" { "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 tab="JSON Schema" { "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 } } } ``` ### Audio Chunks | Property | Type | Required | |----------|------|----------| | `audio_url.url` | string | Yes (HTTP URL or data URI) | | `sampling_rate` | integer | Yes | ```json tab="Example" { "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 tab="JSON Schema" { "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 } } } ``` ### Video Chunks | Property | Type | Required | |----------|------|----------| | `video_url.url` | string | Yes (HTTP URL or data URI) | ```json tab="Example" { "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 tab="JSON Schema" { "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 } } } ``` ## Chunk Metadata Each chunk can optionally include `generated_metadata` — a typed structure that follows a fixed format discriminated by a `type` field. When files are processed by the system, this metadata is automatically generated. When using mxjson, you can provide it yourself to match the same structure. Only the `type` field is required within the metadata object; all other fields are optional. You can also add custom fields beyond the typed ones — any additional key-value pairs are preserved alongside the standard fields. See [Generated Metadata](https://www.mixedbread.com/docs/stores/store-files/generated-metadata) for the full reference of all metadata types and their fields. **Example** ```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 } } ``` **JSON Schema** The `generated_metadata` type is determined by the `type` discriminator field. Only `type` is required; all other fields are optional: | Type | Optional Fields | |------|--------| | `text` | `file_type`, `language`, `word_count`, `file_size` | | `markdown` | `file_type`, `language`, `word_count`, `file_size`, `chunk_headings`, `heading_context` | | `pdf` | `file_type`, `total_pages`, `total_size` | | `code` | `file_type`, `language`, `word_count`, `file_size` | | `audio` | `file_type`, `file_size`, `total_duration_seconds`, `sample_rate`, `channels`, `audio_format` | | `video` | `file_type`, `file_size`, `total_duration_seconds`, `fps`, `width`, `height`, `frame_count`, `has_audio_stream` | | `image` | `file_type`, `file_size`, `width`, `height` | File-level metadata (set during upload) applies to all chunks and participates in [contextualization](https://www.mixedbread.com/docs/stores/stores#store-configuration) if enabled on the Store. ## Complete Example ### JSON Format (.mxjson) ```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 } } ] ``` ### JSON Lines Format (.mxjsonl) ```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}} ``` ## Schema Endpoint Retrieve the JSON Schema programmatically: ```bash curl https://api.mixedbread.com/v1/schemas/mxjson ``` ## Use Cases **Custom chunking**: When your domain requires specific chunk boundaries (paragraphs, sections, recipe steps). **Pre-processed pipelines**: When existing ETL pipelines produce chunked content. **Multimodal collections**: When combining text, images, audio, and video from different sources. **Metadata preservation**: When chunks carry structured metadata from source systems. **Migration**: When importing pre-chunked data from other vector databases. ## Validation Errors | Error | Cause | |-------|-------| | `type` is required | Missing `type` field | | `text` must be 1-65536 characters | Text empty or exceeds limit | | Invalid URL format | Malformed URL or data URI | | Unknown chunk type | Type not one of: `text`, `image_url`, `audio_url`, `video_url` | # Create Stores URL: https://www.mixedbread.com/docs/stores/stores Learn how to create Stores with configuration options including unique names, expiration policies, and public access settings. Stores are AI-powered search indexes that organize your files for semantic search. Choose the right configuration for your use case, from temporary development environments to public knowledge bases. ## Basic Creation Create a new Store with default settings: **Create Store** Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") store = mxbai.stores.create(name="my-knowledge-base") print(store) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") store = await mxbai.stores.create(name="my-knowledge-base") print(store) ``` TypeScript: ```ts 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); ``` cURL: ```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" }' ``` When you create a Store, you get a Store object with a unique ID (UUID). You can use either the ID or the name you provide as Store identifiers in all operations. For complete details on the Store object structure, see [Data Models](https://www.mixedbread.com/docs/stores/data-models#store). ## Configuration Options ### Name Names and IDs are interchangeable identifiers for all operations. **Create Store with Name** Python: ```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 (async): ```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: ```ts 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); ``` cURL: ```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" }' ``` **Naming Rules:** - Can only contain lowercase letters, numbers, periods (`.`), and hyphens (`-`) - Must be unique within your organization - Can be updated at any time ### Expiration Policies Set automatic cleanup policies to manage Store lifecycle based on activity: **Create Store with Expiration** Python: ```python from mixedbread import Mixedbread from mixedbread.types import ExpiresAfterParam mxbai = Mixedbread(api_key="YOUR_API_KEY") store = mxbai.stores.create( name="development-tests", expires_after=ExpiresAfterParam(anchor="last_active_at", days=7), ) print(store) ``` Python (async): ```python from mixedbread import AsyncMixedbread from mixedbread.types import ExpiresAfterParam mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") store = await mxbai.stores.create( name="development-tests", expires_after=ExpiresAfterParam(anchor="last_active_at", days=7), ) print(store) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const store = await mxbai.stores.create({ name: "development-tests", expires_after: { anchor: "last_active_at", days: 7, }, }); console.log(store); ``` cURL: ```bash curl -X POST https://api.mixedbread.com/v1/stores \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -d '{ "name": "development-tests", "expires_after": { "anchor": "last_active_at", "days": 7 } }' ``` The `last_active_at` anchor resets the expiration timer whenever you add files, delete files, or perform searches. Stores never expire unless explicitly configured. ### Public Access Control read access to your Store: **Create Store with Public Access** Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") store = mxbai.stores.create( name="public-documentation", description="Public API documentation and tutorials", is_public=True, ) print(store) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") store = await mxbai.stores.create( name="public-documentation", description="Public API documentation and tutorials", is_public=True, ) print(store) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const store = await mxbai.stores.create({ name: "public-documentation", description: "Public API documentation and tutorials", is_public: true, }); console.log(store); ``` cURL: ```bash curl -X POST https://api.mixedbread.com/v1/stores \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -d '{ "name": "public-documentation", "description": "Public API documentation and tutorials", "is_public": true }' ``` **Private** (default): Only your organization can access. You pay all costs. **Public**: Anyone with an API key can search. They pay for their own searches. ### File contextualization Improve retrieval for long documents by adding global context to individual chunks. When enabled, Mixedbread automatically generates chunk-specific explanatory context from the original file and prepends it to each chunk before embedding. **Create Store with File Contextualization** Python: ```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 (async): ```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: ```ts 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); ``` cURL: ```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 } } }' ``` ### Metadata contextualization Improve retrieval using metadata by including selected file metadata in each chunk before embedding. - `false` (default): Do not include file metadata - `true`: Include all file metadata (flattened) - An array of field names: Include only the selected fields (supports nested fields using dot notation) **Create Store with Metadata Contextualization** Python: ```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 (async): ```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: ```ts 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); ``` cURL: ```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"] } } }' ``` ## Configuration Guide | Use Case | Name Pattern | Expiration | Public | Purpose | |----------|-------------|------------|--------|---------| | Development | `dev-{feature}` | 7 days | No | Temporary testing | | Production Docs | `docs-v{version}` | Never | Yes | Public documentation | | Customer Data | `customer-{id}` | Never | No | Private customer content | | Demo/POC | `demo-{client}` | 30 days | No | Time-limited demos | ## Combined Configuration Use multiple configuration options together for specific use cases: **Development Environment with Auto-cleanup** Python: ```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 (async): ```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: ```ts 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); ``` cURL: ```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 } }' ``` --- **Public Knowledge Base** Python: ```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 (async): ```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: ```ts 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); ``` cURL: ```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 }' ``` # Manage Stores URL: https://www.mixedbread.com/docs/stores/stores/manage-stores Learn how to update, retrieve, list, copy, and delete Stores using the management API operations. Once you've created Stores, you can manage them using these core operations. All operations work with either the Store ID or the unique name you assigned. ## Retrieve Store Get details about a specific Store: **Retrieve Store** Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") store = mxbai.stores.retrieve(store_identifier="my-knowledge-base") print(store) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") store = await mxbai.stores.retrieve( store_identifier="my-knowledge-base" ) print(store) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const store = await mxbai.stores.retrieve("my-knowledge-base"); console.log(store); ``` cURL: ```bash curl https://api.mixedbread.com/v1/stores/my-knowledge-base \ -H 'Authorization: Bearer YOUR_API_KEY' ``` This returns a complete Store object with all properties including file counts, status, and usage statistics. For details on all returned fields, see [Data Models](https://www.mixedbread.com/docs/stores/data-models#store). ## Update Store Modify an existing Store's configuration: **Update Store** Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") store = mxbai.stores.update( store_identifier="my-knowledge-base", name="updated-knowledge-base", description="Updated product documentation and FAQs", metadata={"version": "2.0"}, ) print(store) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") store = await mxbai.stores.update( store_identifier="my-knowledge-base", name="updated-knowledge-base", description="Updated product documentation and FAQs", metadata={"version": "2.0"}, ) print(store) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const store = await mxbai.stores.update("my-knowledge-base", { name: "updated-knowledge-base", description: "Updated product documentation and FAQs", metadata: { version: "2.0" }, }); console.log(store); ``` cURL: ```bash curl -X PUT https://api.mixedbread.com/v1/stores/my-knowledge-base \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -d '{ "name": "updated-knowledge-base", "description": "Updated product documentation and FAQs", "metadata": {"version": "2.0"} }' ``` **Updatable Properties:** - **name**: Change the unique identifier (lowercase letters, numbers, periods, and hyphens only) - **description**: Update the description - **is_public**: Change visibility (public/private) - **expires_after**: Modify or remove expiration policy ## List Stores Get all Stores in your organization. The list operation uses cursor-based pagination: **List Stores** Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") response = mxbai.stores.list(limit=20) for store in response.data: print(store) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") response = await mxbai.stores.list(limit=20) for store in response.data: print(store) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const response = await mxbai.stores.list({ limit: 20, }); for (const store of response.data) { console.log(store); } ``` cURL: ```bash curl 'https://api.mixedbread.com/v1/stores?limit=20' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` > **Note** > > **Pagination Details**: For complete information about cursor-based pagination including parameters, response format, and advanced usage patterns, see the [Pagination Reference](https://www.mixedbread.com/api-reference/pagination). ## Copy Store Duplicate a Store into a new one, for example to snapshot it before a risky change or to give a second environment the same content. The copy keeps every file, its metadata, and its indexed chunks, so nothing is parsed or embedded again and the copy is much faster than re-uploading. **Copy Store** Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") copy = mxbai.stores.copy_and_poll( store_identifier="my-knowledge-base", name="my-store-copy", ) print(copy.status) # "completed" or "failed" ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") copy = await mxbai.stores.copy_and_poll( store_identifier="my-knowledge-base", name="my-store-copy", ) print(copy.status) # "completed" or "failed" ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const copy = await mxbai.stores.copyAndPoll("my-knowledge-base", { name: "my-store-copy", }); console.log(copy.status); // "completed" or "failed" ``` cURL: ```bash # Start the copy, then poll the new store until its status leaves "in_progress" curl -X POST https://api.mixedbread.com/v1/stores/my-knowledge-base/copy \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{"name": "my-store-copy"}' curl https://api.mixedbread.com/v1/stores/my-store-copy \ -H 'Authorization: Bearer YOUR_API_KEY' ``` The copy runs in the background. The API returns the new Store immediately with `status: "in_progress"`, and the `copy_and_poll` / `copyAndPoll` helpers shown above wait until it settles. If you call `copy` directly, poll the new Store until its `status` leaves `in_progress`; the `poll` helper does exactly that. While the copy runs: - Both Stores carry a `copy_state` object: `role` (`source` or `target`), `status`, `peer_store_id`, and `started_at`. - Neither Store accepts file changes (uploads, updates, deletes, or re-ingestion). Search keeps working on the source. - The new Store's `file_counts` fill in as files arrive. When it finishes, `copy_state` is cleared on both Stores and the copy's `status` becomes `completed`. If the copy fails, the copy's `status` is `failed` and its `copy_state.error` explains why; the failed copy can only be deleted, and the source is writable again. > **Note** > > A Store can only be copied when none of its files are still being processed, and the copy must use a name that is not taken. Search rules and data-source connections belong to the source and are not copied. The copy counts toward your plan's store limit. ## Delete Store Permanently remove a Store and all its contents: **Delete Store** Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") response = mxbai.stores.delete(store_identifier="my-knowledge-base") print(response) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") response = await mxbai.stores.delete(store_identifier="my-knowledge-base") print(response) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const response = await mxbai.stores.delete("my-knowledge-base"); console.log(response); ``` cURL: ```bash curl -X DELETE https://api.mixedbread.com/v1/stores/my-knowledge-base \ -H 'Authorization: Bearer YOUR_API_KEY' ``` **Important**: Deletion is permanent and cannot be undone. All files, embeddings, and metadata are permanently removed. # Public Stores URL: https://www.mixedbread.com/docs/stores/stores/public-stores Share stores publicly, access stores from other organizations, and understand how public store search billing works. Public stores are search indexes that can be searched by any Mixedbread user. They include stores maintained by Mixedbread as well as stores shared publicly by other organizations. When a store is public, users outside the owning organization can search it without being added to that organization. For cross-organization access, callers use the store's public name in `store_identifiers`. ## Public Names Every public store has a public name in the following format: ```txt {owner_org_slug}/{store_name} ``` For example, if the organization slug is `acme` and the store name is `music`, the public name is: ```txt acme/music ``` Use that public name when searching a public store from another organization: **Search Public Store** Python: ```python results = mxbai.stores.search( query="best ambient albums from the 1990s", store_identifiers=["acme/music"], ) ``` TypeScript: ```ts const results = await mxbai.stores.search({ query: "best ambient albums from the 1990s", store_identifiers: ["acme/music"], }); ``` You can combine public stores with your own stores in a single search: **Combined Search** Python: ```python results = mxbai.stores.search( query="music licensing best practices", store_identifiers=[ "acme/music", "industry-research", "partner-notes" ], top_k=15 ) ``` TypeScript: ```ts const results = await mxbai.stores.search({ query: "music licensing best practices", store_identifiers: [ "acme/music", "industry-research", "partner-notes", ], top_k: 15, }); ``` > **Note** > > Members of other organizations should use the public name, such as `acme/music`, when searching your public store. ## Billing and API Keys Billing for public store searches is tied to the API key that makes the request. If a user from another organization searches `acme/music` using their own API key, the search is billed to their account, not to `acme`. Making a store public does not cause the store owner to pay for searches initiated by external users. > **Note** > > **Example:** If a user at another organization calls `stores.search(store_identifiers=["acme/music"], query="best ambient albums from the 1990s")` with their API key, that user is charged for the search. When sharing a public store with customers, partners, or other teams, provide: - The public name, for example `acme/music` - A sample search request using `store_identifiers` - Clear guidance that searches are billed to the caller's API key ## Mixedbread-Maintained Public Stores Mixedbread maintains public stores that provide access to common data sources. These stores are identified by the `mixedbread/` prefix. ### mixedbread/web A web search store that provides access to the latest information from across the internet. Use it to augment your AI applications with up-to-date web knowledge. > **Note** > > **Billing:** `mixedbread/web` is a special store. Each search query is billed as a **search with rerank query**. See [pricing](https://www.mixedbread.com/pricing) for details. **Web Search** Python: ```python results = mxbai.stores.search( query="latest developments in large language models", store_identifiers=["mixedbread/web"], top_k=10 ) ``` TypeScript: ```ts const results = await mxbai.stores.search({ query: "latest developments in large language models", store_identifiers: ["mixedbread/web"], top_k: 10, }); ``` **Use cases:** - Real-time information retrieval - Fact-checking and verification - Research augmentation - Grounding AI responses with current web data # Introduction URL: https://www.mixedbread.com/mcp The Mixedbread MCP Server connects AI assistants to the Mixedbread Search API. The Mixedbread MCP Server is the missing link between your AI assistants and your knowledge Stores. Todays AI agents are powerful, but their built-in search capabilities are weak. Web search and local grep often waste context, take forever, surface irrelevant results and struggle with complex search queries. The MCP changes that. By connecting your AI directly to our Search API, it improves context usage, retrieval accuracy and reduces latency. ## What You Can Do With the MCP you empower your favorite LLM to: - Search documents - Find relevant information using natural language queries - Manage knowledge bases - Create, list, and delete Stores for different projects - Handle complex queries - Combine multiple search operations for deeper research ## Get Started - [Integration Guides](https://www.mixedbread.com/mcp/integrations/claude-desktop) - Platform-specific setup for Claude Desktop, Cursor, and more - [Tools Reference](https://www.mixedbread.com/mcp/tools) - Complete documentation of available commands # Claude Code URL: https://www.mixedbread.com/mcp/integrations/claude-code Set up the Mixedbread MCP server with Claude Code CLI. Learn how to set up the Mixedbread MCP server with Claude Code. ## Prerequisites Before we configure Claude Code, make sure you have the following: - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed - [Node.js 22+](https://nodejs.org) installed - A [Mixedbread API key](https://platform.mixedbread.com/platform?next=api-keys) from our platform ## Configuration You can configure the Mixedbread MCP server in Claude Code either by importing from Claude Desktop or running the `claude mcp add` command. ### Method 1 — Import from Claude Desktop 1. Import your Claude Desktop MCP configuration into Claude Code: ```bash claude mcp add-from-claude-desktop ``` ### Method 2 — CLI command To configure the Mixedbread MCP server globally: 1. Add the Mixedbread server: ```bash claude mcp add mixedbread --transport stdio --scope user -- npx -y mcp-remote@latest https://www.mcp.mixedbread.com/api/mcp --header "Authorization: Bearer YOUR_MIXEDBREAD_API_KEY" ``` 2. Notes: - **--transport stdio** connects locally via stdio to mcp-remote, which tunnels to the remote Mixedbread MCP server. - **--scope user** sets the configuration scope to your user profile. - **--** separates Claude's flags from the mcp-remote command and arguments. 3. Replace `YOUR_MIXEDBREAD_API_KEY` with your actual key from the [Mixedbread platform](https://platform.mixedbread.com/platform?next=api-keys). ## Verification Now let's confirm the integration is working. 1. List all configured servers: ```bash claude mcp list ``` 2. Use the `/mcp` command to view available tools and server status. 3. Test the connection with a simple command: ```bash Create a new store called "my-knowledge-base" ``` Now you can manage your Stores and perform Search directly from Claude Code. ## References - [Claude Code docs: Model Context Protocol](https://docs.claude.com/en/docs/claude-code/mcp) # Claude Desktop URL: https://www.mixedbread.com/mcp/integrations/claude-desktop Set up the Mixedbread MCP server with Claude Desktop App. Learn how to set up the Mixedbread MCP server with Claude Desktop. ## Prerequisites Before we configure Claude Desktop, make sure you have the following: - [Claude Desktop](https://claude.ai/download) installed - A [Mixedbread account](https://platform.mixedbread.com) ## Configuration You can connect Claude Desktop to the Mixedbread MCP server using either the built-in custom connector or a manual configuration file. ### Method 1 — Custom Connector (Recommended) Claude Desktop supports adding remote MCP servers directly from the UI. This is the simplest way to connect. 1. Open Claude Desktop → **Settings** → **Connectors**. 2. Click **Add custom connector**. 3. Enter the Mixedbread MCP server URL: ``` https://www.mcp.mixedbread.com/api/mcp ``` 4. Click **Add**. 5. You will be redirected to sign in to your Mixedbread account and authorize Claude Desktop. 6. Review the requested permissions and click **Authorize**. That's it — no API key or config file needed. > **Note** > > Custom connectors are available on Claude Pro, Max, Team, and Enterprise plans. ### Method 2 — Configuration File If you prefer manual setup or need more control, you can configure the server via the `claude_desktop_config.json` file. **Additional prerequisites:** - [Node.js 22+](https://nodejs.org) installed - A [Mixedbread API key](https://platform.mixedbread.com/platform?next=api-keys) from our platform **Steps:** 1. Locate the configuration file: - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` - Windows: `%APPDATA%\Claude\claude_desktop_config.json` - Linux: `~/.config/Claude/claude_desktop_config.json` 2. Open and edit configuration: - Open Claude Desktop → Settings - Navigate to Developer in the sidebar - Click Edit Config 3. Add a Mixedbread server entry Add the following to your `claude_desktop_config.json`: ```json { "mcpServers": { "mixedbread": { "command": "npx", "args": [ "-y", "mcp-remote@latest", "https://www.mcp.mixedbread.com/api/mcp", "--header", "Authorization:${MXBAI_AUTH_HEADER}" ], "env": { "MXBAI_AUTH_HEADER": "Bearer YOUR_MIXEDBREAD_API_KEY" } } } } ``` - **command** runs mcp-remote via npx. - **args** specify the Mixedbread MCP endpoint and authentication header. - **env** sets an environment variable with your API key. Replace `YOUR_MIXEDBREAD_API_KEY` with your actual key from the [Mixedbread platform](https://platform.mixedbread.com/platform?next=api-keys). 4. Save and restart Claude Desktop: - Save the file and fully restart Claude Desktop for the changes to take effect. ## Verification Now let's confirm the integration is working. 1. Open a new conversation in Claude Desktop. 2. Click Search & Tools in the input field and verify that Mixedbread is connected. 3. Test the connection with a simple command: ```bash Create a new store called "my-knowledge-base" ``` Now you can manage your Stores and perform Search directly from Claude Desktop. ## References - [Claude Help Center: Custom connectors](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) - [MCP docs: Connect remote servers](https://modelcontextprotocol.io/docs/develop/connect-remote-servers) # Codex CLI URL: https://www.mixedbread.com/mcp/integrations/codex-cli Set up the Mixedbread MCP server with the Codex CLI. Learn how to set up the Mixedbread MCP server with the Codex CLI. ## Prerequisites Before we configure Codex, make sure you have the following: - [Codex CLI](https://developers.openai.com/codex/cli/) installed - [Node.js 22+](https://nodejs.org) installed - A [Mixedbread API key](https://platform.mixedbread.com/platform?next=api-keys) from our platform ## Configuration Codex configures MCP servers via a configuration file named `config.toml`. 1. Locate the configuration file Global scope: `~/.codex/config.toml` If this file doesn't exist yet, you can create it manually. 2. Add a Mixedbread server entry Add the following to your `config.toml`: ```toml [mcp_servers.mixedbread] command = "npx" args = [ "-y", "mcp-remote@latest", "https://www.mcp.mixedbread.com/api/mcp", "--header", "Authorization:${MXBAI_AUTH_HEADER}" ] [mcp_servers.mixedbread.env] MXBAI_AUTH_HEADER = "Bearer YOUR_MIXEDBREAD_API_KEY" ``` - **command** tells Codex to run mcp-remote via npx. - **args** specify the remote MCP endpoint and the header used for authentication. - **env** sets an environment variable that contains your API key. Replace `YOUR_MIXEDBREAD_API_KEY` with your actual API key from the [Mixedbread platform](https://platform.mixedbread.com/platform?next=api-keys). ## Verification Now let's confirm the integration is working. 1. Open the Codex CLI and start a chat session. 2. Use the `/mcp` command to list configured MCP servers and verify that `Mixedbread` appears in the output. 3. Test the connection with a simple command: ```bash Create a new store called "my-knowledge-base" ``` Now you can manage your Stores and perform Search directly from the Codex CLI. ## References - [Codex docs: Model Context Protocol](https://developers.openai.com/codex/config-advanced#mcp-servers) # Cursor URL: https://www.mixedbread.com/mcp/integrations/cursor Set up the Mixedbread MCP server with Cursor IDE. Learn how to set up the Mixedbread MCP server with Cursor IDE. ## Prerequisites Before we configure Cursor, make sure you have the following: - [Cursor IDE](https://cursor.sh) installed - [Node.js 22+](https://nodejs.org) installed - A [Mixedbread API key](https://platform.mixedbread.com/platform?next=api-keys) from our platform ## Configuration Cursor supports MCP servers via a configuration file named `mcp.json`. ### Method 1 — Edit via the terminal 1. Locate or create the configuration file Cursor looks for `mcp.json` in the following paths: - **macOS/Linux:** `~/.cursor/mcp.json` - **Windows:** `%USERPROFILE%\.cursor\mcp.json` If the directory or file doesn't exist, create it manually: **macOS/Linux:** ```bash mkdir -p ~/.cursor touch ~/.cursor/mcp.json ``` **Windows:** ```powershell New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.cursor" New-Item -ItemType File -Force -Path "$env:USERPROFILE\.cursor\mcp.json" ``` 2. Add a Mixedbread server entry Add the following to your `mcp.json`: ```json { "mcpServers": { "mixedbread": { "command": "npx", "args": [ "-y", "mcp-remote@latest", "https://www.mcp.mixedbread.com/api/mcp", "--header", "Authorization:${MXBAI_AUTH_HEADER}" ], "env": { "MXBAI_AUTH_HEADER": "Bearer YOUR_MIXEDBREAD_API_KEY" } } } } ``` - **command** runs mcp-remote via npx. - **args** specify the Mixedbread MCP endpoint and authentication header. - **env** sets an environment variable with your API key. Replace `YOUR_MIXEDBREAD_API_KEY` with your actual key from the [Mixedbread platform](https://platform.mixedbread.com/platform?next=api-keys). 3. Save and restart Cursor to apply the changes. ### Method 2 — Add via the UI 1. Open Settings → Cursor Settings → MCP → New MCP Server. 2. Paste the Mixedbread configuration from Method 1. 3. Save. Cursor will automatically reload the MCP servers. ## Verification Now let's confirm the integration is working. 1. Open Settings → Cursor Settings → MCP and check that `Mixedbread` is listed. 2. Ensure Cursor is in Agent Mode so MCP tools can be used. 3. Test the connection with a simple command: ```bash Create a new store called "my-knowledge-base" ``` Now you can manage your Stores and perform Search directly from Cursor. ## References - [Cursor docs: Model Context Protocol](https://cursor.com/docs/context/mcp#model-context-protocol-mcp) # Gemini CLI URL: https://www.mixedbread.com/mcp/integrations/gemini-cli Set up the Mixedbread MCP server with the Gemini CLI. Learn how to set up the Mixedbread MCP server with the Gemini CLI. ## Prerequisites Before we configure Gemini CLI, make sure you have the following: - [Gemini CLI](https://google-gemini.github.io/gemini-cli/) installed - [Node.js 22+](https://nodejs.org) installed - A [Mixedbread API key](https://platform.mixedbread.com/platform?next=api-keys) from our platform ## Configuration Gemini CLI configures MCP servers via a configuration file named `settings.json`. 1. Locate the configuration file Global scope: `~/.gemini/settings.json` If this file doesn't exist yet, you can create it manually. 2. Add a Mixedbread server entry Add the following to your `settings.json`: ```json { "mcpServers": { "mixedbread": { "command": "npx", "args": [ "-y", "mcp-remote@latest", "https://www.mcp.mixedbread.com/api/mcp", "--header", "Authorization:${MXBAI_AUTH_HEADER}" ], "env": { "MXBAI_AUTH_HEADER": "Bearer YOUR_MIXEDBREAD_API_KEY" }, "trust": false, "timeout": 600000 } } } ``` - **command** tells Gemini to run mcp-remote via npx. - **args** specify the remote MCP endpoint and the header used for authentication. - **env** sets an environment variable that contains your API key. - **trust** controls whether tools require confirmation before execution. - **timeout** sets the request timeout in milliseconds. Defaults to 600000ms (10 minutes). Replace `YOUR_MIXEDBREAD_API_KEY` with your actual API key from the [Mixedbread platform](https://platform.mixedbread.com/platform?next=api-keys). ## Verification Now let's confirm the integration is working. 1. List servers: ```bash gemini mcp list ``` You should see `Mixedbread` in the output. 2. Test the connection with a simple command in chat: ```bash Create a new store called "my-knowledge-base" ``` Now you can manage your Stores and perform Search directly from the Gemini CLI. ## References - [Gemini CLI docs: MCP servers](https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html) # OpenCode URL: https://www.mixedbread.com/mcp/integrations/opencode Set up the Mixedbread MCP server with OpenCode. Learn how to set up the Mixedbread MCP server with OpenCode. ## Prerequisites Before we configure OpenCode, make sure you have the following: - [OpenCode](https://opencode.ai) installed - [Node.js 22+](https://nodejs.org) installed - A [Mixedbread API key](https://platform.mixedbread.com/platform?next=api-keys) from our platform ## Configuration OpenCode configures MCP servers via a configuration file named `opencode.json`. 1. Create the configuration file The recommended setup is project-level: Place an `opencode.json` file in the root of your repository. 2. Add a Mixedbread server entry Add the following to your `opencode.json`: ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "mixedbread": { "type": "local", "command": [ "npx", "-y", "mcp-remote@latest", "https://www.mcp.mixedbread.com/api/mcp", "--header", "Authorization:${MXBAI_AUTH_HEADER}" ], "enabled": true, "environment": { "MXBAI_AUTH_HEADER": "Bearer YOUR_MIXEDBREAD_API_KEY" } } } } ``` - **type** specifies that the server runs locally. - **command** runs mcp-remote with the Mixedbread MCP endpoint and authentication header. - **enabled** controls whether the server is active. - **environment** sets your API key as an environment variable. Replace `YOUR_MIXEDBREAD_API_KEY` with your actual key from the [Mixedbread platform](https://platform.mixedbread.com/platform?next=api-keys). ## Verification Now let's confirm the integration is working. 1. Start OpenCode and reload the configuration. 2. Confirm the `Mixedbread` server is listed under tools and enabled. 3. Test the connection with a simple command, for example: ```bash Create a new store called "my-knowledge-base" ``` Now you can manage your Stores and perform Search directly from OpenCode. ## References - [OpenCode docs: MCP servers](https://opencode.ai/docs/mcp-servers) # VS Code URL: https://www.mixedbread.com/mcp/integrations/vs-code Set up the Mixedbread MCP server with VS Code. Learn how to set up the Mixedbread MCP server with Visual Studio Code. ## Prerequisites Before we configure VS Code, make sure you have the following: - [Visual Studio Code](https://code.visualstudio.com) installed - [GitHub Copilot Chat](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat) extension - [Node.js 22+](https://nodejs.org) installed - A [Mixedbread API key](https://platform.mixedbread.com/platform?next=api-keys) from our platform ## Configuration VS Code configures MCP servers via a configuration file named `mcp.json`. 1. Open the configuration file From the Command Palette, run: ``` MCP: Configure Servers ``` This will open `mcp.json` for your current scope. 2. Add a Mixedbread server entry Add the following to your `mcp.json`: ```json { "servers": { "mixedbread": { "type": "stdio", "command": "npx", "args": [ "-y", "mcp-remote@latest", "https://www.mcp.mixedbread.com/api/mcp", "--header", "Authorization:${MXBAI_AUTH_HEADER}" ], "env": { "MXBAI_AUTH_HEADER": "Bearer YOUR_MIXEDBREAD_API_KEY" } } } } ``` - **command** runs mcp-remote via npx. - **args** specify the Mixedbread MCP endpoint and authentication header. - **env** sets an environment variable with your API key. Replace `YOUR_MIXEDBREAD_API_KEY` with your actual key from the [Mixedbread platform](https://platform.mixedbread.com/platform?next=api-keys). ## Enable and Use in Agent Mode 1. Open Copilot Chat in Agent Mode. 2. Select the Tools button and ensure `Mixedbread` is enabled. 3. Test the connection with a simple command: ```bash Create a new store called "my-knowledge-base" ``` Now you can manage your Stores and perform Search directly from VS Code. ## References - [VS Code docs: MCP servers](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) # Windsurf URL: https://www.mixedbread.com/mcp/integrations/windsurf Set up the Mixedbread MCP server with Windsurf. Learn how to set up the Mixedbread MCP server with Windsurf. ## Prerequisites Before we configure Windsurf, make sure you have the following: - [Windsurf](https://windsurf.com) installed - [Node.js 22+](https://nodejs.org) installed - A [Mixedbread API key](https://platform.mixedbread.com/platform?next=api-keys) from our platform ## Configuration Windsurf configures MCP servers via a configuration file named `mcp_config.json`. 1. Locate or create the configuration file Windsurf looks for `mcp_config.json` in the following paths: - **macOS/Linux:** `~/.codeium/windsurf/mcp_config.json` - **Windows:** `%USERPROFILE%\.codeium\windsurf\mcp_config.json` If the directory or file doesn't exist, create it manually: **macOS/Linux:** ```bash mkdir -p ~/.codeium/windsurf touch ~/.codeium/windsurf/mcp_config.json ``` **Windows (PowerShell):** ```powershell New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.codeium\windsurf" New-Item -ItemType File -Force -Path "$env:USERPROFILE\.codeium\windsurf\mcp_config.json" ``` 2. Add a Mixedbread server entry Add the following to your `mcp_config.json`: ```json { "mcpServers": { "mixedbread": { "command": "npx", "args": [ "-y", "mcp-remote@latest", "https://www.mcp.mixedbread.com/api/mcp", "--header", "Authorization:${MXBAI_AUTH_HEADER}" ], "env": { "MXBAI_AUTH_HEADER": "Bearer YOUR_MIXEDBREAD_API_KEY" } } } } ``` - **command** runs mcp-remote via npx. - **args** specify the Mixedbread MCP endpoint and authentication header. - **env** sets an environment variable with your API key. Replace `YOUR_MIXEDBREAD_API_KEY` with your actual key from the [Mixedbread platform](https://platform.mixedbread.com/platform?next=api-keys). ## Managing Tools Cascade limits total enabled tools to 100 at a time. You can manage tool access by: - Opening the Tools tab inside the plugin - Navigating to Windsurf Settings → Cascade → Manage plugins From here, you can toggle specific tools on or off. ## Verification Now let's confirm the integration is working. 1. Open the Cascade panel → Plugins and press Refresh. 2. Confirm that `Mixedbread` appears and is enabled. 3. Start a session and test Mixedbread tools with a simple command: ```bash Create a new store called "my-knowledge-base" ``` Now you can manage your Stores and perform Search directly from Windsurf. ## References - [Windsurf docs: Model Context Protocol](https://docs.windsurf.com/windsurf/cascade/mcp) # Zed URL: https://www.mixedbread.com/mcp/integrations/zed Set up the Mixedbread MCP server with Zed. Learn how to set up the Mixedbread MCP server with Zed. ## Prerequisites Before we configure Zed, make sure you have the following: - [Zed](https://zed.dev) installed - [Node.js 22+](https://nodejs.org) installed - A [Mixedbread API key](https://platform.mixedbread.com/platform?next=api-keys) from our platform ## Configuration Zed configures MCP servers via a configuration file named `settings.json`. ### Method 1 — Edit settings.json 1. Open Zed settings: - Command Palette → Zed: Open settings 2. Add the Mixedbread MCP server by adding the following JSON to your `settings.json`: ```json { "context_servers": { "mixedbread": { "command": "npx", "args": [ "-y", "mcp-remote@latest", "https://www.mcp.mixedbread.com/api/mcp", "--header", "Authorization:${MXBAI_AUTH_HEADER}" ], "env": { "MXBAI_AUTH_HEADER": "Bearer YOUR_MIXEDBREAD_API_KEY" } } } } ``` - **source** specifies a custom context server. - **command** runs mcp-remote with the Mixedbread MCP endpoint. - **env** sets an environment variable with your API key. Replace `YOUR_MIXEDBREAD_API_KEY` with your actual key from the [Mixedbread platform](https://platform.mixedbread.com/platform?next=api-keys). 3. Save your settings. Zed will start the server shortly after saving. You can confirm status in the Agent Panel. ### Method 2 — Add via Agent Panel UI 1. Open the Agent Panel → Settings. 2. Click Add Custom Server. 3. Fill in the fields: - Name: mixedbread - Command: npx - Args: - `-y` - `mcp-remote@latest` - `https://www.mcp.mixedbread.com/api/mcp` - `--header` - `Authorization:${MXBAI_AUTH_HEADER}` - Env: - `MXBAI_AUTH_HEADER=Bearer YOUR_MIXEDBREAD_API_KEY` 4. Save. The server should appear in the panel with a status indicator. ## Verification Now let's confirm the integration is working. 1. Open the Agent Panel → Settings. 2. Confirm the status dot next to `Mixedbread` is green and the tooltip says "Server is active." 3. Test the connection with a simple command: ```bash Create a new store called "my-knowledge-base" ``` Now you can manage your Stores and perform Search directly from Zed. ## References - [Zed docs: Model Context Protocol](https://zed.dev/docs/ai/mcp) # Tools URL: https://www.mixedbread.com/mcp/tools Complete reference for all tools available in the Mixedbread MCP server, organized by category with examples and best practices. The Mixedbread MCP server provides a comprehensive set of tools for store management and search. ## Tool Categories **Search Operations** - **[Store Search](#store-search)** - **[Store File Search](#store-file-search)** **Store Management** - **[Store Create](#store-create)** - **[Store Retrieve](#store-retrieve)** - **[Store List](#store-list)** - **[Store Delete](#store-delete)** ## Search Operations ### Store Search Search for relevant document chunks within stores. **Parameters:** | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `query` | string | Yes | - | The search query text | | `store_identifiers` | string[] | Yes | - | Array of store IDs or names to search in | | `top_k` | number | No | 5 | Number of top results to return (max: 100) | | `filters` | object | No | - | Custom filters to apply to the search | | `file_ids` | string[] | No | - | Specific file IDs to search within | | `search_options` | object | No | - | Additional search configuration options | ### Store File Search Search for relevant files stored in stores. **Parameters:** | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `query` | string | Yes | - | The search query text | | `store_identifiers` | string[] | Yes | - | Array of store IDs or names | | `top_k` | number | No | 5 | Number of top files to return | | `filters` | object | No | - | Custom filters to apply | | `file_ids` | string[] | No | - | Specific file IDs to search within | | `search_options` | object | No | - | Advanced search options | ## Store Management ### Store Create Create a new store with specified name and optional description. **Parameters:** | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `name` | string | Yes | - | Name of the store (must be unique) | | `description` | string | No | - | Optional description of the store's purpose | ### Store Retrieve Get detailed information about a specific store. **Parameters:** | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `store_identifier` | string | Yes | - | The identifier of the store | ### Store List List all available stores with optional filtering and pagination. **Parameters:** | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `q` | string | No | - | Search query for fuzzy matching over name and description fields | | `limit` | number | No | 20 | Maximum number of items to return per page (1-100) | | `after` | string | No | - | Cursor for forward pagination - get items after this position. Use last_cursor from previous response. | | `before` | string | No | - | Cursor for backward pagination - get items before this position. Use first_cursor from previous response. | | `include_total` | boolean | No | false | Whether to include total count in response (expensive operation) | ### Store Delete Delete an existing store and all its contents. **Parameters:** | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `store_identifier` | string | Yes | - | The identifier of the store to delete | **Warning:** This action is irreversible. All files and chunks in the store will be permanently deleted. # Create a Chat Completion URL: https://www.mixedbread.com/api-reference/endpoints/chat/create-chat-completion Create an OpenAI-compatible chat completion with optional client-executed function tools. ```json { "paths": { "/v1/chat/completions": { "post": { "tags": [ "chat" ], "summary": "Create a Chat Completion", "description": "Supports the OpenAI Chat Completions API subset: a message list, function\ntools, streaming via server-sent events, and persistence via `store`. A\nrequest without hosted tools is one generation over exactly what was sent:\nno instructions, tools, or turns are added. The `previous_completion_id`\ngroups stored turns into a conversation and restores the full model\ncontext; callers normally send only the new suffix. (`previous_messages`\nand `terminal_tool_name` are deprecated: resend the full edited history in\n`messages` instead.)\nRetrieval is opt-in: declare the hosted store tools (`store_search`,\n`store_grep`, `store_list_chunks`, `store_metadata_facets`, `list_stores`)\nin `tools` to let the model search, grep, filter, and read the caller's\nstores server-side, scoped by each declaration. Those executions are\nreported in the `hosted_tool_calls` extension field (and as extra streaming\nchunks), with chunk results included only for the requested `include` keys.\nA model call to a caller-declared function tool ends the completion with\n`tool_calls` on the choice message (finish_reason `tool_calls`); execute the\nfunctions and continue the conversation by appending the assistant message\nand the matching `tool` messages to the next request.", "operationId": "create_chat_completion", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompletionCreateParams", "description": "Completion parameters including messages and tools" } } } }, "responses": { "200": { "description": "The generated chat completion, or a server-sent event stream of completion chunks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletion" }, "example": { "id": "chatcmpl_abc123", "object": "chat.completion", "created": 1786622400, "model": "toast-1", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "A search agent plans queries, gathers evidence with tools, and synthesizes an answer.", "tool_calls": null, "reasoning_content": null }, "finish_reason": "stop", "logprobs": null } ], "usage": { "prompt_tokens": 15, "completion_tokens": 19, "total_tokens": 34 }, "metadata": null, "title": "What is a search agent?" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "CompletionCreateParams": { "properties": { "messages": { "items": { "oneOf": [ { "$ref": "#/components/schemas/SystemMessage" }, { "$ref": "#/components/schemas/DeveloperMessage" }, { "$ref": "#/components/schemas/UserMessage" }, { "$ref": "#/components/schemas/AssistantMessage-Input" }, { "$ref": "#/components/schemas/ToolMessage" } ], "discriminator": { "propertyName": "role", "mapping": { "assistant": "#/components/schemas/AssistantMessage-Input", "developer": "#/components/schemas/DeveloperMessage", "system": "#/components/schemas/SystemMessage", "tool": "#/components/schemas/ToolMessage", "user": "#/components/schemas/UserMessage" } } }, "type": "array", "minItems": 1, "title": "Messages", "description": "The conversation, or its new suffix when continuing a stored completion" }, "model": { "type": "string", "title": "Model", "description": "Public model ID. Defaults to toast-1", "default": "toast-1" }, "tools": { "items": { "oneOf": [ { "$ref": "#/components/schemas/SearchCorpusTool" }, { "$ref": "#/components/schemas/GrepTool" }, { "$ref": "#/components/schemas/FilterChunksTool" }, { "$ref": "#/components/schemas/InspectMetadataTool" }, { "$ref": "#/components/schemas/GetChunksTool" }, { "$ref": "#/components/schemas/StoreSearchTool" }, { "$ref": "#/components/schemas/StoreGrepTool" }, { "$ref": "#/components/schemas/StoreListChunksTool" }, { "$ref": "#/components/schemas/MetadataFacetsTool" }, { "$ref": "#/components/schemas/ListStoresTool" }, { "$ref": "#/components/schemas/FunctionTool" } ], "discriminator": { "propertyName": "type", "mapping": { "filter_chunks": "#/components/schemas/FilterChunksTool", "function": "#/components/schemas/FunctionTool", "get_chunks": "#/components/schemas/GetChunksTool", "grep": "#/components/schemas/GrepTool", "inspect_metadata": "#/components/schemas/InspectMetadataTool", "list_stores": "#/components/schemas/ListStoresTool", "search_corpus": "#/components/schemas/SearchCorpusTool", "store_grep": "#/components/schemas/StoreGrepTool", "store_list_chunks": "#/components/schemas/StoreListChunksTool", "store_metadata_facets": "#/components/schemas/MetadataFacetsTool", "store_search": "#/components/schemas/StoreSearchTool" } } }, "type": "array", "title": "Tools", "description": "Tools the model may call; the hosted tools are opt-in and run server-side for the completions that declare them" }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "auto", "none", "required" ] }, { "$ref": "#/components/schemas/ToolChoiceFunction" }, { "$ref": "#/components/schemas/ToolChoiceSearchCorpus" }, { "$ref": "#/components/schemas/ToolChoiceGrep" }, { "$ref": "#/components/schemas/ToolChoiceFilterChunks" }, { "$ref": "#/components/schemas/ToolChoiceInspectMetadata" }, { "$ref": "#/components/schemas/ToolChoiceListStores" }, { "$ref": "#/components/schemas/ToolChoiceStoreSearch" }, { "$ref": "#/components/schemas/ToolChoiceStoreGrep" }, { "$ref": "#/components/schemas/ToolChoiceStoreListChunks" }, { "$ref": "#/components/schemas/ToolChoiceMetadataFacets" } ], "title": "Tool Choice", "default": "auto" }, "response_format": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/ResponseFormatText" }, { "$ref": "#/components/schemas/ResponseFormatJSONObject" }, { "$ref": "#/components/schemas/ResponseFormatJSONSchema" } ], "discriminator": { "propertyName": "type", "mapping": { "json_object": "#/components/schemas/ResponseFormatJSONObject", "json_schema": "#/components/schemas/ResponseFormatJSONSchema", "text": "#/components/schemas/ResponseFormatText" } } }, { "type": "null" } ], "title": "Response Format", "description": "The shape of the answer: plain text, any JSON object, or JSON matching a schema. A JSON answer is grammar-constrained on the final generation; tool calls are unaffected" }, "store": { "type": "boolean", "title": "Store", "description": "Whether to persist this completion for later retrieval", "default": true }, "previous_completion_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previous Completion Id", "description": "ID of a stored completion this one continues (Mixedbread extension). Groups turns into a conversation for listing and deletion, and always restores the previous completion's full model context, including hosted tool calls and results" }, "previous_messages": { "anyOf": [ { "items": { "oneOf": [ { "$ref": "#/components/schemas/SystemMessage" }, { "$ref": "#/components/schemas/DeveloperMessage" }, { "$ref": "#/components/schemas/UserMessage" }, { "$ref": "#/components/schemas/AssistantMessage-Input" }, { "$ref": "#/components/schemas/ToolMessage" } ], "discriminator": { "propertyName": "role", "mapping": { "assistant": "#/components/schemas/AssistantMessage-Input", "developer": "#/components/schemas/DeveloperMessage", "system": "#/components/schemas/SystemMessage", "tool": "#/components/schemas/ToolMessage", "user": "#/components/schemas/UserMessage" } } }, "type": "array", "minItems": 1 }, { "type": "null" } ], "title": "Previous Messages", "description": "Deprecated. Replacement for the previous completion's stored model context after client-side pruning. Send the full edited history in `messages` without `previous_completion_id` instead; the request is honored exactly as sent", "deprecated": true }, "terminal_tool_name": { "anyOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, { "type": "null" } ], "title": "Terminal Tool Name", "description": "Deprecated and ignored. The stored transcript is never rewritten around a terminal tool call; the completion ends with the model's plain-text answer", "deprecated": true }, "stream": { "type": "boolean", "title": "Stream", "description": "Stream the completion as server-sent events", "default": false }, "temperature": { "anyOf": [ { "type": "number", "maximum": 2, "minimum": 0 }, { "type": "null" } ], "title": "Temperature" }, "top_p": { "anyOf": [ { "type": "number", "maximum": 1, "minimum": 0 }, { "type": "null" } ], "title": "Top P" }, "max_completion_tokens": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Max Completion Tokens" }, "max_tokens": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Max Tokens", "description": "Deprecated alias of max_completion_tokens, honored when it is absent" }, "max_tool_calls": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Max Tool Calls", "description": "Maximum number of server-handled tool calls (store tools and prune_context) executed for this completion; ignored when none are declared" }, "context_management": { "anyOf": [ { "$ref": "#/components/schemas/ContextManagementConfig" }, { "type": "null" } ], "description": "Opt-in context editing (Mixedbread extension). Declaring the prune_context edit gives the model a tool to clear stale tool results as the conversation approaches the context window; accepted with any tool set, a no-op when nothing prunable accumulates" }, "parallel_tool_calls": { "type": "boolean", "title": "Parallel Tool Calls", "description": "Whether the model may call multiple tools in one turn; when false, at most one is honored", "default": true }, "metadata": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "include": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Include", "description": "Extra fields to include, e.g. search_corpus_call.results; unsupported values are ignored" } }, "type": "object", "required": [ "messages" ], "title": "CompletionCreateParams", "description": "Request body for POST /v1/chat/completions." }, "SystemMessage": { "properties": { "role": { "type": "string", "const": "system", "title": "Role" }, "content": { "anyOf": [ { "type": "string" }, { "items": { "$ref": "#/components/schemas/TextPart" }, "type": "array" } ], "title": "Content" } }, "type": "object", "required": [ "role", "content" ], "title": "SystemMessage" }, "TextPart": { "properties": { "type": { "type": "string", "const": "text", "title": "Type", "default": "text" }, "text": { "type": "string", "title": "Text" } }, "type": "object", "required": [ "text" ], "title": "TextPart" }, "DeveloperMessage": { "properties": { "role": { "type": "string", "const": "developer", "title": "Role" }, "content": { "anyOf": [ { "type": "string" }, { "items": { "$ref": "#/components/schemas/TextPart" }, "type": "array" } ], "title": "Content" } }, "type": "object", "required": [ "role", "content" ], "title": "DeveloperMessage", "description": "Alias of the system role; forwarded to the provider as system instructions." }, "UserMessage": { "properties": { "role": { "type": "string", "const": "user", "title": "Role" }, "content": { "anyOf": [ { "type": "string" }, { "items": { "$ref": "#/components/schemas/TextPart" }, "type": "array" } ], "title": "Content" } }, "type": "object", "required": [ "role", "content" ], "title": "UserMessage" }, "AssistantMessage-Input": { "properties": { "role": { "type": "string", "const": "assistant", "title": "Role" }, "content": { "anyOf": [ { "type": "string" }, { "items": { "$ref": "#/components/schemas/TextPart" }, "type": "array" }, { "type": "null" } ], "title": "Content" }, "tool_calls": { "items": { "$ref": "#/components/schemas/MessageToolCall" }, "type": "array", "title": "Tool Calls" }, "reasoning_content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reasoning Content" }, "annotations": { "items": { "oneOf": [ { "$ref": "#/components/schemas/FileCitation" }, { "$ref": "#/components/schemas/UrlCitation" } ], "discriminator": { "propertyName": "type", "mapping": { "file_citation": "#/components/schemas/FileCitation", "url_citation": "#/components/schemas/UrlCitation" } } }, "type": "array", "title": "Annotations" } }, "type": "object", "required": [ "role" ], "title": "AssistantMessage" }, "MessageToolCall": { "properties": { "id": { "type": "string", "title": "Id" }, "type": { "type": "string", "const": "function", "title": "Type", "default": "function" }, "function": { "$ref": "#/components/schemas/ToolCallFunction" } }, "type": "object", "required": [ "id", "function" ], "title": "MessageToolCall", "description": "One function tool call of an assistant message." }, "ToolCallFunction": { "properties": { "name": { "type": "string", "title": "Name" }, "arguments": { "type": "string", "title": "Arguments" } }, "type": "object", "required": [ "name", "arguments" ], "title": "ToolCallFunction" }, "FileCitation": { "properties": { "type": { "type": "string", "const": "file_citation", "title": "Type", "default": "file_citation" }, "file_id": { "type": "string", "title": "File Id" }, "filename": { "type": "string", "title": "Filename" }, "index": { "type": "integer", "title": "Index" }, "chunk_id": { "type": "string", "title": "Chunk Id" }, "store_id": { "type": "string", "title": "Store Id" } }, "type": "object", "required": [ "file_id", "filename", "index", "chunk_id", "store_id" ], "title": "FileCitation", "description": "The OpenAI ``file_citation`` annotation, plus the chunk it points at.\n\n``chunk_id`` is the same ``file_id:chunk_index`` reference every hosted\nresult carries, and ``store_id`` the store whose index holds the chunk;\nthe cited text and score are on the included tool results." }, "UrlCitation": { "properties": { "type": { "type": "string", "const": "url_citation", "title": "Type", "default": "url_citation" }, "url": { "type": "string", "title": "Url" }, "title": { "type": "string", "title": "Title" }, "start_index": { "type": "integer", "title": "Start Index" }, "end_index": { "type": "integer", "title": "End Index" }, "chunk_id": { "type": "string", "title": "Chunk Id" } }, "type": "object", "required": [ "url", "title", "start_index", "end_index", "chunk_id" ], "title": "UrlCitation", "description": "The OpenAI ``url_citation`` annotation, for a hit of the web store; ``chunk_id`` as on the hosted result." }, "ToolMessage": { "properties": { "role": { "type": "string", "const": "tool", "title": "Role" }, "content": { "anyOf": [ { "type": "string" }, { "items": { "$ref": "#/components/schemas/TextPart" }, "type": "array" } ], "title": "Content" }, "tool_call_id": { "type": "string", "title": "Tool Call Id" } }, "type": "object", "required": [ "role", "content", "tool_call_id" ], "title": "ToolMessage", "description": "Result of a function tool call, sent back by the caller." }, "SearchCorpusTool": { "properties": { "store_identifiers": { "anyOf": [ { "items": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ] }, "type": "array", "minItems": 1 }, { "type": "null" } ], "title": "Store Identifiers", "description": "IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)" }, "type": { "type": "string", "const": "search_corpus", "title": "Type", "default": "search_corpus" }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" }, { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Filters", "description": "Optional filter conditions applied to every search" }, "score_threshold": { "type": "number", "maximum": 1, "minimum": 0, "title": "Score Threshold", "description": "Minimum similarity score threshold", "default": 0 }, "citations": { "type": "boolean", "title": "Citations", "description": "Have the model cite its evidence inline; the answer ships with the markers removed and an annotations list of file_citation entries pointing at the cited chunks", "default": false } }, "type": "object", "title": "SearchCorpusTool", "description": "Hosted tool: semantic search over the caller's stores, executed server-side." }, "SearchFilter-Input": { "properties": { "all": { "anyOf": [ { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "All", "description": "List of conditions or filters to be ANDed together", "examples": [ [ { "key": "price", "operator": "gt", "value": "100" }, { "key": "color", "operator": "eq", "value": "red" } ], null ] }, "any": { "anyOf": [ { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Any", "description": "List of conditions or filters to be ORed together", "examples": [ [ { "key": "price", "operator": "gt", "value": "100" }, { "key": "color", "operator": "eq", "value": "red" } ], null ] }, "none": { "anyOf": [ { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "None", "description": "List of conditions or filters to be NOTed", "examples": [ [ { "key": "price", "operator": "gt", "value": "100" }, { "key": "color", "operator": "eq", "value": "red" } ], null ] } }, "type": "object", "title": "SearchFilter", "description": "Represents a filter with AND, OR, and NOT conditions." }, "SearchFilterCondition": { "properties": { "key": { "type": "string", "title": "Key", "description": "The field to apply the condition on", "examples": [ "price", "color" ] }, "value": { "title": "Value", "description": "The value to compare against", "examples": [ "100", "red" ] }, "operator": { "$ref": "#/components/schemas/ConditionOperator", "description": "The operator for the condition", "examples": [ "eq", "gt" ] } }, "type": "object", "required": [ "key", "value", "operator" ], "title": "SearchFilterCondition", "description": "Represents a condition with a field, operator, and value." }, "ConditionOperator": { "type": "string", "enum": [ "eq", "not_eq", "gt", "gte", "lt", "lte", "in", "not_in", "like", "contains", "starts_with", "not_like", "regex" ], "title": "ConditionOperator", "description": "Operator for a filter condition." }, "GrepTool": { "properties": { "store_identifiers": { "anyOf": [ { "items": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ] }, "type": "array", "minItems": 1 }, { "type": "null" } ], "title": "Store Identifiers", "description": "IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)" }, "type": { "type": "string", "const": "grep", "title": "Type", "default": "grep" }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" }, { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Filters", "description": "Optional filter conditions applied to every grep" }, "citations": { "type": "boolean", "title": "Citations", "description": "Have the model cite its evidence inline; the answer ships with the markers removed and an annotations list of file_citation entries pointing at the cited chunks", "default": false } }, "type": "object", "title": "GrepTool", "description": "Hosted tool: regular-expression match over stores' chunks, executed server-side.\n\ngrep runs the pattern against the literal chunk text — no embeddings, no\nreranker. Each call searches all pinned stores, or the store selected by the\nmodel when no stores are pinned, with one global result limit." }, "FilterChunksTool": { "properties": { "store_identifiers": { "anyOf": [ { "items": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ] }, "type": "array", "minItems": 1 }, { "type": "null" } ], "title": "Store Identifiers", "description": "IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)" }, "type": { "type": "string", "const": "filter_chunks", "title": "Type", "default": "filter_chunks" }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" }, { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Filters", "description": "Optional filter conditions applied to every listing" }, "citations": { "type": "boolean", "title": "Citations", "description": "Have the model cite its evidence inline; the answer ships with the markers removed and an annotations list of file_citation entries pointing at the cited chunks", "default": false } }, "type": "object", "title": "FilterChunksTool", "description": "Hosted tool: metadata-driven listing of stores' chunks, executed server-side.\n\nNo embeddings and no reranker: chunks are selected by metadata filters and\noptionally ordered globally by a numeric metadata field. Each call covers all\npinned stores, or the store selected by the model when no stores are pinned." }, "InspectMetadataTool": { "properties": { "store_identifiers": { "anyOf": [ { "items": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ] }, "type": "array", "minItems": 1 }, { "type": "null" } ], "title": "Store Identifiers", "description": "IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)" }, "type": { "type": "string", "const": "inspect_metadata", "title": "Type", "default": "inspect_metadata" }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" }, { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Filters", "description": "Optional filter conditions restricting the files the facets are computed over" } }, "type": "object", "title": "InspectMetadataTool", "description": "Hosted tool: metadata field/value overview of the caller's stores, executed server-side.\n\nFacets tell the model which metadata keys exist and what their values look\nlike, so it can filter (`grep`, `filter_chunks`) and phrase queries\nagainst real values instead of guessing." }, "GetChunksTool": { "properties": { "store_identifiers": { "anyOf": [ { "items": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ] }, "type": "array", "minItems": 1 }, { "type": "null" } ], "title": "Store Identifiers", "description": "IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)" }, "type": { "type": "string", "const": "get_chunks", "title": "Type", "default": "get_chunks" } }, "type": "object", "title": "GetChunksTool", "description": "Hosted tool: re-fetch of already-seen chunks by their `file_id:chunk_index` ids.\n\nThe recovery half of the per-chunk payload clip: a chunk a search returned\ntruncated can be re-read at a much larger budget. Configuration is the\nshared store scope only; the per-call id bound is the tool schema's own\n`maxItems`." }, "StoreSearchTool": { "properties": { "store_identifiers": { "anyOf": [ { "items": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ] }, "type": "array", "minItems": 1 }, { "type": "null" } ], "title": "Store Identifiers", "description": "IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)" }, "type": { "type": "string", "const": "store_search", "title": "Type", "default": "store_search" }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" }, { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Filters", "description": "Optional filter conditions applied to every search" }, "score_threshold": { "type": "number", "maximum": 1, "minimum": 0, "title": "Score Threshold", "description": "Minimum similarity score threshold", "default": 0 }, "citations": { "type": "boolean", "title": "Citations", "description": "Have the model cite its evidence inline; the answer ships with the markers removed and an annotations list of file_citation entries pointing at the cited chunks", "default": false } }, "type": "object", "title": "StoreSearchTool", "description": "Deprecated alias of `search_corpus`; parses to the same tool, echoed as sent.", "deprecated": true }, "StoreGrepTool": { "properties": { "store_identifiers": { "anyOf": [ { "items": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ] }, "type": "array", "minItems": 1 }, { "type": "null" } ], "title": "Store Identifiers", "description": "IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)" }, "type": { "type": "string", "const": "store_grep", "title": "Type", "default": "store_grep" }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" }, { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Filters", "description": "Optional filter conditions applied to every grep" }, "citations": { "type": "boolean", "title": "Citations", "description": "Have the model cite its evidence inline; the answer ships with the markers removed and an annotations list of file_citation entries pointing at the cited chunks", "default": false } }, "type": "object", "title": "StoreGrepTool", "description": "Deprecated alias of `grep`; parses to the same tool, echoed as sent.", "deprecated": true }, "StoreListChunksTool": { "properties": { "store_identifiers": { "anyOf": [ { "items": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ] }, "type": "array", "minItems": 1 }, { "type": "null" } ], "title": "Store Identifiers", "description": "IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)" }, "type": { "type": "string", "const": "store_list_chunks", "title": "Type", "default": "store_list_chunks" }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" }, { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Filters", "description": "Optional filter conditions applied to every listing" }, "citations": { "type": "boolean", "title": "Citations", "description": "Have the model cite its evidence inline; the answer ships with the markers removed and an annotations list of file_citation entries pointing at the cited chunks", "default": false } }, "type": "object", "title": "StoreListChunksTool", "description": "Deprecated alias of `filter_chunks`; parses to the same tool, echoed as sent.", "deprecated": true }, "MetadataFacetsTool": { "properties": { "store_identifiers": { "anyOf": [ { "items": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ] }, "type": "array", "minItems": 1 }, { "type": "null" } ], "title": "Store Identifiers", "description": "IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)" }, "type": { "type": "string", "const": "store_metadata_facets", "title": "Type", "default": "store_metadata_facets" }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" }, { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Filters", "description": "Optional filter conditions restricting the files the facets are computed over" } }, "type": "object", "title": "MetadataFacetsTool", "description": "Deprecated alias of `inspect_metadata`; parses to the same tool, echoed as sent.", "deprecated": true }, "ListStoresTool": { "properties": { "type": { "type": "string", "const": "list_stores", "title": "Type", "default": "list_stores" }, "limit": { "type": "integer", "maximum": 100, "minimum": 1, "title": "Limit", "description": "Number of stores returned per listing call", "default": 20 } }, "type": "object", "title": "ListStoresTool", "description": "Hosted tool: paginated listing of the caller's stores, executed server-side.\n\nPair it with the store-scoped tools that are left unpinned, so the model can\ndiscover which stores it may name." }, "FunctionTool": { "properties": { "type": { "type": "string", "const": "function", "title": "Type", "default": "function" }, "function": { "$ref": "#/components/schemas/FunctionDefinition" } }, "type": "object", "required": [ "function" ], "title": "FunctionTool", "description": "Client-executed function tool, as in the OpenAI Chat Completions API." }, "FunctionDefinition": { "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "parameters": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Parameters" }, "strict": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Strict" } }, "type": "object", "required": [ "name" ], "title": "FunctionDefinition", "description": "Definition of a client-executed function tool, as in the OpenAI Chat Completions API.\n\nAny name is usable; hosted tool names are only reserved against the\nrequests that declare that hosted tool (checked at the params level)." }, "ToolChoiceFunction": { "properties": { "type": { "type": "string", "const": "function", "title": "Type", "default": "function" }, "function": { "$ref": "#/components/schemas/ToolChoiceFunctionName" } }, "type": "object", "required": [ "function" ], "title": "ToolChoiceFunction", "description": "Force a call to a specific function tool, as in the OpenAI Chat Completions API." }, "ToolChoiceFunctionName": { "properties": { "name": { "type": "string", "title": "Name" } }, "type": "object", "required": [ "name" ], "title": "ToolChoiceFunctionName" }, "ToolChoiceSearchCorpus": { "properties": { "type": { "type": "string", "const": "search_corpus", "title": "Type", "default": "search_corpus" } }, "type": "object", "title": "ToolChoiceSearchCorpus", "description": "Force a call to the hosted search tool (Mixedbread extension)." }, "ToolChoiceGrep": { "properties": { "type": { "type": "string", "const": "grep", "title": "Type", "default": "grep" } }, "type": "object", "title": "ToolChoiceGrep", "description": "Force a call to the hosted grep tool (Mixedbread extension)." }, "ToolChoiceFilterChunks": { "properties": { "type": { "type": "string", "const": "filter_chunks", "title": "Type", "default": "filter_chunks" } }, "type": "object", "title": "ToolChoiceFilterChunks", "description": "Force a call to the hosted chunk-listing tool (Mixedbread extension)." }, "ToolChoiceInspectMetadata": { "properties": { "type": { "type": "string", "const": "inspect_metadata", "title": "Type", "default": "inspect_metadata" } }, "type": "object", "title": "ToolChoiceInspectMetadata", "description": "Force a call to the hosted metadata-overview tool (Mixedbread extension)." }, "ToolChoiceListStores": { "properties": { "type": { "type": "string", "const": "list_stores", "title": "Type", "default": "list_stores" } }, "type": "object", "title": "ToolChoiceListStores", "description": "Force a call to the hosted list stores tool (Mixedbread extension)." }, "ToolChoiceStoreSearch": { "properties": { "type": { "type": "string", "const": "store_search", "title": "Type", "default": "store_search" } }, "type": "object", "title": "ToolChoiceStoreSearch", "description": "Deprecated alias of the `search_corpus` tool choice.", "deprecated": true }, "ToolChoiceStoreGrep": { "properties": { "type": { "type": "string", "const": "store_grep", "title": "Type", "default": "store_grep" } }, "type": "object", "title": "ToolChoiceStoreGrep", "description": "Deprecated alias of the `grep` tool choice.", "deprecated": true }, "ToolChoiceStoreListChunks": { "properties": { "type": { "type": "string", "const": "store_list_chunks", "title": "Type", "default": "store_list_chunks" } }, "type": "object", "title": "ToolChoiceStoreListChunks", "description": "Deprecated alias of the `filter_chunks` tool choice.", "deprecated": true }, "ToolChoiceMetadataFacets": { "properties": { "type": { "type": "string", "const": "store_metadata_facets", "title": "Type", "default": "store_metadata_facets" } }, "type": "object", "title": "ToolChoiceMetadataFacets", "description": "Deprecated alias of the `inspect_metadata` tool choice.", "deprecated": true }, "ResponseFormatText": { "properties": { "type": { "type": "string", "const": "text", "title": "Type", "default": "text" } }, "type": "object", "title": "ResponseFormatText", "description": "Plain text, the default." }, "ResponseFormatJSONObject": { "properties": { "type": { "type": "string", "const": "json_object", "title": "Type", "default": "json_object" } }, "type": "object", "title": "ResponseFormatJSONObject", "description": "Any JSON object; the prompt says which." }, "ResponseFormatJSONSchema": { "properties": { "type": { "type": "string", "const": "json_schema", "title": "Type", "default": "json_schema" }, "json_schema": { "$ref": "#/components/schemas/JSONSchemaResponseFormat" } }, "type": "object", "required": [ "json_schema" ], "title": "ResponseFormatJSONSchema", "description": "The answer is a JSON value matching the given schema." }, "JSONSchemaResponseFormat": { "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$", "title": "Name" }, "schema": { "additionalProperties": true, "type": "object", "title": "Schema", "description": "The JSON schema the answer must match; decoding is constrained to it. The dialect is JSON Schema 2020-12 (`$schema`, if given, names it at the root only). References must point into the schema itself, `pattern` and `patternProperties` regexes use RE2 syntax (no backreferences or lookaround), and `unevaluatedProperties` cannot be combined with `patternProperties`" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "strict": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Strict", "description": "Accepted for compatibility. The answer is grammar-constrained to the schema either way, and the schema is not narrowed to OpenAI's strict subset" } }, "type": "object", "required": [ "name", "schema" ], "title": "JSONSchemaResponseFormat", "description": "The schema of a `json_schema` response format, as in the OpenAI API." }, "ContextManagementConfig": { "properties": { "edits": { "items": { "$ref": "#/components/schemas/ContextManagementEdit" }, "type": "array", "minItems": 1, "title": "Edits", "description": "The context edits enabled for this completion" } }, "type": "object", "required": [ "edits" ], "title": "ContextManagementConfig", "description": "Opt-in context editing for one completion (Mixedbread extension)." }, "ContextManagementEdit": { "properties": { "type": { "type": "string", "const": "prune_context", "title": "Type", "default": "prune_context" } }, "type": "object", "title": "ContextManagementEdit", "description": "One enabled context edit. `prune_context` gives the model a tool to clear\nold tool results when the conversation approaches the context window." }, "ChatCompletion": { "properties": { "id": { "type": "string", "title": "Id" }, "object": { "type": "string", "const": "chat.completion", "title": "Object", "default": "chat.completion" }, "created": { "type": "integer", "title": "Created" }, "model": { "type": "string", "title": "Model" }, "choices": { "items": { "$ref": "#/components/schemas/ChatCompletionChoice" }, "type": "array", "title": "Choices" }, "usage": { "anyOf": [ { "$ref": "#/components/schemas/CompletionUsage" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title", "description": "Short display title of the conversation this completion belongs to (Mixedbread extension)" }, "hosted_tool_calls": { "items": { "oneOf": [ { "$ref": "#/components/schemas/SearchCorpusCallItem" }, { "$ref": "#/components/schemas/GrepCallItem" }, { "$ref": "#/components/schemas/FilterChunksCallItem" }, { "$ref": "#/components/schemas/InspectMetadataCallItem" }, { "$ref": "#/components/schemas/GetChunksCallItem" }, { "$ref": "#/components/schemas/StoreSearchCallItem" }, { "$ref": "#/components/schemas/StoreGrepCallItem" }, { "$ref": "#/components/schemas/StoreListChunksCallItem" }, { "$ref": "#/components/schemas/MetadataFacetsCallItem" }, { "$ref": "#/components/schemas/ListStoresCallItem" } ], "discriminator": { "propertyName": "type", "mapping": { "filter_chunks_call": "#/components/schemas/FilterChunksCallItem", "get_chunks_call": "#/components/schemas/GetChunksCallItem", "grep_call": "#/components/schemas/GrepCallItem", "inspect_metadata_call": "#/components/schemas/InspectMetadataCallItem", "list_stores_call": "#/components/schemas/ListStoresCallItem", "search_corpus_call": "#/components/schemas/SearchCorpusCallItem", "store_grep_call": "#/components/schemas/StoreGrepCallItem", "store_list_chunks_call": "#/components/schemas/StoreListChunksCallItem", "store_metadata_facets_call": "#/components/schemas/MetadataFacetsCallItem", "store_search_call": "#/components/schemas/StoreSearchCallItem" } } }, "type": "array", "title": "Hosted Tool Calls", "description": "Server-side hosted tool executions of this completion (Mixedbread extension); chunk results ride along only for requested include keys, e.g. search_corpus_call.results" }, "context_management": { "anyOf": [ { "$ref": "#/components/schemas/ContextManagementResult" }, { "type": "null" } ], "description": "Context edits applied while serving this request (Mixedbread extension); null when the context was never edited" }, "tool_tickets": { "items": { "$ref": "#/components/schemas/ToolTicket" }, "type": "array", "title": "Tool Tickets", "description": "One short-lived ticket per client-executed tool call (Mixedbread extension). Send the matching ticket as the X-Mxbai-Tool-Ticket header on the store search or grep you run for that call, and it bills at the discounted agent rate. Each ticket redeems once." }, "transcript": { "anyOf": [ { "items": { "oneOf": [ { "$ref": "#/components/schemas/SystemMessage" }, { "$ref": "#/components/schemas/DeveloperMessage" }, { "$ref": "#/components/schemas/UserMessage" }, { "$ref": "#/components/schemas/AssistantMessage-Output" }, { "$ref": "#/components/schemas/ToolMessage" } ], "discriminator": { "propertyName": "role", "mapping": { "assistant": "#/components/schemas/AssistantMessage-Output", "developer": "#/components/schemas/DeveloperMessage", "system": "#/components/schemas/SystemMessage", "tool": "#/components/schemas/ToolMessage", "user": "#/components/schemas/UserMessage" } } }, "type": "array" }, { "type": "null" } ], "title": "Transcript", "description": "Complete stored conversation transcript when requested through include" } }, "type": "object", "required": [ "id", "created", "model", "choices" ], "title": "ChatCompletion", "description": "A chat completion object, as returned by the API and persisted for retrieval." }, "ChatCompletionChoice": { "properties": { "index": { "type": "integer", "title": "Index", "default": 0 }, "message": { "$ref": "#/components/schemas/ChatCompletionMessage" }, "finish_reason": { "type": "string", "enum": [ "stop", "tool_calls", "length" ], "title": "Finish Reason", "default": "stop" }, "logprobs": { "type": "null", "title": "Logprobs" } }, "type": "object", "required": [ "message" ], "title": "ChatCompletionChoice" }, "ChatCompletionMessage": { "properties": { "role": { "type": "string", "const": "assistant", "title": "Role", "default": "assistant" }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content" }, "refusal": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Refusal" }, "tool_calls": { "anyOf": [ { "items": { "$ref": "#/components/schemas/MessageToolCall" }, "type": "array" }, { "type": "null" } ], "title": "Tool Calls" }, "reasoning_content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reasoning Content" }, "annotations": { "anyOf": [ { "items": { "oneOf": [ { "$ref": "#/components/schemas/FileCitation" }, { "$ref": "#/components/schemas/UrlCitation" } ], "discriminator": { "propertyName": "type", "mapping": { "file_citation": "#/components/schemas/FileCitation", "url_citation": "#/components/schemas/UrlCitation" } } }, "type": "array" }, { "type": "null" } ], "title": "Annotations" } }, "type": "object", "title": "ChatCompletionMessage", "description": "The assistant message of one completion choice." }, "CompletionUsage": { "properties": { "prompt_tokens": { "type": "integer", "title": "Prompt Tokens", "default": 0 }, "completion_tokens": { "type": "integer", "title": "Completion Tokens", "default": 0 }, "total_tokens": { "type": "integer", "title": "Total Tokens", "default": 0 }, "prompt_tokens_details": { "$ref": "#/components/schemas/PromptTokensDetails" }, "completion_tokens_details": { "$ref": "#/components/schemas/CompletionTokensDetails" } }, "type": "object", "title": "CompletionUsage" }, "PromptTokensDetails": { "properties": { "cached_tokens": { "type": "integer", "title": "Cached Tokens", "description": "Prompt tokens served from the cache; part of prompt_tokens, not extra", "default": 0 } }, "type": "object", "title": "PromptTokensDetails", "description": "Breakdown of the prompt tokens, as in the OpenAI usage object." }, "CompletionTokensDetails": { "properties": { "reasoning_tokens": { "type": "integer", "title": "Reasoning Tokens", "description": "Tokens of the hosted loop's narration; part of completion_tokens, not extra", "default": 0 } }, "type": "object", "title": "CompletionTokensDetails", "description": "Breakdown of the completion tokens, as in the OpenAI usage object." }, "SearchCorpusCallItem": { "properties": { "type": { "type": "string", "const": "search_corpus_call", "title": "Type", "default": "search_corpus_call" }, "id": { "type": "string", "title": "Id" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "failed" ], "title": "Status", "default": "completed" }, "queries": { "items": { "type": "string" }, "type": "array", "title": "Queries" }, "metadata_filters": { "anyOf": [ { "items": { "$ref": "#/components/schemas/MetadataFilter" }, "type": "array" }, { "type": "null" } ], "title": "Metadata Filters" }, "filter_mode": { "type": "string", "enum": [ "all", "any" ], "title": "Filter Mode", "default": "all" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Store" }, "results": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Results" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ToolCallError" }, { "type": "null" } ] } }, "type": "object", "required": [ "id" ], "title": "SearchCorpusCallItem", "description": "Record of one server-side search execution." }, "MetadataFilter": { "properties": { "key": { "type": "string", "minLength": 1, "title": "Key", "description": "Metadata field key" }, "operator": { "$ref": "#/components/schemas/ConditionOperator", "description": "Comparison operator" }, "value": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" } ] }, "type": "array" }, { "type": "null" } ], "title": "Value", "description": "Value to compare against. Use a list for `in`/`not_in`." } }, "type": "object", "required": [ "key", "operator", "value" ], "title": "MetadataFilter", "description": "One metadata filter condition the model may attach to a hosted tool call." }, "ToolCallError": { "properties": { "code": { "type": "string", "enum": [ "permission_denied", "invalid_arguments", "server_error" ], "title": "Code" }, "message": { "type": "string", "title": "Message" } }, "type": "object", "required": [ "code", "message" ], "title": "ToolCallError", "description": "Machine-readable reason a hosted tool call failed (Mixedbread extension)." }, "GrepCallItem": { "properties": { "type": { "type": "string", "const": "grep_call", "title": "Type", "default": "grep_call" }, "id": { "type": "string", "title": "Id" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "failed" ], "title": "Status", "default": "completed" }, "pattern": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pattern" }, "targets": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StoreChunkGrepTarget" }, "type": "array" }, { "type": "null" } ], "title": "Targets" }, "case_sensitive": { "type": "boolean", "title": "Case Sensitive", "default": false }, "metadata_filters": { "anyOf": [ { "items": { "$ref": "#/components/schemas/MetadataFilter" }, "type": "array" }, { "type": "null" } ], "title": "Metadata Filters" }, "filter_mode": { "type": "string", "enum": [ "all", "any" ], "title": "Filter Mode", "default": "all" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Store" }, "results": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Results" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ToolCallError" }, { "type": "null" } ] } }, "type": "object", "required": [ "id" ], "title": "GrepCallItem", "description": "Record of one server-side grep execution." }, "StoreChunkGrepTarget": { "type": "string", "enum": [ "text", "generated" ], "title": "StoreChunkGrepTarget", "description": "Logical chunk content groups the grep tool can match against.\n\nThese map to one or more underlying chunk fields:\n\n- ``text`` → text chunks' ``text`` field (original text content).\n- ``generated`` → fields produced during ingestion (``transcription`` for audio/video,\n ``ocr_text`` for images, and ``summary`` across modalities)." }, "FilterChunksCallItem": { "properties": { "type": { "type": "string", "const": "filter_chunks_call", "title": "Type", "default": "filter_chunks_call" }, "id": { "type": "string", "title": "Id" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "failed" ], "title": "Status", "default": "completed" }, "metadata_filters": { "anyOf": [ { "items": { "$ref": "#/components/schemas/MetadataFilter" }, "type": "array" }, { "type": "null" } ], "title": "Metadata Filters" }, "filter_mode": { "type": "string", "enum": [ "all", "any" ], "title": "Filter Mode", "default": "all" }, "rank_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rank By" }, "direction": { "type": "string", "enum": [ "asc", "desc" ], "title": "Direction", "default": "desc" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Store" }, "results": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Results" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ToolCallError" }, { "type": "null" } ] } }, "type": "object", "required": [ "id" ], "title": "FilterChunksCallItem", "description": "Record of one server-side metadata-driven chunk listing." }, "InspectMetadataCallItem": { "properties": { "type": { "type": "string", "const": "inspect_metadata_call", "title": "Type", "default": "inspect_metadata_call" }, "id": { "type": "string", "title": "Id" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "failed" ], "title": "Status", "default": "completed" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Store" }, "facets": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Facets" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ToolCallError" }, { "type": "null" } ] } }, "type": "object", "required": [ "id" ], "title": "InspectMetadataCallItem", "description": "Record of one server-side metadata facets lookup." }, "GetChunksCallItem": { "properties": { "type": { "type": "string", "const": "get_chunks_call", "title": "Type", "default": "get_chunks_call" }, "id": { "type": "string", "title": "Id" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "failed" ], "title": "Status", "default": "completed" }, "chunk_ids": { "items": { "type": "string" }, "type": "array", "title": "Chunk Ids" }, "results": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Results" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ToolCallError" }, { "type": "null" } ] } }, "type": "object", "required": [ "id" ], "title": "GetChunksCallItem", "description": "Record of one server-side re-fetch of already-seen chunks." }, "StoreSearchCallItem": { "properties": { "type": { "type": "string", "const": "store_search_call", "title": "Type", "default": "store_search_call" }, "id": { "type": "string", "title": "Id" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "failed" ], "title": "Status", "default": "completed" }, "queries": { "items": { "type": "string" }, "type": "array", "title": "Queries" }, "metadata_filters": { "anyOf": [ { "items": { "$ref": "#/components/schemas/MetadataFilter" }, "type": "array" }, { "type": "null" } ], "title": "Metadata Filters" }, "filter_mode": { "type": "string", "enum": [ "all", "any" ], "title": "Filter Mode", "default": "all" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Store" }, "results": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Results" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ToolCallError" }, { "type": "null" } ] } }, "type": "object", "required": [ "id" ], "title": "StoreSearchCallItem", "description": "Deprecated `store_search_call` form, emitted for requests that declared the alias.", "deprecated": true }, "StoreGrepCallItem": { "properties": { "type": { "type": "string", "const": "store_grep_call", "title": "Type", "default": "store_grep_call" }, "id": { "type": "string", "title": "Id" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "failed" ], "title": "Status", "default": "completed" }, "pattern": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pattern" }, "targets": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StoreChunkGrepTarget" }, "type": "array" }, { "type": "null" } ], "title": "Targets" }, "case_sensitive": { "type": "boolean", "title": "Case Sensitive", "default": false }, "metadata_filters": { "anyOf": [ { "items": { "$ref": "#/components/schemas/MetadataFilter" }, "type": "array" }, { "type": "null" } ], "title": "Metadata Filters" }, "filter_mode": { "type": "string", "enum": [ "all", "any" ], "title": "Filter Mode", "default": "all" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Store" }, "results": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Results" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ToolCallError" }, { "type": "null" } ] } }, "type": "object", "required": [ "id" ], "title": "StoreGrepCallItem", "description": "Deprecated `store_grep_call` form, emitted for requests that declared the alias.", "deprecated": true }, "StoreListChunksCallItem": { "properties": { "type": { "type": "string", "const": "store_list_chunks_call", "title": "Type", "default": "store_list_chunks_call" }, "id": { "type": "string", "title": "Id" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "failed" ], "title": "Status", "default": "completed" }, "metadata_filters": { "anyOf": [ { "items": { "$ref": "#/components/schemas/MetadataFilter" }, "type": "array" }, { "type": "null" } ], "title": "Metadata Filters" }, "filter_mode": { "type": "string", "enum": [ "all", "any" ], "title": "Filter Mode", "default": "all" }, "rank_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rank By" }, "direction": { "type": "string", "enum": [ "asc", "desc" ], "title": "Direction", "default": "desc" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Store" }, "results": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Results" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ToolCallError" }, { "type": "null" } ] } }, "type": "object", "required": [ "id" ], "title": "StoreListChunksCallItem", "description": "Deprecated `store_list_chunks_call` form, emitted for requests that declared the alias.", "deprecated": true }, "MetadataFacetsCallItem": { "properties": { "type": { "type": "string", "const": "store_metadata_facets_call", "title": "Type", "default": "store_metadata_facets_call" }, "id": { "type": "string", "title": "Id" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "failed" ], "title": "Status", "default": "completed" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Store" }, "facets": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Facets" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ToolCallError" }, { "type": "null" } ] } }, "type": "object", "required": [ "id" ], "title": "MetadataFacetsCallItem", "description": "Deprecated `store_metadata_facets_call` form, emitted for requests that declared the alias.", "deprecated": true }, "ListStoresCallItem": { "properties": { "type": { "type": "string", "const": "list_stores_call", "title": "Type", "default": "list_stores_call" }, "id": { "type": "string", "title": "Id" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "failed" ], "title": "Status", "default": "completed" }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" }, "stores": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ListStoresResult" }, "type": "array" }, { "type": "null" } ], "title": "Stores" }, "has_more": { "type": "boolean", "title": "Has More", "default": false }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ToolCallError" }, { "type": "null" } ] } }, "type": "object", "required": [ "id" ], "title": "ListStoresCallItem", "description": "Record of one server-side store listing execution." }, "ListStoresResult": { "properties": { "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "connectors": { "items": { "type": "string" }, "type": "array", "title": "Connectors", "description": "Providers of the connectors ingesting into this store, e.g. slack or notion" } }, "type": "object", "required": [ "name" ], "title": "ListStoresResult", "description": "One store entry returned by the hosted list stores tool." }, "ContextManagementResult": { "properties": { "applied_edits": { "items": { "oneOf": [ { "$ref": "#/components/schemas/AppliedPruneContextEdit" }, { "$ref": "#/components/schemas/AppliedTruncateToolResultEdit" } ], "discriminator": { "propertyName": "type", "mapping": { "prune_context": "#/components/schemas/AppliedPruneContextEdit", "truncate_tool_result": "#/components/schemas/AppliedTruncateToolResultEdit" } } }, "type": "array", "minItems": 1, "title": "Applied Edits" } }, "type": "object", "required": [ "applied_edits" ], "title": "ContextManagementResult", "description": "Context edits applied while serving one request (Mixedbread extension).\n\nOnly ever emitted non-empty: a request whose context was never edited\ncarries no `context_management` object at all." }, "AppliedPruneContextEdit": { "properties": { "type": { "type": "string", "const": "prune_context", "title": "Type", "default": "prune_context" }, "calls": { "type": "integer", "title": "Calls", "description": "Number of prune_context calls the model made in this request" }, "cleared_input_tokens": { "type": "integer", "title": "Cleared Input Tokens", "description": "Input tokens cleared from the model's context" } }, "type": "object", "required": [ "calls", "cleared_input_tokens" ], "title": "AppliedPruneContextEdit", "description": "Aggregate of the model's prune_context calls in one request." }, "AppliedTruncateToolResultEdit": { "properties": { "type": { "type": "string", "const": "truncate_tool_result", "title": "Type", "default": "truncate_tool_result" }, "tool_call_id": { "type": "string", "title": "Tool Call Id", "description": "ID of the tool call whose result was shortened" }, "cleared_input_tokens": { "type": "integer", "title": "Cleared Input Tokens", "description": "Input tokens cleared from the model's context" } }, "type": "object", "required": [ "tool_call_id", "cleared_input_tokens" ], "title": "AppliedTruncateToolResultEdit", "description": "One caller tool result shortened by the server's context-overflow recovery." }, "ToolTicket": { "properties": { "tool_call_id": { "type": "string", "title": "Tool Call Id", "description": "ID of the tool call in `choices[].message.tool_calls` this covers" }, "ticket": { "type": "string", "title": "Ticket", "description": "Opaque token to send as the X-Mxbai-Tool-Ticket header" }, "expires_at": { "type": "integer", "title": "Expires At", "description": "Unix timestamp after which the ticket no longer redeems" } }, "type": "object", "required": [ "tool_call_id", "ticket", "expires_at" ], "title": "ToolTicket", "description": "Proof that one client-executed tool call belongs to this completion." }, "AssistantMessage-Output": { "properties": { "role": { "type": "string", "const": "assistant", "title": "Role" }, "content": { "anyOf": [ { "type": "string" }, { "items": { "$ref": "#/components/schemas/TextPart" }, "type": "array" }, { "type": "null" } ], "title": "Content" }, "tool_calls": { "items": { "$ref": "#/components/schemas/MessageToolCall" }, "type": "array", "title": "Tool Calls" }, "reasoning_content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reasoning Content" }, "annotations": { "items": { "oneOf": [ { "$ref": "#/components/schemas/FileCitation" }, { "$ref": "#/components/schemas/UrlCitation" } ], "discriminator": { "propertyName": "type", "mapping": { "file_citation": "#/components/schemas/FileCitation", "url_citation": "#/components/schemas/UrlCitation" } } }, "type": "array", "title": "Annotations" } }, "type": "object", "required": [ "role" ], "title": "AssistantMessage" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` Python: ```python from openai import OpenAI client = OpenAI( base_url="https://api.mixedbread.com/v1", api_key="YOUR_API_KEY", ) completion = client.chat.completions.create( model="toast-1", messages=[ { "role": "user", "content": "What is a search agent?", } ], ) print(completion.choices[0].message.content) ``` Python (async): ```python from openai import AsyncOpenAI client = AsyncOpenAI( base_url="https://api.mixedbread.com/v1", api_key="YOUR_API_KEY", ) completion = await client.chat.completions.create( model="toast-1", messages=[ { "role": "user", "content": "What is a search agent?", } ], ) print(completion.choices[0].message.content) ``` TypeScript: ```ts import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://api.mixedbread.com/v1", apiKey: "YOUR_API_KEY", }); const completion = await client.chat.completions.create({ model: "toast-1", messages: [ { role: "user", content: "What is a search agent?", }, ], }); console.log(completion.choices[0]?.message.content); ``` cURL: ```bash curl https://api.mixedbread.com/v1/chat/completions \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "model": "toast-1", "messages": [ { "role": "user", "content": "What is a search agent?" } ] }' ``` # Abort Multipart Upload URL: https://www.mixedbread.com/api-reference/endpoints/files/abort-multipart-upload Abort a multipart upload and clean up any uploaded parts. ```json { "paths": { "/v1/files/uploads/{upload_id}/abort": { "post": { "tags": [ "files" ], "summary": "Abort Multipart Upload", "operationId": "abort_multipart_upload", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "upload_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the multipart upload to abort", "title": "Upload Id" }, "description": "The ID of the multipart upload to abort" } ], "responses": { "200": { "description": "The details of the aborted upload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileDeleted" }, "example": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "deleted": true, "object": "file" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "FileDeleted": { "properties": { "id": { "type": "string", "title": "Id", "description": "The ID of the deleted file" }, "deleted": { "type": "boolean", "title": "Deleted", "description": "Whether the file was deleted", "default": true }, "object": { "type": "string", "const": "file", "title": "Object", "description": "The type of the deleted object", "default": "file" } }, "type": "object", "required": [ "id" ], "title": "FileDeleted" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") res = mxbai.files.uploads.abort("a1b2c3d4-e5f6-7890-abcd-ef1234567890") print(res) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") res = await mxbai.files.uploads.abort("a1b2c3d4-e5f6-7890-abcd-ef1234567890") print(res) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const response = await mxbai.files.uploads.abort( "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ); console.log(response); ``` cURL: ```bash curl -X POST https://api.mixedbread.com/v1/files/uploads/a1b2c3d4-e5f6-7890-abcd-ef1234567890/abort \ -H "Authorization: Bearer YOUR_API_KEY" ``` # Complete Multipart Upload URL: https://www.mixedbread.com/api-reference/endpoints/files/complete-multipart-upload Complete a multipart upload after all parts have been uploaded. Creates the file object and returns it. ```json { "paths": { "/v1/files/uploads/{upload_id}/complete": { "post": { "tags": [ "files" ], "summary": "Complete Multipart Upload", "operationId": "complete_multipart_upload", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "upload_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the multipart upload", "title": "Upload Id" }, "description": "The ID of the multipart upload" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteMultipartUploadRequest" } } } }, "responses": { "200": { "description": "The completed file details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileObject" }, "example": { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "filename": "large-document.pdf", "bytes": 104857600, "mime_type": "application/pdf", "version": 1, "created_at": "2025-01-15T10:00:00.000Z", "updated_at": "2025-01-15T10:05:00.000Z", "object": "file" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "CompleteMultipartUploadRequest": { "properties": { "parts": { "items": { "$ref": "#/components/schemas/MultipartUploadPart" }, "type": "array", "minItems": 1, "title": "Parts", "description": "List of completed parts with their ETags" } }, "type": "object", "required": [ "parts" ], "title": "CompleteMultipartUploadRequest" }, "MultipartUploadPart": { "properties": { "part_number": { "type": "integer", "minimum": 1, "title": "Part Number", "description": "1-based part number" }, "etag": { "type": "string", "title": "Etag", "description": "ETag returned by the storage backend after uploading the part" } }, "type": "object", "required": [ "part_number", "etag" ], "title": "MultipartUploadPart" }, "FileObject": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier for the file", "examples": [ "file_abc123", "file_xyz789" ] }, "filename": { "type": "string", "minLength": 1, "title": "Filename", "description": "Name of the file including extension", "examples": [ "document.pdf", "image.jpg" ] }, "bytes": { "type": "integer", "exclusiveMinimum": 0, "title": "Bytes", "description": "Size of the file in bytes", "examples": [ 1024, 2048 ] }, "mime_type": { "type": "string", "pattern": "^[\\w\\.\\-\\+]+/[\\w\\.\\-\\+]+(\\.\\w+)*$", "title": "Mime Type", "description": "MIME type of the file", "examples": [ "application/pdf", "image/jpeg", "application/vnd.openxmlformats-officedocument.presentationml.presentation", "application/x-ipynb+json" ] }, "version": { "type": "integer", "minimum": 1, "title": "Version", "description": "Version of the file", "examples": [ 1, 2 ] }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when the file was created" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Timestamp when the file was last updated" } }, "type": "object", "required": [ "id", "filename", "bytes", "mime_type", "version", "created_at", "updated_at" ], "title": "FileObject", "description": "A model representing a file object in the system.\n\nThis model contains metadata about files stored in the system, including\nidentifiers, size information, and timestamps." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") res = mxbai.files.uploads.complete( "a1b2c3d4-e5f6-7890-abcd-ef1234567890", parts=[ {"part_number": 1, "etag": '"abc123def456"'}, {"part_number": 2, "etag": '"789ghi012jkl"'}, ], ) print(res) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") res = await mxbai.files.uploads.complete( "a1b2c3d4-e5f6-7890-abcd-ef1234567890", parts=[ {"part_number": 1, "etag": '"abc123def456"'}, {"part_number": 2, "etag": '"789ghi012jkl"'}, ], ) print(res) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const response = await mxbai.files.uploads.complete( "a1b2c3d4-e5f6-7890-abcd-ef1234567890", { parts: [ { part_number: 1, etag: '"abc123def456"' }, { part_number: 2, etag: '"789ghi012jkl"' }, ], } ); console.log(response); ``` cURL: ```bash curl -X POST https://api.mixedbread.com/v1/files/uploads/a1b2c3d4-e5f6-7890-abcd-ef1234567890/complete \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "parts": [ { "part_number": 1, "etag": "\"abc123def456\"" }, { "part_number": 2, "etag": "\"789ghi012jkl\"" } ] }' ``` # Create Multipart Upload URL: https://www.mixedbread.com/api-reference/endpoints/files/create-multipart-upload Initiate a multipart upload and receive presigned URLs for uploading parts directly to storage. ```json { "paths": { "/v1/files/uploads": { "post": { "tags": [ "files" ], "summary": "Create Multipart Upload", "operationId": "create_multipart_upload", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMultipartUploadRequest" } } }, "required": true }, "responses": { "201": { "description": "The multipart upload details with presigned URLs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMultipartUploadResponse" }, "example": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "part_urls": [ { "part_number": 1, "url": "https://storage.example.com/upload?partNumber=1&uploadId=..." }, { "part_number": 2, "url": "https://storage.example.com/upload?partNumber=2&uploadId=..." } ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } } }, "components": { "schemas": { "CreateMultipartUploadRequest": { "properties": { "filename": { "type": "string", "minLength": 1, "title": "Filename", "description": "Name of the file including extension", "examples": [ "document.pdf" ] }, "file_size": { "type": "integer", "exclusiveMinimum": 0, "title": "File Size", "description": "Total size of the file in bytes", "examples": [ 10485760 ] }, "mime_type": { "type": "string", "pattern": "^[\\w\\.\\-\\+]+/[\\w\\.\\-\\+]+(\\.\\w+)*$", "title": "Mime Type", "description": "MIME type of the file", "examples": [ "application/pdf" ] }, "part_count": { "type": "integer", "maximum": 10000, "minimum": 1, "title": "Part Count", "description": "Number of parts to split the upload into", "default": 1, "examples": [ 3 ] } }, "type": "object", "required": [ "filename", "file_size", "mime_type" ], "title": "CreateMultipartUploadRequest" }, "CreateMultipartUploadResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "The multipart upload ID (use this to complete or abort)" }, "part_urls": { "items": { "$ref": "#/components/schemas/MultipartUploadPartUrl" }, "type": "array", "title": "Part Urls", "description": "Presigned URLs for uploading parts" } }, "type": "object", "required": [ "id", "part_urls" ], "title": "CreateMultipartUploadResponse" }, "MultipartUploadPartUrl": { "properties": { "part_number": { "type": "integer", "minimum": 1, "title": "Part Number", "description": "1-based part number" }, "url": { "type": "string", "title": "Url", "description": "Presigned URL for uploading this part" } }, "type": "object", "required": [ "part_number", "url" ], "title": "MultipartUploadPartUrl" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") res = mxbai.files.uploads.create( filename="large-document.pdf", file_size=104857600, mime_type="application/pdf", part_count=10, ) print(res) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") res = await mxbai.files.uploads.create( filename="large-document.pdf", file_size=104857600, mime_type="application/pdf", part_count=10, ) print(res) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const response = await mxbai.files.uploads.create({ filename: "large-document.pdf", file_size: 104857600, mime_type: "application/pdf", part_count: 10, }); console.log(response); ``` cURL: ```bash curl -X POST https://api.mixedbread.com/v1/files/uploads \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "filename": "large-document.pdf", "file_size": 104857600, "mime_type": "application/pdf", "part_count": 10 }' ``` # Delete File URL: https://www.mixedbread.com/api-reference/endpoints/files/delete-file Delete a specific file by its ID. ```json { "paths": { "/v1/files/{file_id}": { "delete": { "tags": [ "files" ], "summary": "Delete File", "description": "Removes the file from every store that references it (cleaning up chunks\nand store stats) before deleting the file object itself.", "operationId": "delete_file", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the file to delete", "title": "File Id" }, "description": "The ID of the file to delete" } ], "responses": { "200": { "description": "The details of the deleted file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileDeleted" }, "example": { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "deleted": true, "object": "file" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "FileDeleted": { "properties": { "id": { "type": "string", "title": "Id", "description": "The ID of the deleted file" }, "deleted": { "type": "boolean", "title": "Deleted", "description": "Whether the file was deleted", "default": true }, "object": { "type": "string", "const": "file", "title": "Object", "description": "The type of the deleted object", "default": "file" } }, "type": "object", "required": [ "id" ], "title": "FileDeleted" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") response = mxbai.files.delete(file_id="f47ac10b-58cc-4372-a567-0e02b2c3d479") print(response) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") response = await mxbai.files.delete(file_id="f47ac10b-58cc-4372-a567-0e02b2c3d479") print(response) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const response = await mxbai.files.delete("f47ac10b-58cc-4372-a567-0e02b2c3d479"); console.log(response); ``` cURL: ```bash curl -X DELETE https://api.mixedbread.com/v1/files/f47ac10b-58cc-4372-a567-0e02b2c3d479 \ -H "Authorization: Bearer YOUR_API_KEY" ``` # Download File URL: https://www.mixedbread.com/api-reference/endpoints/files/download-file Download a specific file by its ID. ```json { "paths": { "/v1/files/{file_id}/content": { "get": { "tags": [ "files" ], "summary": "Download File", "operationId": "download_file", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the file to download", "title": "File Id" }, "description": "The ID of the file to download" } ], "responses": { "200": { "description": "The file to be downloaded", "content": { "application/octet-stream": { "schema": { "type": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") response = mxbai.files.content("f47ac10b-58cc-4372-a567-0e02b2c3d479") with open("document.pdf", "wb") as f: for chunk in response.iter_bytes(): f.write(chunk) print("File downloaded successfully") ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") response = await mxbai.files.content("f47ac10b-58cc-4372-a567-0e02b2c3d479") with open("document.pdf", "wb") as f: async for chunk in response.aiter_bytes(): f.write(chunk) print("File downloaded successfully") ``` TypeScript: ```ts import * as fs from "node:fs"; import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const response = await mxbai.files.content("f47ac10b-58cc-4372-a567-0e02b2c3d479"); const buffer = await response.arrayBuffer(); fs.writeFileSync("document.pdf", Buffer.from(buffer)); console.log("File downloaded successfully"); ``` cURL: ```bash curl -X GET https://api.mixedbread.com/v1/files/f47ac10b-58cc-4372-a567-0e02b2c3d479/content \ -H "Authorization: Bearer YOUR_API_KEY" \ -o document.pdf echo "File downloaded successfully" ``` # Get File URL: https://www.mixedbread.com/api-reference/endpoints/files/get-file Retrieve details of a specific file by its ID. ```json { "paths": { "/v1/files/{file_id}": { "get": { "tags": [ "files" ], "summary": "Get File", "operationId": "retrieve_file", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the file to retrieve", "title": "File Id" }, "description": "The ID of the file to retrieve" } ], "responses": { "200": { "description": "The details of the requested file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileObject" }, "example": { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "filename": "document.pdf", "bytes": 1048576, "mime_type": "application/pdf", "version": 1, "created_at": "2025-01-15T10:00:00.000Z", "updated_at": "2025-01-15T10:00:00.000Z", "object": "file" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "FileObject": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier for the file", "examples": [ "file_abc123", "file_xyz789" ] }, "filename": { "type": "string", "minLength": 1, "title": "Filename", "description": "Name of the file including extension", "examples": [ "document.pdf", "image.jpg" ] }, "bytes": { "type": "integer", "exclusiveMinimum": 0, "title": "Bytes", "description": "Size of the file in bytes", "examples": [ 1024, 2048 ] }, "mime_type": { "type": "string", "pattern": "^[\\w\\.\\-\\+]+/[\\w\\.\\-\\+]+(\\.\\w+)*$", "title": "Mime Type", "description": "MIME type of the file", "examples": [ "application/pdf", "image/jpeg", "application/vnd.openxmlformats-officedocument.presentationml.presentation", "application/x-ipynb+json" ] }, "version": { "type": "integer", "minimum": 1, "title": "Version", "description": "Version of the file", "examples": [ 1, 2 ] }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when the file was created" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Timestamp when the file was last updated" } }, "type": "object", "required": [ "id", "filename", "bytes", "mime_type", "version", "created_at", "updated_at" ], "title": "FileObject", "description": "A model representing a file object in the system.\n\nThis model contains metadata about files stored in the system, including\nidentifiers, size information, and timestamps." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") response = mxbai.files.retrieve(file_id="f47ac10b-58cc-4372-a567-0e02b2c3d479") print(response) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") response = await mxbai.files.retrieve(file_id="f47ac10b-58cc-4372-a567-0e02b2c3d479") print(response) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY" }); const response = await mxbai.files.retrieve("f47ac10b-58cc-4372-a567-0e02b2c3d479"); console.log(response); ``` cURL: ```bash curl -X GET https://api.mixedbread.com/v1/files/f47ac10b-58cc-4372-a567-0e02b2c3d479 \ -H "Authorization: Bearer YOUR_API_KEY" ``` # Get Multipart Upload URL: https://www.mixedbread.com/api-reference/endpoints/files/get-multipart-upload Get a multipart upload's details with fresh presigned URLs for any parts not yet uploaded. ```json { "paths": { "/v1/files/uploads/{upload_id}": { "get": { "tags": [ "files" ], "summary": "Get Multipart Upload", "operationId": "get_multipart_upload", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "upload_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the multipart upload", "title": "Upload Id" }, "description": "The ID of the multipart upload" } ], "responses": { "200": { "description": "Upload details with presigned URLs for incomplete parts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultipartUploadDetailResponse" }, "example": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "filename": "large-document.pdf", "file_size": 104857600, "mime_type": "application/pdf", "part_count": 10, "created_at": "2025-01-15T10:00:00.000Z", "completed_parts": [ { "part_number": 1, "etag": "\"abc123def456\"" } ], "part_urls": [ { "part_number": 2, "url": "https://storage.example.com/upload?partNumber=2&uploadId=..." } ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "MultipartUploadDetailResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "The multipart upload record ID" }, "filename": { "type": "string", "title": "Filename", "description": "Original filename" }, "file_size": { "type": "integer", "title": "File Size", "description": "Total file size in bytes" }, "mime_type": { "type": "string", "title": "Mime Type", "description": "MIME type of the file" }, "part_count": { "type": "integer", "title": "Part Count", "description": "Number of parts the file was split into" }, "created_at": { "type": "string", "title": "Created At", "description": "When the upload was initiated" }, "completed_parts": { "items": { "$ref": "#/components/schemas/MultipartUploadPart" }, "type": "array", "title": "Completed Parts", "description": "Parts that have already been uploaded" }, "part_urls": { "items": { "$ref": "#/components/schemas/MultipartUploadPartUrl" }, "type": "array", "title": "Part Urls", "description": "Presigned URLs for the parts that still need to be uploaded" } }, "type": "object", "required": [ "id", "filename", "file_size", "mime_type", "part_count", "created_at", "completed_parts", "part_urls" ], "title": "MultipartUploadDetailResponse" }, "MultipartUploadPart": { "properties": { "part_number": { "type": "integer", "minimum": 1, "title": "Part Number", "description": "1-based part number" }, "etag": { "type": "string", "title": "Etag", "description": "ETag returned by the storage backend after uploading the part" } }, "type": "object", "required": [ "part_number", "etag" ], "title": "MultipartUploadPart" }, "MultipartUploadPartUrl": { "properties": { "part_number": { "type": "integer", "minimum": 1, "title": "Part Number", "description": "1-based part number" }, "url": { "type": "string", "title": "Url", "description": "Presigned URL for uploading this part" } }, "type": "object", "required": [ "part_number", "url" ], "title": "MultipartUploadPartUrl" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") res = mxbai.files.uploads.get("a1b2c3d4-e5f6-7890-abcd-ef1234567890") print(res) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") res = await mxbai.files.uploads.get("a1b2c3d4-e5f6-7890-abcd-ef1234567890") print(res) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const response = await mxbai.files.uploads.retrieve( "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ); console.log(response); ``` cURL: ```bash curl -X GET https://api.mixedbread.com/v1/files/uploads/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \ -H "Authorization: Bearer YOUR_API_KEY" ``` # List Files URL: https://www.mixedbread.com/api-reference/endpoints/files/list-files List all files for the authenticated user. ```json { "paths": { "/v1/files": { "get": { "tags": [ "files" ], "summary": "List Files", "operationId": "list_files", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Maximum number of items to return per page (1-100)", "examples": [ 10, 20, 50 ], "default": 20, "title": "Limit" }, "description": "Maximum number of items to return per page (1-100)" }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for forward pagination - get items after this position. Use last_cursor from previous response.", "examples": [ "eyJjcmVhdGVkX2F0IjoiMjAyNC0xMi0zMVQyMzo1OTo1OS4wMDBaIiwiaWQiOiJhYmMxMjMifQ==" ], "title": "After" }, "description": "Cursor for forward pagination - get items after this position. Use last_cursor from previous response." }, { "name": "before", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for backward pagination - get items before this position. Use first_cursor from previous response.", "examples": [ "eyJjcmVhdGVkX2F0IjoiMjAyNC0xMi0zMVQyMzo1OTo1OS4wMDBaIiwiaWQiOiJhYmMxMjMifQ==" ], "title": "Before" }, "description": "Cursor for backward pagination - get items before this position. Use first_cursor from previous response." }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Whether to include total count in response (expensive operation)", "examples": [ false, true ], "default": false, "title": "Include Total" }, "description": "Whether to include total count in response (expensive operation)" }, { "name": "q", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Search query for fuzzy matching over name and description fields", "title": "Q" }, "description": "Search query for fuzzy matching over name and description fields" } ], "responses": { "200": { "description": "A list of files for the user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileListResponse" }, "example": { "object": "list", "data": [ { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "filename": "document.pdf", "bytes": 1048576, "mime_type": "application/pdf", "version": 1, "created_at": "2025-01-15T10:00:00.000Z", "updated_at": "2025-01-15T10:00:00.000Z", "object": "file" }, { "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012", "filename": "report.docx", "bytes": 524288, "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "version": 1, "created_at": "2025-01-14T15:30:00.000Z", "updated_at": "2025-01-14T15:30:00.000Z", "object": "file" } ], "pagination": { "has_more": false, "first_cursor": "eyJpZCI6ImZpbGVfYWJjMTIzIn0=", "last_cursor": "eyJpZCI6ImZpbGVfZGVmNDU2In0=" } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "FileListResponse": { "properties": { "pagination": { "$ref": "#/components/schemas/CursorPaginationResponse" }, "object": { "type": "string", "const": "list", "title": "Object", "description": "The object type of the response", "default": "list" }, "data": { "items": { "$ref": "#/components/schemas/FileObject" }, "type": "array", "title": "Data", "description": "The list of files" } }, "type": "object", "required": [ "pagination", "data" ], "title": "FileListResponse" }, "CursorPaginationResponse": { "properties": { "has_more": { "type": "boolean", "title": "Has More", "description": "Contextual direction-aware flag: True if more items exist in the requested pagination direction. For 'after': more items after this page. For 'before': more items before this page.", "examples": [ true, false ] }, "first_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Cursor", "description": "Cursor of the first item in this page. Use for backward pagination. None if page is empty.", "examples": [ "eyJjcmVhdGVkX2F0IjoiMjAyNC0xMi0zMVQyMzo1OTo1OS4wMDBaIiwiaWQiOiJhYmMxMjMifQ==", null ] }, "last_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Cursor", "description": "Cursor of the last item in this page. Use for forward pagination. None if page is empty.", "examples": [ "eyJjcmVhdGVkX2F0IjoiMjAyNC0xMi0zMFQyMzo1OTo1OS4wMDBaIiwiaWQiOiJ4eXo3ODkifQ==", null ] }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total", "description": "Total number of items available across all pages. Only included when include_total=true was requested. Expensive operation - use sparingly.", "examples": [ 42, 0, null ] } }, "type": "object", "required": [ "has_more", "first_cursor", "last_cursor" ], "title": "CursorPaginationResponse", "description": "Response model for cursor-based pagination." }, "FileObject": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier for the file", "examples": [ "file_abc123", "file_xyz789" ] }, "filename": { "type": "string", "minLength": 1, "title": "Filename", "description": "Name of the file including extension", "examples": [ "document.pdf", "image.jpg" ] }, "bytes": { "type": "integer", "exclusiveMinimum": 0, "title": "Bytes", "description": "Size of the file in bytes", "examples": [ 1024, 2048 ] }, "mime_type": { "type": "string", "pattern": "^[\\w\\.\\-\\+]+/[\\w\\.\\-\\+]+(\\.\\w+)*$", "title": "Mime Type", "description": "MIME type of the file", "examples": [ "application/pdf", "image/jpeg", "application/vnd.openxmlformats-officedocument.presentationml.presentation", "application/x-ipynb+json" ] }, "version": { "type": "integer", "minimum": 1, "title": "Version", "description": "Version of the file", "examples": [ 1, 2 ] }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when the file was created" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Timestamp when the file was last updated" } }, "type": "object", "required": [ "id", "filename", "bytes", "mime_type", "version", "created_at", "updated_at" ], "title": "FileObject", "description": "A model representing a file object in the system.\n\nThis model contains metadata about files stored in the system, including\nidentifiers, size information, and timestamps." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") files = mxbai.files.list(limit=20) for file in files.data: print(file.id, file.filename) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") files = await mxbai.files.list(limit=20) for file in files.data: print(file.id, file.filename) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY" }); const files = await mxbai.files.list({ limit: 20, }); for (const file of files.data) { console.log(file.id, file.filename); } ``` cURL: ```bash curl -X GET "https://api.mixedbread.com/v1/files?limit=20" \ -H "Authorization: Bearer YOUR_API_KEY" ``` # List Multipart Uploads URL: https://www.mixedbread.com/api-reference/endpoints/files/list-multipart-uploads List all in-progress multipart uploads for the authenticated organization. ```json { "paths": { "/v1/files/uploads": { "get": { "tags": [ "files" ], "summary": "List Multipart Uploads", "operationId": "list_multipart_uploads", "responses": { "200": { "description": "All in-progress multipart uploads for the organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultipartUploadListResponse" }, "example": { "data": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "filename": "large-document.pdf", "file_size": 104857600, "mime_type": "application/pdf", "part_count": 10, "created_at": "2025-01-15T10:00:00.000Z" } ] } } } } }, "security": [ { "ApiKeyAuth": [] } ] } } }, "components": { "schemas": { "MultipartUploadListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/MultipartUploadObject" }, "type": "array", "title": "Data", "description": "List of in-progress multipart uploads" } }, "type": "object", "required": [ "data" ], "title": "MultipartUploadListResponse" }, "MultipartUploadObject": { "properties": { "id": { "type": "string", "title": "Id", "description": "The multipart upload record ID" }, "filename": { "type": "string", "title": "Filename", "description": "Original filename" }, "file_size": { "type": "integer", "title": "File Size", "description": "Total file size in bytes" }, "mime_type": { "type": "string", "title": "Mime Type", "description": "MIME type of the file" }, "part_count": { "type": "integer", "title": "Part Count", "description": "Number of parts the file was split into" }, "created_at": { "type": "string", "title": "Created At", "description": "When the upload was initiated" } }, "type": "object", "required": [ "id", "filename", "file_size", "mime_type", "part_count", "created_at" ], "title": "MultipartUploadObject" } } } } ``` Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") res = mxbai.files.uploads.list() print(res) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") res = await mxbai.files.uploads.list() print(res) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const response = await mxbai.files.uploads.list(); console.log(response); ``` cURL: ```bash curl -X GET https://api.mixedbread.com/v1/files/uploads \ -H "Authorization: Bearer YOUR_API_KEY" ``` # Update File URL: https://www.mixedbread.com/api-reference/endpoints/files/update-file Update the details of a specific file. ```json { "paths": { "/v1/files/{file_id}": { "post": { "tags": [ "files" ], "summary": "Update File", "operationId": "update_file", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the file to update", "title": "File Id" }, "description": "The ID of the file to update" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_update_file" } } } }, "responses": { "200": { "description": "The updated file details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileObject" }, "example": { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "filename": "updated_document.pdf", "bytes": 2097152, "mime_type": "application/pdf", "version": 2, "created_at": "2025-01-15T10:00:00.000Z", "updated_at": "2025-01-15T16:30:00.000Z", "object": "file" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "Body_update_file": { "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "File", "description": "The file to update" } }, "type": "object", "required": [ "file" ], "title": "Body_update_file" }, "FileObject": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier for the file", "examples": [ "file_abc123", "file_xyz789" ] }, "filename": { "type": "string", "minLength": 1, "title": "Filename", "description": "Name of the file including extension", "examples": [ "document.pdf", "image.jpg" ] }, "bytes": { "type": "integer", "exclusiveMinimum": 0, "title": "Bytes", "description": "Size of the file in bytes", "examples": [ 1024, 2048 ] }, "mime_type": { "type": "string", "pattern": "^[\\w\\.\\-\\+]+/[\\w\\.\\-\\+]+(\\.\\w+)*$", "title": "Mime Type", "description": "MIME type of the file", "examples": [ "application/pdf", "image/jpeg", "application/vnd.openxmlformats-officedocument.presentationml.presentation", "application/x-ipynb+json" ] }, "version": { "type": "integer", "minimum": 1, "title": "Version", "description": "Version of the file", "examples": [ 1, 2 ] }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when the file was created" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Timestamp when the file was last updated" } }, "type": "object", "required": [ "id", "filename", "bytes", "mime_type", "version", "created_at", "updated_at" ], "title": "FileObject", "description": "A model representing a file object in the system.\n\nThis model contains metadata about files stored in the system, including\nidentifiers, size information, and timestamps." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") file_path = "updated_document.pdf" with open(file_path, "rb") as f: res = mxbai.files.update(file_id="f47ac10b-58cc-4372-a567-0e02b2c3d479", file=f) print(res) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") file_path = "updated_document.pdf" with open(file_path, "rb") as f: res = await mxbai.files.update( file_id="f47ac10b-58cc-4372-a567-0e02b2c3d479", file=f ) print(res) ``` TypeScript: ```ts import * as fs from "node:fs"; import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY" }); const filePath = "updated_document.pdf"; const fileStream = fs.createReadStream(filePath); const response = await mxbai.files.update("f47ac10b-58cc-4372-a567-0e02b2c3d479", { file: fileStream, }); console.log(response); ``` cURL: ```bash curl -X POST https://api.mixedbread.com/v1/files/f47ac10b-58cc-4372-a567-0e02b2c3d479 \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "file=@updated_document.pdf" ``` # Upload File URL: https://www.mixedbread.com/api-reference/endpoints/files/upload-file Upload a new file. ```json { "paths": { "/v1/files": { "post": { "tags": [ "files" ], "summary": "Upload File", "operationId": "create_file", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_create_file" } } } }, "responses": { "201": { "description": "The uploaded file details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileObject" }, "example": { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "filename": "document.pdf", "bytes": 1048576, "mime_type": "application/pdf", "version": 1, "created_at": "2025-01-15T10:00:00.000Z", "updated_at": "2025-01-15T10:00:00.000Z", "object": "file" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "Body_create_file": { "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "File", "description": "The file to upload" } }, "type": "object", "required": [ "file" ], "title": "Body_create_file" }, "FileObject": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier for the file", "examples": [ "file_abc123", "file_xyz789" ] }, "filename": { "type": "string", "minLength": 1, "title": "Filename", "description": "Name of the file including extension", "examples": [ "document.pdf", "image.jpg" ] }, "bytes": { "type": "integer", "exclusiveMinimum": 0, "title": "Bytes", "description": "Size of the file in bytes", "examples": [ 1024, 2048 ] }, "mime_type": { "type": "string", "pattern": "^[\\w\\.\\-\\+]+/[\\w\\.\\-\\+]+(\\.\\w+)*$", "title": "Mime Type", "description": "MIME type of the file", "examples": [ "application/pdf", "image/jpeg", "application/vnd.openxmlformats-officedocument.presentationml.presentation", "application/x-ipynb+json" ] }, "version": { "type": "integer", "minimum": 1, "title": "Version", "description": "Version of the file", "examples": [ 1, 2 ] }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when the file was created" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Timestamp when the file was last updated" } }, "type": "object", "required": [ "id", "filename", "bytes", "mime_type", "version", "created_at", "updated_at" ], "title": "FileObject", "description": "A model representing a file object in the system.\n\nThis model contains metadata about files stored in the system, including\nidentifiers, size information, and timestamps." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") file_path = "document.pdf" with open(file_path, "rb") as f: res = mxbai.files.create(file=f) print(res) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") file_path = "document.pdf" with open(file_path, "rb") as f: res = await mxbai.files.create(file=f) print(res) ``` TypeScript: ```ts import * as fs from "node:fs"; import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const filePath = "document.pdf"; const fileStream = fs.createReadStream(filePath); const response = await mxbai.files.create({ file: fileStream }); console.log(response); ``` cURL: ```bash curl -X POST https://api.mixedbread.com/v1/files \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "file=@document.pdf" ``` # Authorize Gmail URL: https://www.mixedbread.com/api-reference/endpoints/integrations/authorize-gmail Start Gmail OAuth; the response redirects to Google's consent page. ```json { "paths": { "/v1/integrations/gmail/oauth/authorize": { "get": { "tags": [ "integrations" ], "summary": "Authorize Gmail", "description": "Every call creates an installation, also for an account the organization already connected, e.g. the same\nmailbox feeding a second store; the same account in another organization is that organization's own. To\nrefresh an existing installation's credentials, reconnect it through\n`GET /v1/integrations/gmail/installations/{installation_id}/oauth/authorize` instead.\n\nAfter consent the browser returns to the organization's return URL with `status`, `installation_id` or\n`error`, and `reference`. `error` is `store_in_use` when another installation of the account already feeds\nthe store, `store_exists` when `new_store` names a store that exists by then, `store_change_on_refresh` or\n`reconnect_account_mismatch` for the deprecated `installation_id`, and otherwise the provider's error (such\nas `access_denied`), `scope_not_granted` when consent left out a scope the connector needs, `invalid_state`,\n`token_exchange_failed` or `callback_failed`.", "operationId": "authorize_gmail_integration", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "store_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Ingestion store name. A store that already exists is shared: every data source connected to it ingests into it, except another installation of the same account, which would ingest every item again. Without it, the account's default store, numbered past a store another installation of the account feeds. Rejected with 422 when the connect refreshes an existing installation and names a store other than its own.", "title": "Store Name" }, "description": "Ingestion store name. A store that already exists is shared: every data source connected to it ingests into it, except another installation of the same account, which would ingest every item again. Without it, the account's default store, numbered past a store another installation of the account feeds. Rejected with 422 when the connect refreshes an existing installation and names a store other than its own." }, { "name": "new_store", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Ingest into a store created for this connection: the connect fails with 409 when `store_name` names a store that already exists, and without `store_name` the default name is numbered past existing stores. Rejected with 422 when the connect refreshes an existing installation, which keeps its store.", "default": false, "title": "New Store" }, "description": "Ingest into a store created for this connection: the connect fails with 409 when `store_name` names a store that already exists, and without `store_name` the default name is numbered past existing stores. Rejected with 422 when the connect refreshes an existing installation, which keeps its store." }, { "name": "installation_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Gmail installation ID when reconnecting an existing installation. Deprecated: use GET /v1/integrations/gmail/installations/{installation_id}/oauth/authorize.", "deprecated": true, "title": "Installation Id" }, "description": "Gmail installation ID when reconnecting an existing installation. Deprecated: use GET /v1/integrations/gmail/installations/{installation_id}/oauth/authorize.", "deprecated": true }, { "name": "reference", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "description": "Opaque value echoed back as `reference` on the return URL, so your app can match the outcome to the user who started the flow", "title": "Reference" }, "description": "Opaque value echoed back as `reference` on the return URL, so your app can match the outcome to the user who started the flow" }, { "name": "metadata_contextualization", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Contextualize chunks with the connector's curated metadata fields", "default": true, "title": "Metadata Contextualization" }, "description": "Contextualize chunks with the connector's curated metadata fields" }, { "name": "file_contextualization", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Generate an LLM context for each chunk situating it within the full document", "default": true, "title": "File Contextualization" }, "description": "Generate an LLM context for each chunk situating it within the full document" }, { "name": "ingestion_mode", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/StoreFileParsingStrategy", "description": "Parsing strategy for imported files", "default": "high_quality" }, "description": "Parsing strategy for imported files" } ], "responses": { "307": { "description": "Redirect to Google OAuth", "content": { "application/json": { "schema": {} } } }, "409": { "description": "The store already receives data from another installation of the same account, `new_store` names a store that already exists, a Slack workspace bot is already installed by a different Mixedbread organization, or a Notion internal integration that is already connected is asked for a new or different store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } } }, "422": { "description": "The request failed validation, the credentials it carries were rejected, or `new_store` is set on a connect that refreshes an existing installation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } } } } } } }, "components": { "schemas": { "StoreFileParsingStrategy": { "type": "string", "enum": [ "fast", "high_quality" ], "title": "StoreFileParsingStrategy", "description": "Strategy for adding a file to a store." }, "APIErrorResponse": { "properties": { "type": { "type": "string", "title": "Type" }, "code": { "anyOf": [ { "$ref": "#/components/schemas/ErrorCode" }, { "type": "null" } ] }, "message": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Message" } }, "type": "object", "required": [ "type", "code", "message" ], "title": "APIErrorResponse", "description": "JSON-compatible API error response." }, "ErrorCode": { "type": "string", "enum": [ "internal_error", "validation_error", "service_unavailable_error", "not_found_error", "conflict_error", "permission_denied_error", "payment_required_error", "rate_limit_error", "usage_quota_error", "spend_limit_exceeded_error", "credits_depleted_error", "invoice_overdue_error", "unprocessable_entity_error", "context_length_exceeded_error", "bad_request_error", "auth_error", "unsupported_file_error", "invalid_cursor_error", "auth_credentials_not_provided_error", "auth_credentials_invalid_error", "auth_credentials_expired_error", "permission_user_required_error", "permission_admin_required_error", "permission_read_required_error", "permission_write_required_error", "permission_delete_required_error", "permission_list_required_error", "permission_create_required_error", "permission_search_required_error", "organization_not_found_error", "api_key_not_found_error", "api_key_invalid_error", "api_key_expired_error", "jwt_invalid_error", "file_not_found_error", "file_invalid_error", "store_not_found_error", "store_already_exists_error", "store_expired_error", "store_filter_invalid_error", "store_chunk_invalid_error", "store_chunk_not_found_error", "store_name_already_exists_error", "store_conflicting_search_rules_error", "store_search_rule_not_found_error", "store_unsupported_search_option_error", "store_incompatible_error", "store_public_disabled_error", "store_lsf_not_enabled_error", "store_in_use_by_data_source_error", "store_frozen_error", "store_file_not_found_error", "store_file_already_exists_error", "store_file_invalid_chunk_indices_error", "store_file_bucket_mismatch_error", "bucket_not_found_error", "bucket_validation_failed_error", "bucket_in_use_error", "bucket_invalid_error", "bucket_already_exists_error", "bucket_propagation_failed_error", "bucket_feature_not_enabled_error", "bucket_unavailable_error", "trace_destination_not_found_error", "trace_destination_invalid_error", "trace_destination_unreachable_error", "trace_destination_already_exists_error", "parsing_job_not_found_error", "parsing_job_not_in_progress_error", "extraction_job_not_found_error", "extraction_job_not_in_progress_error", "model_not_found_error", "model_input_invalid_error", "data_source_feature_not_enabled_error", "data_source_not_found_error", "data_source_unsupported_error", "data_source_auth_type_not_supported_error", "data_source_type_can_not_be_changed_error", "data_source_connector_not_found_error", "invalid_state_error", "oauth2_token_exchange_failed_error", "data_source_connector_synced_file_not_found_error", "multipart_upload_not_available_error", "multipart_upload_not_found_error", "multipart_upload_part_too_small_error", "multipart_upload_missing_parts_error", "file_processing_error", "file_corrupted_error", "file_too_large_error", "file_empty_error", "file_password_protected_error" ], "title": "ErrorCode", "description": "Error codes for API responses.\n\nThese codes provide fine-grained error information to API users beyond HTTP status codes.\nOnly add error codes for situations where users need to know specific details about what went wrong.\nFor internal error handling that doesn't need to be exposed to users, use error types without codes.\n\nNaming convention:\n- Enum names use format: RESOURCE_STATE or RESOURCE_ACTION_RESULT (e.g., FILE_NOT_FOUND, AUTH_CREDENTIALS_EXPIRED)\n- String values use snake_case format: \"resource_specific_reason_error\" (e.g., \"file_not_found_error\")\n\nTODO @rui: Register these codes in the OpenAPI specification for each endpoint\nto provide better documentation and client-side error handling capabilities." } } } } ``` cURL: ```bash curl -s -o /dev/null -w '%{redirect_url}' \ 'https://api.mixedbread.com/v1/integrations/gmail/oauth/authorize?store_name=mail-olivia&reference=user-42' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` Redirects: ```bash # Location header of the 307: send the browser here https://accounts.google.com/o/oauth2/v2/auth?client_id=…&redirect_uri=…&scope=…&access_type=offline&state=… # Return URL after consent https://platform.example.com/connected?provider=gmail&status=connected&installation_id=2f1c9a8e-6b4d-4e3a-9c1f-7d8e5b6a4c21&reference=user-42 # Return URL when consent fails https://platform.example.com/connected?provider=gmail&status=error&error=account_already_connected&reference=user-42 ``` # Authorize Google Drive URL: https://www.mixedbread.com/api-reference/endpoints/integrations/authorize-google-drive Start Google Drive OAuth; the response redirects to Google's consent page. ```json { "paths": { "/v1/integrations/google_drive/oauth/authorize": { "get": { "tags": [ "integrations" ], "summary": "Authorize Google Drive", "description": "Every call creates an installation, also for an account the organization already connected, e.g. the same\nmailbox feeding a second store; the same account in another organization is that organization's own. To\nrefresh an existing installation's credentials, reconnect it through\n`GET /v1/integrations/google_drive/installations/{installation_id}/oauth/authorize` instead.\n\nAfter consent the browser returns to the organization's return URL with `status`, `installation_id` or\n`error`, and `reference`. `error` is `store_in_use` when another installation of the account already feeds\nthe store, `store_exists` when `new_store` names a store that exists by then, `store_change_on_refresh` or\n`reconnect_account_mismatch` for the deprecated `installation_id`, and otherwise the provider's error (such\nas `access_denied`), `scope_not_granted` when consent left out a scope the connector needs, `invalid_state`,\n`token_exchange_failed` or `callback_failed`.", "operationId": "authorize_google_drive_integration", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "store_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Ingestion store name. A store that already exists is shared: every data source connected to it ingests into it, except another installation of the same account, which would ingest every item again. Without it, the account's default store, numbered past a store another installation of the account feeds. Rejected with 422 when the connect refreshes an existing installation and names a store other than its own.", "title": "Store Name" }, "description": "Ingestion store name. A store that already exists is shared: every data source connected to it ingests into it, except another installation of the same account, which would ingest every item again. Without it, the account's default store, numbered past a store another installation of the account feeds. Rejected with 422 when the connect refreshes an existing installation and names a store other than its own." }, { "name": "new_store", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Ingest into a store created for this connection: the connect fails with 409 when `store_name` names a store that already exists, and without `store_name` the default name is numbered past existing stores. Rejected with 422 when the connect refreshes an existing installation, which keeps its store.", "default": false, "title": "New Store" }, "description": "Ingest into a store created for this connection: the connect fails with 409 when `store_name` names a store that already exists, and without `store_name` the default name is numbered past existing stores. Rejected with 422 when the connect refreshes an existing installation, which keeps its store." }, { "name": "installation_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Google Drive installation ID when reconnecting an existing installation. Deprecated: use GET /v1/integrations/google_drive/installations/{installation_id}/oauth/authorize.", "deprecated": true, "title": "Installation Id" }, "description": "Google Drive installation ID when reconnecting an existing installation. Deprecated: use GET /v1/integrations/google_drive/installations/{installation_id}/oauth/authorize.", "deprecated": true }, { "name": "reference", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "description": "Opaque value echoed back as `reference` on the return URL, so your app can match the outcome to the user who started the flow", "title": "Reference" }, "description": "Opaque value echoed back as `reference` on the return URL, so your app can match the outcome to the user who started the flow" }, { "name": "metadata_contextualization", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Contextualize chunks with the connector's curated metadata fields", "default": true, "title": "Metadata Contextualization" }, "description": "Contextualize chunks with the connector's curated metadata fields" }, { "name": "file_contextualization", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Generate an LLM context for each chunk situating it within the full document", "default": true, "title": "File Contextualization" }, "description": "Generate an LLM context for each chunk situating it within the full document" }, { "name": "ingestion_mode", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/StoreFileParsingStrategy", "description": "Parsing strategy for imported files", "default": "high_quality" }, "description": "Parsing strategy for imported files" } ], "responses": { "307": { "description": "Redirect to Google OAuth", "content": { "application/json": { "schema": {} } } }, "409": { "description": "The store already receives data from another installation of the same account, `new_store` names a store that already exists, a Slack workspace bot is already installed by a different Mixedbread organization, or a Notion internal integration that is already connected is asked for a new or different store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } } }, "422": { "description": "The request failed validation, the credentials it carries were rejected, or `new_store` is set on a connect that refreshes an existing installation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } } } } } } }, "components": { "schemas": { "StoreFileParsingStrategy": { "type": "string", "enum": [ "fast", "high_quality" ], "title": "StoreFileParsingStrategy", "description": "Strategy for adding a file to a store." }, "APIErrorResponse": { "properties": { "type": { "type": "string", "title": "Type" }, "code": { "anyOf": [ { "$ref": "#/components/schemas/ErrorCode" }, { "type": "null" } ] }, "message": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Message" } }, "type": "object", "required": [ "type", "code", "message" ], "title": "APIErrorResponse", "description": "JSON-compatible API error response." }, "ErrorCode": { "type": "string", "enum": [ "internal_error", "validation_error", "service_unavailable_error", "not_found_error", "conflict_error", "permission_denied_error", "payment_required_error", "rate_limit_error", "usage_quota_error", "spend_limit_exceeded_error", "credits_depleted_error", "invoice_overdue_error", "unprocessable_entity_error", "context_length_exceeded_error", "bad_request_error", "auth_error", "unsupported_file_error", "invalid_cursor_error", "auth_credentials_not_provided_error", "auth_credentials_invalid_error", "auth_credentials_expired_error", "permission_user_required_error", "permission_admin_required_error", "permission_read_required_error", "permission_write_required_error", "permission_delete_required_error", "permission_list_required_error", "permission_create_required_error", "permission_search_required_error", "organization_not_found_error", "api_key_not_found_error", "api_key_invalid_error", "api_key_expired_error", "jwt_invalid_error", "file_not_found_error", "file_invalid_error", "store_not_found_error", "store_already_exists_error", "store_expired_error", "store_filter_invalid_error", "store_chunk_invalid_error", "store_chunk_not_found_error", "store_name_already_exists_error", "store_conflicting_search_rules_error", "store_search_rule_not_found_error", "store_unsupported_search_option_error", "store_incompatible_error", "store_public_disabled_error", "store_lsf_not_enabled_error", "store_in_use_by_data_source_error", "store_frozen_error", "store_file_not_found_error", "store_file_already_exists_error", "store_file_invalid_chunk_indices_error", "store_file_bucket_mismatch_error", "bucket_not_found_error", "bucket_validation_failed_error", "bucket_in_use_error", "bucket_invalid_error", "bucket_already_exists_error", "bucket_propagation_failed_error", "bucket_feature_not_enabled_error", "bucket_unavailable_error", "trace_destination_not_found_error", "trace_destination_invalid_error", "trace_destination_unreachable_error", "trace_destination_already_exists_error", "parsing_job_not_found_error", "parsing_job_not_in_progress_error", "extraction_job_not_found_error", "extraction_job_not_in_progress_error", "model_not_found_error", "model_input_invalid_error", "data_source_feature_not_enabled_error", "data_source_not_found_error", "data_source_unsupported_error", "data_source_auth_type_not_supported_error", "data_source_type_can_not_be_changed_error", "data_source_connector_not_found_error", "invalid_state_error", "oauth2_token_exchange_failed_error", "data_source_connector_synced_file_not_found_error", "multipart_upload_not_available_error", "multipart_upload_not_found_error", "multipart_upload_part_too_small_error", "multipart_upload_missing_parts_error", "file_processing_error", "file_corrupted_error", "file_too_large_error", "file_empty_error", "file_password_protected_error" ], "title": "ErrorCode", "description": "Error codes for API responses.\n\nThese codes provide fine-grained error information to API users beyond HTTP status codes.\nOnly add error codes for situations where users need to know specific details about what went wrong.\nFor internal error handling that doesn't need to be exposed to users, use error types without codes.\n\nNaming convention:\n- Enum names use format: RESOURCE_STATE or RESOURCE_ACTION_RESULT (e.g., FILE_NOT_FOUND, AUTH_CREDENTIALS_EXPIRED)\n- String values use snake_case format: \"resource_specific_reason_error\" (e.g., \"file_not_found_error\")\n\nTODO @rui: Register these codes in the OpenAPI specification for each endpoint\nto provide better documentation and client-side error handling capabilities." } } } } ``` cURL: ```bash curl -s -o /dev/null -w '%{redirect_url}' \ 'https://api.mixedbread.com/v1/integrations/google_drive/oauth/authorize?store_name=drive-olivia&reference=user-42' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` Redirects: ```bash # Location header of the 307: send the browser here https://accounts.google.com/o/oauth2/v2/auth?client_id=…&redirect_uri=…&scope=…&access_type=offline&state=… # Return URL after consent https://platform.example.com/connected?provider=google_drive&status=connected&installation_id=2f1c9a8e-6b4d-4e3a-9c1f-7d8e5b6a4c21&reference=user-42 # Return URL when consent fails https://platform.example.com/connected?provider=google_drive&status=error&error=account_already_connected&reference=user-42 ``` # Authorize Slack URL: https://www.mixedbread.com/api-reference/endpoints/integrations/authorize-slack Start Slack OAuth; the response redirects to Slack's consent page. ```json { "paths": { "/v1/integrations/slack/oauth/authorize": { "get": { "tags": [ "integrations" ], "summary": "Authorize Slack", "description": "A personal connect (`access_mode=user`) creates an installation every time, so one person can hold several,\neach feeding its own store with its own selection, e.g. public channels in one store and direct and group\nmessages in another; the same person in another organization is that organization's own. A workspace has\none bot, so a `bot` connect refreshes the workspace's bot installation when the organization has one. To\nrefresh an existing installation's tokens, reconnect it through\n`GET /v1/integrations/slack/installations/{installation_id}/oauth/authorize` instead.\n\nAfter consent the browser returns to the organization's return URL with `status`, `installation_id` or\n`error`, and `reference`. `error` is `store_in_use` when another installation of the person already feeds\nthe store, `store_exists` when `new_store` names a store that exists by then, `new_store_on_refresh` when\n`new_store` is set on a workspace bot's refresh, `store_change_on_refresh` when `store_name` names another\nstore than the refreshed bot's, `workspace_already_connected` when another organization\ninstalled the workspace's bot, and otherwise the provider's error (such as `access_denied`),\n`invalid_state` or `callback_failed`.", "operationId": "authorize_slack_integration", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "store_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Ingestion store name. A store that already exists is shared: every data source connected to it ingests into it, except another installation of the same account, which would ingest every item again. Without it, the account's default store, numbered past a store another installation of the account feeds. Rejected with 422 when the connect refreshes an existing installation and names a store other than its own.", "title": "Store Name" }, "description": "Ingestion store name. A store that already exists is shared: every data source connected to it ingests into it, except another installation of the same account, which would ingest every item again. Without it, the account's default store, numbered past a store another installation of the account feeds. Rejected with 422 when the connect refreshes an existing installation and names a store other than its own." }, { "name": "access_mode", "in": "query", "required": false, "schema": { "enum": [ "bot", "user" ], "type": "string", "description": "Authorize as the current Slack user (default). `bot` installs a workspace bot and is only available from the dashboard; requests authenticated with an API key must use `user`.", "default": "user", "title": "Access Mode" }, "description": "Authorize as the current Slack user (default). `bot` installs a workspace bot and is only available from the dashboard; requests authenticated with an API key must use `user`." }, { "name": "reference", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "description": "Opaque value echoed back as `reference` on the return URL, so your app can match the outcome to the user who started the flow", "title": "Reference" }, "description": "Opaque value echoed back as `reference` on the return URL, so your app can match the outcome to the user who started the flow" }, { "name": "new_store", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Ingest into a store created for this connection: the connect fails with 409 when `store_name` names a store that already exists, and without `store_name` the default name is numbered past existing stores. Rejected with 422 when the connect refreshes an existing installation, which keeps its store.", "default": false, "title": "New Store" }, "description": "Ingest into a store created for this connection: the connect fails with 409 when `store_name` names a store that already exists, and without `store_name` the default name is numbered past existing stores. Rejected with 422 when the connect refreshes an existing installation, which keeps its store." }, { "name": "metadata_contextualization", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Contextualize chunks with the connector's curated metadata fields", "default": true, "title": "Metadata Contextualization" }, "description": "Contextualize chunks with the connector's curated metadata fields" }, { "name": "file_contextualization", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Generate an LLM context for each chunk situating it within the full document", "default": true, "title": "File Contextualization" }, "description": "Generate an LLM context for each chunk situating it within the full document" }, { "name": "ingestion_mode", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/StoreFileParsingStrategy", "description": "Parsing strategy for imported files", "default": "high_quality" }, "description": "Parsing strategy for imported files" } ], "responses": { "307": { "description": "Redirect to Slack OAuth", "content": { "application/json": { "schema": {} } } }, "409": { "description": "The store already receives data from another installation of the same account, `new_store` names a store that already exists, a Slack workspace bot is already installed by a different Mixedbread organization, or a Notion internal integration that is already connected is asked for a new or different store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } } }, "422": { "description": "The request failed validation, the credentials it carries were rejected, or `new_store` is set on a connect that refreshes an existing installation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } } } } } } }, "components": { "schemas": { "StoreFileParsingStrategy": { "type": "string", "enum": [ "fast", "high_quality" ], "title": "StoreFileParsingStrategy", "description": "Strategy for adding a file to a store." }, "APIErrorResponse": { "properties": { "type": { "type": "string", "title": "Type" }, "code": { "anyOf": [ { "$ref": "#/components/schemas/ErrorCode" }, { "type": "null" } ] }, "message": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Message" } }, "type": "object", "required": [ "type", "code", "message" ], "title": "APIErrorResponse", "description": "JSON-compatible API error response." }, "ErrorCode": { "type": "string", "enum": [ "internal_error", "validation_error", "service_unavailable_error", "not_found_error", "conflict_error", "permission_denied_error", "payment_required_error", "rate_limit_error", "usage_quota_error", "spend_limit_exceeded_error", "credits_depleted_error", "invoice_overdue_error", "unprocessable_entity_error", "context_length_exceeded_error", "bad_request_error", "auth_error", "unsupported_file_error", "invalid_cursor_error", "auth_credentials_not_provided_error", "auth_credentials_invalid_error", "auth_credentials_expired_error", "permission_user_required_error", "permission_admin_required_error", "permission_read_required_error", "permission_write_required_error", "permission_delete_required_error", "permission_list_required_error", "permission_create_required_error", "permission_search_required_error", "organization_not_found_error", "api_key_not_found_error", "api_key_invalid_error", "api_key_expired_error", "jwt_invalid_error", "file_not_found_error", "file_invalid_error", "store_not_found_error", "store_already_exists_error", "store_expired_error", "store_filter_invalid_error", "store_chunk_invalid_error", "store_chunk_not_found_error", "store_name_already_exists_error", "store_conflicting_search_rules_error", "store_search_rule_not_found_error", "store_unsupported_search_option_error", "store_incompatible_error", "store_public_disabled_error", "store_lsf_not_enabled_error", "store_in_use_by_data_source_error", "store_frozen_error", "store_file_not_found_error", "store_file_already_exists_error", "store_file_invalid_chunk_indices_error", "store_file_bucket_mismatch_error", "bucket_not_found_error", "bucket_validation_failed_error", "bucket_in_use_error", "bucket_invalid_error", "bucket_already_exists_error", "bucket_propagation_failed_error", "bucket_feature_not_enabled_error", "bucket_unavailable_error", "trace_destination_not_found_error", "trace_destination_invalid_error", "trace_destination_unreachable_error", "trace_destination_already_exists_error", "parsing_job_not_found_error", "parsing_job_not_in_progress_error", "extraction_job_not_found_error", "extraction_job_not_in_progress_error", "model_not_found_error", "model_input_invalid_error", "data_source_feature_not_enabled_error", "data_source_not_found_error", "data_source_unsupported_error", "data_source_auth_type_not_supported_error", "data_source_type_can_not_be_changed_error", "data_source_connector_not_found_error", "invalid_state_error", "oauth2_token_exchange_failed_error", "data_source_connector_synced_file_not_found_error", "multipart_upload_not_available_error", "multipart_upload_not_found_error", "multipart_upload_part_too_small_error", "multipart_upload_missing_parts_error", "file_processing_error", "file_corrupted_error", "file_too_large_error", "file_empty_error", "file_password_protected_error" ], "title": "ErrorCode", "description": "Error codes for API responses.\n\nThese codes provide fine-grained error information to API users beyond HTTP status codes.\nOnly add error codes for situations where users need to know specific details about what went wrong.\nFor internal error handling that doesn't need to be exposed to users, use error types without codes.\n\nNaming convention:\n- Enum names use format: RESOURCE_STATE or RESOURCE_ACTION_RESULT (e.g., FILE_NOT_FOUND, AUTH_CREDENTIALS_EXPIRED)\n- String values use snake_case format: \"resource_specific_reason_error\" (e.g., \"file_not_found_error\")\n\nTODO @rui: Register these codes in the OpenAPI specification for each endpoint\nto provide better documentation and client-side error handling capabilities." } } } } ``` cURL: ```bash curl -s -o /dev/null -w '%{redirect_url}' \ 'https://api.mixedbread.com/v1/integrations/slack/oauth/authorize?store_name=slack-olivia&reference=user-42' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` Redirects: ```bash # Location header of the 307: send the browser here https://slack.com/oauth/v2/authorize?client_id=…&user_scope=…&redirect_uri=…&state=… # Return URL after consent https://platform.example.com/connected?provider=slack&status=connected&installation_id=2f1c9a8e-6b4d-4e3a-9c1f-7d8e5b6a4c21&reference=user-42 # Return URL when consent fails https://platform.example.com/connected?provider=slack&status=error&error=access_denied&reference=user-42 ``` # Connect Granola URL: https://www.mixedbread.com/api-reference/endpoints/integrations/connect-granola Connect Granola with a personal or workspace API key. ```json { "paths": { "/v1/integrations/granola/connect": { "post": { "tags": [ "integrations" ], "summary": "Connect Granola", "description": "Every call creates an installation, also for a key already connected, e.g. the same notes feeding a second\nstore. To replace an existing installation's key, e.g. after it expired, use\n`POST /v1/integrations/granola/installations/{installation_id}/reconnect` instead: connecting the new key\nwould add an installation next to the old one.", "operationId": "connect_granola_manual", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GranolaManualConnectBody", "description": "Granola API key" } } }, "required": true }, "responses": { "200": { "description": "The connected Granola installation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorInstallationResponse" }, "example": { "data": { "installation_id": "2f1c9a8e-6b4d-4e3a-9c1f-7d8e5b6a4c21", "provider": "granola", "status": "active", "account": { "id": "9f2c7b1e4d8a6c3b5e7f0a1d2c4b6e8f", "name": "Olivia Chen", "email": "olivia@example.com", "workspace": null }, "store_id": "5d3e7f9a-1b2c-4d6e-8f0a-9c8b7a6d5e4f", "store_name": "notes-olivia", "sync": { "failed_resource_count": 0, "last_error": null, "last_error_operation": null, "last_error_at": null } } } } } }, "409": { "description": "The store already receives data from another installation of the same account, `new_store` names a store that already exists, a Slack workspace bot is already installed by a different Mixedbread organization, or a Notion internal integration that is already connected is asked for a new or different store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } } }, "422": { "description": "The request failed validation, the credentials it carries were rejected, or `new_store` is set on a connect that refreshes an existing installation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } } }, "components": { "schemas": { "GranolaManualConnectBody": { "properties": { "api_key": { "type": "string", "minLength": 1, "title": "Api Key", "description": "Granola API key" }, "store_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Store Name", "description": "Ingestion store name. A store that already exists is shared: every data source connected to it ingests into it, except another installation of the same account, which would ingest every item again. Without it, the account's default store, numbered past a store another installation of the account feeds. Rejected with 422 when the connect refreshes an existing installation and names a store other than its own." }, "new_store": { "type": "boolean", "title": "New Store", "description": "Ingest into a store created for this connection: the connect fails with 409 when `store_name` names a store that already exists, and without `store_name` the default name is numbered past existing stores. Rejected with 422 when the connect refreshes an existing installation, which keeps its store.", "default": false }, "store_config": { "$ref": "#/components/schemas/IntegrationStoreConfig", "description": "Configuration applied to the ingestion store and imported files", "default": { "metadata_contextualization": true, "file_contextualization": true, "ingestion_mode": "high_quality" } }, "sync_schedule_interval": { "type": "string", "enum": [ "off", "ten_minutes", "hourly", "daily", "weekly" ], "title": "Sync Schedule Interval", "description": "Initial periodic sync interval", "default": "ten_minutes" }, "account_name": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "Account Name", "description": "Name of the person the API key belongs to" }, "account_email": { "anyOf": [ { "type": "string", "maxLength": 320 }, { "type": "null" } ], "title": "Account Email", "description": "Email of the person the API key belongs to" } }, "type": "object", "required": [ "api_key" ], "title": "GranolaManualConnectBody", "description": "Request body for connecting Granola with an API key." }, "IntegrationStoreConfig": { "properties": { "metadata_contextualization": { "type": "boolean", "title": "Metadata Contextualization", "description": "Contextualize chunks with the connector's curated metadata fields", "default": true }, "file_contextualization": { "type": "boolean", "title": "File Contextualization", "description": "Generate an LLM context for each chunk situating it within the full document", "default": true }, "ingestion_mode": { "$ref": "#/components/schemas/StoreFileParsingStrategy", "description": "Parsing strategy for imported files", "default": "high_quality" } }, "type": "object", "title": "IntegrationStoreConfig", "description": "Store and file configuration chosen when connecting a data source.\n\nApplied to the ingestion store when the connector creates it and to every imported file.\nThe defaults (contextualization on, high-quality ingestion) give the best retrieval quality\nand downstream availability. A pre-existing store keeps its own configuration; only the\ningestion mode still applies to newly imported files." }, "StoreFileParsingStrategy": { "type": "string", "enum": [ "fast", "high_quality" ], "title": "StoreFileParsingStrategy", "description": "Strategy for adding a file to a store." }, "ConnectorInstallationResponse": { "properties": { "data": { "$ref": "#/components/schemas/ConnectorInstallation", "description": "The connected account and the store it feeds" } }, "type": "object", "required": [ "data" ], "title": "ConnectorInstallationResponse", "description": "Response containing one connected account." }, "ConnectorInstallation": { "properties": { "installation_id": { "type": "string", "title": "Installation Id", "description": "Installation ID" }, "provider": { "type": "string", "enum": [ "google_drive", "gmail", "slack", "granola" ], "title": "Provider", "description": "Connector provider" }, "status": { "type": "string", "title": "Status", "description": "Installation status" }, "account": { "$ref": "#/components/schemas/ConnectorAccount", "description": "The authorized third-party account" }, "store_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Store Id", "description": "Store the installation ingests into" }, "store_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Store Name", "description": "Name of that store" }, "sync": { "$ref": "#/components/schemas/ConnectorInstallationSync", "description": "Account-level sync facts recorded by the sync jobs" } }, "type": "object", "required": [ "installation_id", "provider", "status", "account" ], "title": "ConnectorInstallation", "description": "A connected account and the store it feeds, described the same way for every connector." }, "ConnectorAccount": { "properties": { "id": { "type": "string", "title": "Id", "description": "Provider-side account identifier (email, user ID, or team ID)" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Human-readable account name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email", "description": "Account email, when the provider exposes one" }, "workspace": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace", "description": "Workspace or organization the account belongs to, for providers that have one" } }, "type": "object", "required": [ "id" ], "title": "ConnectorAccount", "description": "The third-party account an installation is authorized as." }, "ConnectorInstallationSync": { "properties": { "failed_resource_count": { "type": "integer", "title": "Failed Resource Count", "description": "Resources whose last sync job failed", "default": 0 }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Error", "description": "Last failure of a job covering the whole account, such as a changes sync" }, "last_error_operation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Error Operation", "description": "Which account-wide job failed" }, "last_error_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Error At", "description": "When it failed" } }, "type": "object", "title": "ConnectorInstallationSync", "description": "Account-level sync facts: how many resources are in error, and the last failure of an account-wide job." }, "APIErrorResponse": { "properties": { "type": { "type": "string", "title": "Type" }, "code": { "anyOf": [ { "$ref": "#/components/schemas/ErrorCode" }, { "type": "null" } ] }, "message": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Message" } }, "type": "object", "required": [ "type", "code", "message" ], "title": "APIErrorResponse", "description": "JSON-compatible API error response." }, "ErrorCode": { "type": "string", "enum": [ "internal_error", "validation_error", "service_unavailable_error", "not_found_error", "conflict_error", "permission_denied_error", "payment_required_error", "rate_limit_error", "usage_quota_error", "spend_limit_exceeded_error", "credits_depleted_error", "invoice_overdue_error", "unprocessable_entity_error", "context_length_exceeded_error", "bad_request_error", "auth_error", "unsupported_file_error", "invalid_cursor_error", "auth_credentials_not_provided_error", "auth_credentials_invalid_error", "auth_credentials_expired_error", "permission_user_required_error", "permission_admin_required_error", "permission_read_required_error", "permission_write_required_error", "permission_delete_required_error", "permission_list_required_error", "permission_create_required_error", "permission_search_required_error", "organization_not_found_error", "api_key_not_found_error", "api_key_invalid_error", "api_key_expired_error", "jwt_invalid_error", "file_not_found_error", "file_invalid_error", "store_not_found_error", "store_already_exists_error", "store_expired_error", "store_filter_invalid_error", "store_chunk_invalid_error", "store_chunk_not_found_error", "store_name_already_exists_error", "store_conflicting_search_rules_error", "store_search_rule_not_found_error", "store_unsupported_search_option_error", "store_incompatible_error", "store_public_disabled_error", "store_lsf_not_enabled_error", "store_in_use_by_data_source_error", "store_frozen_error", "store_file_not_found_error", "store_file_already_exists_error", "store_file_invalid_chunk_indices_error", "store_file_bucket_mismatch_error", "bucket_not_found_error", "bucket_validation_failed_error", "bucket_in_use_error", "bucket_invalid_error", "bucket_already_exists_error", "bucket_propagation_failed_error", "bucket_feature_not_enabled_error", "bucket_unavailable_error", "trace_destination_not_found_error", "trace_destination_invalid_error", "trace_destination_unreachable_error", "trace_destination_already_exists_error", "parsing_job_not_found_error", "parsing_job_not_in_progress_error", "extraction_job_not_found_error", "extraction_job_not_in_progress_error", "model_not_found_error", "model_input_invalid_error", "data_source_feature_not_enabled_error", "data_source_not_found_error", "data_source_unsupported_error", "data_source_auth_type_not_supported_error", "data_source_type_can_not_be_changed_error", "data_source_connector_not_found_error", "invalid_state_error", "oauth2_token_exchange_failed_error", "data_source_connector_synced_file_not_found_error", "multipart_upload_not_available_error", "multipart_upload_not_found_error", "multipart_upload_part_too_small_error", "multipart_upload_missing_parts_error", "file_processing_error", "file_corrupted_error", "file_too_large_error", "file_empty_error", "file_password_protected_error" ], "title": "ErrorCode", "description": "Error codes for API responses.\n\nThese codes provide fine-grained error information to API users beyond HTTP status codes.\nOnly add error codes for situations where users need to know specific details about what went wrong.\nFor internal error handling that doesn't need to be exposed to users, use error types without codes.\n\nNaming convention:\n- Enum names use format: RESOURCE_STATE or RESOURCE_ACTION_RESULT (e.g., FILE_NOT_FOUND, AUTH_CREDENTIALS_EXPIRED)\n- String values use snake_case format: \"resource_specific_reason_error\" (e.g., \"file_not_found_error\")\n\nTODO @rui: Register these codes in the OpenAPI specification for each endpoint\nto provide better documentation and client-side error handling capabilities." } } } } ``` cURL: ```bash curl -X POST https://api.mixedbread.com/v1/integrations/granola/connect \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -d '{ "api_key": "grn_…", "account_name": "Olivia Chen", "account_email": "olivia@example.com", "store_name": "notes-olivia" }' ``` # Delete OAuth Client URL: https://www.mixedbread.com/api-reference/endpoints/integrations/delete-oauth-client Remove the organization's own OAuth client, disconnecting every account that connected through it and revoking their grants. ```json { "paths": { "/v1/integrations/oauth-clients/{provider}": { "delete": { "tags": [ "integrations" ], "summary": "Delete OAuth Client", "description": "Each connection's provider grant is revoked on the way out, with the same Google sharing rule as\na single disconnect.", "operationId": "delete_oauth_client", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "enum": [ "google_drive", "gmail", "slack" ], "type": "string", "description": "The connector to reset", "title": "Provider" }, "description": "The connector to reset" } ], "responses": { "200": { "description": "The connector slot after the change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthClientMutationResponse" }, "example": { "data": { "slot": { "provider": "gmail", "redirect_uri": "https://api.mixedbread.com/v1/integrations/gmail/oauth/callback", "required_scopes": [ "https://www.googleapis.com/auth/gmail.readonly" ], "app_manifest": null, "client": null }, "reauth_required_installation_ids": [], "disconnected_installation_ids": [ "2f1c9a8e-6b4d-4e3a-9c1f-7d8e5b6a4c21" ] } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "OAuthClientMutationResponse": { "properties": { "data": { "$ref": "#/components/schemas/OAuthClientMutationResult", "description": "The connector slot after the change" } }, "type": "object", "required": [ "data" ], "title": "OAuthClientMutationResponse", "description": "The result of registering, rotating, or removing a customer-owned Google OAuth client." }, "OAuthClientMutationResult": { "properties": { "slot": { "$ref": "#/components/schemas/OAuthClientSlot", "description": "The connector slot after the change" }, "reauth_required_installation_ids": { "items": { "type": "string" }, "type": "array", "title": "Reauth Required Installation Ids", "description": "Installations whose refresh tokens were invalidated and now need reconnecting" }, "disconnected_installation_ids": { "items": { "type": "string" }, "type": "array", "title": "Disconnected Installation Ids", "description": "Installations that were disconnected because the client they were authorized with was removed" } }, "type": "object", "required": [ "slot" ], "title": "OAuthClientMutationResult", "description": "The outcome of registering, rotating, or removing a customer-owned OAuth client." }, "OAuthClientSlot": { "properties": { "provider": { "type": "string", "enum": [ "google_drive", "gmail", "slack" ], "title": "Provider", "description": "The connector this slot is for" }, "redirect_uri": { "type": "string", "title": "Redirect Uri", "description": "The redirect URI that must be authorized on the customer's OAuth client" }, "required_scopes": { "items": { "type": "string" }, "type": "array", "title": "Required Scopes", "description": "Scopes the customer's OAuth client must grant" }, "app_manifest": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "App Manifest", "description": "A JSON app manifest to create the customer's app from, for connectors that have one" }, "client": { "anyOf": [ { "$ref": "#/components/schemas/OAuthClientView" }, { "type": "null" } ], "description": "The registered client, or null when the connector uses the Mixedbread client" } }, "type": "object", "required": [ "provider", "redirect_uri", "required_scopes" ], "title": "OAuthClientSlot", "description": "One connector's bring-your-own-client slot, registered or not." }, "OAuthClientView": { "properties": { "provider": { "type": "string", "enum": [ "google_drive", "gmail", "slack" ], "title": "Provider", "description": "The connector this client is used for" }, "client_id": { "type": "string", "title": "Client Id", "description": "The customer's OAuth client id" }, "redirect_uri": { "type": "string", "title": "Redirect Uri", "description": "The redirect URI that must be authorized on the customer's OAuth client" }, "return_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Return Url", "description": "Where the OAuth callback returns the user after consent, if the organization set one" }, "has_signing_secret": { "type": "boolean", "title": "Has Signing Secret", "description": "Whether a webhook signing secret is stored for the client (Slack only)", "default": false }, "created_by_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created By User Id", "description": "The user who registered the client" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At", "description": "When the client was first registered" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated At", "description": "When the client was last rotated" } }, "type": "object", "required": [ "provider", "client_id", "redirect_uri" ], "title": "OAuthClientView", "description": "An organization's registered OAuth client as exposed to the dashboard.\n\nSecrets are never part of this shape: once stored they are only ever decrypted inside a token\nexchange or a webhook signature check. A client id is public by construction (it appears in the\nconsent URL), so it is returned in full to let the customer confirm which app is wired up." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` cURL: ```bash curl -X DELETE https://api.mixedbread.com/v1/integrations/oauth-clients/gmail \ -H 'Authorization: Bearer YOUR_API_KEY' ``` # Disconnect Installation URL: https://www.mixedbread.com/api-reference/endpoints/integrations/disconnect-installation Disconnect the account, stop its syncs, and revoke its provider grant. The store and what is already in it remain. ```json { "paths": { "/v1/integrations/installations/{installation_id}": { "delete": { "tags": [ "integrations" ], "summary": "Disconnect Installation", "description": "By default the store and what is already in it remain. With ``delete_data``, a single store no other\nconnection feeds is deleted; otherwise the account's own files are removed from each store it fed, in\nthe background.\n\nThe provider grant is revoked as well: always for Slack, and for Google unless another\ninstallation of the same Google account was authorized through the same OAuth client.", "operationId": "disconnect_integration_installation", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "installation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Installation ID, as returned when the account connected", "title": "Installation Id" }, "description": "Installation ID, as returned when the account connected" }, { "name": "delete_data", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Also delete what the connection synced: its own files are removed from each store it fed, in the background, then a single store left empty that no other connection feeds.", "default": false, "title": "Delete Data" }, "description": "Also delete what the connection synced: its own files are removed from each store it fed, in the background, then a single store left empty that no other connection feeds." } ], "responses": { "200": { "description": "The disconnected account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorInstallationResponse" }, "example": { "data": { "installation_id": "2f1c9a8e-6b4d-4e3a-9c1f-7d8e5b6a4c21", "provider": "gmail", "status": "active", "account": { "id": "olivia@example.com", "name": "olivia@example.com", "email": "olivia@example.com", "workspace": null }, "store_id": "5d3e7f9a-1b2c-4d6e-8f0a-9c8b7a6d5e4f", "store_name": "mail-olivia", "sync": { "failed_resource_count": 0, "last_error": null, "last_error_operation": null, "last_error_at": null } } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "ConnectorInstallationResponse": { "properties": { "data": { "$ref": "#/components/schemas/ConnectorInstallation", "description": "The connected account and the store it feeds" } }, "type": "object", "required": [ "data" ], "title": "ConnectorInstallationResponse", "description": "Response containing one connected account." }, "ConnectorInstallation": { "properties": { "installation_id": { "type": "string", "title": "Installation Id", "description": "Installation ID" }, "provider": { "type": "string", "enum": [ "google_drive", "gmail", "slack", "granola" ], "title": "Provider", "description": "Connector provider" }, "status": { "type": "string", "title": "Status", "description": "Installation status" }, "account": { "$ref": "#/components/schemas/ConnectorAccount", "description": "The authorized third-party account" }, "store_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Store Id", "description": "Store the installation ingests into" }, "store_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Store Name", "description": "Name of that store" }, "sync": { "$ref": "#/components/schemas/ConnectorInstallationSync", "description": "Account-level sync facts recorded by the sync jobs" } }, "type": "object", "required": [ "installation_id", "provider", "status", "account" ], "title": "ConnectorInstallation", "description": "A connected account and the store it feeds, described the same way for every connector." }, "ConnectorAccount": { "properties": { "id": { "type": "string", "title": "Id", "description": "Provider-side account identifier (email, user ID, or team ID)" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Human-readable account name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email", "description": "Account email, when the provider exposes one" }, "workspace": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace", "description": "Workspace or organization the account belongs to, for providers that have one" } }, "type": "object", "required": [ "id" ], "title": "ConnectorAccount", "description": "The third-party account an installation is authorized as." }, "ConnectorInstallationSync": { "properties": { "failed_resource_count": { "type": "integer", "title": "Failed Resource Count", "description": "Resources whose last sync job failed", "default": 0 }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Error", "description": "Last failure of a job covering the whole account, such as a changes sync" }, "last_error_operation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Error Operation", "description": "Which account-wide job failed" }, "last_error_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Error At", "description": "When it failed" } }, "type": "object", "title": "ConnectorInstallationSync", "description": "Account-level sync facts: how many resources are in error, and the last failure of an account-wide job." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` cURL: ```bash curl -X DELETE https://api.mixedbread.com/v1/integrations/installations/2f1c9a8e-6b4d-4e3a-9c1f-7d8e5b6a4c21 \ -H 'Authorization: Bearer YOUR_API_KEY' ``` # Get Installation URL: https://www.mixedbread.com/api-reference/endpoints/integrations/get-installation Describe one connected account: its provider, the third-party identity, its store, and account-level sync facts. ```json { "paths": { "/v1/integrations/installations/{installation_id}": { "get": { "tags": [ "integrations" ], "summary": "Get Installation", "operationId": "get_integration_installation", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "installation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Installation ID, as returned when the account connected", "title": "Installation Id" }, "description": "Installation ID, as returned when the account connected" } ], "responses": { "200": { "description": "The connected account and the store it feeds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorInstallationResponse" }, "example": { "data": { "installation_id": "2f1c9a8e-6b4d-4e3a-9c1f-7d8e5b6a4c21", "provider": "gmail", "status": "active", "account": { "id": "olivia@example.com", "name": "olivia@example.com", "email": "olivia@example.com", "workspace": null }, "store_id": "5d3e7f9a-1b2c-4d6e-8f0a-9c8b7a6d5e4f", "store_name": "mail-olivia", "sync": { "failed_resource_count": 0, "last_error": null, "last_error_operation": null, "last_error_at": null } } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "ConnectorInstallationResponse": { "properties": { "data": { "$ref": "#/components/schemas/ConnectorInstallation", "description": "The connected account and the store it feeds" } }, "type": "object", "required": [ "data" ], "title": "ConnectorInstallationResponse", "description": "Response containing one connected account." }, "ConnectorInstallation": { "properties": { "installation_id": { "type": "string", "title": "Installation Id", "description": "Installation ID" }, "provider": { "type": "string", "enum": [ "google_drive", "gmail", "slack", "granola" ], "title": "Provider", "description": "Connector provider" }, "status": { "type": "string", "title": "Status", "description": "Installation status" }, "account": { "$ref": "#/components/schemas/ConnectorAccount", "description": "The authorized third-party account" }, "store_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Store Id", "description": "Store the installation ingests into" }, "store_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Store Name", "description": "Name of that store" }, "sync": { "$ref": "#/components/schemas/ConnectorInstallationSync", "description": "Account-level sync facts recorded by the sync jobs" } }, "type": "object", "required": [ "installation_id", "provider", "status", "account" ], "title": "ConnectorInstallation", "description": "A connected account and the store it feeds, described the same way for every connector." }, "ConnectorAccount": { "properties": { "id": { "type": "string", "title": "Id", "description": "Provider-side account identifier (email, user ID, or team ID)" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Human-readable account name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email", "description": "Account email, when the provider exposes one" }, "workspace": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace", "description": "Workspace or organization the account belongs to, for providers that have one" } }, "type": "object", "required": [ "id" ], "title": "ConnectorAccount", "description": "The third-party account an installation is authorized as." }, "ConnectorInstallationSync": { "properties": { "failed_resource_count": { "type": "integer", "title": "Failed Resource Count", "description": "Resources whose last sync job failed", "default": 0 }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Error", "description": "Last failure of a job covering the whole account, such as a changes sync" }, "last_error_operation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Error Operation", "description": "Which account-wide job failed" }, "last_error_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Error At", "description": "When it failed" } }, "type": "object", "title": "ConnectorInstallationSync", "description": "Account-level sync facts: how many resources are in error, and the last failure of an account-wide job." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` cURL: ```bash curl https://api.mixedbread.com/v1/integrations/installations/2f1c9a8e-6b4d-4e3a-9c1f-7d8e5b6a4c21 \ -H 'Authorization: Bearer YOUR_API_KEY' ``` # List Failed Resources URL: https://www.mixedbread.com/api-reference/endpoints/integrations/list-failed-resources Every resource across the account whose last sync job failed, with the error that job recorded. ```json { "paths": { "/v1/integrations/installations/{installation_id}/resources/failed": { "get": { "tags": [ "integrations" ], "summary": "List Failed Resources", "operationId": "list_integration_installation_failed_resources", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "installation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Installation ID, as returned when the account connected", "title": "Installation Id" }, "description": "Installation ID, as returned when the account connected" } ], "responses": { "200": { "description": "Resources whose last sync job failed, with the error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorResourceListResponse" }, "example": { "data": [ { "id": "C0B923S996K", "name": "design-reviews", "kind": "channel", "is_selected": true, "parent_id": null, "url": null, "message_count": null, "member_count": 5, "sync": { "status": "error", "last_synced_at": null, "error": "Slack import timed out or exceeded retries. Run Sync to retry.", "last_run": { "status": "failed", "started_at": "2026-09-05T17:46:33.299985Z", "completed_at": "2026-09-05T18:34:55.380515Z", "error": "Slack import timed out or exceeded retries. Run Sync to retry." } } } ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "ConnectorResourceListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ConnectorResource" }, "type": "array", "title": "Data", "description": "Connector resources" } }, "type": "object", "required": [ "data" ], "title": "ConnectorResourceListResponse", "description": "A flat list of connector resources." }, "ConnectorResource": { "properties": { "id": { "type": "string", "title": "Id", "description": "Provider-side resource ID; pass it back to select or sync" }, "name": { "type": "string", "title": "Name", "description": "Display name" }, "kind": { "type": "string", "enum": [ "label", "folder", "file", "channel", "private_channel", "direct_message", "group_message" ], "title": "Kind", "description": "What kind of resource this is" }, "is_selected": { "type": "boolean", "title": "Is Selected", "description": "Whether the resource is selected for ingestion", "default": false }, "parent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Id", "description": "Containing resource ID, for hierarchical providers" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url", "description": "Link to the resource on the provider, when available" }, "message_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Message Count", "description": "Approximate number of messages in the resource, when known" }, "member_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Member Count", "description": "Approximate number of members, when known" }, "sync": { "anyOf": [ { "$ref": "#/components/schemas/ConnectorResourceSync" }, { "type": "null" } ], "description": "Per-resource sync state, when tracked" } }, "type": "object", "required": [ "id", "name", "kind" ], "title": "ConnectorResource", "description": "One syncable unit of a connected account." }, "ConnectorResourceSync": { "properties": { "status": { "type": "string", "enum": [ "not_syncing", "syncing", "partial", "error" ], "title": "Status", "description": "Whether the resource is syncing; partial means only some of a folder's contents are" }, "last_synced_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Synced At", "description": "Last successful sync time" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Last sync error, if the resource is in an error state" }, "last_run": { "anyOf": [ { "$ref": "#/components/schemas/ConnectorSyncRun" }, { "type": "null" } ], "description": "The last sync job on this resource, when one has run" } }, "type": "object", "required": [ "status" ], "title": "ConnectorResourceSync", "description": "Sync state of one resource, for providers that track it per resource." }, "ConnectorSyncRun": { "properties": { "status": { "type": "string", "enum": [ "in_progress", "completed", "failed", "stale" ], "title": "Status", "description": "Job outcome; `stale` is a job that reported starting but nothing since for hours" }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Started At", "description": "When the job started" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Completed At", "description": "When the job finished or failed" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Why the job failed" } }, "type": "object", "required": [ "status" ], "title": "ConnectorSyncRun", "description": "The last sync job on a resource, as that job recorded it when it started, finished, or failed." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` cURL: ```bash curl https://api.mixedbread.com/v1/integrations/installations/7b3d5f1a-9c2e-4a8b-b6d4-1e0f3c5a7d92/resources/failed \ -H 'Authorization: Bearer YOUR_API_KEY' ``` # List Installations URL: https://www.mixedbread.com/api-reference/endpoints/integrations/list-installations List every account connected through Gmail, Google Drive, Slack, or Granola, with the store each feeds. ```json { "paths": { "/v1/integrations/installations": { "get": { "tags": [ "integrations" ], "summary": "List Installations", "description": "Each entry has the same shape as [Get Installation](#operation/get_integration_installation).", "operationId": "list_integration_installations", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Maximum number of items to return per page (1-100)", "examples": [ 10, 20, 50 ], "default": 20, "title": "Limit" }, "description": "Maximum number of items to return per page (1-100)" }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for forward pagination - get items after this position. Use last_cursor from previous response.", "examples": [ "eyJjcmVhdGVkX2F0IjoiMjAyNC0xMi0zMVQyMzo1OTo1OS4wMDBaIiwiaWQiOiJhYmMxMjMifQ==" ], "title": "After" }, "description": "Cursor for forward pagination - get items after this position. Use last_cursor from previous response." }, { "name": "before", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for backward pagination - get items before this position. Use first_cursor from previous response.", "examples": [ "eyJjcmVhdGVkX2F0IjoiMjAyNC0xMi0zMVQyMzo1OTo1OS4wMDBaIiwiaWQiOiJhYmMxMjMifQ==" ], "title": "Before" }, "description": "Cursor for backward pagination - get items before this position. Use first_cursor from previous response." }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Whether to include total count in response (expensive operation)", "examples": [ false, true ], "default": false, "title": "Include Total" }, "description": "Whether to include total count in response (expensive operation)" }, { "name": "provider", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "google_drive", "gmail", "slack", "granola" ], "type": "string" }, { "type": "null" } ], "description": "Only accounts connected through this connector", "title": "Provider" }, "description": "Only accounts connected through this connector" } ], "responses": { "200": { "description": "Connected accounts across connectors, newest first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorInstallationListResponse" }, "example": { "data": [ { "installation_id": "2f1c9a8e-6b4d-4e3a-9c1f-7d8e5b6a4c21", "provider": "gmail", "status": "active", "account": { "id": "olivia@example.com", "name": "olivia@example.com", "email": "olivia@example.com", "workspace": null }, "store_id": "5d3e7f9a-1b2c-4d6e-8f0a-9c8b7a6d5e4f", "store_name": "mail-olivia", "sync": { "failed_resource_count": 0, "last_error": null, "last_error_operation": null, "last_error_at": null } }, { "installation_id": "8a1d2c3b-4e5f-4a6b-9c7d-0e1f2a3b4c5d", "provider": "gmail", "status": "needs_reauth", "account": { "id": "sam@example.com", "name": "sam@example.com", "email": "sam@example.com", "workspace": null }, "store_id": "9b8a7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "store_name": "mail-sam", "sync": { "failed_resource_count": 0, "last_error": "Google refused the refresh token: consent must be granted again", "last_error_operation": "gmail.history", "last_error_at": "2026-09-06T08:12:41.201000+00:00" } } ], "pagination": { "has_more": false, "first_cursor": "eyJpZCI6…", "last_cursor": "eyJpZCI6…", "total": null } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "ConnectorInstallationListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ConnectorInstallation" }, "type": "array", "title": "Data", "description": "Connected accounts, newest first" }, "pagination": { "$ref": "#/components/schemas/CursorPaginationResponse", "description": "Pagination information" } }, "type": "object", "required": [ "data", "pagination" ], "title": "ConnectorInstallationListResponse", "description": "One page of connected accounts." }, "ConnectorInstallation": { "properties": { "installation_id": { "type": "string", "title": "Installation Id", "description": "Installation ID" }, "provider": { "type": "string", "enum": [ "google_drive", "gmail", "slack", "granola" ], "title": "Provider", "description": "Connector provider" }, "status": { "type": "string", "title": "Status", "description": "Installation status" }, "account": { "$ref": "#/components/schemas/ConnectorAccount", "description": "The authorized third-party account" }, "store_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Store Id", "description": "Store the installation ingests into" }, "store_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Store Name", "description": "Name of that store" }, "sync": { "$ref": "#/components/schemas/ConnectorInstallationSync", "description": "Account-level sync facts recorded by the sync jobs" } }, "type": "object", "required": [ "installation_id", "provider", "status", "account" ], "title": "ConnectorInstallation", "description": "A connected account and the store it feeds, described the same way for every connector." }, "ConnectorAccount": { "properties": { "id": { "type": "string", "title": "Id", "description": "Provider-side account identifier (email, user ID, or team ID)" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Human-readable account name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email", "description": "Account email, when the provider exposes one" }, "workspace": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace", "description": "Workspace or organization the account belongs to, for providers that have one" } }, "type": "object", "required": [ "id" ], "title": "ConnectorAccount", "description": "The third-party account an installation is authorized as." }, "ConnectorInstallationSync": { "properties": { "failed_resource_count": { "type": "integer", "title": "Failed Resource Count", "description": "Resources whose last sync job failed", "default": 0 }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Error", "description": "Last failure of a job covering the whole account, such as a changes sync" }, "last_error_operation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Error Operation", "description": "Which account-wide job failed" }, "last_error_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Error At", "description": "When it failed" } }, "type": "object", "title": "ConnectorInstallationSync", "description": "Account-level sync facts: how many resources are in error, and the last failure of an account-wide job." }, "CursorPaginationResponse": { "properties": { "has_more": { "type": "boolean", "title": "Has More", "description": "Contextual direction-aware flag: True if more items exist in the requested pagination direction. For 'after': more items after this page. For 'before': more items before this page.", "examples": [ true, false ] }, "first_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Cursor", "description": "Cursor of the first item in this page. Use for backward pagination. None if page is empty.", "examples": [ "eyJjcmVhdGVkX2F0IjoiMjAyNC0xMi0zMVQyMzo1OTo1OS4wMDBaIiwiaWQiOiJhYmMxMjMifQ==", null ] }, "last_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Cursor", "description": "Cursor of the last item in this page. Use for forward pagination. None if page is empty.", "examples": [ "eyJjcmVhdGVkX2F0IjoiMjAyNC0xMi0zMFQyMzo1OTo1OS4wMDBaIiwiaWQiOiJ4eXo3ODkifQ==", null ] }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total", "description": "Total number of items available across all pages. Only included when include_total=true was requested. Expensive operation - use sparingly.", "examples": [ 42, 0, null ] } }, "type": "object", "required": [ "has_more", "first_cursor", "last_cursor" ], "title": "CursorPaginationResponse", "description": "Response model for cursor-based pagination." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` cURL: ```bash curl 'https://api.mixedbread.com/v1/integrations/installations?limit=20&provider=gmail' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` # List OAuth Client Connections URL: https://www.mixedbread.com/api-reference/endpoints/integrations/list-oauth-client-connections List the accounts that connected through the organization's own OAuth client for a connector, newest first. ```json { "paths": { "/v1/integrations/oauth-clients/{provider}/connections": { "get": { "tags": [ "integrations" ], "summary": "List OAuth Client Connections", "description": "Empty when no client is registered for the connector. Connections made through the Mixedbread\nclient are not included.", "operationId": "list_oauth_client_connections", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "enum": [ "google_drive", "gmail", "slack" ], "type": "string", "description": "The connector to inspect", "title": "Provider" }, "description": "The connector to inspect" } ], "responses": { "200": { "description": "Connections authorized through the customer-owned client, newest first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthClientConnectionListResponse" }, "example": { "data": [ { "installation_id": "2f1c9a8e-6b4d-4e3a-9c1f-7d8e5b6a4c21", "provider": "gmail", "status": "active", "account": { "id": "olivia@example.com", "name": "olivia@example.com", "email": "olivia@example.com", "workspace": null }, "store_id": "5d3e7f9a-1b2c-4d6e-8f0a-9c8b7a6d5e4f", "store_name": "mail-olivia", "sync": { "failed_resource_count": 0, "last_error": null, "last_error_operation": null, "last_error_at": null }, "installed_by_user_id": null, "connected_at": "2026-09-05T17:25:12.338038+00:00", "updated_at": "2026-09-05T17:25:12.338038+00:00" } ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "OAuthClientConnectionListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/OAuthClientConnection" }, "type": "array", "title": "Data", "description": "Connections authorized through the customer-owned client, newest first" } }, "type": "object", "required": [ "data" ], "title": "OAuthClientConnectionListResponse", "description": "The connections authorized through the organization's own Google OAuth client for a connector." }, "OAuthClientConnection": { "properties": { "installation_id": { "type": "string", "title": "Installation Id", "description": "Installation ID" }, "provider": { "type": "string", "enum": [ "google_drive", "gmail", "slack" ], "title": "Provider", "description": "The connector the account is connected to" }, "status": { "type": "string", "title": "Status", "description": "Installation status" }, "account": { "$ref": "#/components/schemas/ConnectorAccount", "description": "The authorized third-party account" }, "store_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Store Id", "description": "Store the installation ingests into" }, "store_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Store Name", "description": "Name of that store" }, "sync": { "$ref": "#/components/schemas/ConnectorInstallationSync", "description": "Account-level sync facts recorded by the sync jobs" }, "installed_by_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Installed By User Id", "description": "The dashboard user who authorized the connection, or null when an API key did" }, "connected_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Connected At", "description": "When the connection was authorized" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated At", "description": "When the connection last changed" } }, "type": "object", "required": [ "installation_id", "provider", "status", "account" ], "title": "OAuthClientConnection", "description": "One connection authorized through an organization's own OAuth client.\n\nThis is the admin's view of \"who has connected through my app\": the account, who started the\nflow (``null`` for connections made by the organization's backend with an API key), and when.\nDisconnecting stays on the connector's own installation routes." }, "ConnectorAccount": { "properties": { "id": { "type": "string", "title": "Id", "description": "Provider-side account identifier (email, user ID, or team ID)" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Human-readable account name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email", "description": "Account email, when the provider exposes one" }, "workspace": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace", "description": "Workspace or organization the account belongs to, for providers that have one" } }, "type": "object", "required": [ "id" ], "title": "ConnectorAccount", "description": "The third-party account an installation is authorized as." }, "ConnectorInstallationSync": { "properties": { "failed_resource_count": { "type": "integer", "title": "Failed Resource Count", "description": "Resources whose last sync job failed", "default": 0 }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Error", "description": "Last failure of a job covering the whole account, such as a changes sync" }, "last_error_operation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Error Operation", "description": "Which account-wide job failed" }, "last_error_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Error At", "description": "When it failed" } }, "type": "object", "title": "ConnectorInstallationSync", "description": "Account-level sync facts: how many resources are in error, and the last failure of an account-wide job." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` cURL: ```bash curl https://api.mixedbread.com/v1/integrations/oauth-clients/gmail/connections \ -H 'Authorization: Bearer YOUR_API_KEY' ``` # List OAuth Clients URL: https://www.mixedbread.com/api-reference/endpoints/integrations/list-oauth-clients List each connector slot and the OAuth client registered for it, if any. ```json { "paths": { "/v1/integrations/oauth-clients": { "get": { "tags": [ "integrations" ], "summary": "List OAuth Clients", "operationId": "list_oauth_clients", "responses": { "200": { "description": "One slot per connector, with its registered client if any", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthClientSlotListResponse" }, "example": { "data": [ { "provider": "gmail", "redirect_uri": "https://api.mixedbread.com/v1/integrations/gmail/oauth/callback", "required_scopes": [ "https://www.googleapis.com/auth/gmail.readonly" ], "app_manifest": null, "client": { "provider": "gmail", "client_id": "123456789012-abcdefghijklmnop.apps.googleusercontent.com", "redirect_uri": "https://api.mixedbread.com/v1/integrations/gmail/oauth/callback", "return_url": "https://platform.example.com/connected", "has_signing_secret": false, "created_by_user_id": "da5f646d-4827-49a5-92cc-2f16a6594c27", "created_at": "2026-09-05T17:25:12.338038+00:00", "updated_at": "2026-09-05T17:25:12.338038+00:00" } }, { "provider": "google_drive", "redirect_uri": "https://api.mixedbread.com/v1/integrations/google_drive/oauth/callback", "required_scopes": [ "https://www.googleapis.com/auth/drive.readonly" ], "app_manifest": null, "client": null }, { "provider": "slack", "redirect_uri": "https://api.mixedbread.com/v1/integrations/slack/oauth/callback", "required_scopes": [ "users:read", "users:read.email", "channels:history", "channels:read", "files:read", "groups:history", "groups:read", "im:history", "im:read", "mpim:history", "mpim:read", "users:read" ], "app_manifest": "{ ... }", "client": { "provider": "slack", "client_id": "1234567890.1234567890", "redirect_uri": "https://api.mixedbread.com/v1/integrations/slack/oauth/callback", "return_url": "https://platform.example.com/connected", "has_signing_secret": true, "created_by_user_id": "da5f646d-4827-49a5-92cc-2f16a6594c27", "created_at": "2026-09-05T17:25:12.338038+00:00", "updated_at": "2026-09-05T17:25:12.338038+00:00" } } ] } } } } }, "security": [ { "ApiKeyAuth": [] } ] } } }, "components": { "schemas": { "OAuthClientSlotListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/OAuthClientSlot" }, "type": "array", "title": "Data", "description": "One slot per Google connector" } }, "type": "object", "required": [ "data" ], "title": "OAuthClientSlotListResponse", "description": "The Google connector slots and the customer-owned OAuth client registered for each." }, "OAuthClientSlot": { "properties": { "provider": { "type": "string", "enum": [ "google_drive", "gmail", "slack" ], "title": "Provider", "description": "The connector this slot is for" }, "redirect_uri": { "type": "string", "title": "Redirect Uri", "description": "The redirect URI that must be authorized on the customer's OAuth client" }, "required_scopes": { "items": { "type": "string" }, "type": "array", "title": "Required Scopes", "description": "Scopes the customer's OAuth client must grant" }, "app_manifest": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "App Manifest", "description": "A JSON app manifest to create the customer's app from, for connectors that have one" }, "client": { "anyOf": [ { "$ref": "#/components/schemas/OAuthClientView" }, { "type": "null" } ], "description": "The registered client, or null when the connector uses the Mixedbread client" } }, "type": "object", "required": [ "provider", "redirect_uri", "required_scopes" ], "title": "OAuthClientSlot", "description": "One connector's bring-your-own-client slot, registered or not." }, "OAuthClientView": { "properties": { "provider": { "type": "string", "enum": [ "google_drive", "gmail", "slack" ], "title": "Provider", "description": "The connector this client is used for" }, "client_id": { "type": "string", "title": "Client Id", "description": "The customer's OAuth client id" }, "redirect_uri": { "type": "string", "title": "Redirect Uri", "description": "The redirect URI that must be authorized on the customer's OAuth client" }, "return_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Return Url", "description": "Where the OAuth callback returns the user after consent, if the organization set one" }, "has_signing_secret": { "type": "boolean", "title": "Has Signing Secret", "description": "Whether a webhook signing secret is stored for the client (Slack only)", "default": false }, "created_by_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created By User Id", "description": "The user who registered the client" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At", "description": "When the client was first registered" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated At", "description": "When the client was last rotated" } }, "type": "object", "required": [ "provider", "client_id", "redirect_uri" ], "title": "OAuthClientView", "description": "An organization's registered OAuth client as exposed to the dashboard.\n\nSecrets are never part of this shape: once stored they are only ever decrypted inside a token\nexchange or a webhook signature check. A client id is public by construction (it appears in the\nconsent URL), so it is returned in full to let the customer confirm which app is wired up." } } } } ``` cURL: ```bash curl https://api.mixedbread.com/v1/integrations/oauth-clients \ -H 'Authorization: Bearer YOUR_API_KEY' ``` # List Resources URL: https://www.mixedbread.com/api-reference/endpoints/integrations/list-resources List what the account can sync (labels, folders and files, conversations, or notes) and what is selected. ```json { "paths": { "/v1/integrations/installations/{installation_id}/resources": { "get": { "tags": [ "integrations" ], "summary": "List Resources", "operationId": "list_integration_installation_resources", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "installation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Installation ID, as returned when the account connected", "title": "Installation Id" }, "description": "Installation ID, as returned when the account connected" }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination cursor from a previous page", "title": "Cursor" }, "description": "Pagination cursor from a previous page" }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "description": "Resources per page, for providers that paginate", "title": "Limit" }, "description": "Resources per page, for providers that paginate" }, { "name": "query", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "description": "Filter resources by name, where supported", "title": "Query" }, "description": "Filter resources by name, where supported" }, { "name": "parent_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Container to list, for hierarchical providers such as Google Drive or Granola", "title": "Parent Id" }, "description": "Container to list, for hierarchical providers such as Google Drive or Granola" } ], "responses": { "200": { "description": "Resources with their selection state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorResourceSelectionResponse" }, "example": { "data": { "installation_id": "2f1c9a8e-6b4d-4e3a-9c1f-7d8e5b6a4c21", "provider": "gmail", "status": "active", "account": { "id": "olivia@example.com", "name": "olivia@example.com", "email": "olivia@example.com", "workspace": null }, "store_id": "5d3e7f9a-1b2c-4d6e-8f0a-9c8b7a6d5e4f", "store_name": "mail-olivia", "sync": { "failed_resource_count": 0, "last_error": null, "last_error_operation": null, "last_error_at": null }, "resources": [ { "id": "INBOX", "name": "INBOX", "kind": "label", "is_selected": false, "parent_id": null, "url": null, "message_count": null, "member_count": null, "sync": null }, { "id": "Label_12", "name": "Customers", "kind": "label", "is_selected": false, "parent_id": null, "url": null, "message_count": null, "member_count": null, "sync": null } ], "aliases": [ { "id": "all_mail", "name": "All mail", "kind": "label", "is_selected": true } ], "selected_resource_ids": [], "selected_resource_aliases": [ "all_mail" ], "parent_id": null, "next_cursor": null, "total": null, "listing_status": "ready", "sync_all": true } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "ConnectorResourceSelectionResponse": { "properties": { "data": { "$ref": "#/components/schemas/ConnectorResourceSelection", "description": "Resources with their selection state" } }, "type": "object", "required": [ "data" ], "title": "ConnectorResourceSelectionResponse", "description": "Response containing one page of an installation's resources." }, "ConnectorResourceSelection": { "properties": { "installation_id": { "type": "string", "title": "Installation Id", "description": "Installation ID" }, "provider": { "type": "string", "enum": [ "google_drive", "gmail", "slack", "granola" ], "title": "Provider", "description": "Connector provider" }, "status": { "type": "string", "title": "Status", "description": "Installation status" }, "account": { "$ref": "#/components/schemas/ConnectorAccount", "description": "The authorized third-party account" }, "store_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Store Id", "description": "Store the installation ingests into" }, "store_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Store Name", "description": "Name of that store" }, "sync": { "$ref": "#/components/schemas/ConnectorInstallationSync", "description": "Account-level sync facts recorded by the sync jobs" }, "resources": { "items": { "$ref": "#/components/schemas/ConnectorResource" }, "type": "array", "title": "Resources", "description": "Resources on this page" }, "aliases": { "items": { "$ref": "#/components/schemas/ConnectorResourceAlias" }, "type": "array", "title": "Aliases", "description": "Every alias this installation can select, with whether it is selected" }, "selected_resource_ids": { "items": { "type": "string" }, "type": "array", "title": "Selected Resource Ids", "description": "Every selected resource ID for the installation, across all pages. A Gmail or Granola alias also appears here by its provider ID (`__gmail_all_mail__`, `__granola_all_notes__`), so a selection read from this field can be saved back as `resource_ids` unchanged." }, "selected_resource_aliases": { "items": { "type": "string", "enum": [ "all_mail", "all_notes", "public_channels", "private_channels", "direct_messages", "group_messages" ] }, "type": "array", "title": "Selected Resource Aliases", "description": "Every selected alias for the installation" }, "parent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Id", "description": "The container being listed, for hierarchical providers; null at the root" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Cursor for the next page, or null on the last page" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total", "description": "Total matching resources across pages, when known" }, "listing_status": { "type": "string", "enum": [ "ready", "loading", "failed" ], "title": "Listing Status", "description": "Whether the listing is complete; `loading` while a provider catalog is still being built", "default": "ready" }, "sync_all": { "type": "boolean", "title": "Sync All", "description": "Whether the installation syncs everything the account can see, new resources included: every alias it offers is selected", "default": false } }, "type": "object", "required": [ "installation_id", "provider", "status", "account", "resources" ], "title": "ConnectorResourceSelection", "description": "One page of an installation's resources with their selection state." }, "ConnectorAccount": { "properties": { "id": { "type": "string", "title": "Id", "description": "Provider-side account identifier (email, user ID, or team ID)" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Human-readable account name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email", "description": "Account email, when the provider exposes one" }, "workspace": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace", "description": "Workspace or organization the account belongs to, for providers that have one" } }, "type": "object", "required": [ "id" ], "title": "ConnectorAccount", "description": "The third-party account an installation is authorized as." }, "ConnectorInstallationSync": { "properties": { "failed_resource_count": { "type": "integer", "title": "Failed Resource Count", "description": "Resources whose last sync job failed", "default": 0 }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Error", "description": "Last failure of a job covering the whole account, such as a changes sync" }, "last_error_operation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Error Operation", "description": "Which account-wide job failed" }, "last_error_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Error At", "description": "When it failed" } }, "type": "object", "title": "ConnectorInstallationSync", "description": "Account-level sync facts: how many resources are in error, and the last failure of an account-wide job." }, "ConnectorResource": { "properties": { "id": { "type": "string", "title": "Id", "description": "Provider-side resource ID; pass it back to select or sync" }, "name": { "type": "string", "title": "Name", "description": "Display name" }, "kind": { "type": "string", "enum": [ "label", "folder", "file", "channel", "private_channel", "direct_message", "group_message" ], "title": "Kind", "description": "What kind of resource this is" }, "is_selected": { "type": "boolean", "title": "Is Selected", "description": "Whether the resource is selected for ingestion", "default": false }, "parent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Id", "description": "Containing resource ID, for hierarchical providers" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url", "description": "Link to the resource on the provider, when available" }, "message_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Message Count", "description": "Approximate number of messages in the resource, when known" }, "member_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Member Count", "description": "Approximate number of members, when known" }, "sync": { "anyOf": [ { "$ref": "#/components/schemas/ConnectorResourceSync" }, { "type": "null" } ], "description": "Per-resource sync state, when tracked" } }, "type": "object", "required": [ "id", "name", "kind" ], "title": "ConnectorResource", "description": "One syncable unit of a connected account." }, "ConnectorResourceSync": { "properties": { "status": { "type": "string", "enum": [ "not_syncing", "syncing", "partial", "error" ], "title": "Status", "description": "Whether the resource is syncing; partial means only some of a folder's contents are" }, "last_synced_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Synced At", "description": "Last successful sync time" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Last sync error, if the resource is in an error state" }, "last_run": { "anyOf": [ { "$ref": "#/components/schemas/ConnectorSyncRun" }, { "type": "null" } ], "description": "The last sync job on this resource, when one has run" } }, "type": "object", "required": [ "status" ], "title": "ConnectorResourceSync", "description": "Sync state of one resource, for providers that track it per resource." }, "ConnectorSyncRun": { "properties": { "status": { "type": "string", "enum": [ "in_progress", "completed", "failed", "stale" ], "title": "Status", "description": "Job outcome; `stale` is a job that reported starting but nothing since for hours" }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Started At", "description": "When the job started" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Completed At", "description": "When the job finished or failed" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Why the job failed" } }, "type": "object", "required": [ "status" ], "title": "ConnectorSyncRun", "description": "The last sync job on a resource, as that job recorded it when it started, finished, or failed." }, "ConnectorResourceAlias": { "properties": { "id": { "type": "string", "enum": [ "all_mail", "all_notes", "public_channels", "private_channels", "direct_messages", "group_messages" ], "title": "Id", "description": "Alias ID; pass it back in `resource_aliases`" }, "name": { "type": "string", "title": "Name", "description": "Display name" }, "kind": { "type": "string", "enum": [ "label", "folder", "file", "channel", "private_channel", "direct_message", "group_message" ], "title": "Kind", "description": "The kind of resource the alias covers" }, "is_selected": { "type": "boolean", "title": "Is Selected", "description": "Whether the alias is selected for ingestion", "default": false } }, "type": "object", "required": [ "id", "name", "kind" ], "title": "ConnectorResourceAlias", "description": "A whole kind of resource selected at once, new resources included.\n\nAliases are not resources: they never page, match a search, or carry a sync run. Gmail offers\n`all_mail`, Granola `all_notes`, and Slack one per conversation kind; Google Drive offers none." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` cURL: ```bash curl 'https://api.mixedbread.com/v1/integrations/installations/2f1c9a8e-6b4d-4e3a-9c1f-7d8e5b6a4c21/resources?limit=50' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` # Reconnect Gmail URL: https://www.mixedbread.com/api-reference/endpoints/integrations/reconnect-gmail Start Gmail OAuth that refreshes one installation's credentials, keeping its store. ```json { "paths": { "/v1/integrations/gmail/installations/{installation_id}/oauth/authorize": { "get": { "tags": [ "integrations" ], "summary": "Reconnect Gmail", "description": "The person must sign in with the Google account already connected to the installation; the return\nURL otherwise reports `error=reconnect_account_mismatch`.", "operationId": "reconnect_gmail_installation", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "installation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Gmail installation ID", "title": "Installation Id" }, "description": "Gmail installation ID" }, { "name": "reference", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "description": "Opaque value echoed back as `reference` on the return URL, so your app can match the outcome to the user who started the flow", "title": "Reference" }, "description": "Opaque value echoed back as `reference` on the return URL, so your app can match the outcome to the user who started the flow" } ], "responses": { "307": { "description": "Redirect to Google OAuth", "content": { "application/json": { "schema": {} } } }, "404": { "description": "No installation of this provider with this id in the organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } } }, "422": { "description": "The request failed validation, or the credentials it carries were rejected or belong to a different account than the installation's", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } } } } } } }, "components": { "schemas": { "APIErrorResponse": { "properties": { "type": { "type": "string", "title": "Type" }, "code": { "anyOf": [ { "$ref": "#/components/schemas/ErrorCode" }, { "type": "null" } ] }, "message": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Message" } }, "type": "object", "required": [ "type", "code", "message" ], "title": "APIErrorResponse", "description": "JSON-compatible API error response." }, "ErrorCode": { "type": "string", "enum": [ "internal_error", "validation_error", "service_unavailable_error", "not_found_error", "conflict_error", "permission_denied_error", "payment_required_error", "rate_limit_error", "usage_quota_error", "spend_limit_exceeded_error", "credits_depleted_error", "invoice_overdue_error", "unprocessable_entity_error", "context_length_exceeded_error", "bad_request_error", "auth_error", "unsupported_file_error", "invalid_cursor_error", "auth_credentials_not_provided_error", "auth_credentials_invalid_error", "auth_credentials_expired_error", "permission_user_required_error", "permission_admin_required_error", "permission_read_required_error", "permission_write_required_error", "permission_delete_required_error", "permission_list_required_error", "permission_create_required_error", "permission_search_required_error", "organization_not_found_error", "api_key_not_found_error", "api_key_invalid_error", "api_key_expired_error", "jwt_invalid_error", "file_not_found_error", "file_invalid_error", "store_not_found_error", "store_already_exists_error", "store_expired_error", "store_filter_invalid_error", "store_chunk_invalid_error", "store_chunk_not_found_error", "store_name_already_exists_error", "store_conflicting_search_rules_error", "store_search_rule_not_found_error", "store_unsupported_search_option_error", "store_incompatible_error", "store_public_disabled_error", "store_lsf_not_enabled_error", "store_in_use_by_data_source_error", "store_frozen_error", "store_file_not_found_error", "store_file_already_exists_error", "store_file_invalid_chunk_indices_error", "store_file_bucket_mismatch_error", "bucket_not_found_error", "bucket_validation_failed_error", "bucket_in_use_error", "bucket_invalid_error", "bucket_already_exists_error", "bucket_propagation_failed_error", "bucket_feature_not_enabled_error", "bucket_unavailable_error", "trace_destination_not_found_error", "trace_destination_invalid_error", "trace_destination_unreachable_error", "trace_destination_already_exists_error", "parsing_job_not_found_error", "parsing_job_not_in_progress_error", "extraction_job_not_found_error", "extraction_job_not_in_progress_error", "model_not_found_error", "model_input_invalid_error", "data_source_feature_not_enabled_error", "data_source_not_found_error", "data_source_unsupported_error", "data_source_auth_type_not_supported_error", "data_source_type_can_not_be_changed_error", "data_source_connector_not_found_error", "invalid_state_error", "oauth2_token_exchange_failed_error", "data_source_connector_synced_file_not_found_error", "multipart_upload_not_available_error", "multipart_upload_not_found_error", "multipart_upload_part_too_small_error", "multipart_upload_missing_parts_error", "file_processing_error", "file_corrupted_error", "file_too_large_error", "file_empty_error", "file_password_protected_error" ], "title": "ErrorCode", "description": "Error codes for API responses.\n\nThese codes provide fine-grained error information to API users beyond HTTP status codes.\nOnly add error codes for situations where users need to know specific details about what went wrong.\nFor internal error handling that doesn't need to be exposed to users, use error types without codes.\n\nNaming convention:\n- Enum names use format: RESOURCE_STATE or RESOURCE_ACTION_RESULT (e.g., FILE_NOT_FOUND, AUTH_CREDENTIALS_EXPIRED)\n- String values use snake_case format: \"resource_specific_reason_error\" (e.g., \"file_not_found_error\")\n\nTODO @rui: Register these codes in the OpenAPI specification for each endpoint\nto provide better documentation and client-side error handling capabilities." } } } } ``` cURL: ```bash curl -s -o /dev/null -w '%{redirect_url}' \ 'https://api.mixedbread.com/v1/integrations/gmail/installations/2f1c9a8e-6b4d-4e3a-9c1f-7d8e5b6a4c21/oauth/authorize?reference=user-42' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` Redirects: ```bash # Location header of the 307: send the browser here https://accounts.google.com/o/oauth2/v2/auth?client_id=…&redirect_uri=…&scope=…&access_type=offline&state=… # Return URL after consent https://platform.example.com/connected?provider=gmail&status=connected&installation_id=2f1c9a8e-6b4d-4e3a-9c1f-7d8e5b6a4c21&reference=user-42 # Return URL when consent was given for a different account https://platform.example.com/connected?provider=gmail&status=error&error=reconnect_account_mismatch&reference=user-42 ``` # Reconnect Google Drive URL: https://www.mixedbread.com/api-reference/endpoints/integrations/reconnect-google-drive Start Google Drive OAuth that refreshes one installation's credentials, keeping its store. ```json { "paths": { "/v1/integrations/google_drive/installations/{installation_id}/oauth/authorize": { "get": { "tags": [ "integrations" ], "summary": "Reconnect Google Drive", "description": "The person must sign in with the Google account already connected to the installation; the return\nURL otherwise reports `error=reconnect_account_mismatch`.", "operationId": "reconnect_google_drive_installation", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "installation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Google Drive installation ID", "title": "Installation Id" }, "description": "Google Drive installation ID" }, { "name": "reference", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "description": "Opaque value echoed back as `reference` on the return URL, so your app can match the outcome to the user who started the flow", "title": "Reference" }, "description": "Opaque value echoed back as `reference` on the return URL, so your app can match the outcome to the user who started the flow" } ], "responses": { "307": { "description": "Redirect to Google OAuth", "content": { "application/json": { "schema": {} } } }, "404": { "description": "No installation of this provider with this id in the organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } } }, "422": { "description": "The request failed validation, or the credentials it carries were rejected or belong to a different account than the installation's", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } } } } } } }, "components": { "schemas": { "APIErrorResponse": { "properties": { "type": { "type": "string", "title": "Type" }, "code": { "anyOf": [ { "$ref": "#/components/schemas/ErrorCode" }, { "type": "null" } ] }, "message": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Message" } }, "type": "object", "required": [ "type", "code", "message" ], "title": "APIErrorResponse", "description": "JSON-compatible API error response." }, "ErrorCode": { "type": "string", "enum": [ "internal_error", "validation_error", "service_unavailable_error", "not_found_error", "conflict_error", "permission_denied_error", "payment_required_error", "rate_limit_error", "usage_quota_error", "spend_limit_exceeded_error", "credits_depleted_error", "invoice_overdue_error", "unprocessable_entity_error", "context_length_exceeded_error", "bad_request_error", "auth_error", "unsupported_file_error", "invalid_cursor_error", "auth_credentials_not_provided_error", "auth_credentials_invalid_error", "auth_credentials_expired_error", "permission_user_required_error", "permission_admin_required_error", "permission_read_required_error", "permission_write_required_error", "permission_delete_required_error", "permission_list_required_error", "permission_create_required_error", "permission_search_required_error", "organization_not_found_error", "api_key_not_found_error", "api_key_invalid_error", "api_key_expired_error", "jwt_invalid_error", "file_not_found_error", "file_invalid_error", "store_not_found_error", "store_already_exists_error", "store_expired_error", "store_filter_invalid_error", "store_chunk_invalid_error", "store_chunk_not_found_error", "store_name_already_exists_error", "store_conflicting_search_rules_error", "store_search_rule_not_found_error", "store_unsupported_search_option_error", "store_incompatible_error", "store_public_disabled_error", "store_lsf_not_enabled_error", "store_in_use_by_data_source_error", "store_frozen_error", "store_file_not_found_error", "store_file_already_exists_error", "store_file_invalid_chunk_indices_error", "store_file_bucket_mismatch_error", "bucket_not_found_error", "bucket_validation_failed_error", "bucket_in_use_error", "bucket_invalid_error", "bucket_already_exists_error", "bucket_propagation_failed_error", "bucket_feature_not_enabled_error", "bucket_unavailable_error", "trace_destination_not_found_error", "trace_destination_invalid_error", "trace_destination_unreachable_error", "trace_destination_already_exists_error", "parsing_job_not_found_error", "parsing_job_not_in_progress_error", "extraction_job_not_found_error", "extraction_job_not_in_progress_error", "model_not_found_error", "model_input_invalid_error", "data_source_feature_not_enabled_error", "data_source_not_found_error", "data_source_unsupported_error", "data_source_auth_type_not_supported_error", "data_source_type_can_not_be_changed_error", "data_source_connector_not_found_error", "invalid_state_error", "oauth2_token_exchange_failed_error", "data_source_connector_synced_file_not_found_error", "multipart_upload_not_available_error", "multipart_upload_not_found_error", "multipart_upload_part_too_small_error", "multipart_upload_missing_parts_error", "file_processing_error", "file_corrupted_error", "file_too_large_error", "file_empty_error", "file_password_protected_error" ], "title": "ErrorCode", "description": "Error codes for API responses.\n\nThese codes provide fine-grained error information to API users beyond HTTP status codes.\nOnly add error codes for situations where users need to know specific details about what went wrong.\nFor internal error handling that doesn't need to be exposed to users, use error types without codes.\n\nNaming convention:\n- Enum names use format: RESOURCE_STATE or RESOURCE_ACTION_RESULT (e.g., FILE_NOT_FOUND, AUTH_CREDENTIALS_EXPIRED)\n- String values use snake_case format: \"resource_specific_reason_error\" (e.g., \"file_not_found_error\")\n\nTODO @rui: Register these codes in the OpenAPI specification for each endpoint\nto provide better documentation and client-side error handling capabilities." } } } } ``` cURL: ```bash curl -s -o /dev/null -w '%{redirect_url}' \ 'https://api.mixedbread.com/v1/integrations/google_drive/installations/2f1c9a8e-6b4d-4e3a-9c1f-7d8e5b6a4c21/oauth/authorize?reference=user-42' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` Redirects: ```bash # Location header of the 307: send the browser here https://accounts.google.com/o/oauth2/v2/auth?client_id=…&redirect_uri=…&scope=…&access_type=offline&state=… # Return URL after consent https://platform.example.com/connected?provider=google_drive&status=connected&installation_id=2f1c9a8e-6b4d-4e3a-9c1f-7d8e5b6a4c21&reference=user-42 # Return URL when consent was given for a different account https://platform.example.com/connected?provider=google_drive&status=error&error=reconnect_account_mismatch&reference=user-42 ``` # Reconnect Slack URL: https://www.mixedbread.com/api-reference/endpoints/integrations/reconnect-slack Start Slack OAuth that refreshes one installation's credentials, keeping its store. ```json { "paths": { "/v1/integrations/slack/installations/{installation_id}/oauth/authorize": { "get": { "tags": [ "integrations" ], "summary": "Reconnect Slack", "description": "The person must authorize as the Slack user, or for a workspace bot the workspace, already connected\nto the installation; the return URL otherwise reports `error=reconnect_account_mismatch`.", "operationId": "reconnect_slack_installation", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "installation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Slack installation ID", "title": "Installation Id" }, "description": "Slack installation ID" }, { "name": "reference", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "description": "Opaque value echoed back as `reference` on the return URL, so your app can match the outcome to the user who started the flow", "title": "Reference" }, "description": "Opaque value echoed back as `reference` on the return URL, so your app can match the outcome to the user who started the flow" } ], "responses": { "307": { "description": "Redirect to Slack OAuth", "content": { "application/json": { "schema": {} } } }, "404": { "description": "No installation of this provider with this id in the organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } } }, "422": { "description": "The request failed validation, or the credentials it carries were rejected or belong to a different account than the installation's", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } } } } } } }, "components": { "schemas": { "APIErrorResponse": { "properties": { "type": { "type": "string", "title": "Type" }, "code": { "anyOf": [ { "$ref": "#/components/schemas/ErrorCode" }, { "type": "null" } ] }, "message": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Message" } }, "type": "object", "required": [ "type", "code", "message" ], "title": "APIErrorResponse", "description": "JSON-compatible API error response." }, "ErrorCode": { "type": "string", "enum": [ "internal_error", "validation_error", "service_unavailable_error", "not_found_error", "conflict_error", "permission_denied_error", "payment_required_error", "rate_limit_error", "usage_quota_error", "spend_limit_exceeded_error", "credits_depleted_error", "invoice_overdue_error", "unprocessable_entity_error", "context_length_exceeded_error", "bad_request_error", "auth_error", "unsupported_file_error", "invalid_cursor_error", "auth_credentials_not_provided_error", "auth_credentials_invalid_error", "auth_credentials_expired_error", "permission_user_required_error", "permission_admin_required_error", "permission_read_required_error", "permission_write_required_error", "permission_delete_required_error", "permission_list_required_error", "permission_create_required_error", "permission_search_required_error", "organization_not_found_error", "api_key_not_found_error", "api_key_invalid_error", "api_key_expired_error", "jwt_invalid_error", "file_not_found_error", "file_invalid_error", "store_not_found_error", "store_already_exists_error", "store_expired_error", "store_filter_invalid_error", "store_chunk_invalid_error", "store_chunk_not_found_error", "store_name_already_exists_error", "store_conflicting_search_rules_error", "store_search_rule_not_found_error", "store_unsupported_search_option_error", "store_incompatible_error", "store_public_disabled_error", "store_lsf_not_enabled_error", "store_in_use_by_data_source_error", "store_frozen_error", "store_file_not_found_error", "store_file_already_exists_error", "store_file_invalid_chunk_indices_error", "store_file_bucket_mismatch_error", "bucket_not_found_error", "bucket_validation_failed_error", "bucket_in_use_error", "bucket_invalid_error", "bucket_already_exists_error", "bucket_propagation_failed_error", "bucket_feature_not_enabled_error", "bucket_unavailable_error", "trace_destination_not_found_error", "trace_destination_invalid_error", "trace_destination_unreachable_error", "trace_destination_already_exists_error", "parsing_job_not_found_error", "parsing_job_not_in_progress_error", "extraction_job_not_found_error", "extraction_job_not_in_progress_error", "model_not_found_error", "model_input_invalid_error", "data_source_feature_not_enabled_error", "data_source_not_found_error", "data_source_unsupported_error", "data_source_auth_type_not_supported_error", "data_source_type_can_not_be_changed_error", "data_source_connector_not_found_error", "invalid_state_error", "oauth2_token_exchange_failed_error", "data_source_connector_synced_file_not_found_error", "multipart_upload_not_available_error", "multipart_upload_not_found_error", "multipart_upload_part_too_small_error", "multipart_upload_missing_parts_error", "file_processing_error", "file_corrupted_error", "file_too_large_error", "file_empty_error", "file_password_protected_error" ], "title": "ErrorCode", "description": "Error codes for API responses.\n\nThese codes provide fine-grained error information to API users beyond HTTP status codes.\nOnly add error codes for situations where users need to know specific details about what went wrong.\nFor internal error handling that doesn't need to be exposed to users, use error types without codes.\n\nNaming convention:\n- Enum names use format: RESOURCE_STATE or RESOURCE_ACTION_RESULT (e.g., FILE_NOT_FOUND, AUTH_CREDENTIALS_EXPIRED)\n- String values use snake_case format: \"resource_specific_reason_error\" (e.g., \"file_not_found_error\")\n\nTODO @rui: Register these codes in the OpenAPI specification for each endpoint\nto provide better documentation and client-side error handling capabilities." } } } } ``` cURL: ```bash curl -s -o /dev/null -w '%{redirect_url}' \ 'https://api.mixedbread.com/v1/integrations/slack/installations/2f1c9a8e-6b4d-4e3a-9c1f-7d8e5b6a4c21/oauth/authorize?reference=user-42' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` Redirects: ```bash # Location header of the 307: send the browser here https://slack.com/oauth/v2/authorize?client_id=…&user_scope=…&redirect_uri=…&state=… # Return URL after consent https://platform.example.com/connected?provider=slack&status=connected&installation_id=2f1c9a8e-6b4d-4e3a-9c1f-7d8e5b6a4c21&reference=user-42 # Return URL when consent was given for a different account https://platform.example.com/connected?provider=slack&status=error&error=reconnect_account_mismatch&reference=user-42 ``` # Refresh Resources URL: https://www.mixedbread.com/api-reference/endpoints/integrations/refresh-resources Rebuild the provider catalog where one is kept (Slack, Granola), then return the first page of resources. ```json { "paths": { "/v1/integrations/installations/{installation_id}/resources/refresh": { "post": { "tags": [ "integrations" ], "summary": "Refresh Resources", "operationId": "refresh_integration_installation_resources", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "installation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Installation ID, as returned when the account connected", "title": "Installation Id" }, "description": "Installation ID, as returned when the account connected" } ], "responses": { "200": { "description": "The first page of resources after the refresh started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorResourceSelectionResponse" }, "example": { "data": { "installation_id": "7b3d5f1a-9c2e-4a8b-b6d4-1e0f3c5a7d92", "provider": "slack", "status": "active", "account": { "id": "U0AE2TTTBPU", "name": "Olivia", "email": "olivia@example.com", "workspace": "Example Inc" }, "store_id": "c4a6e8f0-2b1d-4c3e-9a5f-7e6d5c4b3a21", "store_name": "slack-olivia", "sync": { "failed_resource_count": 1, "last_error": null, "last_error_operation": null, "last_error_at": null }, "resources": [ { "id": "C067DDX8J2X", "name": "general", "kind": "channel", "is_selected": true, "parent_id": null, "url": null, "message_count": null, "member_count": 42, "sync": { "status": "syncing", "last_synced_at": "2026-09-05T17:13:35.604283Z", "error": null, "last_run": { "status": "completed", "started_at": "2026-09-05T17:13:33.145422Z", "completed_at": "2026-09-05T17:13:35.635698Z", "error": null } } }, { "id": "D0ADMEQP5P1", "name": "Aamir", "kind": "direct_message", "is_selected": true, "parent_id": null, "url": null, "message_count": null, "member_count": null, "sync": { "status": "syncing", "last_synced_at": "2026-09-05T17:13:37.073422Z", "error": null, "last_run": { "status": "completed", "started_at": "2026-09-05T17:13:35.750981Z", "completed_at": "2026-09-05T17:13:37.105403Z", "error": null } } }, { "id": "C0B6S6XJJN4", "name": "ext-partners", "kind": "channel", "is_selected": false, "parent_id": null, "url": null, "message_count": null, "member_count": 7, "sync": { "status": "not_syncing", "last_synced_at": null, "error": null, "last_run": null } } ], "aliases": [ { "id": "public_channels", "name": "Public channels", "kind": "channel", "is_selected": true }, { "id": "private_channels", "name": "Private channels", "kind": "private_channel", "is_selected": true }, { "id": "direct_messages", "name": "Direct messages", "kind": "direct_message", "is_selected": true }, { "id": "group_messages", "name": "Group messages", "kind": "group_message", "is_selected": true } ], "selected_resource_ids": [ "C067DDX8J2X", "D0ADMEQP5P1" ], "selected_resource_aliases": [ "public_channels", "private_channels", "direct_messages", "group_messages" ], "parent_id": null, "next_cursor": "3", "total": 162, "listing_status": "ready", "sync_all": true } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "ConnectorResourceSelectionResponse": { "properties": { "data": { "$ref": "#/components/schemas/ConnectorResourceSelection", "description": "Resources with their selection state" } }, "type": "object", "required": [ "data" ], "title": "ConnectorResourceSelectionResponse", "description": "Response containing one page of an installation's resources." }, "ConnectorResourceSelection": { "properties": { "installation_id": { "type": "string", "title": "Installation Id", "description": "Installation ID" }, "provider": { "type": "string", "enum": [ "google_drive", "gmail", "slack", "granola" ], "title": "Provider", "description": "Connector provider" }, "status": { "type": "string", "title": "Status", "description": "Installation status" }, "account": { "$ref": "#/components/schemas/ConnectorAccount", "description": "The authorized third-party account" }, "store_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Store Id", "description": "Store the installation ingests into" }, "store_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Store Name", "description": "Name of that store" }, "sync": { "$ref": "#/components/schemas/ConnectorInstallationSync", "description": "Account-level sync facts recorded by the sync jobs" }, "resources": { "items": { "$ref": "#/components/schemas/ConnectorResource" }, "type": "array", "title": "Resources", "description": "Resources on this page" }, "aliases": { "items": { "$ref": "#/components/schemas/ConnectorResourceAlias" }, "type": "array", "title": "Aliases", "description": "Every alias this installation can select, with whether it is selected" }, "selected_resource_ids": { "items": { "type": "string" }, "type": "array", "title": "Selected Resource Ids", "description": "Every selected resource ID for the installation, across all pages. A Gmail or Granola alias also appears here by its provider ID (`__gmail_all_mail__`, `__granola_all_notes__`), so a selection read from this field can be saved back as `resource_ids` unchanged." }, "selected_resource_aliases": { "items": { "type": "string", "enum": [ "all_mail", "all_notes", "public_channels", "private_channels", "direct_messages", "group_messages" ] }, "type": "array", "title": "Selected Resource Aliases", "description": "Every selected alias for the installation" }, "parent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Id", "description": "The container being listed, for hierarchical providers; null at the root" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Cursor for the next page, or null on the last page" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total", "description": "Total matching resources across pages, when known" }, "listing_status": { "type": "string", "enum": [ "ready", "loading", "failed" ], "title": "Listing Status", "description": "Whether the listing is complete; `loading` while a provider catalog is still being built", "default": "ready" }, "sync_all": { "type": "boolean", "title": "Sync All", "description": "Whether the installation syncs everything the account can see, new resources included: every alias it offers is selected", "default": false } }, "type": "object", "required": [ "installation_id", "provider", "status", "account", "resources" ], "title": "ConnectorResourceSelection", "description": "One page of an installation's resources with their selection state." }, "ConnectorAccount": { "properties": { "id": { "type": "string", "title": "Id", "description": "Provider-side account identifier (email, user ID, or team ID)" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Human-readable account name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email", "description": "Account email, when the provider exposes one" }, "workspace": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace", "description": "Workspace or organization the account belongs to, for providers that have one" } }, "type": "object", "required": [ "id" ], "title": "ConnectorAccount", "description": "The third-party account an installation is authorized as." }, "ConnectorInstallationSync": { "properties": { "failed_resource_count": { "type": "integer", "title": "Failed Resource Count", "description": "Resources whose last sync job failed", "default": 0 }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Error", "description": "Last failure of a job covering the whole account, such as a changes sync" }, "last_error_operation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Error Operation", "description": "Which account-wide job failed" }, "last_error_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Error At", "description": "When it failed" } }, "type": "object", "title": "ConnectorInstallationSync", "description": "Account-level sync facts: how many resources are in error, and the last failure of an account-wide job." }, "ConnectorResource": { "properties": { "id": { "type": "string", "title": "Id", "description": "Provider-side resource ID; pass it back to select or sync" }, "name": { "type": "string", "title": "Name", "description": "Display name" }, "kind": { "type": "string", "enum": [ "label", "folder", "file", "channel", "private_channel", "direct_message", "group_message" ], "title": "Kind", "description": "What kind of resource this is" }, "is_selected": { "type": "boolean", "title": "Is Selected", "description": "Whether the resource is selected for ingestion", "default": false }, "parent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Id", "description": "Containing resource ID, for hierarchical providers" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url", "description": "Link to the resource on the provider, when available" }, "message_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Message Count", "description": "Approximate number of messages in the resource, when known" }, "member_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Member Count", "description": "Approximate number of members, when known" }, "sync": { "anyOf": [ { "$ref": "#/components/schemas/ConnectorResourceSync" }, { "type": "null" } ], "description": "Per-resource sync state, when tracked" } }, "type": "object", "required": [ "id", "name", "kind" ], "title": "ConnectorResource", "description": "One syncable unit of a connected account." }, "ConnectorResourceSync": { "properties": { "status": { "type": "string", "enum": [ "not_syncing", "syncing", "partial", "error" ], "title": "Status", "description": "Whether the resource is syncing; partial means only some of a folder's contents are" }, "last_synced_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Synced At", "description": "Last successful sync time" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Last sync error, if the resource is in an error state" }, "last_run": { "anyOf": [ { "$ref": "#/components/schemas/ConnectorSyncRun" }, { "type": "null" } ], "description": "The last sync job on this resource, when one has run" } }, "type": "object", "required": [ "status" ], "title": "ConnectorResourceSync", "description": "Sync state of one resource, for providers that track it per resource." }, "ConnectorSyncRun": { "properties": { "status": { "type": "string", "enum": [ "in_progress", "completed", "failed", "stale" ], "title": "Status", "description": "Job outcome; `stale` is a job that reported starting but nothing since for hours" }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Started At", "description": "When the job started" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Completed At", "description": "When the job finished or failed" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Why the job failed" } }, "type": "object", "required": [ "status" ], "title": "ConnectorSyncRun", "description": "The last sync job on a resource, as that job recorded it when it started, finished, or failed." }, "ConnectorResourceAlias": { "properties": { "id": { "type": "string", "enum": [ "all_mail", "all_notes", "public_channels", "private_channels", "direct_messages", "group_messages" ], "title": "Id", "description": "Alias ID; pass it back in `resource_aliases`" }, "name": { "type": "string", "title": "Name", "description": "Display name" }, "kind": { "type": "string", "enum": [ "label", "folder", "file", "channel", "private_channel", "direct_message", "group_message" ], "title": "Kind", "description": "The kind of resource the alias covers" }, "is_selected": { "type": "boolean", "title": "Is Selected", "description": "Whether the alias is selected for ingestion", "default": false } }, "type": "object", "required": [ "id", "name", "kind" ], "title": "ConnectorResourceAlias", "description": "A whole kind of resource selected at once, new resources included.\n\nAliases are not resources: they never page, match a search, or carry a sync run. Gmail offers\n`all_mail`, Granola `all_notes`, and Slack one per conversation kind; Google Drive offers none." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` cURL: ```bash curl -X POST https://api.mixedbread.com/v1/integrations/installations/7b3d5f1a-9c2e-4a8b-b6d4-1e0f3c5a7d92/resources/refresh \ -H 'Authorization: Bearer YOUR_API_KEY' ``` # Register OAuth Client URL: https://www.mixedbread.com/api-reference/endpoints/integrations/register-oauth-client Register the organization's own OAuth client for a connector, or rotate its secrets. ```json { "paths": { "/v1/integrations/oauth-clients/{provider}": { "put": { "tags": [ "integrations" ], "summary": "Register OAuth Client", "operationId": "upsert_oauth_client", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "enum": [ "google_drive", "gmail", "slack" ], "type": "string", "description": "The connector to configure", "title": "Provider" }, "description": "The connector to configure" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthClientBody", "description": "The customer's OAuth client credentials" } } } }, "responses": { "200": { "description": "The connector slot after the change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthClientMutationResponse" }, "example": { "data": { "slot": { "provider": "gmail", "redirect_uri": "https://api.mixedbread.com/v1/integrations/gmail/oauth/callback", "required_scopes": [ "https://www.googleapis.com/auth/gmail.readonly" ], "app_manifest": null, "client": { "provider": "gmail", "client_id": "123456789012-abcdefghijklmnop.apps.googleusercontent.com", "redirect_uri": "https://api.mixedbread.com/v1/integrations/gmail/oauth/callback", "return_url": "https://platform.example.com/connected", "has_signing_secret": false, "created_by_user_id": "da5f646d-4827-49a5-92cc-2f16a6594c27", "created_at": "2026-09-05T17:25:12.338038+00:00", "updated_at": "2026-09-05T17:25:12.338038+00:00" } }, "reauth_required_installation_ids": [], "disconnected_installation_ids": [] } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "OAuthClientBody": { "properties": { "client_id": { "type": "string", "maxLength": 256, "minLength": 1, "title": "Client Id", "description": "The OAuth client ID from the customer's Google Cloud project or Slack app" }, "client_secret": { "type": "string", "format": "password", "title": "Client Secret", "description": "The OAuth client secret. Write-only: it is encrypted at rest and never returned.", "writeOnly": true }, "signing_secret": { "anyOf": [ { "type": "string", "format": "password", "writeOnly": true }, { "type": "null" } ], "title": "Signing Secret", "description": "The app's signing secret, used to verify the webhooks it sends. Required for Slack; not accepted for Google connectors. Write-only." }, "return_url": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "title": "Return Url", "description": "Required. Where the connector's OAuth callback returns the user after consent. Must be an absolute https URL (http is allowed for localhost). The outcome is appended as query parameters: provider, status, and installation_id or error." } }, "type": "object", "required": [ "client_id", "client_secret" ], "title": "OAuthClientBody", "description": "Request body for registering or rotating an organization's own OAuth client.\n\nThe secrets are :class:`SecretStr` so they are masked in reprs and in the input echo that\npydantic attaches to validation errors; they are only ever read back inside a token exchange or\na webhook signature check. Only the credentials are accepted -- the authorization and token\nendpoints stay pinned to Google's and Slack's own URLs, so a registered client can never redirect\na token exchange elsewhere." }, "OAuthClientMutationResponse": { "properties": { "data": { "$ref": "#/components/schemas/OAuthClientMutationResult", "description": "The connector slot after the change" } }, "type": "object", "required": [ "data" ], "title": "OAuthClientMutationResponse", "description": "The result of registering, rotating, or removing a customer-owned Google OAuth client." }, "OAuthClientMutationResult": { "properties": { "slot": { "$ref": "#/components/schemas/OAuthClientSlot", "description": "The connector slot after the change" }, "reauth_required_installation_ids": { "items": { "type": "string" }, "type": "array", "title": "Reauth Required Installation Ids", "description": "Installations whose refresh tokens were invalidated and now need reconnecting" }, "disconnected_installation_ids": { "items": { "type": "string" }, "type": "array", "title": "Disconnected Installation Ids", "description": "Installations that were disconnected because the client they were authorized with was removed" } }, "type": "object", "required": [ "slot" ], "title": "OAuthClientMutationResult", "description": "The outcome of registering, rotating, or removing a customer-owned OAuth client." }, "OAuthClientSlot": { "properties": { "provider": { "type": "string", "enum": [ "google_drive", "gmail", "slack" ], "title": "Provider", "description": "The connector this slot is for" }, "redirect_uri": { "type": "string", "title": "Redirect Uri", "description": "The redirect URI that must be authorized on the customer's OAuth client" }, "required_scopes": { "items": { "type": "string" }, "type": "array", "title": "Required Scopes", "description": "Scopes the customer's OAuth client must grant" }, "app_manifest": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "App Manifest", "description": "A JSON app manifest to create the customer's app from, for connectors that have one" }, "client": { "anyOf": [ { "$ref": "#/components/schemas/OAuthClientView" }, { "type": "null" } ], "description": "The registered client, or null when the connector uses the Mixedbread client" } }, "type": "object", "required": [ "provider", "redirect_uri", "required_scopes" ], "title": "OAuthClientSlot", "description": "One connector's bring-your-own-client slot, registered or not." }, "OAuthClientView": { "properties": { "provider": { "type": "string", "enum": [ "google_drive", "gmail", "slack" ], "title": "Provider", "description": "The connector this client is used for" }, "client_id": { "type": "string", "title": "Client Id", "description": "The customer's OAuth client id" }, "redirect_uri": { "type": "string", "title": "Redirect Uri", "description": "The redirect URI that must be authorized on the customer's OAuth client" }, "return_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Return Url", "description": "Where the OAuth callback returns the user after consent, if the organization set one" }, "has_signing_secret": { "type": "boolean", "title": "Has Signing Secret", "description": "Whether a webhook signing secret is stored for the client (Slack only)", "default": false }, "created_by_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created By User Id", "description": "The user who registered the client" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At", "description": "When the client was first registered" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated At", "description": "When the client was last rotated" } }, "type": "object", "required": [ "provider", "client_id", "redirect_uri" ], "title": "OAuthClientView", "description": "An organization's registered OAuth client as exposed to the dashboard.\n\nSecrets are never part of this shape: once stored they are only ever decrypted inside a token\nexchange or a webhook signature check. A client id is public by construction (it appears in the\nconsent URL), so it is returned in full to let the customer confirm which app is wired up." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` cURL: ```bash curl -X PUT https://api.mixedbread.com/v1/integrations/oauth-clients/gmail \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -d '{ "client_id": "123456789012-abcdefghijklmnop.apps.googleusercontent.com", "client_secret": "GOCSPX-…", "return_url": "https://platform.example.com/connected" }' ``` # Replace Resources URL: https://www.mixedbread.com/api-reference/endpoints/integrations/replace-resources Set exactly which resources and aliases sync into the store. Newly selected ones are queued; anything not listed stops syncing. ```json { "paths": { "/v1/integrations/installations/{installation_id}/resources": { "put": { "tags": [ "integrations" ], "summary": "Replace Resources", "description": "An alias from the listing's `aliases` selects every resource of its kind, new ones included: Gmail's\n`all_mail`, Granola's `all_notes`, or a Slack conversation kind such as `private_channels`. Selecting\nevery alias the installation offers is the same as `sync_all` on the sync endpoint.", "operationId": "update_integration_installation_resources", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "installation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Installation ID, as returned when the account connected", "title": "Installation Id" }, "description": "Installation ID, as returned when the account connected" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorResourceSelectionUpdateParams", "description": "The complete selection" } } } }, "responses": { "200": { "description": "The updated selection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorResourceSelectionUpdateResponse" }, "example": { "data": { "installation_id": "7b3d5f1a-9c2e-4a8b-b6d4-1e0f3c5a7d92", "store_id": "c4a6e8f0-2b1d-4c3e-9a5f-7e6d5c4b3a21", "selected_resource_ids": [ "C067DDX8J2X", "G0B7TQ2M4KD", "D0ADMEQP5P1", "C0AEUC2HDAN" ], "selected_resource_aliases": [ "private_channels", "direct_messages", "group_messages" ], "queued_resource_ids": [ "G0B7TQ2M4KD", "C0AEUC2HDAN" ], "skipped_resources": {} } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "ConnectorResourceSelectionUpdateParams": { "properties": { "resource_ids": { "items": { "type": "string" }, "type": "array", "title": "Resource Ids", "description": "Complete set of resource IDs to sync; anything not listed stops syncing" }, "resource_aliases": { "items": { "type": "string", "enum": [ "all_mail", "all_notes", "public_channels", "private_channels", "direct_messages", "group_messages" ] }, "type": "array", "title": "Resource Aliases", "description": "Complete set of aliases to sync, from the listing's `aliases`. An alias covers every resource of its kind, new ones included; anything not listed stops syncing" } }, "type": "object", "title": "ConnectorResourceSelectionUpdateParams", "description": "Replace the set of selected resources and aliases." }, "ConnectorResourceSelectionUpdateResponse": { "properties": { "data": { "$ref": "#/components/schemas/ConnectorResourceSelectionUpdate", "description": "The updated selection" } }, "type": "object", "required": [ "data" ], "title": "ConnectorResourceSelectionUpdateResponse", "description": "Response containing the outcome of replacing a selection." }, "ConnectorResourceSelectionUpdate": { "properties": { "installation_id": { "type": "string", "title": "Installation Id", "description": "Installation ID" }, "store_id": { "type": "string", "title": "Store Id", "description": "Store the selection ingests into" }, "selected_resource_ids": { "items": { "type": "string" }, "type": "array", "title": "Selected Resource Ids", "description": "Resource IDs selected after the update. A Gmail or Granola alias also appears here by its provider ID (`__gmail_all_mail__`, `__granola_all_notes__`)." }, "selected_resource_aliases": { "items": { "type": "string", "enum": [ "all_mail", "all_notes", "public_channels", "private_channels", "direct_messages", "group_messages" ] }, "type": "array", "title": "Selected Resource Aliases", "description": "Aliases selected after the update" }, "queued_resource_ids": { "items": { "type": "string" }, "type": "array", "title": "Queued Resource Ids", "description": "Newly selected resources queued for historical ingestion" }, "skipped_resources": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Skipped Resources", "description": "Requested resource IDs that could not be selected, with a reason" } }, "type": "object", "required": [ "installation_id", "store_id", "selected_resource_ids" ], "title": "ConnectorResourceSelectionUpdate", "description": "Outcome of replacing the selection." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` cURL: ```bash curl -X PUT https://api.mixedbread.com/v1/integrations/installations/7b3d5f1a-9c2e-4a8b-b6d4-1e0f3c5a7d92/resources \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -d '{ "resource_aliases": [ "private_channels", "direct_messages", "group_messages" ], "resource_ids": [ "C067DDX8J2X" ] }' ``` # Sync Installation URL: https://www.mixedbread.com/api-reference/endpoints/integrations/sync-installation Queue a sync of the selected resources, of a subset, or of everything the account can see with sync_all. ```json { "paths": { "/v1/integrations/installations/{installation_id}/sync": { "post": { "tags": [ "integrations" ], "summary": "Sync Installation", "description": "With `sync_all` the account's entire contents are selected and synced, and new resources keep being\npicked up on their own; the listing then reports `sync_all` until an explicit selection replaces it.", "operationId": "sync_integration_installation", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "installation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Installation ID, as returned when the account connected", "title": "Installation Id" }, "description": "Installation ID, as returned when the account connected" } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ConnectorSyncParams" }, { "type": "null" } ], "description": "Optional subset of resources to sync, or `sync_all`", "title": "Params" } } } }, "responses": { "200": { "description": "Queued and skipped resources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorSyncResponse" }, "example": { "data": { "installation_id": "2f1c9a8e-6b4d-4e3a-9c1f-7d8e5b6a4c21", "store_id": "5d3e7f9a-1b2c-4d6e-8f0a-9c8b7a6d5e4f", "sync_all": true, "selected_resource_aliases": [ "all_mail" ], "queued_resource_ids": [ "all_mail" ], "skipped_resources": {} } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "ConnectorSyncParams": { "properties": { "resource_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Resource Ids", "description": "Selected resource IDs to sync; defaults to every selected resource. Providers that sync the whole installation at once ignore this and sync everything selected." }, "sync_all": { "type": "boolean", "title": "Sync All", "description": "Sync everything the account can see and keep syncing new resources as they appear: every mail outside spam, trash and drafts, the whole Drive, every note, or every conversation. Replaces the selection; a later explicit selection turns the mode off again.", "default": false } }, "type": "object", "title": "ConnectorSyncParams", "description": "Trigger a sync." }, "ConnectorSyncResponse": { "properties": { "data": { "$ref": "#/components/schemas/ConnectorSync", "description": "Queued and skipped resources" } }, "type": "object", "required": [ "data" ], "title": "ConnectorSyncResponse", "description": "Response containing the outcome of triggering a sync." }, "ConnectorSync": { "properties": { "installation_id": { "type": "string", "title": "Installation Id", "description": "Installation ID" }, "store_id": { "type": "string", "title": "Store Id", "description": "Store the sync ingests into" }, "sync_all": { "type": "boolean", "title": "Sync All", "description": "Whether the installation now syncs everything, new resources included", "default": false }, "selected_resource_aliases": { "items": { "type": "string", "enum": [ "all_mail", "all_notes", "public_channels", "private_channels", "direct_messages", "group_messages" ] }, "type": "array", "title": "Selected Resource Aliases", "description": "Aliases selected after the sync" }, "queued_resource_ids": { "items": { "type": "string" }, "type": "array", "title": "Queued Resource Ids", "description": "Resource IDs queued for sync; an alias is queued under its alias ID" }, "skipped_resources": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Skipped Resources", "description": "Requested resource IDs that were not queued, with a reason" } }, "type": "object", "required": [ "installation_id", "store_id" ], "title": "ConnectorSync", "description": "Outcome of triggering a sync." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` cURL: ```bash curl -X POST https://api.mixedbread.com/v1/integrations/installations/2f1c9a8e-6b4d-4e3a-9c1f-7d8e5b6a4c21/sync \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -d '{ "sync_all": true }' ``` # Update Installation Schedule URL: https://www.mixedbread.com/api-reference/endpoints/integrations/update-installation-schedule Set how often a connected account is polled for new and changed content. ```json { "paths": { "/v1/integrations/installations/{installation_id}/schedule": { "put": { "tags": [ "integrations" ], "summary": "Update Installation Schedule", "description": "Only Granola polls. Gmail, Google Drive, and Slack receive change notifications from the provider and\nreject this call.", "operationId": "update_integration_installation_schedule", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "installation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Installation ID, as returned when the account connected", "title": "Installation Id" }, "description": "Installation ID, as returned when the account connected" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorScheduleParams", "description": "The polling interval" } } } }, "responses": { "200": { "description": "The schedule after the change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorScheduleResponse" }, "example": { "data": { "installation_id": "2f1c9a8e-6b4d-4e3a-9c1f-7d8e5b6a4c21", "interval": "hourly", "updated_at": "2026-09-05T17:25:12.338038+00:00" } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "ConnectorScheduleParams": { "properties": { "interval": { "type": "string", "enum": [ "off", "ten_minutes", "hourly", "daily", "weekly" ], "title": "Interval", "description": "How often to poll for new and changed content; `off` stops the periodic sync" } }, "type": "object", "required": [ "interval" ], "title": "ConnectorScheduleParams", "description": "Set how often an installation polls its provider for changes." }, "ConnectorScheduleResponse": { "properties": { "data": { "$ref": "#/components/schemas/ConnectorSchedule", "description": "The schedule after the change" } }, "type": "object", "required": [ "data" ], "title": "ConnectorScheduleResponse", "description": "Response containing an installation's sync schedule." }, "ConnectorSchedule": { "properties": { "installation_id": { "type": "string", "title": "Installation Id", "description": "Installation ID" }, "interval": { "type": "string", "enum": [ "off", "ten_minutes", "hourly", "daily", "weekly" ], "title": "Interval", "description": "Current periodic sync interval" }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At", "description": "When the schedule was last changed" } }, "type": "object", "required": [ "installation_id", "interval" ], "title": "ConnectorSchedule", "description": "An installation's periodic sync schedule." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` cURL: ```bash curl -X PUT https://api.mixedbread.com/v1/integrations/installations/2f1c9a8e-6b4d-4e3a-9c1f-7d8e5b6a4c21/schedule \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -d '{ "interval": "hourly" }' ``` # List Store Events URL: https://www.mixedbread.com/api-reference/endpoints/stores/events/list-store-events List ingestion, search, grep, question answering, and chat completion events for a store with pagination and time filters. ```json { "paths": { "/v1/stores/{store_identifier}/events": { "get": { "tags": [ "stores" ], "summary": "List Store Events", "operationId": "list_store_events", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "store_identifier", "in": "path", "required": true, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ], "description": "The ID or name of the store", "title": "Store Identifier" }, "description": "The ID or name of the store" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Maximum number of items to return per page (1-100)", "examples": [ 10, 20, 50 ], "default": 20, "title": "Limit" }, "description": "Maximum number of items to return per page (1-100)" }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for forward pagination - get items after this position. Use last_cursor from previous response.", "examples": [ "eyJjcmVhdGVkX2F0IjoiMjAyNC0xMi0zMVQyMzo1OTo1OS4wMDBaIiwiaWQiOiJhYmMxMjMifQ==" ], "title": "After" }, "description": "Cursor for forward pagination - get items after this position. Use last_cursor from previous response." }, { "name": "before", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for backward pagination - get items before this position. Use first_cursor from previous response.", "examples": [ "eyJjcmVhdGVkX2F0IjoiMjAyNC0xMi0zMVQyMzo1OTo1OS4wMDBaIiwiaWQiOiJhYmMxMjMifQ==" ], "title": "Before" }, "description": "Cursor for backward pagination - get items before this position. Use first_cursor from previous response." }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Whether to include total count in response (expensive operation)", "examples": [ false, true ], "default": false, "title": "Include Total" }, "description": "Whether to include total count in response (expensive operation)" }, { "name": "filter_before", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time to filter events before", "title": "Filter Before" }, "description": "Time to filter events before" }, { "name": "filter_after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time to filter events after", "title": "Filter After" }, "description": "Time to filter events after" }, { "name": "event_type", "in": "query", "required": true, "schema": { "enum": [ "ingestion", "search", "agentic_search", "grep", "completion", "qa" ], "type": "string", "description": "The type of event to list", "examples": [ "ingestion", "search", "agentic_search", "grep" ], "title": "Event Type" }, "description": "The type of event to list" } ], "responses": { "200": { "description": "The list of events for the store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreEventListResponse" }, "example": { "object": "list", "data": [ { "id": "evt_abc123", "type": "ingestion", "created_at": "2025-01-15T14:30:00.000Z", "store_id": "vs_abc123", "store_file_id": "vsf_def456", "total_time": "PT5.2S", "queue_time": "PT1.1S", "ingestion_time": "PT4.1S", "chunk_count": 42, "contextualization": true, "mode": "high_quality", "filename": "product-docs.pdf" }, { "id": "evt_def456", "type": "ingestion", "created_at": "2025-01-15T14:25:00.000Z", "store_id": "vs_abc123", "store_file_id": "vsf_ghi789", "total_time": "PT2.8S", "queue_time": "PT0.5S", "ingestion_time": "PT2.3S", "chunk_count": 15, "contextualization": false, "mode": "fast", "filename": "faq.md" } ], "pagination": { "has_more": true, "first_cursor": "eyJpZCI6ImV2dF9hYmMxMjMifQ==", "last_cursor": "eyJpZCI6ImV2dF9kZWY0NTYifQ==" } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "StoreEventListResponse": { "properties": { "pagination": { "$ref": "#/components/schemas/CursorPaginationResponse" }, "object": { "type": "string", "const": "list", "title": "Object", "description": "The object type of the response", "default": "list" }, "data": { "items": { "oneOf": [ { "$ref": "#/components/schemas/StoreIngestionEvent" }, { "$ref": "#/components/schemas/StoreSearchEvent" }, { "$ref": "#/components/schemas/StoreAgenticSearchEvent" }, { "$ref": "#/components/schemas/StoreGrepEvent" }, { "$ref": "#/components/schemas/StoreCompletionEvent" }, { "$ref": "#/components/schemas/StoreQAEvent" } ], "discriminator": { "propertyName": "type", "mapping": { "agentic_search": "#/components/schemas/StoreAgenticSearchEvent", "completion": "#/components/schemas/StoreCompletionEvent", "grep": "#/components/schemas/StoreGrepEvent", "ingestion": "#/components/schemas/StoreIngestionEvent", "qa": "#/components/schemas/StoreQAEvent", "search": "#/components/schemas/StoreSearchEvent" } } }, "type": "array", "title": "Data", "description": "The list of store events" } }, "type": "object", "required": [ "pagination", "data" ], "title": "StoreEventListResponse" }, "CursorPaginationResponse": { "properties": { "has_more": { "type": "boolean", "title": "Has More", "description": "Contextual direction-aware flag: True if more items exist in the requested pagination direction. For 'after': more items after this page. For 'before': more items before this page.", "examples": [ true, false ] }, "first_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Cursor", "description": "Cursor of the first item in this page. Use for backward pagination. None if page is empty.", "examples": [ "eyJjcmVhdGVkX2F0IjoiMjAyNC0xMi0zMVQyMzo1OTo1OS4wMDBaIiwiaWQiOiJhYmMxMjMifQ==", null ] }, "last_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Cursor", "description": "Cursor of the last item in this page. Use for forward pagination. None if page is empty.", "examples": [ "eyJjcmVhdGVkX2F0IjoiMjAyNC0xMi0zMFQyMzo1OTo1OS4wMDBaIiwiaWQiOiJ4eXo3ODkifQ==", null ] }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total", "description": "Total number of items available across all pages. Only included when include_total=true was requested. Expensive operation - use sparingly.", "examples": [ 42, 0, null ] } }, "type": "object", "required": [ "has_more", "first_cursor", "last_cursor" ], "title": "CursorPaginationResponse", "description": "Response model for cursor-based pagination." }, "StoreIngestionEvent": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Unique identifier for the event" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when the event was created" }, "type": { "type": "string", "const": "ingestion", "title": "Type", "default": "ingestion" }, "store_id": { "type": "string", "format": "uuid", "title": "Store Id", "description": "ID of the vector store" }, "store_file_id": { "type": "string", "title": "Store File Id", "description": "ID of the vector store file" }, "total_time": { "type": "string", "format": "duration", "title": "Total Time", "description": "Total time taken to ingest the file, including queue time" }, "queue_time": { "type": "string", "format": "duration", "title": "Queue Time", "description": "Time spent in the queue" }, "ingestion_time": { "type": "string", "format": "duration", "title": "Ingestion Time", "description": "Time taken to ingest the file, excluding queue time" }, "chunk_count": { "type": "integer", "title": "Chunk Count", "description": "Number of chunks ingested" }, "contextualization": { "type": "boolean", "title": "Contextualization", "description": "Whether contextualization was used" }, "mode": { "$ref": "#/components/schemas/StoreFileParsingStrategy", "description": "Strategy used to ingest the file" }, "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Filename", "description": "Name of the file if the event is tied to a file" } }, "type": "object", "required": [ "id", "created_at", "store_id", "store_file_id", "total_time", "queue_time", "ingestion_time", "chunk_count", "contextualization", "mode" ], "title": "StoreIngestionEvent", "description": "Represents an ingestion event in a vector store." }, "StoreFileParsingStrategy": { "type": "string", "enum": [ "fast", "high_quality" ], "title": "StoreFileParsingStrategy", "description": "Strategy for adding a file to a store." }, "StoreSearchEvent": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Unique identifier for the event" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when the event was created" }, "type": { "type": "string", "const": "search", "title": "Type", "default": "search" }, "store_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "title": "Store Ids", "description": "IDs of the vector stores searched" }, "search_time": { "type": "string", "format": "duration", "title": "Search Time", "description": "Time taken to search the vector store", "default": "PT0S" }, "query": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Query", "description": "Query used to search the vector store" }, "rewritten_query": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rewritten Query", "description": "Rewritten query if query rewriting was enabled" }, "rewritten_filters": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Output" }, { "$ref": "#/components/schemas/SearchFilterCondition" }, { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Output" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Rewritten Filters", "description": "Filters used after query rewriting" }, "rewrite_rank_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rewrite Rank By", "description": "Metadata field used for ranking" }, "rewrite_rank_direction": { "anyOf": [ { "type": "string", "enum": [ "asc", "desc" ] }, { "type": "null" } ], "title": "Rewrite Rank Direction", "description": "Ranking direction" }, "rewrite_rank_mode": { "anyOf": [ { "type": "string", "enum": [ "post_search", "metadata" ] }, { "type": "null" } ], "title": "Rewrite Rank Mode", "description": "Ranking mode" }, "rerank": { "type": "boolean", "title": "Rerank", "description": "Whether to rerank the results", "default": false }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Output" }, { "$ref": "#/components/schemas/SearchFilterCondition" }, { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Output" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Filters", "description": "Metadata filters submitted with the search request" }, "results": { "items": { "$ref": "#/components/schemas/StoreSearchEventResult" }, "type": "array", "title": "Results", "description": "Chunks returned by the search" } }, "type": "object", "required": [ "id", "created_at", "store_ids" ], "title": "StoreSearchEvent", "description": "Represents a search event in a vector store." }, "SearchFilter-Output": { "properties": { "all": { "anyOf": [ { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Output" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "All", "description": "List of conditions or filters to be ANDed together", "examples": [ [ { "key": "price", "operator": "gt", "value": "100" }, { "key": "color", "operator": "eq", "value": "red" } ], null ] }, "any": { "anyOf": [ { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Output" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Any", "description": "List of conditions or filters to be ORed together", "examples": [ [ { "key": "price", "operator": "gt", "value": "100" }, { "key": "color", "operator": "eq", "value": "red" } ], null ] }, "none": { "anyOf": [ { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Output" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "None", "description": "List of conditions or filters to be NOTed", "examples": [ [ { "key": "price", "operator": "gt", "value": "100" }, { "key": "color", "operator": "eq", "value": "red" } ], null ] } }, "type": "object", "title": "SearchFilter", "description": "Represents a filter with AND, OR, and NOT conditions." }, "SearchFilterCondition": { "properties": { "key": { "type": "string", "title": "Key", "description": "The field to apply the condition on", "examples": [ "price", "color" ] }, "value": { "title": "Value", "description": "The value to compare against", "examples": [ "100", "red" ] }, "operator": { "$ref": "#/components/schemas/ConditionOperator", "description": "The operator for the condition", "examples": [ "eq", "gt" ] } }, "type": "object", "required": [ "key", "value", "operator" ], "title": "SearchFilterCondition", "description": "Represents a condition with a field, operator, and value." }, "ConditionOperator": { "type": "string", "enum": [ "eq", "not_eq", "gt", "gte", "lt", "lte", "in", "not_in", "like", "contains", "starts_with", "not_like", "regex" ], "title": "ConditionOperator", "description": "Operator for a filter condition." }, "StoreSearchEventResult": { "properties": { "store_id": { "type": "string", "title": "Store Id", "description": "ID of the store the chunk belongs to" }, "file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Id", "description": "ID of the file the chunk belongs to" }, "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Filename", "description": "Name of the file the chunk belongs to" }, "chunk_index": { "type": "integer", "title": "Chunk Index", "description": "Index of the chunk within its file" }, "score": { "type": "number", "title": "Score", "description": "Final score assigned to the chunk" }, "first_stage_position": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "First Stage Position", "description": "Position of the chunk in the first-stage ranking" }, "first_stage_source": { "anyOf": [ { "type": "string", "enum": [ "dense", "sparse", "both" ] }, { "type": "null" } ], "title": "First Stage Source", "description": "Which first-stage retriever surfaced the chunk" } }, "type": "object", "required": [ "store_id", "chunk_index", "score" ], "title": "StoreSearchEventResult", "description": "A single result captured on a search event." }, "StoreAgenticSearchEvent": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Unique identifier for the event" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when the event was created" }, "type": { "type": "string", "const": "agentic_search", "title": "Type", "default": "agentic_search" }, "store_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "title": "Store Ids", "description": "IDs of the vector stores searched" }, "started_at": { "type": "string", "format": "date-time", "title": "Started At", "description": "Time when the agentic search began" }, "search_time": { "type": "string", "format": "duration", "title": "Search Time", "description": "Total wall-clock time of the agent loop", "default": "PT0S" }, "query": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Query", "description": "Original query submitted by the user" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions", "description": "Custom instructions provided with the agentic search, if any" }, "ranking_strategy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ranking Strategy", "description": "Agent-submitted explanation of how chunks were ranked" }, "rounds_executed": { "type": "integer", "title": "Rounds Executed", "description": "Number of search rounds the agent executed", "default": 0 }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Output" }, { "$ref": "#/components/schemas/SearchFilterCondition" }, { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Output" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Filters", "description": "Metadata filters submitted with the search request" }, "token_usage": { "$ref": "#/components/schemas/AgenticSearchTokenUsage", "description": "Token usage for LLM calls during the agentic search" }, "tool_calls": { "items": { "$ref": "#/components/schemas/AgenticToolCall" }, "type": "array", "title": "Tool Calls", "description": "Ordered tool calls issued by the agent" }, "results": { "items": { "$ref": "#/components/schemas/StoreSearchEventResult" }, "type": "array", "title": "Results", "description": "Chunks returned by the agentic search" } }, "type": "object", "required": [ "id", "created_at", "store_ids", "started_at" ], "title": "StoreAgenticSearchEvent", "description": "Represents an agentic search trace in a vector store.\n\nUnlike StoreSearchEvent, this captures the full sequence of tool calls the\nagent issued (name, arguments, result) so developers can inspect what the\nagent did, along with the token usage." }, "AgenticSearchTokenUsage": { "properties": { "prompt_tokens": { "type": "integer", "title": "Prompt Tokens", "description": "Number of prompt tokens consumed", "default": 0 }, "completion_tokens": { "type": "integer", "title": "Completion Tokens", "description": "Number of completion tokens generated", "default": 0 }, "total_tokens": { "type": "integer", "title": "Total Tokens", "description": "Total tokens consumed (prompt + completion)", "default": 0 } }, "type": "object", "title": "AgenticSearchTokenUsage", "description": "Token usage for LLM calls made during an agentic search." }, "AgenticToolCall": { "properties": { "tool_call_id": { "type": "string", "title": "Tool Call Id", "description": "Unique identifier for the tool call (gen_ai.tool.call.id)" }, "tool_name": { "type": "string", "title": "Tool Name", "description": "Name of the tool invoked (gen_ai.tool.name)", "examples": [ "search_batch" ] }, "tool_type": { "type": "string", "enum": [ "function", "extension", "datastore" ], "title": "Tool Type", "description": "Category of the tool (gen_ai.tool.type)", "default": "function" }, "started_at": { "type": "string", "format": "date-time", "title": "Started At", "description": "Time when the tool call began" }, "duration": { "type": "string", "format": "duration", "title": "Duration", "description": "Time taken to execute the tool call" }, "arguments": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Arguments", "description": "Arguments passed to the tool (gen_ai.tool.call.arguments)" }, "result": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Result", "description": "Result returned to the model (gen_ai.tool.call.result). None if the tool errored." }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Error message if the tool call failed" }, "error_kind": { "anyOf": [ { "type": "string", "enum": [ "provider", "agent" ] }, { "type": "null" } ], "title": "Error Kind", "description": "Failure classification when the tool call errored: `provider` is an infrastructure failure outside the agent's control, `agent` is feedback the agent received and can recover from." } }, "type": "object", "required": [ "tool_call_id", "tool_name", "started_at", "duration" ], "title": "AgenticToolCall", "description": "Represents a single tool call made by the agent during an agentic search.\n\nFields follow the OpenTelemetry GenAI semantic conventions for tool calls:\nhttps://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/" }, "StoreGrepEvent": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Unique identifier for the event" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when the event was created" }, "type": { "type": "string", "const": "grep", "title": "Type", "default": "grep" }, "store_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "title": "Store Ids", "description": "IDs of the vector stores grepped" }, "pattern": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pattern", "description": "Regular expression matched against chunk text" }, "case_sensitive": { "type": "boolean", "title": "Case Sensitive", "description": "Whether the pattern was matched case-sensitively", "default": false }, "search_time": { "type": "string", "format": "duration", "title": "Search Time", "description": "Time taken to grep the vector store", "default": "PT0S" }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Output" }, { "$ref": "#/components/schemas/SearchFilterCondition" }, { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Output" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Filters", "description": "Metadata filters submitted with the grep request" }, "results": { "items": { "$ref": "#/components/schemas/StoreSearchEventResult" }, "type": "array", "title": "Results", "description": "Chunks that matched the pattern" } }, "type": "object", "required": [ "id", "created_at", "store_ids" ], "title": "StoreGrepEvent", "description": "Represents a grep event in a vector store.\n\nGrep matches chunks against a regular expression rather than running a\nsemantic search, so it has no ranking, rewrite, or rerank fields." }, "StoreCompletionEvent": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Unique identifier for the event" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when the event was created" }, "type": { "type": "string", "const": "completion", "title": "Type", "default": "completion" }, "store_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "title": "Store Ids", "description": "IDs of the stores the completion's hosted tools touched" }, "completion_id": { "type": "string", "title": "Completion Id", "description": "ID of the completion; retrievable while it is persisted" }, "endpoint": { "type": "string", "enum": [ "chat_completions", "responses" ], "title": "Endpoint", "description": "API the completion was created through", "default": "chat_completions" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "Model that served the completion" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title", "description": "Conversation title" }, "previous_completion_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previous Completion Id", "description": "Completion this turn continued from, if the conversation was resumed" }, "root_completion_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Root Completion Id", "description": "First completion of the conversation this turn belongs to; groups the turns of one chat" }, "persisted": { "type": "boolean", "title": "Persisted", "description": "Whether the completion was stored for later retrieval", "default": true }, "finish_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Finish Reason", "description": "Why generation ended" }, "started_at": { "type": "string", "format": "date-time", "title": "Started At", "description": "Time when the completion began" }, "total_time": { "type": "string", "format": "duration", "title": "Total Time", "description": "Wall-clock time of the completion turn", "default": "PT0S" }, "user_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Message", "description": "Text of the last user message in the request, truncated" }, "answer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Answer", "description": "Text of the generated answer, truncated" }, "token_usage": { "$ref": "#/components/schemas/AgenticSearchTokenUsage", "description": "Token usage for the model calls of the turn" }, "tool_calls": { "items": { "$ref": "#/components/schemas/AgenticToolCall" }, "type": "array", "title": "Tool Calls", "description": "Ordered model generations and hosted tool calls of the turn" } }, "type": "object", "required": [ "id", "created_at", "store_ids", "completion_id", "started_at" ], "title": "StoreCompletionEvent", "description": "Represents a chat completion or response that used the store through its hosted tools.\n\nOne event per completion turn, shared by the Chat Completions and Responses\nendpoints. It records the model calls and the hosted store tool calls the\nturn issued, in the same trace shape as agentic search events." }, "StoreQAEvent": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Unique identifier for the event" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when the event was created" }, "type": { "type": "string", "const": "qa", "title": "Type", "default": "qa" }, "store_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "title": "Store Ids", "description": "IDs of the stores the answer was grounded in" }, "started_at": { "type": "string", "format": "date-time", "title": "Started At", "description": "Time when the question answering began" }, "total_time": { "type": "string", "format": "duration", "title": "Total Time", "description": "Wall-clock time of the request, retrieval and generation included", "default": "PT0S" }, "search_time": { "type": "string", "format": "duration", "title": "Search Time", "description": "Time spent on the retrieval half", "default": "PT0S" }, "query": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Query", "description": "Question submitted by the user" }, "answer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Answer", "description": "Answer generated by the model" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions", "description": "Custom instructions provided with the request, if any" }, "cite": { "type": "boolean", "title": "Cite", "description": "Whether citations were requested", "default": false }, "cited_chunk_indices": { "items": { "type": "integer" }, "type": "array", "title": "Cited Chunk Indices", "description": "Indices into `results` the answer cited" }, "agentic": { "type": "boolean", "title": "Agentic", "description": "Whether the retrieval ran as an agentic search", "default": false }, "rounds_executed": { "type": "integer", "title": "Rounds Executed", "description": "Number of search rounds of the agentic retrieval, when agentic", "default": 0 }, "token_usage": { "$ref": "#/components/schemas/AgenticSearchTokenUsage", "description": "Token usage of the answer generation; retrieval usage is on its tool calls" }, "tool_calls": { "items": { "$ref": "#/components/schemas/AgenticToolCall" }, "type": "array", "title": "Tool Calls", "description": "Retrieval tool calls followed by the answer generation" }, "results": { "items": { "$ref": "#/components/schemas/StoreSearchEventResult" }, "type": "array", "title": "Results", "description": "Chunks the answer was grounded in" } }, "type": "object", "required": [ "id", "created_at", "store_ids", "started_at" ], "title": "StoreQAEvent", "description": "Represents a question-answering request over one or more stores.\n\nCaptures both halves of the request in one record: the retrieval (a plain\nor agentic search, recorded as tool calls) and the answer generation (a\n`generation` tool call carrying the model and its token usage)." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` cURL: ```bash curl 'https://api.mixedbread.com/v1/stores/my-store/events?event_type=ingestion&limit=20' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` # Add File to Store URL: https://www.mixedbread.com/api-reference/endpoints/stores/files/add-store-file Upload a new file to a store for indexing. ```json { "paths": { "/v1/stores/{store_identifier}/files": { "post": { "tags": [ "stores" ], "summary": "Add File to Store", "operationId": "create_store_file", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "store_identifier", "in": "path", "required": true, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ], "description": "The ID or name of the store", "title": "Store Identifier" }, "description": "The ID or name of the store" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeprecatedStoreFileUpsertParams", "description": "The file to add to the store" } } } }, "responses": { "201": { "description": "The uploaded store file details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreFile" }, "example": { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "external_id": "ext-doc-001", "object": "store.file", "filename": "example_document.pdf", "metadata": { "category": "documentation" }, "status": "in_progress", "last_error": null, "store_id": "c3d4e5f6-a7b8-9012-cdef-345678901234", "usage_bytes": 0, "usage_tokens": 0, "config": { "parsing_strategy": "fast" }, "version": 1, "created_at": "2025-01-15T16:00:00.000Z", "content_url": "https://example.com/files/f47ac10b-58cc-4372-a567-0e02b2c3d479?signature=..." } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "DeprecatedStoreFileUpsertParams": { "properties": { "metadata": { "anyOf": [ {}, { "type": "null" } ], "title": "Metadata", "description": "Optional metadata for the file" }, "config": { "$ref": "#/components/schemas/StoreFileConfig", "description": "Configuration for adding the file" }, "external_id": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "null" } ], "title": "External Id", "description": "External identifier for this file in the store" }, "overwrite": { "type": "boolean", "title": "Overwrite", "description": "If true, overwrite an existing file with the same external_id", "default": true, "examples": [ false, true ] }, "file_id": { "type": "string", "format": "uuid", "title": "File Id", "description": "ID of the file to add" }, "experimental": { "anyOf": [ { "$ref": "#/components/schemas/StoreFileConfig" }, { "type": "null" } ], "description": "Strategy for adding the file. This field is deprecated. Please use the top-level 'config' field instead. If this is provided, it will override the top-level 'config' field.", "deprecated": true } }, "type": "object", "required": [ "file_id" ], "title": "DeprecatedStoreFileUpsertParams" }, "StoreFileConfig": { "properties": { "parsing_strategy": { "$ref": "#/components/schemas/StoreFileParsingStrategy", "description": "Strategy for adding the file, this overrides the store-level default", "default": "fast" } }, "type": "object", "title": "StoreFileConfig", "description": "Configuration for a file." }, "StoreFileParsingStrategy": { "type": "string", "enum": [ "fast", "high_quality" ], "title": "StoreFileParsingStrategy", "description": "Strategy for adding a file to a store." }, "StoreFile": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier for the file" }, "filename": { "type": "string", "title": "Filename", "description": "Name of the file" }, "metadata": { "anyOf": [ {}, { "type": "null" } ], "title": "Metadata", "description": "Optional file metadata" }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Id", "description": "External identifier for this file in the store" }, "status": { "$ref": "#/components/schemas/JobStatus", "description": "Processing status of the file", "default": "pending" }, "last_error": { "anyOf": [ {}, { "type": "null" } ], "title": "Last Error", "description": "Last error message if processing failed" }, "store_id": { "type": "string", "title": "Store Id", "description": "ID of the containing store" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp of store file creation" }, "version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Version", "description": "Version number of the file", "examples": [ 1 ] }, "usage_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Usage Bytes", "description": "Storage usage in bytes", "examples": [ 51200 ] }, "usage_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Usage Tokens", "description": "Storage usage in tokens", "examples": [ 51200 ] }, "config": { "anyOf": [ { "$ref": "#/components/schemas/StoreFileConfig" }, { "type": "null" } ], "description": "Configuration for the file" }, "object": { "type": "string", "const": "store.file", "title": "Object", "description": "Type of the object", "default": "store.file" }, "chunks": { "anyOf": [ { "items": { "oneOf": [ { "$ref": "#/components/schemas/TextInputChunk" }, { "$ref": "#/components/schemas/ImageUrlInputChunk" }, { "$ref": "#/components/schemas/AudioUrlInputChunk" }, { "$ref": "#/components/schemas/VideoUrlInputChunk" } ], "discriminator": { "propertyName": "type", "mapping": { "audio_url": "#/components/schemas/AudioUrlInputChunk", "image_url": "#/components/schemas/ImageUrlInputChunk", "text": "#/components/schemas/TextInputChunk", "video_url": "#/components/schemas/VideoUrlInputChunk" } } }, "type": "array" }, { "type": "null" } ], "title": "Chunks", "description": "chunks" }, "content_url": { "type": "string", "title": "Content Url", "description": "Presigned URL for file content" } }, "type": "object", "required": [ "id", "store_id", "created_at", "content_url" ], "title": "StoreFile", "description": "Represents a file stored in a store." }, "JobStatus": { "type": "string", "enum": [ "pending", "in_progress", "cancelled", "completed", "failed" ], "title": "JobStatus", "description": "The lifecycle of a unit of background work.\n\nOne vocabulary for every job family. The database keeps a separate enum type\nper table (``parsing_job_status``, ``store_file_status``, ...) but they all\ncarry these values, so the aliases below are this enum rather than copies of\nit. :class:`SyncStatus` is this set plus ``IDLE`` for connectors, which have\na resting state between runs." }, "TextInputChunk": { "properties": { "chunk_index": { "type": "integer", "title": "Chunk Index", "description": "position of the chunk in a file", "examples": [ 0, 1, 2, 3, 4 ] }, "mime_type": { "type": "string", "title": "Mime Type", "description": "mime type of the chunk", "default": "text/plain", "examples": [ "text/plain" ] }, "generated_metadata": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/MarkdownChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/TextChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/EmailChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CsvChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/PDFChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CodeChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/AudioChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/VideoChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/ImageChunkGeneratedMetadata" } ], "discriminator": { "propertyName": "type", "mapping": { "audio": "#/components/schemas/AudioChunkGeneratedMetadata", "code": "#/components/schemas/CodeChunkGeneratedMetadata", "csv": "#/components/schemas/CsvChunkGeneratedMetadata", "email": "#/components/schemas/EmailChunkGeneratedMetadata", "image": "#/components/schemas/ImageChunkGeneratedMetadata", "markdown": "#/components/schemas/MarkdownChunkGeneratedMetadata", "pdf": "#/components/schemas/PDFChunkGeneratedMetadata", "text": "#/components/schemas/TextChunkGeneratedMetadata", "video": "#/components/schemas/VideoChunkGeneratedMetadata" } } }, { "type": "null" } ], "title": "Generated Metadata", "description": "metadata of the chunk", "examples": [ { "file_size": 1024, "file_type": "text/plain", "language": "en", "type": "text", "word_count": 100 } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "model used for this chunk", "examples": [ "text-embedding-ada-002", "clip-vit-large-patch14" ] }, "type": { "type": "string", "const": "text", "title": "Type", "description": "Input type identifier", "default": "text" }, "offset": { "type": "integer", "title": "Offset", "description": "The offset of the text in the file relative to the start of the file.", "default": 0, "examples": [ 0, 13, 42 ] }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text", "description": "Text content" }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context", "description": "LLM-generated context that situates this chunk within its source document", "examples": [ "This chunk is from an SEC filing on ACME corp's Q2 2023 performance." ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "summary of the text chunk", "examples": [ "A short overview of ACME's Q2 2023 performance." ] } }, "type": "object", "required": [ "chunk_index" ], "title": "TextInputChunk" }, "MarkdownChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "markdown", "title": "Type", "default": "markdown" }, "file_type": { "type": "string", "const": "text/markdown", "title": "File Type", "default": "text/markdown" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "chunk_headings": { "items": { "$ref": "#/components/schemas/MarkdownHeading" }, "type": "array", "title": "Chunk Headings" }, "heading_context": { "items": { "$ref": "#/components/schemas/MarkdownHeading" }, "type": "array", "title": "Heading Context" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" }, "frontmatter": { "additionalProperties": true, "type": "object", "title": "Frontmatter" } }, "additionalProperties": true, "type": "object", "title": "MarkdownChunkGeneratedMetadata" }, "MarkdownHeading": { "properties": { "level": { "type": "integer", "title": "Level" }, "text": { "type": "string", "title": "Text" } }, "type": "object", "required": [ "level", "text" ], "title": "MarkdownHeading" }, "TextChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "text", "title": "Type", "default": "text" }, "file_type": { "type": "string", "enum": [ "text/plain", "message/rfc822" ], "title": "File Type", "default": "text/plain" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "title": "TextChunkGeneratedMetadata" }, "EmailChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "email", "title": "Type", "default": "email" }, "file_type": { "type": "string", "title": "File Type", "default": "message/rfc822" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subject" }, "from_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From Email" }, "to_emails": { "items": { "type": "string" }, "type": "array", "title": "To Emails" }, "cc_emails": { "items": { "type": "string" }, "type": "array", "title": "Cc Emails" }, "bcc_emails": { "items": { "type": "string" }, "type": "array", "title": "Bcc Emails" }, "date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Date" }, "attachment_names": { "items": { "type": "string" }, "type": "array", "title": "Attachment Names" } }, "additionalProperties": true, "type": "object", "title": "EmailChunkGeneratedMetadata" }, "CsvChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "csv", "title": "Type", "default": "csv" }, "file_type": { "type": "string", "const": "text/csv", "title": "File Type", "default": "text/csv" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "start_row": { "type": "integer", "title": "Start Row", "default": 0 }, "num_rows": { "type": "integer", "title": "Num Rows", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "title": "CsvChunkGeneratedMetadata" }, "PDFChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "pdf", "title": "Type", "default": "pdf" }, "file_type": { "type": "string", "const": "application/pdf", "title": "File Type", "default": "application/pdf" }, "total_pages": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Pages" }, "total_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Size" }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" }, "layout": { "anyOf": [ { "$ref": "#/components/schemas/LayoutMetadata" }, { "type": "null" } ] } }, "additionalProperties": true, "type": "object", "title": "PDFChunkGeneratedMetadata" }, "LayoutMetadata": { "properties": { "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Width" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Height" }, "elements": { "items": { "$ref": "#/components/schemas/LayoutElement" }, "type": "array", "title": "Elements" } }, "type": "object", "title": "LayoutMetadata", "description": "Per-page layout for chunks parsed in high-quality (visual) mode.\n\n``elements`` are ordered by reading order (list position == reading order).\n``width``/``height`` are the page-image dimensions the ``bbox`` coords are\nrelative to, so consumers can normalize/render without a second fetch.\n\nLayout is part of the generated metadata payload and is returned with the\nchunk whenever present." }, "LayoutElement": { "properties": { "bbox": { "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" }, { "type": "number" } ], "type": "array", "maxItems": 4, "minItems": 4, "title": "Bbox" }, "type": { "type": "string", "title": "Type" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text" } }, "type": "object", "required": [ "bbox", "type" ], "title": "LayoutElement", "description": "A single detected layout element and its location on the page image." }, "CodeChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "code", "title": "Type", "default": "code" }, "file_type": { "type": "string", "title": "File Type" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "required": [ "file_type" ], "title": "CodeChunkGeneratedMetadata" }, "AudioChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "audio", "title": "Type", "default": "audio" }, "file_type": { "type": "string", "title": "File Type", "default": "audio/mpeg" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "total_duration_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Duration Seconds" }, "sample_rate": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Sample Rate" }, "channels": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Channels" }, "audio_format": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Audio Format" }, "bpm": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bpm" }, "speakers": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Speakers" }, "speaker_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Speaker Count" }, "speaker_turns": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SpeakerTurn" }, "type": "array" }, { "type": "null" } ], "title": "Speaker Turns" }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "title": "AudioChunkGeneratedMetadata" }, "SpeakerTurn": { "properties": { "speaker": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Speaker" }, "text": { "type": "string", "title": "Text" }, "start_time_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Start Time Seconds" }, "end_time_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "End Time Seconds" } }, "type": "object", "required": [ "text" ], "title": "SpeakerTurn" }, "VideoChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "video", "title": "Type", "default": "video" }, "file_type": { "type": "string", "title": "File Type", "default": "video/mp4" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "total_duration_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Duration Seconds" }, "fps": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Fps" }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Width" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Height" }, "frame_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Frame Count" }, "has_audio_stream": { "type": "boolean", "title": "Has Audio Stream", "default": false }, "bpm": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bpm" }, "speakers": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Speakers" }, "speaker_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Speaker Count" }, "speaker_turns": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SpeakerTurn" }, "type": "array" }, { "type": "null" } ], "title": "Speaker Turns" }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "title": "VideoChunkGeneratedMetadata" }, "ImageChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "image", "title": "Type", "default": "image" }, "file_type": { "type": "string", "title": "File Type", "default": "image/jpeg" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Width" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Height" }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" }, "layout": { "anyOf": [ { "$ref": "#/components/schemas/LayoutMetadata" }, { "type": "null" } ] } }, "additionalProperties": true, "type": "object", "title": "ImageChunkGeneratedMetadata" }, "ImageUrlInputChunk": { "properties": { "chunk_index": { "type": "integer", "title": "Chunk Index", "description": "position of the chunk in a file", "examples": [ 0, 1, 2, 3, 4 ] }, "mime_type": { "type": "string", "title": "Mime Type", "description": "mime type of the chunk", "default": "image/jpeg", "examples": [ "image/jpeg" ] }, "generated_metadata": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/MarkdownChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/TextChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/EmailChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CsvChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/PDFChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CodeChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/AudioChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/VideoChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/ImageChunkGeneratedMetadata" } ], "discriminator": { "propertyName": "type", "mapping": { "audio": "#/components/schemas/AudioChunkGeneratedMetadata", "code": "#/components/schemas/CodeChunkGeneratedMetadata", "csv": "#/components/schemas/CsvChunkGeneratedMetadata", "email": "#/components/schemas/EmailChunkGeneratedMetadata", "image": "#/components/schemas/ImageChunkGeneratedMetadata", "markdown": "#/components/schemas/MarkdownChunkGeneratedMetadata", "pdf": "#/components/schemas/PDFChunkGeneratedMetadata", "text": "#/components/schemas/TextChunkGeneratedMetadata", "video": "#/components/schemas/VideoChunkGeneratedMetadata" } } }, { "type": "null" } ], "title": "Generated Metadata", "description": "metadata of the chunk", "examples": [ { "file_size": 1024, "file_type": "text/plain", "language": "en", "type": "text", "word_count": 100 } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "model used for this chunk", "examples": [ "text-embedding-ada-002", "clip-vit-large-patch14" ] }, "type": { "type": "string", "const": "image_url", "title": "Type", "description": "Input type identifier", "default": "image_url" }, "ocr_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ocr Text", "description": "ocr text of the image", "examples": [ "2025 Financial Report" ] }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context", "description": "LLM-generated context that situates this image within its source document", "examples": [ "This page contains ACME's Q2 2023 financial results." ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "summary of the image", "examples": [ "A financial report for 2025" ] }, "image_url": { "anyOf": [ { "$ref": "#/components/schemas/ImageUrl-Output" }, { "type": "null" } ], "description": "Image URL" } }, "type": "object", "required": [ "chunk_index" ], "title": "ImageUrlInputChunk" }, "ImageUrl-Output": { "properties": { "url": { "type": "string", "title": "Url", "description": "The image URL. Can be either a URL or a Data URI." }, "format": { "type": "string", "title": "Format", "description": "The image format/mimetype", "default": "" } }, "type": "object", "required": [ "url" ], "title": "ImageUrl", "description": "Model for image URL validation." }, "AudioUrlInputChunk": { "properties": { "chunk_index": { "type": "integer", "title": "Chunk Index", "description": "position of the chunk in a file", "examples": [ 0, 1, 2, 3, 4 ] }, "mime_type": { "type": "string", "title": "Mime Type", "description": "mime type of the chunk", "default": "audio/mpeg", "examples": [ "audio/mpeg" ] }, "generated_metadata": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/MarkdownChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/TextChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/EmailChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CsvChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/PDFChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CodeChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/AudioChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/VideoChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/ImageChunkGeneratedMetadata" } ], "discriminator": { "propertyName": "type", "mapping": { "audio": "#/components/schemas/AudioChunkGeneratedMetadata", "code": "#/components/schemas/CodeChunkGeneratedMetadata", "csv": "#/components/schemas/CsvChunkGeneratedMetadata", "email": "#/components/schemas/EmailChunkGeneratedMetadata", "image": "#/components/schemas/ImageChunkGeneratedMetadata", "markdown": "#/components/schemas/MarkdownChunkGeneratedMetadata", "pdf": "#/components/schemas/PDFChunkGeneratedMetadata", "text": "#/components/schemas/TextChunkGeneratedMetadata", "video": "#/components/schemas/VideoChunkGeneratedMetadata" } } }, { "type": "null" } ], "title": "Generated Metadata", "description": "metadata of the chunk", "examples": [ { "file_size": 1024, "file_type": "text/plain", "language": "en", "type": "text", "word_count": 100 } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "model used for this chunk", "examples": [ "text-embedding-ada-002", "clip-vit-large-patch14" ] }, "type": { "type": "string", "const": "audio_url", "title": "Type", "description": "Input type identifier", "default": "audio_url" }, "transcription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transcription", "description": "speech recognition (sr) text of the audio", "examples": [ "The year 2025 reports for .." ] }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context", "description": "LLM-generated context that situates this audio chunk within its source file", "examples": [ "This segment introduces ACME's quarterly earnings call." ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "summary of the audio", "examples": [ "A financial report audio for 2025" ] }, "audio_url": { "anyOf": [ { "$ref": "#/components/schemas/AudioUrl" }, { "type": "null" } ], "description": "Audio URL" }, "sampling_rate": { "type": "integer", "title": "Sampling Rate", "description": "The sampling rate of the audio." } }, "type": "object", "required": [ "chunk_index", "sampling_rate" ], "title": "AudioUrlInputChunk" }, "AudioUrl": { "properties": { "url": { "type": "string", "title": "Url", "description": "The audio URL. Can be either a URL or a Data URI." } }, "type": "object", "required": [ "url" ], "title": "AudioUrl", "description": "Model for audio URL validation." }, "VideoUrlInputChunk": { "properties": { "chunk_index": { "type": "integer", "title": "Chunk Index", "description": "position of the chunk in a file", "examples": [ 0, 1, 2, 3, 4 ] }, "mime_type": { "type": "string", "title": "Mime Type", "description": "mime type of the chunk", "default": "video/mp4", "examples": [ "video/mp4" ] }, "generated_metadata": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/MarkdownChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/TextChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/EmailChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CsvChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/PDFChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CodeChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/AudioChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/VideoChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/ImageChunkGeneratedMetadata" } ], "discriminator": { "propertyName": "type", "mapping": { "audio": "#/components/schemas/AudioChunkGeneratedMetadata", "code": "#/components/schemas/CodeChunkGeneratedMetadata", "csv": "#/components/schemas/CsvChunkGeneratedMetadata", "email": "#/components/schemas/EmailChunkGeneratedMetadata", "image": "#/components/schemas/ImageChunkGeneratedMetadata", "markdown": "#/components/schemas/MarkdownChunkGeneratedMetadata", "pdf": "#/components/schemas/PDFChunkGeneratedMetadata", "text": "#/components/schemas/TextChunkGeneratedMetadata", "video": "#/components/schemas/VideoChunkGeneratedMetadata" } } }, { "type": "null" } ], "title": "Generated Metadata", "description": "metadata of the chunk", "examples": [ { "file_size": 1024, "file_type": "text/plain", "language": "en", "type": "text", "word_count": 100 } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "model used for this chunk", "examples": [ "text-embedding-ada-002", "clip-vit-large-patch14" ] }, "type": { "type": "string", "const": "video_url", "title": "Type", "description": "Input type identifier", "default": "video_url" }, "transcription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transcription", "description": "speech recognition (sr) text of the video", "examples": [ "The year 2025 reports for .." ] }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context", "description": "LLM-generated context that situates this video chunk within its source file", "examples": [ "This segment demonstrates the product's document search workflow." ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "summary of the video", "examples": [ "A financial report video for 2025" ] }, "video_url": { "anyOf": [ { "$ref": "#/components/schemas/VideoUrl" }, { "type": "null" } ], "description": "Video URL" } }, "type": "object", "required": [ "chunk_index" ], "title": "VideoUrlInputChunk" }, "VideoUrl": { "properties": { "url": { "type": "string", "title": "Url", "description": "The video URL. Can be either a URL or a Data URI." } }, "type": "object", "required": [ "url" ], "title": "VideoUrl", "description": "Model for video URL validation." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") file = mxbai.stores.files.create( "my-knowledge-base", file_id="f47ac10b-58cc-4372-a567-0e02b2c3d479", metadata={"category": "documentation"}, ) print(file) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") file = await mxbai.stores.files.create( "my-knowledge-base", file_id="f47ac10b-58cc-4372-a567-0e02b2c3d479", metadata={"category": "documentation"}, ) print(file) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const file = await mxbai.stores.files.create("my-knowledge-base", { file_id: "f47ac10b-58cc-4372-a567-0e02b2c3d479", metadata: { category: "documentation" }, }); console.log(file); ``` cURL: ```bash curl -X POST https://api.mixedbread.com/v1/stores/my-knowledge-base/files \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -d '{ "file_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "metadata": {"category": "documentation"} }' ``` # Delete Store File URL: https://www.mixedbread.com/api-reference/endpoints/stores/files/delete-store-file Delete a file from a store. ```json { "paths": { "/v1/stores/{store_identifier}/files/{file_identifier}": { "delete": { "tags": [ "stores" ], "summary": "Delete Store File", "operationId": "delete_store_file", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "store_identifier", "in": "path", "required": true, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ], "description": "The ID or name of the store", "title": "Store Identifier" }, "description": "The ID or name of the store" }, { "name": "file_identifier", "in": "path", "required": true, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ], "description": "The ID or name of the file to delete", "title": "File Identifier" }, "description": "The ID or name of the file to delete" } ], "responses": { "200": { "description": "The deleted store file details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreFileDeleted" }, "example": { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "object": "store.file", "deleted": true } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "StoreFileDeleted": { "properties": { "id": { "type": "string", "title": "Id", "description": "ID of the deleted file" }, "deleted": { "type": "boolean", "title": "Deleted", "description": "Whether the deletion was successful", "default": true }, "object": { "type": "string", "const": "store.file", "title": "Object", "description": "Type of the deleted object", "default": "store.file" } }, "type": "object", "required": [ "id" ], "title": "StoreFileDeleted", "description": "Response model for file deletion." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` Python: ```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 (async): ```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: ```ts 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); ``` cURL: ```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' ``` # Get Store File URL: https://www.mixedbread.com/api-reference/endpoints/stores/files/get-store-file Get details of a specific file in a store. ```json { "paths": { "/v1/stores/{store_identifier}/files/{file_identifier}": { "get": { "tags": [ "stores" ], "summary": "Get Store File", "operationId": "retrieve_store_file", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "store_identifier", "in": "path", "required": true, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ], "description": "The ID or name of the store", "title": "Store Identifier" }, "description": "The ID or name of the store" }, { "name": "file_identifier", "in": "path", "required": true, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ], "description": "The ID or name of the file", "title": "File Identifier" }, "description": "The ID or name of the file" }, { "name": "return_chunks", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "array", "items": { "type": "integer" } } ], "description": "Whether to return the chunks for the file. If a list of integers is provided, only the chunks at the specified indices will be returned.", "default": false, "title": "Return Chunks" }, "description": "Whether to return the chunks for the file. If a list of integers is provided, only the chunks at the specified indices will be returned." } ], "responses": { "200": { "description": "The store file details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreFile" }, "example": { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "external_id": "ext-doc-001", "object": "store.file", "filename": "example_document.pdf", "metadata": { "category": "documentation" }, "status": "completed", "last_error": null, "store_id": "c3d4e5f6-a7b8-9012-cdef-345678901234", "usage_bytes": 1048576, "usage_tokens": 51200, "config": { "parsing_strategy": "fast" }, "version": 1, "created_at": "2025-01-15T16:00:00.000Z", "content_url": "https://example.com/files/f47ac10b-58cc-4372-a567-0e02b2c3d479?signature=..." } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "StoreFile": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier for the file" }, "filename": { "type": "string", "title": "Filename", "description": "Name of the file" }, "metadata": { "anyOf": [ {}, { "type": "null" } ], "title": "Metadata", "description": "Optional file metadata" }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Id", "description": "External identifier for this file in the store" }, "status": { "$ref": "#/components/schemas/JobStatus", "description": "Processing status of the file", "default": "pending" }, "last_error": { "anyOf": [ {}, { "type": "null" } ], "title": "Last Error", "description": "Last error message if processing failed" }, "store_id": { "type": "string", "title": "Store Id", "description": "ID of the containing store" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp of store file creation" }, "version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Version", "description": "Version number of the file", "examples": [ 1 ] }, "usage_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Usage Bytes", "description": "Storage usage in bytes", "examples": [ 51200 ] }, "usage_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Usage Tokens", "description": "Storage usage in tokens", "examples": [ 51200 ] }, "config": { "anyOf": [ { "$ref": "#/components/schemas/StoreFileConfig" }, { "type": "null" } ], "description": "Configuration for the file" }, "object": { "type": "string", "const": "store.file", "title": "Object", "description": "Type of the object", "default": "store.file" }, "chunks": { "anyOf": [ { "items": { "oneOf": [ { "$ref": "#/components/schemas/TextInputChunk" }, { "$ref": "#/components/schemas/ImageUrlInputChunk" }, { "$ref": "#/components/schemas/AudioUrlInputChunk" }, { "$ref": "#/components/schemas/VideoUrlInputChunk" } ], "discriminator": { "propertyName": "type", "mapping": { "audio_url": "#/components/schemas/AudioUrlInputChunk", "image_url": "#/components/schemas/ImageUrlInputChunk", "text": "#/components/schemas/TextInputChunk", "video_url": "#/components/schemas/VideoUrlInputChunk" } } }, "type": "array" }, { "type": "null" } ], "title": "Chunks", "description": "chunks" }, "content_url": { "type": "string", "title": "Content Url", "description": "Presigned URL for file content" } }, "type": "object", "required": [ "id", "store_id", "created_at", "content_url" ], "title": "StoreFile", "description": "Represents a file stored in a store." }, "JobStatus": { "type": "string", "enum": [ "pending", "in_progress", "cancelled", "completed", "failed" ], "title": "JobStatus", "description": "The lifecycle of a unit of background work.\n\nOne vocabulary for every job family. The database keeps a separate enum type\nper table (``parsing_job_status``, ``store_file_status``, ...) but they all\ncarry these values, so the aliases below are this enum rather than copies of\nit. :class:`SyncStatus` is this set plus ``IDLE`` for connectors, which have\na resting state between runs." }, "StoreFileConfig": { "properties": { "parsing_strategy": { "$ref": "#/components/schemas/StoreFileParsingStrategy", "description": "Strategy for adding the file, this overrides the store-level default", "default": "fast" } }, "type": "object", "title": "StoreFileConfig", "description": "Configuration for a file." }, "StoreFileParsingStrategy": { "type": "string", "enum": [ "fast", "high_quality" ], "title": "StoreFileParsingStrategy", "description": "Strategy for adding a file to a store." }, "TextInputChunk": { "properties": { "chunk_index": { "type": "integer", "title": "Chunk Index", "description": "position of the chunk in a file", "examples": [ 0, 1, 2, 3, 4 ] }, "mime_type": { "type": "string", "title": "Mime Type", "description": "mime type of the chunk", "default": "text/plain", "examples": [ "text/plain" ] }, "generated_metadata": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/MarkdownChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/TextChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/EmailChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CsvChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/PDFChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CodeChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/AudioChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/VideoChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/ImageChunkGeneratedMetadata" } ], "discriminator": { "propertyName": "type", "mapping": { "audio": "#/components/schemas/AudioChunkGeneratedMetadata", "code": "#/components/schemas/CodeChunkGeneratedMetadata", "csv": "#/components/schemas/CsvChunkGeneratedMetadata", "email": "#/components/schemas/EmailChunkGeneratedMetadata", "image": "#/components/schemas/ImageChunkGeneratedMetadata", "markdown": "#/components/schemas/MarkdownChunkGeneratedMetadata", "pdf": "#/components/schemas/PDFChunkGeneratedMetadata", "text": "#/components/schemas/TextChunkGeneratedMetadata", "video": "#/components/schemas/VideoChunkGeneratedMetadata" } } }, { "type": "null" } ], "title": "Generated Metadata", "description": "metadata of the chunk", "examples": [ { "file_size": 1024, "file_type": "text/plain", "language": "en", "type": "text", "word_count": 100 } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "model used for this chunk", "examples": [ "text-embedding-ada-002", "clip-vit-large-patch14" ] }, "type": { "type": "string", "const": "text", "title": "Type", "description": "Input type identifier", "default": "text" }, "offset": { "type": "integer", "title": "Offset", "description": "The offset of the text in the file relative to the start of the file.", "default": 0, "examples": [ 0, 13, 42 ] }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text", "description": "Text content" }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context", "description": "LLM-generated context that situates this chunk within its source document", "examples": [ "This chunk is from an SEC filing on ACME corp's Q2 2023 performance." ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "summary of the text chunk", "examples": [ "A short overview of ACME's Q2 2023 performance." ] } }, "type": "object", "required": [ "chunk_index" ], "title": "TextInputChunk" }, "MarkdownChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "markdown", "title": "Type", "default": "markdown" }, "file_type": { "type": "string", "const": "text/markdown", "title": "File Type", "default": "text/markdown" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "chunk_headings": { "items": { "$ref": "#/components/schemas/MarkdownHeading" }, "type": "array", "title": "Chunk Headings" }, "heading_context": { "items": { "$ref": "#/components/schemas/MarkdownHeading" }, "type": "array", "title": "Heading Context" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" }, "frontmatter": { "additionalProperties": true, "type": "object", "title": "Frontmatter" } }, "additionalProperties": true, "type": "object", "title": "MarkdownChunkGeneratedMetadata" }, "MarkdownHeading": { "properties": { "level": { "type": "integer", "title": "Level" }, "text": { "type": "string", "title": "Text" } }, "type": "object", "required": [ "level", "text" ], "title": "MarkdownHeading" }, "TextChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "text", "title": "Type", "default": "text" }, "file_type": { "type": "string", "enum": [ "text/plain", "message/rfc822" ], "title": "File Type", "default": "text/plain" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "title": "TextChunkGeneratedMetadata" }, "EmailChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "email", "title": "Type", "default": "email" }, "file_type": { "type": "string", "title": "File Type", "default": "message/rfc822" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subject" }, "from_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From Email" }, "to_emails": { "items": { "type": "string" }, "type": "array", "title": "To Emails" }, "cc_emails": { "items": { "type": "string" }, "type": "array", "title": "Cc Emails" }, "bcc_emails": { "items": { "type": "string" }, "type": "array", "title": "Bcc Emails" }, "date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Date" }, "attachment_names": { "items": { "type": "string" }, "type": "array", "title": "Attachment Names" } }, "additionalProperties": true, "type": "object", "title": "EmailChunkGeneratedMetadata" }, "CsvChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "csv", "title": "Type", "default": "csv" }, "file_type": { "type": "string", "const": "text/csv", "title": "File Type", "default": "text/csv" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "start_row": { "type": "integer", "title": "Start Row", "default": 0 }, "num_rows": { "type": "integer", "title": "Num Rows", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "title": "CsvChunkGeneratedMetadata" }, "PDFChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "pdf", "title": "Type", "default": "pdf" }, "file_type": { "type": "string", "const": "application/pdf", "title": "File Type", "default": "application/pdf" }, "total_pages": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Pages" }, "total_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Size" }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" }, "layout": { "anyOf": [ { "$ref": "#/components/schemas/LayoutMetadata" }, { "type": "null" } ] } }, "additionalProperties": true, "type": "object", "title": "PDFChunkGeneratedMetadata" }, "LayoutMetadata": { "properties": { "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Width" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Height" }, "elements": { "items": { "$ref": "#/components/schemas/LayoutElement" }, "type": "array", "title": "Elements" } }, "type": "object", "title": "LayoutMetadata", "description": "Per-page layout for chunks parsed in high-quality (visual) mode.\n\n``elements`` are ordered by reading order (list position == reading order).\n``width``/``height`` are the page-image dimensions the ``bbox`` coords are\nrelative to, so consumers can normalize/render without a second fetch.\n\nLayout is part of the generated metadata payload and is returned with the\nchunk whenever present." }, "LayoutElement": { "properties": { "bbox": { "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" }, { "type": "number" } ], "type": "array", "maxItems": 4, "minItems": 4, "title": "Bbox" }, "type": { "type": "string", "title": "Type" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text" } }, "type": "object", "required": [ "bbox", "type" ], "title": "LayoutElement", "description": "A single detected layout element and its location on the page image." }, "CodeChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "code", "title": "Type", "default": "code" }, "file_type": { "type": "string", "title": "File Type" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "required": [ "file_type" ], "title": "CodeChunkGeneratedMetadata" }, "AudioChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "audio", "title": "Type", "default": "audio" }, "file_type": { "type": "string", "title": "File Type", "default": "audio/mpeg" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "total_duration_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Duration Seconds" }, "sample_rate": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Sample Rate" }, "channels": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Channels" }, "audio_format": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Audio Format" }, "bpm": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bpm" }, "speakers": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Speakers" }, "speaker_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Speaker Count" }, "speaker_turns": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SpeakerTurn" }, "type": "array" }, { "type": "null" } ], "title": "Speaker Turns" }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "title": "AudioChunkGeneratedMetadata" }, "SpeakerTurn": { "properties": { "speaker": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Speaker" }, "text": { "type": "string", "title": "Text" }, "start_time_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Start Time Seconds" }, "end_time_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "End Time Seconds" } }, "type": "object", "required": [ "text" ], "title": "SpeakerTurn" }, "VideoChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "video", "title": "Type", "default": "video" }, "file_type": { "type": "string", "title": "File Type", "default": "video/mp4" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "total_duration_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Duration Seconds" }, "fps": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Fps" }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Width" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Height" }, "frame_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Frame Count" }, "has_audio_stream": { "type": "boolean", "title": "Has Audio Stream", "default": false }, "bpm": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bpm" }, "speakers": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Speakers" }, "speaker_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Speaker Count" }, "speaker_turns": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SpeakerTurn" }, "type": "array" }, { "type": "null" } ], "title": "Speaker Turns" }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "title": "VideoChunkGeneratedMetadata" }, "ImageChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "image", "title": "Type", "default": "image" }, "file_type": { "type": "string", "title": "File Type", "default": "image/jpeg" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Width" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Height" }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" }, "layout": { "anyOf": [ { "$ref": "#/components/schemas/LayoutMetadata" }, { "type": "null" } ] } }, "additionalProperties": true, "type": "object", "title": "ImageChunkGeneratedMetadata" }, "ImageUrlInputChunk": { "properties": { "chunk_index": { "type": "integer", "title": "Chunk Index", "description": "position of the chunk in a file", "examples": [ 0, 1, 2, 3, 4 ] }, "mime_type": { "type": "string", "title": "Mime Type", "description": "mime type of the chunk", "default": "image/jpeg", "examples": [ "image/jpeg" ] }, "generated_metadata": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/MarkdownChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/TextChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/EmailChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CsvChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/PDFChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CodeChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/AudioChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/VideoChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/ImageChunkGeneratedMetadata" } ], "discriminator": { "propertyName": "type", "mapping": { "audio": "#/components/schemas/AudioChunkGeneratedMetadata", "code": "#/components/schemas/CodeChunkGeneratedMetadata", "csv": "#/components/schemas/CsvChunkGeneratedMetadata", "email": "#/components/schemas/EmailChunkGeneratedMetadata", "image": "#/components/schemas/ImageChunkGeneratedMetadata", "markdown": "#/components/schemas/MarkdownChunkGeneratedMetadata", "pdf": "#/components/schemas/PDFChunkGeneratedMetadata", "text": "#/components/schemas/TextChunkGeneratedMetadata", "video": "#/components/schemas/VideoChunkGeneratedMetadata" } } }, { "type": "null" } ], "title": "Generated Metadata", "description": "metadata of the chunk", "examples": [ { "file_size": 1024, "file_type": "text/plain", "language": "en", "type": "text", "word_count": 100 } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "model used for this chunk", "examples": [ "text-embedding-ada-002", "clip-vit-large-patch14" ] }, "type": { "type": "string", "const": "image_url", "title": "Type", "description": "Input type identifier", "default": "image_url" }, "ocr_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ocr Text", "description": "ocr text of the image", "examples": [ "2025 Financial Report" ] }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context", "description": "LLM-generated context that situates this image within its source document", "examples": [ "This page contains ACME's Q2 2023 financial results." ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "summary of the image", "examples": [ "A financial report for 2025" ] }, "image_url": { "anyOf": [ { "$ref": "#/components/schemas/ImageUrl-Output" }, { "type": "null" } ], "description": "Image URL" } }, "type": "object", "required": [ "chunk_index" ], "title": "ImageUrlInputChunk" }, "ImageUrl-Output": { "properties": { "url": { "type": "string", "title": "Url", "description": "The image URL. Can be either a URL or a Data URI." }, "format": { "type": "string", "title": "Format", "description": "The image format/mimetype", "default": "" } }, "type": "object", "required": [ "url" ], "title": "ImageUrl", "description": "Model for image URL validation." }, "AudioUrlInputChunk": { "properties": { "chunk_index": { "type": "integer", "title": "Chunk Index", "description": "position of the chunk in a file", "examples": [ 0, 1, 2, 3, 4 ] }, "mime_type": { "type": "string", "title": "Mime Type", "description": "mime type of the chunk", "default": "audio/mpeg", "examples": [ "audio/mpeg" ] }, "generated_metadata": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/MarkdownChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/TextChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/EmailChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CsvChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/PDFChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CodeChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/AudioChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/VideoChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/ImageChunkGeneratedMetadata" } ], "discriminator": { "propertyName": "type", "mapping": { "audio": "#/components/schemas/AudioChunkGeneratedMetadata", "code": "#/components/schemas/CodeChunkGeneratedMetadata", "csv": "#/components/schemas/CsvChunkGeneratedMetadata", "email": "#/components/schemas/EmailChunkGeneratedMetadata", "image": "#/components/schemas/ImageChunkGeneratedMetadata", "markdown": "#/components/schemas/MarkdownChunkGeneratedMetadata", "pdf": "#/components/schemas/PDFChunkGeneratedMetadata", "text": "#/components/schemas/TextChunkGeneratedMetadata", "video": "#/components/schemas/VideoChunkGeneratedMetadata" } } }, { "type": "null" } ], "title": "Generated Metadata", "description": "metadata of the chunk", "examples": [ { "file_size": 1024, "file_type": "text/plain", "language": "en", "type": "text", "word_count": 100 } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "model used for this chunk", "examples": [ "text-embedding-ada-002", "clip-vit-large-patch14" ] }, "type": { "type": "string", "const": "audio_url", "title": "Type", "description": "Input type identifier", "default": "audio_url" }, "transcription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transcription", "description": "speech recognition (sr) text of the audio", "examples": [ "The year 2025 reports for .." ] }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context", "description": "LLM-generated context that situates this audio chunk within its source file", "examples": [ "This segment introduces ACME's quarterly earnings call." ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "summary of the audio", "examples": [ "A financial report audio for 2025" ] }, "audio_url": { "anyOf": [ { "$ref": "#/components/schemas/AudioUrl" }, { "type": "null" } ], "description": "Audio URL" }, "sampling_rate": { "type": "integer", "title": "Sampling Rate", "description": "The sampling rate of the audio." } }, "type": "object", "required": [ "chunk_index", "sampling_rate" ], "title": "AudioUrlInputChunk" }, "AudioUrl": { "properties": { "url": { "type": "string", "title": "Url", "description": "The audio URL. Can be either a URL or a Data URI." } }, "type": "object", "required": [ "url" ], "title": "AudioUrl", "description": "Model for audio URL validation." }, "VideoUrlInputChunk": { "properties": { "chunk_index": { "type": "integer", "title": "Chunk Index", "description": "position of the chunk in a file", "examples": [ 0, 1, 2, 3, 4 ] }, "mime_type": { "type": "string", "title": "Mime Type", "description": "mime type of the chunk", "default": "video/mp4", "examples": [ "video/mp4" ] }, "generated_metadata": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/MarkdownChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/TextChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/EmailChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CsvChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/PDFChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CodeChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/AudioChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/VideoChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/ImageChunkGeneratedMetadata" } ], "discriminator": { "propertyName": "type", "mapping": { "audio": "#/components/schemas/AudioChunkGeneratedMetadata", "code": "#/components/schemas/CodeChunkGeneratedMetadata", "csv": "#/components/schemas/CsvChunkGeneratedMetadata", "email": "#/components/schemas/EmailChunkGeneratedMetadata", "image": "#/components/schemas/ImageChunkGeneratedMetadata", "markdown": "#/components/schemas/MarkdownChunkGeneratedMetadata", "pdf": "#/components/schemas/PDFChunkGeneratedMetadata", "text": "#/components/schemas/TextChunkGeneratedMetadata", "video": "#/components/schemas/VideoChunkGeneratedMetadata" } } }, { "type": "null" } ], "title": "Generated Metadata", "description": "metadata of the chunk", "examples": [ { "file_size": 1024, "file_type": "text/plain", "language": "en", "type": "text", "word_count": 100 } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "model used for this chunk", "examples": [ "text-embedding-ada-002", "clip-vit-large-patch14" ] }, "type": { "type": "string", "const": "video_url", "title": "Type", "description": "Input type identifier", "default": "video_url" }, "transcription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transcription", "description": "speech recognition (sr) text of the video", "examples": [ "The year 2025 reports for .." ] }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context", "description": "LLM-generated context that situates this video chunk within its source file", "examples": [ "This segment demonstrates the product's document search workflow." ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "summary of the video", "examples": [ "A financial report video for 2025" ] }, "video_url": { "anyOf": [ { "$ref": "#/components/schemas/VideoUrl" }, { "type": "null" } ], "description": "Video URL" } }, "type": "object", "required": [ "chunk_index" ], "title": "VideoUrlInputChunk" }, "VideoUrl": { "properties": { "url": { "type": "string", "title": "Url", "description": "The video URL. Can be either a URL or a Data URI." } }, "type": "object", "required": [ "url" ], "title": "VideoUrl", "description": "Model for video URL validation." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") file = mxbai.stores.files.retrieve( store_identifier="my-knowledge-base", file_identifier="f47ac10b-58cc-4372-a567-0e02b2c3d479", ) print(file) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") file = await mxbai.stores.files.retrieve( store_identifier="my-knowledge-base", file_identifier="f47ac10b-58cc-4372-a567-0e02b2c3d479", ) print(file) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const file = await mxbai.stores.files.retrieve("f47ac10b-58cc-4372-a567-0e02b2c3d479", { store_identifier: "my-knowledge-base", }); console.log(file); ``` cURL: ```bash curl https://api.mixedbread.com/v1/stores/my-knowledge-base/files/f47ac10b-58cc-4372-a567-0e02b2c3d479 \ -H 'Authorization: Bearer YOUR_API_KEY' ``` # List Store Files URL: https://www.mixedbread.com/api-reference/endpoints/stores/files/list-store-files List files indexed in a store with pagination and metadata filter. ```json { "paths": { "/v1/stores/{store_identifier}/files/list": { "post": { "tags": [ "stores" ], "summary": "List Store Files", "operationId": "list_store_files_with_metadata_filter", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "store_identifier", "in": "path", "required": true, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ], "description": "The ID or name of the store", "title": "Store Identifier" }, "description": "The ID or name of the store" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchCursorPagination", "description": "For pagination" } } } }, "responses": { "200": { "description": "List of files in the store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreFileListResponse" }, "example": { "object": "list", "data": [ { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "external_id": "ext-doc-001", "object": "store.file", "filename": "example_document.pdf", "status": "completed", "last_error": null, "store_id": "c3d4e5f6-a7b8-9012-cdef-345678901234", "usage_bytes": 1048576, "usage_tokens": 51200, "config": { "parsing_strategy": "fast" }, "version": 1, "created_at": "2025-01-15T14:00:00.000Z", "content_url": "https://example.com/files/f47ac10b-58cc-4372-a567-0e02b2c3d479?signature=...", "metadata": { "category": "documentation", "author": "John Doe" } }, { "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012", "external_id": "ext-doc-001", "object": "store.file", "filename": "api_reference.pdf", "status": "completed", "last_error": null, "store_id": "c3d4e5f6-a7b8-9012-cdef-345678901234", "usage_bytes": 524288, "usage_tokens": 51200, "config": { "parsing_strategy": "fast" }, "version": 1, "created_at": "2025-01-15T15:00:00.000Z", "content_url": "https://example.com/files/b2c3d4e5-f6a7-8901-bcde-f23456789012?signature=...", "metadata": { "category": "documentation", "author": "Jane Smith" } } ], "pagination": { "has_more": false, "first_cursor": "eyJpZCI6ImZpbGVfYWJjMTIzIn0=", "last_cursor": "eyJpZCI6ImZpbGVfZGVmNDU2In0=" } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "SearchCursorPagination": { "properties": { "limit": { "type": "integer", "maximum": 100, "minimum": 1, "title": "Limit", "description": "Maximum number of items to return per page (1-100)", "default": 20, "examples": [ 10, 20, 50 ] }, "after": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After", "description": "Cursor for forward pagination - get items after this position. Use last_cursor from previous response.", "examples": [ "eyJjcmVhdGVkX2F0IjoiMjAyNC0xMi0zMVQyMzo1OTo1OS4wMDBaIiwiaWQiOiJhYmMxMjMifQ==" ] }, "before": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Before", "description": "Cursor for backward pagination - get items before this position. Use first_cursor from previous response.", "examples": [ "eyJjcmVhdGVkX2F0IjoiMjAyNC0xMi0zMVQyMzo1OTo1OS4wMDBaIiwiaWQiOiJhYmMxMjMifQ==" ] }, "include_total": { "type": "boolean", "title": "Include Total", "description": "Whether to include total count in response (expensive operation)", "default": false, "examples": [ false, true ] }, "sort_by": { "type": "string", "enum": [ "created_at", "filename", "usage_bytes", "usage_tokens" ], "title": "Sort By", "description": "Field to order the files by", "default": "created_at", "examples": [ "created_at", "filename" ] }, "sort_order": { "type": "string", "enum": [ "asc", "desc" ], "title": "Sort Order", "description": "Direction of the sort", "default": "desc", "examples": [ "desc", "asc" ] }, "statuses": { "anyOf": [ { "items": { "$ref": "#/components/schemas/JobStatus" }, "type": "array" }, { "type": "null" } ], "title": "Statuses", "description": "Status to filter by" }, "metadata_filter": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" }, { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Metadata Filter", "description": "Metadata filter to apply to the query" }, "q": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ], "title": "Q", "description": "Search query for fuzzy matching over name and external_id fields" } }, "type": "object", "title": "SearchCursorPagination", "description": "Cursor pagination with status, metadata, and a search query." }, "JobStatus": { "type": "string", "enum": [ "pending", "in_progress", "cancelled", "completed", "failed" ], "title": "JobStatus", "description": "The lifecycle of a unit of background work.\n\nOne vocabulary for every job family. The database keeps a separate enum type\nper table (``parsing_job_status``, ``store_file_status``, ...) but they all\ncarry these values, so the aliases below are this enum rather than copies of\nit. :class:`SyncStatus` is this set plus ``IDLE`` for connectors, which have\na resting state between runs." }, "SearchFilter-Input": { "properties": { "all": { "anyOf": [ { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "All", "description": "List of conditions or filters to be ANDed together", "examples": [ [ { "key": "price", "operator": "gt", "value": "100" }, { "key": "color", "operator": "eq", "value": "red" } ], null ] }, "any": { "anyOf": [ { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Any", "description": "List of conditions or filters to be ORed together", "examples": [ [ { "key": "price", "operator": "gt", "value": "100" }, { "key": "color", "operator": "eq", "value": "red" } ], null ] }, "none": { "anyOf": [ { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "None", "description": "List of conditions or filters to be NOTed", "examples": [ [ { "key": "price", "operator": "gt", "value": "100" }, { "key": "color", "operator": "eq", "value": "red" } ], null ] } }, "type": "object", "title": "SearchFilter", "description": "Represents a filter with AND, OR, and NOT conditions." }, "SearchFilterCondition": { "properties": { "key": { "type": "string", "title": "Key", "description": "The field to apply the condition on", "examples": [ "price", "color" ] }, "value": { "title": "Value", "description": "The value to compare against", "examples": [ "100", "red" ] }, "operator": { "$ref": "#/components/schemas/ConditionOperator", "description": "The operator for the condition", "examples": [ "eq", "gt" ] } }, "type": "object", "required": [ "key", "value", "operator" ], "title": "SearchFilterCondition", "description": "Represents a condition with a field, operator, and value." }, "ConditionOperator": { "type": "string", "enum": [ "eq", "not_eq", "gt", "gte", "lt", "lte", "in", "not_in", "like", "contains", "starts_with", "not_like", "regex" ], "title": "ConditionOperator", "description": "Operator for a filter condition." }, "StoreFileListResponse": { "properties": { "pagination": { "$ref": "#/components/schemas/CursorPaginationResponse" }, "object": { "type": "string", "const": "list", "title": "Object", "description": "The object type of the response", "default": "list" }, "data": { "items": { "$ref": "#/components/schemas/StoreFile" }, "type": "array", "title": "Data", "description": "The list of store files" } }, "type": "object", "required": [ "pagination", "data" ], "title": "StoreFileListResponse" }, "CursorPaginationResponse": { "properties": { "has_more": { "type": "boolean", "title": "Has More", "description": "Contextual direction-aware flag: True if more items exist in the requested pagination direction. For 'after': more items after this page. For 'before': more items before this page.", "examples": [ true, false ] }, "first_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Cursor", "description": "Cursor of the first item in this page. Use for backward pagination. None if page is empty.", "examples": [ "eyJjcmVhdGVkX2F0IjoiMjAyNC0xMi0zMVQyMzo1OTo1OS4wMDBaIiwiaWQiOiJhYmMxMjMifQ==", null ] }, "last_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Cursor", "description": "Cursor of the last item in this page. Use for forward pagination. None if page is empty.", "examples": [ "eyJjcmVhdGVkX2F0IjoiMjAyNC0xMi0zMFQyMzo1OTo1OS4wMDBaIiwiaWQiOiJ4eXo3ODkifQ==", null ] }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total", "description": "Total number of items available across all pages. Only included when include_total=true was requested. Expensive operation - use sparingly.", "examples": [ 42, 0, null ] } }, "type": "object", "required": [ "has_more", "first_cursor", "last_cursor" ], "title": "CursorPaginationResponse", "description": "Response model for cursor-based pagination." }, "StoreFile": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier for the file" }, "filename": { "type": "string", "title": "Filename", "description": "Name of the file" }, "metadata": { "anyOf": [ {}, { "type": "null" } ], "title": "Metadata", "description": "Optional file metadata" }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Id", "description": "External identifier for this file in the store" }, "status": { "$ref": "#/components/schemas/JobStatus", "description": "Processing status of the file", "default": "pending" }, "last_error": { "anyOf": [ {}, { "type": "null" } ], "title": "Last Error", "description": "Last error message if processing failed" }, "store_id": { "type": "string", "title": "Store Id", "description": "ID of the containing store" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp of store file creation" }, "version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Version", "description": "Version number of the file", "examples": [ 1 ] }, "usage_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Usage Bytes", "description": "Storage usage in bytes", "examples": [ 51200 ] }, "usage_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Usage Tokens", "description": "Storage usage in tokens", "examples": [ 51200 ] }, "config": { "anyOf": [ { "$ref": "#/components/schemas/StoreFileConfig" }, { "type": "null" } ], "description": "Configuration for the file" }, "object": { "type": "string", "const": "store.file", "title": "Object", "description": "Type of the object", "default": "store.file" }, "chunks": { "anyOf": [ { "items": { "oneOf": [ { "$ref": "#/components/schemas/TextInputChunk" }, { "$ref": "#/components/schemas/ImageUrlInputChunk" }, { "$ref": "#/components/schemas/AudioUrlInputChunk" }, { "$ref": "#/components/schemas/VideoUrlInputChunk" } ], "discriminator": { "propertyName": "type", "mapping": { "audio_url": "#/components/schemas/AudioUrlInputChunk", "image_url": "#/components/schemas/ImageUrlInputChunk", "text": "#/components/schemas/TextInputChunk", "video_url": "#/components/schemas/VideoUrlInputChunk" } } }, "type": "array" }, { "type": "null" } ], "title": "Chunks", "description": "chunks" }, "content_url": { "type": "string", "title": "Content Url", "description": "Presigned URL for file content" } }, "type": "object", "required": [ "id", "store_id", "created_at", "content_url" ], "title": "StoreFile", "description": "Represents a file stored in a store." }, "StoreFileConfig": { "properties": { "parsing_strategy": { "$ref": "#/components/schemas/StoreFileParsingStrategy", "description": "Strategy for adding the file, this overrides the store-level default", "default": "fast" } }, "type": "object", "title": "StoreFileConfig", "description": "Configuration for a file." }, "StoreFileParsingStrategy": { "type": "string", "enum": [ "fast", "high_quality" ], "title": "StoreFileParsingStrategy", "description": "Strategy for adding a file to a store." }, "TextInputChunk": { "properties": { "chunk_index": { "type": "integer", "title": "Chunk Index", "description": "position of the chunk in a file", "examples": [ 0, 1, 2, 3, 4 ] }, "mime_type": { "type": "string", "title": "Mime Type", "description": "mime type of the chunk", "default": "text/plain", "examples": [ "text/plain" ] }, "generated_metadata": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/MarkdownChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/TextChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/EmailChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CsvChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/PDFChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CodeChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/AudioChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/VideoChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/ImageChunkGeneratedMetadata" } ], "discriminator": { "propertyName": "type", "mapping": { "audio": "#/components/schemas/AudioChunkGeneratedMetadata", "code": "#/components/schemas/CodeChunkGeneratedMetadata", "csv": "#/components/schemas/CsvChunkGeneratedMetadata", "email": "#/components/schemas/EmailChunkGeneratedMetadata", "image": "#/components/schemas/ImageChunkGeneratedMetadata", "markdown": "#/components/schemas/MarkdownChunkGeneratedMetadata", "pdf": "#/components/schemas/PDFChunkGeneratedMetadata", "text": "#/components/schemas/TextChunkGeneratedMetadata", "video": "#/components/schemas/VideoChunkGeneratedMetadata" } } }, { "type": "null" } ], "title": "Generated Metadata", "description": "metadata of the chunk", "examples": [ { "file_size": 1024, "file_type": "text/plain", "language": "en", "type": "text", "word_count": 100 } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "model used for this chunk", "examples": [ "text-embedding-ada-002", "clip-vit-large-patch14" ] }, "type": { "type": "string", "const": "text", "title": "Type", "description": "Input type identifier", "default": "text" }, "offset": { "type": "integer", "title": "Offset", "description": "The offset of the text in the file relative to the start of the file.", "default": 0, "examples": [ 0, 13, 42 ] }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text", "description": "Text content" }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context", "description": "LLM-generated context that situates this chunk within its source document", "examples": [ "This chunk is from an SEC filing on ACME corp's Q2 2023 performance." ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "summary of the text chunk", "examples": [ "A short overview of ACME's Q2 2023 performance." ] } }, "type": "object", "required": [ "chunk_index" ], "title": "TextInputChunk" }, "MarkdownChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "markdown", "title": "Type", "default": "markdown" }, "file_type": { "type": "string", "const": "text/markdown", "title": "File Type", "default": "text/markdown" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "chunk_headings": { "items": { "$ref": "#/components/schemas/MarkdownHeading" }, "type": "array", "title": "Chunk Headings" }, "heading_context": { "items": { "$ref": "#/components/schemas/MarkdownHeading" }, "type": "array", "title": "Heading Context" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" }, "frontmatter": { "additionalProperties": true, "type": "object", "title": "Frontmatter" } }, "additionalProperties": true, "type": "object", "title": "MarkdownChunkGeneratedMetadata" }, "MarkdownHeading": { "properties": { "level": { "type": "integer", "title": "Level" }, "text": { "type": "string", "title": "Text" } }, "type": "object", "required": [ "level", "text" ], "title": "MarkdownHeading" }, "TextChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "text", "title": "Type", "default": "text" }, "file_type": { "type": "string", "enum": [ "text/plain", "message/rfc822" ], "title": "File Type", "default": "text/plain" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "title": "TextChunkGeneratedMetadata" }, "EmailChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "email", "title": "Type", "default": "email" }, "file_type": { "type": "string", "title": "File Type", "default": "message/rfc822" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subject" }, "from_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From Email" }, "to_emails": { "items": { "type": "string" }, "type": "array", "title": "To Emails" }, "cc_emails": { "items": { "type": "string" }, "type": "array", "title": "Cc Emails" }, "bcc_emails": { "items": { "type": "string" }, "type": "array", "title": "Bcc Emails" }, "date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Date" }, "attachment_names": { "items": { "type": "string" }, "type": "array", "title": "Attachment Names" } }, "additionalProperties": true, "type": "object", "title": "EmailChunkGeneratedMetadata" }, "CsvChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "csv", "title": "Type", "default": "csv" }, "file_type": { "type": "string", "const": "text/csv", "title": "File Type", "default": "text/csv" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "start_row": { "type": "integer", "title": "Start Row", "default": 0 }, "num_rows": { "type": "integer", "title": "Num Rows", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "title": "CsvChunkGeneratedMetadata" }, "PDFChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "pdf", "title": "Type", "default": "pdf" }, "file_type": { "type": "string", "const": "application/pdf", "title": "File Type", "default": "application/pdf" }, "total_pages": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Pages" }, "total_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Size" }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" }, "layout": { "anyOf": [ { "$ref": "#/components/schemas/LayoutMetadata" }, { "type": "null" } ] } }, "additionalProperties": true, "type": "object", "title": "PDFChunkGeneratedMetadata" }, "LayoutMetadata": { "properties": { "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Width" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Height" }, "elements": { "items": { "$ref": "#/components/schemas/LayoutElement" }, "type": "array", "title": "Elements" } }, "type": "object", "title": "LayoutMetadata", "description": "Per-page layout for chunks parsed in high-quality (visual) mode.\n\n``elements`` are ordered by reading order (list position == reading order).\n``width``/``height`` are the page-image dimensions the ``bbox`` coords are\nrelative to, so consumers can normalize/render without a second fetch.\n\nLayout is part of the generated metadata payload and is returned with the\nchunk whenever present." }, "LayoutElement": { "properties": { "bbox": { "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" }, { "type": "number" } ], "type": "array", "maxItems": 4, "minItems": 4, "title": "Bbox" }, "type": { "type": "string", "title": "Type" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text" } }, "type": "object", "required": [ "bbox", "type" ], "title": "LayoutElement", "description": "A single detected layout element and its location on the page image." }, "CodeChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "code", "title": "Type", "default": "code" }, "file_type": { "type": "string", "title": "File Type" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "required": [ "file_type" ], "title": "CodeChunkGeneratedMetadata" }, "AudioChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "audio", "title": "Type", "default": "audio" }, "file_type": { "type": "string", "title": "File Type", "default": "audio/mpeg" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "total_duration_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Duration Seconds" }, "sample_rate": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Sample Rate" }, "channels": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Channels" }, "audio_format": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Audio Format" }, "bpm": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bpm" }, "speakers": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Speakers" }, "speaker_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Speaker Count" }, "speaker_turns": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SpeakerTurn" }, "type": "array" }, { "type": "null" } ], "title": "Speaker Turns" }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "title": "AudioChunkGeneratedMetadata" }, "SpeakerTurn": { "properties": { "speaker": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Speaker" }, "text": { "type": "string", "title": "Text" }, "start_time_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Start Time Seconds" }, "end_time_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "End Time Seconds" } }, "type": "object", "required": [ "text" ], "title": "SpeakerTurn" }, "VideoChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "video", "title": "Type", "default": "video" }, "file_type": { "type": "string", "title": "File Type", "default": "video/mp4" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "total_duration_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Duration Seconds" }, "fps": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Fps" }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Width" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Height" }, "frame_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Frame Count" }, "has_audio_stream": { "type": "boolean", "title": "Has Audio Stream", "default": false }, "bpm": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bpm" }, "speakers": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Speakers" }, "speaker_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Speaker Count" }, "speaker_turns": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SpeakerTurn" }, "type": "array" }, { "type": "null" } ], "title": "Speaker Turns" }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "title": "VideoChunkGeneratedMetadata" }, "ImageChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "image", "title": "Type", "default": "image" }, "file_type": { "type": "string", "title": "File Type", "default": "image/jpeg" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Width" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Height" }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" }, "layout": { "anyOf": [ { "$ref": "#/components/schemas/LayoutMetadata" }, { "type": "null" } ] } }, "additionalProperties": true, "type": "object", "title": "ImageChunkGeneratedMetadata" }, "ImageUrlInputChunk": { "properties": { "chunk_index": { "type": "integer", "title": "Chunk Index", "description": "position of the chunk in a file", "examples": [ 0, 1, 2, 3, 4 ] }, "mime_type": { "type": "string", "title": "Mime Type", "description": "mime type of the chunk", "default": "image/jpeg", "examples": [ "image/jpeg" ] }, "generated_metadata": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/MarkdownChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/TextChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/EmailChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CsvChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/PDFChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CodeChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/AudioChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/VideoChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/ImageChunkGeneratedMetadata" } ], "discriminator": { "propertyName": "type", "mapping": { "audio": "#/components/schemas/AudioChunkGeneratedMetadata", "code": "#/components/schemas/CodeChunkGeneratedMetadata", "csv": "#/components/schemas/CsvChunkGeneratedMetadata", "email": "#/components/schemas/EmailChunkGeneratedMetadata", "image": "#/components/schemas/ImageChunkGeneratedMetadata", "markdown": "#/components/schemas/MarkdownChunkGeneratedMetadata", "pdf": "#/components/schemas/PDFChunkGeneratedMetadata", "text": "#/components/schemas/TextChunkGeneratedMetadata", "video": "#/components/schemas/VideoChunkGeneratedMetadata" } } }, { "type": "null" } ], "title": "Generated Metadata", "description": "metadata of the chunk", "examples": [ { "file_size": 1024, "file_type": "text/plain", "language": "en", "type": "text", "word_count": 100 } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "model used for this chunk", "examples": [ "text-embedding-ada-002", "clip-vit-large-patch14" ] }, "type": { "type": "string", "const": "image_url", "title": "Type", "description": "Input type identifier", "default": "image_url" }, "ocr_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ocr Text", "description": "ocr text of the image", "examples": [ "2025 Financial Report" ] }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context", "description": "LLM-generated context that situates this image within its source document", "examples": [ "This page contains ACME's Q2 2023 financial results." ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "summary of the image", "examples": [ "A financial report for 2025" ] }, "image_url": { "anyOf": [ { "$ref": "#/components/schemas/ImageUrl-Output" }, { "type": "null" } ], "description": "Image URL" } }, "type": "object", "required": [ "chunk_index" ], "title": "ImageUrlInputChunk" }, "ImageUrl-Output": { "properties": { "url": { "type": "string", "title": "Url", "description": "The image URL. Can be either a URL or a Data URI." }, "format": { "type": "string", "title": "Format", "description": "The image format/mimetype", "default": "" } }, "type": "object", "required": [ "url" ], "title": "ImageUrl", "description": "Model for image URL validation." }, "AudioUrlInputChunk": { "properties": { "chunk_index": { "type": "integer", "title": "Chunk Index", "description": "position of the chunk in a file", "examples": [ 0, 1, 2, 3, 4 ] }, "mime_type": { "type": "string", "title": "Mime Type", "description": "mime type of the chunk", "default": "audio/mpeg", "examples": [ "audio/mpeg" ] }, "generated_metadata": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/MarkdownChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/TextChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/EmailChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CsvChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/PDFChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CodeChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/AudioChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/VideoChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/ImageChunkGeneratedMetadata" } ], "discriminator": { "propertyName": "type", "mapping": { "audio": "#/components/schemas/AudioChunkGeneratedMetadata", "code": "#/components/schemas/CodeChunkGeneratedMetadata", "csv": "#/components/schemas/CsvChunkGeneratedMetadata", "email": "#/components/schemas/EmailChunkGeneratedMetadata", "image": "#/components/schemas/ImageChunkGeneratedMetadata", "markdown": "#/components/schemas/MarkdownChunkGeneratedMetadata", "pdf": "#/components/schemas/PDFChunkGeneratedMetadata", "text": "#/components/schemas/TextChunkGeneratedMetadata", "video": "#/components/schemas/VideoChunkGeneratedMetadata" } } }, { "type": "null" } ], "title": "Generated Metadata", "description": "metadata of the chunk", "examples": [ { "file_size": 1024, "file_type": "text/plain", "language": "en", "type": "text", "word_count": 100 } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "model used for this chunk", "examples": [ "text-embedding-ada-002", "clip-vit-large-patch14" ] }, "type": { "type": "string", "const": "audio_url", "title": "Type", "description": "Input type identifier", "default": "audio_url" }, "transcription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transcription", "description": "speech recognition (sr) text of the audio", "examples": [ "The year 2025 reports for .." ] }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context", "description": "LLM-generated context that situates this audio chunk within its source file", "examples": [ "This segment introduces ACME's quarterly earnings call." ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "summary of the audio", "examples": [ "A financial report audio for 2025" ] }, "audio_url": { "anyOf": [ { "$ref": "#/components/schemas/AudioUrl" }, { "type": "null" } ], "description": "Audio URL" }, "sampling_rate": { "type": "integer", "title": "Sampling Rate", "description": "The sampling rate of the audio." } }, "type": "object", "required": [ "chunk_index", "sampling_rate" ], "title": "AudioUrlInputChunk" }, "AudioUrl": { "properties": { "url": { "type": "string", "title": "Url", "description": "The audio URL. Can be either a URL or a Data URI." } }, "type": "object", "required": [ "url" ], "title": "AudioUrl", "description": "Model for audio URL validation." }, "VideoUrlInputChunk": { "properties": { "chunk_index": { "type": "integer", "title": "Chunk Index", "description": "position of the chunk in a file", "examples": [ 0, 1, 2, 3, 4 ] }, "mime_type": { "type": "string", "title": "Mime Type", "description": "mime type of the chunk", "default": "video/mp4", "examples": [ "video/mp4" ] }, "generated_metadata": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/MarkdownChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/TextChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/EmailChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CsvChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/PDFChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CodeChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/AudioChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/VideoChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/ImageChunkGeneratedMetadata" } ], "discriminator": { "propertyName": "type", "mapping": { "audio": "#/components/schemas/AudioChunkGeneratedMetadata", "code": "#/components/schemas/CodeChunkGeneratedMetadata", "csv": "#/components/schemas/CsvChunkGeneratedMetadata", "email": "#/components/schemas/EmailChunkGeneratedMetadata", "image": "#/components/schemas/ImageChunkGeneratedMetadata", "markdown": "#/components/schemas/MarkdownChunkGeneratedMetadata", "pdf": "#/components/schemas/PDFChunkGeneratedMetadata", "text": "#/components/schemas/TextChunkGeneratedMetadata", "video": "#/components/schemas/VideoChunkGeneratedMetadata" } } }, { "type": "null" } ], "title": "Generated Metadata", "description": "metadata of the chunk", "examples": [ { "file_size": 1024, "file_type": "text/plain", "language": "en", "type": "text", "word_count": 100 } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "model used for this chunk", "examples": [ "text-embedding-ada-002", "clip-vit-large-patch14" ] }, "type": { "type": "string", "const": "video_url", "title": "Type", "description": "Input type identifier", "default": "video_url" }, "transcription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transcription", "description": "speech recognition (sr) text of the video", "examples": [ "The year 2025 reports for .." ] }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context", "description": "LLM-generated context that situates this video chunk within its source file", "examples": [ "This segment demonstrates the product's document search workflow." ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "summary of the video", "examples": [ "A financial report video for 2025" ] }, "video_url": { "anyOf": [ { "$ref": "#/components/schemas/VideoUrl" }, { "type": "null" } ], "description": "Video URL" } }, "type": "object", "required": [ "chunk_index" ], "title": "VideoUrlInputChunk" }, "VideoUrl": { "properties": { "url": { "type": "string", "title": "Url", "description": "The video URL. Can be either a URL or a Data URI." } }, "type": "object", "required": [ "url" ], "title": "VideoUrl", "description": "Model for video URL validation." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") response = mxbai.stores.files.list("my-knowledge-base", limit=20) for file in response.data: print(file) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") response = await mxbai.stores.files.list("my-knowledge-base", limit=20) for file in response.data: print(file) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const response = await mxbai.stores.files.list("my-knowledge-base", { limit: 20, }); for (const file of response.data) { console.log(file); } ``` cURL: ```bash curl -X GET 'https://api.mixedbread.com/v1/stores/my-knowledge-base/files?limit=20' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` # Update Store File URL: https://www.mixedbread.com/api-reference/endpoints/stores/files/update-store-file Update metadata on a file within a store. ```json { "paths": { "/v1/stores/{store_identifier}/files/{file_identifier}": { "patch": { "tags": [ "stores" ], "summary": "Update Store File", "operationId": "update_store_file", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "store_identifier", "in": "path", "required": true, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ], "description": "The ID or name of the store", "title": "Store Identifier" }, "description": "The ID or name of the store" }, { "name": "file_identifier", "in": "path", "required": true, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ], "description": "The ID or name of the file to update", "title": "File Identifier" }, "description": "The ID or name of the file to update" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreFileMetadataUpdateParams", "description": "Fields to update for the store file" } } } }, "responses": { "200": { "description": "The updated store file details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreFile" }, "example": { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "external_id": "ext-doc-001", "object": "store.file", "filename": "example_document.pdf", "metadata": { "category": "documentation" }, "status": "completed", "last_error": null, "store_id": "c3d4e5f6-a7b8-9012-cdef-345678901234", "usage_bytes": 1048576, "usage_tokens": 51200, "config": { "parsing_strategy": "fast" }, "version": 1, "created_at": "2025-01-15T16:00:00.000Z", "content_url": "https://example.com/files/f47ac10b-58cc-4372-a567-0e02b2c3d479?signature=..." } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "StoreFileMetadataUpdateParams": { "properties": { "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Updated metadata for the file" } }, "type": "object", "title": "StoreFileMetadataUpdateParams", "description": "Parameters for updating metadata on an existing store file." }, "StoreFile": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier for the file" }, "filename": { "type": "string", "title": "Filename", "description": "Name of the file" }, "metadata": { "anyOf": [ {}, { "type": "null" } ], "title": "Metadata", "description": "Optional file metadata" }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Id", "description": "External identifier for this file in the store" }, "status": { "$ref": "#/components/schemas/JobStatus", "description": "Processing status of the file", "default": "pending" }, "last_error": { "anyOf": [ {}, { "type": "null" } ], "title": "Last Error", "description": "Last error message if processing failed" }, "store_id": { "type": "string", "title": "Store Id", "description": "ID of the containing store" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp of store file creation" }, "version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Version", "description": "Version number of the file", "examples": [ 1 ] }, "usage_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Usage Bytes", "description": "Storage usage in bytes", "examples": [ 51200 ] }, "usage_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Usage Tokens", "description": "Storage usage in tokens", "examples": [ 51200 ] }, "config": { "anyOf": [ { "$ref": "#/components/schemas/StoreFileConfig" }, { "type": "null" } ], "description": "Configuration for the file" }, "object": { "type": "string", "const": "store.file", "title": "Object", "description": "Type of the object", "default": "store.file" }, "chunks": { "anyOf": [ { "items": { "oneOf": [ { "$ref": "#/components/schemas/TextInputChunk" }, { "$ref": "#/components/schemas/ImageUrlInputChunk" }, { "$ref": "#/components/schemas/AudioUrlInputChunk" }, { "$ref": "#/components/schemas/VideoUrlInputChunk" } ], "discriminator": { "propertyName": "type", "mapping": { "audio_url": "#/components/schemas/AudioUrlInputChunk", "image_url": "#/components/schemas/ImageUrlInputChunk", "text": "#/components/schemas/TextInputChunk", "video_url": "#/components/schemas/VideoUrlInputChunk" } } }, "type": "array" }, { "type": "null" } ], "title": "Chunks", "description": "chunks" }, "content_url": { "type": "string", "title": "Content Url", "description": "Presigned URL for file content" } }, "type": "object", "required": [ "id", "store_id", "created_at", "content_url" ], "title": "StoreFile", "description": "Represents a file stored in a store." }, "JobStatus": { "type": "string", "enum": [ "pending", "in_progress", "cancelled", "completed", "failed" ], "title": "JobStatus", "description": "The lifecycle of a unit of background work.\n\nOne vocabulary for every job family. The database keeps a separate enum type\nper table (``parsing_job_status``, ``store_file_status``, ...) but they all\ncarry these values, so the aliases below are this enum rather than copies of\nit. :class:`SyncStatus` is this set plus ``IDLE`` for connectors, which have\na resting state between runs." }, "StoreFileConfig": { "properties": { "parsing_strategy": { "$ref": "#/components/schemas/StoreFileParsingStrategy", "description": "Strategy for adding the file, this overrides the store-level default", "default": "fast" } }, "type": "object", "title": "StoreFileConfig", "description": "Configuration for a file." }, "StoreFileParsingStrategy": { "type": "string", "enum": [ "fast", "high_quality" ], "title": "StoreFileParsingStrategy", "description": "Strategy for adding a file to a store." }, "TextInputChunk": { "properties": { "chunk_index": { "type": "integer", "title": "Chunk Index", "description": "position of the chunk in a file", "examples": [ 0, 1, 2, 3, 4 ] }, "mime_type": { "type": "string", "title": "Mime Type", "description": "mime type of the chunk", "default": "text/plain", "examples": [ "text/plain" ] }, "generated_metadata": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/MarkdownChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/TextChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/EmailChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CsvChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/PDFChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CodeChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/AudioChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/VideoChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/ImageChunkGeneratedMetadata" } ], "discriminator": { "propertyName": "type", "mapping": { "audio": "#/components/schemas/AudioChunkGeneratedMetadata", "code": "#/components/schemas/CodeChunkGeneratedMetadata", "csv": "#/components/schemas/CsvChunkGeneratedMetadata", "email": "#/components/schemas/EmailChunkGeneratedMetadata", "image": "#/components/schemas/ImageChunkGeneratedMetadata", "markdown": "#/components/schemas/MarkdownChunkGeneratedMetadata", "pdf": "#/components/schemas/PDFChunkGeneratedMetadata", "text": "#/components/schemas/TextChunkGeneratedMetadata", "video": "#/components/schemas/VideoChunkGeneratedMetadata" } } }, { "type": "null" } ], "title": "Generated Metadata", "description": "metadata of the chunk", "examples": [ { "file_size": 1024, "file_type": "text/plain", "language": "en", "type": "text", "word_count": 100 } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "model used for this chunk", "examples": [ "text-embedding-ada-002", "clip-vit-large-patch14" ] }, "type": { "type": "string", "const": "text", "title": "Type", "description": "Input type identifier", "default": "text" }, "offset": { "type": "integer", "title": "Offset", "description": "The offset of the text in the file relative to the start of the file.", "default": 0, "examples": [ 0, 13, 42 ] }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text", "description": "Text content" }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context", "description": "LLM-generated context that situates this chunk within its source document", "examples": [ "This chunk is from an SEC filing on ACME corp's Q2 2023 performance." ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "summary of the text chunk", "examples": [ "A short overview of ACME's Q2 2023 performance." ] } }, "type": "object", "required": [ "chunk_index" ], "title": "TextInputChunk" }, "MarkdownChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "markdown", "title": "Type", "default": "markdown" }, "file_type": { "type": "string", "const": "text/markdown", "title": "File Type", "default": "text/markdown" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "chunk_headings": { "items": { "$ref": "#/components/schemas/MarkdownHeading" }, "type": "array", "title": "Chunk Headings" }, "heading_context": { "items": { "$ref": "#/components/schemas/MarkdownHeading" }, "type": "array", "title": "Heading Context" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" }, "frontmatter": { "additionalProperties": true, "type": "object", "title": "Frontmatter" } }, "additionalProperties": true, "type": "object", "title": "MarkdownChunkGeneratedMetadata" }, "MarkdownHeading": { "properties": { "level": { "type": "integer", "title": "Level" }, "text": { "type": "string", "title": "Text" } }, "type": "object", "required": [ "level", "text" ], "title": "MarkdownHeading" }, "TextChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "text", "title": "Type", "default": "text" }, "file_type": { "type": "string", "enum": [ "text/plain", "message/rfc822" ], "title": "File Type", "default": "text/plain" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "title": "TextChunkGeneratedMetadata" }, "EmailChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "email", "title": "Type", "default": "email" }, "file_type": { "type": "string", "title": "File Type", "default": "message/rfc822" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subject" }, "from_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From Email" }, "to_emails": { "items": { "type": "string" }, "type": "array", "title": "To Emails" }, "cc_emails": { "items": { "type": "string" }, "type": "array", "title": "Cc Emails" }, "bcc_emails": { "items": { "type": "string" }, "type": "array", "title": "Bcc Emails" }, "date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Date" }, "attachment_names": { "items": { "type": "string" }, "type": "array", "title": "Attachment Names" } }, "additionalProperties": true, "type": "object", "title": "EmailChunkGeneratedMetadata" }, "CsvChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "csv", "title": "Type", "default": "csv" }, "file_type": { "type": "string", "const": "text/csv", "title": "File Type", "default": "text/csv" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "start_row": { "type": "integer", "title": "Start Row", "default": 0 }, "num_rows": { "type": "integer", "title": "Num Rows", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "title": "CsvChunkGeneratedMetadata" }, "PDFChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "pdf", "title": "Type", "default": "pdf" }, "file_type": { "type": "string", "const": "application/pdf", "title": "File Type", "default": "application/pdf" }, "total_pages": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Pages" }, "total_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Size" }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" }, "layout": { "anyOf": [ { "$ref": "#/components/schemas/LayoutMetadata" }, { "type": "null" } ] } }, "additionalProperties": true, "type": "object", "title": "PDFChunkGeneratedMetadata" }, "LayoutMetadata": { "properties": { "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Width" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Height" }, "elements": { "items": { "$ref": "#/components/schemas/LayoutElement" }, "type": "array", "title": "Elements" } }, "type": "object", "title": "LayoutMetadata", "description": "Per-page layout for chunks parsed in high-quality (visual) mode.\n\n``elements`` are ordered by reading order (list position == reading order).\n``width``/``height`` are the page-image dimensions the ``bbox`` coords are\nrelative to, so consumers can normalize/render without a second fetch.\n\nLayout is part of the generated metadata payload and is returned with the\nchunk whenever present." }, "LayoutElement": { "properties": { "bbox": { "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" }, { "type": "number" } ], "type": "array", "maxItems": 4, "minItems": 4, "title": "Bbox" }, "type": { "type": "string", "title": "Type" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text" } }, "type": "object", "required": [ "bbox", "type" ], "title": "LayoutElement", "description": "A single detected layout element and its location on the page image." }, "CodeChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "code", "title": "Type", "default": "code" }, "file_type": { "type": "string", "title": "File Type" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "required": [ "file_type" ], "title": "CodeChunkGeneratedMetadata" }, "AudioChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "audio", "title": "Type", "default": "audio" }, "file_type": { "type": "string", "title": "File Type", "default": "audio/mpeg" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "total_duration_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Duration Seconds" }, "sample_rate": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Sample Rate" }, "channels": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Channels" }, "audio_format": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Audio Format" }, "bpm": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bpm" }, "speakers": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Speakers" }, "speaker_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Speaker Count" }, "speaker_turns": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SpeakerTurn" }, "type": "array" }, { "type": "null" } ], "title": "Speaker Turns" }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "title": "AudioChunkGeneratedMetadata" }, "SpeakerTurn": { "properties": { "speaker": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Speaker" }, "text": { "type": "string", "title": "Text" }, "start_time_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Start Time Seconds" }, "end_time_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "End Time Seconds" } }, "type": "object", "required": [ "text" ], "title": "SpeakerTurn" }, "VideoChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "video", "title": "Type", "default": "video" }, "file_type": { "type": "string", "title": "File Type", "default": "video/mp4" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "total_duration_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Duration Seconds" }, "fps": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Fps" }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Width" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Height" }, "frame_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Frame Count" }, "has_audio_stream": { "type": "boolean", "title": "Has Audio Stream", "default": false }, "bpm": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bpm" }, "speakers": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Speakers" }, "speaker_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Speaker Count" }, "speaker_turns": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SpeakerTurn" }, "type": "array" }, { "type": "null" } ], "title": "Speaker Turns" }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "title": "VideoChunkGeneratedMetadata" }, "ImageChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "image", "title": "Type", "default": "image" }, "file_type": { "type": "string", "title": "File Type", "default": "image/jpeg" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Width" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Height" }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" }, "layout": { "anyOf": [ { "$ref": "#/components/schemas/LayoutMetadata" }, { "type": "null" } ] } }, "additionalProperties": true, "type": "object", "title": "ImageChunkGeneratedMetadata" }, "ImageUrlInputChunk": { "properties": { "chunk_index": { "type": "integer", "title": "Chunk Index", "description": "position of the chunk in a file", "examples": [ 0, 1, 2, 3, 4 ] }, "mime_type": { "type": "string", "title": "Mime Type", "description": "mime type of the chunk", "default": "image/jpeg", "examples": [ "image/jpeg" ] }, "generated_metadata": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/MarkdownChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/TextChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/EmailChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CsvChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/PDFChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CodeChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/AudioChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/VideoChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/ImageChunkGeneratedMetadata" } ], "discriminator": { "propertyName": "type", "mapping": { "audio": "#/components/schemas/AudioChunkGeneratedMetadata", "code": "#/components/schemas/CodeChunkGeneratedMetadata", "csv": "#/components/schemas/CsvChunkGeneratedMetadata", "email": "#/components/schemas/EmailChunkGeneratedMetadata", "image": "#/components/schemas/ImageChunkGeneratedMetadata", "markdown": "#/components/schemas/MarkdownChunkGeneratedMetadata", "pdf": "#/components/schemas/PDFChunkGeneratedMetadata", "text": "#/components/schemas/TextChunkGeneratedMetadata", "video": "#/components/schemas/VideoChunkGeneratedMetadata" } } }, { "type": "null" } ], "title": "Generated Metadata", "description": "metadata of the chunk", "examples": [ { "file_size": 1024, "file_type": "text/plain", "language": "en", "type": "text", "word_count": 100 } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "model used for this chunk", "examples": [ "text-embedding-ada-002", "clip-vit-large-patch14" ] }, "type": { "type": "string", "const": "image_url", "title": "Type", "description": "Input type identifier", "default": "image_url" }, "ocr_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ocr Text", "description": "ocr text of the image", "examples": [ "2025 Financial Report" ] }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context", "description": "LLM-generated context that situates this image within its source document", "examples": [ "This page contains ACME's Q2 2023 financial results." ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "summary of the image", "examples": [ "A financial report for 2025" ] }, "image_url": { "anyOf": [ { "$ref": "#/components/schemas/ImageUrl-Output" }, { "type": "null" } ], "description": "Image URL" } }, "type": "object", "required": [ "chunk_index" ], "title": "ImageUrlInputChunk" }, "ImageUrl-Output": { "properties": { "url": { "type": "string", "title": "Url", "description": "The image URL. Can be either a URL or a Data URI." }, "format": { "type": "string", "title": "Format", "description": "The image format/mimetype", "default": "" } }, "type": "object", "required": [ "url" ], "title": "ImageUrl", "description": "Model for image URL validation." }, "AudioUrlInputChunk": { "properties": { "chunk_index": { "type": "integer", "title": "Chunk Index", "description": "position of the chunk in a file", "examples": [ 0, 1, 2, 3, 4 ] }, "mime_type": { "type": "string", "title": "Mime Type", "description": "mime type of the chunk", "default": "audio/mpeg", "examples": [ "audio/mpeg" ] }, "generated_metadata": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/MarkdownChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/TextChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/EmailChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CsvChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/PDFChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CodeChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/AudioChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/VideoChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/ImageChunkGeneratedMetadata" } ], "discriminator": { "propertyName": "type", "mapping": { "audio": "#/components/schemas/AudioChunkGeneratedMetadata", "code": "#/components/schemas/CodeChunkGeneratedMetadata", "csv": "#/components/schemas/CsvChunkGeneratedMetadata", "email": "#/components/schemas/EmailChunkGeneratedMetadata", "image": "#/components/schemas/ImageChunkGeneratedMetadata", "markdown": "#/components/schemas/MarkdownChunkGeneratedMetadata", "pdf": "#/components/schemas/PDFChunkGeneratedMetadata", "text": "#/components/schemas/TextChunkGeneratedMetadata", "video": "#/components/schemas/VideoChunkGeneratedMetadata" } } }, { "type": "null" } ], "title": "Generated Metadata", "description": "metadata of the chunk", "examples": [ { "file_size": 1024, "file_type": "text/plain", "language": "en", "type": "text", "word_count": 100 } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "model used for this chunk", "examples": [ "text-embedding-ada-002", "clip-vit-large-patch14" ] }, "type": { "type": "string", "const": "audio_url", "title": "Type", "description": "Input type identifier", "default": "audio_url" }, "transcription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transcription", "description": "speech recognition (sr) text of the audio", "examples": [ "The year 2025 reports for .." ] }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context", "description": "LLM-generated context that situates this audio chunk within its source file", "examples": [ "This segment introduces ACME's quarterly earnings call." ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "summary of the audio", "examples": [ "A financial report audio for 2025" ] }, "audio_url": { "anyOf": [ { "$ref": "#/components/schemas/AudioUrl" }, { "type": "null" } ], "description": "Audio URL" }, "sampling_rate": { "type": "integer", "title": "Sampling Rate", "description": "The sampling rate of the audio." } }, "type": "object", "required": [ "chunk_index", "sampling_rate" ], "title": "AudioUrlInputChunk" }, "AudioUrl": { "properties": { "url": { "type": "string", "title": "Url", "description": "The audio URL. Can be either a URL or a Data URI." } }, "type": "object", "required": [ "url" ], "title": "AudioUrl", "description": "Model for audio URL validation." }, "VideoUrlInputChunk": { "properties": { "chunk_index": { "type": "integer", "title": "Chunk Index", "description": "position of the chunk in a file", "examples": [ 0, 1, 2, 3, 4 ] }, "mime_type": { "type": "string", "title": "Mime Type", "description": "mime type of the chunk", "default": "video/mp4", "examples": [ "video/mp4" ] }, "generated_metadata": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/MarkdownChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/TextChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/EmailChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CsvChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/PDFChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CodeChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/AudioChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/VideoChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/ImageChunkGeneratedMetadata" } ], "discriminator": { "propertyName": "type", "mapping": { "audio": "#/components/schemas/AudioChunkGeneratedMetadata", "code": "#/components/schemas/CodeChunkGeneratedMetadata", "csv": "#/components/schemas/CsvChunkGeneratedMetadata", "email": "#/components/schemas/EmailChunkGeneratedMetadata", "image": "#/components/schemas/ImageChunkGeneratedMetadata", "markdown": "#/components/schemas/MarkdownChunkGeneratedMetadata", "pdf": "#/components/schemas/PDFChunkGeneratedMetadata", "text": "#/components/schemas/TextChunkGeneratedMetadata", "video": "#/components/schemas/VideoChunkGeneratedMetadata" } } }, { "type": "null" } ], "title": "Generated Metadata", "description": "metadata of the chunk", "examples": [ { "file_size": 1024, "file_type": "text/plain", "language": "en", "type": "text", "word_count": 100 } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "model used for this chunk", "examples": [ "text-embedding-ada-002", "clip-vit-large-patch14" ] }, "type": { "type": "string", "const": "video_url", "title": "Type", "description": "Input type identifier", "default": "video_url" }, "transcription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transcription", "description": "speech recognition (sr) text of the video", "examples": [ "The year 2025 reports for .." ] }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context", "description": "LLM-generated context that situates this video chunk within its source file", "examples": [ "This segment demonstrates the product's document search workflow." ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "summary of the video", "examples": [ "A financial report video for 2025" ] }, "video_url": { "anyOf": [ { "$ref": "#/components/schemas/VideoUrl" }, { "type": "null" } ], "description": "Video URL" } }, "type": "object", "required": [ "chunk_index" ], "title": "VideoUrlInputChunk" }, "VideoUrl": { "properties": { "url": { "type": "string", "title": "Url", "description": "The video URL. Can be either a URL or a Data URI." } }, "type": "object", "required": [ "url" ], "title": "VideoUrl", "description": "Model for video URL validation." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") file = mxbai.stores.files.update( store_identifier="my-knowledge-base", file_identifier="f47ac10b-58cc-4372-a567-0e02b2c3d479", metadata={"category": "documentation"}, ) print(file) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") file = await mxbai.stores.files.update( store_identifier="my-knowledge-base", file_identifier="f47ac10b-58cc-4372-a567-0e02b2c3d479", metadata={"category": "documentation"}, ) print(file) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const file = await mxbai.stores.files.update("f47ac10b-58cc-4372-a567-0e02b2c3d479", { store_identifier: "my-knowledge-base", metadata: { category: "documentation" }, }); console.log(file); ``` cURL: ```bash curl -X PATCH https://api.mixedbread.com/v1/stores/my-knowledge-base/files/f47ac10b-58cc-4372-a567-0e02b2c3d479 \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -d '{ "metadata": {"category": "documentation"} }' ``` # Create Store URL: https://www.mixedbread.com/api-reference/endpoints/stores/manage/create-store Create a new store. ```json { "paths": { "/v1/stores": { "post": { "tags": [ "stores" ], "summary": "Create Store", "operationId": "create_store", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCreateParams", "description": "The store details for creation" } } } }, "responses": { "201": { "description": "The details of the created store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Store" }, "example": { "id": "vs_abc123", "object": "store", "name": "product-documentation", "description": "Product documentation and FAQs", "is_public": false, "metadata": {}, "tags": [], "config": { "contextualization": { "with_metadata": false, "with_file_context": false } }, "file_counts": { "in_progress": 0, "completed": 0, "failed": 0, "cancelled": 0, "pending": 0, "total": 0 }, "status": "completed", "usage_bytes": 0, "usage_tokens": 0, "expires_after": null, "expires_at": null, "created_at": "2025-01-15T10:30:00.000Z", "updated_at": "2025-01-15T10:30:00.000Z", "last_active_at": null } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "StoreCreateParams": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1 }, { "type": "null" } ], "title": "Name", "description": "Name for the new store. Can only contain lowercase letters, numbers, periods (.), and hyphens (-).", "examples": [ "technical-documentation" ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "null" } ], "title": "Description", "description": "Description of the store", "examples": [ "Contains technical specifications and guides" ] }, "is_public": { "type": "boolean", "title": "Is Public", "description": "Whether the store can be accessed by anyone with valid login credentials", "default": false, "examples": [ false ] }, "license": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License", "description": "License for public stores" }, "expires_after": { "anyOf": [ { "$ref": "#/components/schemas/ExpiresAfter" }, { "type": "null" } ], "description": "Optional expiration policy" }, "metadata": { "anyOf": [ {}, { "type": "null" } ], "title": "Metadata", "description": "Optional metadata key-value pairs" }, "tags": { "items": { "type": "string" }, "type": "array", "maxItems": 32, "title": "Tags", "description": "Tags for organizing stores. Trimmed, lowercased and deduplicated.", "examples": [ [ "production", "docs" ] ] }, "config": { "anyOf": [ { "$ref": "#/components/schemas/StoreConfig" }, { "type": "null" } ], "description": "Store-level configuration defaults" }, "file_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "File Ids", "description": "Optional list of file IDs" } }, "type": "object", "title": "StoreCreateParams", "description": "Parameters for creating a new store." }, "ExpiresAfter": { "properties": { "anchor": { "type": "string", "const": "last_active_at", "title": "Anchor", "description": "Anchor date for the expiration policy", "default": "last_active_at" }, "days": { "type": "integer", "title": "Days", "description": "Number of days after which the store expires", "default": 30 } }, "type": "object", "title": "ExpiresAfter", "description": "Represents an expiration policy for a store." }, "StoreConfig": { "properties": { "contextualization": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/ContextualizationConfig" } ], "title": "Contextualization", "description": "Include additional context when embedding chunks.", "default": false }, "lsf": { "anyOf": [ { "$ref": "#/components/schemas/LsfStoreConfig" }, { "type": "null" } ], "description": "Learn a scoring function for this store. Searches are captured as training data, a model is trained from reranking and answer signals, and once trained, searches apply it by default (override per search with the lsf option). Pass an empty object to enable it." } }, "type": "object", "title": "StoreConfig", "description": "Configuration for a store." }, "ContextualizationConfig": { "properties": { "with_metadata": { "anyOf": [ { "type": "boolean" }, { "items": { "type": "string" }, "type": "array" } ], "title": "With Metadata", "description": "Include all metadata or specific fields in the contextualization. Supports dot notation for nested fields (e.g., 'author.name'). When True, all metadata is included (flattened). When a list, only specified fields are included.", "default": false, "examples": [ true, false, [ "title", "author.name", "author.email", "tags" ] ] }, "with_file_context": { "type": "boolean", "title": "With File Context", "description": "Use an LLM to generate a short context for each chunk that situates it within the full document, improving retrieval accuracy.", "default": false } }, "type": "object", "title": "ContextualizationConfig" }, "LsfStoreConfig": { "properties": {}, "type": "object", "title": "LsfStoreConfig", "description": "Learned-scoring-function settings a store opts into; an empty object enables it." }, "Store": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier for the store", "examples": [ "1b8b486e-16d0-400b-8868-04cd75217a7e" ] }, "name": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Name", "description": "Name of the store", "examples": [ "customer-support-kb", "product-documentation" ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "null" } ], "title": "Description", "description": "Detailed description of the store's purpose and contents", "examples": [ "Contains customer support articles and FAQs" ] }, "is_public": { "type": "boolean", "title": "Is Public", "description": "Whether the store can be accessed by anyone with valid login credentials", "default": false, "examples": [ false ] }, "license": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License", "description": "License for public stores" }, "metadata": { "anyOf": [ {}, { "type": "null" } ], "title": "Metadata", "description": "Additional metadata associated with the store", "examples": [ { "category": "support", "language": "en" } ] }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags", "description": "Tags for organizing stores", "examples": [ [ "production", "docs" ] ] }, "config": { "anyOf": [ { "$ref": "#/components/schemas/StoreConfig" }, { "type": "null" } ], "description": "Store-level configuration defaults" }, "bucket_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Bucket Id", "description": "Customer bucket backing this store's storage; null = platform default" }, "file_counts": { "$ref": "#/components/schemas/FileCounts", "description": "Counts of files in different states" }, "expires_after": { "anyOf": [ { "$ref": "#/components/schemas/ExpiresAfter" }, { "type": "null" } ], "description": "Optional expiration policy" }, "status": { "$ref": "#/components/schemas/StoreStatus", "description": "Processing status of the store", "default": "completed" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when the store was created", "examples": [ "2024-01-01T00:00:00Z" ] }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Timestamp when the store was last updated", "examples": [ "2024-01-01T00:00:00Z" ] }, "last_active_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Active At", "description": "Timestamp when the store was last used" }, "usage_bytes": { "type": "integer", "title": "Usage Bytes", "description": "Total storage usage in bytes", "default": 0, "examples": [ 1024000 ] }, "usage_tokens": { "type": "integer", "title": "Usage Tokens", "description": "Total storage usage in tokens", "default": 0, "examples": [ 1024000 ] }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At", "description": "Optional expiration timestamp for the store", "examples": [ "2024-01-01T00:00:00Z" ] }, "copy_state": { "anyOf": [ { "$ref": "#/components/schemas/StoreCopyInfo" }, { "type": "null" } ], "description": "Set while the store is being copied from or into, and when a copy into it failed" }, "object": { "type": "string", "const": "store", "title": "Object", "description": "Type of the object", "default": "store" } }, "type": "object", "required": [ "id", "name", "created_at", "updated_at" ], "title": "Store", "description": "Model representing a store with its metadata and timestamps." }, "FileCounts": { "properties": { "pending": { "type": "integer", "title": "Pending", "description": "Number of files waiting to be processed", "default": 0, "examples": [ 5 ] }, "in_progress": { "type": "integer", "title": "In Progress", "description": "Number of files currently being processed", "default": 0, "examples": [ 5 ] }, "cancelled": { "type": "integer", "title": "Cancelled", "description": "Number of files whose processing was cancelled", "default": 0, "examples": [ 2 ] }, "completed": { "type": "integer", "title": "Completed", "description": "Number of successfully processed files", "default": 0, "examples": [ 42 ] }, "failed": { "type": "integer", "title": "Failed", "description": "Number of files that failed processing", "default": 0, "examples": [ 1 ] }, "total": { "type": "integer", "title": "Total", "description": "Total number of files", "default": 0, "examples": [ 50 ] } }, "type": "object", "title": "FileCounts", "description": "Tracks counts of files in different states within a store." }, "StoreStatus": { "type": "string", "enum": [ "expired", "in_progress", "completed", "failed" ], "title": "StoreStatus", "description": "Status of a store." }, "StoreCopyInfo": { "properties": { "role": { "type": "string", "enum": [ "source", "target" ], "title": "Role", "description": "Whether this store is copied from or into" }, "status": { "type": "string", "enum": [ "in_progress", "failed" ], "title": "Status", "description": "Progress of the copy" }, "peer_store_id": { "type": "string", "title": "Peer Store Id", "description": "The other store of the copy" }, "started_at": { "type": "string", "format": "date-time", "title": "Started At", "description": "When the copy was requested" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Why the copy failed, when it did" } }, "type": "object", "required": [ "role", "status", "peer_store_id", "started_at" ], "title": "StoreCopyInfo", "description": "Progress of a store copy, present on both the source and the target while it runs." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") store = mxbai.stores.create( name="my-knowledge-base", description="Product documentation and FAQs" ) print(store) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") store = await mxbai.stores.create( name="my-knowledge-base", description="Product documentation and FAQs" ) print(store) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const store = await mxbai.stores.create({ name: "my-knowledge-base", description: "Product documentation and FAQs", }); console.log(store); ``` cURL: ```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", "description": "Product documentation and FAQs" }' ``` # Delete Store URL: https://www.mixedbread.com/api-reference/endpoints/stores/manage/delete-store Delete a store by ID or name. ```json { "paths": { "/v1/stores/{store_identifier}": { "delete": { "tags": [ "stores" ], "summary": "Delete Store", "operationId": "delete_store", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "store_identifier", "in": "path", "required": true, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ], "description": "The ID or name of the store to delete", "title": "Store Identifier" }, "description": "The ID or name of the store to delete" } ], "responses": { "200": { "description": "The details of the deleted store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreDeleted" }, "example": { "id": "vs_abc123", "object": "store", "deleted": true } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "StoreDeleted": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ], "title": "Id", "description": "ID of the deleted store" }, "deleted": { "type": "boolean", "title": "Deleted", "description": "Whether the deletion was successful" }, "object": { "type": "string", "const": "store", "title": "Object", "description": "Type of the deleted object", "default": "store" } }, "type": "object", "required": [ "id", "deleted" ], "title": "StoreDeleted", "description": "Response model for store deletion." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") response = mxbai.stores.delete(store_identifier="my-knowledge-base") print(response) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") response = await mxbai.stores.delete(store_identifier="my-knowledge-base") print(response) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const response = await mxbai.stores.delete("my-knowledge-base"); console.log(response); ``` cURL: ```bash curl -X DELETE https://api.mixedbread.com/v1/stores/my-knowledge-base \ -H 'Authorization: Bearer YOUR_API_KEY' ``` # Get Store URL: https://www.mixedbread.com/api-reference/endpoints/stores/manage/get-store Get a store by ID or name. ```json { "paths": { "/v1/stores/{store_identifier}": { "get": { "tags": [ "stores" ], "summary": "Get Store", "operationId": "retrieve_store", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "store_identifier", "in": "path", "required": true, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ], "description": "The ID or name of the store", "title": "Store Identifier" }, "description": "The ID or name of the store" } ], "responses": { "200": { "description": "The details of the store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Store" }, "example": { "id": "vs_abc123", "object": "store", "name": "product-documentation", "description": "Product documentation and FAQs", "is_public": false, "metadata": {}, "tags": [], "config": { "contextualization": { "with_metadata": false, "with_file_context": false } }, "file_counts": { "in_progress": 0, "completed": 5, "failed": 0, "cancelled": 0, "pending": 0, "total": 5 }, "status": "completed", "usage_bytes": 1048576, "usage_tokens": 51200, "expires_after": null, "expires_at": null, "created_at": "2025-01-15T10:30:00.000Z", "updated_at": "2025-01-15T11:45:00.000Z", "last_active_at": "2025-01-15T12:00:00.000Z" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "Store": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier for the store", "examples": [ "1b8b486e-16d0-400b-8868-04cd75217a7e" ] }, "name": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Name", "description": "Name of the store", "examples": [ "customer-support-kb", "product-documentation" ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "null" } ], "title": "Description", "description": "Detailed description of the store's purpose and contents", "examples": [ "Contains customer support articles and FAQs" ] }, "is_public": { "type": "boolean", "title": "Is Public", "description": "Whether the store can be accessed by anyone with valid login credentials", "default": false, "examples": [ false ] }, "license": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License", "description": "License for public stores" }, "metadata": { "anyOf": [ {}, { "type": "null" } ], "title": "Metadata", "description": "Additional metadata associated with the store", "examples": [ { "category": "support", "language": "en" } ] }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags", "description": "Tags for organizing stores", "examples": [ [ "production", "docs" ] ] }, "config": { "anyOf": [ { "$ref": "#/components/schemas/StoreConfig" }, { "type": "null" } ], "description": "Store-level configuration defaults" }, "bucket_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Bucket Id", "description": "Customer bucket backing this store's storage; null = platform default" }, "file_counts": { "$ref": "#/components/schemas/FileCounts", "description": "Counts of files in different states" }, "expires_after": { "anyOf": [ { "$ref": "#/components/schemas/ExpiresAfter" }, { "type": "null" } ], "description": "Optional expiration policy" }, "status": { "$ref": "#/components/schemas/StoreStatus", "description": "Processing status of the store", "default": "completed" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when the store was created", "examples": [ "2024-01-01T00:00:00Z" ] }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Timestamp when the store was last updated", "examples": [ "2024-01-01T00:00:00Z" ] }, "last_active_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Active At", "description": "Timestamp when the store was last used" }, "usage_bytes": { "type": "integer", "title": "Usage Bytes", "description": "Total storage usage in bytes", "default": 0, "examples": [ 1024000 ] }, "usage_tokens": { "type": "integer", "title": "Usage Tokens", "description": "Total storage usage in tokens", "default": 0, "examples": [ 1024000 ] }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At", "description": "Optional expiration timestamp for the store", "examples": [ "2024-01-01T00:00:00Z" ] }, "copy_state": { "anyOf": [ { "$ref": "#/components/schemas/StoreCopyInfo" }, { "type": "null" } ], "description": "Set while the store is being copied from or into, and when a copy into it failed" }, "object": { "type": "string", "const": "store", "title": "Object", "description": "Type of the object", "default": "store" } }, "type": "object", "required": [ "id", "name", "created_at", "updated_at" ], "title": "Store", "description": "Model representing a store with its metadata and timestamps." }, "StoreConfig": { "properties": { "contextualization": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/ContextualizationConfig" } ], "title": "Contextualization", "description": "Include additional context when embedding chunks.", "default": false }, "lsf": { "anyOf": [ { "$ref": "#/components/schemas/LsfStoreConfig" }, { "type": "null" } ], "description": "Learn a scoring function for this store. Searches are captured as training data, a model is trained from reranking and answer signals, and once trained, searches apply it by default (override per search with the lsf option). Pass an empty object to enable it." } }, "type": "object", "title": "StoreConfig", "description": "Configuration for a store." }, "ContextualizationConfig": { "properties": { "with_metadata": { "anyOf": [ { "type": "boolean" }, { "items": { "type": "string" }, "type": "array" } ], "title": "With Metadata", "description": "Include all metadata or specific fields in the contextualization. Supports dot notation for nested fields (e.g., 'author.name'). When True, all metadata is included (flattened). When a list, only specified fields are included.", "default": false, "examples": [ true, false, [ "title", "author.name", "author.email", "tags" ] ] }, "with_file_context": { "type": "boolean", "title": "With File Context", "description": "Use an LLM to generate a short context for each chunk that situates it within the full document, improving retrieval accuracy.", "default": false } }, "type": "object", "title": "ContextualizationConfig" }, "LsfStoreConfig": { "properties": {}, "type": "object", "title": "LsfStoreConfig", "description": "Learned-scoring-function settings a store opts into; an empty object enables it." }, "FileCounts": { "properties": { "pending": { "type": "integer", "title": "Pending", "description": "Number of files waiting to be processed", "default": 0, "examples": [ 5 ] }, "in_progress": { "type": "integer", "title": "In Progress", "description": "Number of files currently being processed", "default": 0, "examples": [ 5 ] }, "cancelled": { "type": "integer", "title": "Cancelled", "description": "Number of files whose processing was cancelled", "default": 0, "examples": [ 2 ] }, "completed": { "type": "integer", "title": "Completed", "description": "Number of successfully processed files", "default": 0, "examples": [ 42 ] }, "failed": { "type": "integer", "title": "Failed", "description": "Number of files that failed processing", "default": 0, "examples": [ 1 ] }, "total": { "type": "integer", "title": "Total", "description": "Total number of files", "default": 0, "examples": [ 50 ] } }, "type": "object", "title": "FileCounts", "description": "Tracks counts of files in different states within a store." }, "ExpiresAfter": { "properties": { "anchor": { "type": "string", "const": "last_active_at", "title": "Anchor", "description": "Anchor date for the expiration policy", "default": "last_active_at" }, "days": { "type": "integer", "title": "Days", "description": "Number of days after which the store expires", "default": 30 } }, "type": "object", "title": "ExpiresAfter", "description": "Represents an expiration policy for a store." }, "StoreStatus": { "type": "string", "enum": [ "expired", "in_progress", "completed", "failed" ], "title": "StoreStatus", "description": "Status of a store." }, "StoreCopyInfo": { "properties": { "role": { "type": "string", "enum": [ "source", "target" ], "title": "Role", "description": "Whether this store is copied from or into" }, "status": { "type": "string", "enum": [ "in_progress", "failed" ], "title": "Status", "description": "Progress of the copy" }, "peer_store_id": { "type": "string", "title": "Peer Store Id", "description": "The other store of the copy" }, "started_at": { "type": "string", "format": "date-time", "title": "Started At", "description": "When the copy was requested" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Why the copy failed, when it did" } }, "type": "object", "required": [ "role", "status", "peer_store_id", "started_at" ], "title": "StoreCopyInfo", "description": "Progress of a store copy, present on both the source and the target while it runs." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") store = mxbai.stores.retrieve(store_identifier="my-knowledge-base") print(store) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") store = await mxbai.stores.retrieve( store_identifier="my-knowledge-base" ) print(store) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const store = await mxbai.stores.retrieve("my-knowledge-base"); console.log(store); ``` cURL: ```bash curl https://api.mixedbread.com/v1/stores/my-knowledge-base \ -H 'Authorization: Bearer YOUR_API_KEY' ``` # List Stores URL: https://www.mixedbread.com/api-reference/endpoints/stores/manage/list-stores List all stores with optional search. ```json { "paths": { "/v1/stores": { "get": { "tags": [ "stores" ], "summary": "List Stores", "operationId": "list_stores", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Maximum number of items to return per page (1-100)", "examples": [ 10, 20, 50 ], "default": 20, "title": "Limit" }, "description": "Maximum number of items to return per page (1-100)" }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for forward pagination - get items after this position. Use last_cursor from previous response.", "examples": [ "eyJjcmVhdGVkX2F0IjoiMjAyNC0xMi0zMVQyMzo1OTo1OS4wMDBaIiwiaWQiOiJhYmMxMjMifQ==" ], "title": "After" }, "description": "Cursor for forward pagination - get items after this position. Use last_cursor from previous response." }, { "name": "before", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for backward pagination - get items before this position. Use first_cursor from previous response.", "examples": [ "eyJjcmVhdGVkX2F0IjoiMjAyNC0xMi0zMVQyMzo1OTo1OS4wMDBaIiwiaWQiOiJhYmMxMjMifQ==" ], "title": "Before" }, "description": "Cursor for backward pagination - get items before this position. Use first_cursor from previous response." }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Whether to include total count in response (expensive operation)", "examples": [ false, true ], "default": false, "title": "Include Total" }, "description": "Whether to include total count in response (expensive operation)" }, { "name": "q", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Search query for fuzzy matching over name and description fields", "title": "Q" }, "description": "Search query for fuzzy matching over name and description fields" }, { "name": "tags", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" }, "maxItems": 32 }, { "type": "null" } ], "description": "Only return stores that carry every one of these tags", "title": "Tags" }, "description": "Only return stores that carry every one of these tags" } ], "responses": { "200": { "description": "The list of stores", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreListResponse" }, "example": { "object": "list", "data": [ { "id": "vs_abc123", "object": "store", "name": "product-documentation", "description": "Product documentation and FAQs", "is_public": false, "metadata": {}, "tags": [], "config": { "contextualization": { "with_metadata": false, "with_file_context": false } }, "file_counts": { "in_progress": 0, "completed": 10, "failed": 0, "cancelled": 0, "pending": 0, "total": 10 }, "status": "completed", "usage_bytes": 2097152, "usage_tokens": 102400, "expires_after": null, "expires_at": null, "created_at": "2025-01-10T09:00:00.000Z", "updated_at": "2025-01-15T11:30:00.000Z", "last_active_at": "2025-01-15T14:00:00.000Z" }, { "id": "vs_def456", "object": "store", "name": "api-documentation", "description": "API reference documentation", "is_public": true, "metadata": {}, "tags": [], "config": { "contextualization": { "with_metadata": false, "with_file_context": false } }, "file_counts": { "in_progress": 0, "completed": 5, "failed": 0, "cancelled": 0, "pending": 0, "total": 5 }, "status": "completed", "usage_bytes": 1048576, "usage_tokens": 51200, "expires_after": null, "expires_at": null, "created_at": "2025-01-12T10:15:00.000Z", "updated_at": "2025-01-14T09:20:00.000Z", "last_active_at": "2025-01-15T13:45:00.000Z" } ], "pagination": { "has_more": false, "first_cursor": "eyJpZCI6InZzX2FiYzEyMyJ9", "last_cursor": "eyJpZCI6InZzX2RlZjQ1NiJ9" } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "StoreListResponse": { "properties": { "pagination": { "$ref": "#/components/schemas/CursorPaginationResponse" }, "object": { "type": "string", "const": "list", "title": "Object", "description": "The object type of the response", "default": "list" }, "data": { "items": { "$ref": "#/components/schemas/Store" }, "type": "array", "title": "Data", "description": "The list of stores" } }, "type": "object", "required": [ "pagination", "data" ], "title": "StoreListResponse" }, "CursorPaginationResponse": { "properties": { "has_more": { "type": "boolean", "title": "Has More", "description": "Contextual direction-aware flag: True if more items exist in the requested pagination direction. For 'after': more items after this page. For 'before': more items before this page.", "examples": [ true, false ] }, "first_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Cursor", "description": "Cursor of the first item in this page. Use for backward pagination. None if page is empty.", "examples": [ "eyJjcmVhdGVkX2F0IjoiMjAyNC0xMi0zMVQyMzo1OTo1OS4wMDBaIiwiaWQiOiJhYmMxMjMifQ==", null ] }, "last_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Cursor", "description": "Cursor of the last item in this page. Use for forward pagination. None if page is empty.", "examples": [ "eyJjcmVhdGVkX2F0IjoiMjAyNC0xMi0zMFQyMzo1OTo1OS4wMDBaIiwiaWQiOiJ4eXo3ODkifQ==", null ] }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total", "description": "Total number of items available across all pages. Only included when include_total=true was requested. Expensive operation - use sparingly.", "examples": [ 42, 0, null ] } }, "type": "object", "required": [ "has_more", "first_cursor", "last_cursor" ], "title": "CursorPaginationResponse", "description": "Response model for cursor-based pagination." }, "Store": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier for the store", "examples": [ "1b8b486e-16d0-400b-8868-04cd75217a7e" ] }, "name": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Name", "description": "Name of the store", "examples": [ "customer-support-kb", "product-documentation" ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "null" } ], "title": "Description", "description": "Detailed description of the store's purpose and contents", "examples": [ "Contains customer support articles and FAQs" ] }, "is_public": { "type": "boolean", "title": "Is Public", "description": "Whether the store can be accessed by anyone with valid login credentials", "default": false, "examples": [ false ] }, "license": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License", "description": "License for public stores" }, "metadata": { "anyOf": [ {}, { "type": "null" } ], "title": "Metadata", "description": "Additional metadata associated with the store", "examples": [ { "category": "support", "language": "en" } ] }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags", "description": "Tags for organizing stores", "examples": [ [ "production", "docs" ] ] }, "config": { "anyOf": [ { "$ref": "#/components/schemas/StoreConfig" }, { "type": "null" } ], "description": "Store-level configuration defaults" }, "bucket_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Bucket Id", "description": "Customer bucket backing this store's storage; null = platform default" }, "file_counts": { "$ref": "#/components/schemas/FileCounts", "description": "Counts of files in different states" }, "expires_after": { "anyOf": [ { "$ref": "#/components/schemas/ExpiresAfter" }, { "type": "null" } ], "description": "Optional expiration policy" }, "status": { "$ref": "#/components/schemas/StoreStatus", "description": "Processing status of the store", "default": "completed" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when the store was created", "examples": [ "2024-01-01T00:00:00Z" ] }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Timestamp when the store was last updated", "examples": [ "2024-01-01T00:00:00Z" ] }, "last_active_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Active At", "description": "Timestamp when the store was last used" }, "usage_bytes": { "type": "integer", "title": "Usage Bytes", "description": "Total storage usage in bytes", "default": 0, "examples": [ 1024000 ] }, "usage_tokens": { "type": "integer", "title": "Usage Tokens", "description": "Total storage usage in tokens", "default": 0, "examples": [ 1024000 ] }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At", "description": "Optional expiration timestamp for the store", "examples": [ "2024-01-01T00:00:00Z" ] }, "copy_state": { "anyOf": [ { "$ref": "#/components/schemas/StoreCopyInfo" }, { "type": "null" } ], "description": "Set while the store is being copied from or into, and when a copy into it failed" }, "object": { "type": "string", "const": "store", "title": "Object", "description": "Type of the object", "default": "store" } }, "type": "object", "required": [ "id", "name", "created_at", "updated_at" ], "title": "Store", "description": "Model representing a store with its metadata and timestamps." }, "StoreConfig": { "properties": { "contextualization": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/ContextualizationConfig" } ], "title": "Contextualization", "description": "Include additional context when embedding chunks.", "default": false }, "lsf": { "anyOf": [ { "$ref": "#/components/schemas/LsfStoreConfig" }, { "type": "null" } ], "description": "Learn a scoring function for this store. Searches are captured as training data, a model is trained from reranking and answer signals, and once trained, searches apply it by default (override per search with the lsf option). Pass an empty object to enable it." } }, "type": "object", "title": "StoreConfig", "description": "Configuration for a store." }, "ContextualizationConfig": { "properties": { "with_metadata": { "anyOf": [ { "type": "boolean" }, { "items": { "type": "string" }, "type": "array" } ], "title": "With Metadata", "description": "Include all metadata or specific fields in the contextualization. Supports dot notation for nested fields (e.g., 'author.name'). When True, all metadata is included (flattened). When a list, only specified fields are included.", "default": false, "examples": [ true, false, [ "title", "author.name", "author.email", "tags" ] ] }, "with_file_context": { "type": "boolean", "title": "With File Context", "description": "Use an LLM to generate a short context for each chunk that situates it within the full document, improving retrieval accuracy.", "default": false } }, "type": "object", "title": "ContextualizationConfig" }, "LsfStoreConfig": { "properties": {}, "type": "object", "title": "LsfStoreConfig", "description": "Learned-scoring-function settings a store opts into; an empty object enables it." }, "FileCounts": { "properties": { "pending": { "type": "integer", "title": "Pending", "description": "Number of files waiting to be processed", "default": 0, "examples": [ 5 ] }, "in_progress": { "type": "integer", "title": "In Progress", "description": "Number of files currently being processed", "default": 0, "examples": [ 5 ] }, "cancelled": { "type": "integer", "title": "Cancelled", "description": "Number of files whose processing was cancelled", "default": 0, "examples": [ 2 ] }, "completed": { "type": "integer", "title": "Completed", "description": "Number of successfully processed files", "default": 0, "examples": [ 42 ] }, "failed": { "type": "integer", "title": "Failed", "description": "Number of files that failed processing", "default": 0, "examples": [ 1 ] }, "total": { "type": "integer", "title": "Total", "description": "Total number of files", "default": 0, "examples": [ 50 ] } }, "type": "object", "title": "FileCounts", "description": "Tracks counts of files in different states within a store." }, "ExpiresAfter": { "properties": { "anchor": { "type": "string", "const": "last_active_at", "title": "Anchor", "description": "Anchor date for the expiration policy", "default": "last_active_at" }, "days": { "type": "integer", "title": "Days", "description": "Number of days after which the store expires", "default": 30 } }, "type": "object", "title": "ExpiresAfter", "description": "Represents an expiration policy for a store." }, "StoreStatus": { "type": "string", "enum": [ "expired", "in_progress", "completed", "failed" ], "title": "StoreStatus", "description": "Status of a store." }, "StoreCopyInfo": { "properties": { "role": { "type": "string", "enum": [ "source", "target" ], "title": "Role", "description": "Whether this store is copied from or into" }, "status": { "type": "string", "enum": [ "in_progress", "failed" ], "title": "Status", "description": "Progress of the copy" }, "peer_store_id": { "type": "string", "title": "Peer Store Id", "description": "The other store of the copy" }, "started_at": { "type": "string", "format": "date-time", "title": "Started At", "description": "When the copy was requested" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Why the copy failed, when it did" } }, "type": "object", "required": [ "role", "status", "peer_store_id", "started_at" ], "title": "StoreCopyInfo", "description": "Progress of a store copy, present on both the source and the target while it runs." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") response = mxbai.stores.list(limit=20) for store in response.data: print(store) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") response = await mxbai.stores.list(limit=20) for store in response.data: print(store) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const response = await mxbai.stores.list({ limit: 20, }); for (const store of response.data) { console.log(store); } ``` cURL: ```bash curl 'https://api.mixedbread.com/v1/stores?limit=20' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` # Update Store URL: https://www.mixedbread.com/api-reference/endpoints/stores/manage/update-store Update a store by ID or name. ```json { "paths": { "/v1/stores/{store_identifier}": { "put": { "tags": [ "stores" ], "summary": "Update Store", "operationId": "update_store", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "store_identifier", "in": "path", "required": true, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ], "description": "The ID or name of the store", "title": "Store Identifier" }, "description": "The ID or name of the store" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreUpdateParams", "description": "The fields to update" } } } }, "responses": { "200": { "description": "The details of the updated store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Store" }, "example": { "id": "vs_abc123", "object": "store", "name": "updated-knowledge-base", "description": "Updated product documentation and FAQs", "is_public": false, "metadata": { "version": "2.0" }, "tags": [], "config": { "contextualization": { "with_metadata": false, "with_file_context": false } }, "file_counts": { "in_progress": 0, "completed": 5, "failed": 0, "cancelled": 0, "pending": 0, "total": 5 }, "status": "completed", "usage_bytes": 1048576, "usage_tokens": 51200, "expires_after": null, "expires_at": null, "created_at": "2025-01-15T10:30:00.000Z", "updated_at": "2025-01-15T15:00:00.000Z", "last_active_at": "2025-01-15T15:00:00.000Z" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "StoreUpdateParams": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1 }, { "type": "null" } ], "title": "Name", "description": "New name for the store. Can only contain lowercase letters, numbers, periods (.), and hyphens (-)." }, "description": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "null" } ], "title": "Description", "description": "New description" }, "is_public": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Public", "description": "Whether the store can be accessed by anyone with valid login credentials" }, "license": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License", "description": "License for public stores" }, "expires_after": { "anyOf": [ { "$ref": "#/components/schemas/ExpiresAfter" }, { "type": "null" } ], "description": "Optional expiration policy" }, "metadata": { "anyOf": [ {}, { "type": "null" } ], "title": "Metadata", "description": "Optional metadata key-value pairs" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "maxItems": 32 }, { "type": "null" } ], "title": "Tags", "description": "New tags for the store, replacing the current ones. Send an empty list to clear." } }, "type": "object", "title": "StoreUpdateParams", "description": "Parameters for updating an existing store." }, "ExpiresAfter": { "properties": { "anchor": { "type": "string", "const": "last_active_at", "title": "Anchor", "description": "Anchor date for the expiration policy", "default": "last_active_at" }, "days": { "type": "integer", "title": "Days", "description": "Number of days after which the store expires", "default": 30 } }, "type": "object", "title": "ExpiresAfter", "description": "Represents an expiration policy for a store." }, "Store": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier for the store", "examples": [ "1b8b486e-16d0-400b-8868-04cd75217a7e" ] }, "name": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Name", "description": "Name of the store", "examples": [ "customer-support-kb", "product-documentation" ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "null" } ], "title": "Description", "description": "Detailed description of the store's purpose and contents", "examples": [ "Contains customer support articles and FAQs" ] }, "is_public": { "type": "boolean", "title": "Is Public", "description": "Whether the store can be accessed by anyone with valid login credentials", "default": false, "examples": [ false ] }, "license": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License", "description": "License for public stores" }, "metadata": { "anyOf": [ {}, { "type": "null" } ], "title": "Metadata", "description": "Additional metadata associated with the store", "examples": [ { "category": "support", "language": "en" } ] }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags", "description": "Tags for organizing stores", "examples": [ [ "production", "docs" ] ] }, "config": { "anyOf": [ { "$ref": "#/components/schemas/StoreConfig" }, { "type": "null" } ], "description": "Store-level configuration defaults" }, "bucket_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Bucket Id", "description": "Customer bucket backing this store's storage; null = platform default" }, "file_counts": { "$ref": "#/components/schemas/FileCounts", "description": "Counts of files in different states" }, "expires_after": { "anyOf": [ { "$ref": "#/components/schemas/ExpiresAfter" }, { "type": "null" } ], "description": "Optional expiration policy" }, "status": { "$ref": "#/components/schemas/StoreStatus", "description": "Processing status of the store", "default": "completed" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when the store was created", "examples": [ "2024-01-01T00:00:00Z" ] }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Timestamp when the store was last updated", "examples": [ "2024-01-01T00:00:00Z" ] }, "last_active_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Active At", "description": "Timestamp when the store was last used" }, "usage_bytes": { "type": "integer", "title": "Usage Bytes", "description": "Total storage usage in bytes", "default": 0, "examples": [ 1024000 ] }, "usage_tokens": { "type": "integer", "title": "Usage Tokens", "description": "Total storage usage in tokens", "default": 0, "examples": [ 1024000 ] }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At", "description": "Optional expiration timestamp for the store", "examples": [ "2024-01-01T00:00:00Z" ] }, "copy_state": { "anyOf": [ { "$ref": "#/components/schemas/StoreCopyInfo" }, { "type": "null" } ], "description": "Set while the store is being copied from or into, and when a copy into it failed" }, "object": { "type": "string", "const": "store", "title": "Object", "description": "Type of the object", "default": "store" } }, "type": "object", "required": [ "id", "name", "created_at", "updated_at" ], "title": "Store", "description": "Model representing a store with its metadata and timestamps." }, "StoreConfig": { "properties": { "contextualization": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/ContextualizationConfig" } ], "title": "Contextualization", "description": "Include additional context when embedding chunks.", "default": false }, "lsf": { "anyOf": [ { "$ref": "#/components/schemas/LsfStoreConfig" }, { "type": "null" } ], "description": "Learn a scoring function for this store. Searches are captured as training data, a model is trained from reranking and answer signals, and once trained, searches apply it by default (override per search with the lsf option). Pass an empty object to enable it." } }, "type": "object", "title": "StoreConfig", "description": "Configuration for a store." }, "ContextualizationConfig": { "properties": { "with_metadata": { "anyOf": [ { "type": "boolean" }, { "items": { "type": "string" }, "type": "array" } ], "title": "With Metadata", "description": "Include all metadata or specific fields in the contextualization. Supports dot notation for nested fields (e.g., 'author.name'). When True, all metadata is included (flattened). When a list, only specified fields are included.", "default": false, "examples": [ true, false, [ "title", "author.name", "author.email", "tags" ] ] }, "with_file_context": { "type": "boolean", "title": "With File Context", "description": "Use an LLM to generate a short context for each chunk that situates it within the full document, improving retrieval accuracy.", "default": false } }, "type": "object", "title": "ContextualizationConfig" }, "LsfStoreConfig": { "properties": {}, "type": "object", "title": "LsfStoreConfig", "description": "Learned-scoring-function settings a store opts into; an empty object enables it." }, "FileCounts": { "properties": { "pending": { "type": "integer", "title": "Pending", "description": "Number of files waiting to be processed", "default": 0, "examples": [ 5 ] }, "in_progress": { "type": "integer", "title": "In Progress", "description": "Number of files currently being processed", "default": 0, "examples": [ 5 ] }, "cancelled": { "type": "integer", "title": "Cancelled", "description": "Number of files whose processing was cancelled", "default": 0, "examples": [ 2 ] }, "completed": { "type": "integer", "title": "Completed", "description": "Number of successfully processed files", "default": 0, "examples": [ 42 ] }, "failed": { "type": "integer", "title": "Failed", "description": "Number of files that failed processing", "default": 0, "examples": [ 1 ] }, "total": { "type": "integer", "title": "Total", "description": "Total number of files", "default": 0, "examples": [ 50 ] } }, "type": "object", "title": "FileCounts", "description": "Tracks counts of files in different states within a store." }, "StoreStatus": { "type": "string", "enum": [ "expired", "in_progress", "completed", "failed" ], "title": "StoreStatus", "description": "Status of a store." }, "StoreCopyInfo": { "properties": { "role": { "type": "string", "enum": [ "source", "target" ], "title": "Role", "description": "Whether this store is copied from or into" }, "status": { "type": "string", "enum": [ "in_progress", "failed" ], "title": "Status", "description": "Progress of the copy" }, "peer_store_id": { "type": "string", "title": "Peer Store Id", "description": "The other store of the copy" }, "started_at": { "type": "string", "format": "date-time", "title": "Started At", "description": "When the copy was requested" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Why the copy failed, when it did" } }, "type": "object", "required": [ "role", "status", "peer_store_id", "started_at" ], "title": "StoreCopyInfo", "description": "Progress of a store copy, present on both the source and the target while it runs." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") store = mxbai.stores.update( store_identifier="my-knowledge-base", name="updated-knowledge-base", description="Updated product documentation and FAQs", metadata={"version": "2.0"}, ) print(store) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") store = await mxbai.stores.update( store_identifier="my-knowledge-base", name="updated-knowledge-base", description="Updated product documentation and FAQs", metadata={"version": "2.0"}, ) print(store) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const store = await mxbai.stores.update("my-knowledge-base", { name: "updated-knowledge-base", description: "Updated product documentation and FAQs", metadata: { version: "2.0" }, }); console.log(store); ``` cURL: ```bash curl -X PUT https://api.mixedbread.com/v1/stores/my-knowledge-base \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -d '{ "name": "updated-knowledge-base", "description": "Updated product documentation and FAQs", "metadata": {"version": "2.0"} }' ``` # Get Metadata Facets URL: https://www.mixedbread.com/api-reference/endpoints/stores/search/get-metadata-facets Get metadata facets ```json { "paths": { "/v1/stores/metadata-facets": { "post": { "tags": [ "stores" ], "summary": "Get Metadata Facets", "operationId": "get_metadata_facets", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataFacetsParams", "description": "The parameters for getting metadata facets" } } }, "required": true }, "responses": { "200": { "description": "The metadata facets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataFacets" }, "example": { "facets": { "category": { "report": 3, "press": 2 }, "year": { "2022": 1, "2023": 2, "2024": 2 }, "author.name": { "alice": 2, "bob": 1, "carol": 2 } } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } } }, "components": { "schemas": { "MetadataFacetsParams": { "properties": { "store_identifiers": { "items": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ] }, "type": "array", "maxItems": 64, "minItems": 1, "title": "Store Identifiers", "description": "IDs or names of stores" }, "top_k": { "type": "integer", "maximum": 10000, "minimum": 1, "title": "Top K", "description": "Number of results to return", "default": 10 }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" }, { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Filters", "description": "Optional filter conditions" }, "file_ids": { "anyOf": [ { "prefixItems": [ { "$ref": "#/components/schemas/ConditionOperator" }, { "items": { "type": "string", "format": "uuid" }, "type": "array" } ], "type": "array", "maxItems": 2, "minItems": 2 }, { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "File Ids", "description": "Optional list of file IDs to filter chunks by (inclusion filter)", "examples": [ [ "123e4567-e89b-12d3-a456-426614174000", "123e4567-e89b-12d3-a456-426614174001" ], [ "in", [ "123e4567-e89b-12d3-a456-426614174000" ] ], [ "not_in", [ "123e4567-e89b-12d3-a456-426614174000" ] ] ] }, "query": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "title": "Query", "description": "Search query text", "examples": [ "how to configure SSL" ] }, "search_options": { "$ref": "#/components/schemas/StoreChunkSearchOptions", "description": "Search configuration options" }, "facets": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Facets", "description": "Optional list of facets to return. Use dot for nested fields.", "examples": [ "author", "year", "author.name" ] }, "max_fields": { "type": "integer", "maximum": 256, "minimum": 1, "title": "Max Fields", "description": "Maximum number of distinct metadata fields (keys) to return.", "default": 64 }, "max_values_per_field": { "type": "integer", "maximum": 256, "minimum": 1, "title": "Max Values Per Field", "description": "Maximum number of distinct values returned per field, ranked by count.", "default": 32 }, "max_files": { "type": "integer", "maximum": 100000, "minimum": 1, "title": "Max Files", "description": "Maximum number of store files scanned to compute facets.", "default": 10000 } }, "type": "object", "required": [ "store_identifiers" ], "title": "MetadataFacetsParams", "description": "Parameters for getting metadata facets." }, "SearchFilter-Input": { "properties": { "all": { "anyOf": [ { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "All", "description": "List of conditions or filters to be ANDed together", "examples": [ [ { "key": "price", "operator": "gt", "value": "100" }, { "key": "color", "operator": "eq", "value": "red" } ], null ] }, "any": { "anyOf": [ { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Any", "description": "List of conditions or filters to be ORed together", "examples": [ [ { "key": "price", "operator": "gt", "value": "100" }, { "key": "color", "operator": "eq", "value": "red" } ], null ] }, "none": { "anyOf": [ { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "None", "description": "List of conditions or filters to be NOTed", "examples": [ [ { "key": "price", "operator": "gt", "value": "100" }, { "key": "color", "operator": "eq", "value": "red" } ], null ] } }, "type": "object", "title": "SearchFilter", "description": "Represents a filter with AND, OR, and NOT conditions." }, "SearchFilterCondition": { "properties": { "key": { "type": "string", "title": "Key", "description": "The field to apply the condition on", "examples": [ "price", "color" ] }, "value": { "title": "Value", "description": "The value to compare against", "examples": [ "100", "red" ] }, "operator": { "$ref": "#/components/schemas/ConditionOperator", "description": "The operator for the condition", "examples": [ "eq", "gt" ] } }, "type": "object", "required": [ "key", "value", "operator" ], "title": "SearchFilterCondition", "description": "Represents a condition with a field, operator, and value." }, "ConditionOperator": { "type": "string", "enum": [ "eq", "not_eq", "gt", "gte", "lt", "lte", "in", "not_in", "like", "contains", "starts_with", "not_like", "regex" ], "title": "ConditionOperator", "description": "Operator for a filter condition." }, "StoreChunkSearchOptions": { "properties": { "score_threshold": { "type": "number", "maximum": 1, "minimum": 0, "title": "Score Threshold", "description": "Minimum similarity score threshold", "default": 0 }, "rewrite_query": { "type": "boolean", "title": "Rewrite Query", "description": "Whether to rewrite the query. Ignored when agentic is enabled (the agent handles query decomposition).", "default": false }, "rerank": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/RerankConfig" }, { "type": "null" } ], "title": "Rerank", "description": "Whether to rerank results and optional reranking configuration. Ignored when agentic is enabled (the agent handles ranking)." }, "agentic": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/AgenticSearchConfig" }, { "type": "null" } ], "title": "Agentic", "description": "Whether to use agentic multi-query search with automatic query decomposition and ranking. When enabled, rewrite_query and rerank options are ignored." }, "lsf": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Lsf", "description": "Whether to apply the learned scoring function to second-stage scoring. Requires weights configured for the searched stores; silently skipped otherwise." }, "return_metadata": { "type": "boolean", "title": "Return Metadata", "description": "Whether to return file metadata", "default": true }, "apply_search_rules": { "type": "boolean", "title": "Apply Search Rules", "description": "Whether to apply search rules", "default": true } }, "type": "object", "title": "StoreChunkSearchOptions", "description": "Options for configuring store chunk searches." }, "RerankConfig": { "properties": { "model": { "type": "string", "maxLength": 500, "minLength": 1, "title": "Model", "description": "The name of the reranking model", "default": "mixedbread-ai/mxbai-rerank-v3.1-listwise", "examples": [ "rerank_model" ] }, "with_metadata": { "anyOf": [ { "type": "boolean" }, { "items": { "type": "string" }, "type": "array" } ], "title": "With Metadata", "description": "Whether to include metadata in the reranked results", "default": false, "examples": [ true, false, [ "metadata1", "metadata2" ] ] }, "top_k": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "title": "Top K", "description": "Maximum number of results to return after reranking. If None, returns all reranked results.", "examples": [ 10, 50, 100 ] } }, "type": "object", "title": "RerankConfig", "description": "Represents a reranking configuration." }, "AgenticSearchConfig": { "properties": { "max_rounds": { "type": "integer", "maximum": 10, "minimum": 1, "title": "Max Rounds", "description": "Maximum number of search rounds", "default": 3 }, "queries_per_round": { "type": "integer", "maximum": 10, "minimum": 1, "title": "Queries Per Round", "description": "Maximum queries per round", "default": 4 }, "strict_top_k": { "type": "boolean", "title": "Strict Top K", "description": "Whether the agent fills the final ranking to top_k chunks from what it retrieved, capped at top_k, instead of returning only the chunks it judged relevant", "default": false }, "media_content": { "type": "string", "enum": [ "auto", "never", "always" ], "title": "Media Content", "description": "Controls when retrieved image content is provided to the agent. `auto` sends images only when no OCR text or summary is available, `never` disables image content, and `always` sends image content when available. Currently not forwarded: the search agent runs without image content.", "default": "auto" }, "instructions": { "anyOf": [ { "type": "string", "maxLength": 5000, "minLength": 1 }, { "type": "null" } ], "title": "Instructions", "description": "Additional custom instructions (followed only when not in conflict with existing rules)" }, "verbose": { "type": "boolean", "title": "Verbose", "description": "Internal: when set, the response includes a `trace` field with the full tool-call timeline. Used by the Mixedbread playground; not part of the documented public API.", "default": false } }, "type": "object", "title": "AgenticSearchConfig", "description": "Configuration for agentic multi-query search." }, "MetadataFacets": { "properties": { "facets": { "additionalProperties": { "additionalProperties": true, "type": "object" }, "type": "object", "title": "Facets", "description": "Metadata facets", "examples": [ { "author": { "count": 1, "value": "John Doe" }, "year": { "count": 2, "value": "2024" } } ] } }, "type": "object", "required": [ "facets" ], "title": "MetadataFacets", "description": "Represents metadata facets for a store." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") response = mxbai.stores.metadata_facets( store_identifiers=["my-knowledge-base"], facets=["author", "year"], ) print(response.facets) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") response = await mxbai.stores.metadata_facets( store_identifiers=["my-knowledge-base"], facets=["author", "year"], ) print(response.facets) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const response = await mxbai.stores.metadataFacets({ store_identifiers: ["my-knowledge-base"], facets: ["author", "year"], }); console.log(response.facets); ``` cURL: ```bash curl -X POST https://api.mixedbread.com/v1/stores/metadata-facets \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -d '{ "store_identifiers": ["my-knowledge-base"], "facets": ["author", "year"] }' ``` # Grep Store Chunks URL: https://www.mixedbread.com/api-reference/endpoints/stores/search/grep-store-chunks Match store chunks against a regular expression. Unlike `/stores/search`, this runs your regex against the literal text of each chunk. Use it to find chunks containing a specific token, identifier, error code, or literal phrase. ```json { "paths": { "/v1/stores/grep": { "post": { "tags": [ "stores" ], "summary": "Grep Store Chunks", "description": "Unlike `/stores/search`, this runs your regex against the literal text of each\nchunk. Use it to find chunks containing a specific token, identifier, error code,\nor literal phrase.\n\ngrep matches across all requested stores and returns at most `top_k` chunks in total.\nMatches are unranked and interleaved across stores in the order requested, preserving each\nstore's result order. Pagination is not supported; raise `top_k` to retrieve more matches.", "operationId": "grep_store_chunks", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "X-Mxbai-Tool-Ticket", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Ticket from a chat completion's `tool_tickets`, proving this call runs a tool call that completion asked for. Redeems once, and bills the operation at the discounted agent rate.", "title": "X-Mxbai-Tool-Ticket" }, "description": "Ticket from a chat completion's `tool_tickets`, proving this call runs a tool call that completion asked for. Redeems once, and bills the operation at the discounted agent rate." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreChunkGrepParams", "description": "Grep parameters including the regular expression pattern, targets and filters" } } } }, "responses": { "200": { "description": "List of chunks whose text matches the pattern", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreGrepResponse" }, "example": { "object": "list", "data": [ { "chunk_index": 3, "mime_type": "text/plain", "model": "mxbai-omni", "score": 1, "file_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "filename": "error_logs.txt", "store_id": "c3d4e5f6-a7b8-9012-cdef-345678901234", "metadata": { "source": "upload", "page": 2 }, "type": "text", "text": "Encountered ERR-4021 while processing the request payload." }, { "chunk_index": 7, "mime_type": "text/plain", "model": "mxbai-omni", "score": 1, "file_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012", "filename": "incident_report.md", "store_id": "c3d4e5f6-a7b8-9012-cdef-345678901234", "metadata": { "category": "ops" }, "type": "text", "text": "Root cause analysis points to ERR-1337 raised by the upstream service." } ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "StoreChunkGrepParams": { "properties": { "store_identifiers": { "items": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ] }, "type": "array", "maxItems": 64, "minItems": 1, "title": "Store Identifiers", "description": "IDs or names of stores" }, "top_k": { "type": "integer", "maximum": 10000, "minimum": 1, "title": "Top K", "description": "Number of results to return", "default": 10 }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" }, { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Filters", "description": "Optional filter conditions" }, "file_ids": { "anyOf": [ { "prefixItems": [ { "$ref": "#/components/schemas/ConditionOperator" }, { "items": { "type": "string", "format": "uuid" }, "type": "array" } ], "type": "array", "maxItems": 2, "minItems": 2 }, { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "File Ids", "description": "Optional list of file IDs to filter chunks by (inclusion filter)", "examples": [ [ "123e4567-e89b-12d3-a456-426614174000", "123e4567-e89b-12d3-a456-426614174001" ], [ "in", [ "123e4567-e89b-12d3-a456-426614174000" ] ], [ "not_in", [ "123e4567-e89b-12d3-a456-426614174000" ] ] ] }, "pattern": { "type": "string", "maxLength": 1024, "minLength": 1, "title": "Pattern", "description": "Regular expression (RE2 syntax) matched against chunk text", "examples": [ "ERR-\\d{4}", "invoice|receipt" ] }, "targets": { "items": { "$ref": "#/components/schemas/StoreChunkGrepTarget" }, "type": "array", "minItems": 1, "title": "Targets", "description": "Chunk content groups to match against. `text` matches the original text of text chunks; `generated` matches ingestion-derived fields (transcription, OCR text, summaries)." }, "case_sensitive": { "type": "boolean", "title": "Case Sensitive", "description": "Whether the regular expression is case-sensitive", "default": false }, "return_metadata": { "type": "boolean", "title": "Return Metadata", "description": "Whether to return file metadata", "default": true } }, "type": "object", "required": [ "store_identifiers", "pattern" ], "title": "StoreChunkGrepParams", "description": "Parameters for matching store chunks against a regular expression.\n\nUnlike semantic search, grep runs your regex against the literal text of each\nchunk. It finds chunks whose text matches the pattern." }, "SearchFilter-Input": { "properties": { "all": { "anyOf": [ { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "All", "description": "List of conditions or filters to be ANDed together", "examples": [ [ { "key": "price", "operator": "gt", "value": "100" }, { "key": "color", "operator": "eq", "value": "red" } ], null ] }, "any": { "anyOf": [ { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Any", "description": "List of conditions or filters to be ORed together", "examples": [ [ { "key": "price", "operator": "gt", "value": "100" }, { "key": "color", "operator": "eq", "value": "red" } ], null ] }, "none": { "anyOf": [ { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "None", "description": "List of conditions or filters to be NOTed", "examples": [ [ { "key": "price", "operator": "gt", "value": "100" }, { "key": "color", "operator": "eq", "value": "red" } ], null ] } }, "type": "object", "title": "SearchFilter", "description": "Represents a filter with AND, OR, and NOT conditions." }, "SearchFilterCondition": { "properties": { "key": { "type": "string", "title": "Key", "description": "The field to apply the condition on", "examples": [ "price", "color" ] }, "value": { "title": "Value", "description": "The value to compare against", "examples": [ "100", "red" ] }, "operator": { "$ref": "#/components/schemas/ConditionOperator", "description": "The operator for the condition", "examples": [ "eq", "gt" ] } }, "type": "object", "required": [ "key", "value", "operator" ], "title": "SearchFilterCondition", "description": "Represents a condition with a field, operator, and value." }, "ConditionOperator": { "type": "string", "enum": [ "eq", "not_eq", "gt", "gte", "lt", "lte", "in", "not_in", "like", "contains", "starts_with", "not_like", "regex" ], "title": "ConditionOperator", "description": "Operator for a filter condition." }, "StoreChunkGrepTarget": { "type": "string", "enum": [ "text", "generated" ], "title": "StoreChunkGrepTarget", "description": "Logical chunk content groups the grep tool can match against.\n\nThese map to one or more underlying chunk fields:\n\n- ``text`` → text chunks' ``text`` field (original text content).\n- ``generated`` → fields produced during ingestion (``transcription`` for audio/video,\n ``ocr_text`` for images, and ``summary`` across modalities)." }, "StoreGrepResponse": { "properties": { "object": { "type": "string", "const": "list", "title": "Object", "description": "The object type of the response", "default": "list" }, "data": { "items": { "oneOf": [ { "$ref": "#/components/schemas/mxbai_omni__core__store__models__chunk_types__ScoredTextInputChunk" }, { "$ref": "#/components/schemas/mxbai_omni__core__store__models__chunk_types__ScoredImageUrlInputChunk" }, { "$ref": "#/components/schemas/mxbai_omni__core__store__models__chunk_types__ScoredAudioUrlInputChunk" }, { "$ref": "#/components/schemas/mxbai_omni__core__store__models__chunk_types__ScoredVideoUrlInputChunk" } ], "discriminator": { "propertyName": "type", "mapping": { "audio_url": "#/components/schemas/mxbai_omni__core__store__models__chunk_types__ScoredAudioUrlInputChunk", "image_url": "#/components/schemas/mxbai_omni__core__store__models__chunk_types__ScoredImageUrlInputChunk", "text": "#/components/schemas/mxbai_omni__core__store__models__chunk_types__ScoredTextInputChunk", "video_url": "#/components/schemas/mxbai_omni__core__store__models__chunk_types__ScoredVideoUrlInputChunk" } } }, "type": "array", "title": "Data", "description": "The list of chunks matching the pattern" } }, "type": "object", "required": [ "data" ], "title": "StoreGrepResponse" }, "mxbai_omni__core__store__models__chunk_types__ScoredTextInputChunk": { "properties": { "chunk_index": { "type": "integer", "title": "Chunk Index", "description": "position of the chunk in a file", "examples": [ 0, 1, 2, 3, 4 ] }, "mime_type": { "type": "string", "title": "Mime Type", "description": "mime type of the chunk", "default": "text/plain", "examples": [ "text/plain" ] }, "generated_metadata": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/MarkdownChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/TextChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/EmailChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CsvChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/PDFChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CodeChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/AudioChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/VideoChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/ImageChunkGeneratedMetadata" } ], "discriminator": { "propertyName": "type", "mapping": { "audio": "#/components/schemas/AudioChunkGeneratedMetadata", "code": "#/components/schemas/CodeChunkGeneratedMetadata", "csv": "#/components/schemas/CsvChunkGeneratedMetadata", "email": "#/components/schemas/EmailChunkGeneratedMetadata", "image": "#/components/schemas/ImageChunkGeneratedMetadata", "markdown": "#/components/schemas/MarkdownChunkGeneratedMetadata", "pdf": "#/components/schemas/PDFChunkGeneratedMetadata", "text": "#/components/schemas/TextChunkGeneratedMetadata", "video": "#/components/schemas/VideoChunkGeneratedMetadata" } } }, { "type": "null" } ], "title": "Generated Metadata", "description": "metadata of the chunk", "examples": [ { "file_size": 1024, "file_type": "text/plain", "language": "en", "type": "text", "word_count": 100 } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "model used for this chunk", "examples": [ "text-embedding-ada-002", "clip-vit-large-patch14" ] }, "score": { "type": "number", "title": "Score", "description": "score of the chunk", "examples": [ 0.5 ] }, "file_id": { "type": "string", "title": "File Id", "description": "file id", "examples": [ "file1" ] }, "filename": { "type": "string", "title": "Filename", "description": "filename", "examples": [ "file1" ] }, "store_id": { "type": "string", "title": "Store Id", "description": "store id", "examples": [ "store1" ] }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Id", "description": "external identifier for this file", "examples": [ "ext-123" ] }, "metadata": { "anyOf": [ {}, { "type": "null" } ], "title": "Metadata", "description": "file metadata", "examples": [ { "key": "value" } ] }, "file_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Url", "description": "Presigned URL to download the file this chunk belongs to; null when there is no stored file", "examples": [ "https://storage.mixedbread.com/org1/files/file1.pdf?X-Amz-Signature=..." ] }, "type": { "type": "string", "const": "text", "title": "Type", "description": "Input type identifier", "default": "text" }, "offset": { "type": "integer", "title": "Offset", "description": "The offset of the text in the file relative to the start of the file.", "default": 0, "examples": [ 0, 13, 42 ] }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text", "description": "Text content" }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context", "description": "LLM-generated context that situates this chunk within its source document", "examples": [ "This chunk is from an SEC filing on ACME corp's Q2 2023 performance." ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "summary of the text chunk", "examples": [ "A short overview of ACME's Q2 2023 performance." ] } }, "type": "object", "required": [ "chunk_index", "score", "file_id", "filename", "store_id" ], "title": "ScoredTextInputChunk" }, "MarkdownChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "markdown", "title": "Type", "default": "markdown" }, "file_type": { "type": "string", "const": "text/markdown", "title": "File Type", "default": "text/markdown" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "chunk_headings": { "items": { "$ref": "#/components/schemas/MarkdownHeading" }, "type": "array", "title": "Chunk Headings" }, "heading_context": { "items": { "$ref": "#/components/schemas/MarkdownHeading" }, "type": "array", "title": "Heading Context" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" }, "frontmatter": { "additionalProperties": true, "type": "object", "title": "Frontmatter" } }, "additionalProperties": true, "type": "object", "title": "MarkdownChunkGeneratedMetadata" }, "MarkdownHeading": { "properties": { "level": { "type": "integer", "title": "Level" }, "text": { "type": "string", "title": "Text" } }, "type": "object", "required": [ "level", "text" ], "title": "MarkdownHeading" }, "TextChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "text", "title": "Type", "default": "text" }, "file_type": { "type": "string", "enum": [ "text/plain", "message/rfc822" ], "title": "File Type", "default": "text/plain" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "title": "TextChunkGeneratedMetadata" }, "EmailChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "email", "title": "Type", "default": "email" }, "file_type": { "type": "string", "title": "File Type", "default": "message/rfc822" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subject" }, "from_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From Email" }, "to_emails": { "items": { "type": "string" }, "type": "array", "title": "To Emails" }, "cc_emails": { "items": { "type": "string" }, "type": "array", "title": "Cc Emails" }, "bcc_emails": { "items": { "type": "string" }, "type": "array", "title": "Bcc Emails" }, "date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Date" }, "attachment_names": { "items": { "type": "string" }, "type": "array", "title": "Attachment Names" } }, "additionalProperties": true, "type": "object", "title": "EmailChunkGeneratedMetadata" }, "CsvChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "csv", "title": "Type", "default": "csv" }, "file_type": { "type": "string", "const": "text/csv", "title": "File Type", "default": "text/csv" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "start_row": { "type": "integer", "title": "Start Row", "default": 0 }, "num_rows": { "type": "integer", "title": "Num Rows", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "title": "CsvChunkGeneratedMetadata" }, "PDFChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "pdf", "title": "Type", "default": "pdf" }, "file_type": { "type": "string", "const": "application/pdf", "title": "File Type", "default": "application/pdf" }, "total_pages": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Pages" }, "total_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Size" }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" }, "layout": { "anyOf": [ { "$ref": "#/components/schemas/LayoutMetadata" }, { "type": "null" } ] } }, "additionalProperties": true, "type": "object", "title": "PDFChunkGeneratedMetadata" }, "LayoutMetadata": { "properties": { "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Width" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Height" }, "elements": { "items": { "$ref": "#/components/schemas/LayoutElement" }, "type": "array", "title": "Elements" } }, "type": "object", "title": "LayoutMetadata", "description": "Per-page layout for chunks parsed in high-quality (visual) mode.\n\n``elements`` are ordered by reading order (list position == reading order).\n``width``/``height`` are the page-image dimensions the ``bbox`` coords are\nrelative to, so consumers can normalize/render without a second fetch.\n\nLayout is part of the generated metadata payload and is returned with the\nchunk whenever present." }, "LayoutElement": { "properties": { "bbox": { "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" }, { "type": "number" } ], "type": "array", "maxItems": 4, "minItems": 4, "title": "Bbox" }, "type": { "type": "string", "title": "Type" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text" } }, "type": "object", "required": [ "bbox", "type" ], "title": "LayoutElement", "description": "A single detected layout element and its location on the page image." }, "CodeChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "code", "title": "Type", "default": "code" }, "file_type": { "type": "string", "title": "File Type" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "required": [ "file_type" ], "title": "CodeChunkGeneratedMetadata" }, "AudioChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "audio", "title": "Type", "default": "audio" }, "file_type": { "type": "string", "title": "File Type", "default": "audio/mpeg" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "total_duration_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Duration Seconds" }, "sample_rate": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Sample Rate" }, "channels": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Channels" }, "audio_format": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Audio Format" }, "bpm": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bpm" }, "speakers": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Speakers" }, "speaker_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Speaker Count" }, "speaker_turns": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SpeakerTurn" }, "type": "array" }, { "type": "null" } ], "title": "Speaker Turns" }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "title": "AudioChunkGeneratedMetadata" }, "SpeakerTurn": { "properties": { "speaker": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Speaker" }, "text": { "type": "string", "title": "Text" }, "start_time_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Start Time Seconds" }, "end_time_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "End Time Seconds" } }, "type": "object", "required": [ "text" ], "title": "SpeakerTurn" }, "VideoChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "video", "title": "Type", "default": "video" }, "file_type": { "type": "string", "title": "File Type", "default": "video/mp4" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "total_duration_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Duration Seconds" }, "fps": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Fps" }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Width" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Height" }, "frame_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Frame Count" }, "has_audio_stream": { "type": "boolean", "title": "Has Audio Stream", "default": false }, "bpm": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bpm" }, "speakers": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Speakers" }, "speaker_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Speaker Count" }, "speaker_turns": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SpeakerTurn" }, "type": "array" }, { "type": "null" } ], "title": "Speaker Turns" }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "title": "VideoChunkGeneratedMetadata" }, "ImageChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "image", "title": "Type", "default": "image" }, "file_type": { "type": "string", "title": "File Type", "default": "image/jpeg" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Width" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Height" }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" }, "layout": { "anyOf": [ { "$ref": "#/components/schemas/LayoutMetadata" }, { "type": "null" } ] } }, "additionalProperties": true, "type": "object", "title": "ImageChunkGeneratedMetadata" }, "mxbai_omni__core__store__models__chunk_types__ScoredImageUrlInputChunk": { "properties": { "chunk_index": { "type": "integer", "title": "Chunk Index", "description": "position of the chunk in a file", "examples": [ 0, 1, 2, 3, 4 ] }, "mime_type": { "type": "string", "title": "Mime Type", "description": "mime type of the chunk", "default": "image/jpeg", "examples": [ "image/jpeg" ] }, "generated_metadata": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/MarkdownChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/TextChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/EmailChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CsvChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/PDFChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CodeChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/AudioChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/VideoChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/ImageChunkGeneratedMetadata" } ], "discriminator": { "propertyName": "type", "mapping": { "audio": "#/components/schemas/AudioChunkGeneratedMetadata", "code": "#/components/schemas/CodeChunkGeneratedMetadata", "csv": "#/components/schemas/CsvChunkGeneratedMetadata", "email": "#/components/schemas/EmailChunkGeneratedMetadata", "image": "#/components/schemas/ImageChunkGeneratedMetadata", "markdown": "#/components/schemas/MarkdownChunkGeneratedMetadata", "pdf": "#/components/schemas/PDFChunkGeneratedMetadata", "text": "#/components/schemas/TextChunkGeneratedMetadata", "video": "#/components/schemas/VideoChunkGeneratedMetadata" } } }, { "type": "null" } ], "title": "Generated Metadata", "description": "metadata of the chunk", "examples": [ { "file_size": 1024, "file_type": "text/plain", "language": "en", "type": "text", "word_count": 100 } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "model used for this chunk", "examples": [ "text-embedding-ada-002", "clip-vit-large-patch14" ] }, "score": { "type": "number", "title": "Score", "description": "score of the chunk", "examples": [ 0.5 ] }, "file_id": { "type": "string", "title": "File Id", "description": "file id", "examples": [ "file1" ] }, "filename": { "type": "string", "title": "Filename", "description": "filename", "examples": [ "file1" ] }, "store_id": { "type": "string", "title": "Store Id", "description": "store id", "examples": [ "store1" ] }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Id", "description": "external identifier for this file", "examples": [ "ext-123" ] }, "metadata": { "anyOf": [ {}, { "type": "null" } ], "title": "Metadata", "description": "file metadata", "examples": [ { "key": "value" } ] }, "file_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Url", "description": "Presigned URL to download the file this chunk belongs to; null when there is no stored file", "examples": [ "https://storage.mixedbread.com/org1/files/file1.pdf?X-Amz-Signature=..." ] }, "type": { "type": "string", "const": "image_url", "title": "Type", "description": "Input type identifier", "default": "image_url" }, "ocr_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ocr Text", "description": "ocr text of the image", "examples": [ "2025 Financial Report" ] }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context", "description": "LLM-generated context that situates this image within its source document", "examples": [ "This page contains ACME's Q2 2023 financial results." ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "summary of the image", "examples": [ "A financial report for 2025" ] }, "image_url": { "anyOf": [ { "$ref": "#/components/schemas/ImageUrl-Output" }, { "type": "null" } ], "description": "Image URL" } }, "type": "object", "required": [ "chunk_index", "score", "file_id", "filename", "store_id" ], "title": "ScoredImageUrlInputChunk" }, "ImageUrl-Output": { "properties": { "url": { "type": "string", "title": "Url", "description": "The image URL. Can be either a URL or a Data URI." }, "format": { "type": "string", "title": "Format", "description": "The image format/mimetype", "default": "" } }, "type": "object", "required": [ "url" ], "title": "ImageUrl", "description": "Model for image URL validation." }, "mxbai_omni__core__store__models__chunk_types__ScoredAudioUrlInputChunk": { "properties": { "chunk_index": { "type": "integer", "title": "Chunk Index", "description": "position of the chunk in a file", "examples": [ 0, 1, 2, 3, 4 ] }, "mime_type": { "type": "string", "title": "Mime Type", "description": "mime type of the chunk", "default": "audio/mpeg", "examples": [ "audio/mpeg" ] }, "generated_metadata": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/MarkdownChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/TextChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/EmailChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CsvChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/PDFChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CodeChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/AudioChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/VideoChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/ImageChunkGeneratedMetadata" } ], "discriminator": { "propertyName": "type", "mapping": { "audio": "#/components/schemas/AudioChunkGeneratedMetadata", "code": "#/components/schemas/CodeChunkGeneratedMetadata", "csv": "#/components/schemas/CsvChunkGeneratedMetadata", "email": "#/components/schemas/EmailChunkGeneratedMetadata", "image": "#/components/schemas/ImageChunkGeneratedMetadata", "markdown": "#/components/schemas/MarkdownChunkGeneratedMetadata", "pdf": "#/components/schemas/PDFChunkGeneratedMetadata", "text": "#/components/schemas/TextChunkGeneratedMetadata", "video": "#/components/schemas/VideoChunkGeneratedMetadata" } } }, { "type": "null" } ], "title": "Generated Metadata", "description": "metadata of the chunk", "examples": [ { "file_size": 1024, "file_type": "text/plain", "language": "en", "type": "text", "word_count": 100 } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "model used for this chunk", "examples": [ "text-embedding-ada-002", "clip-vit-large-patch14" ] }, "score": { "type": "number", "title": "Score", "description": "score of the chunk", "examples": [ 0.5 ] }, "file_id": { "type": "string", "title": "File Id", "description": "file id", "examples": [ "file1" ] }, "filename": { "type": "string", "title": "Filename", "description": "filename", "examples": [ "file1" ] }, "store_id": { "type": "string", "title": "Store Id", "description": "store id", "examples": [ "store1" ] }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Id", "description": "external identifier for this file", "examples": [ "ext-123" ] }, "metadata": { "anyOf": [ {}, { "type": "null" } ], "title": "Metadata", "description": "file metadata", "examples": [ { "key": "value" } ] }, "file_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Url", "description": "Presigned URL to download the file this chunk belongs to; null when there is no stored file", "examples": [ "https://storage.mixedbread.com/org1/files/file1.pdf?X-Amz-Signature=..." ] }, "type": { "type": "string", "const": "audio_url", "title": "Type", "description": "Input type identifier", "default": "audio_url" }, "transcription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transcription", "description": "speech recognition (sr) text of the audio", "examples": [ "The year 2025 reports for .." ] }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context", "description": "LLM-generated context that situates this audio chunk within its source file", "examples": [ "This segment introduces ACME's quarterly earnings call." ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "summary of the audio", "examples": [ "A financial report audio for 2025" ] }, "audio_url": { "anyOf": [ { "$ref": "#/components/schemas/AudioUrl" }, { "type": "null" } ], "description": "Audio URL" }, "sampling_rate": { "type": "integer", "title": "Sampling Rate", "description": "The sampling rate of the audio." } }, "type": "object", "required": [ "chunk_index", "score", "file_id", "filename", "store_id", "sampling_rate" ], "title": "ScoredAudioUrlInputChunk" }, "AudioUrl": { "properties": { "url": { "type": "string", "title": "Url", "description": "The audio URL. Can be either a URL or a Data URI." } }, "type": "object", "required": [ "url" ], "title": "AudioUrl", "description": "Model for audio URL validation." }, "mxbai_omni__core__store__models__chunk_types__ScoredVideoUrlInputChunk": { "properties": { "chunk_index": { "type": "integer", "title": "Chunk Index", "description": "position of the chunk in a file", "examples": [ 0, 1, 2, 3, 4 ] }, "mime_type": { "type": "string", "title": "Mime Type", "description": "mime type of the chunk", "default": "video/mp4", "examples": [ "video/mp4" ] }, "generated_metadata": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/MarkdownChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/TextChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/EmailChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CsvChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/PDFChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CodeChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/AudioChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/VideoChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/ImageChunkGeneratedMetadata" } ], "discriminator": { "propertyName": "type", "mapping": { "audio": "#/components/schemas/AudioChunkGeneratedMetadata", "code": "#/components/schemas/CodeChunkGeneratedMetadata", "csv": "#/components/schemas/CsvChunkGeneratedMetadata", "email": "#/components/schemas/EmailChunkGeneratedMetadata", "image": "#/components/schemas/ImageChunkGeneratedMetadata", "markdown": "#/components/schemas/MarkdownChunkGeneratedMetadata", "pdf": "#/components/schemas/PDFChunkGeneratedMetadata", "text": "#/components/schemas/TextChunkGeneratedMetadata", "video": "#/components/schemas/VideoChunkGeneratedMetadata" } } }, { "type": "null" } ], "title": "Generated Metadata", "description": "metadata of the chunk", "examples": [ { "file_size": 1024, "file_type": "text/plain", "language": "en", "type": "text", "word_count": 100 } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "model used for this chunk", "examples": [ "text-embedding-ada-002", "clip-vit-large-patch14" ] }, "score": { "type": "number", "title": "Score", "description": "score of the chunk", "examples": [ 0.5 ] }, "file_id": { "type": "string", "title": "File Id", "description": "file id", "examples": [ "file1" ] }, "filename": { "type": "string", "title": "Filename", "description": "filename", "examples": [ "file1" ] }, "store_id": { "type": "string", "title": "Store Id", "description": "store id", "examples": [ "store1" ] }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Id", "description": "external identifier for this file", "examples": [ "ext-123" ] }, "metadata": { "anyOf": [ {}, { "type": "null" } ], "title": "Metadata", "description": "file metadata", "examples": [ { "key": "value" } ] }, "file_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Url", "description": "Presigned URL to download the file this chunk belongs to; null when there is no stored file", "examples": [ "https://storage.mixedbread.com/org1/files/file1.pdf?X-Amz-Signature=..." ] }, "type": { "type": "string", "const": "video_url", "title": "Type", "description": "Input type identifier", "default": "video_url" }, "transcription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transcription", "description": "speech recognition (sr) text of the video", "examples": [ "The year 2025 reports for .." ] }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context", "description": "LLM-generated context that situates this video chunk within its source file", "examples": [ "This segment demonstrates the product's document search workflow." ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "summary of the video", "examples": [ "A financial report video for 2025" ] }, "video_url": { "anyOf": [ { "$ref": "#/components/schemas/VideoUrl" }, { "type": "null" } ], "description": "Video URL" } }, "type": "object", "required": [ "chunk_index", "score", "file_id", "filename", "store_id" ], "title": "ScoredVideoUrlInputChunk" }, "VideoUrl": { "properties": { "url": { "type": "string", "title": "Url", "description": "The video URL. Can be either a URL or a Data URI." } }, "type": "object", "required": [ "url" ], "title": "VideoUrl", "description": "Model for video URL validation." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") response = mxbai.stores.grep( store_identifiers=["{{STORE_IDENTIFIER}}"], pattern="ERR-\\d{4}", top_k=10, ) for chunk in response.data: print(chunk) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") response = await mxbai.stores.grep( store_identifiers=["{{STORE_IDENTIFIER}}"], pattern="ERR-\\d{4}", top_k=10, ) for chunk in response.data: print(chunk) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const response = await mxbai.stores.grep({ store_identifiers: ["{{STORE_IDENTIFIER}}"], pattern: "ERR-\\d{4}", top_k: 10, }); for (const chunk of response.data) { console.log(chunk); } ``` cURL: ```bash curl -X POST https://api.mixedbread.com/v1/stores/grep \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -d '{ "store_identifiers": ["{{STORE_IDENTIFIER}}"], "pattern": "ERR-\\d{4}", "top_k": 10 }' ``` # List Store Chunks URL: https://www.mixedbread.com/api-reference/endpoints/stores/search/list-store-chunks List store chunks purely by metadata filters, with no embeddings, semantic similarity or reranking. Useful for ranked retrieval over numeric metadata attributes. ```json { "paths": { "/v1/stores/list-chunks": { "post": { "tags": [ "stores" ], "summary": "List Store Chunks", "description": "Unlike `/stores/search`, this endpoint does not require a query and never runs a vector lookup.\nIt returns chunks whose file and chunk metadata satisfy `filters`, optionally ordered by a\nnumeric metadata field via `sort_by`. Useful for ranked retrieval over numeric attributes\n(e.g. price, BPM) and for reproducing the agentic `filter_chunks` tool externally.\n\nlist-chunks filters across all requested stores and returns at most `top_k` chunks in total.\nWith `sort_by`, results are ordered globally by that field. Otherwise results are interleaved\nacross stores in the order requested, preserving each store's result order. Pagination is not\nsupported; raise `top_k` to retrieve more chunks.", "operationId": "list_store_chunks", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreChunkFilterParams", "description": "Filter parameters including metadata filters, optional numeric sort, and pagination options" } } }, "required": true }, "responses": { "200": { "description": "List of chunks matching the metadata filters, optionally ordered by a numeric metadata field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreListChunksResponse" }, "example": { "object": "list", "data": [ { "chunk_index": 0, "mime_type": "text/plain", "model": "mxbai-omni", "score": 1, "file_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "filename": "pricing.csv", "store_id": "c3d4e5f6-a7b8-9012-cdef-345678901234", "metadata": { "category": "pricing", "currency": "USD" }, "type": "text", "text": "Premium plan: $99/month, includes unlimited search across all stores." }, { "chunk_index": 3, "mime_type": "text/plain", "model": "mxbai-omni", "score": 1, "file_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012", "filename": "pricing.csv", "store_id": "c3d4e5f6-a7b8-9012-cdef-345678901234", "metadata": { "category": "pricing", "currency": "USD" }, "type": "text", "text": "Starter plan: $19/month, includes 1,000 search queries per month." } ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } } }, "components": { "schemas": { "StoreChunkFilterParams": { "properties": { "store_identifiers": { "items": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ] }, "type": "array", "maxItems": 64, "minItems": 1, "title": "Store Identifiers", "description": "IDs or names of stores" }, "top_k": { "type": "integer", "maximum": 10000, "minimum": 1, "title": "Top K", "description": "Number of results to return", "default": 10 }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" }, { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Filters", "description": "Optional filter conditions" }, "file_ids": { "anyOf": [ { "prefixItems": [ { "$ref": "#/components/schemas/ConditionOperator" }, { "items": { "type": "string", "format": "uuid" }, "type": "array" } ], "type": "array", "maxItems": 2, "minItems": 2 }, { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "File Ids", "description": "Optional list of file IDs to filter chunks by (inclusion filter)", "examples": [ [ "123e4567-e89b-12d3-a456-426614174000", "123e4567-e89b-12d3-a456-426614174001" ], [ "in", [ "123e4567-e89b-12d3-a456-426614174000" ] ], [ "not_in", [ "123e4567-e89b-12d3-a456-426614174000" ] ] ] }, "sort_by": { "anyOf": [ { "type": "string" }, { "prefixItems": [ { "type": "string" }, { "type": "boolean" } ], "type": "array", "maxItems": 2, "minItems": 2 }, { "type": "null" } ], "title": "Sort By", "description": "Optional sort applied to the returned chunks. Pass a metadata field path or a tuple of (field path, ascending). Unprefixed dot paths target file metadata; generated_metadata.* targets chunk metadata.", "examples": [ "price", [ "price", false ], "campaign.name", [ "generated_metadata.bpm", true ] ] }, "search_options": { "$ref": "#/components/schemas/StoreChunkSearchOptions", "description": "Search configuration options" } }, "type": "object", "required": [ "store_identifiers" ], "title": "StoreChunkFilterParams", "description": "Parameters for listing store chunks by metadata filter." }, "SearchFilter-Input": { "properties": { "all": { "anyOf": [ { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "All", "description": "List of conditions or filters to be ANDed together", "examples": [ [ { "key": "price", "operator": "gt", "value": "100" }, { "key": "color", "operator": "eq", "value": "red" } ], null ] }, "any": { "anyOf": [ { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Any", "description": "List of conditions or filters to be ORed together", "examples": [ [ { "key": "price", "operator": "gt", "value": "100" }, { "key": "color", "operator": "eq", "value": "red" } ], null ] }, "none": { "anyOf": [ { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "None", "description": "List of conditions or filters to be NOTed", "examples": [ [ { "key": "price", "operator": "gt", "value": "100" }, { "key": "color", "operator": "eq", "value": "red" } ], null ] } }, "type": "object", "title": "SearchFilter", "description": "Represents a filter with AND, OR, and NOT conditions." }, "SearchFilterCondition": { "properties": { "key": { "type": "string", "title": "Key", "description": "The field to apply the condition on", "examples": [ "price", "color" ] }, "value": { "title": "Value", "description": "The value to compare against", "examples": [ "100", "red" ] }, "operator": { "$ref": "#/components/schemas/ConditionOperator", "description": "The operator for the condition", "examples": [ "eq", "gt" ] } }, "type": "object", "required": [ "key", "value", "operator" ], "title": "SearchFilterCondition", "description": "Represents a condition with a field, operator, and value." }, "ConditionOperator": { "type": "string", "enum": [ "eq", "not_eq", "gt", "gte", "lt", "lte", "in", "not_in", "like", "contains", "starts_with", "not_like", "regex" ], "title": "ConditionOperator", "description": "Operator for a filter condition." }, "StoreChunkSearchOptions": { "properties": { "score_threshold": { "type": "number", "maximum": 1, "minimum": 0, "title": "Score Threshold", "description": "Minimum similarity score threshold", "default": 0 }, "rewrite_query": { "type": "boolean", "title": "Rewrite Query", "description": "Whether to rewrite the query. Ignored when agentic is enabled (the agent handles query decomposition).", "default": false }, "rerank": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/RerankConfig" }, { "type": "null" } ], "title": "Rerank", "description": "Whether to rerank results and optional reranking configuration. Ignored when agentic is enabled (the agent handles ranking)." }, "agentic": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/AgenticSearchConfig" }, { "type": "null" } ], "title": "Agentic", "description": "Whether to use agentic multi-query search with automatic query decomposition and ranking. When enabled, rewrite_query and rerank options are ignored." }, "lsf": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Lsf", "description": "Whether to apply the learned scoring function to second-stage scoring. Requires weights configured for the searched stores; silently skipped otherwise." }, "return_metadata": { "type": "boolean", "title": "Return Metadata", "description": "Whether to return file metadata", "default": true }, "apply_search_rules": { "type": "boolean", "title": "Apply Search Rules", "description": "Whether to apply search rules", "default": true } }, "type": "object", "title": "StoreChunkSearchOptions", "description": "Options for configuring store chunk searches." }, "RerankConfig": { "properties": { "model": { "type": "string", "maxLength": 500, "minLength": 1, "title": "Model", "description": "The name of the reranking model", "default": "mixedbread-ai/mxbai-rerank-v3.1-listwise", "examples": [ "rerank_model" ] }, "with_metadata": { "anyOf": [ { "type": "boolean" }, { "items": { "type": "string" }, "type": "array" } ], "title": "With Metadata", "description": "Whether to include metadata in the reranked results", "default": false, "examples": [ true, false, [ "metadata1", "metadata2" ] ] }, "top_k": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "title": "Top K", "description": "Maximum number of results to return after reranking. If None, returns all reranked results.", "examples": [ 10, 50, 100 ] } }, "type": "object", "title": "RerankConfig", "description": "Represents a reranking configuration." }, "AgenticSearchConfig": { "properties": { "max_rounds": { "type": "integer", "maximum": 10, "minimum": 1, "title": "Max Rounds", "description": "Maximum number of search rounds", "default": 3 }, "queries_per_round": { "type": "integer", "maximum": 10, "minimum": 1, "title": "Queries Per Round", "description": "Maximum queries per round", "default": 4 }, "strict_top_k": { "type": "boolean", "title": "Strict Top K", "description": "Whether the agent fills the final ranking to top_k chunks from what it retrieved, capped at top_k, instead of returning only the chunks it judged relevant", "default": false }, "media_content": { "type": "string", "enum": [ "auto", "never", "always" ], "title": "Media Content", "description": "Controls when retrieved image content is provided to the agent. `auto` sends images only when no OCR text or summary is available, `never` disables image content, and `always` sends image content when available. Currently not forwarded: the search agent runs without image content.", "default": "auto" }, "instructions": { "anyOf": [ { "type": "string", "maxLength": 5000, "minLength": 1 }, { "type": "null" } ], "title": "Instructions", "description": "Additional custom instructions (followed only when not in conflict with existing rules)" }, "verbose": { "type": "boolean", "title": "Verbose", "description": "Internal: when set, the response includes a `trace` field with the full tool-call timeline. Used by the Mixedbread playground; not part of the documented public API.", "default": false } }, "type": "object", "title": "AgenticSearchConfig", "description": "Configuration for agentic multi-query search." }, "StoreListChunksResponse": { "properties": { "object": { "type": "string", "const": "list", "title": "Object", "description": "The object type of the response", "default": "list" }, "data": { "items": { "oneOf": [ { "$ref": "#/components/schemas/mxbai_omni__core__store__models__chunk_types__ScoredTextInputChunk" }, { "$ref": "#/components/schemas/mxbai_omni__core__store__models__chunk_types__ScoredImageUrlInputChunk" }, { "$ref": "#/components/schemas/mxbai_omni__core__store__models__chunk_types__ScoredAudioUrlInputChunk" }, { "$ref": "#/components/schemas/mxbai_omni__core__store__models__chunk_types__ScoredVideoUrlInputChunk" } ], "discriminator": { "propertyName": "type", "mapping": { "audio_url": "#/components/schemas/mxbai_omni__core__store__models__chunk_types__ScoredAudioUrlInputChunk", "image_url": "#/components/schemas/mxbai_omni__core__store__models__chunk_types__ScoredImageUrlInputChunk", "text": "#/components/schemas/mxbai_omni__core__store__models__chunk_types__ScoredTextInputChunk", "video_url": "#/components/schemas/mxbai_omni__core__store__models__chunk_types__ScoredVideoUrlInputChunk" } } }, "type": "array", "title": "Data", "description": "The list of chunks matching the metadata filters" } }, "type": "object", "required": [ "data" ], "title": "StoreListChunksResponse" }, "mxbai_omni__core__store__models__chunk_types__ScoredTextInputChunk": { "properties": { "chunk_index": { "type": "integer", "title": "Chunk Index", "description": "position of the chunk in a file", "examples": [ 0, 1, 2, 3, 4 ] }, "mime_type": { "type": "string", "title": "Mime Type", "description": "mime type of the chunk", "default": "text/plain", "examples": [ "text/plain" ] }, "generated_metadata": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/MarkdownChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/TextChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/EmailChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CsvChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/PDFChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CodeChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/AudioChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/VideoChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/ImageChunkGeneratedMetadata" } ], "discriminator": { "propertyName": "type", "mapping": { "audio": "#/components/schemas/AudioChunkGeneratedMetadata", "code": "#/components/schemas/CodeChunkGeneratedMetadata", "csv": "#/components/schemas/CsvChunkGeneratedMetadata", "email": "#/components/schemas/EmailChunkGeneratedMetadata", "image": "#/components/schemas/ImageChunkGeneratedMetadata", "markdown": "#/components/schemas/MarkdownChunkGeneratedMetadata", "pdf": "#/components/schemas/PDFChunkGeneratedMetadata", "text": "#/components/schemas/TextChunkGeneratedMetadata", "video": "#/components/schemas/VideoChunkGeneratedMetadata" } } }, { "type": "null" } ], "title": "Generated Metadata", "description": "metadata of the chunk", "examples": [ { "file_size": 1024, "file_type": "text/plain", "language": "en", "type": "text", "word_count": 100 } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "model used for this chunk", "examples": [ "text-embedding-ada-002", "clip-vit-large-patch14" ] }, "score": { "type": "number", "title": "Score", "description": "score of the chunk", "examples": [ 0.5 ] }, "file_id": { "type": "string", "title": "File Id", "description": "file id", "examples": [ "file1" ] }, "filename": { "type": "string", "title": "Filename", "description": "filename", "examples": [ "file1" ] }, "store_id": { "type": "string", "title": "Store Id", "description": "store id", "examples": [ "store1" ] }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Id", "description": "external identifier for this file", "examples": [ "ext-123" ] }, "metadata": { "anyOf": [ {}, { "type": "null" } ], "title": "Metadata", "description": "file metadata", "examples": [ { "key": "value" } ] }, "file_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Url", "description": "Presigned URL to download the file this chunk belongs to; null when there is no stored file", "examples": [ "https://storage.mixedbread.com/org1/files/file1.pdf?X-Amz-Signature=..." ] }, "type": { "type": "string", "const": "text", "title": "Type", "description": "Input type identifier", "default": "text" }, "offset": { "type": "integer", "title": "Offset", "description": "The offset of the text in the file relative to the start of the file.", "default": 0, "examples": [ 0, 13, 42 ] }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text", "description": "Text content" }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context", "description": "LLM-generated context that situates this chunk within its source document", "examples": [ "This chunk is from an SEC filing on ACME corp's Q2 2023 performance." ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "summary of the text chunk", "examples": [ "A short overview of ACME's Q2 2023 performance." ] } }, "type": "object", "required": [ "chunk_index", "score", "file_id", "filename", "store_id" ], "title": "ScoredTextInputChunk" }, "MarkdownChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "markdown", "title": "Type", "default": "markdown" }, "file_type": { "type": "string", "const": "text/markdown", "title": "File Type", "default": "text/markdown" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "chunk_headings": { "items": { "$ref": "#/components/schemas/MarkdownHeading" }, "type": "array", "title": "Chunk Headings" }, "heading_context": { "items": { "$ref": "#/components/schemas/MarkdownHeading" }, "type": "array", "title": "Heading Context" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" }, "frontmatter": { "additionalProperties": true, "type": "object", "title": "Frontmatter" } }, "additionalProperties": true, "type": "object", "title": "MarkdownChunkGeneratedMetadata" }, "MarkdownHeading": { "properties": { "level": { "type": "integer", "title": "Level" }, "text": { "type": "string", "title": "Text" } }, "type": "object", "required": [ "level", "text" ], "title": "MarkdownHeading" }, "TextChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "text", "title": "Type", "default": "text" }, "file_type": { "type": "string", "enum": [ "text/plain", "message/rfc822" ], "title": "File Type", "default": "text/plain" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "title": "TextChunkGeneratedMetadata" }, "EmailChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "email", "title": "Type", "default": "email" }, "file_type": { "type": "string", "title": "File Type", "default": "message/rfc822" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subject" }, "from_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From Email" }, "to_emails": { "items": { "type": "string" }, "type": "array", "title": "To Emails" }, "cc_emails": { "items": { "type": "string" }, "type": "array", "title": "Cc Emails" }, "bcc_emails": { "items": { "type": "string" }, "type": "array", "title": "Bcc Emails" }, "date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Date" }, "attachment_names": { "items": { "type": "string" }, "type": "array", "title": "Attachment Names" } }, "additionalProperties": true, "type": "object", "title": "EmailChunkGeneratedMetadata" }, "CsvChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "csv", "title": "Type", "default": "csv" }, "file_type": { "type": "string", "const": "text/csv", "title": "File Type", "default": "text/csv" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "start_row": { "type": "integer", "title": "Start Row", "default": 0 }, "num_rows": { "type": "integer", "title": "Num Rows", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "title": "CsvChunkGeneratedMetadata" }, "PDFChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "pdf", "title": "Type", "default": "pdf" }, "file_type": { "type": "string", "const": "application/pdf", "title": "File Type", "default": "application/pdf" }, "total_pages": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Pages" }, "total_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Size" }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" }, "layout": { "anyOf": [ { "$ref": "#/components/schemas/LayoutMetadata" }, { "type": "null" } ] } }, "additionalProperties": true, "type": "object", "title": "PDFChunkGeneratedMetadata" }, "LayoutMetadata": { "properties": { "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Width" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Height" }, "elements": { "items": { "$ref": "#/components/schemas/LayoutElement" }, "type": "array", "title": "Elements" } }, "type": "object", "title": "LayoutMetadata", "description": "Per-page layout for chunks parsed in high-quality (visual) mode.\n\n``elements`` are ordered by reading order (list position == reading order).\n``width``/``height`` are the page-image dimensions the ``bbox`` coords are\nrelative to, so consumers can normalize/render without a second fetch.\n\nLayout is part of the generated metadata payload and is returned with the\nchunk whenever present." }, "LayoutElement": { "properties": { "bbox": { "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" }, { "type": "number" } ], "type": "array", "maxItems": 4, "minItems": 4, "title": "Bbox" }, "type": { "type": "string", "title": "Type" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text" } }, "type": "object", "required": [ "bbox", "type" ], "title": "LayoutElement", "description": "A single detected layout element and its location on the page image." }, "CodeChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "code", "title": "Type", "default": "code" }, "file_type": { "type": "string", "title": "File Type" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "required": [ "file_type" ], "title": "CodeChunkGeneratedMetadata" }, "AudioChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "audio", "title": "Type", "default": "audio" }, "file_type": { "type": "string", "title": "File Type", "default": "audio/mpeg" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "total_duration_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Duration Seconds" }, "sample_rate": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Sample Rate" }, "channels": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Channels" }, "audio_format": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Audio Format" }, "bpm": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bpm" }, "speakers": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Speakers" }, "speaker_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Speaker Count" }, "speaker_turns": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SpeakerTurn" }, "type": "array" }, { "type": "null" } ], "title": "Speaker Turns" }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "title": "AudioChunkGeneratedMetadata" }, "SpeakerTurn": { "properties": { "speaker": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Speaker" }, "text": { "type": "string", "title": "Text" }, "start_time_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Start Time Seconds" }, "end_time_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "End Time Seconds" } }, "type": "object", "required": [ "text" ], "title": "SpeakerTurn" }, "VideoChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "video", "title": "Type", "default": "video" }, "file_type": { "type": "string", "title": "File Type", "default": "video/mp4" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "total_duration_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Duration Seconds" }, "fps": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Fps" }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Width" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Height" }, "frame_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Frame Count" }, "has_audio_stream": { "type": "boolean", "title": "Has Audio Stream", "default": false }, "bpm": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bpm" }, "speakers": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Speakers" }, "speaker_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Speaker Count" }, "speaker_turns": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SpeakerTurn" }, "type": "array" }, { "type": "null" } ], "title": "Speaker Turns" }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "title": "VideoChunkGeneratedMetadata" }, "ImageChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "image", "title": "Type", "default": "image" }, "file_type": { "type": "string", "title": "File Type", "default": "image/jpeg" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Width" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Height" }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" }, "layout": { "anyOf": [ { "$ref": "#/components/schemas/LayoutMetadata" }, { "type": "null" } ] } }, "additionalProperties": true, "type": "object", "title": "ImageChunkGeneratedMetadata" }, "mxbai_omni__core__store__models__chunk_types__ScoredImageUrlInputChunk": { "properties": { "chunk_index": { "type": "integer", "title": "Chunk Index", "description": "position of the chunk in a file", "examples": [ 0, 1, 2, 3, 4 ] }, "mime_type": { "type": "string", "title": "Mime Type", "description": "mime type of the chunk", "default": "image/jpeg", "examples": [ "image/jpeg" ] }, "generated_metadata": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/MarkdownChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/TextChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/EmailChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CsvChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/PDFChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CodeChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/AudioChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/VideoChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/ImageChunkGeneratedMetadata" } ], "discriminator": { "propertyName": "type", "mapping": { "audio": "#/components/schemas/AudioChunkGeneratedMetadata", "code": "#/components/schemas/CodeChunkGeneratedMetadata", "csv": "#/components/schemas/CsvChunkGeneratedMetadata", "email": "#/components/schemas/EmailChunkGeneratedMetadata", "image": "#/components/schemas/ImageChunkGeneratedMetadata", "markdown": "#/components/schemas/MarkdownChunkGeneratedMetadata", "pdf": "#/components/schemas/PDFChunkGeneratedMetadata", "text": "#/components/schemas/TextChunkGeneratedMetadata", "video": "#/components/schemas/VideoChunkGeneratedMetadata" } } }, { "type": "null" } ], "title": "Generated Metadata", "description": "metadata of the chunk", "examples": [ { "file_size": 1024, "file_type": "text/plain", "language": "en", "type": "text", "word_count": 100 } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "model used for this chunk", "examples": [ "text-embedding-ada-002", "clip-vit-large-patch14" ] }, "score": { "type": "number", "title": "Score", "description": "score of the chunk", "examples": [ 0.5 ] }, "file_id": { "type": "string", "title": "File Id", "description": "file id", "examples": [ "file1" ] }, "filename": { "type": "string", "title": "Filename", "description": "filename", "examples": [ "file1" ] }, "store_id": { "type": "string", "title": "Store Id", "description": "store id", "examples": [ "store1" ] }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Id", "description": "external identifier for this file", "examples": [ "ext-123" ] }, "metadata": { "anyOf": [ {}, { "type": "null" } ], "title": "Metadata", "description": "file metadata", "examples": [ { "key": "value" } ] }, "file_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Url", "description": "Presigned URL to download the file this chunk belongs to; null when there is no stored file", "examples": [ "https://storage.mixedbread.com/org1/files/file1.pdf?X-Amz-Signature=..." ] }, "type": { "type": "string", "const": "image_url", "title": "Type", "description": "Input type identifier", "default": "image_url" }, "ocr_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ocr Text", "description": "ocr text of the image", "examples": [ "2025 Financial Report" ] }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context", "description": "LLM-generated context that situates this image within its source document", "examples": [ "This page contains ACME's Q2 2023 financial results." ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "summary of the image", "examples": [ "A financial report for 2025" ] }, "image_url": { "anyOf": [ { "$ref": "#/components/schemas/ImageUrl-Output" }, { "type": "null" } ], "description": "Image URL" } }, "type": "object", "required": [ "chunk_index", "score", "file_id", "filename", "store_id" ], "title": "ScoredImageUrlInputChunk" }, "ImageUrl-Output": { "properties": { "url": { "type": "string", "title": "Url", "description": "The image URL. Can be either a URL or a Data URI." }, "format": { "type": "string", "title": "Format", "description": "The image format/mimetype", "default": "" } }, "type": "object", "required": [ "url" ], "title": "ImageUrl", "description": "Model for image URL validation." }, "mxbai_omni__core__store__models__chunk_types__ScoredAudioUrlInputChunk": { "properties": { "chunk_index": { "type": "integer", "title": "Chunk Index", "description": "position of the chunk in a file", "examples": [ 0, 1, 2, 3, 4 ] }, "mime_type": { "type": "string", "title": "Mime Type", "description": "mime type of the chunk", "default": "audio/mpeg", "examples": [ "audio/mpeg" ] }, "generated_metadata": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/MarkdownChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/TextChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/EmailChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CsvChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/PDFChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CodeChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/AudioChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/VideoChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/ImageChunkGeneratedMetadata" } ], "discriminator": { "propertyName": "type", "mapping": { "audio": "#/components/schemas/AudioChunkGeneratedMetadata", "code": "#/components/schemas/CodeChunkGeneratedMetadata", "csv": "#/components/schemas/CsvChunkGeneratedMetadata", "email": "#/components/schemas/EmailChunkGeneratedMetadata", "image": "#/components/schemas/ImageChunkGeneratedMetadata", "markdown": "#/components/schemas/MarkdownChunkGeneratedMetadata", "pdf": "#/components/schemas/PDFChunkGeneratedMetadata", "text": "#/components/schemas/TextChunkGeneratedMetadata", "video": "#/components/schemas/VideoChunkGeneratedMetadata" } } }, { "type": "null" } ], "title": "Generated Metadata", "description": "metadata of the chunk", "examples": [ { "file_size": 1024, "file_type": "text/plain", "language": "en", "type": "text", "word_count": 100 } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "model used for this chunk", "examples": [ "text-embedding-ada-002", "clip-vit-large-patch14" ] }, "score": { "type": "number", "title": "Score", "description": "score of the chunk", "examples": [ 0.5 ] }, "file_id": { "type": "string", "title": "File Id", "description": "file id", "examples": [ "file1" ] }, "filename": { "type": "string", "title": "Filename", "description": "filename", "examples": [ "file1" ] }, "store_id": { "type": "string", "title": "Store Id", "description": "store id", "examples": [ "store1" ] }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Id", "description": "external identifier for this file", "examples": [ "ext-123" ] }, "metadata": { "anyOf": [ {}, { "type": "null" } ], "title": "Metadata", "description": "file metadata", "examples": [ { "key": "value" } ] }, "file_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Url", "description": "Presigned URL to download the file this chunk belongs to; null when there is no stored file", "examples": [ "https://storage.mixedbread.com/org1/files/file1.pdf?X-Amz-Signature=..." ] }, "type": { "type": "string", "const": "audio_url", "title": "Type", "description": "Input type identifier", "default": "audio_url" }, "transcription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transcription", "description": "speech recognition (sr) text of the audio", "examples": [ "The year 2025 reports for .." ] }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context", "description": "LLM-generated context that situates this audio chunk within its source file", "examples": [ "This segment introduces ACME's quarterly earnings call." ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "summary of the audio", "examples": [ "A financial report audio for 2025" ] }, "audio_url": { "anyOf": [ { "$ref": "#/components/schemas/AudioUrl" }, { "type": "null" } ], "description": "Audio URL" }, "sampling_rate": { "type": "integer", "title": "Sampling Rate", "description": "The sampling rate of the audio." } }, "type": "object", "required": [ "chunk_index", "score", "file_id", "filename", "store_id", "sampling_rate" ], "title": "ScoredAudioUrlInputChunk" }, "AudioUrl": { "properties": { "url": { "type": "string", "title": "Url", "description": "The audio URL. Can be either a URL or a Data URI." } }, "type": "object", "required": [ "url" ], "title": "AudioUrl", "description": "Model for audio URL validation." }, "mxbai_omni__core__store__models__chunk_types__ScoredVideoUrlInputChunk": { "properties": { "chunk_index": { "type": "integer", "title": "Chunk Index", "description": "position of the chunk in a file", "examples": [ 0, 1, 2, 3, 4 ] }, "mime_type": { "type": "string", "title": "Mime Type", "description": "mime type of the chunk", "default": "video/mp4", "examples": [ "video/mp4" ] }, "generated_metadata": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/MarkdownChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/TextChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/EmailChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CsvChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/PDFChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CodeChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/AudioChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/VideoChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/ImageChunkGeneratedMetadata" } ], "discriminator": { "propertyName": "type", "mapping": { "audio": "#/components/schemas/AudioChunkGeneratedMetadata", "code": "#/components/schemas/CodeChunkGeneratedMetadata", "csv": "#/components/schemas/CsvChunkGeneratedMetadata", "email": "#/components/schemas/EmailChunkGeneratedMetadata", "image": "#/components/schemas/ImageChunkGeneratedMetadata", "markdown": "#/components/schemas/MarkdownChunkGeneratedMetadata", "pdf": "#/components/schemas/PDFChunkGeneratedMetadata", "text": "#/components/schemas/TextChunkGeneratedMetadata", "video": "#/components/schemas/VideoChunkGeneratedMetadata" } } }, { "type": "null" } ], "title": "Generated Metadata", "description": "metadata of the chunk", "examples": [ { "file_size": 1024, "file_type": "text/plain", "language": "en", "type": "text", "word_count": 100 } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "model used for this chunk", "examples": [ "text-embedding-ada-002", "clip-vit-large-patch14" ] }, "score": { "type": "number", "title": "Score", "description": "score of the chunk", "examples": [ 0.5 ] }, "file_id": { "type": "string", "title": "File Id", "description": "file id", "examples": [ "file1" ] }, "filename": { "type": "string", "title": "Filename", "description": "filename", "examples": [ "file1" ] }, "store_id": { "type": "string", "title": "Store Id", "description": "store id", "examples": [ "store1" ] }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Id", "description": "external identifier for this file", "examples": [ "ext-123" ] }, "metadata": { "anyOf": [ {}, { "type": "null" } ], "title": "Metadata", "description": "file metadata", "examples": [ { "key": "value" } ] }, "file_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Url", "description": "Presigned URL to download the file this chunk belongs to; null when there is no stored file", "examples": [ "https://storage.mixedbread.com/org1/files/file1.pdf?X-Amz-Signature=..." ] }, "type": { "type": "string", "const": "video_url", "title": "Type", "description": "Input type identifier", "default": "video_url" }, "transcription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transcription", "description": "speech recognition (sr) text of the video", "examples": [ "The year 2025 reports for .." ] }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context", "description": "LLM-generated context that situates this video chunk within its source file", "examples": [ "This segment demonstrates the product's document search workflow." ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "summary of the video", "examples": [ "A financial report video for 2025" ] }, "video_url": { "anyOf": [ { "$ref": "#/components/schemas/VideoUrl" }, { "type": "null" } ], "description": "Video URL" } }, "type": "object", "required": [ "chunk_index", "score", "file_id", "filename", "store_id" ], "title": "ScoredVideoUrlInputChunk" }, "VideoUrl": { "properties": { "url": { "type": "string", "title": "Url", "description": "The video URL. Can be either a URL or a Data URI." } }, "type": "object", "required": [ "url" ], "title": "VideoUrl", "description": "Model for video URL validation." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") response = mxbai.stores.list_chunks( store_identifiers=["my-knowledge-base"], top_k=10, ) for chunk in response.data: print(chunk) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") response = await mxbai.stores.list_chunks( store_identifiers=["my-knowledge-base"], top_k=10, ) for chunk in response.data: print(chunk) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const response = await mxbai.stores.listChunks({ store_identifiers: ["my-knowledge-base"], top_k: 10, }); for (const chunk of response.data) { console.log(chunk); } ``` cURL: ```bash curl -X POST https://api.mixedbread.com/v1/stores/list-chunks \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -d '{ "store_identifiers": ["my-knowledge-base"], "top_k": 10 }' ``` # Question Answering URL: https://www.mixedbread.com/api-reference/endpoints/stores/search/question-answering Question answering ```json { "paths": { "/v1/stores/question-answering": { "post": { "tags": [ "stores" ], "summary": "Question Answering", "operationId": "create_question_answering", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreQAParams", "description": "The question answering query" } } }, "required": true }, "responses": { "200": { "description": "The answer to the question", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreQAResults" }, "example": { "answer": "Based on the documentation, the main features of the product include:\n\n1. **Real-time data processing** - The system can process up to 10,000 requests per second with sub-millisecond latency.\n\n2. **Advanced analytics dashboard** - Provides comprehensive insights with customizable charts and reports for tracking key metrics.\n\n3. **API integration** - RESTful API with support for webhooks and batch operations, making it easy to integrate with existing systems.\n\n4. **Security features** - Enterprise-grade security with end-to-end encryption, SSO support, and compliance with SOC 2 and GDPR standards.\n\n5. **Scalability** - Auto-scaling infrastructure that grows with your needs, supporting from small teams to enterprise deployments.", "sources": [ { "chunk_index": 3, "mime_type": "text/plain", "model": "mxbai-omni", "score": 0.9234, "file_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "filename": "product_overview.pdf", "store_id": "c3d4e5f6-a7b8-9012-cdef-345678901234", "metadata": { "page": 2, "section": "features" }, "type": "text", "text": "Our product offers real-time data processing capabilities, handling up to 10,000 requests per second..." }, { "chunk_index": 7, "mime_type": "text/plain", "model": "mxbai-omni", "score": 0.8956, "file_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012", "filename": "technical_specs.pdf", "store_id": "c3d4e5f6-a7b8-9012-cdef-345678901234", "metadata": { "page": 5, "section": "architecture" }, "type": "text", "text": "The platform includes an advanced analytics dashboard with customizable charts and reporting tools..." } ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } } }, "components": { "schemas": { "StoreQAParams": { "properties": { "store_identifiers": { "items": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ] }, "type": "array", "maxItems": 64, "minItems": 1, "title": "Store Identifiers", "description": "IDs or names of stores" }, "top_k": { "type": "integer", "maximum": 10000, "minimum": 1, "title": "Top K", "description": "Number of results to return", "default": 10 }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" }, { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Filters", "description": "Optional filter conditions" }, "file_ids": { "anyOf": [ { "prefixItems": [ { "$ref": "#/components/schemas/ConditionOperator" }, { "items": { "type": "string", "format": "uuid" }, "type": "array" } ], "type": "array", "maxItems": 2, "minItems": 2 }, { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "File Ids", "description": "Optional list of file IDs to filter chunks by (inclusion filter)", "examples": [ [ "123e4567-e89b-12d3-a456-426614174000", "123e4567-e89b-12d3-a456-426614174001" ], [ "in", [ "123e4567-e89b-12d3-a456-426614174000" ] ], [ "not_in", [ "123e4567-e89b-12d3-a456-426614174000" ] ] ] }, "query": { "type": "string", "minLength": 1, "title": "Query", "description": "Question to answer. If not provided, the question will be extracted from the passed messages." }, "search_options": { "$ref": "#/components/schemas/StoreChunkSearchOptions", "description": "Search configuration options" }, "stream": { "type": "boolean", "title": "Stream", "description": "Internal: when set, the response is a server-sent event stream of the retrieved chunks, live trace events, and finally the answer. Used by the Mixedbread playground; not part of the documented public API.", "default": false }, "instructions": { "anyOf": [ { "type": "string", "maxLength": 8000, "minLength": 1 }, { "type": "null" } ], "title": "Instructions", "description": "Additional custom instructions (followed only when not in conflict with existing rules)" }, "qa_options": { "$ref": "#/components/schemas/QuestionAnsweringOptions", "description": "Question answering configuration options" } }, "type": "object", "required": [ "store_identifiers" ], "title": "StoreQAParams", "description": "Query parameters for question answering." }, "SearchFilter-Input": { "properties": { "all": { "anyOf": [ { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "All", "description": "List of conditions or filters to be ANDed together", "examples": [ [ { "key": "price", "operator": "gt", "value": "100" }, { "key": "color", "operator": "eq", "value": "red" } ], null ] }, "any": { "anyOf": [ { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "Any", "description": "List of conditions or filters to be ORed together", "examples": [ [ { "key": "price", "operator": "gt", "value": "100" }, { "key": "color", "operator": "eq", "value": "red" } ], null ] }, "none": { "anyOf": [ { "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchFilter-Input" }, { "$ref": "#/components/schemas/SearchFilterCondition" } ] }, "type": "array" }, { "type": "null" } ], "title": "None", "description": "List of conditions or filters to be NOTed", "examples": [ [ { "key": "price", "operator": "gt", "value": "100" }, { "key": "color", "operator": "eq", "value": "red" } ], null ] } }, "type": "object", "title": "SearchFilter", "description": "Represents a filter with AND, OR, and NOT conditions." }, "SearchFilterCondition": { "properties": { "key": { "type": "string", "title": "Key", "description": "The field to apply the condition on", "examples": [ "price", "color" ] }, "value": { "title": "Value", "description": "The value to compare against", "examples": [ "100", "red" ] }, "operator": { "$ref": "#/components/schemas/ConditionOperator", "description": "The operator for the condition", "examples": [ "eq", "gt" ] } }, "type": "object", "required": [ "key", "value", "operator" ], "title": "SearchFilterCondition", "description": "Represents a condition with a field, operator, and value." }, "ConditionOperator": { "type": "string", "enum": [ "eq", "not_eq", "gt", "gte", "lt", "lte", "in", "not_in", "like", "contains", "starts_with", "not_like", "regex" ], "title": "ConditionOperator", "description": "Operator for a filter condition." }, "StoreChunkSearchOptions": { "properties": { "score_threshold": { "type": "number", "maximum": 1, "minimum": 0, "title": "Score Threshold", "description": "Minimum similarity score threshold", "default": 0 }, "rewrite_query": { "type": "boolean", "title": "Rewrite Query", "description": "Whether to rewrite the query. Ignored when agentic is enabled (the agent handles query decomposition).", "default": false }, "rerank": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/RerankConfig" }, { "type": "null" } ], "title": "Rerank", "description": "Whether to rerank results and optional reranking configuration. Ignored when agentic is enabled (the agent handles ranking)." }, "agentic": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/AgenticSearchConfig" }, { "type": "null" } ], "title": "Agentic", "description": "Whether to use agentic multi-query search with automatic query decomposition and ranking. When enabled, rewrite_query and rerank options are ignored." }, "lsf": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Lsf", "description": "Whether to apply the learned scoring function to second-stage scoring. Requires weights configured for the searched stores; silently skipped otherwise." }, "return_metadata": { "type": "boolean", "title": "Return Metadata", "description": "Whether to return file metadata", "default": true }, "apply_search_rules": { "type": "boolean", "title": "Apply Search Rules", "description": "Whether to apply search rules", "default": true } }, "type": "object", "title": "StoreChunkSearchOptions", "description": "Options for configuring store chunk searches." }, "RerankConfig": { "properties": { "model": { "type": "string", "maxLength": 500, "minLength": 1, "title": "Model", "description": "The name of the reranking model", "default": "mixedbread-ai/mxbai-rerank-v3.1-listwise", "examples": [ "rerank_model" ] }, "with_metadata": { "anyOf": [ { "type": "boolean" }, { "items": { "type": "string" }, "type": "array" } ], "title": "With Metadata", "description": "Whether to include metadata in the reranked results", "default": false, "examples": [ true, false, [ "metadata1", "metadata2" ] ] }, "top_k": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "title": "Top K", "description": "Maximum number of results to return after reranking. If None, returns all reranked results.", "examples": [ 10, 50, 100 ] } }, "type": "object", "title": "RerankConfig", "description": "Represents a reranking configuration." }, "AgenticSearchConfig": { "properties": { "max_rounds": { "type": "integer", "maximum": 10, "minimum": 1, "title": "Max Rounds", "description": "Maximum number of search rounds", "default": 3 }, "queries_per_round": { "type": "integer", "maximum": 10, "minimum": 1, "title": "Queries Per Round", "description": "Maximum queries per round", "default": 4 }, "strict_top_k": { "type": "boolean", "title": "Strict Top K", "description": "Whether the agent fills the final ranking to top_k chunks from what it retrieved, capped at top_k, instead of returning only the chunks it judged relevant", "default": false }, "media_content": { "type": "string", "enum": [ "auto", "never", "always" ], "title": "Media Content", "description": "Controls when retrieved image content is provided to the agent. `auto` sends images only when no OCR text or summary is available, `never` disables image content, and `always` sends image content when available. Currently not forwarded: the search agent runs without image content.", "default": "auto" }, "instructions": { "anyOf": [ { "type": "string", "maxLength": 5000, "minLength": 1 }, { "type": "null" } ], "title": "Instructions", "description": "Additional custom instructions (followed only when not in conflict with existing rules)" }, "verbose": { "type": "boolean", "title": "Verbose", "description": "Internal: when set, the response includes a `trace` field with the full tool-call timeline. Used by the Mixedbread playground; not part of the documented public API.", "default": false } }, "type": "object", "title": "AgenticSearchConfig", "description": "Configuration for agentic multi-query search." }, "QuestionAnsweringOptions": { "properties": { "cite": { "type": "boolean", "title": "Cite", "description": "Whether to use citations", "default": true }, "multimodal": { "type": "boolean", "title": "Multimodal", "description": "Whether to use multimodal context", "default": true } }, "type": "object", "title": "QuestionAnsweringOptions", "description": "Options for question answering." }, "StoreQAResults": { "properties": { "answer": { "type": "string", "title": "Answer", "description": "The answer generated by the LLM" }, "sources": { "items": { "oneOf": [ { "$ref": "#/components/schemas/mxbai_omni__core__store__models__chunk_types__ScoredTextInputChunk" }, { "$ref": "#/components/schemas/mxbai_omni__core__store__models__chunk_types__ScoredImageUrlInputChunk" }, { "$ref": "#/components/schemas/mxbai_omni__core__store__models__chunk_types__ScoredAudioUrlInputChunk" }, { "$ref": "#/components/schemas/mxbai_omni__core__store__models__chunk_types__ScoredVideoUrlInputChunk" } ], "discriminator": { "propertyName": "type", "mapping": { "audio_url": "#/components/schemas/mxbai_omni__core__store__models__chunk_types__ScoredAudioUrlInputChunk", "image_url": "#/components/schemas/mxbai_omni__core__store__models__chunk_types__ScoredImageUrlInputChunk", "text": "#/components/schemas/mxbai_omni__core__store__models__chunk_types__ScoredTextInputChunk", "video_url": "#/components/schemas/mxbai_omni__core__store__models__chunk_types__ScoredVideoUrlInputChunk" } } }, "type": "array", "title": "Sources", "description": "Source documents used to generate the answer" } }, "additionalProperties": true, "type": "object", "required": [ "answer" ], "title": "StoreQAResults", "description": "Results from a question answering operation." }, "mxbai_omni__core__store__models__chunk_types__ScoredTextInputChunk": { "properties": { "chunk_index": { "type": "integer", "title": "Chunk Index", "description": "position of the chunk in a file", "examples": [ 0, 1, 2, 3, 4 ] }, "mime_type": { "type": "string", "title": "Mime Type", "description": "mime type of the chunk", "default": "text/plain", "examples": [ "text/plain" ] }, "generated_metadata": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/MarkdownChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/TextChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/EmailChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CsvChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/PDFChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CodeChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/AudioChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/VideoChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/ImageChunkGeneratedMetadata" } ], "discriminator": { "propertyName": "type", "mapping": { "audio": "#/components/schemas/AudioChunkGeneratedMetadata", "code": "#/components/schemas/CodeChunkGeneratedMetadata", "csv": "#/components/schemas/CsvChunkGeneratedMetadata", "email": "#/components/schemas/EmailChunkGeneratedMetadata", "image": "#/components/schemas/ImageChunkGeneratedMetadata", "markdown": "#/components/schemas/MarkdownChunkGeneratedMetadata", "pdf": "#/components/schemas/PDFChunkGeneratedMetadata", "text": "#/components/schemas/TextChunkGeneratedMetadata", "video": "#/components/schemas/VideoChunkGeneratedMetadata" } } }, { "type": "null" } ], "title": "Generated Metadata", "description": "metadata of the chunk", "examples": [ { "file_size": 1024, "file_type": "text/plain", "language": "en", "type": "text", "word_count": 100 } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "model used for this chunk", "examples": [ "text-embedding-ada-002", "clip-vit-large-patch14" ] }, "score": { "type": "number", "title": "Score", "description": "score of the chunk", "examples": [ 0.5 ] }, "file_id": { "type": "string", "title": "File Id", "description": "file id", "examples": [ "file1" ] }, "filename": { "type": "string", "title": "Filename", "description": "filename", "examples": [ "file1" ] }, "store_id": { "type": "string", "title": "Store Id", "description": "store id", "examples": [ "store1" ] }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Id", "description": "external identifier for this file", "examples": [ "ext-123" ] }, "metadata": { "anyOf": [ {}, { "type": "null" } ], "title": "Metadata", "description": "file metadata", "examples": [ { "key": "value" } ] }, "file_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Url", "description": "Presigned URL to download the file this chunk belongs to; null when there is no stored file", "examples": [ "https://storage.mixedbread.com/org1/files/file1.pdf?X-Amz-Signature=..." ] }, "type": { "type": "string", "const": "text", "title": "Type", "description": "Input type identifier", "default": "text" }, "offset": { "type": "integer", "title": "Offset", "description": "The offset of the text in the file relative to the start of the file.", "default": 0, "examples": [ 0, 13, 42 ] }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text", "description": "Text content" }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context", "description": "LLM-generated context that situates this chunk within its source document", "examples": [ "This chunk is from an SEC filing on ACME corp's Q2 2023 performance." ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "summary of the text chunk", "examples": [ "A short overview of ACME's Q2 2023 performance." ] } }, "type": "object", "required": [ "chunk_index", "score", "file_id", "filename", "store_id" ], "title": "ScoredTextInputChunk" }, "MarkdownChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "markdown", "title": "Type", "default": "markdown" }, "file_type": { "type": "string", "const": "text/markdown", "title": "File Type", "default": "text/markdown" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "chunk_headings": { "items": { "$ref": "#/components/schemas/MarkdownHeading" }, "type": "array", "title": "Chunk Headings" }, "heading_context": { "items": { "$ref": "#/components/schemas/MarkdownHeading" }, "type": "array", "title": "Heading Context" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" }, "frontmatter": { "additionalProperties": true, "type": "object", "title": "Frontmatter" } }, "additionalProperties": true, "type": "object", "title": "MarkdownChunkGeneratedMetadata" }, "MarkdownHeading": { "properties": { "level": { "type": "integer", "title": "Level" }, "text": { "type": "string", "title": "Text" } }, "type": "object", "required": [ "level", "text" ], "title": "MarkdownHeading" }, "TextChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "text", "title": "Type", "default": "text" }, "file_type": { "type": "string", "enum": [ "text/plain", "message/rfc822" ], "title": "File Type", "default": "text/plain" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "title": "TextChunkGeneratedMetadata" }, "EmailChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "email", "title": "Type", "default": "email" }, "file_type": { "type": "string", "title": "File Type", "default": "message/rfc822" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subject" }, "from_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From Email" }, "to_emails": { "items": { "type": "string" }, "type": "array", "title": "To Emails" }, "cc_emails": { "items": { "type": "string" }, "type": "array", "title": "Cc Emails" }, "bcc_emails": { "items": { "type": "string" }, "type": "array", "title": "Bcc Emails" }, "date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Date" }, "attachment_names": { "items": { "type": "string" }, "type": "array", "title": "Attachment Names" } }, "additionalProperties": true, "type": "object", "title": "EmailChunkGeneratedMetadata" }, "CsvChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "csv", "title": "Type", "default": "csv" }, "file_type": { "type": "string", "const": "text/csv", "title": "File Type", "default": "text/csv" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "start_row": { "type": "integer", "title": "Start Row", "default": 0 }, "num_rows": { "type": "integer", "title": "Num Rows", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "title": "CsvChunkGeneratedMetadata" }, "PDFChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "pdf", "title": "Type", "default": "pdf" }, "file_type": { "type": "string", "const": "application/pdf", "title": "File Type", "default": "application/pdf" }, "total_pages": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Pages" }, "total_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Size" }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" }, "layout": { "anyOf": [ { "$ref": "#/components/schemas/LayoutMetadata" }, { "type": "null" } ] } }, "additionalProperties": true, "type": "object", "title": "PDFChunkGeneratedMetadata" }, "LayoutMetadata": { "properties": { "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Width" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Height" }, "elements": { "items": { "$ref": "#/components/schemas/LayoutElement" }, "type": "array", "title": "Elements" } }, "type": "object", "title": "LayoutMetadata", "description": "Per-page layout for chunks parsed in high-quality (visual) mode.\n\n``elements`` are ordered by reading order (list position == reading order).\n``width``/``height`` are the page-image dimensions the ``bbox`` coords are\nrelative to, so consumers can normalize/render without a second fetch.\n\nLayout is part of the generated metadata payload and is returned with the\nchunk whenever present." }, "LayoutElement": { "properties": { "bbox": { "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" }, { "type": "number" } ], "type": "array", "maxItems": 4, "minItems": 4, "title": "Bbox" }, "type": { "type": "string", "title": "Type" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text" } }, "type": "object", "required": [ "bbox", "type" ], "title": "LayoutElement", "description": "A single detected layout element and its location on the page image." }, "CodeChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "code", "title": "Type", "default": "code" }, "file_type": { "type": "string", "title": "File Type" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "start_line": { "type": "integer", "title": "Start Line", "default": 0 }, "num_lines": { "type": "integer", "title": "Num Lines", "default": 0 }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "required": [ "file_type" ], "title": "CodeChunkGeneratedMetadata" }, "AudioChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "audio", "title": "Type", "default": "audio" }, "file_type": { "type": "string", "title": "File Type", "default": "audio/mpeg" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "total_duration_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Duration Seconds" }, "sample_rate": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Sample Rate" }, "channels": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Channels" }, "audio_format": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Audio Format" }, "bpm": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bpm" }, "speakers": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Speakers" }, "speaker_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Speaker Count" }, "speaker_turns": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SpeakerTurn" }, "type": "array" }, { "type": "null" } ], "title": "Speaker Turns" }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "title": "AudioChunkGeneratedMetadata" }, "SpeakerTurn": { "properties": { "speaker": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Speaker" }, "text": { "type": "string", "title": "Text" }, "start_time_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Start Time Seconds" }, "end_time_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "End Time Seconds" } }, "type": "object", "required": [ "text" ], "title": "SpeakerTurn" }, "VideoChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "video", "title": "Type", "default": "video" }, "file_type": { "type": "string", "title": "File Type", "default": "video/mp4" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "total_duration_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Duration Seconds" }, "fps": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Fps" }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Width" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Height" }, "frame_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Frame Count" }, "has_audio_stream": { "type": "boolean", "title": "Has Audio Stream", "default": false }, "bpm": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bpm" }, "speakers": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Speakers" }, "speaker_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Speaker Count" }, "speaker_turns": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SpeakerTurn" }, "type": "array" }, { "type": "null" } ], "title": "Speaker Turns" }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" } }, "additionalProperties": true, "type": "object", "title": "VideoChunkGeneratedMetadata" }, "ImageChunkGeneratedMetadata": { "properties": { "type": { "type": "string", "const": "image", "title": "Type", "default": "image" }, "file_type": { "type": "string", "title": "File Type", "default": "image/jpeg" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Width" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Height" }, "file_extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Extension" }, "layout": { "anyOf": [ { "$ref": "#/components/schemas/LayoutMetadata" }, { "type": "null" } ] } }, "additionalProperties": true, "type": "object", "title": "ImageChunkGeneratedMetadata" }, "mxbai_omni__core__store__models__chunk_types__ScoredImageUrlInputChunk": { "properties": { "chunk_index": { "type": "integer", "title": "Chunk Index", "description": "position of the chunk in a file", "examples": [ 0, 1, 2, 3, 4 ] }, "mime_type": { "type": "string", "title": "Mime Type", "description": "mime type of the chunk", "default": "image/jpeg", "examples": [ "image/jpeg" ] }, "generated_metadata": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/MarkdownChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/TextChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/EmailChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CsvChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/PDFChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CodeChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/AudioChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/VideoChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/ImageChunkGeneratedMetadata" } ], "discriminator": { "propertyName": "type", "mapping": { "audio": "#/components/schemas/AudioChunkGeneratedMetadata", "code": "#/components/schemas/CodeChunkGeneratedMetadata", "csv": "#/components/schemas/CsvChunkGeneratedMetadata", "email": "#/components/schemas/EmailChunkGeneratedMetadata", "image": "#/components/schemas/ImageChunkGeneratedMetadata", "markdown": "#/components/schemas/MarkdownChunkGeneratedMetadata", "pdf": "#/components/schemas/PDFChunkGeneratedMetadata", "text": "#/components/schemas/TextChunkGeneratedMetadata", "video": "#/components/schemas/VideoChunkGeneratedMetadata" } } }, { "type": "null" } ], "title": "Generated Metadata", "description": "metadata of the chunk", "examples": [ { "file_size": 1024, "file_type": "text/plain", "language": "en", "type": "text", "word_count": 100 } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "model used for this chunk", "examples": [ "text-embedding-ada-002", "clip-vit-large-patch14" ] }, "score": { "type": "number", "title": "Score", "description": "score of the chunk", "examples": [ 0.5 ] }, "file_id": { "type": "string", "title": "File Id", "description": "file id", "examples": [ "file1" ] }, "filename": { "type": "string", "title": "Filename", "description": "filename", "examples": [ "file1" ] }, "store_id": { "type": "string", "title": "Store Id", "description": "store id", "examples": [ "store1" ] }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Id", "description": "external identifier for this file", "examples": [ "ext-123" ] }, "metadata": { "anyOf": [ {}, { "type": "null" } ], "title": "Metadata", "description": "file metadata", "examples": [ { "key": "value" } ] }, "file_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Url", "description": "Presigned URL to download the file this chunk belongs to; null when there is no stored file", "examples": [ "https://storage.mixedbread.com/org1/files/file1.pdf?X-Amz-Signature=..." ] }, "type": { "type": "string", "const": "image_url", "title": "Type", "description": "Input type identifier", "default": "image_url" }, "ocr_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ocr Text", "description": "ocr text of the image", "examples": [ "2025 Financial Report" ] }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context", "description": "LLM-generated context that situates this image within its source document", "examples": [ "This page contains ACME's Q2 2023 financial results." ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "summary of the image", "examples": [ "A financial report for 2025" ] }, "image_url": { "anyOf": [ { "$ref": "#/components/schemas/ImageUrl-Output" }, { "type": "null" } ], "description": "Image URL" } }, "type": "object", "required": [ "chunk_index", "score", "file_id", "filename", "store_id" ], "title": "ScoredImageUrlInputChunk" }, "ImageUrl-Output": { "properties": { "url": { "type": "string", "title": "Url", "description": "The image URL. Can be either a URL or a Data URI." }, "format": { "type": "string", "title": "Format", "description": "The image format/mimetype", "default": "" } }, "type": "object", "required": [ "url" ], "title": "ImageUrl", "description": "Model for image URL validation." }, "mxbai_omni__core__store__models__chunk_types__ScoredAudioUrlInputChunk": { "properties": { "chunk_index": { "type": "integer", "title": "Chunk Index", "description": "position of the chunk in a file", "examples": [ 0, 1, 2, 3, 4 ] }, "mime_type": { "type": "string", "title": "Mime Type", "description": "mime type of the chunk", "default": "audio/mpeg", "examples": [ "audio/mpeg" ] }, "generated_metadata": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/MarkdownChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/TextChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/EmailChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CsvChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/PDFChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CodeChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/AudioChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/VideoChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/ImageChunkGeneratedMetadata" } ], "discriminator": { "propertyName": "type", "mapping": { "audio": "#/components/schemas/AudioChunkGeneratedMetadata", "code": "#/components/schemas/CodeChunkGeneratedMetadata", "csv": "#/components/schemas/CsvChunkGeneratedMetadata", "email": "#/components/schemas/EmailChunkGeneratedMetadata", "image": "#/components/schemas/ImageChunkGeneratedMetadata", "markdown": "#/components/schemas/MarkdownChunkGeneratedMetadata", "pdf": "#/components/schemas/PDFChunkGeneratedMetadata", "text": "#/components/schemas/TextChunkGeneratedMetadata", "video": "#/components/schemas/VideoChunkGeneratedMetadata" } } }, { "type": "null" } ], "title": "Generated Metadata", "description": "metadata of the chunk", "examples": [ { "file_size": 1024, "file_type": "text/plain", "language": "en", "type": "text", "word_count": 100 } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "model used for this chunk", "examples": [ "text-embedding-ada-002", "clip-vit-large-patch14" ] }, "score": { "type": "number", "title": "Score", "description": "score of the chunk", "examples": [ 0.5 ] }, "file_id": { "type": "string", "title": "File Id", "description": "file id", "examples": [ "file1" ] }, "filename": { "type": "string", "title": "Filename", "description": "filename", "examples": [ "file1" ] }, "store_id": { "type": "string", "title": "Store Id", "description": "store id", "examples": [ "store1" ] }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Id", "description": "external identifier for this file", "examples": [ "ext-123" ] }, "metadata": { "anyOf": [ {}, { "type": "null" } ], "title": "Metadata", "description": "file metadata", "examples": [ { "key": "value" } ] }, "file_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Url", "description": "Presigned URL to download the file this chunk belongs to; null when there is no stored file", "examples": [ "https://storage.mixedbread.com/org1/files/file1.pdf?X-Amz-Signature=..." ] }, "type": { "type": "string", "const": "audio_url", "title": "Type", "description": "Input type identifier", "default": "audio_url" }, "transcription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transcription", "description": "speech recognition (sr) text of the audio", "examples": [ "The year 2025 reports for .." ] }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context", "description": "LLM-generated context that situates this audio chunk within its source file", "examples": [ "This segment introduces ACME's quarterly earnings call." ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "summary of the audio", "examples": [ "A financial report audio for 2025" ] }, "audio_url": { "anyOf": [ { "$ref": "#/components/schemas/AudioUrl" }, { "type": "null" } ], "description": "Audio URL" }, "sampling_rate": { "type": "integer", "title": "Sampling Rate", "description": "The sampling rate of the audio." } }, "type": "object", "required": [ "chunk_index", "score", "file_id", "filename", "store_id", "sampling_rate" ], "title": "ScoredAudioUrlInputChunk" }, "AudioUrl": { "properties": { "url": { "type": "string", "title": "Url", "description": "The audio URL. Can be either a URL or a Data URI." } }, "type": "object", "required": [ "url" ], "title": "AudioUrl", "description": "Model for audio URL validation." }, "mxbai_omni__core__store__models__chunk_types__ScoredVideoUrlInputChunk": { "properties": { "chunk_index": { "type": "integer", "title": "Chunk Index", "description": "position of the chunk in a file", "examples": [ 0, 1, 2, 3, 4 ] }, "mime_type": { "type": "string", "title": "Mime Type", "description": "mime type of the chunk", "default": "video/mp4", "examples": [ "video/mp4" ] }, "generated_metadata": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/MarkdownChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/TextChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/EmailChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CsvChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/PDFChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/CodeChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/AudioChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/VideoChunkGeneratedMetadata" }, { "$ref": "#/components/schemas/ImageChunkGeneratedMetadata" } ], "discriminator": { "propertyName": "type", "mapping": { "audio": "#/components/schemas/AudioChunkGeneratedMetadata", "code": "#/components/schemas/CodeChunkGeneratedMetadata", "csv": "#/components/schemas/CsvChunkGeneratedMetadata", "email": "#/components/schemas/EmailChunkGeneratedMetadata", "image": "#/components/schemas/ImageChunkGeneratedMetadata", "markdown": "#/components/schemas/MarkdownChunkGeneratedMetadata", "pdf": "#/components/schemas/PDFChunkGeneratedMetadata", "text": "#/components/schemas/TextChunkGeneratedMetadata", "video": "#/components/schemas/VideoChunkGeneratedMetadata" } } }, { "type": "null" } ], "title": "Generated Metadata", "description": "metadata of the chunk", "examples": [ { "file_size": 1024, "file_type": "text/plain", "language": "en", "type": "text", "word_count": 100 } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "model used for this chunk", "examples": [ "text-embedding-ada-002", "clip-vit-large-patch14" ] }, "score": { "type": "number", "title": "Score", "description": "score of the chunk", "examples": [ 0.5 ] }, "file_id": { "type": "string", "title": "File Id", "description": "file id", "examples": [ "file1" ] }, "filename": { "type": "string", "title": "Filename", "description": "filename", "examples": [ "file1" ] }, "store_id": { "type": "string", "title": "Store Id", "description": "store id", "examples": [ "store1" ] }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Id", "description": "external identifier for this file", "examples": [ "ext-123" ] }, "metadata": { "anyOf": [ {}, { "type": "null" } ], "title": "Metadata", "description": "file metadata", "examples": [ { "key": "value" } ] }, "file_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Url", "description": "Presigned URL to download the file this chunk belongs to; null when there is no stored file", "examples": [ "https://storage.mixedbread.com/org1/files/file1.pdf?X-Amz-Signature=..." ] }, "type": { "type": "string", "const": "video_url", "title": "Type", "description": "Input type identifier", "default": "video_url" }, "transcription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transcription", "description": "speech recognition (sr) text of the video", "examples": [ "The year 2025 reports for .." ] }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context", "description": "LLM-generated context that situates this video chunk within its source file", "examples": [ "This segment demonstrates the product's document search workflow." ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "summary of the video", "examples": [ "A financial report video for 2025" ] }, "video_url": { "anyOf": [ { "$ref": "#/components/schemas/VideoUrl" }, { "type": "null" } ], "description": "Video URL" } }, "type": "object", "required": [ "chunk_index", "score", "file_id", "filename", "store_id" ], "title": "ScoredVideoUrlInputChunk" }, "VideoUrl": { "properties": { "url": { "type": "string", "title": "Url", "description": "The video URL. Can be either a URL or a Data URI." } }, "type": "object", "required": [ "url" ], "title": "VideoUrl", "description": "Model for video URL validation." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") response = mxbai.stores.question_answering( store_identifiers=["my-knowledge-base"], query="What are the main features of the product?", top_k=5, instructions=( "Answer for an API evaluator. Use concise bullets and cite the most relevant sources." ), qa_options={"cite": True, "multimodal": True}, ) print(response) ``` Python (async): ```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 are the main features of the product?", top_k=5, instructions=( "Answer for an API evaluator. Use concise bullets and cite the most relevant sources." ), qa_options={"cite": True, "multimodal": True}, ) print(response) ``` TypeScript: ```ts 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 are the main features of the product?", top_k: 5, instructions: "Answer for an API evaluator. Use concise bullets and cite the most relevant sources.", qa_options: { cite: true, multimodal: true }, }); console.log(response); ``` cURL: ```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 are the main features of the product?", "top_k": 5, "instructions": "Answer for an API evaluator. Use concise bullets and cite the most relevant sources.", "qa_options": { "cite": true, "multimodal": true } }' ```