answerline-dev Credits API

openapi: 3.2.0
info:
  title: Answerline Credits API
  description: 'Answerline tracks how AI assistants and search engines answer, across engines and regions. Each request comes back as structured JSON holding the engine''s answer: the parsed text, its cited sources and whatever else the engine returned with them, geo-targeted to a country you choose (which countries are available depends on the engine; see coverage).


    ## Authentication


    Pass your API key in the header `Authorization: Bearer `. You can create keys yourself at https://dashboard.answerline.dev/keys, and each new account starts with free requests, no card needed. A single key works for all endpoints; keys cannot currently be limited to particular scopes.


    ## Versioning and deprecation


    The URL path carries the version. All endpoints sit under `/v1/`; no header or query parameter selects a version.


    Changes inside a version only add things: new endpoints, optional request fields and response fields may be introduced at any moment. Clients have to skip response fields they don''t know. Anything breaking ships under a new path (`/v2/`) and never replaces an existing version.


    Deprecation is announced in the endpoint''s responses themselves, not just in a changelog: the `Deprecation` header (RFC 9745) gives the date it became deprecated, `Sunset` (RFC 8594) gives the date it will stop answering, and the replacement is given by a `Link` header carrying `rel="deprecation"`. For generally available endpoints, those two dates are at least six months apart. No endpoint is currently deprecated.


    ## Rate limits


    There is no per-account request rate limit and no cap on how many requests run at once. Each response still carries `X-RateLimit-Limit` and `X-RateLimit-Remaining` for clients that read them: both are deprecated and always 100000, meaning no limit. The concurrency and USD balance headers report your account''s state. Your async queue is bounded only by the memory its tasks take: a submission that does not fit is refused whole with `QUEUE_LIMIT_EXCEEDED`, whose details say how many more tasks of that size fit. A synchronous call that cannot start now is refused with `CONCURRENT_LIMIT_EXCEEDED`, which goes away once your running jobs complete. `Retry-After` is set only on `SERVICE_OVERLOADED` and on a `RATE_LIMIT_EXCEEDED` sent because one address presented too many unknown keys. No IETF `RateLimit-*` headers are sent.


    ## Errors


    All 4xx and 5xx responses share the `Error` envelope: `{ "error": { "code", "message", "details", "timestamp" } }`, except validation errors, which use `{ "success": false, "error", "details": [{ "field", "message" }] }`. Clients should branch on `code`, a stable identifier meant for machines; `message` is meant for people reading logs.'
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  version: 1.0.0
  contact:
    name: answerline support
    email: support@answerline.dev
  termsOfService: https://answerline.dev/legal/terms
servers:
- url: https://api.answerline.dev
  description: Production server
security:
- bearerAuth: []
tags:
- name: Credits
paths:
  /v1/credits:
    get:
      summary: Read the account balance
      description: Get the USD balance currently on your organization's account. This lets you check the balance from code — even for workloads that only use async — without sending a sync /v1/monitor/* request merely to read the X-Credits-Remaining header. The definitive check still happens at the time each task is billed.
      operationId: getCredits
      security:
      - bearerAuth: []
      responses:
        '200':
          description: The USD balance as of now.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditsResponse'
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
        '401':
          description: Unauthorized - authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '429':
          description: Too Many Requests - the service dropped the request because it was overloaded (`SERVICE_OVERLOADED`), which returns `Retry-After` without any limit headers, or one address presented too many unknown keys (`RATE_LIMIT_EXCEEDED`, with `Retry-After`)
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
      tags:
      - Credits
components:
  headers:
    XRateLimitLimit:
      description: 'Deprecated: there is no per-account request rate limit. Always 100000, meaning no limit; kept for clients that read it.'
      deprecated: true
      schema:
        type: integer
        example: 100000
    XRateLimitRemaining:
      description: 'Deprecated: there is no per-account request rate limit, so nothing counts down. Always 100000, the same as `X-RateLimit-Limit`.'
      deprecated: true
      schema:
        type: integer
        example: 100000
  schemas:
    CreditsResponse:
      type: object
      required:
      - remaining
      - perCycle
      - cycleResetsAt
      properties:
        remaining:
          type: number
          description: 'USD you can still spend: the balance less what open tasks hold back.'
          example: 12.34
        perCycle:
          type: integer
          nullable: true
          description: 'Always null: balances do not reset.'
          example: null
        cycleResetsAt:
          type: string
          format: date-time
          nullable: true
          description: 'Always null: balances do not reset.'
          example: null
    AuthenticationError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
              - MISSING_API_KEY
              - INVALID_API_KEY_FORMAT
              - INVALID_OR_EXPIRED_API_KEY
              example: MISSING_API_KEY
            message:
              type: string
              example: API key is missing or not valid
            timestamp:
              type: string
              format: date-time
              example: '2025-01-15T12:00:00.000Z'
    RateLimitError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: RATE_LIMIT_EXCEEDED
            message:
              type: string
              example: Too many requests for this API key
            timestamp:
              type: string
              format: date-time
              example: '2025-01-15T12:00:00.000Z'
    InternalError:
      type: object
      oneOf:
      - properties:
          success:
            type: boolean
            example: false
          error:
            type: string
            example: Maximum retries exceeded
      - properties:
          error:
            type: object
            properties:
              code:
                type: string
                example: INTERNAL_SERVER_ERROR
              message:
                type: string
                example: Internal server error
              timestamp:
                type: string
                format: date-time
                example: '2025-01-15T12:00:00.000Z'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Answerline API key sent as a bearer token. A single key gives access to all endpoints in this spec; keys cannot be scoped, so clients have no way to ask for narrower permissions. Create, rotate, and revoke keys at https://dashboard.answerline.dev/keys. See https://answerline.dev/docs/authentication for more, which also covers the versioning and deprecation policy.