POST /v1/reranking reorders a candidate document list against a query using the mxbai-rerank family (xsmall-v1, base-v1, large-v1, base-v2, large-v2, plus the v3-listwise instruction-following reranker). Documents can be raw strings or structured objects with a return_input flag. Top-K results returned with relevance scores.
openapi: 3.1.0
info:
title: Mixedbread Reranking API
version: 0.1.0
description: Mixedbread reranking 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/reranking:
post:
summary: Rerank different kind of documents for a given query
description: "Rerank different kind of documents for a given query.\n\nArgs:\n params: RerankParams: The parameters\
\ for reranking.\n\nReturns:\n RerankResponse: The reranked documents for the input query."
operationId: rerank
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RerankParams'
description: The parameters for reranking
required: true
responses:
'200':
description: The reranked documents for the input query
content:
application/json:
schema:
$ref: '#/components/schemas/RerankResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- ApiKeyAuth: []
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: The histogram of cost information
object:
type: string
const: cost.histogram
title: Object
description: The object type of the response
default: cost.histogram
type: object
required:
- data
title: CostHistogramResponse
CostInfo:
properties:
net_usage_cost:
type: string
pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
title: Net Usage Cost
description: The net usage cost
default: '0'
gross_usage_cost:
type: string
pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
title: Gross Usage Cost
description: The gross usage cost
default: '0'
balance_applied:
type: string
pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
title: Balance Applied
description: The balance applied
default: '0'
phases:
items:
$ref: '#/components/schemas/PhaseCostInfo'
type: array
title: Phases
description: The cost for each phase in descending order of end date
default: []
products:
items:
$ref: '#/components/schemas/ProductCostInfo'
type: array
title: Products
description: The cost for each product. Store, Parsing, Reranking, Embeddings
default: []
type: object
title: CostInfo
description: "Cost information for a billing period.\n\n- net_usage_cost: portion of usage that actually ends up on\
\ the invoice after credits,\n computed as gross_usage_cost - balance_applied.\n- gross_usage_cost: metered usage\
\ value before balance applied."
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.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.0
minimum: 1.0
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
CreatedJsonSchema:
properties:
json_schema:
additionalProperties: true
type: object
title: Json Schema
description: The created JSON schema
type: object
required:
- json_schema
title: CreatedJsonSchema
description: Result of creating a JSON schema.
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.
DailyCostBucket:
properties:
day:
type: string
format: date-time
title: Day
description: The date of the cost bucket
cost:
type: string
pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
title: Cost
description: The cost of the cost bucket
cost_per_metric:
additionalProperties:
type: string
pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
type: object
title: Cost Per Metric
description: The cost per metric
type: object
required:
- day
- cost
- cost_per_metric
title: DailyCostBucket
description: Daily cost bucket.
DataSource:
properties:
id:
type: string
title: Id
description: The ID of the data source
created_at:
type: string
format: date-time
title: Created At
description: The creation time of the data source
updated_at:
# --- truncated at 32 KB (242 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mixedbread-ai/refs/heads/main/openapi/mixedbread-reranking-api-openapi.yml