Mixedbread Data Sources API
Manage external data sources and their connectors, including OAuth2 authorization/callback flows. Lets stores ingest content from third-party SaaS systems through reusable connector definitions.
OpenAPI Specification
openapi: 3.1.0
info:
title: Mixedbread Data Sources API
version: 0.1.0
description: Mixedbread data-sources 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/data_sources/{data_source_id}/connectors:
post:
tags:
- data_sources
- data_sources
summary: Create a new connector
description: "Create a new connector.\n\nArgs:\n data_source_id: The ID of the data source to create a connector\
\ for.\n params: The connector to create.\n\nReturns:\n The created connector."
operationId: create_connector
security:
- ApiKeyAuth: []
parameters:
- name: data_source_id
in: path
required: true
schema:
type: string
format: uuid
description: The ID of the data source to create a connector for
title: Data Source Id
description: The ID of the data source to create a connector for
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DataSourceConnectorCreateParams'
description: The connector to create
responses:
'201':
description: The created connector
content:
application/json:
schema:
$ref: '#/components/schemas/DataSourceConnector'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
get:
tags:
- data_sources
- data_sources
summary: Get all connectors for a data source
description: "Get all connectors for a data source.\n\nArgs:\n data_source_id: The ID of the data source to get connectors\
\ for.\n pagination: The pagination options.\n\nReturns:\n The list of connectors."
operationId: list_connectors
security:
- ApiKeyAuth: []
parameters:
- name: data_source_id
in: path
required: true
schema:
type: string
format: uuid
description: The ID of the data source to get connectors for
title: Data Source Id
description: The ID of the data source to get connectors for
- 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)
responses:
'200':
description: The list of connectors
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectorListResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/data_sources/{data_source_id}/connectors/{connector_id}:
get:
tags:
- data_sources
- data_sources
summary: Get a connector by ID
description: "Get a connector by ID.\n\nArgs:\n data_source_id: The ID of the data source to get a connector for.\n\
\ connector_id: The ID of the connector to get.\n\nReturns:\n The connector."
operationId: get_connector
security:
- ApiKeyAuth: []
parameters:
- name: data_source_id
in: path
required: true
schema:
type: string
format: uuid
description: The ID of the data source to get a connector for
title: Data Source Id
description: The ID of the data source to get a connector for
- name: connector_id
in: path
required: true
schema:
type: string
format: uuid
description: The ID of the connector to get
title: Connector Id
description: The ID of the connector to get
responses:
'200':
description: The connector
content:
application/json:
schema:
$ref: '#/components/schemas/DataSourceConnector'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
put:
tags:
- data_sources
- data_sources
summary: Update a connector
description: "Update a connector.\n\nArgs:\n data_source_id: The ID of the data source to update a connector for.\n\
\ connector_id: The ID of the connector to update.\n params: The connector to update.\n\nReturns:\n The updated\
\ connector."
operationId: update_connector
security:
- ApiKeyAuth: []
parameters:
- name: data_source_id
in: path
required: true
schema:
type: string
format: uuid
description: The ID of the data source to update a connector for
title: Data Source Id
description: The ID of the data source to update a connector for
- name: connector_id
in: path
required: true
schema:
type: string
format: uuid
description: The ID of the connector to update
title: Connector Id
description: The ID of the connector to update
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DataSourceConnectorUpdateParams'
description: The connector to update
responses:
'200':
description: The updated connector
content:
application/json:
schema:
$ref: '#/components/schemas/DataSourceConnector'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- data_sources
- data_sources
summary: Delete a connector
description: "Delete a connector.\n\nArgs:\n data_source_id: The ID of the data source to delete a connector for.\n\
\ connector_id: The ID of the connector to delete.\n\nReturns:\n The deleted connector."
operationId: delete_connector
security:
- ApiKeyAuth: []
parameters:
- name: data_source_id
in: path
required: true
schema:
type: string
format: uuid
description: The ID of the data source to delete a connector for
title: Data Source Id
description: The ID of the data source to delete a connector for
- name: connector_id
in: path
required: true
schema:
type: string
format: uuid
description: The ID of the connector to delete
title: Connector Id
description: The ID of the connector to delete
responses:
'200':
description: The deleted connector
content:
application/json:
schema:
$ref: '#/components/schemas/DataSourceConnectorDeleted'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/data_sources/:
post:
tags:
- data_sources
summary: Create a new data source
description: "Create a new data source.\n\nArgs:\n params: The data source to create.\n\nReturns:\n The created\
\ data source."
operationId: create_data_source
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/NotionDataSourceCreateOrUpdateParams'
- $ref: '#/components/schemas/LinearDataSourceCreateOrUpdateParams'
description: The data source to create
title: Params
responses:
'201':
description: The created data source
content:
application/json:
schema:
$ref: '#/components/schemas/DataSource'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
get:
tags:
- data_sources
summary: Get all data sources
description: "Get all data sources.\n\nReturns:\n The list of data sources."
operationId: list_data_sources
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)
responses:
'200':
description: The list of data sources
content:
application/json:
schema:
$ref: '#/components/schemas/DataSourceListResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/data_sources/{data_source_id}:
get:
tags:
- data_sources
summary: Get a data source by ID
description: "Get a data source by ID.\n\nArgs:\n data_source_id: The ID of the data source to fetch.\n\nReturns:\n\
\ The data source."
operationId: get_data_source
security:
- ApiKeyAuth: []
parameters:
- name: data_source_id
in: path
required: true
schema:
type: string
format: uuid
description: The ID of the data source to fetch
title: Data Source Id
description: The ID of the data source to fetch
responses:
'200':
description: The data source
content:
application/json:
schema:
$ref: '#/components/schemas/DataSource'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
put:
tags:
- data_sources
summary: Update a data source
description: "Update a data source.\n\nArgs:\n data_source_id: The ID of the data source to update.\n params:\
\ The data source to update.\n\nReturns:\n The updated data source."
operationId: update_data_source
security:
- ApiKeyAuth: []
parameters:
- name: data_source_id
in: path
required: true
schema:
type: string
format: uuid
description: The ID of the data source to update
title: Data Source Id
description: The ID of the data source to update
requestBody:
required: true
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/NotionDataSourceCreateOrUpdateParams'
- $ref: '#/components/schemas/LinearDataSourceCreateOrUpdateParams'
description: The data source to update
title: Params
responses:
'200':
description: The updated data source
content:
application/json:
schema:
$ref: '#/components/schemas/DataSource'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- data_sources
summary: Delete a data source
description: "Delete a data source.\n\nArgs:\n data_source_id: The ID of the data source to delete."
operationId: delete_data_source
security:
- ApiKeyAuth: []
parameters:
- name: data_source_id
in: path
required: true
schema:
type: string
format: uuid
description: The ID of the data source to delete
title: Data Source Id
description: The ID of the data source to delete
responses:
'200':
description: The ID of the deleted data source and if it was deleted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DataSourceDeleted'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/data_sources/{data_source_id}/oauth2/authorize:
get:
tags:
- data_sources
summary: Authorize a data source
description: "Start OAuth2 authorization flow for a data source.\n\nInitiates the OAuth2 authorization process by redirecting\
\ the user\nto the external service's authorization page. After authorization,\nthe user will be redirected back to\
\ the oauth2_callback endpoint.\n\nArgs:\n data_source_id: The ID of the data source to authorize\n\nReturns:\n\
\ Redirect to the OAuth2 provider's authorization page\n\nRaises:\n DataSourceNotFoundError: When data source\
\ doesn't exist\n DataSourceAuthTypeNotSupportedError: When OAuth2 is not supported for this data source type"
operationId: authorize_data_source
security:
- ApiKeyAuth: []
parameters:
- name: data_source_id
in: path
required: true
schema:
type: string
format: uuid
description: The ID of the data source to authorize
title: Data Source Id
description: The ID of the data source to authorize
responses:
'200':
description: The authorization URL
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/data_sources/oauth2/callback:
get:
tags:
- data_sources
summary: OAuth2 callback for data source authorization
description: "OAuth2 callback endpoint for completing data source authorization.\n\nThis endpoint is called by OAuth2\
\ providers after user authorization.\nIt exchanges the authorization code for access tokens and stores them\nsecurely\
\ for the data source.\n\nArgs:\n state: OAuth2 state parameter used for CSRF protection\n code: Authorization\
\ code from the OAuth2 provider\n error: OAuth2 error code if authorization was denied or failed\n error_description:\
\ Human-readable description of the error\n\nReturns:\n Redirect to the data source details page on success\n\n\
Raises:\n OAuth2TokenExchangeError: When OAuth2 provider returns an error\n InvalidStateError: When state parameter\
\ is invalid or expired"
operationId: oauth2_callback
security:
- ApiKeyAuth: []
parameters:
- name: state
in: query
required: true
schema:
type: string
description: OAuth2 state parameter for CSRF protection
title: State
description: OAuth2 state parameter for CSRF protection
- name: code
in: query
required: true
schema:
type: string
description: Authorization code from OAuth2 provider
title: Code
description: Authorization code from OAuth2 provider
- name: error
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: OAuth2 error code if authorization failed
title: Error
description: OAuth2 error code if authorization failed
- name: error_description
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Human-readable error description
title: Error Description
description: Human-readable error description
responses:
'307':
description: Successful authorization, redirect to data source
content:
application/json:
schema: {}
'400':
description: OAuth2 error or invalid parameters
'404':
description: Invalid or expired state parameter
'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:
typ
# --- truncated at 32 KB (260 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mixedbread-ai/refs/heads/main/openapi/mixedbread-data-sources-api-openapi.yml