answerline-dev States API

openapi: 3.2.0
info:
  title: Answerline States 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: States
paths:
  /v1/states:
    get:
      summary: Array of states
      description: 'Lists US state codes usable for state-level geo-targeting. `state` is served for Gemini only; ChatGPT, Copilot, Perplexity and Grok refuse it with a 400, uncharged. "DC" is listed but fails uncharged: no exit serves it. States exist only for the US; any other country value yields an empty array.'
      operationId: getStates
      parameters:
      - name: country
        in: query
        required: true
        description: Country as an ISO 3166-1 alpha-2 code. Results are available only for "US".
        schema:
          type: string
          minLength: 2
          maxLength: 2
          pattern: ^[A-Z]{2}$
        example: US
      responses:
        '200':
          description: States that are supported
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    code:
                      type: string
                      description: Two-letter state abbreviation as defined by USPS
                      example: CA
                    name:
                      type: string
                      description: State name written out in full
                      example: California
                  required:
                  - code
                  - name
                example:
                - code: AL
                  name: Alabama
                - code: AK
                  name: Alaska
                - code: AZ
                  name: Arizona
                - code: CA
                  name: California
                - code: DC
                  name: District of Columbia
                - code: NY
                  name: New York
                - code: TX
                  name: Texas
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
        '400':
          description: Bad Request — country parameter absent or not valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '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:
      - States
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:
    ValidationError:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          example: Request validation failed
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
                example: prompt
              message:
                type: string
                example: Prompt must not be empty
    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.