openapi: 3.0.3
info:
  title: Toolsy OCR API
  description: |
    Handwriting and document recognition. Create a key in your account after sign-up
    (free monthly quota, no card). Docs: https://toolsy.tools/api-docs
  version: "1.1.0"
  contact:
    email: hello@toolsy.tools
servers:
  - url: https://toolsy.tools
paths:
  /api/v1/ocr:
    post:
      operationId: ocrRecognize
      summary: Recognize a document
      description: |
        Multipart or JSON (image_base64). Response always includes text.
        Table tools return CSV inside text. Max file 12 MB; PDF up to 20 pages.
        Set grounding=true (or boxes=true) to also return normalized bounding boxes
        for evidence review (0–1000 coordinate grid).
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file, tool]
              properties:
                file:
                  type: string
                  format: binary
                  description: JPG, PNG, WebP, GIF or PDF up to 12 MB
                tool:
                  $ref: "#/components/schemas/OcrTool"
                grounding:
                  type: boolean
                  description: When true, also return boxes for key fields
                boxes:
                  type: boolean
                  description: Alias for grounding
          application/json:
            schema:
              type: object
              required: [image_base64, tool]
              properties:
                tool:
                  $ref: "#/components/schemas/OcrTool"
                image_base64:
                  type: string
                  description: Base64 without data: prefix
                mime:
                  type: string
                  example: image/jpeg
                filename:
                  type: string
                grounding:
                  type: boolean
                boxes:
                  type: boolean
      responses:
        "200":
          description: Success
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: Monthly quota
            X-RateLimit-Used:
              schema:
                type: integer
            X-RateLimit-Remaining:
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OcrSuccess"
        "401":
          description: invalid_api_key
        "400":
          description: unknown_tool | file_required | file_too_large
        "429":
          description: rate_limited | quota_exceeded
        "502":
          description: ocr_failed
        "503":
          description: ocr_unavailable
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: Key like tsy_xxxx.yyyy from account
  schemas:
    OcrTool:
      type: string
      enum:
        - handwriting-to-text
        - handwriting-to-latex
        - handwriting-to-table
        - table-photo-to-excel
        - receipt-to-excel
        - packing-slip-to-excel
        - invoice-to-excel
        - business-card-to-excel
        - doctor-handwriting
        - historical-manuscript
        - form-to-json
        - whiteboard-to-text
        - screenshot-to-code
        - screenshot-to-text
        - meter-reading
        - notes-to-markdown
    OcrBox:
      type: object
      required: [mention, x1, y1, x2, y2]
      properties:
        mention:
          type: string
          description: Label such as field:value
        x1:
          type: number
        y1:
          type: number
        x2:
          type: number
        y2:
          type: number
    OcrSuccess:
      type: object
      required: [text, tool, usage]
      properties:
        text:
          type: string
        tool:
          type: string
        boxes:
          type: array
          items:
            $ref: "#/components/schemas/OcrBox"
          description: Present when grounding=true
        coordinate_space:
          type: string
          enum: [normalized_0_1000]
          description: Present when grounding=true
        usage:
          type: object
          properties:
            used:
              type: integer
            quota:
              type: integer
            remaining:
              type: integer
            plan:
              type: string
            month:
              type: string