Invoice Data Extraction Credits API

openapi: 3.2.0
info:
  title: Invoice Data Extraction Credits API
  version: 1.0.0
  summary: Turn invoices and other financial documents into structured rows and spreadsheets.
  description: 'Upload files, submit an extraction that says in plain words what to extract, wait for it

    to finish, and read the rows as JSON or download an XLSX, CSV or JSON file. An extraction

    submitted with `options.ask_questions` can stop and ask when the documents leave something

    unsettled; the caller answers and the extraction continues.


    This document is the contract as the API enforces it. The prose reference, with the same

    facts told in order, is https://invoicedataextraction.com/docs/api (Markdown:

    https://invoicedataextraction.com/docs/api.md). What changed and when, and how the API is

    versioned, is https://invoicedataextraction.com/docs/changelog. A guide for AI agents and the

    people directing them is https://invoicedataextraction.com/docs/agents.


    Every request may carry `X-SDK-Name` (up to 32 characters) naming the client it comes from,

    and `X-SDK-Version` with its version; the official SDKs send `node` and `python`.'
  termsOfService: https://invoicedataextraction.com/terms-of-service
  contact:
    name: Invoice Data Extraction support
    email: support@invoicedataextraction.com
    url: https://invoicedataextraction.com/contact
servers:
- url: https://api.invoicedataextraction.com/v1
security:
- bearerAuth: []
tags:
- name: Credits
  description: The account's credit balance.
paths:
  /credits/balance:
    get:
      tags:
      - Credits
      operationId: getCreditsBalance
      summary: Get the credit balance
      description: 'The account''s total credit balance and the credits reserved by extractions in

        progress. The usable balance is `credits_balance` minus `credits_reserved`. Costs

        nothing, so it is the call to verify a new key with.


        Rate limit: 60 requests per minute per API key.'
      responses:
        '200':
          description: The balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditsBalanceResponse'
              example:
                success: true
                credits_balance: 150
                credits_reserved: 10
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  responses:
    InternalError:
      description: '`INTERNAL_ERROR`: retry after a short delay.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Unauthenticated:
      description: '`UNAUTHENTICATED`, `API_KEY_EXPIRED` or `API_KEY_REVOKED`.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    RateLimited:
      description: '`RATE_LIMITED`: wait `details.retry_after_seconds` (also the `Retry-After` header), then retry.'
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  schemas:
    CreditsBalanceResponse:
      type: object
      required:
      - success
      - credits_balance
      - credits_reserved
      properties:
        success:
          type: boolean
          const: true
        credits_balance:
          type: integer
          description: Total balance, paid and free credits together.
        credits_reserved:
          type: integer
          description: Held by extractions in progress; up to this much is deducted when they complete.
    ErrorEnvelope:
      type: object
      required:
      - success
      - error
      properties:
        success:
          type: boolean
          const: false
        error:
          $ref: '#/components/schemas/ErrorObject'
    ErrorCode:
      type: string
      description: The codes an error envelope can carry, from any endpoint.
      enum:
      - UNAUTHENTICATED
      - API_KEY_EXPIRED
      - API_KEY_REVOKED
      - INVALID_INPUT
      - EXTRACTION_NOT_FOUND
      - INTERNAL_ERROR
      - SUBMISSIONS_PAUSED
      - SUBMISSION_ID_ALREADY_USED
      - DUPLICATE_FILE_NAME
      - DUPLICATE_FILE_ID
      - FILE_TOO_LARGE
      - TOTAL_UPLOAD_SIZE_LIMIT_EXCEEDED
      - SESSION_ALREADY_INITIALIZED
      - FILE_NOT_FOUND
      - FILE_NOT_UPLOADABLE
      - FILE_ABORTED
      - INVALID_COMPLETION_PARTS
      - OBJECT_SIZE_MISMATCH
      - UPLOAD_ID_NOT_FOUND
      - INSUFFICIENT_CREDITS
      - UPLOAD_COMPLETE_FAILED
      - OUTPUT_NOT_AVAILABLE
      - OUTPUT_EXPIRED
      - EXTRACTION_IN_PROGRESS
      - EXTRACTION_NOT_CANCELLABLE
      - NOT_FOUND
      - FORBIDDEN
      - RATE_LIMITED
    ErrorObject:
      type: object
      required:
      - code
      - message
      - retryable
      - details
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
          description: What happened and what to do next, in plain words.
        retryable:
          type: boolean
          description: '`true` when the same request may succeed after a short delay; `false` when the request itself must change.'
        details:
          description: 'Always present: `null`, or an object with error-specific context. `INVALID_INPUT` carries `issues`, each with a `message` and a `path`; `RATE_LIMITED` carries `retry_after_seconds`.'
          oneOf:
          - type: object
            additionalProperties: true
          - type: 'null'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'An API key created at https://invoicedataextraction.com/dashboard?view=API, sent as `Authorization: Bearer YOUR_API_KEY`. Every account includes 50 free pages a month. A team admin''s key sees the team''s extractions by default (the `scope` parameter).'
externalDocs:
  description: REST API reference
  url: https://invoicedataextraction.com/docs/api