openapi: 3.1.0
info:
  title: Docling CLI as REST Async Convert API
  description: 'REST-style mapping of the `docling` command-line tool, modeling each conversion

    invocation as a `POST /v1/convert` call. Useful for documenting and orchestrating

    local CLI runs from agent frameworks and capability-based runtimes.

    '
  version: '1.0'
  license:
    name: MIT
    url: https://github.com/docling-project/docling/blob/main/LICENSE
  contact:
    name: Docling Project
    url: https://github.com/docling-project/docling
servers:
- url: file:///usr/local/bin
  description: Local docling CLI binary.
tags:
- name: Convert
  description: Document conversion operations.
paths:
  /v1/convert:
    post:
      tags:
      - Convert
      summary: Convert A Document Via The Docling CLI
      description: 'Run the `docling` command against one source (file path or URL) and write the

        configured outputs to disk. Mirrors the `docling [source] [flags]` invocation.

        '
      operationId: cliConvert
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CliConvertRequest'
      responses:
        '200':
          description: Conversion succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CliConvertResponse'
        '400':
          description: Invalid arguments.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CliError'
        '500':
          description: Conversion failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CliError'
  /v1/convert/source:
    post:
      tags:
      - Convert
      summary: Convert Documents From Source URLs
      description: 'Synchronously convert one or more documents pulled from HTTP source URLs or

        provided inline as base64. Returns the converted document(s) directly in the

        response body.

        '
      operationId: convertSource
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConvertSourceRequest'
      responses:
        '200':
          description: Conversion completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConvertResponse'
            application/zip:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
  /v1/convert/file:
    post:
      tags:
      - Convert
      summary: Convert Documents From Uploaded Files
      description: 'Synchronously convert one or more documents uploaded as multipart form data.

        Conversion options are supplied as additional form fields.

        '
      operationId: convertFile
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ConvertFileForm'
      responses:
        '200':
          description: Conversion completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConvertResponse'
            application/zip:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
components:
  schemas:
    ConvertFileForm:
      type: object
      properties:
        files:
          type: array
          items:
            type: string
            format: binary
        from_formats:
          type: array
          items:
            type: string
        to_formats:
          type: array
          items:
            type: string
        image_export_mode:
          type: string
          enum:
          - embedded
          - placeholder
          - referenced
        do_ocr:
          type: boolean
        ocr_engine:
          type: string
        force_ocr:
          type: boolean
        ocr_lang:
          type: array
          items:
            type: string
        pdf_backend:
          type: string
        table_mode:
          type: string
          enum:
          - fast
          - accurate
        do_table_structure:
          type: boolean
        include_images:
          type: boolean
        images_scale:
          type: number
        return_as_file:
          type: boolean
    ConvertDocumentsOptions:
      type: object
      description: Conversion behavior knobs shared by sync and async endpoints.
      properties:
        from_formats:
          type: array
          description: Input formats to accept.
          items:
            type: string
            enum:
            - pdf
            - docx
            - pptx
            - xlsx
            - html
            - md
            - asciidoc
            - image
            - audio
            - csv
            - xml_uspto
            - xml_jats
        to_formats:
          type: array
          description: Output formats to produce.
          items:
            type: string
            enum:
            - md
            - html
            - json
            - text
            - doctags
        image_export_mode:
          type: string
          enum:
          - embedded
          - placeholder
          - referenced
        do_ocr:
          type: boolean
        force_ocr:
          type: boolean
        ocr_engine:
          type: string
          enum:
          - easyocr
          - tesseract
          - tesseract_cli
          - rapidocr
          - mac_ocr
          - ocrmac
        ocr_lang:
          type: array
          items:
            type: string
        pdf_backend:
          type: string
          enum:
          - dlparse_v1
          - dlparse_v2
          - pypdfium2
        table_mode:
          type: string
          enum:
          - fast
          - accurate
        do_table_structure:
          type: boolean
        do_code_enrichment:
          type: boolean
        do_formula_enrichment:
          type: boolean
        do_picture_classification:
          type: boolean
        do_picture_description:
          type: boolean
        picture_description_area_threshold:
          type: number
        include_images:
          type: boolean
        images_scale:
          type: number
        pipeline:
          type: string
          enum:
          - standard
          - vlm
        vlm_model:
          type: string
        return_as_file:
          type: boolean
        abort_on_error:
          type: boolean
    CliConvertRequest:
      type: object
      required:
      - source
      properties:
        source:
          type: string
          description: File path, directory, or HTTP(S) URL to convert.
        from_formats:
          type: array
          items:
            type: string
            enum:
            - pdf
            - docx
            - pptx
            - xlsx
            - html
            - md
            - asciidoc
            - image
            - audio
            - csv
          description: Input formats to accept when scanning directories.
        to_formats:
          type: array
          items:
            type: string
            enum:
            - md
            - html
            - json
            - text
            - doctags
          description: Output formats to write.
        output:
          type: string
          description: Output directory.
        ocr:
          type: boolean
        ocr_engine:
          type: string
          enum:
          - easyocr
          - tesseract
          - tesseract_cli
          - rapidocr
          - ocrmac
        ocr_lang:
          type: array
          items:
            type: string
        force_ocr:
          type: boolean
        table_mode:
          type: string
          enum:
          - fast
          - accurate
        pipeline:
          type: string
          enum:
          - standard
          - vlm
        vlm_model:
          type: string
          enum:
          - granite_docling
          - granite_docling_mlx
          - smoldocling
        image_export_mode:
          type: string
          enum:
          - embedded
          - placeholder
          - referenced
        enrich_code:
          type: boolean
        enrich_formula:
          type: boolean
        enrich_picture_classes:
          type: boolean
        enrich_picture_description:
          type: boolean
        device:
          type: string
          enum:
          - auto
          - cpu
          - cuda
          - mps
        num_threads:
          type: integer
        abort_on_error:
          type: boolean
        verbose:
          type: boolean
    DoclingDocumentRendering:
      type: object
      description: Container of one or more renderings of the converted document.
      properties:
        filename:
          type: string
        md_content:
          type: string
        html_content:
          type: string
        json_content:
          $ref: '#/components/schemas/DoclingDocument'
        text_content:
          type: string
        doctags_content:
          type: string
    DoclingDocument:
      type: object
      description: Canonical Docling document representation. See docling-core for the full schema.
      properties:
        schema_name:
          type: string
        version:
          type: string
        name:
          type: string
        origin:
          type: object
        furniture:
          type: array
          items:
            type: object
        body:
          type: object
        groups:
          type: array
          items:
            type: object
        texts:
          type: array
          items:
            type: object
        tables:
          type: array
          items:
            type: object
        pictures:
          type: array
          items:
            type: object
        key_value_items:
          type: array
          items:
            type: object
        pages:
          type: object
    CliError:
      type: object
      properties:
        message:
          type: string
        code:
          type: integer
    HttpSource:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          format: uri
        headers:
          type: object
          additionalProperties:
            type: string
    Target:
      type: object
      description: Optional delivery target for the converted output.
      properties:
        kind:
          type: string
          enum:
          - inbody
          - zip
          - s3
          - http
        zip_file_name:
          type: string
    ErrorResponse:
      type: object
      properties:
        detail:
          type: string
        code:
          type: string
    ConvertResponse:
      type: object
      properties:
        document:
          $ref: '#/components/schemas/DoclingDocumentRendering'
        status:
          type: string
          enum:
          - success
          - partial_success
          - failure
        errors:
          type: array
          items:
            type: object
        processing_time:
          type: number
        timings:
          type: object
          additionalProperties:
            type: number
    FileSource:
      type: object
      required:
      - base64_string
      - filename
      properties:
        base64_string:
          type: string
          description: Base64-encoded file content.
        filename:
          type: string
          description: Original filename, used for format detection.
    ConvertSourceRequest:
      type: object
      description: Request body for source-based document conversion.
      properties:
        http_sources:
          type: array
          description: HTTP/HTTPS URLs to fetch and convert.
          items:
            $ref: '#/components/schemas/HttpSource'
        file_sources:
          type: array
          description: Inline base64-encoded documents.
          items:
            $ref: '#/components/schemas/FileSource'
        options:
          $ref: '#/components/schemas/ConvertDocumentsOptions'
        target:
          $ref: '#/components/schemas/Target'
    CliConvertResponse:
      type: object
      properties:
        outputs:
          type: array
          items:
            type: object
            properties:
              path:
                type: string
              format:
                type: string
        status:
          type: string
          enum:
          - success
          - partial_success
          - failure
        processing_time:
          type: number
  responses:
    Error:
      description: Error response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'