openapi: 3.1.0
info:
  title: Mathpix App Tokens Images API
  description: 'Mint short-lived client-side tokens so browsers, mobile apps, and digital-ink surfaces can call Mathpix without exposing your long-lived app_key. Tokens default to 5 minutes and can be issued from 30 seconds to 12 hours. Token issuance is free.

    '
  version: v3
  contact:
    name: Mathpix Support
    url: https://docs.mathpix.com
    email: support@mathpix.com
  license:
    name: Mathpix Terms of Service
    url: https://mathpix.com/terms-of-service
servers:
- url: https://api.mathpix.com
  description: Production Server
security:
- AppKeyAuth: []
tags:
- name: Images
  description: Process a single image for STEM OCR.
paths:
  /v3/text:
    post:
      summary: Process An Image
      description: 'Submit a single image (by URL or base64) and receive Mathpix Markdown (MMD) plus optional structured data, HTML, styled LaTeX, line data, and word data. Auto-detects whether the content is printed or handwritten.

        '
      operationId: processImage
      tags:
      - Images
      parameters:
      - $ref: '#/components/parameters/AppIdHeader'
      - $ref: '#/components/parameters/AppKeyHeader'
      - $ref: '#/components/parameters/ContentTypeHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TextRequest'
      responses:
        '200':
          description: Successful OCR result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TextResponse'
        '401':
          description: Missing or invalid credentials.
        '429':
          description: Rate limit exceeded.
components:
  schemas:
    TextRequest:
      type: object
      description: Single-image OCR request body.
      properties:
        src:
          type: string
          description: Image URL or base64-encoded image (e.g. data:image/png;base64,...).
        metadata:
          type: object
          description: Free-form key/value metadata stored with the request for privacy and audit.
          additionalProperties: true
        formats:
          type: array
          description: Output formats requested in addition to MMD. Supported values include text, data, html, latex_styled.
          items:
            type: string
            enum:
            - text
            - data
            - html
            - latex_styled
        math_inline_delimiters:
          type: array
          description: Custom delimiters for inline math, e.g. ["\\(", "\\)"].
          items:
            type: string
        math_display_delimiters:
          type: array
          description: Custom delimiters for display math, e.g. ["\\[", "\\]"].
          items:
            type: string
        include_line_data:
          type: boolean
          description: Include line-by-line segmentation in the response.
          default: false
        include_word_data:
          type: boolean
          description: Include word-level segmentation in the response.
          default: false
        rm_spaces:
          type: boolean
          description: Strip extra whitespace inside equations.
          default: true
        confidence_threshold:
          type: number
          format: float
          description: Minimum confidence threshold (0.0 - 1.0) below which results are rejected.
          minimum: 0.0
          maximum: 1.0
    TextResponse:
      type: object
      description: OCR response containing recognized content and confidence metrics.
      properties:
        request_id:
          type: string
          description: Unique identifier for debugging.
        text:
          type: string
          description: Recognized content in Mathpix Markdown.
        latex_styled:
          type: string
          description: Styled LaTeX equivalent when latex_styled is requested.
        html:
          type: string
          description: HTML rendering when html is requested.
        data:
          type: array
          description: Structured data extracted from the image.
          items:
            type: object
            additionalProperties: true
        confidence:
          type: number
          format: float
          description: Probability of 100% accuracy in the range 0.0 - 1.0.
        confidence_rate:
          type: number
          format: float
          description: Output quality confidence in the range 0.0 - 1.0.
        is_printed:
          type: boolean
          description: True when printed content was detected.
        is_handwritten:
          type: boolean
          description: True when handwritten content was detected.
        auto_rotate_confidence:
          type: number
          format: float
        auto_rotate_degrees:
          type: integer
          enum:
          - 0
          - 90
          - -90
          - 180
        image_height:
          type: integer
        image_width:
          type: integer
        line_data:
          type: array
          description: Per-line segmentation when include_line_data=true.
          items:
            type: object
            additionalProperties: true
        word_data:
          type: array
          description: Per-word segmentation when include_word_data=true.
          items:
            type: object
            additionalProperties: true
        version:
          type: string
        error:
          type: string
          description: Error message if processing failed.
  parameters:
    ContentTypeHeader:
      name: Content-Type
      in: header
      required: true
      schema:
        type: string
        default: application/json
    AppKeyHeader:
      name: app_key
      in: header
      required: true
      schema:
        type: string
      description: Mathpix application secret issued at console.mathpix.com.
    AppIdHeader:
      name: app_id
      in: header
      required: true
      schema:
        type: string
      description: Mathpix application identifier issued at console.mathpix.com.
  securitySchemes:
    AppKeyAuth:
      type: apiKey
      in: header
      name: app_key