Asynchronous document parsing as jobs. POST /v1/parsing/jobs starts a parse over an uploaded file with configurable chunking strategy, return format (markdown/HTML/text), and element extraction. GET/PATCH/DELETE on /v1/parsing/jobs/{job_id} for retrieval, cancellation, and deletion. Produces structured chunks with type metadata for text, code, tables, images, audio, video.
openapi: 3.1.0
info:
title: Mixedbread Parsing API
version: 0.1.0
description: Mixedbread parsing endpoints extracted from the canonical OpenAPI spec at https://api.mixedbread.com/openapi.json
servers:
- url: https://api.mixedbread.com
description: mixedbread ai production server
- url: https://api.dev.mixedbread.com
description: mixedbread ai development server
- url: http://127.0.0.1:8000
description: mixedbread local server
- url: http://localhost:8000
description: mixedbread local server
paths:
/v1/parsing/jobs:
post:
tags:
- parsing
summary: Start a parse job
description: "Start a parse job for the provided file.\n\nArgs:\n params: The parameters for creating a parse job.\n\
\nReturns:\n The created parsing job."
operationId: create_parsing_job
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ParsingJobCreateParams'
description: The parameters for creating a parse job
responses:
'201':
description: The created parse job
content:
application/json:
schema:
$ref: '#/components/schemas/ParsingJob'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
get:
tags:
- parsing
summary: List parsing jobs
description: "List parsing jobs with pagination.\n\nArgs:\n limit: The number of items to return.\n offset: The\
\ number of items to skip.\n\nReturns:\n List of parsing jobs with pagination."
operationId: list_parsing_jobs
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: statuses
in: query
required: false
schema:
anyOf:
- type: array
items:
$ref: '#/components/schemas/ParsingJobStatus'
- type: 'null'
description: Status to filter by
title: Statuses
description: Status to filter by
- name: q
in: query
required: false
schema:
anyOf:
- type: string
minLength: 1
maxLength: 255
- type: 'null'
description: Search query to filter by
title: Q
description: Search query to filter by
responses:
'200':
description: List of parsing jobs with pagination
content:
application/json:
schema:
$ref: '#/components/schemas/ParsingJobListResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/parsing/jobs/{job_id}:
get:
tags:
- parsing
summary: Get parsing job result
description: "Get detailed information about a specific parse job.\n\nArgs:\n job_id: The ID of the parse job.\n\n\
Returns:\n Detailed information about the parse job."
operationId: retrieve_parsing_job
security:
- ApiKeyAuth: []
parameters:
- name: job_id
in: path
required: true
schema:
type: string
format: uuid
description: The ID of the parse job to retrieve
title: Job Id
description: The ID of the parse job to retrieve
responses:
'200':
description: Detailed information about a parsing job
content:
application/json:
schema:
$ref: '#/components/schemas/ParsingJob'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
patch:
tags:
- parsing
summary: Cancel a parsing job
description: "Cancel a specific parse job.\n\nArgs:\n job_id: The ID of the parse job to cancel.\n\nReturns:\n \
\ The cancelled parsing job."
operationId: cancel_parsing_job
security:
- ApiKeyAuth: []
parameters:
- name: job_id
in: path
required: true
schema:
type: string
format: uuid
description: The ID of the parse job to cancel
title: Job Id
description: The ID of the parse job to cancel
responses:
'200':
description: The cancelled parse job
content:
application/json:
schema:
$ref: '#/components/schemas/ParsingJob'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- parsing
summary: Delete a parsing job
description: "Delete a specific parse job.\n\nArgs:\n job_id: The ID of the parse job to delete.\n\nReturns:\n \
\ The deleted parsing job."
operationId: delete_parsing_job
security:
- ApiKeyAuth: []
parameters:
- name: job_id
in: path
required: true
schema:
type: string
format: uuid
description: The ID of the parse job to delete
title: Job Id
description: The ID of the parse job to delete
responses:
'200':
description: The deleted parse job
content:
application/json:
schema:
$ref: '#/components/schemas/ParsingJobDeleted'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
AgenticSearchConfig:
properties:
max_rounds:
type: integer
maximum: 10.0
minimum: 1.0
title: Max Rounds
description: Maximum number of search rounds
default: 3
queries_per_round:
type: integer
maximum: 10.0
minimum: 1.0
title: Queries Per Round
description: Maximum queries per round
default: 4
strict_top_k:
type: boolean
title: Strict Top K
description: Whether the final retrieved chunk list must provide exactly top_k ranked chunks
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.
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.
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
cost_usd:
type: number
title: Cost Usd
description: Estimated cost in USD
default: 0.0
type: object
title: AgenticSearchTokenUsage
description: Token usage and cost 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:
additionalProperties: true
type: object
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
type: object
required:
- tool_call_id
- tool_name
- started_at
- duration
- arguments
title: AgenticToolCall
description: 'Represents a single tool call made by the agent during an agentic search.
Fields follow the OpenTelemetry GenAI semantic conventions for tool calls:
https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/'
ApiKey:
properties:
id:
type: string
title: Id
description: The ID of the API key
name:
type: string
title: Name
description: The name of the API key
redacted_value:
type: string
title: Redacted Value
description: The redacted value of the API key
expires_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Expires At
description: The expiration datetime of the API key
created_at:
type: string
format: date-time
title: Created At
description: The creation datetime of the API key
updated_at:
type: string
format: date-time
title: Updated At
description: The last update datetime of the API key
last_active_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Last Active At
description: The last active datetime of the API key
object:
type: string
const: api_key
title: Object
description: The type of the object
default: api_key
scope:
anyOf:
- items:
$ref: '#/components/schemas/Scope'
type: array
- type: 'null'
title: Scope
description: The scope of the API key
type: object
required:
- id
- name
- redacted_value
- created_at
- updated_at
title: ApiKey
description: Response model for an API key.
ApiKeyCreateOrUpdateParams:
properties:
type:
type: string
const: api_key
title: Type
default: api_key
api_key:
type: string
title: Api Key
description: The API key
type: object
required:
- api_key
title: ApiKeyCreateOrUpdateParams
description: Base class for API key create or update parameters.
ApiKeyCreateParams:
properties:
name:
type: string
title: Name
description: A name/description for the API key
default: API Key
scope:
anyOf:
- items:
$ref: '#/components/schemas/Scope'
type: array
- type: 'null'
title: Scope
description: The scope of the API key
expires_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Expires At
description: Optional expiration datetime
type: object
title: ApiKeyCreateParams
description: Parameters for creating an API key.
ApiKeyCreated:
properties:
id:
type: string
title: Id
description: The ID of the API key
name:
type: string
title: Name
description: The name of the API key
redacted_value:
type: string
title: Redacted Value
description: The redacted value of the API key
expires_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Expires At
description: The expiration datetime of the API key
created_at:
type: string
format: date-time
title: Created At
description: The creation datetime of the API key
updated_at:
type: string
format: date-time
title: Updated At
description: The last update datetime of the API key
last_active_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Last Active At
description: The last active datetime of the API key
object:
type: string
const: api_key
title: Object
description: The type of the object
default: api_key
scope:
anyOf:
- items:
$ref: '#/components/schemas/Scope'
type: array
- type: 'null'
title: Scope
description: The scope of the API key
value:
type: string
title: Value
description: The value of the API key
type: object
required:
- id
- name
- redacted_value
- created_at
- updated_at
- value
title: ApiKeyCreated
description: Response model for creating an API key.
ApiKeyDeleted:
properties:
id:
type: string
title: Id
description: The ID of the deleted API key
deleted:
type: boolean
title: Deleted
description: Whether the API key was deleted
object:
type: string
const: api_key
title: Object
description: The type of the object deleted
default: api_key
type: object
required:
- id
- deleted
title: ApiKeyDeleted
description: Response model for deleting an API key.
ApiKeyListResponse:
properties:
pagination:
$ref: '#/components/schemas/PaginationWithTotal'
object:
type: string
const: list
title: Object
description: The object type of the response
default: list
data:
items:
$ref: '#/components/schemas/ApiKey'
type: array
title: Data
description: The list of API keys
type: object
required:
- pagination
- data
title: ApiKeyListResponse
ApiKeyUpdateParams:
properties:
name:
anyOf:
- type: string
- type: 'null'
title: Name
description: A name/description for the API key
expires_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Expires At
description: Optional expiration datetime
type: object
title: ApiKeyUpdateParams
description: Parameters for updating an API key.
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
file_extension:
anyOf:
- type: string
- type: 'null'
title: File Extension
additionalProperties: true
type: object
title: AudioChunkGeneratedMetadata
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.
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/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'
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 ..
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
BalanceInfo:
properties:
current_balance:
type: number
title: Current Balance
description: The current balance
next_effective_balance:
type: number
title: Next Effective Balance
description: The next effective balance
next_effective_date:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Next Effective Date
description: The next effective date
type: object
title: BalanceInfo
description: Information about an organization's credit balance.
BillingPeriodSummary:
properties:
period:
$ref: '#/components/schemas/Period'
description: The billing period
cost:
$ref: '#/components/schemas/CostInfo'
description: The cost information
balance:
$ref: '#/components/schemas/BalanceInfo'
description: The balance information
usages:
additionalProperties:
$ref: '#/components/schemas/UsageInfo'
type: object
title: Usages
description: The monthly usages information per metric
generated_at:
type: string
format: date-time
title: Generated At
description: The date and time the summary was generated
type: object
required:
- period
- cost
- balance
- usages
- generated_at
title: BillingPeriodSummary
description: High level billing summary for the currently active period.
Body_create_file:
properties:
file:
type: string
format: binary
title: File
description: The file to upload
type: object
required:
- file
title: Body_create_file
Body_update_file:
properties:
file:
type: string
format: binary
title: File
description: The file to update
type: object
required:
- file
title: Body_update_file
Body_upload_store_file:
properties:
file:
type: string
format: binary
title: File
description: The file to upload and index
params:
anyOf:
- type: string
- type: 'null'
title: Params
type: object
required:
- file
title: Body_upload_store_file
Chunk:
properties:
content:
anyOf:
- type: string
- type: 'null'
title: Content
description: The full content of the chunk
content_to_embed:
type: string
title: Content To Embed
description: The content of the chunk to embed
elements:
items:
$ref: '#/components/schemas/ChunkElement'
type: array
title: Elements
description: List of elements contained in this chunk
type: object
required:
- content_to_embed
- elements
title: Chunk
description: A chunk of text extracted from a document page.
ChunkElement:
properties:
type:
$ref: '#/components/schemas/ElementType'
description: The type of the extracted element
confidence:
type: number
maximum: 1.0
minimum: 0.0
title: Confidence
description: The confidence score of the extraction
bbox:
prefixItems:
- type: number
- type: number
- type: number
- type: number
type: array
maxItems: 4
minItems: 4
title: Bbox
description: The bounding box coordinates [x1, y1, x2, y2]
page:
type: integer
minimum: 0.0
title: Page
description: The page number where the element was found
content:
type: string
title: Content
description: The extracted text content of the element
summary:
anyOf:
- type: string
- type: 'null'
title: Summary
description: A brief summary of the element's content
image:
anyOf:
- type: string
- type: 'null'
title: Image
description: The base64-encoded image data for figure elements
type: object
required:
- type
- confidence
- bbox
- page
- content
title: ChunkElement
description: Represents an extracted element from a document with its content and metadata.
ChunkSearchResultRule:
properties:
query:
type: string
title: Query
description: The query to trigger the rule
store_id:
type: string
title: Store Id
description: The store identifier to apply the rule to
type:
type: string
const: chunk_search_result
title: Type
description: The type of substitution
file_id:
type: string
title: File Id
description: The file ID of the chunk to substitute
chunk_index:
type: integer
minimum: 0.0
title: Chunk Index
description: The index of the chunk to substitute
result_index:
type: integer
minimum: 0.0
title: Result Index
description: The index where the result will be inserted
type: object
required:
- query
- store_id
- type
- file_id
- chunk_index
- result_index
title: ChunkSearchResultRule
description: Represents a chunk search result rule for a vector store search.
ChunkingStrategy:
type: string
enum:
- page
title: ChunkingStrategy
description: Strategy used for chunking document content.
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
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
ConditionOperator:
type: string
enum:
- eq
- not_eq
- gt
- gte
- lt
- lte
- in
- not_in
- like
- starts_with
- not_like
- regex
title: ConditionOperator
description: Operator for a filter condition.
ConnectorListResponse:
properties:
pagination:
$ref: '#/components/schemas/CursorPaginationResponse'
data:
items:
$ref: '#/components/schemas/DataSourceConnector'
type: array
title: Data
description: The list of connectors
object:
type: string
const: list
title: Object
description: The object type of the response
default: list
type: object
required:
- pagination
- data
title: ConnectorListResponse
description: A list of connectors with pagination.
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 text chunk that situates it within the full document,
improving retrieval accuracy. Only applies to text content during non-sliced ingestion.
default: false
type: object
title: ContextualizationConfig
CostHistogramResponse:
properties:
data:
items:
$ref: '#/components/schemas/DailyCostBucket'
type: array
title: Data
description
# --- truncated at 32 KB (248 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mixedbread-ai/refs/heads/main/openapi/mixedbread-parsing-api-openapi.yml