openapi: 3.2.0
info:
  title: Kit for AI — API Playground Batch API
  version: 1.0.0
  description: Welcome to the **Kit for AI** API playground.
  contact:
    name: Kit for AI
    url: https://kitforai.com
servers:
- url: https://kitforai.com
security:
- apiKey: []
tags:
- name: Batch
paths:
  /api/v1/batch:
    post:
      summary: Convert in bulk
      description: Submit up to 25 files and/or URLs in one multipart request (repeat the `file` and `url` fields). Each item consumes one rate-limit token. Returns a per-item result array; the response is 200 even with partial failures — inspect each item's `status`.
      operationId: convertBatch
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: One or more documents
                url:
                  type: array
                  items:
                    type: string
                  description: One or more URLs
                outputFormat:
                  type: string
                  enum:
                  - markdown
                  - json
                  default: markdown
                jsonSchema:
                  type: string
                  description: Optional stringified JSON schema (outputFormat=json)
                deepExtract:
                  type: boolean
      responses:
        '200':
          description: Per-item results
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      total:
                        type: integer
                      succeeded:
                        type: integer
                      results:
                        type: array
                        items:
                          type: object
                          properties:
                            index:
                              type: integer
                            source:
                              type: string
                            status:
                              type: string
                              enum:
                              - completed
                              - failed
                              - rate_limited
                            id:
                              type: string
                            output:
                              type:
                              - string
                              - 'null'
                            json:
                              type:
                              - object
                              - 'null'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Empty batch or over the item limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Batch
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            endUserMessage:
              type: string
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key