AthenaHQ

Add brand facts to a website's Knowledge Base in bulk (1-50 per call). Each fact runs the full ingestion pipeline (deduplication, approval gates, pillar routing); there is no way to force-approve. Returns one outcome per fact (approved | pending | duplicate; extensible) with the created fact id and the pillar it was filed under. Facts without a pillar_id are routed automatically and may land unfiled. A fact similar to facts already in the Knowledge Base is not added: its outcome is duplicate and lists them under matches, and the response carries a match_token. To resolve, call again with those facts, the match_token, one decision per listed match (approve, optionally with new text, or delete) and save_submitted (true adds the facts as written, false only applies the decisions).

Add an article that is already written (for example, one drafted in this conversation) to the website's Content Hub as an editable draft. Same as pasting it into the Content Hub's blank editor: no AI model runs and no content credits are spent. Use create_content instead when Athena should research and write the piece. body is the full article in Markdown and is stored as given, except that link and image destinations with an unsafe scheme (javascript:, data:) become #. The item is created with type manual at stage generated, and the body is recorded as version 1, so get_content_draft, edit_content, revise_content and get_content_versions work on it right away. Pass title, or it is taken from the body's first heading (else its first line). sheet_id must be a tab from get_content_hub_sheets: a sheet-type tab keeps the item, a view-type tab or no sheet_id puts it in the shared pool. The item is not published. Once it is live on the site, call publish_content with its URL to start citation tracking.

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_content_status afterwards, then read the result with get_content_draft.

Check HTTP responses to AI crawler user agents and robots.txt permissions for a public website. No AthenaHQ account required. Search, retrieval and training are separate. Requests originate from AthenaHQ, not verified crawler IPs. Unknown responses are inconclusive; this does not measure visibility or guarantee indexing, citations or real crawler access. Use nullable evidence and diagnostics.

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 brief and wait for approve_brief. Poll get_content_status using each returned content_ids value. Slice mode returns slice_titles and an empty content_ids array; generated items appear in list_content. To save an already-written article without generation or credit use, call add_content.

Create a location for a website

Create 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, it is returned with created: false instead of failing, so retries are idempotent.

Create a prompt tag on a website, or return the existing tag when its name matches case-insensitively. Trims surrounding whitespace and rejects reserved prompt-type names. Returns the tag ID and whether it was created. Use the returned ID to assign the tag to prompts; creating a tag does not assign it to any prompts.

Create one or more prompts on a website

Create a saved view (filter preset) for a website. Saved views appear in the dashboard filter bar for every member of the website. filters is an object keyed by filter field key, each value shaped {"id": "<unique string>", "field": "<same field key>", "operator": "is_any_of", "values": [...]}. Common field keys: "models" (slugs like "chatgpt", "perplexity", "google_ai_overview"), "competitors", "prompts", "personas", "locations", "promptTags", "attributes" (arrays of UUIDs from the matching list tools), "countries", "sourceTag". "promptTags" also accepts the builtin tokens "type:high_intent" (branded prompts) and "type:discovery" (non-branded) alongside tag UUIDs. "sourceTag" values are the builtin categories "owned", "competitor", "partner", "third_party" or custom source tag UUIDs, not display labels; custom source tag ids appear on existing saved views (list the website's saved views to find them). When unsure, list the website's saved views and mirror their filter shapes. icon, when set, must be a supported Remix icon name (e.g. "RiStarLine"); invalid names are rejected with the full list. When talking to the user about a view or its filters, use the dashboard names (Branded / Non-branded prompts, Owned / Competitor / Partner / Third party sources), never internal tokens, field keys, operator strings, or icon identifiers.

Create a custom source tag with a name and URL patterns. Research existing tags and cited sources first when recommending changes. Obtain user confirmation before calling. MCP executes immediately after authorization; Athena AI chat presents an approval card. Patterns support hosts (example.com), subdomains (*.example.com), path sections (example.com/blog), exact pages (example.com/blog$), and query constraints (youtube.com/watch?v=abc). Up to 500 patterns; new tags use a neutral color. These are source tags, not prompt tags.

Create a topic on a website (returns the existing topic when the name is already taken)

Permanently delete 1-50 brand facts from a website's Knowledge Base. There is no undo. Ids that do not exist on the website are reported in not_found_ids rather than failing the call, so retries are idempotent. Requires an admin; on OAuth connections the signed-in user must have the admin role.

Delete a content row. Destructive: physical row delete, no undo. Powers delete-and-retry. Bulk delete is out of scope.

Delete a location from a website

Permanently delete 1-20 Knowledge Base pillars and every fact filed under them. Facts are deleted, not unfiled; there is no undo. Ids that do not exist on the website are reported in not_found_ids rather than failing the call, so retries are idempotent; ids in failed_ids are untouched and safe to retry. Requires an admin; on OAuth connections the signed-in user must have the admin role.

Delete a prompt (soft when responses exist, hard otherwise)

Permanently delete a custom source tag and all its pattern assignments; retain source records. Read the source-tag listing tool first and supply the tag's current revision in the expected-revision input. Built-in source categories cannot be deleted. Obtain explicit user confirmation identifying the tag and its assignments before calling. MCP executes immediately after authorization; Athena AI chat presents an approval card. If the tag changed, read again and obtain approval for a fresh deletion. Never retry a declined proposal unless the user requests it. A false analytics-refresh result means the tag was deleted but filtered analytics may still be cached.

Delete a topic (soft delete; optionally also delete its prompts)

Apply exact find-and-replace edits to a content draft's article body. Deterministic, no AI model involved: your replacement text lands verbatim (use revise_content when you want an AI rewrite from an instruction). Each edit's find text must match the current body exactly once; zero or multiple matches fail the whole call and nothing is saved, so extend the find text until it is unique. Edits apply in order, later ones see earlier results, and the batch is recorded as one new version, recoverable via get_content_versions / restore_content_version. Pass expected_version_number from get_content_draft to fail with a conflict when a new version was recorded after your read (a revision, edit, or restore). An app autosave changes the body without recording a version; that drift is caught by the anchors themselves, since a moved or vanished find text fails the call.

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.

Get cumulative brand trait (attribute) metrics: for each brand-perception keyword (e.g. 'Affordable', 'Slow Support'), how many AI responses mentioned it across the date range, and the percentage. `positive` selects the observation direction and defaults to true when omitted. `total_responses` is the denominator: responses in the date range that mention the brand AND had attribute extraction run on them. It is NOT every response for the website — responses that never mention the brand are excluded, and Athena samples which responses get extraction, so un-analyzed ones are excluded too. Compute rates from the returned `percentage` / `total_responses` rather than against a response count from another endpoint. Attributes nobody mentioned come back with response_count 0. Use get_competitor_attribute_metrics for the same breakdown per competitor.

Get individual brand trait (attribute) observations: each row is one AI response describing one entity (the brand or a competitor) with one brand trait, including the response excerpt as `text_span`. `score` runs from -1 to 1 and its sign always matches `positive`; its magnitude (0.1 to 1.0) is how strongly the wording praises or criticizes. `score` is null when the observation was not scored (extracted before scoring existed, or no valid value was recorded); for direction only, use `score ?? (positive ? 1 : -1)`. Omit `positive` for both directions. `sort: "intensity"` (the default) returns the strongest observations first with unscored ones last; `sort: "recent"` returns the newest first. Narrow with entity_ids and attribute_ids (from get_attributes). Paginate with page_num and page_size; a page can hold fewer than page_size rows when an excerpt is no longer available, so use `has_more` to decide whether to fetch the next page. Use get_attribute_metrics for how often each trait is mentioned.

Get the daily trend for ONE brand trait (attribute), brand and competitors side by side — how mentions of a keyword like 'Affordable' moved over time. Requires an attribute_id: call get_attributes first to discover ids. `positive` selects the observation direction and defaults to true when omitted. Days with no data are returned as zeros, so the series is gap-free and chartable. Denominators are per-side, not the day's whole response set: brand_percentage divides by that day's responses that mention the brand (and had attribute extraction run), and competitor_percentage by responses that mention the tracked competitors. brand_total and competitor_total return those denominators explicitly. Competitor figures aggregate all tracked competitors unless competitor_ids narrows them.

List the brand traits (called attributes in the API) tracked for a website: brand-perception keywords such as 'Affordable' or 'Slow Support'. Athena extracts these from AI model responses. Brand traits are direction-neutral; `positive` selects the directional series and defaults to true when omitted. Use this to discover attribute ids, then get_attribute_metrics for how often each is mentioned, or get_attribute_time_series for one attribute's trend over time.

List a website's brand facts from the Knowledge Base, newest first, with offset paging. By default excludes facts generated by Oracle analysis; pass include_oracle=true to include them. Filters: pillar, review status (default approved), source type, and unfiled=true for facts not under any published pillar (unfiled and pillar_id are mutually exclusive).

Get cumulative citation rate — average citation rate for each competitor across the date range.

Get citation rate over time — how often AI models cite (link to) the website, grouped by day.

Get brand trait (attribute) metrics per tracked competitor: for each competitor and each brand-perception keyword (e.g. 'Affordable'), how many AI responses mentioned that keyword for that competitor, and the percentage. Use with get_attribute_metrics to compare the brand against competitors. `total_responses` is per-competitor: responses in the date range that mention THAT competitor and had attribute extraction run on them. Each competitor therefore has its own denominator, and none of them is the website's total response count. `positive` selects the observation direction and defaults to true when omitted. Returns one row per competitor per attribute, so results can be large — filter with competitor_ids. Competitors with no responses in the date range are omitted entirely rather than returned with zeros.

List competitors tracked for a website

For a single tracked content item, list every prompt whose AI responses cited it — with citations, citation %, and estimated impressions. Use after get_tracked_content to drill into which prompts a given URL is appearing for. This is CITED-BY, measured over the requested date range, not the targeting the page was written for: an empty prompts array means no AI response cited this URL in that window, which is expected for new or never-cited pages and is not missing data. For the prompts a page was written to target, read `prompts` on get_content_detail (or prompt_ids on list_content) — those come from the content record itself and do not depend on any citation having happened.

Fetch the full detail of a single tracked content item — its brief and body text (drafts, optimize rewrites, snipes, authored and scraped pages), plus status, cited source URLs, and links. Use after get_tracked_content to read the actual text behind a content_id. A status of generated_brief means the brief is ready while the article is still being written. Pages registered via track_content_urls return a null body and null status until their page text is fetched from the app — a null body on an external page means not fetched yet, not missing content; citation tracking does not need the body. `prompts` lists the prompts this page was WRITTEN FOR (the same ids create_content takes), newest-linked last, capped at 100 with the true size in `prompts_total`. When prompts_total exceeds 100 the rest are not currently readable through any tool — report the total, do not imply the list is complete. Entries carry status active, paused or deleted: a deleted prompt is still part of what the page was written for and still shows in the Content Hub, but get_prompts will not list it, so use the text returned here. An empty array means the page has no prompt targeting, which is normal for imported or externally tracked pages. That is a different question from get_content_citation_prompts, which lists prompts whose AI responses CITED the page. To see the reworded variants actually asked of the models for these prompts, pass their ids to get_responses (each row carries base_prompt plus the variation as prompt) or query the responses cube via query_rows on the prompt_variation dimension.

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 still being written, so body may still be empty. For the full record (cited urls, links, social posts) use get_content_detail instead.

List the Content Hub tabs/sheets configured for a website. Use to discover available tabs (e.g. 1st-party content, 3rd-party placements, Reddit) before calling get_tracked_content with a specific sheet_id (metrics; excludes in-flight pipeline items) or list_content (every item including unpublished drafts).

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-auto-approve draft it stays there until approve_brief is called, so do not treat running as always in progress. Not meaningful for tracked pages (track_content_urls / external rows): they have no generation pipeline and report running with a null stage forever — read them via get_tracked_content or get_content_detail instead.

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.

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.

Read recorded organization credit consumption: total, hourly (24h) or daily trend, and charged website/group/organization pools. Use for spending trends and biggest charged pools; the credit-balance tools read current balances. For 'this month' or a specific spike, supply explicit UTC window boundaries; 30d is rolling, not a calendar month. State the returned interval. A group pool is not an originating website. The breakdown may exclude unattributed usage or be capped by the billing provider; totalCreditsUsed is authoritative, not the sum of displayed entities. Negative credits are refunds. Entities are paginated: continue with window and nextOffset while hasMore. Use credit-usage events to inspect recorded actions. Requires organization billing access on a signed-in connection, or a global organization API key. Website-scoped keys are not supported. Read-only.

Read a page of recorded credit charges/refunds and action labels for the organization, optionally filtered by originatingWebsiteId. Use to inspect a usage spike or charges behind a total. Use credit-usage totals for complete period totals. Supply explicit UTC window for calendar months. Continue with returned window, originatingWebsiteId, and nextOffset while hasMore; never compute the next offset from returned row count. Limit bounds underlying operations, each may split into several charged-pool rows. One page is not a complete action breakdown. 'Not recorded' means unknown historical action/site attribution, never infer it. Unknown raw action tags are preserved. Negative credits are refunds. Requires organization billing access on a signed-in connection, or a global organization API key. Website-scoped keys are not supported. Read-only.

Get credit balance for the organization

Get credit balance for a specific website

Get the earliest and latest response dates for a website

Fetch a single group by id with its member websites.

List group-level saved views (filter presets) shared across the websites in a group

List all groups in the organization (global API key only)

Read the identifiers of the website's brand, or of one competitor: the names, aliases and domains Athena looks for in AI responses to count a mention. default_identifiers (the name and domain) are always matched and cannot be removed; identifiers lists every other value, as the Competitors page shows them. case_sensitive tells whether matching respects letter case. Read this before update_identifiers. Read-only.

List geo-locations configured for a website

Get cumulative mention rate — average mention rate for each competitor across the date range. mention_rate is absolute (share of all responses); relative_mention_rate is the share of responses mentioning any tracked brand.

Get mention rate over time — how often AI models mention the website by name, grouped by day. mention_rate is absolute (share of that day's responses); relative_mention_rate is the share of that day's responses mentioning any tracked brand.

When grounding is present, use its complete team-confirmed statement and all supporting facts as joint evidence; the legacy fact ID/text are only a compatibility anchor. Load one Oracle finding in full: the flagged claim with its verified fact and prompt text, the run it came from, a ~2000-character response excerpt centered on the quoted claim, the cited-page evidence captured during the run (url, quote, snippet, scrape_hash), and its lineage: sibling findings sharing its lineage_id across runs, newest first. Use after get_oracle_findings to interrogate a specific finding. Returns a not-found error for an unknown finding id, and status 'no_access' if the brand does not have Oracle v2.