AthenaHQ Sources API

openapi: 3.2.0
info:
  title: AthenaHQ Sources 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: Sources
paths:
  /api/v1/sources:
    post:
      tags:
      - Sources
      summary: List Sources (by root domain)
      description: 'Returns the top cited sources for a website, grouped by root domain. Each row carries citation, mention, brand-mention, and impression metrics for the requested date range, plus a `default_source_type` classification (`owned` / `competitor` / `partner` / `third_party`).


        Companion to POST /api/v1/source-pages, which returns the same data grouped per URL (one row per cited page) instead of per root domain. Ownership and source tags use the centralized URL-pattern rules. Domain summaries consider whole-host rules only; path and query rules apply to page-level results. Explicit www hosts remain separate when their matching rules differ from the apex.'
      operationId: listSources
      security:
      - apiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SourcesListRequest'
      responses:
        '200':
          description: Successful response with the page of sources.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourcesListResponse'
              example:
                sources:
                - root_domain: wikipedia.org
                  total_mentions: 124
                  response_count: 86
                  estimated_impressions: 18400
                  domain_count: 31
                  mention_percentage: 12.3
                  citation_percentage: 14.1
                  competitor_mention_percentage: 3.2
                  brand_mention_percentage: 8.9
                  mentions_count: 47
                  responses_mentioned_count: 39
                  competitor_ids: []
                  default_source_type: third_party
                  source_type_ids: []
                  first_seen: '2024-01-04'
                pagination:
                  page_num: 0
                  page_size: 30
                  total: 142
        '400':
          description: Bad request — invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing_website_id:
                  value:
                    error: website_id is required
                invalid_website_id:
                  value:
                    error: website_id must be a uuid
        '401':
          description: Unauthorized — invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden — you don't have access to this website, or a sub-resource ID (`prompt_ids`, `competitor_ids`, `location_ids`) belongs to another website.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                website:
                  value:
                    error: Unauthorized access to this website
                prompts:
                  value:
                    error: Unauthorized access to these prompts
        '404':
          description: Website not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Website not found
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/source-pages:
    post:
      tags:
      - Sources
      summary: List Source Pages (per URL)
      description: 'Returns individual cited URLs for a website with citation, mention, and impression metrics — one row per `normalized_url`. Each row also includes a `daily_mentions` sparkline (citation percentage per day across the date range) and the same source-type classification as POST /api/v1/sources.


        Use this when you need URL-level resolution (e.g. drill into which specific articles on a partner domain drove citations). For the root-domain rollup, use POST /api/v1/sources. Ownership and source tags match original citation URLs, preserving host distinctions, path case, and query constraints. Results retain their normalized URL identifiers and pagination, combining labels from matching citation variants within each page row.'
      operationId: listSourcePages
      security:
      - apiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SourcePagesListRequest'
      responses:
        '200':
          description: Successful response with the page of cited URLs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourcePagesListResponse'
              example:
                pages:
                - normalized_url: wikipedia.org/wiki/Customer_Relationship_Management
                  domain: en.wikipedia.org
                  root_domain: wikipedia.org
                  normalized_root_domain: wikipedia.org
                  total_mentions: 24
                  estimated_impressions: 3400
                  citation_percentage: 2.7
                  mentions_count: 9
                  competitor_ids: []
                  default_source_type: third_party
                  source_type_ids: []
                  first_seen: '2024-01-07'
                  daily_mentions:
                  - date: '2024-01-07'
                    citation_percentage: 0.4
                  - date: '2024-01-08'
                    citation_percentage: 0.6
                pagination:
                  page_num: 0
                  page_size: 30
                  total: 412
        '400':
          description: Bad request — invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing_website_id:
                  value:
                    error: website_id is required
                invalid_website_id:
                  value:
                    error: website_id must be a uuid
        '401':
          description: Unauthorized — invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden — you don't have access to this website, or a sub-resource ID (`prompt_ids`, `competitor_ids`, `location_ids`, `prompt_tags`) belongs to another website.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                website:
                  value:
                    error: Unauthorized access to this website
                prompts:
                  value:
                    error: Unauthorized access to these prompts
        '404':
          description: Website not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Website not found
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    SourcesPagination:
      type: object
      description: Pagination metadata. Unlike `Pagination` (which uses `has_more` lookahead), the sources surfaces expose a precise `total` count — the underlying ClickHouse query computes it as a window function in the same scan, so there's no extra round-trip cost.
      required:
      - page_num
      - page_size
      - total
      properties:
        page_num:
          type: integer
          description: Zero-indexed page number returned.
          example: 0
        page_size:
          type: integer
          description: Maximum items per page.
          example: 30
        total:
          type: integer
          description: Total number of rows matching the filters (across all pages).
          example: 142
    Error:
      type: object
      description: Error response object
      required:
      - error
      properties:
        error:
          type: string
          description: Error message describing what went wrong
          example: Unauthorized
    SourceTypeClassification:
      type: string
      enum:
      - owned
      - competitor
      - partner
      - third_party
      description: 'How the source row is classified relative to the website. `owned` covers the website''s own host, every host listed as an owned domain, and their subdomains; a listed owned URL pattern with a path (for example `reddit.com/user/brand`) makes only the pages under that path `owned`, not the whole host. `competitor` matches tracked competitor root domains. `partner` matches configured affiliate domains. `third_party` is the residual bucket (Wikipedia, news, etc.). Per-website source-type overrides apply in this order: an override on the exact URL decides; a host or path the website lists as owned stays `owned`; a domain-level override then decides, including for hosts that are `owned` only as subdomains of a listed domain.'
    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
    SourceItem:
      type: object
      description: A domain-grouped source row. Identifies one cited root domain with its citation, mention, and impression metrics for the requested date range.
      required:
      - root_domain
      - total_mentions
      - response_count
      - estimated_impressions
      - domain_count
      - mention_percentage
      - citation_percentage
      - competitor_mention_percentage
      - brand_mention_percentage
      - mentions_count
      - responses_mentioned_count
      - competitor_ids
      - default_source_type
      - source_type_ids
      - first_seen
      properties:
        root_domain:
          type: string
          description: The cited root domain (display form).
          example: wikipedia.org
        total_mentions:
          type: number
          description: Total citations of this domain (one per citing response) in the date range.
          example: 124
        response_count:
          type: number
          description: Distinct AI responses citing this domain.
          example: 86
        estimated_impressions:
          type: number
          description: Estimated impressions attributable to this domain across the date range.
          example: 18400
        domain_count:
          type: number
          description: Distinct subdomain count rolled up under this root domain.
          example: 31
        mention_percentage:
          type: number
          description: Citations of this domain as a percentage of all matching responses.
          example: 12.3
        citation_percentage:
          type: number
          description: Same numerator as `mention_percentage`. Kept for backward compatibility with the existing dashboard wire shape.
          example: 14.1
        competitor_mention_percentage:
          type: number
          description: Of the responses citing this domain, the percentage that also mention a tracked competitor.
          example: 3.2
        brand_mention_percentage:
          type: number
          description: Of the responses citing this domain, the percentage that mention the website's brand.
          example: 8.9
        mentions_count:
          type: number
          description: 'Per-URL rollup: count of cited URLs on this domain where the brand was mentioned.'
          example: 47
        responses_mentioned_count:
          type: number
          description: Count of citing responses where the brand was mentioned.
          example: 39
        competitor_ids:
          type: array
          items:
            type: string
            format: uuid
          description: Tracked competitors mentioned in responses that cite this domain.
          example: []
        default_source_type:
          $ref: '#/components/schemas/SourceTypeClassification'
        source_type_ids:
          type: array
          items:
            type: string
            format: uuid
          description: Custom source-type tag UUIDs attached to this domain (in addition to `default_source_type`).
          example: []
        first_seen:
          type: string
          description: Earliest citation date for this domain in the date range.
          example: '2024-01-04'
    SourcePageDailyMention:
      type: object
      description: A single day of the per-URL citation sparkline.
      required:
      - date
      - citation_percentage
      properties:
        date:
          type: string
          description: Date (YYYY-MM-DD) the citation percentage was measured on.
          example: '2024-01-07'
        citation_percentage:
          type: number
          description: Percentage of all responses on this date that cite the URL.
          example: 0.4
    SourcesListResponse:
      type: object
      required:
      - sources
      - pagination
      properties:
        sources:
          type: array
          items:
            $ref: '#/components/schemas/SourceItem'
        pagination:
          $ref: '#/components/schemas/SourcesPagination'
    SourcePagesListRequest:
      type: object
      description: Request body for listing per-URL cited pages.
      required:
      - website_id
      - filters
      properties:
        website_id:
          type: string
          format: uuid
          description: The website to list cited URLs for.
          example: 123e4567-e89b-12d3-a456-426614174000
        filters:
          allOf:
          - $ref: '#/components/schemas/ApiFilters'
          - type: object
            properties:
              persona_ids:
                type: array
                description: Persona IDs to filter to (list them with GET /api/v1/personas). Omit for all personas.
                items:
                  type: string
                  format: uuid
              prompt_tags:
                type: array
                description: Prompt tag IDs to filter prompts by (list them with GET /api/v1/prompt-tags). An entry can also be `type:high_intent` (branded prompts) or `type:discovery` (non-branded prompts) to filter by prompt type. Omit for all tags.
                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
                description: 'How the tag IDs in prompt_tags combine: is_any_of matches prompts with any listed tag, has_all_of only prompts carrying every listed tag. `type:` entries are not combined with the tags this way: a prompt must also have one of the listed types, and has_all_of accepts at most one `type:` entry, since a prompt has exactly one type. Defaults to is_any_of.'
        page_num:
          type: integer
          minimum: 0
          default: 0
        page_size:
          type: integer
          minimum: 1
          maximum: 100
          default: 30
        sort_field:
          type: string
          enum:
          - citation_percentage
          - estimated_impressions
          - total_mentions
          - mentions_count
          - normalized_url
          - competitor_ids
          - first_seen
          default: citation_percentage
        sort_direction:
          type: string
          enum:
          - asc
          - desc
          default: desc
        search:
          type: string
          nullable: true
          description: Substring filter on `normalized_url` AND `normalized_root_domain`. Protocol (`https://`), `www.`, query, and fragment are stripped before matching; path is preserved so URL-specific searches still work.
        mentioned:
          $ref: '#/components/schemas/SourcesMentionedFilter'
        competitors_mentioned:
          $ref: '#/components/schemas/SourcesMentionedFilter'
      example:
        website_id: 123e4567-e89b-12d3-a456-426614174000
        filters:
          start_date: '2024-01-01T00:00:00.000Z'
          end_date: '2024-01-31T23:59:59.999Z'
        page_size: 30
    SourcesMentionedFilter:
      type: string
      enum:
      - 'yes'
      - 'no'
      description: If `yes`, only count sources where your brand was mentioned in the citing response. If `no`, only count sources where your brand was NOT mentioned. Omit the field to count every cited source.
    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
    SourcePageItem:
      type: object
      description: A per-URL cited page row with metrics + sparkline.
      required:
      - normalized_url
      - domain
      - root_domain
      - normalized_root_domain
      - total_mentions
      - estimated_impressions
      - citation_percentage
      - mentions_count
      - competitor_ids
      - default_source_type
      - source_type_ids
      - first_seen
      - daily_mentions
      properties:
        normalized_url:
          type: string
          description: The cited URL after protocol/www/trailing-slash normalization. Domain is lower-cased; path case is preserved.
          example: wikipedia.org/wiki/Customer_Relationship_Management
        domain:
          type: string
          description: Display-form domain (may include `www.`, subdomains).
          example: en.wikipedia.org
        root_domain:
          type: string
          description: Display-form root domain.
          example: wikipedia.org
        normalized_root_domain:
          type: string
          description: Lower-cased root domain — useful for joining against `POST /api/v1/sources` rows.
          example: wikipedia.org
        total_mentions:
          type: number
          description: Total citations of this URL (one per citing response) in the date range.
          example: 24
        estimated_impressions:
          type: number
          description: Estimated impressions attributable to this URL across the date range.
          example: 3400
        citation_percentage:
          type: number
          description: Citations of this URL as a percentage of all matching responses.
          example: 2.7
        mentions_count:
          type: number
          description: Count of citing responses on this URL where the brand was mentioned.
          example: 9
        competitor_ids:
          type: array
          items:
            type: string
            format: uuid
          description: Tracked competitors mentioned in responses that cite this URL.
          example: []
        default_source_type:
          $ref: '#/components/schemas/SourceTypeClassification'
        source_type_ids:
          type: array
          items:
            type: string
            format: uuid
          description: Custom source-type tag UUIDs attached to this URL or its root domain.
        first_seen:
          type: string
          description: Earliest citation date for this URL in the date range.
          example: '2024-01-07'
        daily_mentions:
          type: array
          items:
            $ref: '#/components/schemas/SourcePageDailyMention'
          description: Per-day citation percentage sparkline for this URL across the date range. Empty array when no citations occurred.
    SourcesListRequest:
      type: object
      description: Request body for listing domain-grouped sources.
      required:
      - website_id
      - filters
      properties:
        website_id:
          type: string
          format: uuid
          description: The website to list sources for.
          example: 123e4567-e89b-12d3-a456-426614174000
        filters:
          $ref: '#/components/schemas/ApiFilters'
        page_num:
          type: integer
          minimum: 0
          default: 0
          description: Zero-indexed page number.
        page_size:
          type: integer
          minimum: 1
          maximum: 100
          default: 30
          description: Number of rows per page (1–100).
        sort_field:
          type: string
          enum:
          - citation_percentage
          - mention_percentage
          - competitor_mention_percentage
          - brand_mention_percentage
          - estimated_impressions
          - total_mentions
          - domain_count
          - mentions_count
          - root_domain
          - response_count
          - first_seen
          default: citation_percentage
          description: Column to sort by.
        sort_direction:
          type: string
          enum:
          - asc
          - desc
          default: desc
        search:
          type: string
          nullable: true
          description: Substring filter on `normalized_root_domain`. Protocol (`https://`), `www.`, path, query, and fragment are stripped before matching, so a full URL like `https://www.example.com/foo` collapses to `example.com`.
        mentioned:
          $ref: '#/components/schemas/SourcesMentionedFilter'
        competitors_mentioned:
          $ref: '#/components/schemas/SourcesMentionedFilter'
      example:
        website_id: 123e4567-e89b-12d3-a456-426614174000
        filters:
          start_date: '2024-01-01T00:00:00.000Z'
          end_date: '2024-01-31T23:59:59.999Z'
        page_size: 30
        sort_field: citation_percentage
        sort_direction: desc
    SourcePagesListResponse:
      type: object
      required:
      - pages
      - pagination
      properties:
        pages:
          type: array
          items:
            $ref: '#/components/schemas/SourcePageItem'
        pagination:
          $ref: '#/components/schemas/SourcesPagination'
  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).