openapi: 3.2.0
info:
  title: SchemaSure — structured extraction Image extraction · x402…
  version: 0.2.0
  summary: Turn messy text, HTML, or document images into guaranteed schema-valid JSON, or pay nothing. SchemaSure V2 is the primary production API.
  description: Pay-per-call APIs that extract strict, JSON-Schema-valid typed JSON from unstructured text, HTML, or document images.
  contact:
    name: SchemaSure
    url: https://schemasure.com
servers:
- url: https://schemasure.com
tags:
- name: Image extraction · x402 V2
paths:
  /v2/extract-image:
    post:
      operationId: extract_image_to_schema
      tags:
      - Image extraction · x402 V2
      summary: Extract schema-valid JSON from a document image with x402 V2
      description: Always paid from the first call, with no V1 or free image route. Send base64-encoded PNG, JPEG, or WebP bytes plus a JSON Schema. Decode the PAYMENT-REQUIRED response header, sign the live terms, and retry the identical request with PAYMENT-SIGNATURE. The server verifies first and settles only after producing schema-valid JSON. Image bytes are processed transiently and are not persisted by SchemaSure.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageExtractRequest'
            example:
              image:
                data: <base64-encoded PNG, JPEG, or WebP bytes>
                mimeType: image/png
              schema:
                type: object
                additionalProperties: false
                required:
                - invoiceNumber
                - vendor
                - total
                properties:
                  invoiceNumber:
                    type: string
                    description: Invoice identifier exactly as printed.
                  vendor:
                    type: string
                  total:
                    type: number
                    description: Final amount due as a number, without currency symbols.
      responses:
        '200':
          description: Schema-valid extraction. Paid responses include PAYMENT-RESPONSE.
          headers:
            X-Request-ID:
              description: Correlation identifier to include when contacting support.
              schema:
                type: string
                format: uuid
            PAYMENT-RESPONSE:
              description: Base64-encoded x402 settlement receipt.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractSuccess'
              example:
                data:
                  invoiceNumber: INV-2048
                  vendor: Northstar Supplies
                  total: 382.45
                meta:
                  repairs: 0
                  latencyMs: 910
                  validated: true
        '400':
          description: Bad request, unsupported input, invalid JSON Schema, or decoded input too large; fix before retrying. Not settled.
          headers:
            X-Request-ID:
              description: Correlation identifier to include when contacting support.
              schema:
                type: string
                format: uuid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Payment required or invalid. Decode PAYMENT-REQUIRED, sign, and retry with PAYMENT-SIGNATURE.
          headers:
            X-Request-ID:
              description: Correlation identifier to include when contacting support.
              schema:
                type: string
                format: uuid
            PAYMENT-REQUIRED:
              required: true
              description: Base64-encoded x402 V2 PaymentRequired object, including Bazaar metadata.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: Encoded HTTP request body is too large; reduce it before retrying. Not settled.
          headers:
            X-Request-ID:
              description: Correlation identifier to include when contacting support.
              schema:
                type: string
                format: uuid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Could not produce schema-valid output; change the input/schema or use a fallback. Not settled.
          headers:
            X-Request-ID:
              description: Correlation identifier to include when contacting support.
              schema:
                type: string
                format: uuid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited. Wait for Retry-After before retrying. Not settled.
          headers:
            X-Request-ID:
              description: Correlation identifier to include when contacting support.
              schema:
                type: string
                format: uuid
            Retry-After:
              description: Seconds until a retry is allowed.
              schema:
                type: integer
                minimum: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Unexpected server error. Retry once with backoff, then report X-Request-ID. Not settled.
          headers:
            X-Request-ID:
              description: Correlation identifier to include when contacting support.
              schema:
                type: string
                format: uuid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: Inference or payment upstream unavailable. Retry with bounded exponential backoff. Not settled.
          headers:
            X-Request-ID:
              description: Correlation identifier to include when contacting support.
              schema:
                type: string
                format: uuid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '504':
          description: Extraction timed out. Retry with bounded exponential backoff. Not settled.
          headers:
            X-Request-ID:
              description: Correlation identifier to include when contacting support.
              schema:
                type: string
                format: uuid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-x402-flow:
        initialResponse: 402 + PAYMENT-REQUIRED
        retryHeader: PAYMENT-SIGNATURE
        successHeader: PAYMENT-RESPONSE
        network: eip155:8453
      x-image:
        acceptedMimeTypes:
        - image/png
        - image/jpeg
        - image/webp
        maxDecodedBytes: 8388608
        encoding: base64
components:
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              enum:
              - BAD_REQUEST
              - INVALID_SCHEMA
              - INPUT_TOO_LARGE
              - UNSUPPORTED_INPUT_TYPE
              - FETCH_BLOCKED
              - EXTRACTION_FAILED
              - VALIDATION_FAILED
              - ABSTAINED
              - UPSTREAM_LLM_ERROR
              - TIMEOUT
              - RATE_LIMITED
              - PAYMENT_REQUIRED
              - PAYMENT_INVALID
              - PAYMENT_UPSTREAM
              - INTERNAL
            message:
              type: string
            details: {}
    ExtractSuccess:
      type: object
      required:
      - data
      - meta
      properties:
        data:
          description: Extracted value; guaranteed to validate against the request `schema`.
        meta:
          type: object
          required:
          - repairs
          - latencyMs
          - validated
          properties:
            repairs:
              type: integer
            latencyMs:
              type: integer
            validated:
              const: true
            deterministicFields:
              type: array
              items:
                type: string
    ImageExtractRequest:
      type: object
      additionalProperties: false
      required:
      - image
      - schema
      properties:
        image:
          type: object
          additionalProperties: false
          required:
          - data
          - mimeType
          properties:
            data:
              type: string
              minLength: 1
              contentEncoding: base64
              description: Base64-encoded image bytes without a data-URL prefix.
            mimeType:
              type: string
              enum:
              - image/png
              - image/jpeg
              - image/webp
              description: Declared image media type; it must match the decoded file signature.
        schema:
          type: object
          description: JSON Schema (draft 2020-12) that the returned `data` is guaranteed to satisfy.
        options:
          type: object
          additionalProperties: false
          properties:
            maxRepairs:
              type: integer
              minimum: 0
              maximum: 5
              description: Max validate->re-prompt repair iterations.
            strict:
              type: boolean
              default: true
              description: Drop fields not present in the schema.
externalDocs:
  description: SchemaSure agent integration guide
  url: https://schemasure.com/llms.txt
x-payment:
  protocol: x402
  version: 2
  primary: true
  scheme: exact
  network: eip155:8453
  asset: USDC
  assetAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
  priceUsd: 0.01
  chargeModel: charge-only-on-success
  alwaysPaid: true
  resource: https://schemasure.com/v2/extract
  resources:
  - kind: text
    resource: https://schemasure.com/v2/extract
    priceUsd: 0.01
  - kind: image
    resource: https://schemasure.com/v2/extract-image
    priceUsd: 0.03