MCP Server

Connect AthenaHQ to ChatGPT, Claude, and other AI assistants via the Model Context Protocol

AthenaHQ ships a remote Model Context Protocol (MCP) server. Once connected, an AI assistant like Claude or ChatGPT can query your AI search visibility data in plain language (share of voice, citation and mention rates, ranking positions, cited sources, tracked prompts and responses, content, and pitches) without you writing any API calls.

Connections you sign in to (Claude.ai and ChatGPT) follow your account’s access permissions, with the Claude response-data exclusions described below. Write tools are available on API-key connections and, for signed-in connections, wherever your role has the matching write permission. Every write runs the same validation and audit logging as the dashboard.

Server URL

https://api.athenahq.ai/api/mcp

​

Source tags

Use source_tags__list, source_tags__get_sources, source_tags__create, source_tags__update, and source_tags__delete to work with source tags. A website sees three kinds: Owned and Competitor (set from brand and competitor identifiers), built-in tags AthenaHQ classifies automatically (Media, Social, Government, E-Commerce, Review sites, PR Wire, Academic and research, Wiki), and the website’s custom tags. These are separate from prompt tags. All tools require website_id and respect API-key website scopes or your account’s Analytics permissions. Reading needs view access; writes need write access.

source_tags__list returns every tag with its kind, icon, colour, revision and patterns: a custom tag’s own patterns, or, for a built-in tag, only what this website added or removed from it. The platform’s own patterns are never listed. Use offset and limit for tag pagination, or tag_id, pattern_offset, and pattern_limit to page one tag’s patterns.

source_tags__get_sources lists cited domains with citation counts: the domains one custom tag matches (tag_id), or, with untagged: true, the domains no tag covers at all. Built-in tags and Owned/Competitor are refused as tag_id; add or remove patterns on them instead.

source_tags__update edits a tag with the current expected_revision. On a custom tag it accepts name, add_patterns, and exact remove_patterns. On a built-in tag it adds patterns to this website’s copy or removes patterns from it: an addition is accepted only when the pattern does not already carry the tag here, a removal only when it does (by a platform rule, by automatic classification, or by your own addition). Built-in tags cannot be renamed. source_tags__create creates a custom tag with patterns and optional icon and colour; names of built-in tags are reserved. source_tags__delete removes a custom tag and its assignments while retaining source records; built-in tags cannot be deleted. Patterns support hosts, subtrees (*.example.com), path sections, exact pages, and query constraints; at most 500 per list.

Update and delete advertise destructive-action hints and ask the assistant to obtain explicit confirmation. Your MCP client controls approval prompts; these hints do not enforce a confirmation dialog. Authorized MCP calls execute immediately. Athena AI chat retains its approval cards. If analytics_refreshed is false, the write succeeded but filtered analytics may still be cached; do not repeat the write to refresh analytics. These tools do not add REST endpoints.

​

Outreach

Outreach finds the authors of pages that AI answers cite and drafts a pitch to each. Five tools cover the same work as the Outreach page:

• list_outreach_contacts reads saved contacts: status, author, email and its source, LinkedIn, contact page, and draft. Only pages someone has triaged, enriched or drafted are listed; find other cited pages with get_source_pages. Filter by url or statuses; page with offset and limit (default 20, at most 50).
• find_outreach_author reads a page’s byline, the addresses the page publishes, and Hunter.io, then saves the result. When no author is found it saves any site contact address or contact page it finds instead.
• draft_outreach_message writes a pitch for a page and saves it as the page’s draft. It uses the website’s team-wide custom instructions (set on the Outreach page), the saved author name, and the signed-in user’s name; API-key connections can pass sender_name. Nothing is sent.
• update_outreach_contact edits the author name, email, LinkedIn, subject or body. Supply at least one field; only the fields you supply change, and null clears one. Changing the author to a different person also clears the previous author’s email and LinkedIn unless you supply new ones.
• set_outreach_status moves up to 100 pages to New, Todo, In Progress, Done or Rejected, and records each change to an existing contact in its Activity. A page without a contact gets one at the new status, with no Activity entry yet; New only resets existing contacts.

Each email carries an email_source: page_author (published on the page and matching the author), page_contact (the site’s own address, which may not reach the author), hunter (a Hunter.io match the page does not publish; check it before sending) or manual. It is null when the source is unknown, as for emails saved before sources were recorded. page_emails lists up to five addresses the page or its linked contact page publishes, the chosen one first, so you can compare them with the chosen one; it is not a complete inventory.

Pages are identified by url in the form the Outreach feed stores, such as example.com/blog/post. A contact already saved under the exact URL you pass is used first, such as one the Outreach page saved for a query variant that the website’s URL rules list separately. Otherwise protocol, www. and the query string (for example utm_ tracking parameters) are ignored, as on the Outreach page. The page is always read at the URL you pass. All tools require website_id and Content permissions: view access to list, write access for the rest. find_outreach_author costs 0.1 credits when it finds an author and draft_outreach_message 0.1 credits per draft, billed as whole credits every 10 successful rows, the same as the Outreach page. These tools do not add REST endpoints.

​

Public AI crawler access

check_public_ai_access checks a public HTTPS domain without an AthenaHQ account. Pass { "domain": "example.com" }, with no path, credentials or custom port. The response includes nullable per-agent evidence, request diagnostics and a diagnostic log. Search, user retrieval and training have separate roles. Google-Extended is policy-only and receives no HTTP probe.

The ChatGPT extension opens from supported sidebar and thread surfaces. It shows HTTP responses and robots permissions, restores tool-result reports, follows the host theme, and supports copy, export and explicit report sharing. Requests originate from AthenaHQ using crawler user-agent strings, not verified crawler IPs. Unknown observations stay inconclusive. These checks do not measure visibility or guarantee real crawler access, indexing or citation.

Public scans are limited to five per minute per hashed ingress IP. Anonymous MCP requests have a separate limit of 60 per minute and 512 KiB per request; batches are rejected. Account analytics and writes retain authentication, scopes and audit checks. The authenticated check_ai_access tool and partner POST /v1/ai-access/check contract retain their existing behavior.

When you call an account tool without credentials, the server returns HTTP 401 with a WWW-Authenticate header pointing to its OAuth resource metadata. The response also retains the tool-level _meta["mcp/www_authenticate"] challenge. Your client can use either signal to start sign-in, then retry the tool call. Initialization, tool discovery, and public crawler tools remain available without sign-in.

​

Date-range inputs

MCP tools with filters.start_date and filters.end_date accept these formats:

Format	Examples
Year first	2026-09-29, 2026/9/29, 2026.9.29
English month name	September 29, 2026, Sep 29 2026, 29 September 2026, 29-Sep-2026
Unambiguous numeric date	09/29/2026, 29/09/2026, 29-09-2026, 29.09.2026
ISO 8601 timestamp	2026-09-29T12:30:00Z, 2026-09-29T12:30:00-07:00

Dates are normalized before querying. Date-only inputs keep their calendar day; timestamps preserve their instant and are normalized to UTC. An ISO timestamp without a timezone is interpreted as UTC. A date-only start begins at midnight UTC; a date-only end includes that day through 23:59:59.999Z. Explicit end timestamps keep their exact instant, including midnight. Omitting end_date keeps the tool’s existing default.

Invalid calendar dates, incomplete dates, relative expressions such as yesterday, and ambiguous numeric dates such as 03/04/2026 return a validation error instead of empty results. Spell out the month or use YYYY-MM-DD to resolve ambiguity. Use four-digit years. An explicit end must not precede the start.

This flexibility applies to the shared MCP date-range filters, including metrics, responses, sources, and content analytics. Partner REST inputs, activity-feed timestamps, and generic cube query predicates retain their documented formats.

​

Connect Claude.ai

Connect from the AthenaHQ listing in Claude’s connector directory. No API key needed. You sign in with your AthenaHQ account.

The Claude connector excludes individual Claude-generated responses and response-level records derived from them by provider policy. You can use it to explore responses from other AI platforms, such as ChatGPT. Aggregate analytics, such as visibility totals and attribute metrics, can still include Claude data. To view individual Claude responses, use the AthenaHQ dashboard or the REST API with an API key.

On Claude Team plans, an Owner or Primary Owner must enable the connector for your organization before you can connect your account. On Enterprise plans, users with a custom role that includes Manage access to Libraries can also enable it.

1. Connect AthenaHQ

   Open the AthenaHQ connector listing in Claude and follow the connection prompts. You can also find AthenaHQ under Customize > Connectors.

2. Sign in and pick an organization

   You’ll be prompted to sign in with your AthenaHQ account and choose which organization to connect. Claude then discovers all available tools automatically.

3. Ask about your AI search performance

   In a chat, open + > Connectors and enable AthenaHQ for the conversation. Ask a question such as “Use AthenaHQ to compare our share of voice with competitors over the last 30 days.” Claude pulls your AthenaHQ data into the conversation. Review and approve tool requests when prompted.

Try questions like:

• “How visible is our brand in AI search over the last 30 days?”
• “What is ChatGPT saying about our brand in our tracked responses?”
• “Which competitors gained share of voice over the last month?”
• “Which pages are getting cited, and where should we focus next?”

Prefer a manual setup? In Claude, open Customize > Connectors and add a custom connector named AthenaHQ with the server URL https://api.athenahq.ai/api/mcp. Follow the authentication prompts to sign in with your AthenaHQ account and choose an organization. On Team and Enterprise plans, an Owner or Primary Owner must add the connector first; Enterprise users with Manage access to Libraries permission can also add it. See Claude’s custom connector guide for the steps for your plan.

​

Connect ChatGPT

The fastest way is the official AthenaHQ plugin. No API key needed. You sign in with your AthenaHQ account.

​

Does the plugin have a separate cost?

From AthenaHQ, the plugin is free to install and has no separate plugin cost. It uses your existing AthenaHQ account, and normal plan limits still apply to the features and actions you access. Plugin availability in ChatGPT depends on your OpenAI plan, workspace settings, role, and region.

1. Install the plugin

   Open the AthenaHQ plugin listing in ChatGPT and click Install plugin.

2. Sign in and pick an organization

   Authorize with your AthenaHQ account and choose which organization to connect.

3. Mention @AthenaHQ in a chat

   Type @AthenaHQ followed by your question, for example “@AthenaHQ how is my brand showing up in AI search?”, and ChatGPT pulls your data into the conversation.

Prefer a manual setup? You can still add the MCP server as a custom connector: in ChatGPT Settings, add a custom MCP connector (found under Apps or Connectors, depending on your plan and version), enter https://api.athenahq.ai/api/mcp, and sign in with your AthenaHQ account. Custom connectors require a plan that supports them (Pro, Business, or Enterprise) and may need developer mode enabled.

​

Connect Optimizely Opal

You need the Opal administrator role to register a remote MCP provider.

​

Sign in with OAuth

1. In Opal, open Tools > External Providers > Add Remote MCP Provider.
2. Enter https://api.athenahq.ai/api/mcp, select OAuth 2.0, and click Discover OAuth Endpoints.
3. Leave Use my own credentials off so Opal uses Dynamic Client Registration. AthenaHQ issues a client ID automatically; you do not need a pre-issued client ID or client secret.
4. Leave scopes empty. AthenaHQ advertises no OAuth scopes. Do not enter the placeholder values your-client-id or scope1,scope2,scope3.
5. Enter a unique provider name and register it. Complete Opal’s approval steps, then connect from Tools > Connectors and sign in to AthenaHQ to choose your organization.
6. Select the tools to add. To use them in Opal Chat, enable Enable for Chat in Tools > Tools.

​

Connect with an API key

If you prefer a shared API-key connection, create a key on the API Keys page. Scope it to the websites Opal should access.

1. Register a remote MCP provider with the same server URL.
2. Select Bearer token and paste the complete AthenaHQ API key into Bearer Token, without adding the word Bearer.
3. Complete registration, add the tools, and enable them for chat as needed.

Opal sends the key as Authorization: Bearer <api-key>. The connection uses the key’s organization and website permissions, including write access within that scope. Delete the key in AthenaHQ to revoke access.

See Optimizely’s remote MCP setup guide for its provider approval and tool setup steps.

​

Connect other MCP clients

Clients that don’t support the sign-in flow authenticate with an API key using either x-api-key: <api-key> or Authorization: Bearer <api-key>. Bearer API-key authentication is supported on /api/mcp; REST endpoints under /api/v1 require x-api-key.

1. Create an API key

   Go to the API Keys page in your dashboard. Scope the key to specific websites if you want to limit access, then save it securely.

   Manage API Keys

   Create, view, and manage API keys in your organization settings

2. Add the server to your client config

   Replace your_api_key_here with your key.

   {
     "mcpServers": {
       "athenahq": {
         "type": "http",
         "url": "https://api.athenahq.ai/api/mcp",
         "headers": {
           "x-api-key": "your_api_key_here"
         }
       }
     }
   }
   

​

Claude Code

claude mcp add --transport http --scope user athenahq https://api.athenahq.ai/api/mcp \
  --header "x-api-key: your_api_key_here"

​

Access and scope

An MCP connection sees exactly what its credential is authorized for, the same scoping as the REST API:

• Organization and website access follow the signed-in user (Claude.ai) or the API key’s scope.
• A website-scoped API key is limited to its websites. The existing get_credits_organization balance tool also allows scoped keys to read its organization-wide aggregate. Detailed usage tools (get_credit_usage and get_credit_usage_events) require a global organization API key, or a signed-in user with organization billing access. Website/group-only membership is insufficient for these usage tools.
• Write tools register on API-key connections and on signed-in connections bound to an organization. On a signed-in connection, each write is gated by your role’s permission for that category (see the Write tools table); API keys act with admin privileges within their scope. Every write runs the same validation and audit logging as the dashboard.

Only organization admins can create, edit, or delete API keys. On signed-in connections, tools follow your role: a viewer can read everything below except the three org-wide admin reads (get_groups, get_group_detail, get_user_by_email) and the credit-usage tools, which require organization billing access. Viewers can only use writes open to every member (such as create_saved_view).

​

Available tools

The assistant discovers these automatically once connected. Most map to an endpoint in the API reference.

​

Metrics

Tool	What it returns
get_share_of_voice_cumulative	Share of voice across competitors for a date range
get_share_of_voice_time_series	Share of voice over time (daily)
get_citation_rate_cumulative	Citation rate (how often AI answers link to you) across competitors
get_citation_rate_time_series	Citation rate over time (daily)
get_mention_rate_cumulative	Mention rate (how often AI answers name your brand) across competitors
get_mention_rate_time_series	Mention rate over time (daily)
get_position_cumulative	Average ranking position in AI answers for a date range
get_position_time_series	Ranking position over time (daily)
get_position_distribution	Share of responses where the brand ranks top, middle, or bottom
get_ai_search_value	AI search value: topic-market value, captured value, headroom, coverage, per-topic detail
get_shopping_metrics	Shopping Insights: product appearances in AI shopping answers, positions, prices, rivals

​

Analytics queries

Flexible query tools over the same analytics warehouse the dashboard uses, for questions the fixed metrics tools don’t cover.

Tool	What it returns
query_metrics	Aggregated measures (count, avg, sum, min, max) over any cube, grouped by the dimensions that cube allows, with optional period-over-period comparison
query_rows	Individual rows (response text, identifiers, mentions) from any cube, with cursor pagination

​

Brand traits

Brand-perception keywords (like “Affordable” or “Slow Support”) extracted from AI answers. The API and tool names call them attributes.

Tool	What it returns
get_attributes	Brand traits tracked for a website, with attribute IDs
get_attribute_metrics	Per brand trait, how many responses mentioned it across a date range
get_competitor_attribute_metrics	The same breakdown per tracked competitor
get_attribute_time_series	Daily trend for one brand trait, brand and competitors side by side
get_attribute_observations	Individual brand trait observations with the response excerpt and a score from -1 to 1

​

Prompts and responses

Tool	What it returns
get_prompts	Tracked prompts for a website, with volume, status, and geography
get_prompt_tags	Prompt tags for a website, with per-tag prompt counts
get_personas	Personas configured for a website, with per-persona prompt counts
get_topics	Active topics for a website, with the count of active prompts in each
get_responses	AI answers for a website, with cited sources, sentiment, and ranking. Set include_response: false and compact_sources: true for a light variation-level export
get_response_detail	One AI answer with full sources, mentions, and rank details
get_response_streaming_status	State and queue progress of the latest (or a specific) response run

​

Content

Tool	What it returns
get_tracked_content	Tracked content with citation, mention, and impression metrics
list_content	Every content item, published or not, each with the ids of the prompts it targets
get_content_detail	Full text of one content item: brief, body, cited URLs, links, status, and the prompts it was written for
get_content_citation_prompts	Prompts whose AI answers cited a given content item
get_content_hub_sheets	Content Hub tabs configured for a website
get_content_status	Normalized generation status (running / succeeded / failed) for one content item
get_content_draft	Current draft text of one item: article body, brief, status, latest version
get_content_versions	Version history of a content item, newest first, with labels and authors
get_content_version	Full text of one saved version

Two of these answer different questions about the same page, and it is worth keeping them apart. get_content_detail and list_content return the prompts a page was written for (its targeting, the same ids create_content takes); that comes from the content record and does not depend on any AI answer having appeared. get_content_citation_prompts returns the prompts whose AI answers cited the page over a date range, so it is legitimately empty for a page nothing has cited yet.

Targeting includes prompts that were later deleted, flagged status: "deleted", because the page was still written for them and the Content Hub still shows them. get_prompts does not list deleted prompts, so an id from a targeting list may not resolve there; get_content_detail returns the prompt text inline for that reason. Targeting is capped at 100 entries per page (25 ids per row in list_content), with the untruncated size in prompts_total / prompt_count.

For an optimize item, get_content_detail also returns source_url: the live page it is based on, available as soon as the item exists. url stays null until publish_content records the published page and marks the item done, so read source_url to link a request in review to its page without publishing it. list_content does not carry this field.

​

Knowledge Base

Requires the Knowledge Base to be enabled for the organization; when it isn’t, these tools return an error explaining that.

Tool	What it returns
search_brand_facts	Semantic search over approved brand facts, including facts not filed under any pillar
get_brand_facts	Paged brand-fact listing with pillar, review-status, source-type, and unfiled filters
get_pillars	Knowledge Base pillars with approved-fact counts and synthesized-document availability
get_pillar_document	A pillar’s synthesized markdown document

​

Brand kits

The voice and style guidance content generation follows (Brand Profile > Brand kits). Needs a paid plan; the writing rules also need the writing rules feature.

Tool	What it returns
get_brand_kit	A brand kit as the editor shows it: the draft name, the eight guidance fields as text, voice settings, tone traits, the kit’s and the website’s global writing rules with ids, and the draft and published versions

​

Sources and competitors

Tool	What it returns
get_sources	Top cited root domains, classified as owned / competitor / partner / third-party
get_source_pages	Individual cited URLs with per-URL metrics
get_competitors	Competitors tracked for a website
get_identifiers	Names, aliases and domains counted as mentions of your brand or a competitor

​

Outreach

Tool	What it does	Sign-in permission
list_outreach_contacts	Saved Outreach contacts with author, email and its source, and draft	Content: view
find_outreach_author	Find and save a cited page’s author and email, or the site’s contact page	Content: write
draft_outreach_message	Draft and save a pitch with the team’s custom instructions	Content: write
update_outreach_contact	Edit a contact’s author, email, LinkedIn, or draft	Content: write
set_outreach_status	Move pages between Outreach pipeline statuses	Content: write

​

Pitches

Tool	What it returns
list_pitches	Pitch reports for the organization
get_pitch	One pitch report: competitors, prompts, attributes, top citing sources, metrics

​

Account and configuration

Tool	What it returns
list_websites	Websites your credential can access, with the country market each targets (baseCountry)
get_groups	Groups in the organization (global API key or org-admin sign-in)
get_group_detail	One group with its member websites (global API key or org-admin sign-in)
get_user_by_email	User lookup by email, scoped to the caller’s organization (global API key or org-admin sign-in)
get_date_range	Earliest and latest response dates for a website
get_locations	Geographies configured for a website
get_saved_views	Saved filter presets for a website
get_group_saved_views	Saved views shared across a group
get_credits_website	Credit balance for a website
get_credits_organization	Credit balance for the organization
get_credit_usage	Credit usage totals, time buckets, and paginated charged-pool breakdown for the organization
get_credit_usage_events	Paginated credit charges/refunds, recorded actions, and originating-website attribution

Credit-usage tools accept website_id to identify the organization, an optional range (24h, 7d, 30d, 90d, or all), and an optional UTC window with start_at_utc and end_at_utc. Use an explicit window for calendar months. For subsequent pages, keep the returned window and use next_offset; page sizes default to 25 and are capped at 50. get_credit_usage_events also accepts originating_website_id within the same organization.

Totals describe the full requested interval; entity and event pages may be partial. Charged group pools differ from originating websites, negative credits are refunds, and “Not recorded” means historical attribution is unavailable. These are read-only MCP tools; they add no public REST endpoints.

​

Prompt discovery

Tool	What it does	Sign-in permission
start_prompt_discovery	Start an asynchronous Discover study for untracked prompt opportunities	Prompts: write
find_more_prompt_discovery	Start the next round of a finished study to find more prompts	Prompts: write
get_prompt_discovery_runs	Read visible discovery history or one run’s progress	Prompts: view

To start a study, supply website_id, a name, and at least one source: website_analysis, social, search_console, keyword_gaps, competitive_landscape, or brand_guidelines. You can specify country, language, prompt_count_range with min and max, and custom_instructions. The default locale is en-US, the default country is United States, and the default prompt-count target is 25 to 50. Current count bands are 25 to 50, 50 to 75, 75 to 100, 100 to 150, and 150 to 200. Selecting brand_guidelines requires non-empty custom instructions. Keyword gaps and Competitive landscape retain their plan restrictions. Competitive landscape also requires at least one tracked competitor, and Search Console requires a connected integration to supply evidence.

Review the sources, locale, requested count and instructions before launching. Launch uses external research services and AI models. Your MCP client handles invocation confirmation; Athena’s in-app chat approval card is not displayed over MCP. The requested count is a target, not a guarantee, and discovery does not add prompts to tracking automatically.

Startup returns run_id and version. Pass that ID as run_id to get_prompt_discovery_runs to poll the same study; do not start a second study to check progress. Without run_id, the tool returns recent history. limit defaults to 10 and is capped at 20. Status is pending, running, completed, partial, failed, or cancelled; results include progress_percentage, the current phase when available, and total_prompts. A finished run also carries reason_code, the terminal reason of a completed run or the error code of a failed one, and reason, a sentence safe to show the user that explains a failed, empty or short run, the same line the Discover page shows. Both are null when there is nothing to explain. rounds counts the rounds of a study continued with find_more_prompt_discovery (1 for a study never continued); status, progress and reason then describe the latest round, and total_prompts adds every round. can_find_more says whether another round can start now, and find_more_reason explains why not when one cannot. Review candidate prompts on the application’s Discover page. These tools do not send notifications or add public REST endpoints.

To find more prompts for a finished study, pass its run_id (or the run_id of any finished round that continues it) to find_more_prompt_discovery with its website_id. The new round repeats the study’s sources, country, language, prompt-count target and custom instructions, skips every question the earlier rounds suggested, and reads evidence they did not use. Each round runs the same research as a new study, so confirm with the user first. A study takes one round at a time and at most two after the first run, and ends early after a round that found fewer than ten new prompts or nothing new to read; the tool then returns an error with the reason. The response is the new round’s run_id and version; poll it with get_prompt_discovery_runs as for a new study.

​

Site Health

Site Health (site_health section) needs the feature on the website’s plan; without it every tool below returns a 403. Start with get_site_health_issues: one group per kind of problem, with the pages it affects and each page’s finding_id and task_revision. Over MCP a call returns at most 25 groups and a group carries at most 10 sample pages; get_site_health_issue_pages walks the rest, 50 at a time, and its page 0 repeats the sample pages.

Tool	What it returns
get_site_health_issues	Issues grouped by check: title, why it matters, severity, priority, owner, effort, page counts by status (open, in_progress, fixed, verified, dismissed), the sections they concentrate in, and sample affected pages with detail, recommendation, evidence and assignee. Filter by status, check, search, page URLs or assignee: "me".
get_site_health_issue_pages	Every page one issue affects, 50 per page, with each page’s finding, evidence, dates and task revision.
get_site_health_analytics	Live GA4, Search Console and AI-citation figures for the last 28 days beside the 28 before: AI sessions, organic and total sessions, clicks, impressions, CTR, position, top queries, pages and sources, and the website’s most cited pages.
get_site_health_properties	The crawl scopes Site Health audits, each with its live page count and latest crawl or audit run.
get_site_health_pages	A property’s audited pages, 50 per page, with last audit status, open finding count and priority flag; groups counts every open check on the property.
get_site_health_page	One page’s measurements (title, meta description, canonical, status code, word count, indexability, rendering comparison, Core Web Vitals), its audit history and every finding on it with its verification.

​

Site diagnostics

Tool	What it returns
check_ai_access	Robots.txt policies and observed crawler user-agent responses from Athena’s network. Use result.evidence for nullable per-agent results and separate search/training; failed or challenged probes mean unknown access. No guarantee of real crawler access, indexing or citations. Includes a diagnostic log for host or CDN tickets. API-key connections only.

​

Write tools

Available on API-key connections and on signed-in connections bound to an organization. On a signed-in connection, each tool follows your role’s permission for its category (rightmost column); API keys act with admin privileges within their scope. Every write is validated and audit-logged, same as the dashboard.

To create a prompt tag, call create_prompt_tag with website_id and tag. The result includes tag_id. Tag names are trimmed, and an existing case-insensitive match returns created: false.

Before changing assignments, call get_prompts with the same website_id and find the target prompt by its id. Its tags array contains the current assignments as { id, name } entries. Build the full desired tag_ids list from those IDs: add the new tag_id to assign it, or remove a tag’s ID to unassign it, keeping all other IDs. Call set_prompt_tags with website_id, that prompt’s prompt_id, and the resulting tag_ids. Pass an empty list only when you want to clear all tags. Repeat this read-and-update process for each prompt.

Identifiers are the names, aliases and domains Athena looks for in AI responses to count a mention. Before changing them, call get_identifiers with website_id, plus the competitor_id from get_competitors for a competitor (omit it for your own brand). default_identifiers, the name and domain, are always matched and cannot be removed. Then call update_identifiers with the same ids and add and remove lists. The rules are the Competitors page’s: a value that is already listed, or that another tracked brand or competitor on the website already uses, is refused and nothing is saved. New responses use the change right away. Past responses are reanalyzed only when someone runs the backfill on the Competitors page, which costs credits; changes_awaiting_backfill counts the edits waiting for it.

A brand kit is edited as a draft and used by content generation only once published. Call get_brand_kit with website_id, and kit_id for a kit other than the default, to read the draft text, the rule ids and the versions; pass fields to read a clipped guidance field whole. Then call update_brand_kit with the kit_id and only what changes: name; guidance entries with a field and the new text, plus find to replace one passage that occurs exactly once in the text you read; voice_settings with values 1 to 5 or "auto"; rules with add, update by id and remove by id. Edits save to the draft; publish: true also publishes it as a new version, which the Brand Profile page can restore from. The result’s outcome is saved, saved_and_published, or saved_publish_failed with the reason in publish_error. A rule that contradicts an existing kit or global rule, a name another kit uses, and a kit still generating are refused and nothing is saved. Kit rules need the writing rules feature on the plan. The tool does not change global rules.

Global writing rules, the ones the Global rules tab holds and every kit follows, are changed with update_global_rules: website_id plus add, update by id and remove by id, with the ids from get_brand_kit’s global_rules. There is no draft: the change is live for all future content as soon as it is saved, as a new version the Global rules tab’s change history can restore. The same conflict check applies, and the feature requirement is the same.

To create a kit from material you already have, call create_brand_kit with website_id, a name unique on the website, and the guidance entries, voice_settings and rules you author from it; nothing is generated. The kit starts as a draft; publish: true publishes it as version 1, and the website’s first kit becomes its default. Generating a kit from the website or uploaded documents stays on the Brand Profile page.

To track new competitors, call add_competitors with website_id and 1 to 25 competitors, each with a name and its website url, or no_website: true for a brand without a website, plus optional identifiers and additional_urls. Each competitor gets its own result: added with its competitor_id, already_tracked when the website already tracks that URL (nothing changes), or rejected with a reason, such as a URL on your own domains or the limit of 500 competitors per website. To stop tracking competitors, call remove_competitors with up to 25 competitor_ids from get_competitors; each result is removed, no_change (already removed) or not_found. Removal keeps past mentions and citations, and the Competitors page can restore the competitor. Neither tool reanalyzes past responses or spends credits: that backfill stays on the Competitors page.

Tool	What it does	Sign-in permission
create_prompts	Create one or more prompts, with topics, tags, personas, and geography	Prompts: write
update_prompt	Update a prompt’s text, type, topic, or geography	Prompts: write
create_prompt_tag	Create a prompt tag, or return an existing tag with the same name (case-insensitive)	Prompts: write
set_prompt_tags	Replace one prompt’s tag assignments, or clear them with an empty list	Prompts: write
set_prompts_status	Pause or unpause multiple prompts in one call	Prompts: write
delete_prompt	Delete a prompt (soft when responses exist, hard otherwise)	Prompts: write
create_topic	Create a topic (returns the existing topic when the name is taken)	Prompts: write
update_topic	Update a topic’s name or description	Prompts: write
delete_topic	Delete a topic, optionally with its prompts	Prompts: write
create_location	Create a geo-location, optionally attached to prompts	Prompts: write
update_location	Update a location	Prompts: write
delete_location	Delete a location	Prompts: write
update_identifiers	Add or remove identifiers on your brand or a competitor (no backfill, no credits)	Competitors: write
add_competitors	Track up to 25 new competitors, with a result for each (no backfill, no credits)	Competitors: write
remove_competitors	Stop tracking up to 25 competitors, with a result for each (no backfill, no credits)	Competitors: write
start_response_streaming	Start a response run for all prompts or a selection	Prompts: write
start_prompt_discovery	Start a Discover study with selected sources, locale and optional instructions	Prompts: write
find_more_prompt_discovery	Start the next round of a finished Discover study, skipping what earlier rounds suggested	Prompts: write
create_content	Start the content pipeline (brief or full article, from a prompt or a topic)	Content: write
add_content	Add an already written article as an editable draft (no generation, no credits), as version 1	Content: write
revise_brief	Rewrite a content brief from an instruction, recorded as a version	Content: write
approve_brief	Approve a brief and start the article from it (uses content credits)	Content: write
revise_content	Rewrite an article draft from an instruction, recorded as a version	Content: write
edit_content	Apply exact find-and-replace edits to a draft (deterministic, no AI model), recorded as a version	Content: write
restore_content_version	Bring an earlier version’s text back as the current draft (appends, never deletes)	Content: write
publish_content	Mark a piece as live at its URL so citation tracking starts	Content: write
track_content_urls	Register existing or third-party URLs as tracked pages (batch, idempotent, no credits)	Content: write
rename_content	Rename a content row	Content: write
move_content	Move content items between sheets (values on conflicting custom columns are permanently dropped)	Content: write
delete_content	Delete a content row (permanent, no undo)	Content: write
add_brand_facts	Add 1-50 brand facts through the full ingestion pipeline, with a per-fact outcome report	Brand knowledge: write
update_brand_fact	Update one brand fact’s text, source URL, or confidence	Brand knowledge: write
delete_brand_facts	Permanently delete 1-50 brand facts (no undo; missing ids reported, not errors)	Admin role
create_pillar	Create a Knowledge Base pillar (get-or-create by name)	Brand knowledge: write
update_pillar	Update a pillar’s name or description, or publish/archive it	Brand knowledge: write
delete_pillars	Permanently delete 1-20 pillars and every fact filed under them (no undo)	Admin role
merge_pillars	Merge source pillars into a published target, then delete the sources	Brand knowledge: write
move_brand_facts	File 1-50 facts under a published pillar (works for unfiled facts)	Brand knowledge: write
update_brand_kit	Change a brand kit’s name, guidance text, voice settings or rules in its draft, and publish on request	Brand knowledge: write
update_global_rules	Add, update or remove the global writing rules every kit follows (live immediately, restorable from change history)	Brand knowledge: write
create_brand_kit	Create a brand kit from text you provide (name, guidance, voice settings, rules), as a draft or published as version 1; no generation	Brand knowledge: write
update_site_health_task	Assign one Site Health finding or set its work status (todo, in_progress, ready_to_verify, dismissed); needs the page’s finding_id and task_revision; unassign: true clears the assignee; signed-in connections only	Analytics: write
update_site_health_issue	Set the status or assignee of a whole Site Health issue, every unresolved page of one check at once; unassign: true clears every page; signed-in connections only	Analytics: write
start_site_health_audit	Audit a Site Health property: full (crawl, then every page), a sample, or 1 to 100 named pages to verify a fix	Analytics: write
create_saved_view	Save a dashboard filter preset (name, optional icon, filters object up to 64KB, stored verbatim)	Any member

The two Site Health task writes need a signed-in connection: the task row records who changed it and a newly assigned teammate is told who assigned them, and an API key stands for no one, so API-key connections are not offered them. start_site_health_audit works on API-key connections.

create_saved_view is the one write open to every website member, since saved views are personal presets: sign-in creations are attributed to the connected user, while API-key creations have no owning user, show as created via API in the dashboard, and can only be edited or deleted there by website admins. create_saved_view, move_content and add_content are the three write tools with no REST equivalent.

delete_brand_facts and delete_pillars are the two writes gated on your role itself rather than a category permission: deleting brand knowledge matches the dashboard’s admin-only delete, and deleting a pillar permanently deletes every fact filed under it. An Editor with brand-knowledge write can update facts, curate pillars, and merge them, but not delete. API-key connections qualify through their admin scope.

​

Example prompts

Once connected, try:

• “What’s my share of voice in AI answers versus my tracked competitors this quarter?”
• “Which domains get cited most for the prompts I track?”
• “Show my citation rate trend over the last 90 days.”
• “What’s my captured AI search value and headroom by topic?”
• “Pull the AI responses that mention my brand and summarize their sentiment.”