openapi: 3.1.0
info:
  title: Mindee OCR API
  version: 2.0.0
  description: Run full-page optical character recognition to obtain raw text and bounding polygons for any document.
  contact:
    name: Mindee
    url: https://mindee.com
  license:
    name: Proprietary
servers:
- url: https://api-v2.mindee.net
tags:
- name: Ocr
  description: Run full-page optical character recognition to obtain raw text and bounding polygons for any document.
paths:
  /v2/products/ocr/enqueue:
    post:
      tags:
      - Ocr
      summary: Send A File For An Ocr Utility Inference
      description: "Send a file to the asynchronous processing queue for an ocr utility inference.\n\nResults can be retrieved\
        \ in two ways:\n* Loop on the `polling_url` endpoint in the response until the status\n  is `Processed` or `Failed`\
        \ (polling).\n* Use a webhook to be notified when the inference is finished.\n  Webhooks can be configured on the\
        \ platform on a per-model basis.\n\nInferences taking longer than 590 seconds will time out."
      operationId: Enqueue_OCR_Product_Inference_v2_products_ocr_enqueue_post
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - APIKeyHeader: []
  /v2/products/ocr/results/{inference_id}:
    get:
      tags:
      - Ocr
      summary: Get The Result Of A Completed Ocr Product Inference
      description: 'Get the result of an ocr utility inference that was previously enqueued.


        The inference will only be available after it has finished processing.


        If you are using webhooks there is no need to call this route.<br/>

        However, the JSON payload described here is what will be sent to each specified webhook''s URL.


        If you activated the "Delete extracted data when fetched" option for the model,

        the inference will be deleted after this route completes.<br>

        Any further requests to the same inference ID will return a 404.'
      operationId: Get_OCR_Product_Result_v2_products_ocr_results__inference_id__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: inference_id
        in: path
        required: true
        schema:
          type: string
          format: uuid4
          title: Inference ID
          description: UUID of the inference to retrieve
        description: UUID of the inference to retrieve
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OCRResponse-Output'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unprocessable Content
      requestBody:
        content:
          multipart/form-data:
            schema:
              description: Form to enqueue an inference for utility models.
              properties:
                model_id:
                  description: Model ID to use for the inference.
                  format: uuid4
                  title: Model Id
                  type: string
                file:
                  anyOf:
                  - format: binary
                    type: string
                  - type: 'null'
                  description: Upload a file as bytes. Required if `url` is not provided.
                  title: File
                url:
                  anyOf:
                  - format: uri
                    maxLength: 2048
                    minLength: 1
                    type: string
                  - type: 'null'
                  description: Download the file from a URL, must be secure (HTTPS) and publicly available. Required if `file`
                    is not provided.
                  title: Url
                file_base64:
                  anyOf:
                  - minLength: 15
                    type: string
                  - type: 'null'
                  description: Upload a file as a base 64 string. Used as an alternative to `file`. *Not recommended*, for
                    specific use only.
                  examples:
                  - Base64String==
                  title: File Base64
                webhook_ids:
                  description: Webhook IDs to call after all processing is finished. If empty, no webhooks will be used. Can
                    be a list or comma-separated string.
                  items:
                    format: uuid4
                    type: string
                  title: Webhook Ids
                  type: array
                filename:
                  anyOf:
                  - type: string
                  - type: 'null'
                  description: Optional filename to associate with the uploaded or fetched file.
                  title: Filename
                alias:
                  anyOf:
                  - type: string
                  - type: 'null'
                  description: 'Optional: a free-form string to tag the request with your own identifier. For example, an
                    internal document ID, reference number, or database key. If set, it will be included in the job and result
                    responses.'
                  examples:
                  - my_file_alias
                  title: Alias
              required:
              - model_id
              title: UtilityEnqueueForm
              type: object
          application/json:
            schema:
              description: Form to enqueue an inference for utility models.
              properties:
                model_id:
                  description: Model ID to use for the inference.
                  format: uuid4
                  title: Model Id
                  type: string
                url:
                  anyOf:
                  - format: uri
                    maxLength: 2048
                    minLength: 1
                    type: string
                  - type: 'null'
                  description: Download the file from a URL, must be secure (HTTPS) and publicly available. Required if `file`
                    is not provided.
                  title: Url
                file_base64:
                  anyOf:
                  - minLength: 15
                    type: string
                  - type: 'null'
                  description: Upload a file as a base 64 string. Used as an alternative to `file`. *Not recommended*, for
                    specific use only.
                  examples:
                  - Base64String==
                  title: File Base64
                webhook_ids:
                  description: Webhook IDs to call after all processing is finished. If empty, no webhooks will be used. Can
                    be a list or comma-separated string.
                  items:
                    format: uuid4
                    type: string
                  title: Webhook Ids
                  type: array
                filename:
                  anyOf:
                  - type: string
                  - type: 'null'
                  description: Optional filename to associate with the uploaded or fetched file.
                  title: Filename
                alias:
                  anyOf:
                  - type: string
                  - type: 'null'
                  description: 'Optional: a free-form string to tag the request with your own identifier. For example, an
                    internal document ID, reference number, or database key. If set, it will be included in the job and result
                    responses.'
                  examples:
                  - my_file_alias
                  title: Alias
              required:
              - model_id
              title: UtilityEnqueueForm
              type: object
        required: true
components:
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: Authorization
  schemas:
    BaseJob:
      properties:
        id:
          type: string
          format: uuid4
          title: Id
          description: UUID of the Job.
      type: object
      required:
      - id
      title: BaseJob
      description: Base class for Job.
    ErrorItem:
      properties:
        pointer:
          anyOf:
          - type: string
          - type: 'null'
          title: Pointer
          description: A JSON Pointer to the location of the body property.
          examples:
          - '#/model_id'
        detail:
          type: string
          title: Detail
          description: Explicit information on the issue.
          examples:
          - '''model_id'' must be a valid UUID format'
      type: object
      required:
      - pointer
      - detail
      title: ErrorItem
      description: Explicit details on a problem.
    ErrorResponse:
      properties:
        status:
          type: integer
          maximum: 599.0
          minimum: 100.0
          title: Status
          description: The HTTP status code returned by the server.
          examples:
          - 422
        detail:
          type: string
          title: Detail
          description: A human-readable explanation specific to the occurrence of the problem.
          examples:
          - One or more fields failed validation.
        title:
          type: string
          title: Title
          description: A short, human-readable summary of the problem.
          examples:
          - Invalid fields in form
        code:
          type: string
          title: Code
          description: A machine-readable code specific to the occurrence of the problem.
          examples:
          - 422-001
        errors:
          items:
            $ref: '#/components/schemas/ErrorItem'
          type: array
          title: Errors
          description: A list of explicit details on the problem.
          default: []
      type: object
      required:
      - status
      - detail
      - title
      - code
      title: ErrorResponse
      description: Error response detailing a problem. The format adheres to RFC 9457.
    InferenceFile:
      properties:
        name:
          type: string
          title: Name
          description: File name as sent to the API.
        alias:
          anyOf:
          - type: string
          - type: 'null'
          title: Alias
          description: Alias sent to the API.
        page_count:
          type: integer
          minimum: 1.0
          title: Page Count
          description: Number of pages in the file.
        mime_type:
          type: string
          title: MIME Type
          description: Detected MIME type of the file.
      type: object
      required:
      - name
      - page_count
      - mime_type
      title: InferenceFile
      description: File used for the inference.
    InferenceModel:
      properties:
        id:
          type: string
          format: uuid4
          title: ID
          description: UUID of the model.
      type: object
      required:
      - id
      title: InferenceModel
      description: Model used for the inference.
    Job:
      properties:
        id:
          type: string
          format: uuid4
          title: Id
          description: UUID of the Job.
        model_id:
          type: string
          format: uuid4
          title: Model Id
          description: UUID of the model to be used for the inference.
        filename:
          type: string
          title: Filename
          description: Name of the file sent.
          examples:
          - file.jpg
        alias:
          anyOf:
          - type: string
          - type: 'null'
          title: Alias
          description: Optional alias sent for the file.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Date and time of the Job creation.
        completed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Completed At
          description: Date and time of the Job completion. Filled once processing is finished.
        status:
          $ref: '#/components/schemas/Status'
        polling_url:
          type: string
          maxLength: 2083
          minLength: 1
          format: uri
          title: Polling Url
          description: URL to poll for the Job status.
        result_url:
          anyOf:
          - type: string
            maxLength: 2083
            minLength: 1
            format: uri
          - type: 'null'
          title: Result Url
          description: URL to retrieve the inference results. Will be filled once the inference is ready.
        webhooks:
          items:
            $ref: '#/components/schemas/WebhookResponse'
          type: array
          title: Webhooks
          description: List of responses from webhooks called. Empty until processing is finished.
          default: []
        error:
          anyOf:
          - $ref: '#/components/schemas/ErrorResponse'
          - type: 'null'
          description: If an error occurred during processing, contains the problem details.
      type: object
      required:
      - id
      - model_id
      - filename
      - created_at
      - status
      - polling_url
      title: Job
      description: Information on the processing of a file sent to the Mindee API.
    JobResponse:
      properties:
        job:
          $ref: '#/components/schemas/Job'
      type: object
      required:
      - job
      title: JobResponse
      description: Response for a Job.
    OCRInference-Output:
      properties:
        id:
          type: string
          format: uuid4
          title: Id
          description: UUID of the Inference.
        job:
          $ref: '#/components/schemas/BaseJob'
          title: Job
          description: Job the inference belongs to.
        model:
          $ref: '#/components/schemas/InferenceModel'
        file:
          $ref: '#/components/schemas/InferenceFile'
        result:
          $ref: '#/components/schemas/OCRResult-Output'
      type: object
      required:
      - id
      - job
      - model
      - file
      - result
      title: OCRInference
      description: The inference result for a ocr utility request.
    OCRResponse-Output:
      properties:
        inference:
          $ref: '#/components/schemas/OCRInference-Output'
      type: object
      required:
      - inference
      title: OCRResponse
      description: Response for an ocr utility inference.
    OCRResult-Output:
      properties:
        pages:
          items:
            $ref: '#/components/schemas/PageOCR'
          type: array
          title: pages
          description: List of OCR results for each page in the document.
      type: object
      required:
      - pages
      title: OCRResult
      description: Result of the OCR utility inference.
    PageOCR:
      properties:
        words:
          items:
            $ref: '#/components/schemas/WordOCR'
          type: array
          title: Words
          description: List of words extracted from the document page.
        content:
          type: string
          title: Content
          description: Full text content extracted from the document page.
      type: object
      required:
      - words
      - content
      title: PageOCR
      description: OCR result for a single page.
    Status:
      type: string
      enum:
      - Processing
      - Failed
      - Processed
      title: Status
      description: Possible states of an operation.
    WebhookResponse:
      properties:
        id:
          type: string
          format: uuid4
          title: Id
          description: UUID of the webhook endpoint.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Date and time the webhook was called.
        status:
          $ref: '#/components/schemas/Status'
          default: Processing
        error:
          anyOf:
          - $ref: '#/components/schemas/ErrorResponse'
          - type: 'null'
          description: If an error occurred when calling the webhook, contains the problem details.
        attempts_count:
          type: integer
          title: Attempts Count
          description: Number of attempts made to call the webhook.
          default: 0
      type: object
      required:
      - id
      title: WebhookResponse
      description: Response from a webhook call.
    WordOCR:
      properties:
        content:
          type: string
          title: Content
          description: Text content of the word.
        polygon:
          items:
            prefixItems:
            - type: number
              maximum: 1.0
              minimum: 0.0
              title: Coordinate
              description: Coordinate value relative to document edge.
            - type: number
              maximum: 1.0
              minimum: 0.0
              title: Coordinate
              description: Coordinate value relative to document edge.
            type: array
            maxItems: 2
            minItems: 2
            title: Point
            description: Relative coordinates of a point in [X,Y] notation.
          type: array
          minItems: 3
          title: Polygon
          description: Position information as a list of points in clockwise order.
      type: object
      required:
      - content
      - polygon
      title: WordOCR
      description: OCR result for a single word extracted from the document page.
security:
- APIKeyHeader: []