openapi: 3.0.3
info:
  title: Toolsie OCR API
  description: |
    Распознавание рукописи и документов. Ключ — в кабинете после регистрации
    (бесплатный лимит без карты). Документация: https://toolsie.ru/api-docs
  version: "1.0.0"
  contact:
    email: hello@toolsie.ru
servers:
  - url: https://toolsie.ru
paths:
  /api/v1/ocr:
    post:
      operationId: ocrRecognize
      summary: Распознать документ
      description: |
        Multipart или JSON (image_base64). Ответ всегда содержит поле text.
        Для табличных tool= — CSV внутри text. Лимит файла 8 МБ, PDF до 12 страниц.
      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 или PDF до 8 МБ
                tool:
                  $ref: "#/components/schemas/OcrTool"
          application/json:
            schema:
              type: object
              required: [image_base64, tool]
              properties:
                tool:
                  $ref: "#/components/schemas/OcrTool"
                image_base64:
                  type: string
                  description: Base64 без data:-префикса
                mime:
                  type: string
                  example: image/jpeg
                filename:
                  type: string
      responses:
        "200":
          description: Успех
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: Месячная квота
            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: Ключ вида tls_xxxx.yyyy из кабинета
  schemas:
    OcrTool:
      type: string
      enum:
        - rukopis-v-tekst
        - vrachebny-pocherk
        - starinny-tekst
        - rukopis-v-latex
        - rukopis-v-tablitsu
        - chek-v-excel
        - nakladnaya-v-excel
        - vizitka-v-excel
        - form-v-json
        - doska-v-tekst
        - foto-tablitsy-v-excel
        - screenshot-v-kod
    OcrSuccess:
      type: object
      required: [text, tool, usage]
      properties:
        text:
          type: string
        tool:
          type: string
        usage:
          type: object
          properties:
            used:
              type: integer
            quota:
              type: integer
            remaining:
              type: integer
            plan:
              type: string
            month:
              type: string