AthenaHQ Analytics API

openapi: 3.2.0
info:
  title: AthenaHQ Analytics 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: Analytics
paths:
  /api/v1/looker-studio/data:
    post:
      tags:
      - Analytics
      summary: Query Looker Studio report data
      description: Return report rows for one website and streaming schedule. filters.schedule_id accepts default or a custom schedule UUID; omission selects Default. The retired manual token is accepted as an alias of default. Schedule selection applies to every metric and dimension and is part of the report cache key. Archived schedules retain history. Response-grain reports are bounded before response text hydration; narrow the filters if the row limit is exceeded.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - website_id
              - dimensions
              - metrics
              - filters
              - looker_studio_filters
              properties:
                website_id:
                  type: string
                  format: uuid
                dimensions:
                  type: array
                  items:
                    type: string
                    enum:
                    - date
                    - model
                    - company_name
                    - is_self
                    - location
                    - topic_name
                    - prompt
                    - response
                metrics:
                  type: array
                  items:
                    type: string
                    enum:
                    - citation_rate
                    - mention_rate
                    - share_of_voice
                    - position
                    - mentions
                    - citations
                    - total_responses
                filters:
                  allOf:
                  - $ref: '#/components/schemas/ApiFilters'
                  - type: object
                    required:
                    - end_date
                    properties:
                      prompt_tags:
                        type: array
                        items:
                          oneOf:
                          - type: string
                            format: uuid
                          - type: string
                            enum:
                            - type:discovery
                            - type:high_intent
                      prompt_tags_operator:
                        type: string
                        enum:
                        - is_any_of
                        - has_all_of
                looker_studio_filters:
                  type: array
                  items:
                    type: array
                    items:
                      type: object
                      required:
                      - fieldName
                      - operator
                      - type
                      - value
                      properties:
                        fieldName:
                          type: string
                          enum:
                          - date
                          - model
                          - company_name
                          - is_self
                          - location
                          - topic_name
                          - prompt
                          - response
                          - citation_rate
                          - mention_rate
                          - share_of_voice
                          - position
                          - mentions
                          - citations
                          - total_responses
                        operator:
                          type: string
                          enum:
                          - EQUALS
                          - CONTAINS
                          - REGEXP_PARTIAL_MATCH
                          - REGEXP_EXACT_MATCH
                          - IN_LIST
                          - IS_NULL
                          - BETWEEN
                          - NUMERIC_GREATER_THAN
                          - NUMERIC_GREATER_THAN_OR_EQUAL
                          - NUMERIC_LESS_THAN
                          - NUMERIC_LESS_THAN_OR_EQUAL
                        type:
                          type: string
                          enum:
                          - INCLUDE
                          - EXCLUDE
                        value:
                          type: array
                          items:
                            type: string
      responses:
        '200':
          description: Report rows
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                        model:
                          type: string
                        company_name:
                          type: string
                        is_self:
                          type: boolean
                        location:
                          type: string
                        topic_name:
                          type: string
                        prompt:
                          type: string
                        response:
                          type: string
                        citation_rate:
                          type: number
                        mention_rate:
                          type: number
                        share_of_voice:
                          type: number
                        position:
                          type: number
                        mentions:
                          type: number
                        citations:
                          type: number
                        total_responses:
                          type: number
        '400':
          description: Invalid request or response report row limit exceeded
        '401':
          description: Authentication required
        '403':
          description: Website or filter resource access denied
        '404':
          description: Website not found
      operationId: postApiV1LookerStudioData
      x-operation-id-source: derived
components:
  schemas:
    PromptScheduleSelection:
      description: Select one streaming schedule. Use the selection returned by GET /api/v1/prompt-schedules. Default includes all pre-cutover history and ad hoc runs; archived schedules retain results. The retired manual token is accepted as an alias of default. This field takes one schedule; a list returns 400.
      default: default
      oneOf:
      - type: string
        enum:
        - default
        - manual
      - type: string
        format: uuid
    ApiFilters:
      type: object
      description: Filters for querying responses and metrics. Pass location filters in the JSON body as `filters.location_ids`.
      required:
      - start_date
      properties:
        schedule_id:
          $ref: '#/components/schemas/PromptScheduleSelection'
        start_date:
          type: string
          format: date-time
          description: Filter start date (UTC)
          example: '2024-01-01T00:00:00.000Z'
        end_date:
          type: string
          format: date-time
          description: Filter end date (UTC)
          example: '2024-12-31T23:59:59.999Z'
        models:
          type: array
          description: Filter by AI models
          items:
            type: string
            enum:
            - chatgpt
            - perplexity
            - gemini
            - google_ai_overview
            - copilot
            - claude
            - ai_mode
            - grok
            - deepseek
            - meta_ai
            - mistral
          example:
          - chatgpt
          - perplexity
        prompt_ids:
          type: array
          description: Filter by specific prompt IDs
          items:
            type: string
            format: uuid
        competitor_ids:
          type: array
          description: Filter by specific competitor IDs
          items:
            type: string
            format: uuid
        location_ids:
          type: array
          description: Filter by location IDs. Pass this in the JSON body as `filters.location_ids`, even when filtering by a single location. Use IDs returned by `GET /api/v1/locations`.
          items:
            type: string
            format: uuid
          example:
          - 123e4567-e89b-12d3-a456-426614174111
        prompt_status:
          type: string
          enum:
          - active
          - paused
          description: Filter by prompt status
        prompt_type:
          type: string
          enum:
          - branded
          - non_branded
          description: Filter by prompt type
  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).