AuditAE Billing API

openapi: 3.2.0
info:
  title: AuditAE REST Billing API
  version: '1'
  description: 'Check whether AI answer engines (ChatGPT, Perplexity, Gemini, Google AI Overviews and AI Mode) cite a brand, crawl a site, and generate or validate schema.org JSON-LD. Prepaid credit: paid calls draw from the workspace balance, free calls never do. When the balance is too low, a paid call answers 402 with a `top_up` request (POST /api/v1/billing/top-up). Authenticate with an ae_live_… key from https://auditae.app/dashboard/keys. The same tools are on the MCP server at https://auditae.app/api/mcp.'
  contact:
    name: AuditAE support
    email: support@auditae.app
    url: https://auditae.app/docs/api
servers:
- url: https://auditae.app
security:
- bearerAuth: []
tags:
- name: Billing
  description: Balance, prices and top-ups.
paths:
  /api/v1/billing:
    get:
      operationId: getBilling
      summary: Get balance and prices
      description: Balance, per-engine check prices, estimated checks left and auto-refill status. Works at a zero balance.
      tags:
      - Billing
      responses:
        '200':
          description: Billing state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingState'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
      x-auditae-auth: any
      x-auditae-price: Free
  /api/v1/billing/top-up:
    post:
      operationId: topUp
      summary: Add credit
      description: Without a token, returns a Stripe Checkout URL for the account owner to pay. With a Stripe shared payment token (spt_…), charges it now and credits the workspace in the same request.
      tags:
      - Billing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - amount_usd
              properties:
                amount_usd:
                  type: integer
                  minimum: 5
                  maximum: 1000
                shared_payment_token:
                  type: string
                  pattern: ^spt_
                  description: Stripe shared payment token to charge now.
            example:
              amount_usd: 10
      responses:
        '200':
          description: A Checkout link, or the completed payment.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/TopUpCheckout'
                - $ref: '#/components/schemas/TopUpPaid'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: The payment token was declined, expired or deactivated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          description: Stripe didn't answer as expected. Check GET /api/v1/billing before paying again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-auditae-auth: any
      x-auditae-price: Free; adds $5–$1,000 of credit
components:
  schemas:
    Engine:
      type: string
      enum:
      - chatgpt
      - perplexity
      - gemini
      - ai-overviews
      - ai-mode
      description: 'Answer engine. ai-mode is opt-in. Check prices: Perplexity 5¢, ChatGPT 7¢, Google AI Overviews 9¢, Google AI Mode 10¢ (opt-in), Gemini 12¢.'
    TopUpCheckout:
      type: object
      required:
      - checkout_url
      - amount_usd
      - expires_at
      - next_step
      properties:
        checkout_url:
          type: string
          format: uri
          description: Stripe Checkout page for the account owner to pay.
        amount_usd:
          type: integer
        expires_at:
          type: string
          format: date-time
          description: When the Checkout link expires.
        next_step:
          type: string
    BillingState:
      type: object
      required:
      - balance_cents
      - balance_usd
      - prices_cents_per_check
      - estimated_checks_left
      - auto_refill
      - billing_url
      properties:
        balance_cents:
          type: integer
        balance_usd:
          type: string
          examples:
          - '12.40'
        available_cents:
          type: integer
          description: 'What a new paid run can use now: the balance less credit held by runs in flight. estimated_checks_left is based on it.'
        prices_cents_per_check:
          type: object
          propertyNames:
            $ref: '#/components/schemas/Engine'
          additionalProperties:
            type: integer
        estimated_checks_left:
          type: object
          propertyNames:
            $ref: '#/components/schemas/Engine'
          additionalProperties:
            type: integer
        auto_refill:
          type:
          - object
          - 'null'
          required:
          - enabled
          - has_card
          - amount_cents
          - threshold_cents
          - monthly_cap_cents
          - cap_reached_this_month
          properties:
            enabled:
              type: boolean
            has_card:
              type: boolean
            amount_cents:
              type: integer
            threshold_cents:
              type: integer
            monthly_cap_cents:
              type: integer
            cap_reached_this_month:
              type: boolean
        billing_url:
          type:
          - string
          - 'null'
          format: uri
          description: 'null for an agent workspace (no login): fund it with POST /api/v1/billing/top-up.'
        free_today:
          type: object
          description: Today's (UTC) use of the daily free allowances and what each further call costs. A counter that can't be read is left out; google_data only for a workspace with a login.
          properties:
            google_data:
              $ref: '#/components/schemas/FreeAllowance'
            technical_audit:
              $ref: '#/components/schemas/FreeAllowance'
    TopUpPaid:
      type: object
      required:
      - paid_usd
      - payment_id
      - balance_cents
      - credit_status
      properties:
        paid_usd:
          type: number
        payment_id:
          type: string
        balance_cents:
          type:
          - integer
          - 'null'
          description: New balance; null while the credit is pending.
        credit_status:
          type: string
          enum:
          - applied
          - pending
        note:
          type: string
          description: Present when pending. Don't pay again.
    FreeAllowance:
      type: object
      required:
      - used
      - of
      - then_cents
      properties:
        used:
          type: integer
        of:
          type: integer
          description: Free calls (or pages) a day.
        then_cents:
          type: integer
          description: Price of each one past the free allowance.
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Human-readable reason.
      additionalProperties: true
    RateLimited:
      type: object
      required:
      - error
      - retry_after
      properties:
        error:
          type: string
          const: rate_limited
        retry_after:
          type: integer
          minimum: 0
          description: Seconds to wait. Also sent as the Retry-After header.
        message:
          type: string
          description: Which limit was hit, when the route says (e.g. a per-site limit).
  responses:
    RateLimited:
      description: 'Too many requests: 60 per 60s per key, and 30 failed authentications per 60s per IP.'
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimited'
    ServerError:
      description: Something failed on our side. Safe to retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The body is missing a field or has a bad value.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing, invalid or revoked key.
      headers:
        WWW-Authenticate:
          $ref: '#/components/headers/WWW-Authenticate'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  headers:
    Retry-After:
      description: Seconds to wait before retrying.
      schema:
        type: integer
    WWW-Authenticate:
      description: Bearer challenge.
      schema:
        type: string
        examples:
        - Bearer realm="auditae-v1"
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An ae_live_… key from https://auditae.app/dashboard/keys. The same key works with the MCP server at https://auditae.app/api/mcp.
externalDocs:
  url: https://auditae.app/docs/api
  description: REST API and API keys
x-service-info:
  categories:
  - ai
  - seo
  - marketing
  docs:
    homepage: https://auditae.app
    apiReference: https://auditae.app/docs/api
    llms: https://auditae.app/llms.txt