# AthenaHQ

- [Getting Started](https://docs.athenahq.ai/getting-started/setup.md): Set up AthenaHQ and start tracking your brand across AI search
- [Discover](https://docs.athenahq.ai/discover.md): Run prompt discovery across your website, search data, social signals, and competitor gaps to find the prompts worth tracking
- [Setting Up Your Prompts](https://docs.athenahq.ai/setting-up-prompts.md): Build a useful Athena prompt set with direct entry or the Discover tab
- [Brand Profile](https://docs.athenahq.ai/brand-profile.md): Set up the brand details Athena uses for tracking, scoring, and content generation
- [Knowledge Base](https://docs.athenahq.ai/knowledge-base.md): Give Athena verified facts about your business for accurate research and content generation
- [Integrations](https://docs.athenahq.ai/integrations.md): Connect analytics, CMS, dashboarding, and reporting tools to Athena
- [Oracle](https://docs.athenahq.ai/oracle.md): Scan AI responses for inaccurate claims, review the evidence, and keep your brand facts current
- [Sources](https://docs.athenahq.ai/sources.md): See which websites AI search engines cite across your tracked prompts
- [Add Website (Onboarding Wizard)](https://docs.athenahq.ai/guides/add-website.md): Multi-step wizard for creating (or resuming/completing) a website's onboarding setup: brand profile, competitors, prompts, region, Google Search Console, and monitoring schedule.
- [Ads](https://docs.athenahq.ai/guides/ads.md): Show sponsored ads captured across ChatGPT, Google AI Mode, and Google Search/AI Overview responses to tracked prompts, and which advertisers are buying them.
- [The AthenaHQ Crawler (/bot)](https://docs.athenahq.ai/guides/bot.md): A public, unauthenticated reference page explaining AthenaHQ's crawler identity, user agent, and access behavior so IT admins can allow it through firewalls.
- [Brand Profile](https://docs.athenahq.ai/guides/brand-profile.md): Central hub for managing a website's brand identity, brand attributes/traits, content memories, brand voice kits, and technical AI-crawler settings (llms.txt, sitemap, schema, AI accessibility).
- [Competitors](https://docs.athenahq.ai/guides/competitors.md): Track and manage competitor brands (and your own website's identity), review AI-visibility comparisons, discover new competitors, and manage deleted competitors.
- [Create Pitch](https://docs.athenahq.ai/guides/create-pitch.md): Two-step wizard that analyzes a website, researches its competitors and prompts, and creates a new pitch report (or clones an existing one).
- [Glossary](https://docs.athenahq.ai/guides/glossary.md): Provide plain-language, searchable/navigable definitions of every AthenaHQ metric, score, and concept, grouped by category, so customers can look up how numbers are calculated and how to act on them.
- [Competitor Heatmap](https://docs.athenahq.ai/guides/heatmap.md): Show a heatmap grid of each tracked topic against the brand and its competitors so users can spot mention/citation gaps at a glance and drill into supporting prompts.
- [Home (Ask Athena chat homepage)](https://docs.athenahq.ai/guides/home.md): Landing page where users type or pick a quick prompt to open an Ask Athena AI chat about their brand's AI search presence.
- [Insights](https://docs.athenahq.ai/guides/insights.md): Show AI-generated proactive insights and content opportunities for a website, letting users act on, resolve, or discard them.
- [Olympus Dashboard](https://docs.athenahq.ai/guides/olympus.md): The main analytics dashboard showing AI search visibility metrics (mentions, citations, share of voice, position, and business value) for the active website, with customizable cards, saved views, and export/reporting tools.
- [Oracle](https://docs.athenahq.ai/guides/oracle.md): Scan AI-generated responses against the knowledge base to surface confirmed inaccuracies, knowledge-base inconsistencies, and model disagreements, and let the customer review/resolve them.
- [Outreach](https://docs.athenahq.ai/guides/outreach.md): Triage pages AI cites as outreach opportunities: find authors, draft pitches, and track outreach status through a Kanban pipeline.
- [Report Builder (Edit Report)](https://docs.athenahq.ai/guides/reports-id.md): Lets a user edit a scheduled report's charts, settings, recipients, and send it immediately or export it as a PDF.
- [Responses](https://docs.athenahq.ai/guides/responses.md): Lets a customer browse, search, filter, sort, export, and drill into every individual AI-model response collected for their tracked prompts.
- [Shopping Insights](https://docs.athenahq.ai/guides/shopping.md): Show how a website's products appear in AI shopping results (ChatGPT, AI Mode and Gemini carousels), including visibility, position, pricing, and competitor comparisons.
- [Content](https://docs.athenahq.ai/guides/content.md): Manage, generate, import, and publish website content in a spreadsheet-style workspace with AI agent columns, custom columns, and metrics tracking.
- [Catalog Optimization](https://docs.athenahq.ai/guides/content-catalog-optimization.md): Review your Shopify catalog, generate product content drafts, and publish selected titles, descriptions and FAQs after review.
- [Catalog Optimization](https://docs.athenahq.ai/guides/content-product-optimization.md): Review your Shopify catalog, generate product content drafts, and publish selected titles, descriptions and FAQs after review.
- [Group Dashboard](https://docs.athenahq.ai/guides/group-id.md): Shows an aggregated, filterable analytics dashboard (share of voice, mention/citation rate, position, dollar value) across all websites in a group, with saved views and scheduled reports.
- [Group Billing](https://docs.athenahq.ai/guides/group-id-billing.md): Lets a group admin (or billing-capable role) enable and manage shared credit billing for a website group, viewing credit balances and invoices scoped to that group.
- [Knowledge Base](https://docs.athenahq.ai/guides/knowledge-base.md): Central workspace for building, curating, and verifying a website's brand knowledge base of pillars (topics), facts (claims), and tracked internal link pages that ground AI-generated content and can be checked against AI responses for accuracy.
- [Review Pending Claims](https://docs.athenahq.ai/guides/knowledge-base-review.md): Lets a team review, approve, reject, delete, or re-file the queue of claims Athena extracted but couldn't auto-verify before they count toward published knowledge base pillars.
- [Knowledge Base Pillar Detail](https://docs.athenahq.ai/guides/knowledge-base-pillarId.md): Detailed working view of a single Knowledge Base pillar (topic), its facts/claims, sources, associated pages, generated document, and matching content.
- [Generate a pitch report](https://docs.athenahq.ai/api-reference/pitch-creation.md): Create a shareable prospect report from a website URL, then poll for results.
- [Pitch Workspace Report](https://docs.athenahq.ai/guides/pitch-workspace.md): Shows the AI-visibility report for the organization's currently active pitch (brand vs. competitors across AI search engines), redirecting to pitch creation if no pitches exist.
- [Pitch Setup](https://docs.athenahq.ai/guides/pitch-workspace-setup.md): Read-only overview of the active pitch's basic info, identifiers, competitors, and prompts configuration.
- [Pitch Workspace Usage](https://docs.athenahq.ai/guides/pitch-workspace-usage.md): Shows an agency org's Pitch Reports usage (used/remaining or unlimited) and a summary of pitch report limits.
- [Content Pitches (list)](https://docs.athenahq.ai/guides/pitch-workspace-content.md): List all content pitches created for the org, letting agency users create new prospect rewrite reports, share links, or delete pitches.
- [Content Pitch Detail (Pitch Workspace)](https://docs.athenahq.ai/guides/pitch-workspace-content-id.md): Lets a workspace user review one content pitch report exactly as the prospect will see it, copy/open its public share link, and delete it.
- [Create Content Pitch](https://docs.athenahq.ai/guides/pitch-workspace-content-create.md): A two-step wizard for creating a shareable AI-search content pitch: paste a prospect's article URL, then review/edit the AI-generated optimization prompts before generating a public rewrite report.'
- [Prompts](https://docs.athenahq.ai/guides/prompts.md): Manage tracked prompts, topics, personas, locations, and discover new prompt opportunities for the active website
- [Discovery Run Detail (Discover)](https://docs.athenahq.ai/guides/prompts-discover-id.md): Review, filter, edit, track, or remove AI-suggested prompt candidates produced by a single prompt-discovery run.
- [Public AI Search Report](https://docs.athenahq.ai/guides/report-pitchId.md): Publicly-shareable, read-only AI search visibility report for a pitch (brand mentions, share of voice, competitor analysis, and sampled AI responses) that anyone with the link can view.
- [Public Content Suggestions Report](https://docs.athenahq.ai/guides/report-content-shareId.md): Lets a prospect (with no AthenaHQ account) view a shareable, read-only report showing how Athena would rewrite a specific webpage's content to perform better in AI search answers.
- [API & Embed Settings](https://docs.athenahq.ai/guides/settings-api.md): Manage AthenaHQ API keys, MCP/Looker Studio integration guides, and embeddable-dashboard credentials for the organization.
- [Users (Team & Access settings)](https://docs.athenahq.ai/guides/settings-users.md): Manage everyone who has access to the organization, its websites, and its groups: members, roles, invites, and access-scope changes: from one roster.
- [Billing Settings](https://docs.athenahq.ai/guides/settings-billing.md): Lets an organization admin or an external website member view and manage subscription plans, credits, invoices, and payment details for their organization or a single website.
- [General Settings](https://docs.athenahq.ai/guides/settings-general.md): View and edit the active organization's core details (name, role, creation date), quickly navigate to other org settings, and delete the organization.
- [Profile Settings](https://docs.athenahq.ai/guides/settings-profile.md): Lets a signed-in user manage their personal profile (name, avatar), sidebar layout preference, and account deletion.
- [Activity Log (Settings → Activity)](https://docs.athenahq.ai/guides/settings-activity.md)
- [Sign-in & access (Security Settings)](https://docs.athenahq.ai/guides/settings-security.md): Let organization admins control who can join automatically by email domain (at org and website level) and configure single sign-on (SSO) plus SCIM user provisioning for their identity provider.
- [Integrations Settings](https://docs.athenahq.ai/guides/settings-integrations.md): Let a website's team connect, configure, and disconnect third-party data, publishing, and reporting integrations (analytics, CMS/e-commerce platforms, Slack, Looker Studio) and browse/connect MCP tool connectors.
- [Site Health](https://docs.athenahq.ai/guides/site-health.md): Shows how AI assistants and search engines read, understand, and cite a website, and lets a team monitor, fix, and verify issues that block or weaken that visibility.
- [Keywords and rankings](https://docs.athenahq.ai/guides/site-health-keywords.md): Research keyword ideas for a topic and compare Google search rankings against AI visibility, letting users promote keywords into AI or Google-rank monitoring.
- [Site Health – Staging Checks (Release Comparisons)](https://docs.athenahq.ai/guides/site-health-releases.md): Lets a team set up and review comparisons between live production pages and their public staging copies before shipping a template or site release, to catch SEO regressions.
- [Site Map](https://docs.athenahq.ai/guides/site-health-site-map.md): Browse and search every page the site crawl found, laid out as a folder tree by URL, to inspect scores/issues per page, move pages between sections, or start an Athena fix.
- [Crawl Scope (Site Health Properties)](https://docs.athenahq.ai/guides/site-health-properties.md): Lets a site owner define and manage the 'crawl scopes' (URL roots + subdomain/sitemap/path rules) that Site Health crawls to discover pages for auditing.
- [Site Health – Page Edits (Optimizations Delivery Board)](https://docs.athenahq.ai/guides/site-health-optimizations.md): Lets a team review, approve, and deliver (export, CMS-push, or manually record) Athena-drafted content edits to a website's pages, and track whether each delivered change is confirmed live.
- [Crawl Scope – Property Pages](https://docs.athenahq.ai/guides/site-health-properties-propertyId.md): Browse the crawled/audited pages of a single site-health crawl scope (property) as a tree, filter by problem or search, and run or review AI-visibility audits on selected pages.
- [Live content check (delivery verification)](https://docs.athenahq.ai/guides/site-health-optimizations-verification-eventId.md): Shows whether a manually-applied Site Health page edit actually matches what's live, field by field, with an option to retry the live check or return to Page edits.
- [Sources](https://docs.athenahq.ai/guides/sources.md): Shows which domains/pages/social platforms are being cited by AI models as sources, letting customers analyze, tag, and export citation data.
- [Source Domain Analytics](https://docs.athenahq.ai/guides/sources-root_domain.md): Deep-dive analytics for a single cited source domain: citation trends, cited pages, cited prompts, citing responses, and (for YouTube) creators/timestamps.
- [Sources Visualization](https://docs.athenahq.ai/guides/sources-visualization.md): Shows an interactive Sankey diagram mapping which web sources LLMs cite when mentioning the brand vs. competitors, so users can trace AI visibility back to its source content.
- [URL Source Analytics (Standalone URL Inspector)](https://docs.athenahq.ai/guides/sources-analytics-source_url.md): Give a deep dive into how a single cited URL (or YouTube video) performs across AI platforms: citation trend, per-platform breakdown, responses that cite it, URL parameter variants, and (for YouTube) creator and timestamp breakdowns.
- [Introduction](https://docs.athenahq.ai/api-reference/introduction.md): Programmatically interact and integrate with AthenaHQ
- [Authentication](https://docs.athenahq.ai/api-reference/authentication.md): Authenticate API requests using API keys
- [Single Sign-On (SSO)](https://docs.athenahq.ai/api-reference/sso.md): Configure SAML or OIDC single sign-on for your AthenaHQ organization
- [Rate Limits](https://docs.athenahq.ai/api-reference/rate-limits.md): API rate limits and availability
- [Changelog](https://docs.athenahq.ai/api-reference/changelog.md): Latest updates and changes to the AthenaHQ API
- [MCP Server](https://docs.athenahq.ai/api-reference/mcp.md): Connect AthenaHQ to ChatGPT, Claude, and other AI assistants via the Model Context Protocol
- [Looker Studio](https://docs.athenahq.ai/api-reference/looker-studio.md): Integrate AthenaHQ with Looker Studio
- [Power BI & Microsoft Fabric](https://docs.athenahq.ai/api-reference/powerbi-fabric.md): Pull AthenaHQ data into Power BI Desktop, Power BI Service, or Microsoft Fabric via the REST API
- [Saved view exports](https://docs.athenahq.ai/api-reference/saved-view-exports.md): Pull the metrics of a dashboard saved view into Snowflake, BigQuery, or any warehouse on a schedule
- [Validate API Key](https://docs.athenahq.ai/api-reference/basics/validate-api-key.md): Validates an API key.
- [Get Date Range](https://docs.athenahq.ai/api-reference/basics/get-date-range.md): Returns the date range with available data for one streaming schedule's prompts. Omitting schedule_id selects Default, including all pre-cutover history.
- [Query Looker Studio report data](https://docs.athenahq.ai/api-reference/analytics/query-looker-studio-report-data.md): 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 ke…
- [Get Websites](https://docs.athenahq.ai/api-reference/basics/get-websites.md): Returns all active websites associated with your API key. **Partner integrations** may pass `external_id` as a query parameter to find the Athena website mapped to a partner-supplied identifier.
- [Create Website](https://docs.athenahq.ai/api-reference/basics/create-website.md): Creates a new website in your organization. The website will be created with onboarding step 1, ready for further configuration. **Partner integrations** may include an `external_id` to map their own identifier onto the new Athena website. A successful creation also provisions the website's Default…
- [Provision Website](https://docs.athenahq.ai/api-reference/basics/provision-website.md): Creates a fully configured website in a single call, skipping the onboarding wizard. Optionally configures competitors, prompts, and a processing schedule. Requires a global API key. **Partner integrations** may include an `external_id` to map their own identifier onto the new Athena website. A succ…
- [Update Website](https://docs.athenahq.ai/api-reference/basics/update-website.md): Sets, replaces, or clears the partner `external_id` mapped to a website. **Partner integrations only:** pass `external_id` as a non-empty string to set or replace the mapping, or as `null` to clear it. Requires a global API key. Works on deleted websites too, because deleting a website does not rele…
- [Delete Website](https://docs.athenahq.ai/api-reference/basics/delete-website.md): Deletes a website. Removes it from your organization and stops all associated processing. Requires a global API key. Idempotent: re-calling on an already deleted website returns 200. This action is reversible — call `POST /api/v1/websites/{website_id}/restore` to reactivate a deleted website.
- [Restore Website](https://docs.athenahq.ai/api-reference/basics/restore-website.md): Restores a previously deleted website, reactivating processing and making it available again. All historical data is preserved. Requires a global API key. Idempotent: re-calling on an already active website returns 200.
- [Get Prompts](https://docs.athenahq.ai/api-reference/basics/get-prompts.md): Returns all prompts for a specific website. You can optionally filter by status (active or paused). The prompts returned include metadata such as monthly search volume and total value.
- [Create Prompts](https://docs.athenahq.ai/api-reference/basics/create-prompts.md): Creates one or more prompts on a website. Returns the created prompt ids. Each prompt's geography (`countries` / `primary_country`) and any attached `location_ids` are validated for compatibility before insert.
- [Update Prompt](https://docs.athenahq.ai/api-reference/basics/update-prompt.md): Updates a prompt's metadata (text, type, volume, topic, geography, locations). Only the supplied fields change. Returns a before/after snapshot.
- [Pause or Unpause Prompts](https://docs.athenahq.ai/api-reference/basics/pause-or-unpause-prompts.md): Pauses or unpauses multiple prompts in one transaction.
- [Delete Prompt](https://docs.athenahq.ai/api-reference/basics/delete-prompt.md): Deletes a prompt. Soft-deletes when the prompt already has responses, otherwise hard-deletes.
- [Get Prompt Tags](https://docs.athenahq.ai/api-reference/basics/get-prompt-tags.md): Returns all prompt tags for a specific website, sorted by tag name, with the number of non-deleted prompts carrying each tag. Use the returned IDs with the `prompt_tags` filter on GET /api/v1/prompts or the `tag_ids` field on POST /api/v1/prompts.
- [List prompt schedules](https://docs.athenahq.ai/api-reference/basics/list-prompt-schedules.md): List Default, custom and archived streaming schedules for a website. Use each row's selection value when filtering analytics or responses. Default includes all pre-cutover history and ad hoc runs. Select one schedule at a time; archived schedules retain results. Filters take one schedule; the metric…
- [List API Keys](https://docs.athenahq.ai/api-reference/basics/list-api-keys.md): Lists API key metadata for the authenticated key's organization, including each key's creator (ID, current name and email), creation date, scope and revocation status. Requires a global API key; website-scoped keys receive 403. No organization ID is accepted. Secrets and hashes are never returned. R…
- [List Activity](https://docs.athenahq.ai/api-reference/basics/list-activity.md): Returns the changes made to prompts, topics and prompt tags across your organization, newest first by default. Each entry names the website, the entity type, the kind of change (`created`, `updated`, `deleted`, `restored`, `paused`, `unpaused`), the affected entity ids and who made the change. Use i…
- [Get Topics](https://docs.athenahq.ai/api-reference/basics/get-topics.md): Returns the active topics for a website, with the count of active prompts in each. Use it to resolve a topic name to its `id` before creating prompts or filtering.
- [Create Topic](https://docs.athenahq.ai/api-reference/basics/create-topic.md): Creates a topic on a website. Topics group prompts for aggregate reporting; pass the returned `id` as `prompts[].topic_id` when creating prompts. Get-or-create by name: if an active topic with the same name already exists, the existing topic is returned with `created: false` instead of failing, so r…
- [Update Topic](https://docs.athenahq.ai/api-reference/basics/update-topic.md): Updates a topic's name and/or description. Only the supplied fields change. Renaming to a name already used by another active topic on the website returns `400`. Renames don't affect metrics or prompt grouping — everything joins on the topic's `id`, not its name. Returns a before/after snapshot.
- [Delete Topic](https://docs.athenahq.ai/api-reference/basics/delete-topic.md): Soft-deletes a topic. By default its prompts are kept: they stay active, keep their history, remain grouped under the deleted topic in the app, and can be re-categorized later. Pass `delete_prompts=true` to also soft-delete every active prompt in the topic (they stop generating responses). Reversibl…
- [Get Personas](https://docs.athenahq.ai/api-reference/basics/get-personas.md): Returns all personas for a specific website, sorted by name, with the number of non-deleted prompts each persona is assigned to. Use the returned IDs to resolve `persona_id` values returned by other endpoints and tools to persona names and descriptions.
- [Get Competitors](https://docs.athenahq.ai/api-reference/basics/get-competitors.md): Returns all competitors for a specific website.
- [Get Locations](https://docs.athenahq.ai/api-reference/basics/get-locations.md): Returns all locations for a specific website.
- [Create Location](https://docs.athenahq.ai/api-reference/basics/create-location.md): Creates a location for a website. `country` is case-insensitive and stored as its canonical label. Any attached `prompt_ids` must allow the location's country.
- [Update Location](https://docs.athenahq.ai/api-reference/basics/update-location.md): Updates a location's name, country, and/or prompt associations. Only supplied fields change; omitting `prompt_ids` preserves existing associations. Returns a before/after snapshot.
- [Delete Location](https://docs.athenahq.ai/api-reference/basics/delete-location.md): Soft-deletes a location.
- [Query Responses](https://docs.athenahq.ai/api-reference/basics/query-responses.md): Returns paginated AI model responses for a website with optional filtering by date range, models, prompts, competitors, and the search queries used to produce each response.
- [Start Response Streaming](https://docs.athenahq.ai/api-reference/basics/start-response-streaming.md): Run tracked prompts against external AI providers to collect new responses for a website. Sends prompt text to the selected providers, stores their responses in AthenaHQ, and consumes response credits. Starts immediately; use only for a user-requested run. Returns a workflow_id; poll GET /api/v1/res…
- [Get Response Streaming Status](https://docs.athenahq.ai/api-reference/basics/get-response-streaming-status.md): Returns the whole-run state and response-queue progress of a website's response-streaming run. By default reports the latest run; pass `workflow_id` to read a specific one. Progress measures response collection only, so `state` can remain `running` when `progress.percentage` is 100 while downstream…
- [Get Saved Views](https://docs.athenahq.ai/api-reference/basics/get-saved-views.md): Returns all saved views (filter presets) for a specific website. Each saved view captures a named set of filters that can be reused across the dashboard.
- [Get Group Saved Views](https://docs.athenahq.ai/api-reference/basics/get-group-saved-views.md): Returns all group-level saved views (filter presets) for the websites in a group. Group saved views capture filter state shared across the group rather than scoped to a single website.
- [List Attributes](https://docs.athenahq.ai/api-reference/attributes/list-attributes.md): Returns the direction-neutral brand-perception attributes tracked for a website. Use positive to select the positive or negative observation series; it defaults to true. Use this to discover attribute ids, then POST /api/v1/attributes/cumulative for prevalence, or POST /api/v1/attributes/time-series…
- [Cumulative Attribute Metrics](https://docs.athenahq.ai/api-reference/attributes/cumulative-attribute-metrics.md): Returns directional prevalence for each direction-neutral brand-perception attribute. The optional top-level `positive` request field selects positive or negative observations and defaults to true. `total_responses` is the denominator: sampled, successfully analyzed responses in the date range that…
- [Competitor Attribute Metrics](https://docs.athenahq.ai/api-reference/attributes/competitor-attribute-metrics.md): Returns directional attribute prevalence per tracked competitor. The optional top-level `positive` request field selects positive or negative observations and defaults to true. `total_responses` is per-competitor: sampled, successfully analyzed responses in the date range that mention that competito…
- [Attribute Time Series](https://docs.athenahq.ai/api-reference/attributes/attribute-time-series.md): Returns the daily directional trend for one attribute, brand and competitors side by side. Requires an attribute_id. The optional top-level `positive` request field selects positive or negative observations and defaults to true. Days with no data are returned as zeros. Denominators are per-side samp…
- [Attribute Observations](https://docs.athenahq.ai/api-reference/attributes/attribute-observations.md): Returns individual brand trait observations: each row is one statement an AI response made about one entity (your brand or a competitor) for one attribute, with the supporting response excerpt as `text_span`. `score` runs from -1 to 1 and its sign always matches `positive`; its magnitude (0.1 to 1.0…
- [Cumulative Share of Voice](https://docs.athenahq.ai/api-reference/metrics/cumulative-share-of-voice.md): Returns aggregated share of voice percentages across the specified date range. Shows what percentage of AI responses mention your brand versus competitors. Each entry also includes `relative_mention_rate`: the entry's mentions as a percentage of responses that mention at least one tracked brand.
- [Share of Voice Over Time](https://docs.athenahq.ai/api-reference/metrics/share-of-voice-over-time.md): Returns daily share of voice breakdown over the specified date range. Each entry contains the date and SOV percentages for your brand and competitors, plus each company's `relative_mention_rate`: its mentions as a percentage of that day's responses that mention at least one tracked brand.
- [Cumulative Mention Rate](https://docs.athenahq.ai/api-reference/metrics/cumulative-mention-rate.md): Returns mention rate percentages across the specified date range. `mention_rate` is absolute (the percentage of all AI responses that mention the brand); `relative_mention_rate` is the percentage of responses mentioning at least one tracked brand.
- [Mention Rate Over Time](https://docs.athenahq.ai/api-reference/metrics/mention-rate-over-time.md): Returns daily mention rate breakdown over the specified date range. Each entry contains the date and, per brand/competitor, the absolute `mention_rate` (share of all responses that day) and `relative_mention_rate` (share of that day's responses mentioning at least one tracked brand).
- [Cumulative Citation Rate](https://docs.athenahq.ai/api-reference/metrics/cumulative-citation-rate.md): Returns citation rate percentages across the specified date range. Shows the percentage of AI responses that cite your brand and competitors as sources.
- [Citation Rate Over Time](https://docs.athenahq.ai/api-reference/metrics/citation-rate-over-time.md): Returns daily citation rate breakdown over the specified date range. Each entry contains the date and citation rate percentages for your brand and competitors.
- [Cumulative Position](https://docs.athenahq.ai/api-reference/metrics/cumulative-position.md): Returns average position/ranking across the specified date range. Shows where your brand and competitors typically appear in AI responses.
- [Position Over Time](https://docs.athenahq.ai/api-reference/metrics/position-over-time.md): Returns daily position/ranking breakdown over the specified date range. Each entry contains position metrics for your brand and competitors.
- [Shopping Metrics](https://docs.athenahq.ai/api-reference/metrics/shopping-metrics.md): Returns the Shopping Insights dashboard for a website over a date range: how often the brand's products appear in AI shopping answers (product carousels) versus competitors, average position and price, the top own and competitor products, the competitor leaderboard, retailer breakdown, rank distribu…
- [AI Search Value](https://docs.athenahq.ai/api-reference/ai-search-value.md): Read the estimated monthly dollar value of a website's presence in AI search answers, as a range grounded in Google keyword economics.
- [Get AI Search Value](https://docs.athenahq.ai/api-reference/ai-search-value/get-ai-search-value.md): AI Search Value for a website: topic-market value, captured value range, headroom, coverage, value-weighted AI share of voice, per-topic detail, and modeled attributed contribution.
- [List Content Hub Sheets](https://docs.athenahq.ai/api-reference/content/list-content-hub-sheets.md): Returns the Content Hub tabs configured for a website. Each tab is either a `sheet` (content pinned via `content.sheet_id`) or a `view` (saved filter layout over the main content pool). Call this first to discover the `sheet_id`s you can pass to `POST /api/v1/content`.
- [List Tracked Content](https://docs.athenahq.ai/api-reference/content/list-tracked-content.md): Returns paginated tracked content with citation, impression, and response metrics joined for the requested date range. Hidden content (`is_hidden = true`) is excluded.
- [List Content Items](https://docs.athenahq.ai/api-reference/content/list-content-items.md): Returns every content item in a website's Content Hub, published or not: in-flight drafts, briefs, snipes, optimize and slice runs, scheduled and failed items, plus tracked pages. This is the enumeration path from a `sheet_id` to its unpublished rows. `POST /api/v1/content` lists only finished pipel…
- [Get Content Detail](https://docs.athenahq.ai/api-reference/content/get-content-detail.md): Fetch the full detail of a single tracked content item — including the actual text: the content brief (`brief`) and the article/page body (`body`). `body` holds generated drafts, optimize rewrites, snipe articles, authored text, and scraped tracked-page bodies alike.
- [Per-Content Prompt Citation Breakdown](https://docs.athenahq.ai/api-reference/content/per-content-prompt-citation-breakdown.md): For a single tracked content item, returns every prompt whose AI responses cite the URL — with citations, citation %, and estimated impressions for the date range.
- [Start Content Pipeline](https://docs.athenahq.ai/api-reference/content/start-content-pipeline.md): Generate an article or content brief in AthenaHQ. Fetches source URLs, sends source material to external AI providers, and consumes content credits. Obtain user approval before calling. Does not publish to a website or CMS. For draft mode, auto_approve defaults to true; set false to generate only a…
- [Get Content Pipeline Status](https://docs.athenahq.ai/api-reference/content/get-content-pipeline-status.md): Get the normalized pipeline status (running | succeeded | failed) for one content row, plus the raw stage behind it. Read-only. Poll once per contentId returned by create_content (content.pipeline.start). A stage of generated_brief with status running means the brief is ready and waiting: for a non-…
- [Get Content Draft](https://docs.athenahq.ai/api-reference/content/get-content-draft.md): Read the current draft text of a content item — the article body as it stands right now, including every revision applied so far. Use this before revise_content to see what you are changing, and after it to confirm the result. A status of generated_brief means the brief is ready while the article is…
- [Revise Content Brief](https://docs.athenahq.ai/api-reference/content/revise-content-brief.md): Rewrite a content brief from a natural-language instruction (for example: 'add a section on pricing objections', 'cut the competitor comparison'). An AI model performs the rewrite server-side, so the result is generated text, not your literal wording. Records each pass as a version; iterate by calli…
- [Approve Content Brief](https://docs.athenahq.ai/api-reference/content/approve-content-brief.md): Approve a content brief and start writing the article from it. Only valid while the piece is at status generated_brief. The article is generated from the brief exactly as it currently stands, including any revisions made with revise_brief or edits made in the app. Consumes content credits; poll get_…
- [Revise Content Draft](https://docs.athenahq.ai/api-reference/content/revise-content-draft.md): Rewrite an existing content draft from a natural-language instruction (for example: 'tighten the intro', 'add a section on pricing', 'remove the second half'). An AI model performs the rewrite server-side, so the result is generated text, not your literal wording; when you already have the exact rep…
- [Edit Content Draft](https://docs.athenahq.ai/api-reference/content/edit-content-draft.md): Apply exact find-and-replace edits to a content draft's article body. Deterministic, no AI model involved: your replacement text lands verbatim (use the revise endpoint when you want an AI rewrite from an instruction). Each edit's find text must match the current body exactly once; zero or multiple…
- [List Content Versions](https://docs.athenahq.ai/api-reference/content/list-content-versions.md): List the saved versions of a content item, newest first. Each entry carries its version number, label, how it was produced, and who made it. Use it to see how a draft evolved, then get_content_version to read a specific one, or restore_content_version to go back to it.
- [Get Content Version](https://docs.athenahq.ai/api-reference/content/get-content-version.md): Read the full text of one saved version of a content item. Use it to compare two passes (fetch both and diff them yourself) or to check what an earlier version said before restoring it.
- [Restore Content Version](https://docs.athenahq.ai/api-reference/content/restore-content-version.md): Bring an earlier version's text back as the current draft — use it when a later pass came out worse than an earlier one. Nothing is deleted: the restored text is appended as a new version on top of the history, so the passes in between remain readable and restorable.
- [Mark Content as Published](https://docs.athenahq.ai/api-reference/content/mark-content-as-published.md): Record an already-published article's URL in AthenaHQ for citation and mention tracking. Does not upload or publish content to a website or CMS. Call only after the article is live. Sets the first publication time and moves the pipeline stage to done. A first publish requires a finished article (sta…
- [Track External URLs](https://docs.athenahq.ai/api-reference/content/track-external-urls.md): Register existing pages or third-party URLs as tracked Content Hub items so Athena attributes citations and mentions to them. Creates external content rows from bare URLs with no generation and no credit cost. Tracking starts immediately: the normalized URL becomes the citation/metric join key, so p…
- [Rename Content](https://docs.athenahq.ai/api-reference/content/rename-content.md): Rename a content row's title. URL editing is not supported — URL is the content asset's stable identity and cannot be changed here.
- [Delete Content](https://docs.athenahq.ai/api-reference/content/delete-content.md): Delete a content row. Destructive: physical row delete, no undo. Powers delete-and-retry. Bulk delete is out of scope.
- [Submit SEO recommendations](https://docs.athenahq.ai/api-reference/seo-recommendations/submit-seo-recommendations.md): Submit one draft or public HTTPS page for asynchronous SEO and AI-search recommendations. The website's organization must have the seo_recommendations entitlement in Autumn, and the caller must have website content administration access. Missing entitlement returns 403; an unavailable entitlement ch…
- [Get SEO recommendation job](https://docs.athenahq.ai/api-reference/seo-recommendations/get-seo-recommendation-job.md): Read a saved job with website content view access (viewer or higher). Results can contain evidence from submitted drafts. A completed result contains source-grounded recommendations, source_digest, token usage and warnings. Dollar cost is explicitly unavailable. Pending jobs wait for worker capacity…
- [Search Brand Facts](https://docs.athenahq.ai/api-reference/knowledge-base/search-brand-facts.md): Semantic search over a website's approved brand facts. Combines vector similarity with full-text search, so it also reaches facts not filed under any pillar. It searches only facts the Knowledge Base shows; facts generated by Oracle analysis are excluded. Returns fact text with confidence, source UR…
- [Get Brand Facts](https://docs.athenahq.ai/api-reference/knowledge-base/get-brand-facts.md): Lists a website's brand facts, newest first, with offset paging. By default excludes facts generated by Oracle analysis; pass `include_oracle=true` to include them. Filter by pillar, review status (defaults to approved), source type, or `unfiled=true` for facts not under any published pillar. `unfil…
- [Get Pillars](https://docs.athenahq.ai/api-reference/knowledge-base/get-pillars.md): Lists a website's Knowledge Base pillars (excluding archived ones) with approved-fact counts, whether a synthesized document exists, and when each pillar was last researched. Also available as the MCP tool `get_pillars`.
- [Get Pillar Document](https://docs.athenahq.ai/api-reference/knowledge-base/get-pillar-document.md): Fetches a pillar's synthesized markdown document. Returns `document: null` when the pillar exists but has no synthesized document yet (this is a 200, not a 404). Also available as the MCP tool `get_pillar_document`.
- [Add Brand Facts](https://docs.athenahq.ai/api-reference/knowledge-base/add-brand-facts.md): Adds brand facts to a website's Knowledge Base in bulk (1-50 per call). Every fact runs the full ingestion pipeline — deduplication, approval gates, and pillar routing — and there is no way to force-approve: inputs are declarative (text, optional source URL, optional pillar pin) and the response rep…
- [Update Brand Fact](https://docs.athenahq.ai/api-reference/knowledge-base/update-brand-fact.md): Updates one brand fact's text, source URL, or confidence. Only provided fields change; pass source_url: "" to clear the stored source. Changing the text creates a new fact (new id) and archives the current one; the new fact keeps the current review status and is the fact returned. Source URL and con…
- [Delete Brand Facts](https://docs.athenahq.ai/api-reference/knowledge-base/delete-brand-facts.md): Permanently deletes 1-50 brand facts from a website's Knowledge Base. There is no undo. Ids with no fact on the website are reported in not_found_ids instead of failing the call, so retries are idempotent. Requires a website-admin API key; on OAuth MCP connections the signed-in user must hold the ad…
- [Move Brand Facts](https://docs.athenahq.ai/api-reference/knowledge-base/move-brand-facts.md): Files 1-50 brand facts under a published Knowledge Base pillar. Works for unfiled facts and re-files facts from other pillars. Review status never changes, and only approved facts under a published pillar feed content generation, so moving is what puts approved facts to work. Ids with no fact on the…
- [Create Pillar](https://docs.athenahq.ai/api-reference/knowledge-base/create-pillar.md): Creates a Knowledge Base pillar (a subject area that groups brand facts) from a name and optional description. Get-or-create semantics: if a pillar with the same name already exists (case-insensitive), it is returned with `created: false` instead of failing, so retries and re-imports are idempotent.…
- [Update Pillar](https://docs.athenahq.ai/api-reference/knowledge-base/update-pillar.md): Updates a Knowledge Base pillar's name, description, or status. At least one of the three must be provided; only provided fields change. Renaming returns a 409 when another pillar already uses the name. Status accepts published or archived: archiving hides the pillar from pillar listings and stops i…
- [Delete Pillars](https://docs.athenahq.ai/api-reference/knowledge-base/delete-pillars.md): Permanently deletes 1-20 Knowledge Base pillars and every fact filed under them. Facts are deleted, not unfiled; there is no undo. Ids with no pillar on the website are reported in not_found_ids instead of failing the call, so retries are idempotent; ids in failed_ids are untouched and safe to retry…
- [Merge Pillars](https://docs.athenahq.ai/api-reference/knowledge-base/merge-pillars.md): Merges 1-20 source pillars into a published target pillar: every fact on the sources (any review status) re-files onto the target, page links carry over keeping the stronger signal, and the source pillars are then deleted. The target must be a published pillar and must not appear among the sources.…
- [Create a pitch report](https://docs.athenahq.ai/api-reference/pitch-workspace/create-a-pitch-report.md): Generate a Pitch Workspace report from a public website URL. Requires a global organization API key, Pitch Workspace entitlement, and available pitch allowance. Returns a durable pitch ID while research runs. Poll GET /api/v1/pitches/{pitch_id} until pitch.status is completed or failed. The report U…
- [List Pitches](https://docs.athenahq.ai/api-reference/pitch-workspace/list-pitches.md): Returns all non-deleted pitch workspace reports for the calling organization, ordered by creation date (newest first). Pitches are org-level resources and are not scoped to a single website.
- [Get Pitch Report](https://docs.athenahq.ai/api-reference/pitch-workspace/get-pitch-report.md): Returns a single pitch report by ID, including the company metadata, generated prompts, tracked competitors, brand and competitor attributes, top citing sources, and aggregate metrics (brand mentions, sentiment, response rate).
- [List Sources (by root domain)](https://docs.athenahq.ai/api-reference/sources/list-sources-by-root-domain.md): 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`).
- [List Source Pages (per URL)](https://docs.athenahq.ai/api-reference/sources/list-source-pages-per-url.md): 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](/api-re…
- [List Groups](https://docs.athenahq.ai/api-reference/groups/list-groups.md): Returns all groups for your organization, including associated websites. Requires a global API key. **Partner integrations** may pass `external_id` as a query parameter to find the Athena group mapped to a partner-supplied identifier. Partner responses additionally include `externalId` on each group…
- [Create Group](https://docs.athenahq.ai/api-reference/groups/create-group.md): Creates a new group with associated websites. Requires a global API key. **Partner integrations** may include an `external_id` to map their own identifier onto the new Athena group.
- [Get Group](https://docs.athenahq.ai/api-reference/groups/get-group.md): Returns a single group by ID, including associated websites. Requires a global API key. **Partner integrations** additionally receive an `externalId` field populated from the partner mapping (if any), and every website object inside `websites` carries its own `externalId` (`null` when that website h…
- [Update Group](https://docs.athenahq.ai/api-reference/groups/update-group.md): Updates a group's name, adds websites, removes websites, and/or (partners only) sets or clears the `external_id` mapping. At least one field must be provided. Requires a global API key. **Partner integrations** may pass `external_id` as a non-empty string to set/replace the mapping, or as `null` to…
- [Create Invite](https://docs.athenahq.ai/api-reference/team-management/create-invite.md): Invites a user to your organization, a specific website, or a group. Use `invite_method: "direct"` to add the user immediately without sending any email — if the email has no existing account, a new user account is created automatically. Use `invite_method: "email"` to create a pending invite and se…
- [Bulk Invite to Websites or Groups](https://docs.athenahq.ai/api-reference/team-management/bulk-invite-to-websites-or-groups.md): Invites a user to multiple websites OR multiple groups in a single request. Provide exactly one of `website_ids` or `group_ids` — the two are mutually exclusive. Each target is processed independently, so some may succeed while others fail (e.g., if the user is already a member). In 'email' mode a s…
- [Revoke Organization Invite](https://docs.athenahq.ai/api-reference/team-management/revoke-organization-invite.md): Soft-revokes a **pending** organization invite by setting its status to `revoked`. The invite row is preserved for audit purposes. Returns 409 if the invite is in any other state (already accepted, declined, expired, or revoked), since revoking an accepted invite would leave a misleading audit trail…
- [Revoke Website Invite](https://docs.athenahq.ai/api-reference/team-management/revoke-website-invite.md): Soft-revokes a **pending** website invite by setting its status to `revoked`. Accepts a global API key, or a website-scoped key if the invite's target website is included in the key's allowlist and the key's creator is an Admin of that website. Returns 409 if the invite is in any other state. To rem…
- [List Organization Members](https://docs.athenahq.ai/api-reference/team-management/list-organization-members.md): Returns all members of your organization, including user details (email, first/last name) and their organization role. Requires a global API key.
- [List Website Members](https://docs.athenahq.ai/api-reference/team-management/list-website-members.md): Returns all users with access to a website — both organization members (implicit access to every website in the org) and users with explicit website-member rows. Each entry includes an `access_type` field (`organization` or `website`) so you can tell them apart. If a user has both an org membership…
- [List Group Members](https://docs.athenahq.ai/api-reference/team-management/list-group-members.md): Returns all users with access to a group. By default, the response merges **organization members** (implicit access to every group in the org) and users with explicit **group-member rows**, tagging each entry with an `access_type` field (`organization` or `group`). If a user has both an org membersh…
- [Look Up User By Email](https://docs.athenahq.ai/api-reference/team-management/look-up-user-by-email.md): Resolves a user's `user_id` from their email address, scoped to your organization. The email is sent in the request body (not the URL) so it never lands in request logs or analytics. Returns the user only when they belong to your organization — either as an organization member (`access_type: "organi…
- [List User Websites](https://docs.athenahq.ai/api-reference/team-management/list-user-websites.md): Returns the websites that a user has access to within your organization, either via organization membership (implicit access to all websites in the org) or via explicit website membership. Organization membership takes precedence — if the user is an org member, all non-paused websites in your organi…
- [Remove User From Websites](https://docs.athenahq.ai/api-reference/team-management/remove-user-from-websites.md): Batch-removes a user's explicit website memberships within your organization. Pass the website IDs as a comma-separated list in the `website_ids` query parameter (at most 100). Requires a global API key. Idempotent: websites where the user has no explicit membership are reported with status `not_a_m…
- [Update Organization Member Role](https://docs.athenahq.ai/api-reference/team-management/update-organization-member-role.md): Updates an organization member's role. Accepts either the coarse `role` (admin/viewer) or a `role_id` — a system role or one of your organization's custom roles (see `GET /api/v1/roles`); provide exactly one. Requires a global API key. Cannot modify the API key's owning user or the organization owne…
- [Update Website Member Role](https://docs.athenahq.ai/api-reference/team-management/update-website-member-role.md): Updates a website member's role. Accepts a global API key, or a website-scoped key if the website is included in the key's allowlist and the key's creator is an Admin of that website. Cannot be used to modify the API key's owning user or the organization owner.
- [Update Group Member Role](https://docs.athenahq.ai/api-reference/team-management/update-group-member-role.md): Updates the role of a user who was explicitly added to a group (a `group_members` row, shown as `access_type: "group"` by `GET /api/v1/groups/{group_id}/members`). Accepts either the coarse `role` (admin/viewer) or a `role_id`: a system role or one of your organization's custom roles (see `GET /api/…
- [Remove Group Member Access](https://docs.athenahq.ai/api-reference/team-management/remove-group-member-access.md): Removes a user's direct group membership and their explicit website memberships for websites currently in the group. Both sets of rows are removed atomically. The request is idempotent: a retry, or a well-formed user ID with no matching membership rows, returns `200` with `group_membership_removed:…
- [Remove Organization Member](https://docs.athenahq.ai/api-reference/team-management/remove-organization-member.md): Removes a user from your organization. Also cleans up any stray website_members rows for that user across all websites in the organization within a single transaction. Requires a global API key. Cannot remove the API key's owning user, the organization owner, or the last remaining admin.
- [Remove Website Member](https://docs.athenahq.ai/api-reference/team-management/remove-website-member.md): Removes a user's explicit membership from a website. Accepts a global API key, or a website-scoped key if the website is included in the key's allowlist and the key's creator is an Admin of that website. Cannot be used to remove the API key's owning user or the organization owner.
- [List Roles](https://docs.athenahq.ai/api-reference/team-management/list-roles.md): Returns all roles available in your organization: the built-in system roles (Admin, Editor, Viewer, Billing) plus your organization's custom roles, each with its resolved permission matrix. Use a role's `role_id` to assign it via invites or member role updates. Requires a global API key.
- [Create Custom Role](https://docs.athenahq.ai/api-reference/team-management/create-custom-role.md): Creates a custom role with a per-category permission matrix. Custom roles are available on the Enterprise plan. Every category is at least 'view' — omitted categories default to 'view'. The role name must be unique in your organization and must not collide with a system role name; the permission mat…
- [Get Role](https://docs.athenahq.ai/api-reference/team-management/get-role.md): Returns a single role — a system role or one of your organization's custom roles — with its resolved permission matrix. Requires a global API key.
- [Update Custom Role](https://docs.athenahq.ai/api-reference/team-management/update-custom-role.md): Updates a custom role's permission matrix. Every category is at least 'view' — omitted categories default to 'view'. System roles cannot be edited. The new matrix must not duplicate an existing role's. Requires a global API key.
- [Delete Custom Role](https://docs.athenahq.ai/api-reference/team-management/delete-custom-role.md): Deletes a custom role. System roles cannot be deleted, and a role that is still assigned to members or pending invites (or set as a default role) cannot be deleted. Requires a global API key.
- [Get Website Credits](https://docs.athenahq.ai/api-reference/billing/get-website-credits.md): Returns the current credit balance for a specific website.
- [Get Organization Credits](https://docs.athenahq.ai/api-reference/billing/get-organization-credits.md): Returns the current credit balance for your organization.
- [Get Group Credits](https://docs.athenahq.ai/api-reference/billing/get-group-credits.md): Returns the current credit balance for a specific group. Requires a global API key.
- [Get Website Subscription](https://docs.athenahq.ai/api-reference/billing/get-website-subscription.md): Returns the subscription products for a specific website, including their status and billing dates.
- [Cancel Subscription](https://docs.athenahq.ai/api-reference/billing/cancel-subscription.md): Cancels a subscription for a specific website. The subscription will remain active until the end of the current billing period.
- [AI Access](https://docs.athenahq.ai/api-reference/ai-access.md): Compare robots.txt policies with observed responses to AI crawler user-agent probes.
- [Check AI accessibility for a domain](https://docs.athenahq.ai/api-reference/ai-access/check-ai-accessibility-for-a-domain.md): 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 acce…

## OpenAPI Specs

- [openapi](/api-reference/openapi.json)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.