openapi: 3.1.0
info:
  title: Mixedbread admin parsing API
  version: 0.1.0
  description: Mixedbread admin 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
tags:
- name: parsing
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\nReturns:\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:
    Mode:
      type: string
      enum:
      - fast
      - high_quality
      title: Mode
      description: The mode of the document parser.
    ParsingJob:
      properties:
        id:
          type: string
          title: Id
          description: The ID of the job
        file_id:
          type: string
          title: File Id
          description: The ID of the file to parse
        filename:
          anyOf:
          - type: string
          - type: 'null'
          title: Filename
          description: The name of the file
        status:
          $ref: '#/components/schemas/ParsingJobStatus'
          description: The status of the job
        error:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Error
          description: The error of the job
        result:
          anyOf:
          - $ref: '#/components/schemas/DocumentParserResult'
          - type: 'null'
          description: The result of the job
        started_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Started At
          description: The started time of the job
        finished_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Finished At
          description: The finished time of the job
        created_at:
          type: string
          format: date-time
          title: Created At
          description: The creation time of the job
        updated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Updated At
          description: The updated time of the job
        object:
          type: string
          const: parsing_job
          title: Object
          description: The type of the object
          default: parsing_job
      type: object
      required:
      - id
      - file_id
      - status
      title: ParsingJob
      description: A job for parsing documents with its current state and result.
    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.
    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
    ElementType:
      type: string
      enum:
      - header
      - footer
      - title
      - section-header
      - page-number
      - list-item
      - figure
      - table
      - form
      - text
      - footnote
      title: ElementType
      description: Types of elements that can be extracted from a document.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ChunkingStrategy:
      type: string
      enum:
      - page
      title: ChunkingStrategy
      description: Strategy used for chunking document content.
    ParsingJobListResponse:
      properties:
        pagination:
          $ref: '#/components/schemas/CursorPaginationResponse'
        data:
          items:
            $ref: '#/components/schemas/ParsingJobListItem'
          type: array
          title: Data
          description: The list of parsing jobs
        object:
          type: string
          const: list
          title: Object
          description: The object type of the response
          default: list
      type: object
      required:
      - pagination
      - data
      title: ParsingJobListResponse
      description: A list of parsing jobs with pagination.
    ParsingJobListItem:
      properties:
        id:
          type: string
          title: Id
          description: The ID of the job
        file_id:
          type: string
          title: File Id
          description: The ID of the file to parse
        filename:
          anyOf:
          - type: string
          - type: 'null'
          title: Filename
          description: The name of the file
        status:
          $ref: '#/components/schemas/ParsingJobStatus'
          description: The status of the job
        error:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Error
          description: The error of the job
        started_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Started At
          description: The started time of the job
        finished_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Finished At
          description: The finished time of the job
        created_at:
          type: string
          format: date-time
          title: Created At
          description: The creation time of the job
        updated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Updated At
          description: The updated time of the job
        object:
          type: string
          const: parsing_job
          title: Object
          description: The type of the object
          default: parsing_job
      type: object
      required:
      - id
      - file_id
      - status
      title: ParsingJobListItem
      description: A parsing job item for list responses.
    ParsingJobCreateParams:
      properties:
        file_id:
          type: string
          title: File Id
          description: The ID of the file to parse
        element_types:
          anyOf:
          - items:
              $ref: '#/components/schemas/ElementType'
            type: array
          - type: 'null'
          title: Element Types
          description: The elements to extract from the document
        chunking_strategy:
          $ref: '#/components/schemas/ChunkingStrategy'
          description: The strategy to use for chunking the content
          default: page
        return_format:
          $ref: '#/components/schemas/ReturnFormat'
          description: The format of the returned content
          default: markdown
        mode:
          $ref: '#/components/schemas/Mode'
          description: The strategy to use for OCR
          default: high_quality
      type: object
      required:
      - file_id
      title: ParsingJobCreateParams
      description: Parameters for creating a parsing job.
    ReturnFormat:
      type: string
      enum:
      - html
      - markdown
      - plain
      title: ReturnFormat
      description: Format options for the returned document content.
    ParsingJobStatus:
      type: string
      enum:
      - pending
      - in_progress
      - cancelled
      - completed
      - failed
      title: ParsingJobStatus
    ParsingJobDeleted:
      properties:
        id:
          type: string
          title: Id
          description: The ID of the deleted job
        deleted:
          type: boolean
          title: Deleted
          description: Whether the job was deleted
          default: true
        object:
          type: string
          const: parsing_job
          title: Object
          description: The type of the object
          default: parsing_job
      type: object
      required:
      - id
      title: ParsingJobDeleted
      description: A deleted parsing 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.
    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.
    DocumentParserResult:
      properties:
        chunking_strategy:
          $ref: '#/components/schemas/ChunkingStrategy'
          description: The strategy used for chunking the document
        return_format:
          $ref: '#/components/schemas/ReturnFormat'
          description: The format of the returned content
        element_types:
          items:
            $ref: '#/components/schemas/ElementType'
          type: array
          title: Element Types
          description: The types of elements extracted
        chunks:
          items:
            $ref: '#/components/schemas/Chunk'
          type: array
          title: Chunks
          description: List of extracted chunks from the document
        page_sizes:
          items:
            prefixItems:
            - type: integer
            - type: integer
            type: array
            maxItems: 2
            minItems: 2
          type: array
          title: Page Sizes
          description: List of (width, height) tuples for each page
      type: object
      required:
      - chunking_strategy
      - return_format
      - element_types
      - chunks
      title: DocumentParserResult
      description: Result of document parsing operation.
  securitySchemes:
    ApiKeyAuth:
      type: http
      description: Api key to access Mixedbreads API
      scheme: bearer