AuditAE Citations API

openapi: 3.2.0
info:
  title: AuditAE REST Citations 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: Citations
  description: Run prompts on answer engines and read the results.
paths:
  /api/v1/check:
    post:
      operationId: checkCitation
      summary: Check one prompt across engines
      description: Asks each engine one prompt and reports whether the brand is cited. Runs synchronously within about 40 seconds. Each answered engine is one check; after the checks AuditAE writes a fix-it playbook for each answered check that didn't cite the brand, billed on LLM usage (about 12¢ each), plus about 45¢ for the audit rollup, some of it later (charged_cents covers what billed in the call). Needs at least 5¢ of credit to start.
      tags:
      - Citations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - brand
              - domain
              - prompt
              properties:
                brand:
                  type: string
                  minLength: 1
                domain:
                  type: string
                  minLength: 1
                  examples:
                  - example.com
                prompt:
                  type: string
                  minLength: 1
                engines:
                  type: array
                  items:
                    $ref: '#/components/schemas/Engine'
                  minItems: 1
                  description: Engines to run. Omit for the defaults (chatgpt, perplexity, gemini, ai-overviews). Unknown names are dropped.
            example:
              brand: Acme
              domain: acme.com
              prompt: best project management tool for agencies
              engines:
              - chatgpt
              - perplexity
      responses:
        '200':
          description: Per-engine results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/WorkspaceUnfunded'
        '429':
          description: The workspace already has its maximum audits running (nothing started, nothing billed); retry in a minute. Or rate limited (see RateLimited).
          headers:
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/RateLimited'
                - $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/ServerError'
      x-auditae-auth: paid
      x-auditae-price: 'Per engine: Perplexity 5¢, ChatGPT 7¢, Google AI Overviews 9¢, Google AI Mode 10¢ (opt-in), Gemini 12¢; plus the fix-it playbook, about 12¢ per answered check that didn''t cite the brand and about 45¢ per audit'
  /api/v1/audits:
    post:
      operationId: createAudit
      summary: Run an audit
      description: 'Runs every prompt × engine cell synchronously (up to 300 seconds) and returns the results. When the workspace already has its maximum audits running, the audit is queued instead: 202, then poll GET /api/v1/audits/{id}. Each answered cell is billed as one check; after the checks AuditAE writes a fix-it playbook for each answered check that didn''t cite the brand, billed on LLM usage (about 12¢ each), plus about 45¢ for the audit rollup. charged_cents is what the run billed.'
      tags:
      - Citations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - brand
              - domain
              - prompts
              properties:
                brand:
                  type: string
                  minLength: 1
                domain:
                  type: string
                  minLength: 1
                prompts:
                  type: array
                  items:
                    type: string
                    minLength: 1
                  minItems: 1
                  maxItems: 10
                engines:
                  type: array
                  items:
                    $ref: '#/components/schemas/Engine'
                  minItems: 1
                  description: Engines to run. Omit for the defaults (chatgpt, perplexity, gemini, ai-overviews). Unknown names are dropped.
                competitor_domains:
                  type: array
                  items:
                    type: string
            example:
              brand: Acme
              domain: acme.com
              prompts:
              - best project management tool for agencies
              competitor_domains:
              - asana.com
      responses:
        '200':
          description: The finished run.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/RunResult'
                - type: object
                  required:
                  - report_url
                  properties:
                    report_url:
                      type:
                      - string
                      - 'null'
                      format: uri
                      description: Shareable report, once any cell completed.
        '202':
          description: Queued; starts when a slot opens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueuedAudit'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/WorkspaceUnfunded'
        '429':
          description: The workspace is busy. Or rate limited (see RateLimited).
          headers:
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/RateLimited'
                - $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/ServerError'
      x-auditae-auth: paid
      x-auditae-price: 'Per prompt × engine: Perplexity 5¢, ChatGPT 7¢, Google AI Overviews 9¢, Google AI Mode 10¢ (opt-in), Gemini 12¢; plus the fix-it playbook, about 12¢ per answered check that didn''t cite the brand and about 45¢ per audit'
  /api/v1/audits/{id}:
    get:
      operationId: getAudit
      summary: Get an audit
      description: Fetches an audit this key's workspace ran, with every cell. Works at a zero balance.
      tags:
      - Citations
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The audit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Audit'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/WorkspaceUnfunded'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
      x-auditae-auth: any
      x-auditae-price: Free
components:
  responses:
    NotFound:
      description: Not found in this key's workspace.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: Something failed on our side. Safe to retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    WorkspaceUnfunded:
      description: The key belongs to an agent workspace (created on /api/mcp/pay) that has never been funded. Until it is, the key works only on /api/mcp/pay and the two billing routes (GET /api/v1/billing, POST /api/v1/billing/top-up). Fund it with the `top_up` request, then retry with the same key.
      content:
        application/json:
          schema:
            type: object
            required:
            - error
            - code
            - top_up
            properties:
              error:
                type: string
              code:
                type: string
                const: workspace_unfunded
              top_up:
                $ref: '#/components/schemas/TopUpRequest'
    PaymentRequired:
      description: Not enough credit. The body says how much is short and how to top up.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaymentRequired'
          example:
            error: Insufficient credits
            balance_cents: 0
            required_cents: 5
            top_up:
              method: POST
              url: https://auditae.app/api/v1/billing/top-up
              body:
                amount_usd: 5
              min_usd: 5
              max_usd: 1000
              note: Returns a Stripe Checkout URL. Give it to the account owner to pay; credit lands within seconds.
            top_up_url: https://auditae.app/dashboard/billing
    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'
    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'
  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"
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Human-readable reason.
      additionalProperties: true
    AuditPromptResult:
      type: object
      description: One prompt × engine cell.
      required:
      - engine
      - prompt
      - status
      - brand_mentioned
      - brand_url_cited
      - position
      - competitors
      - sources
      - sentiment
      - was_cache_hit
      - latency_ms
      - error_message
      properties:
        engine:
          $ref: '#/components/schemas/Engine'
        prompt:
          type: string
        status:
          type: string
          enum:
          - success
          - rate_limited
          - timeout
          - parse_error
          - api_error
        brand_mentioned:
          type: boolean
          description: The answer's text names the brand.
        brand_url_cited:
          type: boolean
          description: The brand's domain is among the answer's cited sources. Citation rate counts this.
        position:
          type:
          - integer
          - 'null'
        competitors:
          type: array
          items:
            type: string
        sources:
          type: array
          items:
            $ref: '#/components/schemas/AuditPromptSource'
        sentiment:
          type:
          - string
          - 'null'
          enum:
          - positive
          - neutral
          - negative
          - null
        was_cache_hit:
          type: boolean
        latency_ms:
          type: integer
        error_message:
          type:
          - string
          - 'null'
    PaymentRequired:
      type: object
      description: The balance can't cover the call. Top up with the `top_up` request (it returns a Stripe Checkout URL for the account owner), then retry.
      required:
      - error
      - balance_cents
      - required_cents
      - top_up
      - top_up_url
      properties:
        error:
          type: string
        balance_cents:
          type: integer
        required_cents:
          type: integer
          description: Credit this call needs, in cents.
        top_up:
          $ref: '#/components/schemas/TopUpRequest'
        top_up_url:
          type: string
          format: uri
          description: The billing page, for a person.
    RunResult:
      type: object
      required:
      - audit_id
      - results
      - citation_rate
      - completed
      - total
      - partial
      - out_of_credits
      properties:
        audit_id:
          type: string
          format: uuid
        results:
          type: array
          items:
            $ref: '#/components/schemas/AuditPromptResult'
        citation_rate:
          type: number
          description: Share of answered cells that cite the brand's URL, 0–1.
        completed:
          type: integer
          description: Cells that finished.
        total:
          type: integer
          description: Cells requested (prompts × engines).
        partial:
          type: boolean
          description: True when some cells didn't finish or failed.
        out_of_credits:
          type: boolean
          description: True when the run stopped because the balance ran out.
        charged_cents:
          type:
          - integer
          - 'null'
          description: 'What the run billed so far: its checks plus the fix-it playbook written in the call. null when the ledger couldn''t be read.'
        charged_breakdown_cents:
          type:
          - object
          - 'null'
          properties:
            checks:
              type: integer
            playbook:
              type: integer
    QueuedAudit:
      type: object
      required:
      - audit_id
      - status
      - message
      properties:
        audit_id:
          type: string
          format: uuid
        status:
          type: string
          const: queued
        message:
          type: string
    Audit:
      type: object
      description: A stored audit. Field names are camelCase here, unlike the snake_case POST responses.
      required:
      - id
      - brand
      - domain
      - competitorDomains
      - prompts
      - engines
      - createdAt
      - status
      - citationRate
      - visibilityScore
      - clickValue
      - results
      - publicShareId
      - reportUrl
      properties:
        id:
          type: string
          format: uuid
        brand:
          type: string
        domain:
          type: string
        competitorDomains:
          type: array
          items:
            type: string
        prompts:
          type: array
          items:
            type: string
        engines:
          type: array
          items:
            $ref: '#/components/schemas/Engine'
        createdAt:
          type: string
          format: date-time
        status:
          type: string
          enum:
          - queued
          - running
          - complete
          - failed
        citationRate:
          type: number
        visibilityScore:
          type:
          - number
          - 'null'
          description: AI Visibility Score, 0–100.
        clickValue:
          type:
          - object
          - 'null'
          description: Google Ads value of the prompts' keywords, in USD cents.
          additionalProperties: true
        results:
          type: array
          items:
            $ref: '#/components/schemas/AuditResult'
        publicShareId:
          type:
          - string
          - 'null'
        failureReason:
          type:
          - string
          - 'null'
          description: Why the run stopped short, when it did.
        reportUrl:
          type:
          - string
          - 'null'
          format: uri
          description: Shareable report link once the audit is complete.
    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¢.'
    TopUpRequest:
      type: object
      description: 'The top-up call to make as-is: it returns a Stripe Checkout URL for the account owner.'
      required:
      - method
      - url
      - body
      - min_usd
      - max_usd
      - note
      properties:
        method:
          type: string
          const: POST
        url:
          type: string
          format: uri
          description: POST /api/v1/billing/top-up on this host.
        body:
          type: object
          required:
          - amount_usd
          properties:
            amount_usd:
              type: integer
              minimum: 5
              maximum: 1000
              description: 'Suggested amount: the shortfall rounded up to whole dollars, within the top-up limits.'
        min_usd:
          type: integer
          const: 5
        max_usd:
          type: integer
          const: 1000
        note:
          type: string
    AuditPromptSource:
      type: object
      required:
      - url
      - title
      properties:
        url:
          type: string
        title:
          type:
          - string
          - 'null'
        resolved_host:
          type:
          - string
          - 'null'
          description: Real host behind an opaque redirect URL, when recovered.
    AuditResult:
      type: object
      description: One stored cell, in the camelCase the audit store uses.
      required:
      - prompt
      - engine
      - brandMentioned
      - brandUrlCited
      - position
      - sourcesReferenced
      - competitors
      - sentiment
      - excerpt
      properties:
        prompt:
          type: string
        engine:
          $ref: '#/components/schemas/Engine'
        brandMentioned:
          type: boolean
        brandUrlCited:
          type: boolean
        position:
          type:
          - integer
          - 'null'
        sourcesReferenced:
          type: array
          items:
            type: string
        competitors:
          type: array
          items:
            type: string
        sentiment:
          type: string
          enum:
          - positive
          - neutral
          - negative
          - n/a
        excerpt:
          type: string
        engineStatus:
          type: string
          enum:
          - success
          - rate_limited
          - timeout
          - parse_error
          - api_error
        errorMessage:
          type:
          - string
          - 'null'
    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).
  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