openapi: 3.2.0
info:
  title: SchemaExtract Extract API
  version: 0.2.0
  description: Schema-driven document to JSON extraction. Upload a PDF or image plus a JSON schema (or preset) and receive structured data. Files are processed in memory and discarded after the response.
servers:
- url: /
  description: This deployment
security:
- bearerAuth: []
- {}
tags:
- name: Extract
paths:
  /v1/extract:
    post:
      operationId: extractDocument
      summary: Extract structured JSON from a document
      description: 'Accepts multipart form-data (`file` + `schema`) or a JSON body (`file_base64` + `schema`). Optionally pass `preset` as invoice | packing_list | bank_statement | bol. When AUTH_SECRET is set and DEMO_MODE is not true, send Authorization: Bearer sk_live_…'
      parameters:
      - name: preset
        in: query
        required: false
        schema:
          type: string
          enum:
          - invoice
          - packing_list
          - bank_statement
          - bol
        description: Use a built-in schema when `schema` is omitted.
      - name: include_raw_text
        in: query
        required: false
        schema:
          type: boolean
        description: Include extracted PDF text in meta.raw_text.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                schema:
                  type: string
                  description: JSON schema or example object, as a string.
                preset:
                  type: string
                  enum:
                  - invoice
                  - packing_list
                  - bank_statement
                  - bol
                include_raw_text:
                  type: boolean
              required:
              - file
          application/json:
            schema:
              type: object
              properties:
                schema:
                  type: object
                file_base64:
                  type: string
                filename:
                  type: string
                mime:
                  type: string
                preset:
                  type: string
                  enum:
                  - invoice
                  - packing_list
                  - bank_statement
                  - bol
                include_raw_text:
                  type: boolean
              required:
              - file_base64
      responses:
        '200':
          description: Extraction succeeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractSuccess'
        '400':
          description: Invalid schema, preset, or request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractError'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractError'
        '402':
          description: Monthly quota exceeded (upgrade)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractError'
        '413':
          description: File too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractError'
        '415':
          description: Unsupported file type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractError'
        '429':
          description: Burst rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractError'
        '502':
          description: Upstream model failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractError'
      tags:
      - Extract
components:
  schemas:
    ExtractError:
      type: object
      required:
      - ok
      - error
      properties:
        ok:
          type: boolean
          enum:
          - false
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              enum:
              - BAD_REQUEST
              - INVALID_JSON
              - INVALID_SCHEMA
              - SCHEMA_TOO_LARGE
              - INVALID_PRESET
              - MISSING_FILE
              - UNSUPPORTED_FILE
              - FILE_TOO_LARGE
              - MODEL_FAILURE
              - RATE_LIMITED
              - UNAUTHORIZED
              - PAYMENT_REQUIRED
              - QUOTA_EXCEEDED
            message:
              type: string
    ExtractSuccess:
      type: object
      required:
      - ok
      - data
      - meta
      properties:
        ok:
          type: boolean
          enum:
          - true
        data:
          type: object
          additionalProperties: true
        meta:
          type: object
          properties:
            model:
              type: string
            pages:
              type: integer
            preset:
              type: string
              nullable: true
            filename:
              type: string
            mode:
              type: string
              enum:
              - mock
              - openai
              - anthropic
              - ollama
            warnings:
              type: array
              items:
                type: string
            vision_pages:
              type: integer
            raw_text:
              type: string
            plan:
              type: string
            quota_remaining:
              type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: sk_live_