AthenaHQ AI Access API

openapi: 3.2.0
info:
  title: AthenaHQ AI Access API
  description: AthenaHQ API provides programmatic access to manage your websites and prompts for AI-powered content optimization.
  version: 1.0.0
  contact:
    email: support@athenahq.ai
servers:
- url: https://api.athenahq.ai
  description: Production server
security:
- apiKey: []
tags:
- name: AI Access
paths:
  /api/v1/ai-access/check:
    post:
      tags:
      - AI Access
      summary: Check AI accessibility for a domain
      description: 'Check robots.txt policy and HTTP responses to crawler user-agent probes from Athena''s network. Use result.evidence and per-agent diagnostics; challenges, timeouts and server errors produce unknown observations. Search, retrieval and training are separate. These probes do not verify real crawler access or guarantee indexing or citations. Legacy status and booleans remain for compatibility.


        Rate limited to 30 requests per minute per organization.'
      operationId: checkAIAccess
      security:
      - apiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                domain:
                  type: string
                  description: The domain to probe (with or without protocol).
                  example: example.com
              required:
              - domain
      responses:
        '200':
          description: Successful AI access check.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AIAccessCheckResponse'
        '400':
          description: Invalid request body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized — invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      description: Error response object
      required:
      - error
      properties:
        error:
          type: string
          description: Error message describing what went wrong
          example: Unauthorized
    AIAccessUIBotAccess:
      type: object
      description: Per-model accessibility map. Keys map to the major answer engines.
      properties:
        chatgpt:
          $ref: '#/components/schemas/AIAccessBotDetails'
        claude:
          $ref: '#/components/schemas/AIAccessBotDetails'
        perplexity:
          $ref: '#/components/schemas/AIAccessBotDetails'
        gemini:
          $ref: '#/components/schemas/AIAccessBotDetails'
        copilot:
          $ref: '#/components/schemas/AIAccessBotDetails'
        grok:
          $ref: '#/components/schemas/AIAccessBotDetails'
        deepseek:
          $ref: '#/components/schemas/AIAccessBotDetails'
        rufus:
          $ref: '#/components/schemas/AIAccessBotDetails'
    AIAccessCheckResponse:
      type: object
      description: Successful AI access check response.
      properties:
        result:
          $ref: '#/components/schemas/AIAccessResult'
        diagnostics:
          $ref: '#/components/schemas/AIAccessDiagnostics'
        log:
          type: string
          description: Plain-text diagnostic log shaped for a host/CDN ticket. Identical to the string the AthenaHQ web app's `Copy log` button produces.
      required:
      - result
      - diagnostics
      - log
    AIAccessResult:
      type: object
      description: AI Access observations plus legacy compatibility fields. Use evidence and per-agent diagnostics for authoritative nullable results.
      properties:
        domain:
          type: string
          description: The domain that was probed.
        status:
          type: string
          enum:
          - accessible
          - partial
          - blocked
          description: Legacy rollup retained for compatibility. Use evidence.status to distinguish inconclusive checks.
        http:
          $ref: '#/components/schemas/AIAccessUIBotAccess'
          description: Legacy per-model booleans retained for compatibility. When Google-Extended has no HTTP observation, Gemini training uses the measured Googlebot response as a compatibility proxy, not proof of training access or permission. Use evidence.http for per-agent nullable observations and evidence.robots for independent policy.
        robots:
          $ref: '#/components/schemas/AIAccessUIBotAccess'
          description: Legacy per-model booleans retained for compatibility. Use evidence.robots for per-agent nullable observations and separate search/training.
        hasSitemap:
          type: boolean
          description: Optional independently verified sitemap result. The current AI Access probe does not check sitemaps and omits this field.
        checkedAt:
          type: string
          format: date-time
        error:
          type: string
          description: Populated only when both probes failed.
        evidence:
          type: object
          description: Authoritative observations. Requests originate from Athena, not verified crawler IP ranges. Null means unknown. ChatGPTUser is retrieval, OAISearchBot is search, GPTBot is training. GoogleExtended is a policy token with no HTTP crawler. Policies and HTTP observations are independent. No guarantee of indexing or citations.
          properties:
            version:
              type: integer
              enum:
              - 2
            network:
              type: string
              enum:
              - athena
            status:
              type: string
              enum:
              - accessible
              - partial
              - blocked
              - inconclusive
            http:
              allOf:
              - $ref: '#/components/schemas/AIAccessRawEvidence'
              nullable: true
            robots:
              allOf:
              - $ref: '#/components/schemas/AIAccessRawEvidence'
              nullable: true
          required:
          - version
          - network
          - status
          - http
          - robots
      required:
      - domain
      - status
      - checkedAt
    AIAccessRawEvidence:
      type: object
      properties:
        chatgpt:
          type: object
          properties:
            ChatGPTUser:
              type: boolean
              nullable: true
            OAISearchBot:
              type: boolean
              nullable: true
            GPTBot:
              type: boolean
              nullable: true
          required:
          - ChatGPTUser
          - OAISearchBot
          - GPTBot
        claude:
          type: object
          properties:
            ClaudeUser:
              type: boolean
              nullable: true
            ClaudeSearchBot:
              type: boolean
              nullable: true
            ClaudeBot:
              type: boolean
              nullable: true
          required:
          - ClaudeUser
          - ClaudeSearchBot
          - ClaudeBot
        gemini:
          type: object
          properties:
            Googlebot:
              type: boolean
              nullable: true
            GoogleExtended:
              type: boolean
              nullable: true
          required:
          - Googlebot
          - GoogleExtended
        perplexity:
          type: object
          properties:
            PerplexityUser:
              type: boolean
              nullable: true
            PerplexityBot:
              type: boolean
              nullable: true
          required:
          - PerplexityUser
          - PerplexityBot
        copilot:
          type: object
          properties:
            Bingbot:
              type: boolean
              nullable: true
          required:
          - Bingbot
        grok:
          type: object
          properties:
            XAIBot:
              type: boolean
              nullable: true
          required:
          - XAIBot
        deepseek:
          type: object
          properties:
            DeepSeekBot:
              type: boolean
              nullable: true
          required:
          - DeepSeekBot
        rufus:
          type: object
          properties:
            Amazonbot:
              type: boolean
              nullable: true
          required:
          - Amazonbot
      required:
      - chatgpt
      - claude
      - gemini
      - perplexity
      - copilot
      - grok
      - deepseek
      - rufus
    AIAccessRobotsCheckDetail:
      type: object
      description: robots.txt fetch diagnostics.
      properties:
        url:
          type: string
        status:
          type:
          - integer
          - 'null'
        finalUrl:
          type:
          - string
          - 'null'
        headers:
          type: object
          additionalProperties:
            type: string
        errorCode:
          type:
          - string
          - 'null'
        errorMessage:
          type:
          - string
          - 'null'
        durationMs:
          type: integer
        checkedAt:
          type: string
          format: date-time
        source:
          type: string
          enum:
          - direct
          - fallback
          - missing
      required:
      - url
      - status
      - finalUrl
      - headers
      - errorCode
      - errorMessage
      - durationMs
      - checkedAt
      - source
    AIAccessDiagnostics:
      type: object
      description: Per-request diagnostic fingerprint. Useful for filing host or CDN tickets.
      properties:
        userAgentChecks:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/AIAccessBotCheckDetail'
          description: Keyed by `${category}.${agentKey}`, e.g. `chatgpt.GPTBot`.
        robotsCheck:
          $ref: '#/components/schemas/AIAccessRobotsCheckDetail'
      required:
      - userAgentChecks
    AIAccessBotCheckDetail:
      type: object
      description: Per-agent diagnostic detail. Used to populate the diagnostic log a partner can paste into a host or CDN ticket.
      properties:
        category:
          type: string
          description: Model category (chatgpt, claude, gemini, ...).
        agentKey:
          type: string
          description: Internal key of the user-agent variant.
        agentName:
          type: string
          description: Human-readable user-agent name (e.g. `GPTBot`, `Googlebot`).
        userAgent:
          type: string
          description: Full user-agent string sent during the probe.
        accessible:
          type: boolean
          description: Whether this user-agent received a successful HTTP response.
        status:
          type:
          - integer
          - 'null'
          description: HTTP status code, or null on network/transport error.
        finalUrl:
          type:
          - string
          - 'null'
          description: Final URL after any redirects, or null on failure.
        headers:
          type: object
          additionalProperties:
            type: string
          description: CDN-relevant response headers (cf-ray, x-vercel-id, x-amz-cf-id, server, etc.).
        errorCode:
          type:
          - string
          - 'null'
          description: Error code when the request failed (e.g. `ENOTFOUND`, `ETIMEDOUT`).
        errorMessage:
          type:
          - string
          - 'null'
        durationMs:
          type: integer
        checkedAt:
          type: string
          format: date-time
        verdict:
          type: string
          enum:
          - allowed
          - challenged
          - blocked
          - error
          - not_tested
          description: Observed probe outcome. Challenged or error means unknown access. Policy-only tokens are not_tested.
      required:
      - category
      - agentKey
      - agentName
      - userAgent
      - accessible
      - status
      - finalUrl
      - headers
      - errorCode
      - errorMessage
      - durationMs
      - checkedAt
    AIAccessBotDetails:
      type: object
      description: Per-model conversational/training accessibility booleans.
      properties:
        conversational:
          type: boolean
          description: Live HTTP signal that the model's conversational user-agent is allowed.
        training:
          type: boolean
          description: Live HTTP signal that the model's training crawler is allowed.
      required:
      - conversational
      - training
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for authentication. You can create one [here](https://app.athenahq.ai/organization?tab=api).