AthenaHQ is an MCP server published by ai.athenahq, hosted at api.athenahq.ai. When last checked on 2026-11-22 it was working: it answers and lists its tools. It declares 132 tools, including open_ai_access, check_public_ai_access, get_prompt_schedules, get_ai_search_value, get_prompts.
Track how AI assistants mention, cite, and rank your brand and competitors in AI search.
4 connections through 4 shared values. Tap any node.
Squares are this server's values; dots are other servers sharing them. A shared address or publisher is a lead, not proof of a common operator.
Inferred from the host name and headers: what a server runs on, not who runs it.
Open the AthenaHQ AI crawler access panel. Enter a public HTTPS domain to inspect crawler responses and robots.txt permissions without an AthenaHQ account.
No parameters.
{
"name": "open_ai_access",
"title": "AI crawler access",
"description": "Open the AthenaHQ AI crawler access panel. Enter a public HTTPS domain to inspect crawler responses and robots.txt permissions without an AthenaHQ account.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}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.
| Parameter | Type | Description |
|---|---|---|
| domain * | string |
{
"name": "check_public_ai_access",
"title": "Check AI crawler access",
"description": "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.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"domain"
],
"properties": {
"domain": {
"type": "string",
"maxLength": 253,
"minLength": 1
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"domain",
"checkedAt",
"evidence",
"diagnostics",
"log"
],
"properties": {
"log": {
"type": "string"
},
"domain": {
"type": "string"
},
"evidence": {
"type": "object",
"required": [
"version",
"network",
"status",
"http",
"robots"
],
"properties": {
"http": {
"anyOf": [
{
"type": "object",
"required": [
"chatgpt",
"claude",
"perplexity",
"gemini",
"copilot",
"grok",
"deepseek",
"rufus"
],
"properties": {
"grok": {
"type": "object",
"required": [
"XAIBot"
],
"properties": {
"XAIBot": {
"type": [
"boolean",
"null"
]
}
},
"additionalProperties": false
},
"rufus": {
"type": "object",
"required": [
"Amazonbot"
],
"properties": {
"Amazonbot": {
"type": [
"boolean",
"null"
]
}
},
"additionalProperties": false
},
"claude": {
"type": "object",
"required": [
"ClaudeUser",
"ClaudeSearchBot",
"ClaudeBot"
],
"properties": {
"ClaudeBot": {
"type": [
"boolean",
"null"
]
},
"ClaudeUser": {
"type": [
"boolean",
"null"
]
},
"ClaudeSearchBot": {
"type": [
"boolean",
"null"
]
}
},
"additionalProperties": false
},
"gemini": {
"type": "object",
"required": [
"Googlebot",
"GoogleExtended"
],
"properties": {
"Googlebot": {
"type": [
"boolean",
"null"
]
},
"GoogleExtended": {
"type": [
"boolean",
"null"
]
}
},
"additionalProperties": false
},
"chatgpt": {
"type": "object",
"required": [
"ChatGPTUser",
"OAISearchBot",
"GPTBot"
],
"properties": {
"GPTBot": {
"type": [
"boolean",
"null"
]
},
"ChatGPTUser": {
"type": [
"boolean",
"null"
]
},
"OAISearchBot": {
"type": [
"boolean",
"null"
]
}
},
"additionalProperties": false
},
"copilot": {
"type": "object",
"required": [
"Bingbot"
],
"properties": {
"Bingbot": {
"type": [
"boolean",
"null"
]
}
},
"additionalProperties": false
},
"deepseek": {
"type": "object",
"required": [
"DeepSeekBot"
],
"properties": {
"DeepSeekBot": {
"type": [
"boolean",
"null"
]
}
},
"additionalProperties": false
},
"perplexity": {
"type": "object",
"required": [
"PerplexityUser",
"PerplexityBot"
],
"properties": {
"PerplexityBot": {
"type": [
"boolean",
"null"
]
},
"PerplexityUser": {
"type": [
"boolean",
"null"
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"robots": {
"anyOf": [
{
"type": "object",
"required": [
"chatgpt",
"claude",
"perplexity",
"gemini",
"copilot",
"grok",
"deepseek",
"rufus"
],
"properties": {
"grok": {
"type": "object",
"required": [
"XAIBot"
],
"properties": {
"XAIBot": {
"type": [
"boolean",
"null"
]
}
},
"additionalProperties": false
},
"rufus": {
"type": "object",
"required": [
"Amazonbot"
],
"properties": {
"Amazonbot": {
"type": [
"boolean",
"null"
]
}
},
"additionalProperties": false
},
"claude": {
"type": "object",
"required": [
"ClaudeUser",
"ClaudeSearchBot",
"ClaudeBot"
],
"properties": {
"ClaudeBot": {
"type": [
"boolean",
"null"
]
},
"ClaudeUser": {
"type": [
"boolean",
"null"
]
},
"ClaudeSearchBot": {
"type": [
"boolean",
"null"
]
}
},
"additionalProperties": false
},
"gemini": {
"type": "object",
"required": [
"Googlebot",
"GoogleExtended"
],
"properties": {
"Googlebot": {
"type": [
"boolean",
"null"
]
},
"GoogleExtended": {
"type": [
"boolean",
"null"
]
}
},
"additionalProperties": false
},
"chatgpt": {
"type": "object",
"required": [
"ChatGPTUser",
"OAISearchBot",
"GPTBot"
],
"properties": {
"GPTBot": {
"type": [
"boolean",
"null"
]
},
"ChatGPTUser": {
"type": [
"boolean",
"null"
]
},
"OAISearchBot": {
"type": [
"boolean",
"null"
]
}
},
"additionalProperties": false
},
"copilot": {
"type": "object",
"required": [
"Bingbot"
],
"properties": {
"Bingbot": {
"type": [
"boolean",
"null"
]
}
},
"additionalProperties": false
},
"deepseek": {
"type": "object",
"required": [
"DeepSeekBot"
],
"properties": {
"DeepSeekBot": {
"type": [
"boolean",
"null"
]
}
},
"additionalProperties": false
},
"perplexity": {
"type": "object",
"required": [
"PerplexityUser",
"PerplexityBot"
],
"properties": {
"PerplexityBot": {
"type": [
"boolean",
"null"
]
},
"PerplexityUser": {
"type": [
"boolean",
"null"
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"status": {
"enum": [
"accessible",
"partial",
"blocked",
"inconclusive"
],
"type": "string"
},
"network": {
"type": "string",
"const": "athena"
},
"version": {
"type": "number",
"const": 2
}
},
"additionalProperties": false
},
"checkedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
},
"diagnostics": {
"type": "object",
"required": [
"userAgentChecks"
],
"properties": {
"robotsCheck": {
"type": "object",
"required": [
"url",
"status",
"finalUrl",
"headers",
"errorCode",
"errorMessage",
"durationMs",
"checkedAt",
"source"
],
"properties": {
"url": {
"type": "string"
},
"source": {
"enum": [
"direct",
"fallback",
"missing"
],
"type": "string"
},
"status": {
"type": [
"number",
"null"
]
},
"headers": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"finalUrl": {
"type": [
"string",
"null"
]
},
"checkedAt": {
"type": "string"
},
"errorCode": {
"type": [
"string",
"null"
]
},
"durationMs": {
"type": "number"
},
"errorMessage": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"userAgentChecks": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"required": [
"category",
"agentKey",
"agentName",
"userAgent",
"accessible",
"status",
"finalUrl",
"headers",
"errorCode",
"errorMessage",
"durationMs",
"checkedAt"
],
"properties": {
"status": {
"type": [
"number",
"null"
]
},
"headers": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"verdict": {
"enum": [
"allowed",
"challenged",
"blocked",
"error",
"not_tested"
],
"type": "string"
},
"agentKey": {
"type": "string"
},
"category": {
"type": "string"
},
"finalUrl": {
"type": [
"string",
"null"
]
},
"agentName": {
"type": "string"
},
"checkedAt": {
"type": "string"
},
"errorCode": {
"type": [
"string",
"null"
]
},
"userAgent": {
"type": "string"
},
"accessible": {
"type": "boolean"
},
"durationMs": {
"type": "number"
},
"errorMessage": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": false,
"destructiveHint": false
}
}List the 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; archived schedules retain results. To combine schedules, pass several selection values as an array in the schedule field of query_metrics and query_rows, or use a saved view that stores several schedules. Partner REST filters take one schedule. starts_on and ends_on bound a custom schedule's active period as UTC days (null means no bound); an active schedule outside its period does not run.
| Parameter | Type | Description |
|---|---|---|
| website_id * | string |
{
"name": "get_prompt_schedules",
"description": "List the 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; archived schedules retain results. To combine schedules, pass several selection values as an array in the schedule field of query_metrics and query_rows, or use a saved view that stores several schedules. Partner REST filters take one schedule. starts_on and ends_on bound a custom schedule's active period as UTC days (null means no bound); an active schedule outside its period does not run.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id"
],
"properties": {
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"schedules"
],
"properties": {
"schedules": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"kind",
"selection",
"is_active",
"archived_at",
"starts_on",
"ends_on"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"kind": {
"enum": [
"default",
"custom"
],
"type": "string"
},
"name": {
"type": "string"
},
"ends_on": {
"type": [
"string",
"null"
]
},
"is_active": {
"type": "boolean"
},
"selection": {
"anyOf": [
{
"type": "string",
"const": "default"
},
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
]
},
"starts_on": {
"type": [
"string",
"null"
]
},
"archived_at": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get prompt schedules",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}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.
| Parameter | Type | Description |
|---|---|---|
| website_id * | string |
{
"name": "get_ai_search_value",
"description": "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.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id"
],
"properties": {
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"assumptions_version",
"computed_at",
"has_computed_valuations",
"is_stale_value",
"market",
"captured",
"headroom",
"measured_responses",
"topics",
"merge_suggestions",
"contribution",
"forecast"
],
"properties": {
"market": {
"type": "object",
"required": [
"value_usd_mo",
"topics_priced",
"topics_total",
"coverage_pct",
"current_sov_pct"
],
"properties": {
"coverage_pct": {
"type": "number"
},
"topics_total": {
"type": "number"
},
"value_usd_mo": {
"type": "number"
},
"topics_priced": {
"type": "number"
},
"current_sov_pct": {
"type": "number"
}
},
"additionalProperties": false
},
"topics": {
"type": "array",
"items": {
"type": "object",
"required": [
"topic_id",
"category",
"local_intent",
"share_basis",
"pw_sov_pct",
"mix_adjusted_share_pct",
"mention_rate_pct",
"drift_pp",
"standard_error_pp",
"responses_28d",
"models_measured",
"personas_measured",
"locations_measured",
"captured",
"headroom",
"counted_in_total"
],
"properties": {
"captured": {
"type": "object",
"required": [
"conservative",
"expected",
"upside"
],
"properties": {
"upside": {
"type": "number"
},
"expected": {
"type": "number"
},
"conservative": {
"type": "number"
}
},
"additionalProperties": false
},
"category": {
"type": "string"
},
"drift_pp": {
"type": "number"
},
"headroom": {
"type": "object",
"required": [
"conservative",
"expected",
"upside"
],
"properties": {
"upside": {
"type": "number"
},
"expected": {
"type": "number"
},
"conservative": {
"type": "number"
}
},
"additionalProperties": false
},
"topic_id": {
"type": "string"
},
"pw_sov_pct": {
"type": "number"
},
"share_basis": {
"type": "string"
},
"local_intent": {
"type": "boolean"
},
"responses_28d": {
"type": "number"
},
"models_measured": {
"type": "number"
},
"counted_in_total": {
"type": "boolean"
},
"mention_rate_pct": {
"type": "number"
},
"personas_measured": {
"type": "number"
},
"standard_error_pp": {
"type": "number"
},
"locations_measured": {
"type": "number"
},
"mix_adjusted_share_pct": {
"type": "number"
}
},
"additionalProperties": false
}
},
"captured": {
"type": "object",
"required": [
"conservative",
"expected",
"upside"
],
"properties": {
"upside": {
"type": "number"
},
"expected": {
"type": "number"
},
"conservative": {
"type": "number"
}
},
"additionalProperties": false
},
"forecast": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"created_at",
"days_elapsed",
"share_delta_pp",
"share_vs_do_nothing_pp",
"captured_delta_expected"
],
"properties": {
"id": {
"type": "string"
},
"created_at": {
"type": "string"
},
"days_elapsed": {
"type": "number"
},
"share_delta_pp": {
"type": "number"
},
"share_vs_do_nothing_pp": {
"type": "number"
},
"captured_delta_expected": {
"type": "number"
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"headroom": {
"type": "object",
"required": [
"conservative",
"expected",
"upside"
],
"properties": {
"upside": {
"type": "number"
},
"expected": {
"type": "number"
},
"conservative": {
"type": "number"
}
},
"additionalProperties": false
},
"computed_at": {
"type": [
"string",
"null"
]
},
"contribution": {
"type": "object",
"required": [
"modeled_attributed",
"attributed_share",
"attribution_unavailable"
],
"properties": {
"attributed_share": {
"type": [
"number",
"null"
]
},
"modeled_attributed": {
"anyOf": [
{
"type": "object",
"required": [
"conservative",
"expected",
"upside"
],
"properties": {
"upside": {
"type": "number"
},
"expected": {
"type": "number"
},
"conservative": {
"type": "number"
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"attribution_unavailable": {
"type": "boolean"
}
},
"additionalProperties": false
},
"is_stale_value": {
"type": "boolean"
},
"merge_suggestions": {
"type": "array",
"items": {
"type": "object",
"required": [
"topic_id_a",
"topic_id_b",
"name_a",
"name_b",
"similarity"
],
"properties": {
"name_a": {
"type": "string"
},
"name_b": {
"type": "string"
},
"similarity": {
"type": "number"
},
"topic_id_a": {
"type": "string"
},
"topic_id_b": {
"type": "string"
}
},
"additionalProperties": false
}
},
"measured_responses": {
"type": "number"
},
"assumptions_version": {
"type": [
"string",
"null"
]
},
"has_computed_valuations": {
"type": "boolean"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get ai search value",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}List prompts (search queries) tracked for a website
| Parameter | Type | Description |
|---|---|---|
| status | string | one of ["active","paused"] |
| website_id * | string | |
| prompt_tags | array | |
| prompt_tags_operator | string | one of ["is_any_of","has_all_of"] |
{
"name": "get_prompts",
"description": "List prompts (search queries) tracked for a website",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id"
],
"properties": {
"status": {
"enum": [
"active",
"paused"
],
"type": "string"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"prompt_tags": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"prompt_tags_operator": {
"enum": [
"is_any_of",
"has_all_of"
],
"type": "string"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"prompts"
],
"properties": {
"prompts": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"prompt",
"topic_name",
"current_monthly_searches",
"current_total_value",
"status",
"country",
"countries",
"tags",
"prompt_type"
],
"properties": {
"id": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"additionalProperties": false
}
},
"prompt": {
"type": "string"
},
"status": {
"enum": [
"active",
"paused"
],
"type": "string"
},
"country": {
"type": "string"
},
"countries": {
"type": "array",
"items": {
"type": "object",
"required": [
"country",
"is_primary"
],
"properties": {
"country": {
"type": "string"
},
"is_primary": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"topic_name": {
"type": [
"string",
"null"
]
},
"prompt_type": {
"anyOf": [
{
"enum": [
"branded",
"non_branded"
],
"type": "string"
},
{
"type": "null"
}
]
},
"current_total_value": {
"type": [
"number",
"null"
]
},
"current_monthly_searches": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get prompts",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}List prompt tags for a website with per-tag prompt counts. Tag IDs can be used with the prompt_tags filter on the prompts endpoint.
| Parameter | Type | Description |
|---|---|---|
| website_id * | string |
{
"name": "get_prompt_tags",
"description": "List prompt tags for a website with per-tag prompt counts. Tag IDs can be used with the prompt_tags filter on the prompts endpoint.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id"
],
"properties": {
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"prompt_tags"
],
"properties": {
"prompt_tags": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"prompt_count"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"prompt_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get prompt tags",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}List personas configured for a website with per-persona prompt counts. Use it to resolve persona_id values returned by other tools to persona names and descriptions.
| Parameter | Type | Description |
|---|---|---|
| website_id * | string |
{
"name": "get_personas",
"description": "List personas configured for a website with per-persona prompt counts. Use it to resolve persona_id values returned by other tools to persona names and descriptions.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id"
],
"properties": {
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"personas"
],
"properties": {
"personas": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"description",
"prompt_count"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": [
"string",
"null"
]
},
"prompt_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get personas",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}List topics (groupings of prompts) for a website, with the count of prompts in each
| Parameter | Type | Description |
|---|---|---|
| website_id * | string |
{
"name": "get_topics",
"description": "List topics (groupings of prompts) for a website, with the count of prompts in each",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id"
],
"properties": {
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"topics"
],
"properties": {
"topics": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"description",
"prompt_count"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": [
"string",
"null"
]
},
"prompt_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get topics",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}List competitors tracked for a website
| Parameter | Type | Description |
|---|---|---|
| website_id * | string |
{
"name": "get_competitors",
"description": "List competitors tracked for a website",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id"
],
"properties": {
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"competitors"
],
"properties": {
"competitors": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"url",
"normalized_url",
"identifiers"
],
"properties": {
"id": {
"type": "string"
},
"url": {
"type": "string"
},
"name": {
"type": "string"
},
"identifiers": {
"type": "array",
"items": {
"type": "string"
}
},
"normalized_url": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get competitors",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}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).
| Parameter | Type | Description |
|---|---|---|
| website_id * | string |
{
"name": "get_content_hub_sheets",
"description": "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).",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id"
],
"properties": {
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"sheets"
],
"properties": {
"sheets": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"sheet_type",
"is_default",
"position",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"position": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"created_at": {
"type": "string"
},
"is_default": {
"type": "boolean"
},
"sheet_type": {
"enum": [
"view",
"sheet"
],
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get content hub sheets",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}List tracked content (1st-party drafts, imported pages, 3rd-party placements) with citation, mention, and impression metrics for the supplied date range and filters. Supports pagination via page_num / page_size and optional filtering by Content Hub sheet_id or content_type. A sheet_id of a view-type tab (see get_content_hub_sheets sheet_type) lists the shared main pool: content not filed in any sheet. In-flight pipeline items (drafts, briefs, running generations) never appear here; enumerate those with list_content. A returned item can still lack a url (pipeline finished but not published anywhere yet).
| Parameter | Type | Description |
|---|---|---|
| filters * | object | |
| page_num | integer | |
| sheet_id | string | Content Hub tab to list (get_content_hub_sheets). A sheet-type tab lists its own content; a view-type tab, the default tab included, lists the shared main pool (content not filed in any sheet), without the view's saved filters. Omit to list content on every tab. |
| mentioned | boolean | |
| page_size | integer | |
| website_id * | string | |
| content_type | string | one of ["external","imported","athena_created","draft","snipe","optimize","slice","manual"] |
Enumerate 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. Returns identity fields only (id, title, type, stage, sheet, URL, timestamps, target prompt ids), no metrics. Uncached and Postgres-backed, so an item created by create_content is listable immediately. Filter by sheet_id, content_type, stage, or prompt_id. stage is the raw pipeline workflow state, not a publication flag: null = no pipeline record (most tracked external / imported pages), and manual editor items carry 'generated'. Treat an item as published only when its stage is done (or it is an external / imported page) AND it has a url; done without a url is an unpublished orphan. A sheet_id of a view-type tab (see get_content_hub_sheets sheet_type) lists the shared main pool without the view's saved filters. Use get_tracked_content for citation and impression metrics on published content; use this tool to discover what exists. Each row carries prompt_ids: the prompts that item was WRITTEN FOR (what create_content was given), capped at 25 with the true size in prompt_count — resolve the ids to text with get_prompts rather than calling get_content_detail per row, and drill in with get_content_detail where prompt_count exceeds the ids returned (that read carries up to 100; associations past 100 are not currently readable). prompt_ids includes soft-deleted prompts, which get_prompts does NOT list — an id that fails to resolve there is a deleted prompt, and get_content_detail returns its text and status: "deleted". Empty prompt_ids means no targeting was recorded, which is normal for imported or externally tracked pages. This is not the same as being cited for a prompt — see get_content_citation_prompts for that. Filter by prompt_id for the reverse question: which content already targets a given prompt (coverage gaps).
| Parameter | Type | Description |
|---|---|---|
| stage | string | one of ["scheduled","pending","pending_brief","generated_brief","pending_article","generated","done","failed"] |
| page_num | integer | |
| sheet_id | string | |
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. For an optimize item, source_url is 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. source_url is null for other content types and for optimize items based on pasted text or a file. 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.
| Parameter | Type | Description |
|---|---|---|
| content_id * | string | |
| website_id * | string |
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.
| Parameter | Type | Description |
|---|---|---|
| filters * | object | |
| mentioned | boolean | |
| content_id * | string | |
| website_id * | string |
{
"name": "get_content_citation_prompts",
"description": "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.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"content_id",
"filters"
],
"properties": {
"filters": {
"type": "object",
"required": [
"start_date"
],
"properties": {
"models": {
"type": "array",
"items": {
"enum": [
"chatgpt",
"perplexity",
"gemini",
"google_ai_overview",
"copilot",
"claude",
"ai_mode",
"grok",
"deepseek",
"meta_ai",
"mistral"
],
"type": "string"
},
"description": "AI models to include, as an array even for one model — e.g. [\"chatgpt\", \"perplexity\"]. Omit to include all models."
},
"end_date": {
"type": "string",
"description": "End of the date range, inclusive. Date-only values include the UTC day through 23:59:59.999; timestamps keep their exact instant. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"prompt_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Prompt UUIDs to filter to, as an array even for one id. Omit for all prompts."
},
"start_date": {
"type": "string",
"description": "Start of the date range. Required. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"persona_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Persona UUIDs to filter to, as an array even for one id. Omit for all personas."
},
"prompt_tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Prompt tag IDs to filter prompts by, as an array (list tags with get_prompt_tags). Omit for all tags."
},
"prompt_type": {
"enum": [
"branded",
"non_branded"
],
"type": "string",
"description": "Filter prompts by type: \"branded\" (mentions the brand) or \"non_branded\". Omit for both."
},
"schedule_id": {
"anyOf": [
{
"enum": [
"default",
"manual"
],
"type": "string"
},
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
],
"description": "One schedule: \"default\" or a custom/archived schedule UUID. Omit for Default, which includes all pre-cutover history and ad hoc runs. The retired \"manual\" token is accepted as an alias of \"default\". Schedules cannot be combined."
},
"location_ids": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "string",
"const": "no-location"
}
]
},
"description": "Location UUIDs to filter to, as an array even for one id. The literal string \"no-location\" selects responses that ran without a location. Omit for all locations."
},
"prompt_status": {
"enum": [
"active",
"paused"
],
"type": "string",
"description": "Filter prompts by tracking status: \"active\" or \"paused\". Omit for both."
},
"competitor_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Competitor UUIDs to filter to, as an array even for one id. Omit for all competitors."
},
"variation_filter": {
"type": "array",
"items": {
"enum": [
"variation",
"prompt"
],
"type": "string"
},
"description": "Which prompt rows to include, as an array: \"prompt\" for base prompts, \"variation\" for generated variations, or both. Omit for both."
},
"target_identifiers": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "string",
"const": "no-identifier"
}
]
},
"description": "Target identifier strings to filter to, as an array even for one value. The literal string \"no-identifier\" selects responses with no target identifier. Omit for all."
},
"prompt_tags_operator": {
"enum": [
"is_any_of",
"has_all_of"
],
"type": "string",
"description": "How prompt_tags combine: \"is_any_of\" matches prompts with any listed tag, \"has_all_of\" only prompts carrying every listed tag."
}
}
},
"mentioned": {
"type": "boolean"
},
"content_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"content_id",
"content_url",
"content_normalized_url",
"prompts"
],
"properties": {
"prompts": {
"type": "array",
"items": {
"type": "object",
"required": [
"prompt_id",
"prompt",
"citation_percent",
"citations",
"estimated_impressions"
],
"properties": {
"prompt": {
"type": "string"
},
"citations": {
"type": "number"
},
"prompt_id": {
"type": "string"
},
"citation_percent": {
"type": "number"
},
"estimated_impressions": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
}
},
"content_id": {
"type": "string"
},
"content_url": {
"type": [
"string",
"null"
]
},
"content_normalized_url": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get content citation prompts",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}List every website accessible to the calling session. Works with any API key (global or scoped) and with MCP/OAuth sessions. Call with an empty argument object `{}`. Each item includes `baseCountry`, the country market the website targets: use it to tell same-brand websites for different countries apart.
No parameters.
{
"name": "list_websites",
"description": "List every website accessible to the calling session. Works with any API key (global or scoped) and with MCP/OAuth sessions. Call with an empty argument object `{}`. Each item includes `baseCountry`, the country market the website targets: use it to tell same-brand websites for different countries apart.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"websites"
],
"properties": {
"websites": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"websiteName",
"websiteUrl",
"baseCountry",
"onboardingStep"
],
"properties": {
"id": {
"type": "string"
},
"externalId": {
"type": [
"string",
"null"
]
},
"websiteUrl": {
"type": "string"
},
"baseCountry": {
"type": [
"string",
"null"
],
"description": "Country market this website targets, e.g. \"United States\". Distinguishes per-country websites that share a brand name. Websites that never chose a country carry the default \"United States\", so treat that value as unconfirmed for non-US-looking sites. Rare legacy values are ISO codes like \"US\"; treat them as their full-name equivalents."
},
"websiteName": {
"type": "string"
},
"onboardingStep": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "List websites",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}List geo-locations configured for a website
| Parameter | Type | Description |
|---|---|---|
| website_id * | string |
{
"name": "get_locations",
"description": "List geo-locations configured for a website",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id"
],
"properties": {
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"locations"
],
"properties": {
"locations": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"location",
"country"
],
"properties": {
"id": {
"type": "string"
},
"country": {
"type": [
"string",
"null"
]
},
"location": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get locations",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}Get the earliest and latest response dates for a website
| Parameter | Type | Description |
|---|---|---|
| website_id * | string | |
| schedule_id | any | One schedule: "default" or a custom/archived schedule UUID. Omit for Default, which includes all pre-cutover history and ad hoc runs. The retired "manual" token is accepted as an alias of "default". Schedules cannot be combined. |
| prompt_status | string | one of ["active","paused"] |
{
"name": "get_date_range",
"description": "Get the earliest and latest response dates for a website",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id"
],
"properties": {
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"schedule_id": {
"anyOf": [
{
"enum": [
"default",
"manual"
],
"type": "string"
},
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
],
"description": "One schedule: \"default\" or a custom/archived schedule UUID. Omit for Default, which includes all pre-cutover history and ad hoc runs. The retired \"manual\" token is accepted as an alias of \"default\". Schedules cannot be combined."
},
"prompt_status": {
"enum": [
"active",
"paused"
],
"type": "string"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"min_date",
"max_date"
],
"properties": {
"max_date": {
"type": [
"string",
"null"
]
},
"min_date": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get date range",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}Get LLM responses for a website. Shows how AI models answer queries, with sources, sentiment, and ranking data. Filter by whether a model used search queries or by text within those queries. For a variation-level export at volume, pair filters.variation_filter with include_response: false and compact_sources: true. That keeps the prompt, its variation, the model, the mentioned/cited flags and the cited domains while dropping the answer text, cutting each row to roughly a tenth of its size.
| Parameter | Type | Description |
|---|---|---|
| filters * | object | |
| page_num | number | |
| page_size | number | |
| website_id * | string | |
| compact_sources | boolean | Replace the per-source `sources` objects with `source_domains`, a deduped, sorted list of cited root domains. Defaults to false. Use when you need which domains were cited but not their exact URLs. |
| include_response | boolean | Include the full answer text on each row. Defaults to true. Set false to omit the `response` field entirely (the heaviest part of a row) when you only need which prompt/variation ran and how it scored. |
{
"name": "get_responses",
"description": "Get LLM responses for a website. Shows how AI models answer queries, with sources, sentiment, and ranking data. Filter by whether a model used search queries or by text within those queries. For a variation-level export at volume, pair filters.variation_filter with include_response: false and compact_sources: true. That keeps the prompt, its variation, the model, the mentioned/cited flags and the cited domains while dropping the answer text, cutting each row to roughly a tenth of its size.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"filters"
],
"properties": {
"filters": {
"type": "object",
"required": [
"start_date"
],
"properties": {
"models": {
"type": "array",
"items": {
"enum": [
"chatgpt",
"perplexity",
"gemini",
"google_ai_overview",
"copilot",
"claude",
"ai_mode",
"grok",
"deepseek",
"meta_ai",
"mistral"
],
"type": "string"
},
"description": "AI models to include, as an array even for one model — e.g. [\"chatgpt\", \"perplexity\"]. Omit to include all models."
},
"end_date": {
"type": "string",
"description": "End of the date range, inclusive. Date-only values include the UTC day through 23:59:59.999; timestamps keep their exact instant. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"prompt_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Prompt UUIDs to filter to, as an array even for one id. Omit for all prompts."
},
"start_date": {
"type": "string",
"description": "Start of the date range. Required. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"persona_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Persona UUIDs to filter to, as an array even for one id. Omit for all personas."
},
"prompt_tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Prompt tag IDs to filter prompts by, as an array (list tags with get_prompt_tags). Omit for all tags."
},
"prompt_type": {
"enum": [
"branded",
"non_branded"
],
"type": "string",
"description": "Filter prompts by type: \"branded\" (mentions the brand) or \"non_branded\". Omit for both."
},
"schedule_id": {
"anyOf": [
{
"enum": [
"default",
"manual"
],
"type": "string"
},
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
],
"description": "One schedule: \"default\" or a custom/archived schedule UUID. Omit for Default, which includes all pre-cutover history and ad hoc runs. The retired \"manual\" token is accepted as an alias of \"default\". Schedules cannot be combined."
},
"location_ids": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "string",
"const": "no-location"
}
]
},
"description": "Location UUIDs to filter to, as an array even for one id. The literal string \"no-location\" selects responses that ran without a location. Omit for all locations."
},
"prompt_status": {
"enum": [
"active",
"paused"
],
"type": "string",
"description": "Filter prompts by tracking status: \"active\" or \"paused\". Omit for both."
},
"competitor_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Competitor UUIDs to filter to, as an array even for one id. Omit for all competitors."
},
"variation_filter": {
"type": "array",
"items": {
"enum": [
"variation",
"prompt"
],
"type": "string"
},
"description": "Which prompt rows to include, as an array: \"prompt\" for base prompts, \"variation\" for generated variations, or both. Omit for both."
},
"search_query_text": {
"type": "string",
"description": "Case-insensitive text to match within the web or map search queries used for a response."
},
"has_search_queries": {
"type": "boolean",
"description": "Filter by whether the model used at least one non-empty web or map search query."
},
"target_identifiers": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "string",
"const": "no-identifier"
}
]
},
"description": "Target identifier strings to filter to, as an array even for one value. The literal string \"no-identifier\" selects responses with no target identifier. Omit for all."
},
"prompt_tags_operator": {
"enum": [
"is_any_of",
"has_all_of"
],
"type": "string",
"description": "How prompt_tags combine: \"is_any_of\" matches prompts with any listed tag, \"has_all_of\" only prompts carrying every listed tag."
},
"search_query_text_operator": {
"enum": [
"contains",
"does_not_contain"
],
"type": "string",
"description": "How search_query_text matches: \"contains\" (default) or \"does_not_contain\"."
}
}
},
"page_num": {
"type": "number",
"minimum": 0
},
"page_size": {
"type": "number",
"maximum": 100,
"minimum": 1
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"compact_sources": {
"type": "boolean",
"description": "Replace the per-source `sources` objects with `source_domains`, a deduped, sorted list of cited root domains. Defaults to false. Use when you need which domains were cited but not their exact URLs."
},
"include_response": {
"type": "boolean",
"description": "Include the full answer text on each row. Defaults to true. Set false to omit the `response` field entirely (the heaviest part of a row) when you only need which prompt/variation ran and how it scored."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"responses",
"total",
"page_num",
"page_size",
"has_more"
],
"properties": {
"total": {
"type": "number"
},
"notice": {
"type": "string"
},
"has_more": {
"type": "boolean"
},
"page_num": {
"type": "number"
},
"page_size": {
"type": "number"
},
"responses": {
"type": "array",
"items": {
"type": "object",
"required": [
"schedule",
"id",
"website_id",
"prompt_id",
"base_prompt",
"prompt",
"model",
"mentioned",
"position",
"cited",
"country",
"created_at",
"competitors"
],
"properties": {
"id": {
"type": "string"
},
"cited": {
"type": "boolean"
},
"model": {
"type": "string"
},
"prompt": {
"type": [
"string",
"null"
]
},
"country": {
"type": [
"string",
"null"
]
},
"sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"url",
"normalized_url",
"root_domain",
"suffix"
],
"properties": {
"url": {
"type": "string"
},
"suffix": {
"type": [
"string",
"null"
]
},
"root_domain": {
"type": "string"
},
"normalized_url": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
},
"position": {
"type": [
"number",
"null"
]
},
"response": {
"type": "string"
},
"schedule": {
"anyOf": [
{
"type": "string",
"const": "default"
},
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
]
},
"mentioned": {
"type": "boolean"
},
"prompt_id": {
"type": "string"
},
"created_at": {
"type": "string"
},
"website_id": {
"type": "string"
},
"base_prompt": {
"type": "string"
},
"competitors": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"url",
"position"
],
"properties": {
"id": {
"type": "string"
},
"url": {
"type": "string"
},
"name": {
"type": "string"
},
"position": {
"type": "number"
}
},
"additionalProperties": false
}
},
"source_domains": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get responses",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}Read the latest (or a specific) response-streaming run's whole-run state and response-queue progress. Only completed means downstream analysis has finished
| Parameter | Type | Description |
|---|---|---|
| website_id * | string | |
| workflow_id | string |
{
"name": "get_response_streaming_status",
"description": "Read the latest (or a specific) response-streaming run's whole-run state and response-queue progress. Only completed means downstream analysis has finished",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id"
],
"properties": {
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"workflow_id": {
"type": "string"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"state",
"workflow_id",
"created_at",
"updated_at",
"is_scheduled",
"finish_reason",
"config",
"progress",
"saved_response_progress"
],
"properties": {
"state": {
"enum": [
"idle",
"running",
"completed",
"failed",
"cancelled"
],
"type": "string",
"description": "Whole-run state. Only \"completed\" means response collection and downstream analysis have finished; \"running\" can coexist with 100 percent response progress."
},
"config": {
"type": "object",
"required": [
"mode",
"selected_prompt_count",
"models",
"prompt_variations",
"use_personas",
"use_locations",
"only_locations"
],
"properties": {
"mode": {
"anyOf": [
{
"enum": [
"all_prompts",
"selected_prompts"
],
"type": "string"
},
{
"type": "null"
}
]
},
"models": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "boolean"
}
},
{
"type": "null"
}
]
},
"use_personas": {
"type": [
"boolean",
"null"
]
},
"use_locations": {
"type": [
"boolean",
"null"
]
},
"only_locations": {
"type": [
"boolean",
"null"
]
},
"prompt_variations": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
{
"type": "null"
}
]
},
"selected_prompt_count": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"progress": {
"type": "object",
"required": [
"pending",
"processing",
"completed",
"failed",
"total",
"percentage"
],
"properties": {
"total": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"failed": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"pending": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"completed": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"percentage": {
"type": "number",
"maximum": 100,
"minimum": 0,
"description": "Percentage of response-queue items completed or failed. A value of 100 does not indicate downstream analysis readiness."
},
"processing": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
}
},
"description": "Response-queue completion only. These counts and percentage do not indicate downstream analysis readiness.",
"additionalProperties": false
},
"created_at": {
"type": [
"string",
"null"
]
},
"updated_at": {
"type": [
"string",
"null"
]
},
"workflow_id": {
"type": [
"string",
"null"
]
},
"is_scheduled": {
"type": [
"boolean",
"null"
]
},
"finish_reason": {
"anyOf": [
{
"enum": [
"credits_exhausted",
"credits_paused",
"subscription_inactive",
"organization_deleted",
"entitlement_unreadable",
"cancelled_by_user",
"responses_failed",
"items_stuck",
"attribute_extraction_failed",
"workflow_error",
"stale"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "Why a \"failed\" or \"cancelled\" run ended: credits_exhausted (no credits remaining), credits_paused (credit allocation paused by the partner), subscription_inactive, organization_deleted, entitlement_unreadable (billing could not be read; pending responses are retried by the backfill), cancelled_by_user, responses_failed (collection finished with failed responses), items_stuck, attribute_extraction_failed, workflow_error, stale. Null while running, for completed runs, and for runs older than this field."
},
"saved_response_progress": {
"anyOf": [
{
"type": "object",
"required": [
"planned_count",
"expected_count",
"completed_count",
"population_completed_at",
"initial_completed_count",
"initial_status",
"initial_terminal_at"
],
"properties": {
"planned_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"expected_count": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
{
"type": "null"
}
]
},
"initial_status": {
"anyOf": [
{
"enum": [
"completed",
"failed",
"cancelled"
],
"type": "string"
},
{
"type": "null"
}
]
},
"completed_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"initial_terminal_at": {
"type": [
"string",
"null"
]
},
"initial_completed_count": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
{
"type": "null"
}
]
},
"population_completed_at": {
"type": [
"string",
"null"
]
},
"completed_count_observed_at": {
"type": [
"string",
"null"
],
"description": "Observation time of the cached retained-response count. Null or absent means unmeasured; completedCount is not a measured zero. Reads never refresh counts."
},
"initial_completed_count_observed_at": {
"type": [
"string",
"null"
],
"description": "Observation time of the snapshot frozen at the first terminal transition; it can precede initialTerminalAt. Null means unmeasured."
}
},
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Cached retained-response counts, separate from execution-queue progress. A missing completed_count_observed_at means the count is unmeasured, not zero. Initial fields preserve the last observed snapshot at first terminal transition, including its observation time."
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get response streaming status",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}Fetch a single LLM response by id with full sources, mentions, and rank details.
| Parameter | Type | Description |
|---|---|---|
| website_id * | string | |
| response_id * | string |
{
"name": "get_response_detail",
"description": "Fetch a single LLM response by id with full sources, mentions, and rank details.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"response_id"
],
"properties": {
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"response_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"response"
],
"properties": {
"response": {
"type": "object",
"required": [
"schedule",
"id",
"website_id",
"prompt_id",
"base_prompt",
"prompt",
"model",
"response",
"mentioned",
"position",
"cited",
"country",
"created_at",
"sources",
"competitors"
],
"properties": {
"id": {
"type": "string"
},
"cited": {
"type": "boolean"
},
"model": {
"type": "string"
},
"prompt": {
"type": [
"string",
"null"
]
},
"country": {
"type": [
"string",
"null"
]
},
"sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"url",
"normalized_url",
"root_domain",
"suffix"
],
"properties": {
"url": {
"type": "string"
},
"suffix": {
"type": [
"string",
"null"
]
},
"root_domain": {
"type": "string"
},
"normalized_url": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
},
"position": {
"type": [
"number",
"null"
]
},
"response": {
"type": "string"
},
"schedule": {
"anyOf": [
{
"type": "string",
"const": "default"
},
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
]
},
"mentioned": {
"type": "boolean"
},
"prompt_id": {
"type": "string"
},
"created_at": {
"type": "string"
},
"website_id": {
"type": "string"
},
"base_prompt": {
"type": "string"
},
"competitors": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"url",
"position"
],
"properties": {
"id": {
"type": "string"
},
"url": {
"type": "string"
},
"name": {
"type": "string"
},
"position": {
"type": "number"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get response detail",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}List saved views (filter presets) for a website
| Parameter | Type | Description |
|---|---|---|
| website_id * | string |
{
"name": "get_saved_views",
"description": "List saved views (filter presets) for a website",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id"
],
"properties": {
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"saved_views"
],
"properties": {
"saved_views": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"icon",
"website_id",
"user_id",
"filters",
"created_at",
"updated_at",
"created_by"
],
"properties": {
"id": {
"type": "string"
},
"icon": {
"type": [
"string",
"null"
]
},
"name": {
"type": "string"
},
"filters": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"user_id": {
"type": [
"string",
"null"
]
},
"created_at": {
"type": [
"string",
"null"
]
},
"created_by": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"email",
"first_name",
"last_name",
"display_name"
],
"properties": {
"id": {
"type": "string"
},
"email": {
"type": "string"
},
"last_name": {
"type": [
"string",
"null"
]
},
"first_name": {
"type": [
"string",
"null"
]
},
"display_name": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"updated_at": {
"type": [
"string",
"null"
]
},
"website_id": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get saved views",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}List group-level saved views (filter presets) shared across the websites in a group
| Parameter | Type | Description |
|---|---|---|
| group_id * | string |
{
"name": "get_group_saved_views",
"description": "List group-level saved views (filter presets) shared across the websites in a group",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"group_id"
],
"properties": {
"group_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"group_saved_views"
],
"properties": {
"group_saved_views": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"icon",
"website_id",
"group_id",
"user_id",
"filters",
"created_at",
"created_by"
],
"properties": {
"id": {
"type": "string"
},
"icon": {
"type": "string"
},
"name": {
"type": "string"
},
"filters": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"user_id": {
"type": [
"string",
"null"
]
},
"group_id": {
"type": [
"string",
"null"
]
},
"created_at": {
"type": "string"
},
"created_by": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"email",
"first_name",
"last_name",
"display_name"
],
"properties": {
"id": {
"type": "string"
},
"email": {
"type": "string"
},
"last_name": {
"type": [
"string",
"null"
]
},
"first_name": {
"type": [
"string",
"null"
]
},
"display_name": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"updated_at": {
"type": "string"
},
"website_id": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get group saved views",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}Get credit balance for the organization
No parameters.
{
"name": "get_credits_organization",
"description": "Get credit balance for the organization",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"total"
],
"properties": {
"total": {
"type": "object",
"required": [
"balance",
"monthly",
"one_off"
],
"properties": {
"balance": {
"type": "number"
},
"monthly": {
"type": "number"
},
"one_off": {
"type": "number"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get credits organization",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}Get credit balance for a specific website
| Parameter | Type | Description |
|---|---|---|
| website_id * | string |
{
"name": "get_credits_website",
"description": "Get credit balance for a specific website",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id"
],
"properties": {
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"credits"
],
"properties": {
"credits": {
"type": "object",
"required": [
"total",
"monthly",
"one_off"
],
"properties": {
"total": {
"type": "number"
},
"monthly": {
"type": "object",
"required": [
"balance",
"next_reset_at"
],
"properties": {
"balance": {
"type": "number"
},
"next_reset_at": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
},
"one_off": {
"type": "object",
"required": [
"balance"
],
"properties": {
"balance": {
"type": "number"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get credits website",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}List all groups in the organization (global API key only)
| Parameter | Type | Description |
|---|---|---|
| external_id | string | Partner API keys only. Filter by the partner-issued external id mapped to a group. Non-partner API keys passing this field receive 403. Omit unless you are a partner integration. |
{
"name": "get_groups",
"description": "List all groups in the organization (global API key only)",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"external_id": {
"type": "string",
"minLength": 1,
"description": "Partner API keys only. Filter by the partner-issued external id mapped to a group. Non-partner API keys passing this field receive 403. Omit unless you are a partner integration."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"groups"
],
"properties": {
"groups": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"orgId",
"billingEnabled",
"createdAt",
"websites"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"orgId": {
"type": "string"
},
"websites": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"websiteUrl",
"websiteName"
],
"properties": {
"id": {
"type": "string"
},
"externalId": {
"type": [
"string",
"null"
]
},
"websiteUrl": {
"type": "string"
},
"websiteName": {
"type": "string"
}
},
"additionalProperties": false
}
},
"createdAt": {
"type": "string"
},
"externalId": {
"type": [
"string",
"null"
]
},
"billingEnabled": {
"type": "boolean"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get groups",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}Fetch a single group by id with its member websites.
| Parameter | Type | Description |
|---|---|---|
| group_id * | string |
{
"name": "get_group_detail",
"description": "Fetch a single group by id with its member websites.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"group_id"
],
"properties": {
"group_id": {
"type": "string"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"group"
],
"properties": {
"group": {
"type": "object",
"required": [
"id",
"name",
"orgId",
"billingEnabled",
"createdAt",
"websites"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"orgId": {
"type": "string"
},
"websites": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"websiteUrl",
"websiteName"
],
"properties": {
"id": {
"type": "string"
},
"externalId": {
"type": [
"string",
"null"
]
},
"websiteUrl": {
"type": "string"
},
"websiteName": {
"type": "string"
}
},
"additionalProperties": false
}
},
"createdAt": {
"type": "string"
},
"externalId": {
"type": [
"string",
"null"
]
},
"billingEnabled": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get group detail",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}Get cumulative share of voice — overall SOV for each competitor across the date range. Each entry also includes relative_mention_rate: the share of responses mentioning any tracked brand that mention this entity.
| Parameter | Type | Description |
|---|---|---|
| filters * | object | |
| website_id * | string |
{
"name": "get_share_of_voice_cumulative",
"description": "Get cumulative share of voice — overall SOV for each competitor across the date range. Each entry also includes relative_mention_rate: the share of responses mentioning any tracked brand that mention this entity.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"filters"
],
"properties": {
"filters": {
"type": "object",
"required": [
"start_date"
],
"properties": {
"models": {
"type": "array",
"items": {
"enum": [
"chatgpt",
"perplexity",
"gemini",
"google_ai_overview",
"copilot",
"claude",
"ai_mode",
"grok",
"deepseek",
"meta_ai",
"mistral"
],
"type": "string"
},
"description": "AI models to include, as an array even for one model — e.g. [\"chatgpt\", \"perplexity\"]. Omit to include all models."
},
"end_date": {
"type": "string",
"description": "End of the date range, inclusive. Date-only values include the UTC day through 23:59:59.999; timestamps keep their exact instant. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"prompt_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Prompt UUIDs to filter to, as an array even for one id. Omit for all prompts."
},
"start_date": {
"type": "string",
"description": "Start of the date range. Required. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"persona_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Persona UUIDs to filter to, as an array even for one id. Omit for all personas."
},
"prompt_tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Prompt tag IDs to filter prompts by, as an array (list tags with get_prompt_tags). Omit for all tags."
},
"prompt_type": {
"enum": [
"branded",
"non_branded"
],
"type": "string",
"description": "Filter prompts by type: \"branded\" (mentions the brand) or \"non_branded\". Omit for both."
},
"schedule_id": {
"anyOf": [
{
"enum": [
"default",
"manual"
],
"type": "string"
},
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
],
"description": "One schedule: \"default\" or a custom/archived schedule UUID. Omit for Default, which includes all pre-cutover history and ad hoc runs. The retired \"manual\" token is accepted as an alias of \"default\". Schedules cannot be combined."
},
"location_ids": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "string",
"const": "no-location"
}
]
},
"description": "Location UUIDs to filter to, as an array even for one id. The literal string \"no-location\" selects responses that ran without a location. Omit for all locations."
},
"prompt_status": {
"enum": [
"active",
"paused"
],
"type": "string",
"description": "Filter prompts by tracking status: \"active\" or \"paused\". Omit for both."
},
"saved_view_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "Saved view to apply (list them with get_saved_views). Its filters apply as the dashboard's metric cards apply them, including its defaults of active prompts and every model. Any filter also sent here replaces the view's value for that field. The view's date range is ignored: start_date and end_date decide the window."
},
"competitor_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Competitor UUIDs to filter to, as an array even for one id. Omit for all competitors."
},
"variation_filter": {
"type": "array",
"items": {
"enum": [
"variation",
"prompt"
],
"type": "string"
},
"description": "Which prompt rows to include, as an array: \"prompt\" for base prompts, \"variation\" for generated variations, or both. Omit for both."
},
"target_identifiers": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "string",
"const": "no-identifier"
}
]
},
"description": "Target identifier strings to filter to, as an array even for one value. The literal string \"no-identifier\" selects responses with no target identifier. Omit for all."
},
"prompt_tags_operator": {
"enum": [
"is_any_of",
"has_all_of"
],
"type": "string",
"description": "How prompt_tags combine: \"is_any_of\" matches prompts with any listed tag, \"has_all_of\" only prompts carrying every listed tag."
}
}
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"value",
"relative_mention_rate",
"absolute_value",
"is_self"
],
"properties": {
"name": {
"type": "string"
},
"value": {
"type": "number"
},
"is_self": {
"type": "boolean"
},
"absolute_value": {
"type": "number"
},
"relative_mention_rate": {
"type": "number"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get share of voice cumulative",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}Get share of voice over time — how often the website is mentioned vs competitors, grouped by day. Each entry also includes relative_mention_rate: the share of that day's responses mentioning any tracked brand that mention this entity.
| Parameter | Type | Description |
|---|---|---|
| filters * | object | |
| website_id * | string |
{
"name": "get_share_of_voice_time_series",
"description": "Get share of voice over time — how often the website is mentioned vs competitors, grouped by day. Each entry also includes relative_mention_rate: the share of that day's responses mentioning any tracked brand that mention this entity.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"filters"
],
"properties": {
"filters": {
"type": "object",
"required": [
"start_date"
],
"properties": {
"models": {
"type": "array",
"items": {
"enum": [
"chatgpt",
"perplexity",
"gemini",
"google_ai_overview",
"copilot",
"claude",
"ai_mode",
"grok",
"deepseek",
"meta_ai",
"mistral"
],
"type": "string"
},
"description": "AI models to include, as an array even for one model — e.g. [\"chatgpt\", \"perplexity\"]. Omit to include all models."
},
"end_date": {
"type": "string",
"description": "End of the date range, inclusive. Date-only values include the UTC day through 23:59:59.999; timestamps keep their exact instant. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"prompt_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Prompt UUIDs to filter to, as an array even for one id. Omit for all prompts."
},
"start_date": {
"type": "string",
"description": "Start of the date range. Required. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"persona_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Persona UUIDs to filter to, as an array even for one id. Omit for all personas."
},
"prompt_tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Prompt tag IDs to filter prompts by, as an array (list tags with get_prompt_tags). Omit for all tags."
},
"prompt_type": {
"enum": [
"branded",
"non_branded"
],
"type": "string",
"description": "Filter prompts by type: \"branded\" (mentions the brand) or \"non_branded\". Omit for both."
},
"schedule_id": {
"anyOf": [
{
"enum": [
"default",
"manual"
],
"type": "string"
},
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
],
"description": "One schedule: \"default\" or a custom/archived schedule UUID. Omit for Default, which includes all pre-cutover history and ad hoc runs. The retired \"manual\" token is accepted as an alias of \"default\". Schedules cannot be combined."
},
"location_ids": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "string",
"const": "no-location"
}
]
},
"description": "Location UUIDs to filter to, as an array even for one id. The literal string \"no-location\" selects responses that ran without a location. Omit for all locations."
},
"prompt_status": {
"enum": [
"active",
"paused"
],
"type": "string",
"description": "Filter prompts by tracking status: \"active\" or \"paused\". Omit for both."
},
"saved_view_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "Saved view to apply (list them with get_saved_views). Its filters apply as the dashboard's metric cards apply them, including its defaults of active prompts and every model. Any filter also sent here replaces the view's value for that field. The view's date range is ignored: start_date and end_date decide the window."
},
"competitor_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Competitor UUIDs to filter to, as an array even for one id. Omit for all competitors."
},
"variation_filter": {
"type": "array",
"items": {
"enum": [
"variation",
"prompt"
],
"type": "string"
},
"description": "Which prompt rows to include, as an array: \"prompt\" for base prompts, \"variation\" for generated variations, or both. Omit for both."
},
"target_identifiers": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "string",
"const": "no-identifier"
}
]
},
"description": "Target identifier strings to filter to, as an array even for one value. The literal string \"no-identifier\" selects responses with no target identifier. Omit for all."
},
"prompt_tags_operator": {
"enum": [
"is_any_of",
"has_all_of"
],
"type": "string",
"description": "How prompt_tags combine: \"is_any_of\" matches prompts with any listed tag, \"has_all_of\" only prompts carrying every listed tag."
}
}
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"date"
],
"properties": {
"date": {
"type": "string"
}
},
"additionalProperties": {
"type": "object",
"required": [
"value",
"relative_mention_rate",
"is_self"
],
"properties": {
"value": {
"type": "number"
},
"is_self": {
"type": "boolean"
},
"relative_mention_rate": {
"type": "number"
}
},
"additionalProperties": false
}
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get share of voice time series",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}Get cumulative citation rate — average citation rate for each competitor across the date range. citation_rate is absolute (share of all responses); relative_citation_rate is the share of responses citing the website or any tracked competitor.
| Parameter | Type | Description |
|---|---|---|
| filters * | object | |
| website_id * | string |
{
"name": "get_citation_rate_cumulative",
"description": "Get cumulative citation rate — average citation rate for each competitor across the date range. citation_rate is absolute (share of all responses); relative_citation_rate is the share of responses citing the website or any tracked competitor.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"filters"
],
"properties": {
"filters": {
"type": "object",
"required": [
"start_date"
],
"properties": {
"models": {
"type": "array",
"items": {
"enum": [
"chatgpt",
"perplexity",
"gemini",
"google_ai_overview",
"copilot",
"claude",
"ai_mode",
"grok",
"deepseek",
"meta_ai",
"mistral"
],
"type": "string"
},
"description": "AI models to include, as an array even for one model — e.g. [\"chatgpt\", \"perplexity\"]. Omit to include all models."
},
"end_date": {
"type": "string",
"description": "End of the date range, inclusive. Date-only values include the UTC day through 23:59:59.999; timestamps keep their exact instant. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"prompt_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Prompt UUIDs to filter to, as an array even for one id. Omit for all prompts."
},
"start_date": {
"type": "string",
"description": "Start of the date range. Required. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"persona_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Persona UUIDs to filter to, as an array even for one id. Omit for all personas."
},
"prompt_tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Prompt tag IDs to filter prompts by, as an array (list tags with get_prompt_tags). Omit for all tags."
},
"prompt_type": {
"enum": [
"branded",
"non_branded"
],
"type": "string",
"description": "Filter prompts by type: \"branded\" (mentions the brand) or \"non_branded\". Omit for both."
},
"schedule_id": {
"anyOf": [
{
"enum": [
"default",
"manual"
],
"type": "string"
},
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
],
"description": "One schedule: \"default\" or a custom/archived schedule UUID. Omit for Default, which includes all pre-cutover history and ad hoc runs. The retired \"manual\" token is accepted as an alias of \"default\". Schedules cannot be combined."
},
"location_ids": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "string",
"const": "no-location"
}
]
},
"description": "Location UUIDs to filter to, as an array even for one id. The literal string \"no-location\" selects responses that ran without a location. Omit for all locations."
},
"prompt_status": {
"enum": [
"active",
"paused"
],
"type": "string",
"description": "Filter prompts by tracking status: \"active\" or \"paused\". Omit for both."
},
"saved_view_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "Saved view to apply (list them with get_saved_views). Its filters apply as the dashboard's metric cards apply them, including its defaults of active prompts and every model. Any filter also sent here replaces the view's value for that field. The view's date range is ignored: start_date and end_date decide the window."
},
"competitor_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Competitor UUIDs to filter to, as an array even for one id. Omit for all competitors."
},
"variation_filter": {
"type": "array",
"items": {
"enum": [
"variation",
"prompt"
],
"type": "string"
},
"description": "Which prompt rows to include, as an array: \"prompt\" for base prompts, \"variation\" for generated variations, or both. Omit for both."
},
"target_identifiers": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "string",
"const": "no-identifier"
}
]
},
"description": "Target identifier strings to filter to, as an array even for one value. The literal string \"no-identifier\" selects responses with no target identifier. Omit for all."
},
"prompt_tags_operator": {
"enum": [
"is_any_of",
"has_all_of"
],
"type": "string",
"description": "How prompt_tags combine: \"is_any_of\" matches prompts with any listed tag, \"has_all_of\" only prompts carrying every listed tag."
}
}
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"required": [
"citation_rate",
"relative_citation_rate",
"is_self"
],
"properties": {
"is_self": {
"type": "boolean"
},
"citation_rate": {
"type": "number"
},
"relative_citation_rate": {
"type": "number"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get citation rate cumulative",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}Get citation rate over time — how often AI models cite (link to) the website, grouped by day. citation_rate is absolute (share of that day's responses); relative_citation_rate is the share of that day's responses citing the website or any tracked competitor.
| Parameter | Type | Description |
|---|---|---|
| filters * | object | |
| website_id * | string |
{
"name": "get_citation_rate_time_series",
"description": "Get citation rate over time — how often AI models cite (link to) the website, grouped by day. citation_rate is absolute (share of that day's responses); relative_citation_rate is the share of that day's responses citing the website or any tracked competitor.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"filters"
],
"properties": {
"filters": {
"type": "object",
"required": [
"start_date"
],
"properties": {
"models": {
"type": "array",
"items": {
"enum": [
"chatgpt",
"perplexity",
"gemini",
"google_ai_overview",
"copilot",
"claude",
"ai_mode",
"grok",
"deepseek",
"meta_ai",
"mistral"
],
"type": "string"
},
"description": "AI models to include, as an array even for one model — e.g. [\"chatgpt\", \"perplexity\"]. Omit to include all models."
},
"end_date": {
"type": "string",
"description": "End of the date range, inclusive. Date-only values include the UTC day through 23:59:59.999; timestamps keep their exact instant. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"prompt_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Prompt UUIDs to filter to, as an array even for one id. Omit for all prompts."
},
"start_date": {
"type": "string",
"description": "Start of the date range. Required. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"persona_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Persona UUIDs to filter to, as an array even for one id. Omit for all personas."
},
"prompt_tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Prompt tag IDs to filter prompts by, as an array (list tags with get_prompt_tags). Omit for all tags."
},
"prompt_type": {
"enum": [
"branded",
"non_branded"
],
"type": "string",
"description": "Filter prompts by type: \"branded\" (mentions the brand) or \"non_branded\". Omit for both."
},
"schedule_id": {
"anyOf": [
{
"enum": [
"default",
"manual"
],
"type": "string"
},
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
],
"description": "One schedule: \"default\" or a custom/archived schedule UUID. Omit for Default, which includes all pre-cutover history and ad hoc runs. The retired \"manual\" token is accepted as an alias of \"default\". Schedules cannot be combined."
},
"location_ids": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "string",
"const": "no-location"
}
]
},
"description": "Location UUIDs to filter to, as an array even for one id. The literal string \"no-location\" selects responses that ran without a location. Omit for all locations."
},
"prompt_status": {
"enum": [
"active",
"paused"
],
"type": "string",
"description": "Filter prompts by tracking status: \"active\" or \"paused\". Omit for both."
},
"saved_view_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "Saved view to apply (list them with get_saved_views). Its filters apply as the dashboard's metric cards apply them, including its defaults of active prompts and every model. Any filter also sent here replaces the view's value for that field. The view's date range is ignored: start_date and end_date decide the window."
},
"competitor_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Competitor UUIDs to filter to, as an array even for one id. Omit for all competitors."
},
"variation_filter": {
"type": "array",
"items": {
"enum": [
"variation",
"prompt"
],
"type": "string"
},
"description": "Which prompt rows to include, as an array: \"prompt\" for base prompts, \"variation\" for generated variations, or both. Omit for both."
},
"target_identifiers": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "string",
"const": "no-identifier"
}
]
},
"description": "Target identifier strings to filter to, as an array even for one value. The literal string \"no-identifier\" selects responses with no target identifier. Omit for all."
},
"prompt_tags_operator": {
"enum": [
"is_any_of",
"has_all_of"
],
"type": "string",
"description": "How prompt_tags combine: \"is_any_of\" matches prompts with any listed tag, \"has_all_of\" only prompts carrying every listed tag."
}
}
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"date",
"metrics"
],
"properties": {
"date": {
"type": "string"
},
"metrics": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"required": [
"citation_rate",
"relative_citation_rate",
"is_self"
],
"properties": {
"is_self": {
"type": "boolean"
},
"citation_rate": {
"type": "number"
},
"relative_citation_rate": {
"type": "number"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get citation rate time series",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}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.
| Parameter | Type | Description |
|---|---|---|
| filters * | object | |
| website_id * | string |
{
"name": "get_mention_rate_cumulative",
"description": "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.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"filters"
],
"properties": {
"filters": {
"type": "object",
"required": [
"start_date"
],
"properties": {
"models": {
"type": "array",
"items": {
"enum": [
"chatgpt",
"perplexity",
"gemini",
"google_ai_overview",
"copilot",
"claude",
"ai_mode",
"grok",
"deepseek",
"meta_ai",
"mistral"
],
"type": "string"
},
"description": "AI models to include, as an array even for one model — e.g. [\"chatgpt\", \"perplexity\"]. Omit to include all models."
},
"end_date": {
"type": "string",
"description": "End of the date range, inclusive. Date-only values include the UTC day through 23:59:59.999; timestamps keep their exact instant. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"prompt_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Prompt UUIDs to filter to, as an array even for one id. Omit for all prompts."
},
"start_date": {
"type": "string",
"description": "Start of the date range. Required. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"persona_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Persona UUIDs to filter to, as an array even for one id. Omit for all personas."
},
"prompt_tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Prompt tag IDs to filter prompts by, as an array (list tags with get_prompt_tags). Omit for all tags."
},
"prompt_type": {
"enum": [
"branded",
"non_branded"
],
"type": "string",
"description": "Filter prompts by type: \"branded\" (mentions the brand) or \"non_branded\". Omit for both."
},
"schedule_id": {
"anyOf": [
{
"enum": [
"default",
"manual"
],
"type": "string"
},
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
],
"description": "One schedule: \"default\" or a custom/archived schedule UUID. Omit for Default, which includes all pre-cutover history and ad hoc runs. The retired \"manual\" token is accepted as an alias of \"default\". Schedules cannot be combined."
},
"location_ids": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "string",
"const": "no-location"
}
]
},
"description": "Location UUIDs to filter to, as an array even for one id. The literal string \"no-location\" selects responses that ran without a location. Omit for all locations."
},
"prompt_status": {
"enum": [
"active",
"paused"
],
"type": "string",
"description": "Filter prompts by tracking status: \"active\" or \"paused\". Omit for both."
},
"saved_view_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "Saved view to apply (list them with get_saved_views). Its filters apply as the dashboard's metric cards apply them, including its defaults of active prompts and every model. Any filter also sent here replaces the view's value for that field. The view's date range is ignored: start_date and end_date decide the window."
},
"competitor_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Competitor UUIDs to filter to, as an array even for one id. Omit for all competitors."
},
"variation_filter": {
"type": "array",
"items": {
"enum": [
"variation",
"prompt"
],
"type": "string"
},
"description": "Which prompt rows to include, as an array: \"prompt\" for base prompts, \"variation\" for generated variations, or both. Omit for both."
},
"target_identifiers": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "string",
"const": "no-identifier"
}
]
},
"description": "Target identifier strings to filter to, as an array even for one value. The literal string \"no-identifier\" selects responses with no target identifier. Omit for all."
},
"prompt_tags_operator": {
"enum": [
"is_any_of",
"has_all_of"
],
"type": "string",
"description": "How prompt_tags combine: \"is_any_of\" matches prompts with any listed tag, \"has_all_of\" only prompts carrying every listed tag."
}
}
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"required": [
"mention_rate",
"relative_mention_rate",
"is_self"
],
"properties": {
"is_self": {
"type": "boolean"
},
"mention_rate": {
"type": "number"
},
"relative_mention_rate": {
"type": "number"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get mention rate cumulative",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}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.
| Parameter | Type | Description |
|---|---|---|
| filters * | object | |
| website_id * | string |
{
"name": "get_mention_rate_time_series",
"description": "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.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"filters"
],
"properties": {
"filters": {
"type": "object",
"required": [
"start_date"
],
"properties": {
"models": {
"type": "array",
"items": {
"enum": [
"chatgpt",
"perplexity",
"gemini",
"google_ai_overview",
"copilot",
"claude",
"ai_mode",
"grok",
"deepseek",
"meta_ai",
"mistral"
],
"type": "string"
},
"description": "AI models to include, as an array even for one model — e.g. [\"chatgpt\", \"perplexity\"]. Omit to include all models."
},
"end_date": {
"type": "string",
"description": "End of the date range, inclusive. Date-only values include the UTC day through 23:59:59.999; timestamps keep their exact instant. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"prompt_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Prompt UUIDs to filter to, as an array even for one id. Omit for all prompts."
},
"start_date": {
"type": "string",
"description": "Start of the date range. Required. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"persona_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Persona UUIDs to filter to, as an array even for one id. Omit for all personas."
},
"prompt_tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Prompt tag IDs to filter prompts by, as an array (list tags with get_prompt_tags). Omit for all tags."
},
"prompt_type": {
"enum": [
"branded",
"non_branded"
],
"type": "string",
"description": "Filter prompts by type: \"branded\" (mentions the brand) or \"non_branded\". Omit for both."
},
"schedule_id": {
"anyOf": [
{
"enum": [
"default",
"manual"
],
"type": "string"
},
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
],
"description": "One schedule: \"default\" or a custom/archived schedule UUID. Omit for Default, which includes all pre-cutover history and ad hoc runs. The retired \"manual\" token is accepted as an alias of \"default\". Schedules cannot be combined."
},
"location_ids": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "string",
"const": "no-location"
}
]
},
"description": "Location UUIDs to filter to, as an array even for one id. The literal string \"no-location\" selects responses that ran without a location. Omit for all locations."
},
"prompt_status": {
"enum": [
"active",
"paused"
],
"type": "string",
"description": "Filter prompts by tracking status: \"active\" or \"paused\". Omit for both."
},
"saved_view_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "Saved view to apply (list them with get_saved_views). Its filters apply as the dashboard's metric cards apply them, including its defaults of active prompts and every model. Any filter also sent here replaces the view's value for that field. The view's date range is ignored: start_date and end_date decide the window."
},
"competitor_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Competitor UUIDs to filter to, as an array even for one id. Omit for all competitors."
},
"variation_filter": {
"type": "array",
"items": {
"enum": [
"variation",
"prompt"
],
"type": "string"
},
"description": "Which prompt rows to include, as an array: \"prompt\" for base prompts, \"variation\" for generated variations, or both. Omit for both."
},
"target_identifiers": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "string",
"const": "no-identifier"
}
]
},
"description": "Target identifier strings to filter to, as an array even for one value. The literal string \"no-identifier\" selects responses with no target identifier. Omit for all."
},
"prompt_tags_operator": {
"enum": [
"is_any_of",
"has_all_of"
],
"type": "string",
"description": "How prompt_tags combine: \"is_any_of\" matches prompts with any listed tag, \"has_all_of\" only prompts carrying every listed tag."
}
}
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"date",
"metrics"
],
"properties": {
"date": {
"type": "string"
},
"metrics": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"required": [
"mention_rate",
"relative_mention_rate",
"is_self"
],
"properties": {
"is_self": {
"type": "boolean"
},
"mention_rate": {
"type": "number"
},
"relative_mention_rate": {
"type": "number"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get mention rate time series",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}Get cumulative position — average ranking position for each competitor across the date range.
| Parameter | Type | Description |
|---|---|---|
| filters * | object | |
| website_id * | string |
{
"name": "get_position_cumulative",
"description": "Get cumulative position — average ranking position for each competitor across the date range.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"filters"
],
"properties": {
"filters": {
"type": "object",
"required": [
"start_date"
],
"properties": {
"models": {
"type": "array",
"items": {
"enum": [
"chatgpt",
"perplexity",
"gemini",
"google_ai_overview",
"copilot",
"claude",
"ai_mode",
"grok",
"deepseek",
"meta_ai",
"mistral"
],
"type": "string"
},
"description": "AI models to include, as an array even for one model — e.g. [\"chatgpt\", \"perplexity\"]. Omit to include all models."
},
"end_date": {
"type": "string",
"description": "End of the date range, inclusive. Date-only values include the UTC day through 23:59:59.999; timestamps keep their exact instant. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"prompt_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Prompt UUIDs to filter to, as an array even for one id. Omit for all prompts."
},
"start_date": {
"type": "string",
"description": "Start of the date range. Required. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"persona_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Persona UUIDs to filter to, as an array even for one id. Omit for all personas."
},
"prompt_tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Prompt tag IDs to filter prompts by, as an array (list tags with get_prompt_tags). Omit for all tags."
},
"prompt_type": {
"enum": [
"branded",
"non_branded"
],
"type": "string",
"description": "Filter prompts by type: \"branded\" (mentions the brand) or \"non_branded\". Omit for both."
},
"schedule_id": {
"anyOf": [
{
"enum": [
"default",
"manual"
],
"type": "string"
},
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
],
"description": "One schedule: \"default\" or a custom/archived schedule UUID. Omit for Default, which includes all pre-cutover history and ad hoc runs. The retired \"manual\" token is accepted as an alias of \"default\". Schedules cannot be combined."
},
"location_ids": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "string",
"const": "no-location"
}
]
},
"description": "Location UUIDs to filter to, as an array even for one id. The literal string \"no-location\" selects responses that ran without a location. Omit for all locations."
},
"prompt_status": {
"enum": [
"active",
"paused"
],
"type": "string",
"description": "Filter prompts by tracking status: \"active\" or \"paused\". Omit for both."
},
"saved_view_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "Saved view to apply (list them with get_saved_views). Its filters apply as the dashboard's metric cards apply them, including its defaults of active prompts and every model. Any filter also sent here replaces the view's value for that field. The view's date range is ignored: start_date and end_date decide the window."
},
"competitor_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Competitor UUIDs to filter to, as an array even for one id. Omit for all competitors."
},
"variation_filter": {
"type": "array",
"items": {
"enum": [
"variation",
"prompt"
],
"type": "string"
},
"description": "Which prompt rows to include, as an array: \"prompt\" for base prompts, \"variation\" for generated variations, or both. Omit for both."
},
"target_identifiers": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "string",
"const": "no-identifier"
}
]
},
"description": "Target identifier strings to filter to, as an array even for one value. The literal string \"no-identifier\" selects responses with no target identifier. Omit for all."
},
"prompt_tags_operator": {
"enum": [
"is_any_of",
"has_all_of"
],
"type": "string",
"description": "How prompt_tags combine: \"is_any_of\" matches prompts with any listed tag, \"has_all_of\" only prompts carrying every listed tag."
}
}
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"required": [
"avg_position",
"is_self"
],
"properties": {
"is_self": {
"type": "boolean"
},
"avg_position": {
"type": "number"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get position cumulative",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}Get ranking position over time — average position of the website in AI model responses, grouped by day.
| Parameter | Type | Description |
|---|---|---|
| filters * | object | |
| website_id * | string |
{
"name": "get_position_time_series",
"description": "Get ranking position over time — average position of the website in AI model responses, grouped by day.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"filters"
],
"properties": {
"filters": {
"type": "object",
"required": [
"start_date"
],
"properties": {
"models": {
"type": "array",
"items": {
"enum": [
"chatgpt",
"perplexity",
"gemini",
"google_ai_overview",
"copilot",
"claude",
"ai_mode",
"grok",
"deepseek",
"meta_ai",
"mistral"
],
"type": "string"
},
"description": "AI models to include, as an array even for one model — e.g. [\"chatgpt\", \"perplexity\"]. Omit to include all models."
},
"end_date": {
"type": "string",
"description": "End of the date range, inclusive. Date-only values include the UTC day through 23:59:59.999; timestamps keep their exact instant. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"prompt_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Prompt UUIDs to filter to, as an array even for one id. Omit for all prompts."
},
"start_date": {
"type": "string",
"description": "Start of the date range. Required. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"persona_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Persona UUIDs to filter to, as an array even for one id. Omit for all personas."
},
"prompt_tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Prompt tag IDs to filter prompts by, as an array (list tags with get_prompt_tags). Omit for all tags."
},
"prompt_type": {
"enum": [
"branded",
"non_branded"
],
"type": "string",
"description": "Filter prompts by type: \"branded\" (mentions the brand) or \"non_branded\". Omit for both."
},
"schedule_id": {
"anyOf": [
{
"enum": [
"default",
"manual"
],
"type": "string"
},
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
],
"description": "One schedule: \"default\" or a custom/archived schedule UUID. Omit for Default, which includes all pre-cutover history and ad hoc runs. The retired \"manual\" token is accepted as an alias of \"default\". Schedules cannot be combined."
},
"location_ids": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "string",
"const": "no-location"
}
]
},
"description": "Location UUIDs to filter to, as an array even for one id. The literal string \"no-location\" selects responses that ran without a location. Omit for all locations."
},
"prompt_status": {
"enum": [
"active",
"paused"
],
"type": "string",
"description": "Filter prompts by tracking status: \"active\" or \"paused\". Omit for both."
},
"saved_view_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "Saved view to apply (list them with get_saved_views). Its filters apply as the dashboard's metric cards apply them, including its defaults of active prompts and every model. Any filter also sent here replaces the view's value for that field. The view's date range is ignored: start_date and end_date decide the window."
},
"competitor_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Competitor UUIDs to filter to, as an array even for one id. Omit for all competitors."
},
"variation_filter": {
"type": "array",
"items": {
"enum": [
"variation",
"prompt"
],
"type": "string"
},
"description": "Which prompt rows to include, as an array: \"prompt\" for base prompts, \"variation\" for generated variations, or both. Omit for both."
},
"target_identifiers": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "string",
"const": "no-identifier"
}
]
},
"description": "Target identifier strings to filter to, as an array even for one value. The literal string \"no-identifier\" selects responses with no target identifier. Omit for all."
},
"prompt_tags_operator": {
"enum": [
"is_any_of",
"has_all_of"
],
"type": "string",
"description": "How prompt_tags combine: \"is_any_of\" matches prompts with any listed tag, \"has_all_of\" only prompts carrying every listed tag."
}
}
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"required": [
"percentile_ranking",
"avg_position",
"is_self"
],
"properties": {
"is_self": {
"type": "boolean"
},
"avg_position": {
"type": "number"
},
"percentile_ranking": {
"type": "number"
}
},
"additionalProperties": false
}
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get position time series",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}Get position distribution: share of responses where the brand ranks top/middle/bottom across the date range.
| Parameter | Type | Description |
|---|---|---|
| filters * | object | |
| website_id * | string |
{
"name": "get_position_distribution",
"description": "Get position distribution: share of responses where the brand ranks top/middle/bottom across the date range.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"filters"
],
"properties": {
"filters": {
"type": "object",
"required": [
"start_date"
],
"properties": {
"models": {
"type": "array",
"items": {
"enum": [
"chatgpt",
"perplexity",
"gemini",
"google_ai_overview",
"copilot",
"claude",
"ai_mode",
"grok",
"deepseek",
"meta_ai",
"mistral"
],
"type": "string"
},
"description": "AI models to include, as an array even for one model — e.g. [\"chatgpt\", \"perplexity\"]. Omit to include all models."
},
"end_date": {
"type": "string",
"description": "End of the date range, inclusive. Date-only values include the UTC day through 23:59:59.999; timestamps keep their exact instant. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"prompt_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Prompt UUIDs to filter to, as an array even for one id. Omit for all prompts."
},
"start_date": {
"type": "string",
"description": "Start of the date range. Required. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"persona_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Persona UUIDs to filter to, as an array even for one id. Omit for all personas."
},
"prompt_tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Prompt tag IDs to filter prompts by, as an array (list tags with get_prompt_tags). Omit for all tags."
},
"prompt_type": {
"enum": [
"branded",
"non_branded"
],
"type": "string",
"description": "Filter prompts by type: \"branded\" (mentions the brand) or \"non_branded\". Omit for both."
},
"schedule_id": {
"anyOf": [
{
"enum": [
"default",
"manual"
],
"type": "string"
},
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
],
"description": "One schedule: \"default\" or a custom/archived schedule UUID. Omit for Default, which includes all pre-cutover history and ad hoc runs. The retired \"manual\" token is accepted as an alias of \"default\". Schedules cannot be combined."
},
"location_ids": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "string",
"const": "no-location"
}
]
},
"description": "Location UUIDs to filter to, as an array even for one id. The literal string \"no-location\" selects responses that ran without a location. Omit for all locations."
},
"prompt_status": {
"enum": [
"active",
"paused"
],
"type": "string",
"description": "Filter prompts by tracking status: \"active\" or \"paused\". Omit for both."
},
"saved_view_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "Saved view to apply (list them with get_saved_views). Its filters apply as the dashboard's metric cards apply them, including its defaults of active prompts and every model. Any filter also sent here replaces the view's value for that field. The view's date range is ignored: start_date and end_date decide the window."
},
"competitor_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Competitor UUIDs to filter to, as an array even for one id. Omit for all competitors."
},
"variation_filter": {
"type": "array",
"items": {
"enum": [
"variation",
"prompt"
],
"type": "string"
},
"description": "Which prompt rows to include, as an array: \"prompt\" for base prompts, \"variation\" for generated variations, or both. Omit for both."
},
"target_identifiers": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "string",
"const": "no-identifier"
}
]
},
"description": "Target identifier strings to filter to, as an array even for one value. The literal string \"no-identifier\" selects responses with no target identifier. Omit for all."
},
"prompt_tags_operator": {
"enum": [
"is_any_of",
"has_all_of"
],
"type": "string",
"description": "How prompt_tags combine: \"is_any_of\" matches prompts with any listed tag, \"has_all_of\" only prompts carrying every listed tag."
}
}
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"top",
"middle",
"bottom"
],
"properties": {
"top": {
"type": "number"
},
"bottom": {
"type": "number"
},
"middle": {
"type": "number"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get position distribution",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}Query aggregated metrics for brand performance, competitors, sources, citations, and response trends. Use query_rows for individual records. Mentions: from "response_mentions". Citations: from "citations". On either, where { is_website: true } selects the brand; { is_competitor: true } selects competitors; { entity_id: { eq: "<uuid>" } } selects one entity. Filter/group models by model_category (display names like "ChatGPT", "Claude"), never "model". Dimensions vary by cube; source_mentions has no prompt/model dimensions. Group by week (Monday start) or month wherever date groups. prompt_status is the paused flag (true = paused). Measures: count, count_distinct, avg, sum, min, max; per-measure where enables conditional aggregation. Use compare for two date ranges. When grouping by IDs, use alsoSelect for names: entity_id/entity_name, prompt_id/prompt_text, prompt_topic_id/topic_name (prompts uses topic_id). Cited pages mentioning competitors but not the brand: from "sources", where { source_mentions_entity: { hasSome: [competitorIds], hasNone: [brandId] } }. Also works on "source_mentions". Checks all stored page mentions per URL/website. Date/model on sources scope AI responses; extracted page content may be older than the live page. Content-hub attribution: on "sources", where { is_attributed_content: true }; by: ["content_id"], alsoSelect: ["content_title"]. Add content_type to by for type, or group by content_type alone. Read articles from "contents" via query_rows. Schedule: select one "default" or custom/archived UUID from the catalog, or an array of them to combine schedules. Omit for caller default (current page in Ask Athena); explicit schedule overrides it. Top-level prompt_schedule_kind/id equality filters remain supported but must not conflict with schedule. Historical provenance is independent of current prompt membership; website-level cubes are unaffected.
| Parameter | Type | Description |
|---|---|---|
| by | array | GROUP BY dimensions. Omit for scalar result. |
| from * | string | Dataset to query. Cubes and their contracts: Each cube lists its selectable fields, then: filter-only (usable only in where), alsoSelect (name←id: group by the id, pass the name in alsoSelect), groupable (the only fields accepted in by), max limit (the most rows one call returns), and order by index… |
Query individual analytics rows. Use for qualitative data like response text, specific identifiers, or individual mentions. Schedule selection: pass schedule: "default" or a custom/archived UUID from the schedule catalog, or an array of them to combine schedules. Omit to use the caller default (Ask Athena uses the current page selection). Explicit selection overrides that default. Existing top-level equality predicates on prompt_schedule_kind/id remain supported, but cannot conflict with schedule. Historical provenance does not change with current prompt membership. Website-level cubes are unaffected. Cubes (same set as query_metrics): attributes, citations, competitors, contents, prompts, response_mentions, responses, source_mentions, sources, topics, websites. Returns { rows, nextCursor, hasMore }. Pass nextCursor back as "after" to paginate. prompt_status is the prompt's paused flag (boolean, true = paused), not a status string. On the responses cube, content is hydrated from Postgres and can only be selected. Do not filter or sort by content. Use search_terms_in_responses for text frequency analysis. Use query_metrics for aggregates instead.
| Parameter | Type | Description |
|---|---|---|
| from * | string | Dataset to query. Cubes and their contracts: Each cube lists its selectable fields, then: filter-only (usable only in where), alsoSelect (name←id: group by the id, pass the name in alsoSelect), groupable (the only fields accepted in by), max limit (the most rows one call returns), and order by index… |
| after | object | Last row from previous page for keyset pagination. Must include values for all orderBy dims. |
| limit | integer | Max rows to return. |
| where | any | WHERE filter. |
| fields * | array | Columns to SELECT. |
List pitch workspace reports for the organization. Returns all non-deleted pitches with their status and metadata.
No parameters.
{
"name": "list_pitches",
"description": "List pitch workspace reports for the organization. Returns all non-deleted pitches with their status and metadata.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"pitches"
],
"properties": {
"pitches": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"company_name",
"company_url",
"company_description",
"status",
"created_at",
"country",
"language",
"type"
],
"properties": {
"id": {
"type": "string"
},
"type": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string"
},
"country": {
"type": [
"string",
"null"
]
},
"language": {
"type": [
"string",
"null"
]
},
"created_at": {
"type": "string"
},
"company_url": {
"type": "string"
},
"company_name": {
"type": "string"
},
"company_description": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "List pitches",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}Get a pitch report by ID including competitors, prompts, attributes, top citing sources, and aggregate metrics (brand mentions, sentiment, response rate).
| Parameter | Type | Description |
|---|---|---|
| pitch_id * | string |
{
"name": "get_pitch",
"description": "Get a pitch report by ID including competitors, prompts, attributes, top citing sources, and aggregate metrics (brand mentions, sentiment, response rate).",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"pitch_id"
],
"properties": {
"pitch_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"pitch",
"competitors",
"prompts",
"attributes",
"sources",
"metrics"
],
"properties": {
"pitch": {
"type": "object",
"required": [
"id",
"company_name",
"company_url",
"company_description",
"status",
"created_at",
"country",
"language",
"type"
],
"properties": {
"id": {
"type": "string"
},
"type": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string"
},
"country": {
"type": [
"string",
"null"
]
},
"language": {
"type": [
"string",
"null"
]
},
"created_at": {
"type": "string"
},
"company_url": {
"type": "string"
},
"company_name": {
"type": "string"
},
"company_description": {
"type": "string"
}
},
"additionalProperties": false
},
"metrics": {
"type": "object",
"required": [
"total_responses",
"brand_mentions",
"sentiment_score",
"response_rate"
],
"properties": {
"response_rate": {
"type": "number"
},
"brand_mentions": {
"type": "number"
},
"sentiment_score": {
"type": "number"
},
"total_responses": {
"type": "number"
}
},
"additionalProperties": false
},
"prompts": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"prompt",
"type"
],
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string"
},
"prompt": {
"type": "string"
}
},
"additionalProperties": false
}
},
"sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"domain",
"mentions"
],
"properties": {
"domain": {
"type": "string"
},
"mentions": {
"type": "number"
}
},
"additionalProperties": false
}
},
"attributes": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"attribute_name",
"attribute_type",
"applies_to",
"count"
],
"properties": {
"id": {
"type": "string"
},
"count": {
"type": "number"
},
"applies_to": {
"type": "string"
},
"attribute_name": {
"type": "string"
},
"attribute_type": {
"type": "string"
}
},
"additionalProperties": false
}
},
"competitors": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"url",
"mentions",
"sentiment"
],
"properties": {
"id": {
"type": "string"
},
"url": {
"type": "string"
},
"name": {
"type": "string"
},
"mentions": {
"type": "number"
},
"sentiment": {
"type": "number"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get pitch",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}List top cited sources (root domains) for a website with citation, mention, brand-mention, and impression metrics. Each row is classified as owned / competitor / partner / third_party. Supports filters (date range, models, prompts, competitors, locations, personas), source_tags (tag IDs from source_tags__list, owned, competitor, other, untagged), sort, and pagination via page_num / page_size.
| Parameter | Type | Description |
|---|---|---|
| search | ["string","null"] | |
| filters * | object | |
| page_num | integer | |
| mentioned | string | one of ["yes","no"] |
| page_size | integer | |
| sort_field | string | one of ["citation_percentage","mention_percentage","competitor_mention_percentage","brand_mention_percentage","estimated_impressions","total_mentions","domain_count","mentions_count","root_domain","response_… |
| website_id * | string | |
| source_tags | array | Source tags to filter by, as an array: tag IDs from source_tags__list (built-in tags such as Media or PR Wire, and custom tags), "owned", "competitor", "other" (sources the Tags column badges Other) or "untagged" (sources with no tag). Omit for all sources. |
| sort_direction | string |
List YouTube channels cited in AI answers for a website, ordered by citations (unknown channel last). Includes channel citation shares, category and video-length breakdowns, and metadata availability. Totals and breakdowns cover the full filtered result, independent of pagination. Use get_youtube_videos with channel_key to list a creator's videos. Reads saved metadata; pending or missing details remain null.
| Parameter | Type | Description |
|---|---|---|
| filters * | object | |
| page_num | integer | Zero-based page number. |
| page_size | integer | |
| website_id * | string |
{
"name": "get_youtube_creators",
"description": "List YouTube channels cited in AI answers for a website, ordered by citations (unknown channel last). Includes channel citation shares, category and video-length breakdowns, and metadata availability. Totals and breakdowns cover the full filtered result, independent of pagination. Use get_youtube_videos with channel_key to list a creator's videos. Reads saved metadata; pending or missing details remain null.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"filters"
],
"properties": {
"filters": {
"type": "object",
"required": [
"start_date"
],
"properties": {
"models": {
"type": "array",
"items": {
"enum": [
"chatgpt",
"perplexity",
"gemini",
"google_ai_overview",
"copilot",
"claude",
"ai_mode",
"grok",
"deepseek",
"meta_ai",
"mistral"
],
"type": "string"
},
"description": "AI models to include, as an array even for one model — e.g. [\"chatgpt\", \"perplexity\"]. Omit to include all models."
},
"end_date": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
"description": "Last day, YYYY-MM-DD, inclusive (UTC). Defaults to today."
},
"prompt_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Prompt UUIDs to filter to, as an array even for one id. Omit for all prompts."
},
"start_date": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
"description": "First day, YYYY-MM-DD, inclusive (UTC)."
},
"persona_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Persona UUIDs to filter to, as an array even for one id. Omit for all personas."
},
"prompt_tags": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Prompt tag UUIDs from get_prompt_tags."
},
"prompt_type": {
"enum": [
"branded",
"non_branded"
],
"type": "string",
"description": "Filter prompts by type: \"branded\" (mentions the brand) or \"non_branded\". Omit for both."
},
"schedule_id": {
"anyOf": [
{
"enum": [
"default",
"manual"
],
"type": "string"
},
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
],
"description": "One schedule: \"default\" or a custom/archived schedule UUID. Omit for Default, which includes all pre-cutover history and ad hoc runs. The retired \"manual\" token is accepted as an alias of \"default\". Schedules cannot be combined."
},
"location_ids": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "string",
"const": "no-location"
}
]
},
"description": "Location UUIDs to filter to, as an array even for one id. The literal string \"no-location\" selects responses that ran without a location. Omit for all locations."
},
"prompt_status": {
"enum": [
"active",
"paused"
],
"type": "string",
"description": "Filter prompts by tracking status: \"active\" or \"paused\". Omit for both."
},
"variation_filter": {
"type": "array",
"items": {
"enum": [
"variation",
"prompt"
],
"type": "string"
},
"description": "Which prompt rows to include, as an array: \"prompt\" for base prompts, \"variation\" for generated variations, or both. Omit for both."
},
"target_identifiers": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "string",
"const": "no-identifier"
}
]
},
"description": "Target identifier strings to filter to, as an array even for one value. The literal string \"no-identifier\" selects responses with no target identifier. Omit for all."
},
"prompt_tags_operator": {
"enum": [
"is_any_of",
"has_all_of"
],
"type": "string",
"description": "How prompt_tags combine: \"is_any_of\" matches prompts with any listed tag, \"has_all_of\" only prompts carrying every listed tag."
}
},
"additionalProperties": false
},
"page_num": {
"type": "integer",
"default": 0,
"maximum": 1000000,
"minimum": 0,
"description": "Zero-based page number."
},
"page_size": {
"type": "integer",
"default": 30,
"maximum": 100,
"minimum": 1
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"creators",
"pagination",
"categories",
"length_buckets",
"totals"
],
"properties": {
"notice": {
"type": "string"
},
"totals": {
"type": "object",
"required": [
"citations",
"video_citations",
"non_video_citations",
"videos",
"channels",
"top_ten_channel_share_percent",
"median_duration_seconds",
"pending",
"missing"
],
"properties": {
"videos": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"missing": {
"type": "object",
"required": [
"videos",
"citations"
],
"properties": {
"videos": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"citations": {
"type": "number"
}
},
"additionalProperties": false
},
"pending": {
"type": "object",
"required": [
"videos",
"citations"
],
"properties": {
"videos": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"citations": {
"type": "number"
}
},
"additionalProperties": false
},
"channels": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"citations": {
"type": "number"
},
"video_citations": {
"type": "number"
},
"non_video_citations": {
"type": "number"
},
"median_duration_seconds": {
"type": [
"number",
"null"
]
},
"top_ten_channel_share_percent": {
"type": "number"
}
},
"additionalProperties": false
},
"creators": {
"type": "array",
"items": {
"type": "object",
"required": [
"channel_key",
"channel_id",
"name",
"handle",
"url",
"thumbnail_url",
"citations",
"share_percent",
"video_count",
"main_category_id",
"avg_duration_seconds"
],
"properties": {
"url": {
"type": [
"string",
"null"
]
},
"name": {
"type": [
"string",
"null"
]
},
"handle": {
"type": [
"string",
"null"
]
},
"citations": {
"type": "number"
},
"channel_id": {
"type": [
"string",
"null"
]
},
"channel_key": {
"type": "string",
"description": "Stable group key; use as channel_key in get_youtube_videos."
},
"video_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"share_percent": {
"type": "number"
},
"thumbnail_url": {
"type": [
"string",
"null"
]
},
"main_category_id": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
{
"type": "null"
}
]
},
"avg_duration_seconds": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
}
},
"categories": {
"type": "array",
"items": {
"type": "object",
"required": [
"category_id",
"citations",
"share_percent",
"videos"
],
"properties": {
"videos": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"citations": {
"type": "number"
},
"category_id": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
{
"type": "null"
}
]
},
"share_percent": {
"type": "number"
}
},
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"required": [
"page_num",
"page_size",
"total"
],
"properties": {
"total": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"page_num": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"page_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
}
},
"additionalProperties": false
},
"length_buckets": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"citations",
"share_percent",
"videos"
],
"properties": {
"id": {
"enum": [
"under-1",
"1-5",
"5-15",
"15-30",
"30-60",
"60-plus"
],
"type": "string"
},
"videos": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"citations": {
"type": "number"
},
"share_percent": {
"type": "number"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get youtube creators",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}List YouTube videos cited in AI answers for a website, ordered by citation count. Returns saved titles, channel details, categories, durations, publication dates, citation counts, distinct-response citation percentages and linked timestamps. Watch, Shorts and short-link variants of one video are combined. Filter by channel_key or video_id. Metadata may be pending or missing; no live YouTube fetch is performed.
| Parameter | Type | Description |
|---|---|---|
| filters * | object | |
| page_num | integer | Zero-based page number. |
| video_id | string | YouTube video ID; omit for all videos. |
| page_size | integer | |
| website_id * | string | |
| channel_key | string | Channel group key from get_youtube_creators; omit for all creators. |
{
"name": "get_youtube_videos",
"description": "List YouTube videos cited in AI answers for a website, ordered by citation count. Returns saved titles, channel details, categories, durations, publication dates, citation counts, distinct-response citation percentages and linked timestamps. Watch, Shorts and short-link variants of one video are combined. Filter by channel_key or video_id. Metadata may be pending or missing; no live YouTube fetch is performed.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"filters"
],
"properties": {
"filters": {
"type": "object",
"required": [
"start_date"
],
"properties": {
"models": {
"type": "array",
"items": {
"enum": [
"chatgpt",
"perplexity",
"gemini",
"google_ai_overview",
"copilot",
"claude",
"ai_mode",
"grok",
"deepseek",
"meta_ai",
"mistral"
],
"type": "string"
},
"description": "AI models to include, as an array even for one model — e.g. [\"chatgpt\", \"perplexity\"]. Omit to include all models."
},
"end_date": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
"description": "Last day, YYYY-MM-DD, inclusive (UTC). Defaults to today."
},
"prompt_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Prompt UUIDs to filter to, as an array even for one id. Omit for all prompts."
},
"start_date": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
"description": "First day, YYYY-MM-DD, inclusive (UTC)."
},
"persona_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Persona UUIDs to filter to, as an array even for one id. Omit for all personas."
},
"prompt_tags": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Prompt tag UUIDs from get_prompt_tags."
},
"prompt_type": {
"enum": [
"branded",
"non_branded"
],
"type": "string",
"description": "Filter prompts by type: \"branded\" (mentions the brand) or \"non_branded\". Omit for both."
},
"schedule_id": {
"anyOf": [
{
"enum": [
"default",
"manual"
],
"type": "string"
},
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
],
"description": "One schedule: \"default\" or a custom/archived schedule UUID. Omit for Default, which includes all pre-cutover history and ad hoc runs. The retired \"manual\" token is accepted as an alias of \"default\". Schedules cannot be combined."
},
"location_ids": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "string",
"const": "no-location"
}
]
},
"description": "Location UUIDs to filter to, as an array even for one id. The literal string \"no-location\" selects responses that ran without a location. Omit for all locations."
},
"prompt_status": {
"enum": [
"active",
"paused"
],
"type": "string",
"description": "Filter prompts by tracking status: \"active\" or \"paused\". Omit for both."
},
"variation_filter": {
"type": "array",
"items": {
"enum": [
"variation",
"prompt"
],
"type": "string"
},
"description": "Which prompt rows to include, as an array: \"prompt\" for base prompts, \"variation\" for generated variations, or both. Omit for both."
},
"target_identifiers": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "string",
"const": "no-identifier"
}
]
},
"description": "Target identifier strings to filter to, as an array even for one value. The literal string \"no-identifier\" selects responses with no target identifier. Omit for all."
},
"prompt_tags_operator": {
"enum": [
"is_any_of",
"has_all_of"
],
"type": "string",
"description": "How prompt_tags combine: \"is_any_of\" matches prompts with any listed tag, \"has_all_of\" only prompts carrying every listed tag."
}
},
"additionalProperties": false
},
"page_num": {
"type": "integer",
"default": 0,
"maximum": 1000000,
"minimum": 0,
"description": "Zero-based page number."
},
"video_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{11}$",
"description": "YouTube video ID; omit for all videos."
},
"page_size": {
"type": "integer",
"default": 30,
"maximum": 100,
"minimum": 1
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"channel_key": {
"type": "string",
"maxLength": 500,
"minLength": 1,
"description": "Channel group key from get_youtube_creators; omit for all creators."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"videos",
"pagination"
],
"properties": {
"notice": {
"type": "string"
},
"videos": {
"type": "array",
"items": {
"type": "object",
"required": [
"video_id",
"url",
"title",
"channel",
"category_id",
"duration_seconds",
"published_at",
"first_seen",
"citations",
"citation_percentage",
"details_status",
"moments"
],
"properties": {
"url": {
"type": "string"
},
"title": {
"type": [
"string",
"null"
]
},
"channel": {
"type": "object",
"required": [
"channel_key",
"channel_id",
"name",
"handle",
"url",
"thumbnail_url"
],
"properties": {
"url": {
"type": [
"string",
"null"
]
},
"name": {
"type": [
"string",
"null"
]
},
"handle": {
"type": [
"string",
"null"
]
},
"channel_id": {
"type": [
"string",
"null"
]
},
"channel_key": {
"type": "string",
"description": "Stable group key; use as channel_key in get_youtube_videos."
},
"thumbnail_url": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"moments": {
"type": "array",
"items": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"description": "Distinct linked timestamps in seconds, from the top 100 cited URL variants. This is a bounded list, not every timestamp or transcript."
},
"video_id": {
"type": "string"
},
"citations": {
"type": "number"
},
"first_seen": {
"type": "string"
},
"category_id": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
{
"type": "null"
}
]
},
"published_at": {
"type": [
"string",
"null"
]
},
"details_status": {
"enum": [
"found",
"pending",
"missing"
],
"type": "string"
},
"duration_seconds": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
{
"type": "null"
}
]
},
"citation_percentage": {
"type": "number"
}
},
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"required": [
"page_num",
"page_size",
"total"
],
"properties": {
"total": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"page_num": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"page_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get youtube videos",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}List TikTok handles cited in AI answers, ordered by citations with unattributed URLs last. Includes profiles, videos and photos across tiktok.com, www, m, vm and vt hosts. Handles come from cited URLs, not verified account identities; short links are not resolved. Citation shares and totals cover all filtered TikTok citations, including unattributed URLs, independent of pagination. Use get_tiktok_pages with channel_key to drill down. No scraping or live TikTok requests.
| Parameter | Type | Description |
|---|---|---|
| filters * | object | |
| page_num | integer | Zero-based page number. |
| page_size | integer | |
| website_id * | string |
{
"name": "get_tiktok_creators",
"description": "List TikTok handles cited in AI answers, ordered by citations with unattributed URLs last. Includes profiles, videos and photos across tiktok.com, www, m, vm and vt hosts. Handles come from cited URLs, not verified account identities; short links are not resolved. Citation shares and totals cover all filtered TikTok citations, including unattributed URLs, independent of pagination. Use get_tiktok_pages with channel_key to drill down. No scraping or live TikTok requests.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"filters"
],
"properties": {
"filters": {
"type": "object",
"required": [
"start_date"
],
"properties": {
"models": {
"type": "array",
"items": {
"enum": [
"chatgpt",
"perplexity",
"gemini",
"google_ai_overview",
"copilot",
"claude",
"ai_mode",
"grok",
"deepseek",
"meta_ai",
"mistral"
],
"type": "string"
},
"description": "AI models to include, as an array even for one model — e.g. [\"chatgpt\", \"perplexity\"]. Omit to include all models."
},
"end_date": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
"description": "Last day, YYYY-MM-DD, inclusive (UTC). Defaults to today."
},
"prompt_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Prompt UUIDs to filter to, as an array even for one id. Omit for all prompts."
},
"start_date": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
"description": "First day, YYYY-MM-DD, inclusive (UTC)."
},
"persona_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Persona UUIDs to filter to, as an array even for one id. Omit for all personas."
},
"prompt_tags": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Prompt tag UUIDs from get_prompt_tags."
},
"prompt_type": {
"enum": [
"branded",
"non_branded"
],
"type": "string",
"description": "Filter prompts by type: \"branded\" (mentions the brand) or \"non_branded\". Omit for both."
},
"schedule_id": {
"anyOf": [
{
"enum": [
"default",
"manual"
],
"type": "string"
},
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
],
"description": "One schedule: \"default\" or a custom/archived schedule UUID. Omit for Default, which includes all pre-cutover history and ad hoc runs. The retired \"manual\" token is accepted as an alias of \"default\". Schedules cannot be combined."
},
"location_ids": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "string",
"const": "no-location"
}
]
},
"description": "Location UUIDs to filter to, as an array even for one id. The literal string \"no-location\" selects responses that ran without a location. Omit for all locations."
},
"prompt_status": {
"enum": [
"active",
"paused"
],
"type": "string",
"description": "Filter prompts by tracking status: \"active\" or \"paused\". Omit for both."
},
"variation_filter": {
"type": "array",
"items": {
"enum": [
"variation",
"prompt"
],
"type": "string"
},
"description": "Which prompt rows to include, as an array: \"prompt\" for base prompts, \"variation\" for generated variations, or both. Omit for both."
},
"target_identifiers": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "string",
"const": "no-identifier"
}
]
},
"description": "Target identifier strings to filter to, as an array even for one value. The literal string \"no-identifier\" selects responses with no target identifier. Omit for all."
},
"prompt_tags_operator": {
"enum": [
"is_any_of",
"has_all_of"
],
"type": "string",
"description": "How prompt_tags combine: \"is_any_of\" matches prompts with any listed tag, \"has_all_of\" only prompts carrying every listed tag."
}
},
"additionalProperties": false
},
"page_num": {
"type": "integer",
"default": 0,
"maximum": 1000000,
"minimum": 0,
"description": "Zero-based page number."
},
"page_size": {
"type": "integer",
"default": 30,
"maximum": 100,
"minimum": 1
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"creators",
"pagination",
"totals"
],
"properties": {
"notice": {
"type": "string"
},
"totals": {
"type": "object",
"required": [
"citations",
"channels",
"unattributed_citations"
],
"properties": {
"channels": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Attributed handles, excluding the unattributed group."
},
"citations": {
"type": "number"
},
"unattributed_citations": {
"type": "number"
}
},
"additionalProperties": false
},
"creators": {
"type": "array",
"items": {
"type": "object",
"required": [
"channel_key",
"handle",
"url",
"citations",
"share_percent",
"page_count"
],
"properties": {
"url": {
"type": [
"string",
"null"
]
},
"handle": {
"type": [
"string",
"null"
]
},
"citations": {
"type": "number"
},
"page_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"channel_key": {
"type": "string",
"description": "URL-derived handle group key; use with get_tiktok_pages. The unattributed group has key unattributed."
},
"share_percent": {
"type": "number"
}
},
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"required": [
"page_num",
"page_size",
"total"
],
"properties": {
"total": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"page_num": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"page_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get tiktok creators",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}List TikTok URLs cited in AI answers, ordered by citations. Includes profile, video, photo and unattributed URLs. Filter by channel_key from get_tiktok_creators. Each page's share_percent and totals use all filtered TikTok citations, including unattributed URLs, even when drilling into one channel or paginating. These are AI-answer citation counts, not TikTok views or engagement. No scraping or live TikTok requests.
| Parameter | Type | Description |
|---|---|---|
| filters * | object | |
| page_num | integer | Zero-based page number. |
| page_size | integer | |
| website_id * | string | |
| channel_key | string | Group key from get_tiktok_creators, including unattributed; omit for all cited pages. |
{
"name": "get_tiktok_pages",
"description": "List TikTok URLs cited in AI answers, ordered by citations. Includes profile, video, photo and unattributed URLs. Filter by channel_key from get_tiktok_creators. Each page's share_percent and totals use all filtered TikTok citations, including unattributed URLs, even when drilling into one channel or paginating. These are AI-answer citation counts, not TikTok views or engagement. No scraping or live TikTok requests.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"filters"
],
"properties": {
"filters": {
"type": "object",
"required": [
"start_date"
],
"properties": {
"models": {
"type": "array",
"items": {
"enum": [
"chatgpt",
"perplexity",
"gemini",
"google_ai_overview",
"copilot",
"claude",
"ai_mode",
"grok",
"deepseek",
"meta_ai",
"mistral"
],
"type": "string"
},
"description": "AI models to include, as an array even for one model — e.g. [\"chatgpt\", \"perplexity\"]. Omit to include all models."
},
"end_date": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
"description": "Last day, YYYY-MM-DD, inclusive (UTC). Defaults to today."
},
"prompt_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Prompt UUIDs to filter to, as an array even for one id. Omit for all prompts."
},
"start_date": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
"description": "First day, YYYY-MM-DD, inclusive (UTC)."
},
"persona_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Persona UUIDs to filter to, as an array even for one id. Omit for all personas."
},
"prompt_tags": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Prompt tag UUIDs from get_prompt_tags."
},
"prompt_type": {
"enum": [
"branded",
"non_branded"
],
"type": "string",
"description": "Filter prompts by type: \"branded\" (mentions the brand) or \"non_branded\". Omit for both."
},
"schedule_id": {
"anyOf": [
{
"enum": [
"default",
"manual"
],
"type": "string"
},
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
],
"description": "One schedule: \"default\" or a custom/archived schedule UUID. Omit for Default, which includes all pre-cutover history and ad hoc runs. The retired \"manual\" token is accepted as an alias of \"default\". Schedules cannot be combined."
},
"location_ids": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "string",
"const": "no-location"
}
]
},
"description": "Location UUIDs to filter to, as an array even for one id. The literal string \"no-location\" selects responses that ran without a location. Omit for all locations."
},
"prompt_status": {
"enum": [
"active",
"paused"
],
"type": "string",
"description": "Filter prompts by tracking status: \"active\" or \"paused\". Omit for both."
},
"variation_filter": {
"type": "array",
"items": {
"enum": [
"variation",
"prompt"
],
"type": "string"
},
"description": "Which prompt rows to include, as an array: \"prompt\" for base prompts, \"variation\" for generated variations, or both. Omit for both."
},
"target_identifiers": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "string",
"const": "no-identifier"
}
]
},
"description": "Target identifier strings to filter to, as an array even for one value. The literal string \"no-identifier\" selects responses with no target identifier. Omit for all."
},
"prompt_tags_operator": {
"enum": [
"is_any_of",
"has_all_of"
],
"type": "string",
"description": "How prompt_tags combine: \"is_any_of\" matches prompts with any listed tag, \"has_all_of\" only prompts carrying every listed tag."
}
},
"additionalProperties": false
},
"page_num": {
"type": "integer",
"default": 0,
"maximum": 1000000,
"minimum": 0,
"description": "Zero-based page number."
},
"page_size": {
"type": "integer",
"default": 30,
"maximum": 100,
"minimum": 1
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"channel_key": {
"type": "string",
"maxLength": 500,
"minLength": 1,
"description": "Group key from get_tiktok_creators, including unattributed; omit for all cited pages."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"pages",
"pagination",
"totals"
],
"properties": {
"pages": {
"type": "array",
"items": {
"type": "object",
"required": [
"url",
"channel",
"citations",
"share_percent"
],
"properties": {
"url": {
"type": "string"
},
"channel": {
"type": "object",
"required": [
"channel_key",
"handle",
"url"
],
"properties": {
"url": {
"type": [
"string",
"null"
]
},
"handle": {
"type": [
"string",
"null"
]
},
"channel_key": {
"type": "string",
"description": "URL-derived handle group key; use with get_tiktok_pages. The unattributed group has key unattributed."
}
},
"additionalProperties": false
},
"citations": {
"type": "number"
},
"share_percent": {
"type": "number"
}
},
"additionalProperties": false
}
},
"notice": {
"type": "string"
},
"totals": {
"type": "object",
"required": [
"citations",
"channels",
"unattributed_citations"
],
"properties": {
"channels": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Attributed handles, excluding the unattributed group."
},
"citations": {
"type": "number"
},
"unattributed_citations": {
"type": "number"
}
},
"additionalProperties": false
},
"pagination": {
"type": "object",
"required": [
"page_num",
"page_size",
"total"
],
"properties": {
"total": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"page_num": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"page_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get tiktok pages",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}List individual cited URLs (pages) for a website with citation, mention, and impression metrics plus a per-URL daily sparkline. Each row is classified as owned / competitor / partner / third_party. Companion to get_sources (root-domain-level). Supports filters (date range, models, prompts, competitors, locations, personas), source_tags (tag IDs from source_tags__list, owned, competitor, other, untagged), search, sort, and pagination.
| Parameter | Type | Description |
|---|---|---|
| search | ["string","null"] | |
| filters * | object | |
| page_num | integer | |
| mentioned | string | one of ["yes","no"] |
| page_size | integer | |
| sort_field | string | one of ["citation_percentage","estimated_impressions","total_mentions","mentions_count","normalized_url","competitor_ids","first_seen"] |
| website_id * | string | |
| source_tags | array | Source tags to filter by, as an array: tag IDs from source_tags__list (built-in tags such as Media or PR Wire, and custom tags), "owned", "competitor", "other" (sources the Tags column badges Other) or "untagged" (sources with no tag). Omit for all sources. |
| sort_direction | string |
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.
| Parameter | Type | Description |
|---|---|---|
| positive | boolean | |
| website_id * | string |
{
"name": "get_attributes",
"description": "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.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id"
],
"properties": {
"positive": {
"type": "boolean"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"attributes"
],
"properties": {
"attributes": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"positive"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"positive": {
"type": "boolean"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get attributes",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}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.
| Parameter | Type | Description |
|---|---|---|
| filters * | object | |
| positive | boolean | |
| website_id * | string |
{
"name": "get_attribute_metrics",
"description": "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.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"filters"
],
"properties": {
"filters": {
"type": "object",
"required": [
"start_date"
],
"properties": {
"models": {
"type": "array",
"items": {
"enum": [
"chatgpt",
"perplexity",
"gemini",
"google_ai_overview",
"copilot",
"claude",
"ai_mode",
"grok",
"deepseek",
"meta_ai",
"mistral"
],
"type": "string"
},
"description": "AI models to include, as an array even for one model — e.g. [\"chatgpt\", \"perplexity\"]. Omit to include all models."
},
"end_date": {
"type": "string",
"description": "End of the date range, inclusive. Date-only values include the UTC day through 23:59:59.999; timestamps keep their exact instant. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"prompt_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Prompt UUIDs to filter to, as an array even for one id. Omit for all prompts."
},
"start_date": {
"type": "string",
"description": "Start of the date range. Required. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"persona_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Persona UUIDs to filter to, as an array even for one id. Omit for all personas."
},
"prompt_tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Prompt tag IDs to filter prompts by, as an array (list tags with get_prompt_tags). Omit for all tags."
},
"prompt_type": {
"enum": [
"branded",
"non_branded"
],
"type": "string",
"description": "Filter prompts by type: \"branded\" (mentions the brand) or \"non_branded\". Omit for both."
},
"schedule_id": {
"anyOf": [
{
"enum": [
"default",
"manual"
],
"type": "string"
},
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
],
"description": "One schedule: \"default\" or a custom/archived schedule UUID. Omit for Default, which includes all pre-cutover history and ad hoc runs. The retired \"manual\" token is accepted as an alias of \"default\". Schedules cannot be combined."
},
"location_ids": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "string",
"const": "no-location"
}
]
},
"description": "Location UUIDs to filter to, as an array even for one id. The literal string \"no-location\" selects responses that ran without a location. Omit for all locations."
},
"prompt_status": {
"enum": [
"active",
"paused"
],
"type": "string",
"description": "Filter prompts by tracking status: \"active\" or \"paused\". Omit for both."
},
"variation_filter": {
"type": "array",
"items": {
"enum": [
"variation",
"prompt"
],
"type": "string"
},
"description": "Which prompt rows to include, as an array: \"prompt\" for base prompts, \"variation\" for generated variations, or both. Omit for both."
},
"target_identifiers": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "string",
"const": "no-identifier"
}
]
},
"description": "Target identifier strings to filter to, as an array even for one value. The literal string \"no-identifier\" selects responses with no target identifier. Omit for all."
},
"prompt_tags_operator": {
"enum": [
"is_any_of",
"has_all_of"
],
"type": "string",
"description": "How prompt_tags combine: \"is_any_of\" matches prompts with any listed tag, \"has_all_of\" only prompts carrying every listed tag."
}
},
"additionalProperties": false
},
"positive": {
"type": "boolean"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"attribute_id",
"attribute_name",
"positive",
"response_count",
"total_responses",
"percentage"
],
"properties": {
"positive": {
"type": "boolean"
},
"percentage": {
"type": "number"
},
"attribute_id": {
"type": "string"
},
"attribute_name": {
"type": "string"
},
"response_count": {
"type": "number"
},
"total_responses": {
"type": "number"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get attribute metrics",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}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.
| Parameter | Type | Description |
|---|---|---|
| filters * | object | |
| positive | boolean | |
| website_id * | string |
{
"name": "get_competitor_attribute_metrics",
"description": "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.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"filters"
],
"properties": {
"filters": {
"type": "object",
"required": [
"start_date"
],
"properties": {
"models": {
"type": "array",
"items": {
"enum": [
"chatgpt",
"perplexity",
"gemini",
"google_ai_overview",
"copilot",
"claude",
"ai_mode",
"grok",
"deepseek",
"meta_ai",
"mistral"
],
"type": "string"
},
"description": "AI models to include, as an array even for one model — e.g. [\"chatgpt\", \"perplexity\"]. Omit to include all models."
},
"end_date": {
"type": "string",
"description": "End of the date range, inclusive. Date-only values include the UTC day through 23:59:59.999; timestamps keep their exact instant. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"prompt_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Prompt UUIDs to filter to, as an array even for one id. Omit for all prompts."
},
"start_date": {
"type": "string",
"description": "Start of the date range. Required. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"persona_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Persona UUIDs to filter to, as an array even for one id. Omit for all personas."
},
"prompt_tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Prompt tag IDs to filter prompts by, as an array (list tags with get_prompt_tags). Omit for all tags."
},
"prompt_type": {
"enum": [
"branded",
"non_branded"
],
"type": "string",
"description": "Filter prompts by type: \"branded\" (mentions the brand) or \"non_branded\". Omit for both."
},
"schedule_id": {
"anyOf": [
{
"enum": [
"default",
"manual"
],
"type": "string"
},
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
],
"description": "One schedule: \"default\" or a custom/archived schedule UUID. Omit for Default, which includes all pre-cutover history and ad hoc runs. The retired \"manual\" token is accepted as an alias of \"default\". Schedules cannot be combined."
},
"location_ids": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "string",
"const": "no-location"
}
]
},
"description": "Location UUIDs to filter to, as an array even for one id. The literal string \"no-location\" selects responses that ran without a location. Omit for all locations."
},
"prompt_status": {
"enum": [
"active",
"paused"
],
"type": "string",
"description": "Filter prompts by tracking status: \"active\" or \"paused\". Omit for both."
},
"competitor_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Competitor UUIDs to filter to, as an array even for one id. Omit for all competitors."
},
"variation_filter": {
"type": "array",
"items": {
"enum": [
"variation",
"prompt"
],
"type": "string"
},
"description": "Which prompt rows to include, as an array: \"prompt\" for base prompts, \"variation\" for generated variations, or both. Omit for both."
},
"target_identifiers": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "string",
"const": "no-identifier"
}
]
},
"description": "Target identifier strings to filter to, as an array even for one value. The literal string \"no-identifier\" selects responses with no target identifier. Omit for all."
},
"prompt_tags_operator": {
"enum": [
"is_any_of",
"has_all_of"
],
"type": "string",
"description": "How prompt_tags combine: \"is_any_of\" matches prompts with any listed tag, \"has_all_of\" only prompts carrying every listed tag."
}
}
},
"positive": {
"type": "boolean"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"competitor_id",
"competitor_name",
"attribute_id",
"attribute_name",
"positive",
"response_count",
"total_responses",
"percentage"
],
"properties": {
"positive": {
"type": "boolean"
},
"percentage": {
"type": "number"
},
"attribute_id": {
"type": "string"
},
"competitor_id": {
"type": "string"
},
"attribute_name": {
"type": "string"
},
"response_count": {
"type": "number"
},
"competitor_name": {
"type": "string"
},
"total_responses": {
"type": "number"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get competitor attribute metrics",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}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.
| Parameter | Type | Description |
|---|---|---|
| filters * | object | |
| positive | boolean | |
| website_id * | string | |
| attribute_id * | string |
{
"name": "get_attribute_time_series",
"description": "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.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"filters",
"attribute_id"
],
"properties": {
"filters": {
"type": "object",
"required": [
"start_date"
],
"properties": {
"models": {
"type": "array",
"items": {
"enum": [
"chatgpt",
"perplexity",
"gemini",
"google_ai_overview",
"copilot",
"claude",
"ai_mode",
"grok",
"deepseek",
"meta_ai",
"mistral"
],
"type": "string"
},
"description": "AI models to include, as an array even for one model — e.g. [\"chatgpt\", \"perplexity\"]. Omit to include all models."
},
"end_date": {
"type": "string",
"description": "End of the date range, inclusive. Date-only values include the UTC day through 23:59:59.999; timestamps keep their exact instant. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"prompt_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Prompt UUIDs to filter to, as an array even for one id. Omit for all prompts."
},
"start_date": {
"type": "string",
"description": "Start of the date range. Required. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"persona_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Persona UUIDs to filter to, as an array even for one id. Omit for all personas."
},
"prompt_tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Prompt tag IDs to filter prompts by, as an array (list tags with get_prompt_tags). Omit for all tags."
},
"prompt_type": {
"enum": [
"branded",
"non_branded"
],
"type": "string",
"description": "Filter prompts by type: \"branded\" (mentions the brand) or \"non_branded\". Omit for both."
},
"schedule_id": {
"anyOf": [
{
"enum": [
"default",
"manual"
],
"type": "string"
},
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
],
"description": "One schedule: \"default\" or a custom/archived schedule UUID. Omit for Default, which includes all pre-cutover history and ad hoc runs. The retired \"manual\" token is accepted as an alias of \"default\". Schedules cannot be combined."
},
"location_ids": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "string",
"const": "no-location"
}
]
},
"description": "Location UUIDs to filter to, as an array even for one id. The literal string \"no-location\" selects responses that ran without a location. Omit for all locations."
},
"prompt_status": {
"enum": [
"active",
"paused"
],
"type": "string",
"description": "Filter prompts by tracking status: \"active\" or \"paused\". Omit for both."
},
"competitor_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Competitor UUIDs to filter to, as an array even for one id. Omit for all competitors."
},
"variation_filter": {
"type": "array",
"items": {
"enum": [
"variation",
"prompt"
],
"type": "string"
},
"description": "Which prompt rows to include, as an array: \"prompt\" for base prompts, \"variation\" for generated variations, or both. Omit for both."
},
"target_identifiers": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "string",
"const": "no-identifier"
}
]
},
"description": "Target identifier strings to filter to, as an array even for one value. The literal string \"no-identifier\" selects responses with no target identifier. Omit for all."
},
"prompt_tags_operator": {
"enum": [
"is_any_of",
"has_all_of"
],
"type": "string",
"description": "How prompt_tags combine: \"is_any_of\" matches prompts with any listed tag, \"has_all_of\" only prompts carrying every listed tag."
}
}
},
"positive": {
"type": "boolean"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"attribute_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"date",
"brand_count",
"brand_total",
"brand_percentage",
"competitor_count",
"competitor_total",
"competitor_percentage"
],
"properties": {
"date": {
"type": "string"
},
"brand_count": {
"type": "number"
},
"brand_total": {
"type": "number"
},
"brand_percentage": {
"type": "number"
},
"competitor_count": {
"type": "number"
},
"competitor_total": {
"type": "number"
},
"competitor_percentage": {
"type": "number"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get attribute time series",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}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.
| Parameter | Type | Description |
|---|---|---|
| sort | string | "intensity" (default): strongest first, unscored last, then newest. "recent": newest first. |
| filters * | object | |
| page_num | integer | Zero-indexed page number. Defaults to 0. |
| positive | boolean | true for favorable observations only, false for critical ones only. Omit for both directions. |
| page_size | integer | Rows per page, 1 to 100. Defaults to 40. |
| entity_ids | array | Entity UUIDs to filter to, as an array even for one id: the website_id for the brand itself, competitor ids from get_competitors for competitors. Omit for every entity. |
Look up a user by email address, scoped to the caller's organization. Returns 404 when the email does not belong to a member of the organization or of one of its websites.
| Parameter | Type | Description |
|---|---|---|
| email * | string |
{
"name": "get_user_by_email",
"description": "Look up a user by email address, scoped to the caller's organization. Returns 404 when the email does not belong to a member of the organization or of one of its websites.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"email"
],
"properties": {
"email": {
"type": "string",
"format": "email",
"pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
"minLength": 1
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"user"
],
"properties": {
"user": {
"type": "object",
"required": [
"user_id",
"email",
"first_name",
"last_name",
"access_type"
],
"properties": {
"email": {
"type": "string"
},
"user_id": {
"type": "string"
},
"last_name": {
"type": [
"string",
"null"
]
},
"first_name": {
"type": [
"string",
"null"
]
},
"access_type": {
"enum": [
"organization",
"website"
],
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get user by email",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}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. List Oracle accuracy findings for a website: places where an AI response contradicted a verified brand fact (type 'inaccuracy' or 'kb_issue', with quote, claim, and reason) or where two knowledge-base facts conflict ('kb_duplicate' / 'kb_contradiction', pairing fact_text with related_fact_text). Findings from every status are included by default (pending, acknowledged, ignored, ...), each row carrying its status — pass the status filter for pending items only. Filters (run_id, fact_id, lineage_id, response_id, prompt_id, source_url, type, kind, severity, status) AND-compose; source_url matches evidence URLs exactly after normalization (protocol and trailing slash ignored). 'total' is the pre-limit count. 'latest_run' is the newest scan of any kind and is null only when the website has never been scanned, so latest_run plus empty findings means it scanned clean, while latest_run null means never scanned, not clean. Archived findings from before the current scanner ARE included: their run carries 'is_imported': true and keeps its original started_at, so an import can be the newest run — say the history is archived rather than calling it a current scan. 'has_imported_history' is true when any such archived run exists, and every finding row carries 'run_is_imported' so archival and current rows stay distinguishable in one list. Returns status 'no_access' if the brand does not have Oracle v2; that response carries the status alone, with no counts or findings.
| Parameter | Type | Description |
|---|---|---|
| kind | string | one of ["false","outdated","overclaim","underclaim","misattributed"] |
| type | string | one of ["inaccuracy","kb_issue","kb_duplicate","kb_contradiction","model_disagreement"] |
| limit | integer | |
| model | string | Filter to one AI model by product name (ChatGPT, Claude, Gemini, Perplexity, Copilot, Muse Spark); raw identifiers also match exactly |
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.
| Parameter | Type | Description |
|---|---|---|
| finding_id * | string | |
| website_id * | string |
{
"name": "get_oracle_finding",
"description": "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.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"finding_id"
],
"properties": {
"finding_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"status",
"finding"
],
"properties": {
"status": {
"enum": [
"no_access",
"ready"
],
"type": "string"
},
"finding": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"run_id",
"lineage_id",
"fact_id",
"fact_text",
"related_fact_id",
"related_fact_text",
"prompt_id",
"prompt_text",
"model",
"response_id",
"quote",
"claim",
"reason",
"type",
"kind",
"severity",
"status",
"created_at",
"evidence_urls",
"run",
"response",
"evidence",
"lineage"
],
"properties": {
"id": {
"type": "string"
},
"run": {
"type": "object",
"required": [
"id",
"status",
"started_at",
"finished_at",
"is_imported"
],
"properties": {
"id": {
"type": "string"
},
"status": {
"type": "string"
},
"started_at": {
"type": "string"
},
"finished_at": {
"type": [
"string",
"null"
]
},
"is_imported": {
"type": "boolean"
}
},
"additionalProperties": false
},
"kind": {
"type": [
"string",
"null"
]
},
"type": {
"type": "string"
},
"claim": {
"type": [
"string",
"null"
]
},
"model": {
"type": [
"string",
"null"
]
},
"quote": {
"type": [
"string",
"null"
]
},
"reason": {
"type": [
"string",
"null"
]
},
"run_id": {
"type": "string"
},
"status": {
"type": "string"
},
"fact_id": {
"type": "string"
},
"lineage": {
"type": "array",
"items": {
"type": "object",
"required": [
"run_id",
"run_started_at",
"finding_id",
"severity",
"status"
],
"properties": {
"run_id": {
"type": "string"
},
"status": {
"type": "string"
},
"severity": {
"type": "string"
},
"finding_id": {
"type": "string"
},
"run_started_at": {
"type": "string"
}
},
"additionalProperties": false
}
},
"evidence": {
"type": "array",
"items": {
"type": "object",
"required": [
"url",
"quote",
"snippet",
"snapshot_id",
"scrape_hash",
"source_id",
"created_at"
],
"properties": {
"url": {
"type": "string"
},
"quote": {
"type": [
"string",
"null"
]
},
"snippet": {
"type": [
"string",
"null"
]
},
"source_id": {
"type": [
"string",
"null"
]
},
"created_at": {
"type": "string"
},
"scrape_hash": {
"type": [
"string",
"null"
]
},
"snapshot_id": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
},
"response": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"model",
"excerpt"
],
"properties": {
"id": {
"type": "string"
},
"model": {
"type": [
"string",
"null"
]
},
"excerpt": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"severity": {
"type": "string"
},
"fact_text": {
"type": [
"string",
"null"
]
},
"grounding": {
"anyOf": [
{
"type": "object",
"required": [
"kind",
"statement",
"confirmationId",
"sourceFindingId",
"facts"
],
"properties": {
"kind": {
"type": "string",
"const": "confirmed_statement"
},
"facts": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"text"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"text": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
},
"minItems": 1
},
"statement": {
"type": "string",
"minLength": 1
},
"confirmationId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"sourceFindingId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "When present, the complete team-confirmed statement and ALL supporting facts are the evidence. The legacy fact ID and text are only a compatibility anchor, not independent proof."
},
"prompt_id": {
"type": [
"string",
"null"
]
},
"created_at": {
"type": "string"
},
"lineage_id": {
"type": "string"
},
"prompt_text": {
"type": [
"string",
"null"
]
},
"response_id": {
"type": [
"string",
"null"
]
},
"evidence_urls": {
"type": "array",
"items": {
"type": "string"
}
},
"related_fact_id": {
"type": [
"string",
"null"
]
},
"related_fact_text": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get oracle finding",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}List the organization's API key metadata, including creator and creation date, oldest first. Includes revoked keys so polling can detect keys revoked between checks. Never returns secrets or hashes. Requires a global API key or an organization admin's MCP connection. For polling, keep since/until fixed while paging, overlap successive windows and deduplicate by id. This is an inventory, not a durable event log; deleted creator accounts remove their keys.
| Parameter | Type | Description |
|---|---|---|
| since | string | Include keys created at or after this ISO 8601 timestamp. |
| until | string | Include keys created at or before this ISO 8601 timestamp. Keep fixed while paging. |
| page_num | integer | |
| page_size | integer |
{
"name": "list_api_keys",
"description": "List the organization's API key metadata, including creator and creation date, oldest first. Includes revoked keys so polling can detect keys revoked between checks. Never returns secrets or hashes. Requires a global API key or an organization admin's MCP connection. For polling, keep since/until fixed while paging, overlap successive windows and deduplicate by id. This is an inventory, not a durable event log; deleted creator accounts remove their keys.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"since": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "Include keys created at or after this ISO 8601 timestamp."
},
"until": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "Include keys created at or before this ISO 8601 timestamp. Keep fixed while paging."
},
"page_num": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0
},
"page_size": {
"type": "integer",
"default": 100,
"maximum": 100,
"minimum": 1
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"api_keys",
"pagination"
],
"properties": {
"api_keys": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"key_prefix",
"created_at",
"created_by",
"is_global",
"website_ids",
"is_revoked"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"is_global": {
"type": "boolean"
},
"created_at": {
"type": "string"
},
"created_by": {
"type": "object",
"required": [
"id",
"name",
"email"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": [
"string",
"null"
]
},
"email": {
"type": "string"
}
},
"additionalProperties": false
},
"is_revoked": {
"type": "boolean"
},
"key_prefix": {
"type": "string"
},
"website_ids": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"required": [
"page_num",
"page_size",
"has_more"
],
"properties": {
"has_more": {
"type": "boolean"
},
"page_num": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"page_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"title": "List api keys",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}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).
| Parameter | Type | Description |
|---|---|---|
| facts * | array | |
| decisions | array | |
| website_id * | string | |
| match_token | string | |
| save_submitted | boolean |
{
"name": "add_brand_facts",
"description": "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).",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"facts"
],
"properties": {
"facts": {
"type": "array",
"items": {
"type": "object",
"required": [
"text"
],
"properties": {
"text": {
"type": "string",
"maxLength": 2000,
"minLength": 1
},
"pillar_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"source_url": {
"type": "string",
"maxLength": 2048
}
},
"additionalProperties": false
}
},
"decisions": {
"type": "array",
"items": {
"type": "object",
"required": [
"claim_id",
"action"
],
"properties": {
"text": {
"type": "string",
"maxLength": 2000,
"minLength": 1
},
"action": {
"enum": [
"approve",
"delete"
],
"type": "string"
},
"claim_id": {
"type": "string"
}
},
"additionalProperties": false
}
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"match_token": {
"type": "string",
"maxLength": 200
},
"save_submitted": {
"type": "boolean"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"outcomes": {
"type": "array",
"items": {
"type": "object",
"required": [
"index",
"outcome",
"fact_id",
"pillar_id"
],
"properties": {
"index": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"fact_id": {
"type": [
"string",
"null"
]
},
"matches": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"text",
"status",
"source_type",
"source_url",
"first_party",
"pillar_id",
"pillar_name",
"created_at"
],
"properties": {
"id": {
"type": "string"
},
"text": {
"type": "string"
},
"status": {
"enum": [
"pending",
"approved"
],
"type": "string"
},
"pillar_id": {
"type": [
"string",
"null"
]
},
"created_at": {
"type": "string"
},
"source_url": {
"type": [
"string",
"null"
]
},
"first_party": {
"type": [
"boolean",
"null"
]
},
"pillar_name": {
"type": [
"string",
"null"
]
},
"source_type": {
"enum": [
"research",
"upload",
"content_hub"
],
"type": "string"
}
},
"additionalProperties": false
}
},
"outcome": {
"enum": [
"approved",
"pending",
"duplicate"
],
"type": "string"
},
"pillar_id": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
},
"resolved": {
"type": "object",
"required": [
"approved_fact_ids",
"pending_fact_ids",
"removed_fact_ids"
],
"properties": {
"pending_fact_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"removed_fact_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"approved_fact_ids": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"match_token": {
"type": "string"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Add brand facts",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": true
}
}Start tracking competitors on a website, 1 to 25 per call, under the same rules as the Competitors page. Each competitor needs a name and its website url, or no_website: true for a brand with no website of its own; identifiers and additional_urls are optional. Returns one result per competitor, in order: added, already_tracked (the website already tracks that url; nothing changes), or rejected with the reason (a url on the website's own domains, an invalid url, or the limit of 500 competitors per website). New AI responses count mentions of an added competitor right away. Past responses are reanalyzed only when someone runs the backfill on the Competitors page, which costs credits; this tool never starts it and costs no credits.
| Parameter | Type | Description |
|---|---|---|
| website_id * | string | |
| competitors * | array |
{
"name": "add_competitors",
"description": "Start tracking competitors on a website, 1 to 25 per call, under the same rules as the Competitors page. Each competitor needs a name and its website url, or no_website: true for a brand with no website of its own; identifiers and additional_urls are optional. Returns one result per competitor, in order: added, already_tracked (the website already tracks that url; nothing changes), or rejected with the reason (a url on the website's own domains, an invalid url, or the limit of 500 competitors per website). New AI responses count mentions of an added competitor right away. Past responses are reanalyzed only when someone runs the backfill on the Competitors page, which costs credits; this tool never starts it and costs no credits.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"competitors"
],
"properties": {
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"competitors": {
"type": "array",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"url": {
"type": "string",
"maxLength": 2048,
"minLength": 1,
"description": "The competitor's website, e.g. acme.com. Required unless no_website is true."
},
"name": {
"type": "string",
"maxLength": 255,
"minLength": 1
},
"no_website": {
"type": "boolean",
"const": true,
"description": "Pass true only for a brand that has no website of its own. Mentions still match on the name and identifiers."
},
"identifiers": {
"type": "array",
"items": {
"type": "string",
"maxLength": 500
},
"description": "Other names and aliases to count as a mention, beyond the name and domain."
},
"additional_urls": {
"type": "array",
"items": {
"type": "string",
"maxLength": 2048
},
"description": "Other domains the competitor owns, e.g. acme.co.uk."
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"status"
],
"properties": {
"name": {
"type": "string"
},
"reason": {
"type": "string"
},
"status": {
"enum": [
"added",
"already_tracked",
"rejected"
],
"type": "string"
},
"competitor_id": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Add competitors",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
}
}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.
| Parameter | Type | Description |
|---|---|---|
| body | string | |
| title | string | |
| sheet_id | any | |
| website_id * | string |
{
"name": "add_content",
"description": "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.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id"
],
"properties": {
"body": {
"type": "string",
"maxLength": 1000000
},
"title": {
"type": "string",
"maxLength": 200
},
"sheet_id": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "null"
}
]
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"title": {
"type": "string"
},
"sheet_id": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "null"
}
]
},
"content_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"version_number": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
{
"type": "null"
}
]
},
"unsafe_links_removed": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
}
},
"additionalProperties": false
},
"annotations": {
"title": "Add content",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
}
}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.
| Parameter | Type | Description |
|---|---|---|
| content_id * | string | |
| website_id * | string |
{
"name": "approve_brief",
"description": "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.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"content_id"
],
"properties": {
"content_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"status": {
"type": "string",
"const": "generating"
},
"content_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Approve brief",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}
}Create a brand kit from text the user provides: a name, guidance text per field (voice is the writing direction), voice settings and writing rules, all authored by the caller; nothing is generated. The kit starts as a draft; content generation uses it only once published, which publish: true does as version 1 (or update_brand_kit later). The website's first kit becomes its default. A name another kit uses is refused; a rule that contradicts an existing global rule is refused with the explanation and no kit is created. Kit rules need the writing rules feature on the plan. To change an existing kit, use update_brand_kit; to generate a kit from the website or uploaded documents, use the Brand Profile page.
| Parameter | Type | Description |
|---|---|---|
| name * | string | The kit's name, unique on the website. |
| rules | object | Writing rules for this kit. |
| publish | boolean | true publishes the new kit as version 1 so content generation can use it. Only when the user asked to publish. |
| guidance | array | Guidance text per field, one entry per field. |
| website_id * | string | |
| voice_settings | object | Each 1 (formality: casual, expression: reserved, humor: serious, stance: neutral, technicality: plain) to 5 (formal, expressive, playful, opinionated, technical), or "auto" to let the writer decide. Omitted dimensions keep their value. |
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.
| Parameter | Type | Description |
|---|---|---|
| url | string | Source page URL. Required for snipe, optimize, and slice modes. A URL without a protocol, such as example.com/article, is accepted. |
| mode * | string | draft: generate a brief and optionally an article from tracked prompts. snipe: draft an article using a competitor URL as input. optimize: improve an existing page for AI search. slice: turn one source URL into several articles. |
| title | string | Article title. Required for draft, snipe, and optimize modes. |
| rec_id | string | |
| kb_mode | string | one of ["auto","manual","none"] |
| rec_kind | string | one of ["on_page_topic","on_page_snipe"] |
| sheet_id | any | |
| prompt_ids | array | Existing tracked prompt UUIDs, up to 100. Required and nonempty for draft; omit for slice. Use IDs from the website's tracked prompt list; never invent them. |
Create a location for a website
| Parameter | Type | Description |
|---|---|---|
| country * | string | |
| location * | string | |
| prompt_ids | array | |
| website_id * | string |
{
"name": "create_location",
"description": "Create a location for a website",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"location",
"country"
],
"properties": {
"country": {
"type": "string",
"minLength": 1
},
"location": {
"type": "string",
"maxLength": 500,
"minLength": 1
},
"prompt_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"id": {
"type": "string"
},
"country": {
"type": "string"
},
"location": {
"type": "string"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Create location",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
}
}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.
| Parameter | Type | Description |
|---|---|---|
| name * | string | |
| website_id * | string | |
| description | string |
{
"name": "create_pillar",
"description": "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.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 120,
"minLength": 1
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": {
"type": "string",
"maxLength": 2000
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"pillar": {
"type": "object",
"required": [
"id",
"name",
"description",
"status"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"status": {
"enum": [
"researching",
"published",
"draft",
"archived"
],
"type": "string"
},
"description": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"created": {
"type": "boolean"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Create pillar",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
}
}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.
| Parameter | Type | Description |
|---|---|---|
| tag * | string | |
| website_id * | string |
{
"name": "create_prompt_tag",
"description": "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.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"tag"
],
"properties": {
"tag": {
"type": "string",
"maxLength": 255,
"minLength": 1
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"tag": {
"type": "string"
},
"tag_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"created": {
"type": "boolean"
},
"success": {
"type": "boolean",
"const": true
}
},
"additionalProperties": false
},
"annotations": {
"title": "Create prompt tag",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
}
}Create one or more prompts on a website
| Parameter | Type | Description |
|---|---|---|
| source | string | one of ["manual","ai_generated","bulk_upload"] |
| prompts * | array | |
| website_id * | string |
{
"name": "create_prompts",
"description": "Create one or more prompts on a website",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"prompts"
],
"properties": {
"source": {
"enum": [
"manual",
"ai_generated",
"bulk_upload"
],
"type": "string"
},
"prompts": {
"type": "array",
"items": {
"type": "object",
"required": [
"prompt"
],
"properties": {
"type": {
"anyOf": [
{
"enum": [
"discovery",
"high_intent"
],
"type": "string"
},
{
"type": "null"
}
]
},
"prompt": {
"type": "string",
"maxLength": 2000
},
"volume": {
"type": [
"string",
"null"
]
},
"tag_ids": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
{
"type": "null"
}
]
},
"topic_id": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "null"
}
]
},
"countries": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"is_paused": {
"type": "boolean"
},
"persona_ids": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
{
"type": "null"
}
]
},
"location_ids": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
{
"type": "null"
}
]
},
"primary_country": {
"type": [
"string",
"null"
]
},
"current_total_value": {
"anyOf": [
{
"type": "number",
"maximum": 9007199254740991,
"minimum": 0
},
{
"type": "null"
}
]
},
"current_monthly_searches": {
"anyOf": [
{
"type": "number",
"maximum": 2147483647,
"minimum": 0
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"count": {
"type": "number"
},
"success": {
"type": "boolean",
"const": true
},
"prompt_ids": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Create prompts",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
}
}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", the states "other" (the Other badge) and "untagged" (no tag), 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 / Other / No tag sources), never internal tokens, field keys, operator strings, or icon identifiers.
| Parameter | Type | Description |
|---|---|---|
| icon | any | |
| name * | string | |
| filters * | object | |
| website_id * | string | |
| olympus_layout | object |
Create a topic on a website (returns the existing topic when the name is already taken)
| Parameter | Type | Description |
|---|---|---|
| name * | string | |
| website_id * | string | |
| description | any |
{
"name": "create_topic",
"description": "Create a topic on a website (returns the existing topic when the name is already taken)",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 255,
"minLength": 1
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": {
"anyOf": [
{
"type": "string",
"maxLength": 2000
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"created": {
"type": "boolean"
},
"description": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "Create topic",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
}
}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.
| Parameter | Type | Description |
|---|---|---|
| fact_ids * | array | |
| website_id * | string |
{
"name": "delete_brand_facts",
"description": "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.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"fact_ids"
],
"properties": {
"fact_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"deleted_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"not_found_ids": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Delete brand facts",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": true
}
}Delete a content row. Destructive: physical row delete, no undo. Powers delete-and-retry. Bulk delete is out of scope.
| Parameter | Type | Description |
|---|---|---|
| content_id * | string | |
| website_id * | string |
{
"name": "delete_content",
"description": "Delete a content row. Destructive: physical row delete, no undo. Powers delete-and-retry. Bulk delete is out of scope.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"content_id"
],
"properties": {
"content_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"success": {
"type": "boolean",
"const": true
}
},
"additionalProperties": false
},
"annotations": {
"title": "Delete content",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": true
}
}Delete a location from a website
| Parameter | Type | Description |
|---|---|---|
| website_id * | string | |
| location_id * | string |
{
"name": "delete_location",
"description": "Delete a location from a website",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"location_id"
],
"properties": {
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"location_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"location": {
"type": "string"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Delete location",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": true
}
}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.
| Parameter | Type | Description |
|---|---|---|
| pillar_ids * | array | |
| website_id * | string |
{
"name": "delete_pillars",
"description": "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.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"pillar_ids"
],
"properties": {
"pillar_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"failed_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"not_found_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"deleted_pillars": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"fact_count"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"fact_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Delete pillars",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": true
}
}Delete a prompt (soft when responses exist, hard otherwise)
| Parameter | Type | Description |
|---|---|---|
| prompt_id * | string | |
| website_id * | string |
{
"name": "delete_prompt",
"description": "Delete a prompt (soft when responses exist, hard otherwise)",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"prompt_id",
"website_id"
],
"properties": {
"prompt_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"soft_deleted": {
"type": "boolean"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Delete prompt",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": true
}
}Delete a topic (soft delete; optionally also delete its prompts)
| Parameter | Type | Description |
|---|---|---|
| topic_id * | string | |
| website_id * | string | |
| delete_prompts | string | one of ["true","false"] |
{
"name": "delete_topic",
"description": "Delete a topic (soft delete; optionally also delete its prompts)",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"topic_id"
],
"properties": {
"topic_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"delete_prompts": {
"enum": [
"true",
"false"
],
"type": "string"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"name": {
"type": "string"
},
"success": {
"type": "boolean",
"const": true
},
"deleted_prompt_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
}
},
"additionalProperties": false
},
"annotations": {
"title": "Delete topic",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": true
}
}Draft a pitch email to the author of a cited page and save it as the page's Outreach draft, replacing any previous draft. Uses the website's team-wide Outreach custom instructions, the saved author name, and the sender's name. Costs 0.1 credits per draft written (billed in whole credits every 10 drafts); free when the page cannot be read. Show the draft to the user before they send it; nothing is sent.
| Parameter | Type | Description |
|---|---|---|
| url * | string | Cited page URL, e.g. "example.com/blog/best-tools". A contact already saved under this exact URL (for example one the Outreach page saved for a query variant its URL rules list separately) is used first. Otherwise protocol, "www." and the query string (tracking parameters) are ignored, as on the Out… |
| website_id * | string | |
| sender_name | string | Name to sign the email with. Defaults to the signed-in user's profile name; required for API-key sessions that should sign with a name. |
{
"name": "draft_outreach_message",
"description": "Draft a pitch email to the author of a cited page and save it as the page's Outreach draft, replacing any previous draft. Uses the website's team-wide Outreach custom instructions, the saved author name, and the sender's name. Costs 0.1 credits per draft written (billed in whole credits every 10 drafts); free when the page cannot be read. Show the draft to the user before they send it; nothing is sent.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"url"
],
"properties": {
"url": {
"type": "string",
"maxLength": 2048,
"minLength": 1,
"description": "Cited page URL, e.g. \"example.com/blog/best-tools\". A contact already saved under this exact URL (for example one the Outreach page saved for a query variant its URL rules list separately) is used first. Otherwise protocol, \"www.\" and the query string (tracking parameters) are ignored, as on the Outreach page. The page is always read at the URL given."
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"sender_name": {
"type": "string",
"maxLength": 120,
"minLength": 1,
"description": "Name to sign the email with. Defaults to the signed-in user's profile name; required for API-key sessions that should sign with a name."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"contact": {
"type": "object",
"required": [
"url",
"status",
"author_name",
"email",
"email_source",
"page_emails",
"contact_page_url",
"linkedin",
"subject",
"message",
"assignee_email",
"created_at"
],
"properties": {
"url": {
"type": "string"
},
"email": {
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"New",
"Todo",
"In Progress",
"Done",
"Rejected"
],
"type": "string"
},
"message": {
"type": [
"string",
"null"
]
},
"subject": {
"type": [
"string",
"null"
]
},
"linkedin": {
"type": [
"string",
"null"
]
},
"created_at": {
"type": "string"
},
"author_name": {
"type": [
"string",
"null"
]
},
"page_emails": {
"type": "array",
"items": {
"type": "string"
},
"description": "Up to five addresses the page or its linked contact page publishes, the chosen one first. Not a complete inventory."
},
"email_source": {
"anyOf": [
{
"enum": [
"page_author",
"page_contact",
"hunter",
"manual"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "Where the email came from: page_author (published on the page and matches the author), page_contact (the site's own address, may not reach the author), hunter (Hunter.io match, not published on the page, check before sending), manual (entered by a person). Null when unknown."
},
"assignee_email": {
"type": [
"string",
"null"
]
},
"contact_page_url": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"created": {
"type": "boolean",
"description": "True when this call created the page's contact."
}
},
"additionalProperties": false
},
"annotations": {
"title": "Draft an Outreach pitch",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": true
}
}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.
| Parameter | Type | Description |
|---|---|---|
| edits * | array | |
| content_id * | string | |
| website_id * | string | |
| expected_version_number | integer |
{
"name": "edit_content",
"description": "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.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"content_id",
"edits"
],
"properties": {
"edits": {
"type": "array",
"items": {
"type": "object",
"required": [
"find",
"replace"
],
"properties": {
"find": {
"type": "string",
"maxLength": 10000,
"minLength": 1
},
"replace": {
"type": "string",
"maxLength": 10000
}
},
"additionalProperties": false
}
},
"content_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"expected_version_number": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"body": {
"type": "string"
},
"content_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"version_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"version_number": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"body_word_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"previous_body_word_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
}
},
"additionalProperties": false
},
"annotations": {
"title": "Edit content",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
}
}Find more prompts for a finished Discover run: start the next round of its series with the same sources, effort level, country, language and custom instructions. The round skips every question the series already suggested and reads evidence earlier rounds did not use, so its prompts add to the same list. Invoke only after the user asks for more prompts from an existing run, and confirm with them first: each round runs the same paid research as a new run. A series 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 refuses with the reason. Returns the new round's run ID; poll the discovery history tool with it. Prompts are not added to tracking automatically. Requires prompt-management permission and the series' source entitlements.
| Parameter | Type | Description |
|---|---|---|
| run_id * | string | A finished Discover run, or any finished round of its series, to continue. |
| website_id * | string |
{
"name": "find_more_prompt_discovery",
"description": "Find more prompts for a finished Discover run: start the next round of its series with the same sources, effort level, country, language and custom instructions. The round skips every question the series already suggested and reads evidence earlier rounds did not use, so its prompts add to the same list. Invoke only after the user asks for more prompts from an existing run, and confirm with them first: each round runs the same paid research as a new run. A series 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 refuses with the reason. Returns the new round's run ID; poll the discovery history tool with it. Prompts are not added to tracking automatically. Requires prompt-management permission and the series' source entitlements.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"run_id"
],
"properties": {
"run_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "A finished Discover run, or any finished round of its series, to continue."
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"run_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"version": {
"type": "string",
"const": "v2"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Find more prompt discovery",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}
}Find who wrote a cited page and how to reach them, then save it to the page's Outreach contact. Reads the page's byline, the addresses the page publishes, and Hunter.io; when no author is found it returns the site's contact address and contact page instead. Every email comes with its source. Costs 0.1 credits when an author is found (billed in whole credits every 10 lookups); free otherwise. Overwrites the saved author fields. Obtain user confirmation before running it over many pages.
| Parameter | Type | Description |
|---|---|---|
| url * | string | Cited page URL, e.g. "example.com/blog/best-tools". A contact already saved under this exact URL (for example one the Outreach page saved for a query variant its URL rules list separately) is used first. Otherwise protocol, "www." and the query string (tracking parameters) are ignored, as on the Out… |
| website_id * | string |
{
"name": "find_outreach_author",
"description": "Find who wrote a cited page and how to reach them, then save it to the page's Outreach contact. Reads the page's byline, the addresses the page publishes, and Hunter.io; when no author is found it returns the site's contact address and contact page instead. Every email comes with its source. Costs 0.1 credits when an author is found (billed in whole credits every 10 lookups); free otherwise. Overwrites the saved author fields. Obtain user confirmation before running it over many pages.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"url"
],
"properties": {
"url": {
"type": "string",
"maxLength": 2048,
"minLength": 1,
"description": "Cited page URL, e.g. \"example.com/blog/best-tools\". A contact already saved under this exact URL (for example one the Outreach page saved for a query variant its URL rules list separately) is used first. Otherwise protocol, \"www.\" and the query string (tracking parameters) are ignored, as on the Outreach page. The page is always read at the URL given."
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"contact": {
"type": "object",
"required": [
"url",
"status",
"author_name",
"email",
"email_source",
"page_emails",
"contact_page_url",
"linkedin",
"subject",
"message",
"assignee_email",
"created_at"
],
"properties": {
"url": {
"type": "string"
},
"email": {
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"New",
"Todo",
"In Progress",
"Done",
"Rejected"
],
"type": "string"
},
"message": {
"type": [
"string",
"null"
]
},
"subject": {
"type": [
"string",
"null"
]
},
"linkedin": {
"type": [
"string",
"null"
]
},
"created_at": {
"type": "string"
},
"author_name": {
"type": [
"string",
"null"
]
},
"page_emails": {
"type": "array",
"items": {
"type": "string"
},
"description": "Up to five addresses the page or its linked contact page publishes, the chosen one first. Not a complete inventory."
},
"email_source": {
"anyOf": [
{
"enum": [
"page_author",
"page_contact",
"hunter",
"manual"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "Where the email came from: page_author (published on the page and matches the author), page_contact (the site's own address, may not reach the author), hunter (Hunter.io match, not published on the page, check before sending), manual (entered by a person). Null when unknown."
},
"assignee_email": {
"type": [
"string",
"null"
]
},
"contact_page_url": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"created": {
"type": "boolean",
"description": "True when this call created the page's contact."
},
"author_found": {
"type": "boolean"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Find a cited page's author",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": true
}
}Read one stored AI insight in full, by its id from get_ai_insights: its title, headline, body, suggested action, why it happened (with reasons and their pages), its numbers (facts, each with the table it came from), its move (subject, metric, current and previous values, the direction that is good news, and a definition of what the series counts and what it is out of), its evidence (topics, competitors, prompts, URLs), and the scope its numbers were computed under (window, comparison period, Default schedule, the prompts active at the analysis, prompt-type filter, the models the citation tables leave out). The numbers are the card's as of its analysis: quote them as such, with the window and the date the analysis ran (analyzed_at). A recompute with the other tools counts today's active prompts, so it can differ. Returns a not-found error for an insight that is not this website's, and status 'no_access' when AI Insights is not part of the organization's setup.
| Parameter | Type | Description |
|---|---|---|
| insight_id * | string | The insight's id, from get_ai_insights. |
| website_id * | string |
{
"name": "get_ai_insight",
"description": "Read one stored AI insight in full, by its id from get_ai_insights: its title, headline, body, suggested action, why it happened (with reasons and their pages), its numbers (facts, each with the table it came from), its move (subject, metric, current and previous values, the direction that is good news, and a definition of what the series counts and what it is out of), its evidence (topics, competitors, prompts, URLs), and the scope its numbers were computed under (window, comparison period, Default schedule, the prompts active at the analysis, prompt-type filter, the models the citation tables leave out). The numbers are the card's as of its analysis: quote them as such, with the window and the date the analysis ran (analyzed_at). A recompute with the other tools counts today's active prompts, so it can differ. Returns a not-found error for an insight that is not this website's, and status 'no_access' when AI Insights is not part of the organization's setup.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"insight_id"
],
"properties": {
"insight_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "The insight's id, from get_ai_insights."
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"status": {
"enum": [
"ready",
"no_access"
],
"type": "string"
},
"insight": {
"type": "object",
"required": [
"id",
"title",
"headline",
"body",
"category",
"impact",
"confidence",
"status",
"rating",
"analyzed_at",
"window",
"analysis",
"comparison",
"scope",
"move",
"why",
"facts",
"evidence",
"action"
],
"properties": {
"id": {
"type": "string"
},
"why": {
"anyOf": [
{
"type": "object",
"required": [
"text",
"since",
"reasons"
],
"properties": {
"text": {
"type": "string"
},
"since": {
"type": [
"string",
"null"
]
},
"reasons": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind",
"text",
"url",
"title",
"published_date"
],
"properties": {
"url": {
"type": [
"string",
"null"
]
},
"kind": {
"type": "string"
},
"text": {
"type": "string"
},
"title": {
"type": [
"string",
"null"
]
},
"published_date": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": {}
}
}
},
"additionalProperties": {}
},
{
"type": "null"
}
]
},
"body": {
"type": "string"
},
"move": {
"anyOf": [
{
"type": "object",
"required": [
"subject",
"metric",
"series",
"definition",
"current",
"previous",
"since",
"direction",
"flags",
"n"
],
"properties": {
"n": {
"type": "number"
},
"flags": {
"type": "array",
"items": {
"type": "string"
}
},
"since": {
"type": [
"string",
"null"
]
},
"metric": {
"type": "string"
},
"series": {
"type": "string"
},
"current": {
"type": "number"
},
"subject": {
"type": "object",
"required": [
"kind",
"label"
],
"properties": {
"kind": {
"type": "string"
},
"label": {
"type": "string"
}
},
"additionalProperties": {}
},
"previous": {
"anyOf": [
{
"type": "object",
"required": [
"value",
"label"
],
"properties": {
"label": {
"type": "string"
},
"value": {
"type": "number"
}
},
"additionalProperties": {}
},
{
"type": "null"
}
]
},
"direction": {
"enum": [
"higher_is_better",
"lower_is_better",
"level",
"unknown"
],
"type": "string"
},
"definition": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": {}
},
{
"type": "null"
}
]
},
"facts": {
"type": "array",
"items": {
"type": "object",
"required": [
"label",
"value",
"unit",
"source"
],
"properties": {
"unit": {
"type": "string"
},
"label": {
"type": "string"
},
"value": {
"type": "number"
},
"source": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": {}
}
},
"scope": {
"type": "object",
"required": [
"schedule",
"prompt_status",
"prompt_scope",
"prompt_type_filter",
"citation_models_excluded",
"note"
],
"properties": {
"note": {
"type": "string"
},
"schedule": {
"type": "string",
"const": "default"
},
"prompt_scope": {
"enum": [
"non_branded",
"all"
],
"type": "string"
},
"prompt_status": {
"type": "string",
"const": "active"
},
"prompt_type_filter": {
"anyOf": [
{
"type": "object",
"required": [
"eq"
],
"properties": {
"eq": {
"type": "string"
}
},
"additionalProperties": {}
},
{
"type": "null"
}
]
},
"citation_models_excluded": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": {}
},
"title": {
"type": "string"
},
"action": {
"type": "object",
"required": [
"text",
"target",
"started"
],
"properties": {
"text": {
"type": [
"string",
"null"
]
},
"target": {
"anyOf": [
{
"type": "object",
"required": [
"kind",
"verb",
"label",
"url",
"prompt_id"
],
"properties": {
"url": {
"type": [
"string",
"null"
]
},
"kind": {
"type": "string"
},
"verb": {
"type": "string"
},
"label": {
"type": "string"
},
"prompt_id": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": {}
},
{
"type": "null"
}
]
},
"started": {
"type": "boolean"
}
},
"additionalProperties": {}
},
"impact": {
"type": "string"
},
"rating": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string"
},
"window": {
"type": "object",
"required": [
"start",
"end",
"days"
],
"properties": {
"end": {
"type": "string"
},
"days": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"start": {
"type": "string"
}
},
"additionalProperties": {}
},
"analysis": {
"type": "object",
"required": [
"run_id",
"window_start",
"window_end",
"completed_at"
],
"properties": {
"run_id": {
"type": "string"
},
"window_end": {
"type": [
"string",
"null"
]
},
"completed_at": {
"type": [
"string",
"null"
]
},
"window_start": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": {}
},
"category": {
"type": "string"
},
"evidence": {
"type": "object",
"required": [
"topics",
"competitors",
"prompts",
"urls"
],
"properties": {
"urls": {
"type": "array",
"items": {
"type": "string"
}
},
"topics": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"additionalProperties": {}
}
},
"prompts": {
"type": "array",
"items": {
"type": "string"
}
},
"competitors": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": {}
},
"headline": {
"type": "string"
},
"comparison": {
"anyOf": [
{
"type": "object",
"required": [
"start",
"end",
"label"
],
"properties": {
"end": {
"type": "string"
},
"label": {
"type": "string"
},
"start": {
"type": "string"
}
},
"additionalProperties": {}
},
{
"type": "null"
}
]
},
"confidence": {
"type": "string"
},
"analyzed_at": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": {}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get AI insight",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}List the website's stored AI insights: the precomputed cards on the AI Insights page, each a verified finding of one past analysis, newest analysis first and higher impact first. Each has its id, title, headline, category, impact, the days its numbers cover (window), the time the analysis ran (analyzed_at), its status (available, done, or discarded = hidden by the team), the team's rating, and its move's subject and metric. Call this first for an open-ended request for insights or for what to do ('give me some insights', 'what's interesting', 'what should I prioritize'), and answer from these cards instead of running a new analysis: highest impact first, each by its title and headline. Always state the window and the date the analysis ran, and offer a fresh look with the other analytics tools. Read one card in full with get_ai_insight. Paged: 20 by default; for more, pass limit (up to 50) and offset set to the returned next_offset until it is null. Default status is available. Returns status 'no_access' when AI Insights is not part of the organization's setup. Then, or when no insight is listed, answer from the other analytics tools.
| Parameter | Type | Description |
|---|---|---|
| limit | integer | |
| offset | integer | How many to skip: the previous read's next_offset. |
| status | string | The lifecycle to list: available (default), done, or discarded (hidden by the team). |
| website_id * | string |
{
"name": "get_ai_insights",
"description": "List the website's stored AI insights: the precomputed cards on the AI Insights page, each a verified finding of one past analysis, newest analysis first and higher impact first. Each has its id, title, headline, category, impact, the days its numbers cover (window), the time the analysis ran (analyzed_at), its status (available, done, or discarded = hidden by the team), the team's rating, and its move's subject and metric. Call this first for an open-ended request for insights or for what to do ('give me some insights', 'what's interesting', 'what should I prioritize'), and answer from these cards instead of running a new analysis: highest impact first, each by its title and headline. Always state the window and the date the analysis ran, and offer a fresh look with the other analytics tools. Read one card in full with get_ai_insight. Paged: 20 by default; for more, pass limit (up to 50) and offset set to the returned next_offset until it is null. Default status is available. Returns status 'no_access' when AI Insights is not part of the organization's setup. Then, or when no insight is listed, answer from the other analytics tools.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id"
],
"properties": {
"limit": {
"type": "integer",
"maximum": 50,
"minimum": 1
},
"offset": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "How many to skip: the previous read's next_offset."
},
"status": {
"enum": [
"available",
"done",
"discarded"
],
"type": "string",
"description": "The lifecycle to list: available (default), done, or discarded (hidden by the team)."
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"status": {
"enum": [
"ready",
"no_access"
],
"type": "string"
},
"has_more": {
"type": "boolean"
},
"insights": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"title",
"headline",
"category",
"impact",
"window",
"analyzed_at",
"status",
"rating",
"subject",
"metric"
],
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"impact": {
"type": "string"
},
"metric": {
"type": [
"string",
"null"
]
},
"rating": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string"
},
"window": {
"type": "object",
"required": [
"start",
"end"
],
"properties": {
"end": {
"type": "string"
},
"start": {
"type": "string"
}
},
"additionalProperties": {}
},
"subject": {
"type": [
"string",
"null"
]
},
"category": {
"type": "string"
},
"headline": {
"type": "string"
},
"analyzed_at": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": {}
}
},
"next_offset": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get AI insights",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}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).
| Parameter | Type | Description |
|---|---|---|
| limit | string | |
| offset | string | |
| status | string | one of ["approved","pending","rejected"] |
| unfiled | string | one of ["true","false"] |
| pillar_id | string | |
| website_id * | string | |
| source_type | string | one of ["research","response","upload","content_hub"] |
| include_oracle | string | one of ["true","false"] |
{
"name": "get_brand_facts",
"description": "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).",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id"
],
"properties": {
"limit": {
"type": "string",
"pattern": "^\\d+$"
},
"offset": {
"type": "string",
"pattern": "^\\d+$"
},
"status": {
"enum": [
"approved",
"pending",
"rejected"
],
"type": "string"
},
"unfiled": {
"enum": [
"true",
"false"
],
"type": "string"
},
"pillar_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"source_type": {
"enum": [
"research",
"response",
"upload",
"content_hub"
],
"type": "string"
},
"include_oracle": {
"enum": [
"true",
"false"
],
"type": "string"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"facts": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"text",
"status",
"confidence",
"source_url",
"source_quote",
"source_type",
"pillar",
"created_at"
],
"properties": {
"id": {
"type": "string"
},
"text": {
"type": "string"
},
"pillar": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"status": {
"enum": [
"approved",
"pending",
"rejected"
],
"type": "string"
},
"confidence": {
"anyOf": [
{
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string"
},
"source_url": {
"type": [
"string",
"null"
]
},
"source_type": {
"enum": [
"research",
"response",
"upload",
"content_hub"
],
"type": "string"
},
"source_quote": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
},
"total": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get brand facts",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}Read a brand kit as the Brand Profile editor shows it, to inspect or change it: the draft name, the eight guidance fields as text (voice is the writing direction), voice settings (1-5 or auto), tone traits, the kit's writing rules with ids, and the website's global writing rules with ids, plus draft and published versions. Omit kit_id for the website's default kit; available_kits lists every kit. Content generation uses a kit's published version, so has_unpublished_changes means the draft differs from it. Guidance fields longer than the clip come back shortened and listed in truncated_fields; pass fields to read those whole, which update_brand_kit's find needs. Rules are clipped too, each with its own truncated flag. Call this before update_brand_kit. To write in the brand's voice, read brandKit__get instead. Read-only.
| Parameter | Type | Description |
|---|---|---|
| fields | array | Guidance fields to return whole (up to 12,000 characters) instead of clipped at 4,000. Needed before a find edit on a clipped field. |
| kit_id | string | The brand kit to read. Omit it for the website's default kit; available_kits lists every kit. |
| website_id * | string |
{
"name": "get_brand_kit",
"description": "Read a brand kit as the Brand Profile editor shows it, to inspect or change it: the draft name, the eight guidance fields as text (voice is the writing direction), voice settings (1-5 or auto), tone traits, the kit's writing rules with ids, and the website's global writing rules with ids, plus draft and published versions. Omit kit_id for the website's default kit; available_kits lists every kit. Content generation uses a kit's published version, so has_unpublished_changes means the draft differs from it. Guidance fields longer than the clip come back shortened and listed in truncated_fields; pass fields to read those whole, which update_brand_kit's find needs. Rules are clipped too, each with its own truncated flag. Call this before update_brand_kit. To write in the brand's voice, read brandKit__get instead. Read-only.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id"
],
"properties": {
"fields": {
"type": "array",
"items": {
"enum": [
"voice",
"audience",
"perspective",
"author",
"terminology",
"channel",
"locale",
"disclosures"
],
"type": "string",
"description": "voice is the writing direction; the others are audience, perspective (point of view), author (author guidance), terminology, channel (format and channel), locale (language and locale), disclosures (claims and disclosures)."
},
"description": "Guidance fields to return whole (up to 12,000 characters) instead of clipped at 4,000. Needed before a find edit on a clipped field."
},
"kit_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "The brand kit to read. Omit it for the website's default kit; available_kits lists every kit."
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"kit": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"name",
"is_default",
"draft_version",
"published_version",
"has_unpublished_changes",
"generation_status",
"guidance",
"tone_traits",
"voice_settings",
"custom_voice_traits",
"rules",
"rules_total",
"examples_count",
"sources_count"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"name": {
"type": "string"
},
"rules": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"text",
"category",
"is_active",
"truncated"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"text": {
"type": "string"
},
"category": {
"type": [
"string",
"null"
]
},
"is_active": {
"type": "boolean"
},
"truncated": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"guidance": {
"type": "object",
"required": [
"voice",
"audience",
"perspective",
"author",
"terminology",
"channel",
"locale",
"disclosures"
],
"properties": {
"voice": {
"type": "string"
},
"author": {
"type": "string"
},
"locale": {
"type": "string"
},
"channel": {
"type": "string"
},
"audience": {
"type": "string"
},
"disclosures": {
"type": "string"
},
"perspective": {
"type": "string"
},
"terminology": {
"type": "string"
}
},
"additionalProperties": false
},
"is_default": {
"type": "boolean"
},
"rules_total": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"tone_traits": {
"type": "array",
"items": {
"type": "string"
}
},
"draft_version": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"sources_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"examples_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"voice_settings": {
"type": "object",
"required": [
"formality",
"expression",
"humor",
"stance",
"technicality"
],
"properties": {
"humor": {
"anyOf": [
{
"type": "integer",
"maximum": 5,
"minimum": 1
},
{
"type": "string",
"const": "auto"
}
]
},
"stance": {
"anyOf": [
{
"type": "integer",
"maximum": 5,
"minimum": 1
},
{
"type": "string",
"const": "auto"
}
]
},
"formality": {
"anyOf": [
{
"type": "integer",
"maximum": 5,
"minimum": 1
},
{
"type": "string",
"const": "auto"
}
]
},
"expression": {
"anyOf": [
{
"type": "integer",
"maximum": 5,
"minimum": 1
},
{
"type": "string",
"const": "auto"
}
]
},
"technicality": {
"anyOf": [
{
"type": "integer",
"maximum": 5,
"minimum": 1
},
{
"type": "string",
"const": "auto"
}
]
}
},
"additionalProperties": false
},
"generation_status": {
"anyOf": [
{
"enum": [
"generating",
"failed"
],
"type": "string"
},
{
"type": "null"
}
]
},
"published_version": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
{
"type": "null"
}
]
},
"custom_voice_traits": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"value"
],
"properties": {
"name": {
"type": "string"
},
"value": {
"anyOf": [
{
"type": "integer",
"maximum": 5,
"minimum": 1
},
{
"type": "string",
"const": "auto"
}
]
}
},
"additionalProperties": false
}
},
"has_unpublished_changes": {
"type": "boolean"
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"truncated": {
"type": "boolean"
},
"global_rules": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"text",
"category",
"is_active",
"truncated"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"text": {
"type": "string"
},
"category": {
"type": [
"string",
"null"
]
},
"is_active": {
"type": "boolean"
},
"truncated": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"can_use_rules": {
"type": "boolean"
},
"available_kits": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"is_default",
"draft_version",
"published_version",
"has_unpublished_changes",
"generation_status"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"name": {
"type": "string"
},
"is_default": {
"type": "boolean"
},
"draft_version": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"generation_status": {
"anyOf": [
{
"enum": [
"generating",
"failed"
],
"type": "string"
},
{
"type": "null"
}
]
},
"published_version": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
{
"type": "null"
}
]
},
"has_unpublished_changes": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"global_version": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"truncated_fields": {
"type": "array",
"items": {
"enum": [
"voice",
"audience",
"perspective",
"author",
"terminology",
"channel",
"locale",
"disclosures"
],
"type": "string",
"description": "voice is the writing direction; the others are audience, perspective (point of view), author (author guidance), terminology, channel (format and channel), locale (language and locale), disclosures (claims and disclosures)."
}
},
"rules_unavailable": {
"type": "boolean"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get brand kit",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}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.
| Parameter | Type | Description |
|---|---|---|
| content_id * | string | |
| website_id * | string |
{
"name": "get_content_draft",
"description": "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.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"content_id"
],
"properties": {
"content_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"body": {
"type": [
"string",
"null"
]
},
"brief": {
"type": [
"string",
"null"
]
},
"title": {
"type": [
"string",
"null"
]
},
"status": {
"type": [
"string",
"null"
]
},
"content_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"meta_description": {
"type": [
"string",
"null"
]
},
"latest_version_number": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get content draft",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}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.
| Parameter | Type | Description |
|---|---|---|
| content_id * | string | |
| website_id * | string |
{
"name": "get_content_status",
"description": "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.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"content_id"
],
"properties": {
"content_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"stage": {
"anyOf": [
{
"enum": [
"scheduled",
"pending",
"pending_brief",
"generated_brief",
"pending_article",
"generated",
"done",
"failed"
],
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"enum": [
"running",
"succeeded",
"failed"
],
"type": "string"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get content status",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}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.
| Parameter | Type | Description |
|---|---|---|
| content_id * | string | |
| version_id * | string | |
| website_id * | string |
{
"name": "get_content_version",
"description": "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.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"content_id",
"version_id"
],
"properties": {
"content_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"version_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"body": {
"type": [
"string",
"null"
]
},
"brief": {
"type": [
"string",
"null"
]
},
"label": {
"type": [
"string",
"null"
]
},
"created_at": {
"type": "string"
},
"version_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"change_type": {
"type": [
"string",
"null"
]
},
"version_number": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"meta_description": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get content version",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}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.
| Parameter | Type | Description |
|---|---|---|
| limit | integer | |
| offset | integer | |
| content_id * | string | |
| website_id * | string |
{
"name": "get_content_versions",
"description": "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.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"content_id"
],
"properties": {
"limit": {
"type": "integer",
"maximum": 50,
"minimum": 1
},
"offset": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"content_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"versions": {
"type": "array",
"items": {
"type": "object",
"required": [
"version_id",
"version_number",
"label",
"change_type",
"created_at",
"created_by_name"
],
"properties": {
"label": {
"type": [
"string",
"null"
]
},
"created_at": {
"type": "string"
},
"version_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"change_type": {
"type": [
"string",
"null"
]
},
"version_number": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"created_by_name": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
},
"total_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get content versions",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}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.
| Parameter | Type | Description |
|---|---|---|
| limit | integer | |
| range | string | one of ["24h","7d","30d","90d","all"] |
| offset | integer | |
| window | object | Explicit UTC interval within recorded history, ending no later than now. For the current month or today, use the current UTC time as endAtUtc, not the next calendar boundary. Reuse both returned boundaries when paging. |
| website_id * | string |
{
"name": "get_credit_usage",
"description": "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.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id"
],
"properties": {
"limit": {
"type": "integer",
"maximum": 50,
"minimum": 1
},
"range": {
"enum": [
"24h",
"7d",
"30d",
"90d",
"all"
],
"type": "string"
},
"offset": {
"type": "integer",
"maximum": 1000000,
"minimum": 0
},
"window": {
"type": "object",
"required": [
"start_at_utc",
"end_at_utc"
],
"properties": {
"end_at_utc": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
},
"start_at_utc": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
}
},
"description": "Explicit UTC interval within recorded history, ending no later than now. For the current month or today, use the current UTC time as endAtUtc, not the next calendar boundary. Reuse both returned boundaries when paging.",
"additionalProperties": false
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"window": {
"type": "object",
"required": [
"start_at_utc",
"end_at_utc"
],
"properties": {
"end_at_utc": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
},
"start_at_utc": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
}
},
"additionalProperties": false
},
"buckets": {
"type": "array",
"items": {
"type": "object",
"required": [
"period_start_utc",
"credits_used",
"event_count"
],
"properties": {
"event_count": {
"type": "number"
},
"credits_used": {
"type": "number"
},
"period_start_utc": {
"type": "string"
}
},
"additionalProperties": false
}
},
"entities": {
"type": "array",
"items": {
"type": "object",
"required": [
"entity_id",
"entity_name",
"entity_type",
"credits_used"
],
"properties": {
"entity_id": {
"type": "string"
},
"entity_name": {
"type": [
"string",
"null"
]
},
"entity_type": {
"enum": [
"website",
"group",
"organization",
"unknown"
],
"type": "string"
},
"credits_used": {
"type": "number"
}
},
"additionalProperties": false
}
},
"has_more": {
"type": "boolean"
},
"next_offset": {
"type": "number"
},
"breakdown_note": {
"type": "string"
},
"total_credits_used": {
"type": "number"
},
"breakdown_credits_used": {
"type": "number"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get credit usage",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}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.
| Parameter | Type | Description |
|---|---|---|
| limit | integer | |
| range | string | one of ["24h","7d","30d","90d","all"] |
| offset | integer | |
| window | object | Explicit UTC interval within recorded history, ending no later than now. For the current month or today, use the current UTC time as endAtUtc, not the next calendar boundary. Reuse both returned boundaries when paging. |
| website_id * | string | |
| originating_website_id | string | Optional originating website in this organization; this is different from the charged group pool. |
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.
| Parameter | Type | Description |
|---|---|---|
| website_id * | string | |
| competitor_id | string | The competitor to read or edit, from get_competitors. Omit it for the website's own brand. |
{
"name": "get_identifiers",
"description": "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.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id"
],
"properties": {
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"competitor_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "The competitor to read or edit, from get_competitors. Omit it for the website's own brand."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"entity": {
"type": "object",
"required": [
"type",
"id",
"name",
"url"
],
"properties": {
"id": {
"type": "string"
},
"url": {
"type": "string"
},
"name": {
"type": "string"
},
"type": {
"enum": [
"brand",
"competitor"
],
"type": "string"
}
},
"additionalProperties": false
},
"identifiers": {
"type": "array",
"items": {
"type": "string"
}
},
"case_sensitive": {
"type": "boolean"
},
"default_identifiers": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get identifiers",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}Fetch a pillar's synthesized markdown document from the Knowledge Base. Returns document: null when the pillar exists but has no synthesized document yet.
| Parameter | Type | Description |
|---|---|---|
| pillar_id * | string | |
| website_id * | string |
{
"name": "get_pillar_document",
"description": "Fetch a pillar's synthesized markdown document from the Knowledge Base. Returns document: null when the pillar exists but has no synthesized document yet.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"pillar_id"
],
"properties": {
"pillar_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"name": {
"type": "string"
},
"document": {
"type": [
"string",
"null"
]
},
"pillar_id": {
"type": "string"
},
"generated_at": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get pillar document",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}List 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.
| Parameter | Type | Description |
|---|---|---|
| website_id * | string |
{
"name": "get_pillars",
"description": "List 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.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id"
],
"properties": {
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"pillars": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"description",
"status",
"fact_count",
"has_document",
"last_researched_at"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"status": {
"enum": [
"researching",
"published",
"draft",
"archived"
],
"type": "string"
},
"fact_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"description": {
"type": [
"string",
"null"
]
},
"has_document": {
"type": "boolean"
},
"last_researched_at": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get pillars",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}Read Discover history and progress for a website, or supply the run ID returned by discovery launch to inspect one study. Distinguishes pending, running, completed, partial, failed and cancelled. limit bounds returned runs (default 10, maximum 20); has_more means older runs remain. This is read-only: it does not start research, monitor in the background or send notifications. Candidate results can be reviewed in the application's Discover page. Requires permission to view prompts; source visibility restrictions still apply.
| Parameter | Type | Description |
|---|---|---|
| limit | integer | |
| run_id | string | |
| website_id * | string |
{
"name": "get_prompt_discovery_runs",
"description": "Read Discover history and progress for a website, or supply the run ID returned by discovery launch to inspect one study. Distinguishes pending, running, completed, partial, failed and cancelled. limit bounds returned runs (default 10, maximum 20); has_more means older runs remain. This is read-only: it does not start research, monitor in the background or send notifications. Candidate results can be reviewed in the application's Discover page. Requires permission to view prompts; source visibility restrictions still apply.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id"
],
"properties": {
"limit": {
"type": "integer",
"maximum": 20,
"minimum": 1
},
"run_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"runs": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"created_at",
"country",
"language",
"sources",
"status",
"progress_percentage",
"phase",
"total_prompts",
"reason_code",
"reason",
"rounds",
"can_find_more",
"find_more_reason"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"phase": {
"type": [
"string",
"null"
]
},
"reason": {
"type": [
"string",
"null"
],
"description": "A user-safe sentence explaining a failed, empty or short run, the same line the Discover page shows. Null when there is nothing to explain."
},
"rounds": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Rounds in the run's Find more series: 1 for a run never continued. Status, progress and reason describe the latest round; total_prompts adds every round."
},
"status": {
"enum": [
"pending",
"running",
"completed",
"partial",
"failed",
"cancelled"
],
"type": "string"
},
"country": {
"type": [
"string",
"null"
]
},
"sources": {
"type": "array",
"items": {
"type": "string"
}
},
"language": {
"type": [
"string",
"null"
]
},
"created_at": {
"type": "string"
},
"reason_code": {
"type": [
"string",
"null"
],
"description": "Why a finished run ended: the terminal reason of a completed run (for example requested_minimum_not_met or coverage_saturated) or the error code of a failed one. Null while the run is in progress or for runs that recorded none."
},
"can_find_more": {
"type": "boolean",
"description": "Whether find_more_prompt_discovery can start another round of this run now."
},
"total_prompts": {
"type": "number"
},
"find_more_reason": {
"type": [
"string",
"null"
],
"description": "A user-safe sentence explaining why no further round can start. Null when can_find_more is true or the run cannot be continued at all."
},
"progress_percentage": {
"type": "number"
}
},
"additionalProperties": false
}
},
"has_more": {
"type": "boolean"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get prompt discovery runs",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}Read saved Google organic rankings by explicit market and device alongside observed AI visibility. Includes recent history, missing-data reasons, freshness and committed provider budget. Does not trigger collection.
| Parameter | Type | Description |
|---|---|---|
| website_id * | string | |
| property_id | string |
{
"name": "get_seo_rankings",
"description": "Read saved Google organic rankings by explicit market and device alongside observed AI visibility. Includes recent history, missing-data reasons, freshness and committed provider budget. Does not trigger collection.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id"
],
"properties": {
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"property_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"property_id",
"keyword",
"market",
"language",
"device",
"target_root",
"is_navigational",
"paused",
"cadence_days",
"next_collect_at",
"last_requested_at",
"stale",
"current",
"history",
"rank_change",
"ai"
],
"properties": {
"ai": {
"type": "object",
"required": [
"prompt_ids",
"responses",
"mentions",
"visibility_pct",
"reason",
"start_date",
"end_date"
],
"properties": {
"reason": {
"type": "string"
},
"end_date": {
"type": "string"
},
"mentions": {
"type": [
"number",
"null"
]
},
"responses": {
"type": [
"number",
"null"
]
},
"prompt_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"start_date": {
"type": "string"
},
"visibility_pct": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
},
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"stale": {
"type": "boolean"
},
"device": {
"enum": [
"desktop",
"mobile"
],
"type": "string"
},
"market": {
"type": "string"
},
"paused": {
"type": "boolean"
},
"current": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"status",
"rank",
"landing_url",
"requested_at",
"collected_at",
"observed_depth",
"error"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"rank": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
{
"type": "null"
}
]
},
"error": {
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"pending",
"submitting",
"queued",
"ranked",
"not_found",
"unavailable",
"failed"
],
"type": "string"
},
"landing_url": {
"type": [
"string",
"null"
]
},
"collected_at": {
"type": [
"string",
"null"
]
},
"requested_at": {
"type": "string"
},
"observed_depth": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"history": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"status",
"rank",
"landing_url",
"requested_at",
"collected_at",
"observed_depth",
"error"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"rank": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
{
"type": "null"
}
]
},
"error": {
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"pending",
"submitting",
"queued",
"ranked",
"not_found",
"unavailable",
"failed"
],
"type": "string"
},
"landing_url": {
"type": [
"string",
"null"
]
},
"collected_at": {
"type": [
"string",
"null"
]
},
"requested_at": {
"type": "string"
},
"observed_depth": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
},
"keyword": {
"type": "string"
},
"language": {
"type": "string",
"const": "en"
},
"property_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"rank_change": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
{
"type": "null"
}
]
},
"target_root": {
"type": "string"
},
"cadence_days": {
"type": "number",
"const": 7
},
"is_navigational": {
"type": "boolean"
},
"next_collect_at": {
"type": "string"
},
"last_requested_at": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
},
"provider": {
"type": "string",
"const": "DataForSEO Google organic"
},
"billed_cost_usd": {
"type": "number"
},
"requested_depth": {
"type": "number",
"const": 100
},
"unknown_cost_jobs": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"collection_enabled": {
"type": "boolean"
},
"monthly_budget_usd": {
"type": "number"
},
"committed_budget_usd": {
"type": "number"
},
"refresh_cooldown_hours": {
"type": "number",
"const": 24
},
"estimated_refresh_cost_usd": {
"type": "number"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get seo rankings",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}Get 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 (merchant) breakdown, rank distribution, price comparison, and a daily appearances trend. Rates are percentages 0-100; positions are 1-based (lower is better). Requires a paid plan.
| Parameter | Type | Description |
|---|---|---|
| filters * | object | |
| website_id * | string | |
| top_products_limit | integer | How many products to return in each of top_own_products and top_competitor_products, 1 to 50. Defaults to 10. |
{
"name": "get_shopping_metrics",
"description": "Get 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 (merchant) breakdown, rank distribution, price comparison, and a daily appearances trend. Rates are percentages 0-100; positions are 1-based (lower is better). Requires a paid plan.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"filters"
],
"properties": {
"filters": {
"type": "object",
"required": [
"start_date"
],
"properties": {
"models": {
"type": "array",
"items": {
"enum": [
"chatgpt",
"ai_mode",
"gemini",
"perplexity",
"copilot"
],
"type": "string"
},
"description": "Shopping-capable models to include, as an array even for one model: any of \"chatgpt\", \"ai_mode\", \"gemini\", \"perplexity\" and \"copilot\". Omit for all."
},
"end_date": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "End of the date range, YYYY-MM-DD (UTC), inclusive. Omit for today."
},
"start_date": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "Start of the date range, YYYY-MM-DD (UTC), inclusive. Required."
},
"prompt_tags": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Prompt tag IDs to filter prompts by, as an array (list tags with get_prompt_tags). Omit for all tags."
},
"schedule_id": {
"anyOf": [
{
"enum": [
"default",
"manual"
],
"type": "string"
},
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
],
"description": "One schedule: \"default\" or a custom/archived schedule UUID. Omit for Default, which includes all pre-cutover history and ad hoc runs. Schedules cannot be combined."
},
"competitor_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Competitor UUIDs to keep in the competitor blocks, as an array even for one id. Own products are always included. Omit for all competitors."
},
"target_identifiers": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"description": "Target identifier strings to filter responses to, as an array even for one value. The literal string \"no-identifier\" selects responses with no target identifier. Omit for all."
},
"prompt_tags_operator": {
"enum": [
"is_any_of",
"has_all_of"
],
"type": "string",
"description": "How prompt_tags combine: \"is_any_of\" matches prompts with any listed tag, \"has_all_of\" only prompts carrying every listed tag."
}
},
"additionalProperties": false
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"top_products_limit": {
"type": "integer",
"maximum": 50,
"minimum": 1,
"description": "How many products to return in each of top_own_products and top_competitor_products, 1 to 50. Defaults to 10."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"data": {
"type": "object",
"required": [
"summary",
"offer_summary",
"top_own_products",
"top_competitor_products",
"competitor_breakdown",
"merchant_breakdown",
"position_distribution",
"price_comparison",
"trend"
],
"properties": {
"trend": {
"type": "array",
"items": {
"type": "object",
"required": [
"date",
"total_products",
"own_products",
"competitor_products",
"total_responses",
"responses_with_own"
],
"properties": {
"date": {
"type": "string"
},
"own_products": {
"type": "number"
},
"total_products": {
"type": "number"
},
"total_responses": {
"type": "number"
},
"responses_with_own": {
"type": "number"
},
"competitor_products": {
"type": "number"
}
},
"additionalProperties": false
}
},
"summary": {
"type": "object",
"required": [
"total_shopping_responses",
"responses_with_own_products",
"appearance_rate",
"total_products",
"own_products",
"competitor_products",
"avg_own_position",
"avg_competitor_position"
],
"properties": {
"own_products": {
"type": "number"
},
"total_products": {
"type": "number"
},
"appearance_rate": {
"type": "number"
},
"avg_own_position": {
"type": [
"number",
"null"
]
},
"competitor_products": {
"type": "number"
},
"avg_competitor_position": {
"type": [
"number",
"null"
]
},
"total_shopping_responses": {
"type": "number"
},
"responses_with_own_products": {
"type": "number"
}
},
"additionalProperties": false
},
"offer_summary": {
"type": "object",
"required": [
"total_offers",
"products_with_offers",
"competitor_offers",
"currency",
"avg_price"
],
"properties": {
"currency": {
"type": "string"
},
"avg_price": {
"type": [
"number",
"null"
]
},
"total_offers": {
"type": "number"
},
"competitor_offers": {
"type": "number"
},
"products_with_offers": {
"type": "number"
}
},
"additionalProperties": false
},
"price_comparison": {
"type": "array",
"items": {
"type": "object",
"required": [
"category",
"currency",
"avg_price",
"min_price",
"max_price",
"product_count"
],
"properties": {
"category": {
"enum": [
"own",
"competitor"
],
"type": "string"
},
"currency": {
"type": "string"
},
"avg_price": {
"type": [
"number",
"null"
]
},
"max_price": {
"type": [
"number",
"null"
]
},
"min_price": {
"type": [
"number",
"null"
]
},
"product_count": {
"type": "number"
}
},
"additionalProperties": false
}
},
"top_own_products": {
"type": "array",
"items": {
"type": "object",
"required": [
"title",
"merchant",
"appearances",
"avg_position",
"avg_rating",
"image_url",
"product_url"
],
"properties": {
"title": {
"type": "string"
},
"merchant": {
"type": [
"string",
"null"
]
},
"image_url": {
"type": [
"string",
"null"
]
},
"avg_rating": {
"type": [
"number",
"null"
]
},
"appearances": {
"type": "number"
},
"product_url": {
"type": [
"string",
"null"
]
},
"avg_position": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
}
},
"merchant_breakdown": {
"type": "array",
"items": {
"type": "object",
"required": [
"merchant",
"own_count",
"competitor_count",
"own_avg_position",
"competitor_avg_position",
"own_response_count",
"competitor_response_count"
],
"properties": {
"merchant": {
"type": "string"
},
"own_count": {
"type": "number"
},
"competitor_count": {
"type": "number"
},
"own_avg_position": {
"type": [
"number",
"null"
]
},
"own_response_count": {
"type": "number"
},
"competitor_avg_position": {
"type": [
"number",
"null"
]
},
"competitor_response_count": {
"type": "number"
}
},
"additionalProperties": false
}
},
"competitor_breakdown": {
"type": "array",
"items": {
"type": "object",
"required": [
"competitor_id",
"competitor_name",
"product_count",
"avg_position",
"avg_rating",
"response_count"
],
"properties": {
"avg_rating": {
"type": [
"number",
"null"
]
},
"avg_position": {
"type": [
"number",
"null"
]
},
"competitor_id": {
"type": "string"
},
"product_count": {
"type": "number"
},
"response_count": {
"type": "number"
},
"competitor_name": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
},
"position_distribution": {
"type": "array",
"items": {
"type": "object",
"required": [
"position",
"count",
"own_count",
"competitor_count"
],
"properties": {
"count": {
"type": "number"
},
"position": {
"type": "number"
},
"own_count": {
"type": "number"
},
"competitor_count": {
"type": "number"
}
},
"additionalProperties": false
}
},
"top_competitor_products": {
"type": "array",
"items": {
"type": "object",
"required": [
"title",
"merchant",
"appearances",
"avg_position",
"avg_rating",
"image_url",
"product_url",
"competitor_id"
],
"properties": {
"title": {
"type": "string"
},
"merchant": {
"type": [
"string",
"null"
]
},
"image_url": {
"type": [
"string",
"null"
]
},
"avg_rating": {
"type": [
"number",
"null"
]
},
"appearances": {
"type": "number"
},
"product_url": {
"type": [
"string",
"null"
]
},
"avg_position": {
"type": [
"number",
"null"
]
},
"competitor_id": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get shopping metrics",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}Live Google Analytics 4, Google Search Console and AI-citation figures for a website over the last 28 complete days, each beside the 28 days before (period gives both ranges; change_pct is null when the earlier period was zero). ga4: AI-referred sessions, their engagement rate and key events, organic and total sessions, AI share of sessions in percent, daily AI sessions, and the top 10 AI sources, AI landing pages and organic landing pages. gsc: clicks, impressions, CTR in percent and average position, a daily series, and the top 10 queries and pages. cited_pages: the website's pages AI answers cited most, with the Google figures for the same page. connected false means no Google property is linked for that provider; available false means it is linked but the read failed. Read live from Google, so a connection made a moment ago shows at once. Requires Site Health on the website's plan; otherwise the call fails with 403.
| Parameter | Type | Description |
|---|---|---|
| website_id * | string |
{
"name": "get_site_health_analytics",
"description": "Live Google Analytics 4, Google Search Console and AI-citation figures for a website over the last 28 complete days, each beside the 28 days before (period gives both ranges; change_pct is null when the earlier period was zero). ga4: AI-referred sessions, their engagement rate and key events, organic and total sessions, AI share of sessions in percent, daily AI sessions, and the top 10 AI sources, AI landing pages and organic landing pages. gsc: clicks, impressions, CTR in percent and average position, a daily series, and the top 10 queries and pages. cited_pages: the website's pages AI answers cited most, with the Google figures for the same page. connected false means no Google property is linked for that provider; available false means it is linked but the read failed. Read live from Google, so a connection made a moment ago shows at once. Requires Site Health on the website's plan; otherwise the call fails with 403.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id"
],
"properties": {
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"ga4": {
"type": "object",
"required": [
"connected",
"available",
"property_name",
"ai_sessions",
"ai_engagement_rate",
"ai_key_events",
"organic_sessions",
"total_sessions",
"ai_share_pct",
"ai_daily",
"sources",
"ai_landing_pages",
"organic_landing_pages"
],
"properties": {
"sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"sessions",
"previous"
],
"properties": {
"name": {
"type": "string"
},
"previous": {
"type": "number"
},
"sessions": {
"type": "number"
}
},
"additionalProperties": false
}
},
"ai_daily": {
"type": "array",
"items": {
"type": "object",
"required": [
"date",
"value"
],
"properties": {
"date": {
"type": "string"
},
"value": {
"type": "number"
}
},
"additionalProperties": false
}
},
"available": {
"type": "boolean"
},
"connected": {
"type": "boolean"
},
"ai_sessions": {
"type": "object",
"required": [
"current",
"previous",
"change_pct"
],
"properties": {
"current": {
"type": "number"
},
"previous": {
"type": "number"
},
"change_pct": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
},
"ai_share_pct": {
"type": [
"number",
"null"
]
},
"ai_key_events": {
"type": "object",
"required": [
"current",
"previous",
"change_pct"
],
"properties": {
"current": {
"type": "number"
},
"previous": {
"type": "number"
},
"change_pct": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
},
"property_name": {
"type": [
"string",
"null"
]
},
"total_sessions": {
"type": "object",
"required": [
"current",
"previous",
"change_pct"
],
"properties": {
"current": {
"type": "number"
},
"previous": {
"type": "number"
},
"change_pct": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
},
"ai_landing_pages": {
"type": "array",
"items": {
"type": "object",
"required": [
"url",
"sessions",
"previous"
],
"properties": {
"url": {
"type": "string"
},
"previous": {
"type": "number"
},
"sessions": {
"type": "number"
}
},
"additionalProperties": false
}
},
"organic_sessions": {
"type": "object",
"required": [
"current",
"previous",
"change_pct"
],
"properties": {
"current": {
"type": "number"
},
"previous": {
"type": "number"
},
"change_pct": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
},
"ai_engagement_rate": {
"type": [
"number",
"null"
]
},
"organic_landing_pages": {
"type": "array",
"items": {
"type": "object",
"required": [
"url",
"sessions",
"key_events"
],
"properties": {
"url": {
"type": "string"
},
"sessions": {
"type": "number"
},
"key_events": {
"type": "number"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"gsc": {
"type": "object",
"required": [
"connected",
"available",
"site_url",
"clicks",
"impressions",
"ctr",
"position",
"daily",
"queries",
"pages"
],
"properties": {
"ctr": {
"type": "object",
"required": [
"current",
"previous",
"change_pct"
],
"properties": {
"current": {
"type": "number"
},
"previous": {
"type": "number"
},
"change_pct": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
},
"daily": {
"type": "array",
"items": {
"type": "object",
"required": [
"date",
"clicks",
"impressions"
],
"properties": {
"date": {
"type": "string"
},
"clicks": {
"type": "number"
},
"impressions": {
"type": "number"
}
},
"additionalProperties": false
}
},
"pages": {
"type": "array",
"items": {
"type": "object",
"required": [
"clicks",
"impressions",
"ctr",
"position",
"previous_clicks",
"url"
],
"properties": {
"ctr": {
"type": "number"
},
"url": {
"type": "string"
},
"clicks": {
"type": "number"
},
"position": {
"type": "number"
},
"impressions": {
"type": "number"
},
"previous_clicks": {
"type": "number"
}
},
"additionalProperties": false
}
},
"clicks": {
"type": "object",
"required": [
"current",
"previous",
"change_pct"
],
"properties": {
"current": {
"type": "number"
},
"previous": {
"type": "number"
},
"change_pct": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
},
"queries": {
"type": "array",
"items": {
"type": "object",
"required": [
"clicks",
"impressions",
"ctr",
"position",
"previous_clicks",
"query"
],
"properties": {
"ctr": {
"type": "number"
},
"query": {
"type": "string"
},
"clicks": {
"type": "number"
},
"position": {
"type": "number"
},
"impressions": {
"type": "number"
},
"previous_clicks": {
"type": "number"
}
},
"additionalProperties": false
}
},
"position": {
"type": "object",
"required": [
"current",
"previous",
"change_pct"
],
"properties": {
"current": {
"type": "number"
},
"previous": {
"type": "number"
},
"change_pct": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
},
"site_url": {
"type": [
"string",
"null"
]
},
"available": {
"type": "boolean"
},
"connected": {
"type": "boolean"
},
"impressions": {
"type": "object",
"required": [
"current",
"previous",
"change_pct"
],
"properties": {
"current": {
"type": "number"
},
"previous": {
"type": "number"
},
"change_pct": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"period": {
"type": "object",
"required": [
"start_date",
"end_date",
"previous_start_date",
"previous_end_date"
],
"properties": {
"end_date": {
"type": "string"
},
"start_date": {
"type": "string"
},
"previous_end_date": {
"type": "string"
},
"previous_start_date": {
"type": "string"
}
},
"additionalProperties": false
},
"cited_pages": {
"type": "object",
"required": [
"available",
"pages"
],
"properties": {
"pages": {
"type": "array",
"items": {
"type": "object",
"required": [
"url",
"citations",
"prompts",
"ai_sessions",
"clicks",
"impressions",
"position"
],
"properties": {
"url": {
"type": "string"
},
"clicks": {
"type": [
"number",
"null"
]
},
"prompts": {
"type": "number"
},
"position": {
"type": [
"number",
"null"
]
},
"citations": {
"type": "number"
},
"ai_sessions": {
"type": [
"number",
"null"
]
},
"impressions": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
}
},
"available": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get site health analytics",
"readOnlyHint": true,
"openWorldHint": true,
"destructiveHint": false
}
}Page through every page one Site Health issue affects, 50 per page, open pages first and most recently seen first within a status. Give the check from the issue list; filter by status; page is 0-based and has_more says whether to continue; page 0 starts from the first affected page, so it repeats the sample pages the issue list showed inline. page_id returns that one page's row for the check. Each row carries the finding_id and task_revision an update of the page's task needs, the finding's detail, recommendation and evidence, the assignee, and the dates it was first and last seen and last checked. Requires Site Health on the website's plan; otherwise the call fails with 403.
| Parameter | Type | Description |
|---|---|---|
| page | integer | Zero-based page of 50 affected pages. |
| check * | string | The check id of the issue, from the issue list. |
| status | string | Only pages in this status. |
| page_id | string | Only this page's row for the check, wherever it sits. |
| website_id * | string |
{
"name": "get_site_health_issue_pages",
"description": "Page through every page one Site Health issue affects, 50 per page, open pages first and most recently seen first within a status. Give the check from the issue list; filter by status; page is 0-based and has_more says whether to continue; page 0 starts from the first affected page, so it repeats the sample pages the issue list showed inline. page_id returns that one page's row for the check. Each row carries the finding_id and task_revision an update of the page's task needs, the finding's detail, recommendation and evidence, the assignee, and the dates it was first and last seen and last checked. Requires Site Health on the website's plan; otherwise the call fails with 403.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"check"
],
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Zero-based page of 50 affected pages."
},
"check": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "The check id of the issue, from the issue list."
},
"status": {
"enum": [
"open",
"in_progress",
"fixed",
"verified",
"dismissed"
],
"type": "string",
"description": "Only pages in this status."
},
"page_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "Only this page's row for the check, wherever it sits."
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"pages": {
"type": "array",
"items": {
"type": "object",
"required": [
"finding_id",
"page_id",
"property_id",
"url",
"status",
"page_title",
"detail",
"recommendation",
"shared_value",
"evidence",
"evidence_links",
"robots_txt_rule",
"first_seen_at",
"last_seen_at",
"resolved_at",
"last_checked_at",
"assignee",
"task_revision",
"draft"
],
"properties": {
"url": {
"type": "string"
},
"draft": {
"anyOf": [
{
"type": "object",
"required": [
"run_id",
"status"
],
"properties": {
"run_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"status": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"detail": {
"type": "string"
},
"status": {
"enum": [
"open",
"in_progress",
"fixed",
"verified",
"dismissed"
],
"type": "string"
},
"page_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"assignee": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"evidence": {
"type": "array",
"items": {
"type": "string"
}
},
"finding_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"page_title": {
"type": [
"string",
"null"
]
},
"property_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"resolved_at": {
"type": [
"string",
"null"
]
},
"last_seen_at": {
"type": "string"
},
"shared_value": {
"type": [
"string",
"null"
]
},
"first_seen_at": {
"type": "string"
},
"task_revision": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"evidence_links": {
"type": "array",
"items": {
"type": "object",
"required": [
"label",
"url"
],
"properties": {
"url": {
"type": "string"
},
"label": {
"type": "string"
}
},
"additionalProperties": false
}
},
"recommendation": {
"type": [
"string",
"null"
]
},
"last_checked_at": {
"type": [
"string",
"null"
]
},
"robots_txt_rule": {
"anyOf": [
{
"type": "object",
"required": [
"url",
"line",
"excerpt"
],
"properties": {
"url": {
"type": "string"
},
"line": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
"excerpt": {
"type": "array",
"items": {
"type": "object",
"required": [
"line",
"text"
],
"properties": {
"line": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
"text": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
},
"has_more": {
"type": "boolean"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get site health issue pages",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}List a website's Site Health issues: one group per kind of problem (check) with its title, why it matters, severity (critical, warning, opportunity), priority (high, medium, low), owner (writer, developer or either; null when unknown), effort (minutes, hours, days), whether it is site-wide, counts of affected pages by status (open, in_progress, fixed, verified, dismissed), up to three sections it concentrates in, and sample affected pages with each page's detail, recommendation, evidence, assignee and task_revision. Filter by status, check, a search term, the stored URLs of specific pages (page_urls), or assignee "me" (signed-in connections only). Groups are paged: page is 0-based, page_size defaults to 25 (max 200) and total counts the groups that match; counts totals pages by status across the whole site, ignoring the status filter. A group carries at most 50 sample pages (10 when a tool calls it, which also caps page_size at 25); has_more_pages says to read the rest with the issue pages read (get_site_health_issue_pages or POST /v1/seo/issues/pages), whose page 0 repeats the sample pages. has_evidence false means the site has never been crawled or audited. Requires Site Health on the website's plan; otherwise the call fails with 403.
| Parameter | Type | Description |
|---|---|---|
| page | integer | Zero-based page of groups. |
| check | string | One check id, as `check` names it in an earlier result. |
| search | string | Matches the issue title or an affected page URL. |
| status | string | Only groups with at least one page in this status. Group and site counts ignore it. |
| assignee | string | Only pages assigned to the signed-in user. Not available to API keys. |
| page_size | integer |
Read one audited page of a Site Health property: what the last audit measured (title, meta description, canonical URL, HTTP status code, word count, whether it is indexable, how the server HTML and the rendered page differ, PageSpeed with performance_score 0 to 100, largest_contentful_paint_ms and interaction_to_next_paint_ms in milliseconds and cumulative_layout_shift unitless, and the hreflang audit), the status of every audit of the page, and every finding on it with its check, detail, recommendation, evidence, severity, priority_score, when it was resolved, and verification: whether the last audit of that check passed, failed or left it unverified, with the reason. page_id comes from get_site_health_pages or from an issue's affected pages. Requires Site Health on the website's plan; otherwise the call fails with 403.
| Parameter | Type | Description |
|---|---|---|
| page_id * | string | The page, from the inventory or an issue's affected pages. |
| website_id * | string |
{
"name": "get_site_health_page",
"description": "Read one audited page of a Site Health property: what the last audit measured (title, meta description, canonical URL, HTTP status code, word count, whether it is indexable, how the server HTML and the rendered page differ, PageSpeed with performance_score 0 to 100, largest_contentful_paint_ms and interaction_to_next_paint_ms in milliseconds and cumulative_layout_shift unitless, and the hreflang audit), the status of every audit of the page, and every finding on it with its check, detail, recommendation, evidence, severity, priority_score, when it was resolved, and verification: whether the last audit of that check passed, failed or left it unverified, with the reason. page_id comes from get_site_health_pages or from an issue's affected pages. Requires Site Health on the website's plan; otherwise the call fails with 403.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"page_id"
],
"properties": {
"page_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "The page, from the inventory or an issue's affected pages."
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"id": {
"type": "string"
},
"url": {
"type": "string"
},
"history": {
"type": "array",
"items": {
"type": "object",
"required": [
"status",
"audited_at"
],
"properties": {
"status": {
"type": "string"
},
"audited_at": {
"type": "string"
}
},
"additionalProperties": false
}
},
"findings": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"check",
"detail",
"severity",
"priority_score",
"recommendation",
"evidence",
"resolved_at",
"verification"
],
"properties": {
"id": {
"type": "string"
},
"check": {
"type": "string"
},
"detail": {
"type": "string"
},
"evidence": {
"type": "array",
"items": {
"type": "string"
}
},
"severity": {
"type": "string"
},
"resolved_at": {
"type": [
"string",
"null"
]
},
"presentation": {
"type": "object",
"required": [
"source"
],
"properties": {
"title": {
"type": "object",
"required": [
"messages"
],
"properties": {
"date": {
"type": "object",
"required": [
"kind",
"iso"
],
"properties": {
"iso": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"kind": {
"type": "string",
"const": "dormant-lastmod"
}
},
"additionalProperties": false
},
"messages": {
"type": "array",
"items": {
"type": "string"
}
},
"canonical": {
"type": "string"
}
},
"additionalProperties": false
},
"source": {
"type": "string",
"const": "technical-findings-v1"
},
"description": {
"type": "object",
"required": [
"messages"
],
"properties": {
"date": {
"type": "object",
"required": [
"kind",
"iso"
],
"properties": {
"iso": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"kind": {
"type": "string",
"const": "dormant-lastmod"
}
},
"additionalProperties": false
},
"messages": {
"type": "array",
"items": {
"type": "string"
}
},
"canonical": {
"type": "string"
}
},
"additionalProperties": false
},
"recommendation": {
"type": "object",
"required": [
"messages"
],
"properties": {
"date": {
"type": "object",
"required": [
"kind",
"iso"
],
"properties": {
"iso": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"kind": {
"type": "string",
"const": "dormant-lastmod"
}
},
"additionalProperties": false
},
"messages": {
"type": "array",
"items": {
"type": "string"
}
},
"canonical": {
"type": "string"
}
},
"additionalProperties": false
},
"priority_reasons": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"required": [
"messages"
],
"properties": {
"date": {
"type": "object",
"required": [
"kind",
"iso"
],
"properties": {
"iso": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"kind": {
"type": "string",
"const": "dormant-lastmod"
}
},
"additionalProperties": false
},
"messages": {
"type": "array",
"items": {
"type": "string"
}
},
"canonical": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
}
}
},
"additionalProperties": false
},
"verification": {
"type": "object",
"required": [
"status",
"reason",
"audited_at",
"run_id",
"content_digest"
],
"properties": {
"reason": {
"type": "string"
},
"run_id": {
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"passed",
"failed",
"unverified"
],
"type": "string"
},
"audited_at": {
"type": [
"string",
"null"
]
},
"content_digest": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"priority_score": {
"type": [
"number",
"null"
]
},
"recommendation": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
},
"measurement": {
"anyOf": [
{
"type": "object",
"required": [
"title",
"meta_description",
"canonical_url",
"status_code",
"word_count",
"indexable"
],
"properties": {
"title": {
"type": [
"string",
"null"
]
},
"indexable": {
"type": "boolean"
},
"rendering": {
"type": "object",
"required": [
"status",
"source",
"captured_at",
"server",
"rendered",
"differences",
"reason"
],
"properties": {
"reason": {
"type": [
"string",
"null"
]
},
"server": {
"type": "object",
"required": [
"word_count",
"digest",
"excerpt",
"title",
"h1",
"schema_types"
],
"properties": {
"h1": {
"type": [
"string",
"null"
]
},
"title": {
"type": [
"string",
"null"
]
},
"digest": {
"type": "string"
},
"excerpt": {
"type": "string"
},
"word_count": {
"type": "number"
},
"schema_types": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"source": {
"type": "string",
"const": "Jina rendered HTML"
},
"status": {
"enum": [
"complete",
"unavailable",
"not_sampled"
],
"type": "string"
},
"rendered": {
"anyOf": [
{
"type": "object",
"required": [
"word_count",
"digest",
"excerpt",
"title",
"h1",
"schema_types"
],
"properties": {
"h1": {
"type": [
"string",
"null"
]
},
"title": {
"type": [
"string",
"null"
]
},
"digest": {
"type": "string"
},
"excerpt": {
"type": "string"
},
"word_count": {
"type": "number"
},
"schema_types": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"captured_at": {
"type": "string"
},
"differences": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"experience": {
"type": "object",
"required": [
"status",
"performance_score",
"largest_contentful_paint_ms",
"interaction_to_next_paint_ms",
"cumulative_layout_shift"
],
"properties": {
"status": {
"type": "string"
},
"measured_at": {
"type": [
"string",
"null"
]
},
"field_data_scope": {
"anyOf": [
{
"enum": [
"url",
"origin"
],
"type": "string"
},
{
"type": "null"
}
]
},
"performance_score": {
"type": [
"number",
"null"
]
},
"cumulative_layout_shift": {
"type": [
"number",
"null"
]
},
"largest_contentful_paint_ms": {
"type": [
"number",
"null"
]
},
"interaction_to_next_paint_ms": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
},
"word_count": {
"type": "number"
},
"status_code": {
"type": "number"
},
"canonical_url": {
"type": [
"string",
"null"
]
},
"hreflang_audit": {
"type": "object",
"required": [
"pages_with_annotations",
"annotations_checked",
"issues"
],
"properties": {
"issues": {
"type": "array",
"items": {
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
}
},
"additionalProperties": false
}
},
"annotations_checked": {
"type": "number"
},
"pages_with_annotations": {
"type": "number"
}
},
"additionalProperties": false
},
"meta_description": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"property_id": {
"type": "string"
},
"last_audited_at": {
"type": [
"string",
"null"
]
},
"last_audit_status": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get site health page",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}Browse the pages of one Site Health property, 50 per page (page is 1-based) sorted by URL, each with its last audit status and time, its count of open findings and whether it is a priority page (cited by AI answers or a top Google page, so audits read it first). Narrow by check (pages with an open finding of it), one URL, or a search term; total counts the pages that match. groups lists every check with an open finding on the property and its page count, ignoring the filters, highest priority first. Page ids feed get_site_health_page and start_site_health_audit. Requires Site Health on the website's plan; otherwise the call fails with 403.
| Parameter | Type | Description |
|---|---|---|
| url | string | Only the page at this URL. |
| page | integer | One-based page of 50 pages, sorted by URL. |
| check | string | Only pages with an open finding of this check. |
| search | string | Only pages whose URL contains this text. |
| website_id * | string | |
| property_id * | string | The property to browse, from the properties list. |
{
"name": "get_site_health_pages",
"description": "Browse the pages of one Site Health property, 50 per page (page is 1-based) sorted by URL, each with its last audit status and time, its count of open findings and whether it is a priority page (cited by AI answers or a top Google page, so audits read it first). Narrow by check (pages with an open finding of it), one URL, or a search term; total counts the pages that match. groups lists every check with an open finding on the property and its page count, ignoring the filters, highest priority first. Page ids feed get_site_health_page and start_site_health_audit. Requires Site Health on the website's plan; otherwise the call fails with 403.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"property_id"
],
"properties": {
"url": {
"type": "string",
"maxLength": 2048,
"minLength": 1,
"description": "Only the page at this URL."
},
"page": {
"type": "integer",
"maximum": 100000,
"minimum": 1,
"description": "One-based page of 50 pages, sorted by URL."
},
"check": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Only pages with an open finding of this check."
},
"search": {
"type": "string",
"maxLength": 500,
"description": "Only pages whose URL contains this text."
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"property_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "The property to browse, from the properties list."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"page": {
"type": "number"
},
"pages": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"url",
"path",
"last_audit_status",
"last_audited_at",
"open_findings",
"is_priority"
],
"properties": {
"id": {
"type": "string"
},
"url": {
"type": "string"
},
"path": {
"type": "string"
},
"is_priority": {
"type": "boolean"
},
"open_findings": {
"type": "number"
},
"last_audited_at": {
"type": [
"string",
"null"
]
},
"last_audit_status": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
},
"total": {
"type": "number"
},
"groups": {
"type": "array",
"items": {
"type": "object",
"required": [
"check",
"count",
"priority"
],
"properties": {
"check": {
"type": "string"
},
"count": {
"type": "number"
},
"priority": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
}
},
"page_size": {
"type": "number"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get site health pages",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}List a website's Site Health properties, the crawl scopes Site Health audits: root URL, included and excluded path prefixes, subdomains, sitemaps, page ceiling (max_pages), whether the property is enabled, the live page count, and the latest crawl or audit run with its status, trigger, counts and timestamps. Use it for the property_id that get_site_health_pages and start_site_health_audit take, and to see whether a run is in progress before starting another. Requires Site Health on the website's plan; otherwise the call fails with 403.
| Parameter | Type | Description |
|---|---|---|
| website_id * | string |
{
"name": "get_site_health_properties",
"description": "List a website's Site Health properties, the crawl scopes Site Health audits: root URL, included and excluded path prefixes, subdomains, sitemaps, page ceiling (max_pages), whether the property is enabled, the live page count, and the latest crawl or audit run with its status, trigger, counts and timestamps. Use it for the property_id that get_site_health_pages and start_site_health_audit take, and to see whether a run is in progress before starting another. Requires Site Health on the website's plan; otherwise the call fails with 403.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id"
],
"properties": {
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"properties": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"website_id",
"name",
"root_url",
"include_prefixes",
"exclude_prefixes",
"include_subdomains",
"include_all_subdomains",
"include_sitemaps",
"is_enabled",
"max_pages",
"crawl_delay_ms",
"live_pages",
"latest_run"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"root_url": {
"type": "string"
},
"max_pages": {
"type": "number"
},
"is_enabled": {
"type": "boolean"
},
"latest_run": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"status",
"trigger",
"started_at",
"completed_at",
"discovered_count",
"scanned_count",
"skipped_count",
"blocked_count",
"failed_count",
"error"
],
"properties": {
"id": {
"type": "string"
},
"kind": {
"type": "string"
},
"error": {
"type": [
"string",
"null"
]
},
"sample": {
"type": "boolean"
},
"status": {
"type": "string"
},
"trigger": {
"type": "string"
},
"started_at": {
"type": "string"
},
"audit_after": {
"type": "boolean"
},
"completed_at": {
"type": [
"string",
"null"
]
},
"failed_count": {
"type": "number"
},
"audit_pending": {
"type": "boolean"
},
"blocked_count": {
"type": "number"
},
"scanned_count": {
"type": "number"
},
"skipped_count": {
"type": "number"
},
"discovered_count": {
"type": "number"
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"live_pages": {
"type": "number"
},
"website_id": {
"type": "string"
},
"crawl_delay_ms": {
"type": "number"
},
"exclude_prefixes": {
"type": "array",
"items": {
"type": "string"
}
},
"include_prefixes": {
"type": "array",
"items": {
"type": "string"
}
},
"include_sitemaps": {
"type": "array",
"items": {
"type": "string"
}
},
"include_subdomains": {
"type": "array",
"items": {
"type": "string"
}
},
"include_all_subdomains": {
"type": "boolean"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get site health properties",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}Read saved Outreach contacts: cited pages with their status, author, email and where the email came from, LinkedIn, contact page, and pitch draft. Only pages someone has triaged, enriched or drafted are listed; find other cited pages with the source-page analytics tools. Newest first; use offset for the next page. Read-only.
| Parameter | Type | Description |
|---|---|---|
| url | string | Return only this page's contact. Omit to list all. |
| limit | integer | Contacts per page: 1 through 50, default 20. |
| offset | integer | |
| statuses | array | Only contacts in these statuses. Omit for all. |
| website_id * | string |
{
"name": "list_outreach_contacts",
"description": "Read saved Outreach contacts: cited pages with their status, author, email and where the email came from, LinkedIn, contact page, and pitch draft. Only pages someone has triaged, enriched or drafted are listed; find other cited pages with the source-page analytics tools. Newest first; use offset for the next page. Read-only.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id"
],
"properties": {
"url": {
"type": "string",
"maxLength": 2048,
"minLength": 1,
"description": "Return only this page's contact. Omit to list all."
},
"limit": {
"type": "integer",
"maximum": 50,
"minimum": 1,
"description": "Contacts per page: 1 through 50, default 20."
},
"offset": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"statuses": {
"type": "array",
"items": {
"enum": [
"New",
"Todo",
"In Progress",
"Done",
"Rejected"
],
"type": "string",
"description": "Pipeline status. \"New\" means untriaged; \"Rejected\" removes the page from the active queue."
},
"description": "Only contacts in these statuses. Omit for all."
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"total": {
"type": "number"
},
"contacts": {
"type": "array",
"items": {
"type": "object",
"required": [
"url",
"status",
"author_name",
"email",
"email_source",
"page_emails",
"contact_page_url",
"linkedin",
"subject",
"message",
"assignee_email",
"created_at"
],
"properties": {
"url": {
"type": "string"
},
"email": {
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"New",
"Todo",
"In Progress",
"Done",
"Rejected"
],
"type": "string"
},
"message": {
"type": [
"string",
"null"
]
},
"subject": {
"type": [
"string",
"null"
]
},
"linkedin": {
"type": [
"string",
"null"
]
},
"created_at": {
"type": "string"
},
"author_name": {
"type": [
"string",
"null"
]
},
"page_emails": {
"type": "array",
"items": {
"type": "string"
},
"description": "Up to five addresses the page or its linked contact page publishes, the chosen one first. Not a complete inventory."
},
"email_source": {
"anyOf": [
{
"enum": [
"page_author",
"page_contact",
"hunter",
"manual"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "Where the email came from: page_author (published on the page and matches the author), page_contact (the site's own address, may not reach the author), hunter (Hunter.io match, not published on the page, check before sending), manual (entered by a person). Null when unknown."
},
"assignee_email": {
"type": [
"string",
"null"
]
},
"contact_page_url": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
},
"has_more": {
"type": "boolean"
}
},
"additionalProperties": false
},
"annotations": {
"title": "List Outreach contacts",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}Merge 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. Unlike the other Knowledge Base writes, retries are strict: missing source ids are rejected rather than skipped, so re-read the pillars before retrying a failed merge.
| Parameter | Type | Description |
|---|---|---|
| website_id * | string | |
| target_pillar_id * | string | |
| source_pillar_ids * | array |
{
"name": "merge_pillars",
"description": "Merge 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. Unlike the other Knowledge Base writes, retries are strict: missing source ids are rejected rather than skipped, so re-read the pillars before retrying a failed merge.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"target_pillar_id",
"source_pillar_ids"
],
"properties": {
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"target_pillar_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"source_pillar_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"pillar": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"additionalProperties": false
},
"success": {
"type": "boolean",
"const": true
},
"merged_pillars": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"additionalProperties": false
}
},
"moved_fact_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
}
},
"additionalProperties": false
},
"annotations": {
"title": "Merge pillars",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": true
}
}File 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. Missing ids are reported in not_found_ids rather than failing the call, so retries are idempotent.
| Parameter | Type | Description |
|---|---|---|
| fact_ids * | array | |
| pillar_id * | string | |
| website_id * | string |
{
"name": "move_brand_facts",
"description": "File 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. Missing ids are reported in not_found_ids rather than failing the call, so retries are idempotent.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"pillar_id",
"fact_ids"
],
"properties": {
"fact_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"pillar_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"pillar": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"additionalProperties": false
},
"success": {
"type": "boolean",
"const": true
},
"moved_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"not_found_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"unchanged_ids": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Move brand facts",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
}
}Move one or more content items to a different Content Hub sheet, or back to the shared pool. Sheet assignment is organizational metadata only: a move never changes an item's stage, brief, body, versions, URL, or metrics, and the item stays fully readable and revisable. targetSheetId must be a "sheet"-type tab from the Content Hub sheets list — view-type tabs (e.g. All content) are computed filters, not assignable; pass null to unassign back to the shared pool they display. Batch is all-or-nothing: if any contentIds entry does not belong to the website, nothing moves. Custom-column values follow each item when the target has a matching column (same name and type; missing columns are auto-created); values whose column conflicts by type are dropped, and multi-select selections whose option is missing on the matched target column are removed — both counts are reported. Each moved item is returned with its previous and new sheet id so no follow-up read is needed.
| Parameter | Type | Description |
|---|---|---|
| website_id * | string | |
| content_ids * | array | |
| target_sheet_id * | any |
{
"name": "move_content",
"description": "Move one or more content items to a different Content Hub sheet, or back to the shared pool. Sheet assignment is organizational metadata only: a move never changes an item's stage, brief, body, versions, URL, or metrics, and the item stays fully readable and revisable. targetSheetId must be a \"sheet\"-type tab from the Content Hub sheets list — view-type tabs (e.g. All content) are computed filters, not assignable; pass null to unassign back to the shared pool they display. Batch is all-or-nothing: if any contentIds entry does not belong to the website, nothing moves. Custom-column values follow each item when the target has a matching column (same name and type; missing columns are auto-created); values whose column conflicts by type are dropped, and multi-select selections whose option is missing on the matched target column are removed — both counts are reported. Each moved item is returned with its previous and new sheet id so no follow-up read is needed.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"content_ids",
"target_sheet_id"
],
"properties": {
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"content_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"target_sheet_id": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"moved": {
"type": "array",
"items": {
"type": "object",
"required": [
"content_id",
"previous_sheet_id",
"sheet_id"
],
"properties": {
"sheet_id": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "null"
}
]
},
"content_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"previous_sheet_id": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
},
"cells_dropped": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"target_sheet_id": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "null"
}
]
},
"cells_transferred": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"target_sheet_name": {
"type": "string"
},
"option_values_dropped": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
}
},
"additionalProperties": false
},
"annotations": {
"title": "Move content",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": true
}
}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 (stage generated), with one exception: an optimize draft is created from a page that is already live and can be marked published while it waits at stage pending, as long as no Athena review is running on it. Briefs, still-generating or failed pieces, optimize drafts with a review in flight, and items with a scheduled CMS publish are rejected with the reason. Pass the exact public URL of the live page (a bare domain path like acme.com/blog/post is fine; the protocol is stripped on store). Calling it again on an already-published item (including external and imported pages, which are live by definition) updates the tracked URL only, keeping the original publish time. This is the only way to set a content URL over MCP; rename_content is deliberately title-only.
| Parameter | Type | Description |
|---|---|---|
| url * | string | |
| content_id * | string | |
| website_id * | string |
{
"name": "publish_content",
"description": "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 (stage generated), with one exception: an optimize draft is created from a page that is already live and can be marked published while it waits at stage pending, as long as no Athena review is running on it. Briefs, still-generating or failed pieces, optimize drafts with a review in flight, and items with a scheduled CMS publish are rejected with the reason. Pass the exact public URL of the live page (a bare domain path like acme.com/blog/post is fine; the protocol is stripped on store). Calling it again on an already-published item (including external and imported pages, which are live by definition) updates the tracked URL only, keeping the original publish time. This is the only way to set a content URL over MCP; rename_content is deliberately title-only.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"content_id",
"url"
],
"properties": {
"url": {
"type": "string",
"maxLength": 2048,
"minLength": 1
},
"content_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"url": {
"type": "string"
},
"title": {
"type": [
"string",
"null"
]
},
"content_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"published_at": {
"type": [
"string",
"null"
]
},
"already_published": {
"type": "boolean"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Mark content as published",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
}
}Stop tracking competitors on a website, 1 to 25 per call, by id from get_competitors, as the Competitors page's delete does. Returns one result per id, in order: removed, no_change (already removed), or not_found (not a competitor of this website). Past mentions and citations are kept, and a removed competitor can be restored on the Competitors page. Reanalyzing past responses happens only when someone runs the backfill on the Competitors page, which costs credits; this tool never starts it and costs no credits.
| Parameter | Type | Description |
|---|---|---|
| website_id * | string | |
| competitor_ids * | array | The competitors to stop tracking, by id from get_competitors. |
{
"name": "remove_competitors",
"description": "Stop tracking competitors on a website, 1 to 25 per call, by id from get_competitors, as the Competitors page's delete does. Returns one result per id, in order: removed, no_change (already removed), or not_found (not a competitor of this website). Past mentions and citations are kept, and a removed competitor can be restored on the Competitors page. Reanalyzing past responses happens only when someone runs the backfill on the Competitors page, which costs credits; this tool never starts it and costs no credits.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"competitor_ids"
],
"properties": {
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"competitor_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "The competitors to stop tracking, by id from get_competitors."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"competitor_id",
"status"
],
"properties": {
"name": {
"type": "string"
},
"status": {
"enum": [
"removed",
"no_change",
"not_found"
],
"type": "string"
},
"competitor_id": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Remove competitors",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": true
}
}Rename a content row's title. URL editing is not supported — URL is the content asset's stable identity and cannot be changed here.
| Parameter | Type | Description |
|---|---|---|
| title * | string | |
| content_id * | string | |
| website_id * | string |
{
"name": "rename_content",
"description": "Rename a content row's title. URL editing is not supported — URL is the content asset's stable identity and cannot be changed here.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"content_id",
"title"
],
"properties": {
"title": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"content_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"success": {
"type": "boolean",
"const": true
}
},
"additionalProperties": false
},
"annotations": {
"title": "Rename content",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
}
}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.
| Parameter | Type | Description |
|---|---|---|
| content_id * | string | |
| version_id * | string | |
| website_id * | string |
{
"name": "restore_content_version",
"description": "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.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"content_id",
"version_id"
],
"properties": {
"content_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"version_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"body": {
"type": "string"
},
"content_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"version_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"version_number": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"restored_from_version_number": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
}
},
"additionalProperties": false
},
"annotations": {
"title": "Restore content version",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
}
}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 calling it again, since each call starts from the current brief. Most useful while a piece waits at status generated_brief, where the brief still shapes what the article will say — call approve_brief once it reads right. It also works after the article exists, to correct the brief for a later regeneration; note that revising the brief does NOT rewrite an already-generated article, so use revise_content for that.
| Parameter | Type | Description |
|---|---|---|
| content_id * | string | |
| website_id * | string | |
| instruction * | string |
{
"name": "revise_brief",
"description": "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 calling it again, since each call starts from the current brief. Most useful while a piece waits at status generated_brief, where the brief still shapes what the article will say — call approve_brief once it reads right. It also works after the article exists, to correct the brief for a later regeneration; note that revising the brief does NOT rewrite an already-generated article, so use revise_content for that.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"content_id",
"instruction"
],
"properties": {
"content_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"instruction": {
"type": "string",
"maxLength": 5000,
"minLength": 1
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"brief": {
"type": "string"
},
"content_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"version_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"version_number": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
}
},
"additionalProperties": false
},
"annotations": {
"title": "Revise brief",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}
}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 replacement text, use edit_content instead. Applies the change to the whole article and records it as a new version, so earlier passes stay recoverable via get_content_versions / restore_content_version. Iterate by calling it again — each call starts from the current text, so no version id is needed. Use this instead of create_content to change a draft; it edits in place rather than generating a new piece. The returned body is always the complete replacement article, never just the edited passage; compare body_word_count with previous_body_word_count to confirm nothing unexpected was lost.
| Parameter | Type | Description |
|---|---|---|
| content_id * | string | |
| website_id * | string | |
| instruction * | string |
{
"name": "revise_content",
"description": "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 replacement text, use edit_content instead. Applies the change to the whole article and records it as a new version, so earlier passes stay recoverable via get_content_versions / restore_content_version. Iterate by calling it again — each call starts from the current text, so no version id is needed. Use this instead of create_content to change a draft; it edits in place rather than generating a new piece. The returned body is always the complete replacement article, never just the edited passage; compare body_word_count with previous_body_word_count to confirm nothing unexpected was lost.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"content_id",
"instruction"
],
"properties": {
"content_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"instruction": {
"type": "string",
"maxLength": 5000,
"minLength": 1
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"body": {
"type": "string"
},
"content_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"version_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"version_number": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"body_word_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"previous_body_word_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
}
},
"additionalProperties": false
},
"annotations": {
"title": "Revise content",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}
}Semantic search over a website's approved brand facts in the Knowledge Base. Reaches facts not filed under any pillar. Returns fact text with confidence, source URL and quote, and the published pillar it belongs to (null when unfiled).
| Parameter | Type | Description |
|---|---|---|
| query * | string | |
| top_k | string | |
| pillar_id | string | |
| website_id * | string |
{
"name": "search_brand_facts",
"description": "Semantic search over a website's approved brand facts in the Knowledge Base. Reaches facts not filed under any pillar. Returns fact text with confidence, source URL and quote, and the published pillar it belongs to (null when unfiled).",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"query"
],
"properties": {
"query": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"top_k": {
"type": "string",
"pattern": "^\\d+$"
},
"pillar_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"facts": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"text",
"confidence",
"source_url",
"source_quote",
"pillar"
],
"properties": {
"id": {
"type": "string"
},
"text": {
"type": "string"
},
"pillar": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"confidence": {
"anyOf": [
{
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
{
"type": "null"
}
]
},
"source_url": {
"type": [
"string",
"null"
]
},
"source_quote": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Search brand facts",
"readOnlyHint": true,
"openWorldHint": true,
"destructiveHint": false
}
}Move cited pages to an Outreach pipeline status (New, Todo, In Progress, Done, Rejected), as the Outreach inbox and board do. Each change to an existing contact is recorded in its activity history. Pages without a contact get one at the new status, starting with no activity entries; "New" only resets existing contacts and creates none. "Rejected" removes pages from the active queue; "New" returns them to untriaged. Up to 100 pages per call. Obtain user confirmation before calling.
| Parameter | Type | Description |
|---|---|---|
| urls * | array | |
| status * | string | Pipeline status. "New" means untriaged; "Rejected" removes the page from the active queue. |
| website_id * | string |
{
"name": "set_outreach_status",
"description": "Move cited pages to an Outreach pipeline status (New, Todo, In Progress, Done, Rejected), as the Outreach inbox and board do. Each change to an existing contact is recorded in its activity history. Pages without a contact get one at the new status, starting with no activity entries; \"New\" only resets existing contacts and creates none. \"Rejected\" removes pages from the active queue; \"New\" returns them to untriaged. Up to 100 pages per call. Obtain user confirmation before calling.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"urls",
"status"
],
"properties": {
"urls": {
"type": "array",
"items": {
"type": "string",
"maxLength": 2048,
"minLength": 1,
"description": "Cited page URL, e.g. \"example.com/blog/best-tools\". A contact already saved under this exact URL (for example one the Outreach page saved for a query variant its URL rules list separately) is used first. Otherwise protocol, \"www.\" and the query string (tracking parameters) are ignored, as on the Outreach page. The page is always read at the URL given."
}
},
"status": {
"enum": [
"New",
"Todo",
"In Progress",
"Done",
"Rejected"
],
"type": "string",
"description": "Pipeline status. \"New\" means untriaged; \"Rejected\" removes the page from the active queue."
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"updated": {
"type": "number"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Set Outreach status",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": true
}
}Replace all tag assignments on an existing prompt. For additions or removals, read the prompt's current tags with get_prompts, resolve tag IDs with get_prompt_tags, and pass the full resulting set. Existing assignments omitted from tag_ids are removed; an empty array clears all assignments. Tag definitions and the prompt itself are preserved.
| Parameter | Type | Description |
|---|---|---|
| tag_ids * | array | |
| prompt_id * | string | |
| website_id * | string |
{
"name": "set_prompt_tags",
"description": "Replace all tag assignments on an existing prompt. For additions or removals, read the prompt's current tags with get_prompts, resolve tag IDs with get_prompt_tags, and pass the full resulting set. Existing assignments omitted from tag_ids are removed; an empty array clears all assignments. Tag definitions and the prompt itself are preserved.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"prompt_id",
"tag_ids"
],
"properties": {
"tag_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"prompt_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"tag_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Set prompt tags",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": true
}
}Pause or unpause multiple prompts in one transaction
| Parameter | Type | Description |
|---|---|---|
| status * | string | one of ["active","paused"] |
| prompt_ids * | array | |
| website_id * | string |
{
"name": "set_prompts_status",
"description": "Pause or unpause multiple prompts in one transaction",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"prompt_ids",
"status"
],
"properties": {
"status": {
"enum": [
"active",
"paused"
],
"type": "string"
},
"prompt_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"message": {
"type": "string"
},
"success": {
"type": "boolean",
"const": true
},
"changed_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"unchanged_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
}
},
"additionalProperties": false
},
"annotations": {
"title": "Set prompts status",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
}
}Create a custom source tag with a name, URL patterns and optionally an icon and colour. Read the tag listing first: built-in tags already cover media, social, government, e-commerce, review sites, PR wires, academic and wiki sources, and a host they miss is better added to the built-in tag than given a new one. Obtain user confirmation before calling. MCP executes immediately after authorization; Athena AI chat presents an approval card. Patterns support hosts (example.com), subtrees (*.example.com), path sections (example.com/blog), exact pages (example.com/blog$) and query constraints. Up to 500 patterns. These are source tags, not prompt tags.
| Parameter | Type | Description |
|---|---|---|
| icon | string | Optional icon key from the curated set (for example newspaper, capsule, hospital, graduation-cap, building). Omit for a letter badge. |
| name * | string | Custom tag name. Names of built-in tags (Media, Social, Government, …) and of Owned and Competitor are reserved. |
| color | string | Optional colour family: ochre, clay, brick, amber, olive, moss, teal, slate, ink, mauve or plum. Default ink. |
| patterns * | array | |
| website_id * | string |
{
"name": "source_tags__create",
"description": "Create a custom source tag with a name, URL patterns and optionally an icon and colour. Read the tag listing first: built-in tags already cover media, social, government, e-commerce, review sites, PR wires, academic and wiki sources, and a host they miss is better added to the built-in tag than given a new one. Obtain user confirmation before calling. MCP executes immediately after authorization; Athena AI chat presents an approval card. Patterns support hosts (example.com), subtrees (*.example.com), path sections (example.com/blog), exact pages (example.com/blog$) and query constraints. Up to 500 patterns. These are source tags, not prompt tags.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"name",
"patterns"
],
"properties": {
"icon": {
"type": "string",
"maxLength": 64,
"description": "Optional icon key from the curated set (for example newspaper, capsule, hospital, graduation-cap, building). Omit for a letter badge."
},
"name": {
"type": "string",
"maxLength": 255,
"minLength": 1,
"description": "Custom tag name. Names of built-in tags (Media, Social, Government, …) and of Owned and Competitor are reserved."
},
"color": {
"type": "string",
"maxLength": 32,
"description": "Optional colour family: ochre, clay, brick, amber, olive, moss, teal, slate, ink, mauve or plum. Default ink."
},
"patterns": {
"type": "array",
"items": {
"type": "string",
"maxLength": 2048,
"minLength": 1,
"description": "Host (example.com), subtree (*.example.com), path section (example.com/blog), exact page (example.com/blog$) or query constraint (youtube.com/watch?v=abc)."
}
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"icon": {
"type": [
"string",
"null"
]
},
"kind": {
"enum": [
"entity",
"platform",
"custom"
],
"type": "string"
},
"name": {
"type": "string"
},
"color": {
"type": "string"
},
"editable": {
"type": "boolean"
},
"patterns": {
"type": "array",
"items": {
"type": "string"
}
},
"revision": {
"type": "string"
},
"deletable": {
"type": "boolean"
},
"removed_patterns": {
"type": "array",
"items": {
"type": "string"
}
},
"analytics_refreshed": {
"type": "boolean"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Source tags create",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
}
}Permanently delete a custom source tag and all its pattern assignments; retain source records. Built-in tags and Owned/Competitor cannot be deleted; remove patterns from a built-in tag instead. Read the listing first and pass the tag's revision as expected-revision. Obtain explicit user confirmation identifying the tag and its patterns before calling. MCP executes immediately after authorization; Athena AI chat presents an approval card. If the tag changed, read again. Never retry a declined proposal unless asked. A false analytics-refresh result means the tag was deleted but filtered analytics may still be cached.
| Parameter | Type | Description |
|---|---|---|
| tag_id * | string | Custom source tag ID returned by the source-tag listing tool. |
| website_id * | string | |
| expected_revision * | string | Revision returned by the source-tag listing tool for this tag. |
{
"name": "source_tags__delete",
"description": "Permanently delete a custom source tag and all its pattern assignments; retain source records. Built-in tags and Owned/Competitor cannot be deleted; remove patterns from a built-in tag instead. Read the listing first and pass the tag's revision as expected-revision. Obtain explicit user confirmation identifying the tag and its patterns before calling. MCP executes immediately after authorization; Athena AI chat presents an approval card. If the tag changed, read again. Never retry a declined proposal unless asked. A false analytics-refresh result means the tag was deleted but filtered analytics may still be cached.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"tag_id",
"expected_revision"
],
"properties": {
"tag_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "Custom source tag ID returned by the source-tag listing tool."
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"expected_revision": {
"type": "string",
"maxLength": 64,
"minLength": 64,
"description": "Revision returned by the source-tag listing tool for this tag."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"icon": {
"type": [
"string",
"null"
]
},
"kind": {
"enum": [
"entity",
"platform",
"custom"
],
"type": "string"
},
"name": {
"type": "string"
},
"color": {
"type": "string"
},
"editable": {
"type": "boolean"
},
"patterns": {
"type": "array",
"items": {
"type": "string"
}
},
"revision": {
"type": "string"
},
"deletable": {
"type": "boolean"
},
"removed_patterns": {
"type": "array",
"items": {
"type": "string"
}
},
"analytics_refreshed": {
"type": "boolean"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Source tags delete",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": true
}
}List cited domains by tag coverage, most cited first with citation counts: either the domains one custom source tag matches (tag ID), or, with untagged true, the domains no tag covers at all. Built-in tags (platform) and Owned/Competitor (entity) are refused as tag IDs: their membership is automatic and not listable; add or remove patterns on them instead. Start from untagged when asked which domains still need tags or which new tags to suggest.
| Parameter | Type | Description |
|---|---|---|
| days | integer | Look-back window in days, default 90. |
| limit | integer | |
| offset | integer | |
| tag_id | string | Custom tag ID from the listing tool. Built-in tags are refused. Omit and set untagged to list sources no tag covers. |
| untagged | boolean | true lists cited domains that carry no tag at all: not Owned, not Competitor, no built-in tag, no custom tag. Use this to find what still needs tagging; then propose adding hosts to a built-in tag or a new custom tag. |
| website_id * | string |
{
"name": "source_tags__get_sources",
"description": "List cited domains by tag coverage, most cited first with citation counts: either the domains one custom source tag matches (tag ID), or, with untagged true, the domains no tag covers at all. Built-in tags (platform) and Owned/Competitor (entity) are refused as tag IDs: their membership is automatic and not listable; add or remove patterns on them instead. Start from untagged when asked which domains still need tags or which new tags to suggest.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id"
],
"properties": {
"days": {
"type": "integer",
"maximum": 365,
"minimum": 1,
"description": "Look-back window in days, default 90."
},
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1
},
"offset": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"tag_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "Custom tag ID from the listing tool. Built-in tags are refused. Omit and set untagged to list sources no tag covers."
},
"untagged": {
"type": "boolean",
"description": "true lists cited domains that carry no tag at all: not Owned, not Competitor, no built-in tag, no custom tag. Use this to find what still needs tagging; then propose adding hosts to a built-in tag or a new custom tag."
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"total": {
"type": "number"
},
"sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"host",
"citations",
"citing_responses",
"citation_percentage"
],
"properties": {
"host": {
"type": "string"
},
"citations": {
"type": "number"
},
"citing_responses": {
"type": "number"
},
"citation_percentage": {
"type": "number"
}
},
"additionalProperties": false
}
},
"has_more": {
"type": "boolean"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Source tags get sources",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}Read every source tag this website sees: Owned and Competitor (entity), the built-in classes AthenaHQ classifies automatically (platform: Media, Social, Government, E-Commerce, Review sites, PR Wire, Academic and research, Wiki) and the website's custom tags. Built-in tags list only what this website added or removed, never the platform's own patterns; custom tags list their patterns. Read this before proposing, creating, editing or deleting tags, and prefer adding hosts to a built-in tag over creating a near-duplicate. To find sources no tag covers, call source_tags__get_sources with untagged true. The Source Tag filter also takes two values that are not tags and are not listed here: 'other' (sources the Tags column badges Other) and 'untagged' (sources with no tag). Filter by name substring or tag ID; page tags with offset, page one tag's patterns with tag ID and pattern offset.
| Parameter | Type | Description |
|---|---|---|
| limit | integer | Tags per page: 1 through 50, default 20. Use offset for the next page. |
| query | string | Optional tag-name substring. Omit to list all names. |
| offset | integer | |
| tag_id | string | Actual UUID returned by this tool. Omit to list all tags; never use a placeholder. |
| website_id * | string | |
| pattern_limit | integer | Patterns per tag: 1 through 500, default 50. |
| pattern_offset | integer |
Edit a source tag. Custom tag: rename, add patterns, remove exact patterns from the listing. Built-in tag (platform): add patterns to this website's copy so they carry the tag here, or remove patterns so they stop carrying it here; a removal is accepted only for a pattern the tag currently applies to (by a platform rule, by automatic classification, or by your own addition), and an addition is accepted only when the pattern does not already carry the tag. Owned and Competitor cannot be edited here; their patterns live in Brand Profile and Competitors. Read the listing first and pass the tag's revision as expected-revision. Obtain explicit user confirmation of the exact changes before calling; MCP executes immediately after authorization; Athena AI chat presents an approval card. If the tag changed, read again. Never retry a declined proposal unless asked. Up to 500 additions and 500 removals. A false analytics-refresh result means the edit saved but filtered analytics may still be cached.
| Parameter | Type | Description |
|---|---|---|
| name | string | Custom tag name. Names of built-in tags (Media, Social, Government, …) and of Owned and Competitor are reserved. |
| tag_id * | string | |
| website_id * | string | |
| add_patterns | array | |
| remove_patterns | array | |
| expected_revision * | string |
Start a Discover study to find evidence-grounded, untracked prompt opportunities for a website. Invoke after explicit user intent to start research and review the sources, country, language, requested prompt count and custom instructions with the user. This launches asynchronous external research and model calls; the prompt count is a target, not a guaranteed yield. Sources: website_analysis (website), social (market discussions), search_console (connected Search Console), keyword_gaps (plan-gated keyword opportunities), competitive_landscape (plan-gated category questions and comparisons researched from the website's tracked competitors; requires at least one tracked competitor), brand_guidelines (requires custom instructions). Returns the run ID and version when startup succeeds. Prompts are not automatically added to tracking. Poll the discovery history/progress tool with the returned run ID; do not start another study to check status. Requires prompt-management permission and source entitlements. Candidate results can be reviewed in the application's Discover page.
| Parameter | Type | Description |
|---|---|---|
| name * | string | |
| country | string | Country name or ISO code; defaults to United States. |
| sources * | array | |
| language | string | Supported locale, for example en-US. Defaults to en-US. |
| website_id * | string | |
| prompt_count_range | object | Supported min/max targets: 25/50 (default), 50/75, 75/100, 100/150, or 150/200. |
| custom_instructions |
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_response_streaming_status over MCP or GET /api/v1/response-streaming/status over the API for progress.
| Parameter | Type | Description |
|---|---|---|
| prompt_ids | array | Specific tracked prompt UUIDs to run, from 1 to 1,000. Overrides schedule prompt selectors when supplied. Omit to use schedule_id selectors, or every active prompt when schedule_id is also omitted. Paused prompts are skipped. |
| website_id * | string | |
| schedule_id | string | Schedule UUID to attribute this run to and take prompt selectors from. A nonempty prompt_ids selection overrides those selectors. Omit to attribute the run to Default and run every active prompt unless prompt_ids is supplied. Explicit model, fan-out, persona and location choices apply to this run. |
| use_personas | boolean | |
| use_locations | boolean | |
| only_locations | boolean | |
| selected_models | object | Map of model id to enabled flag, e.g. { "chatgpt": true, "ai_overview": true, "ai_mode": false }. Model ids: chatgpt, ai_overview (Google AI Overviews; google_ai_overview is also accepted), perplexity, gemini, copilot, ai_mode, grok, claude, deepseek, meta_ai, mistral. An id set to true that names n… |
Start a Site Health audit of one property. mode full (the default) crawls the property, then audits every page the crawl leaves; a crawl already running is joined and audits when it ends. mode sample audits a few pages from every section plus the priority pages; page_ids (1 to 100) re-audits only those pages, which is how a fix is checked. Refused with 400 when the property is disabled. mode full is refused with 409 when a full audit already covers the property or a sample or page_ids audit holds it (try again once that ends). mode sample and page_ids are refused with 409 while any crawl or audit of the property runs, with 400 when the property has no pages yet, and with 404 when a page id is not in the current inventory. Returns the run id (null while a crawl runs first, since its audit run is created when the crawl ends), the property name, how many pages the run reads (in mode full, the inventory before the crawl), whether it is a sample and whether a crawl runs first. Results reach the issue list as the run progresses; the properties list shows the run's status. Requires Site Health on the website's plan; otherwise the call fails with 403.
| Parameter | Type | Description |
|---|---|---|
| mode | string | full crawls the property first and audits every page it leaves; sample audits a few pages per section plus the priority pages. |
| page_ids | array | Re-audit only these pages (1 to 100), from the inventory or an issue's affected pages. Overrides mode. |
| website_id * | string | |
| property_id * | string | The property to audit, from the properties list. |
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 pages cited in the website's monitored AI responses accrue metrics with no publish step (use it for guest posts, partner placements, or any page Athena did not generate). Idempotent per URL: a URL already present on the website (any content type) is not duplicated; the response lists it under skipped with the existing content_id and type. Check that type before chaining destructive calls (a skip can resolve to first-party generated content that shares the URL). Rows are created without page text, which citation tracking does not need; the body can be filled from the app later. Duplicate URLs within one call (including tracking-param variants of the same page) collapse to one row, first occurrence wins. Optional sheet_id files rows under a Content Hub tab; view-type tabs resolve to the main pool (null), echoed per row. Optional per-URL fields set the customer's own Content Hub columns on the created row, addressed by column name as shown on the destination tab (text, number, date, checkbox, link, and multi-select columns; unknown multi-select options are created). An unknown column name or a value that does not fit the column type rejects the whole call and nothing is tracked; skipped URLs keep their existing values. If the user names a destination tab, resolve its id with get_content_hub_sheets before tracking. Omitting sheet_id uses the shared pool, not the user's currently open tab. After the call, report created_count and skipped_count separately, name the returned destination_name, and share content_hub_url so the user can open each item. Skipped rows keep their existing tab: use their returned destination and never describe them as newly added or moved.
| Parameter | Type | Description |
|---|---|---|
| urls * | array | |
| sheet_id | any | |
| website_id * | string |
Update one brand fact's text, source URL, or confidence in the Knowledge Base. Only provided fields change; pass source_url: "" to clear the source. Changing the text creates a new fact (new id) and archives the current one; the new fact keeps the current review status and the response carries it. Source URL and confidence edits update the fact in place. Duplicates across other facts are not rejected here (Knowledge Base dedup owns those). Does not change review status.
| Parameter | Type | Description |
|---|---|---|
| text | string | |
| fact_id * | string | |
| confidence | string | one of ["high","medium","low"] |
| source_url | string | |
| website_id * | string |
{
"name": "update_brand_fact",
"description": "Update one brand fact's text, source URL, or confidence in the Knowledge Base. Only provided fields change; pass source_url: \"\" to clear the source. Changing the text creates a new fact (new id) and archives the current one; the new fact keeps the current review status and the response carries it. Source URL and confidence edits update the fact in place. Duplicates across other facts are not rejected here (Knowledge Base dedup owns those). Does not change review status.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"fact_id"
],
"properties": {
"text": {
"type": "string",
"maxLength": 10000,
"minLength": 1
},
"fact_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"confidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"source_url": {
"type": "string",
"maxLength": 2048
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"fact": {
"type": "object",
"required": [
"id",
"text",
"status",
"confidence",
"source_url",
"source_quote",
"source_type",
"pillar",
"created_at"
],
"properties": {
"id": {
"type": "string"
},
"text": {
"type": "string"
},
"pillar": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"status": {
"enum": [
"approved",
"pending",
"rejected"
],
"type": "string"
},
"confidence": {
"anyOf": [
{
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string"
},
"source_url": {
"type": [
"string",
"null"
]
},
"source_type": {
"enum": [
"research",
"response",
"upload",
"content_hub"
],
"type": "string"
},
"source_quote": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"before": {
"type": "object",
"required": [
"text",
"source_url",
"confidence"
],
"properties": {
"text": {
"type": "string"
},
"confidence": {
"anyOf": [
{
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
{
"type": "null"
}
]
},
"source_url": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"title": "Update brand fact",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}
}Change one brand kit's name, guidance text, voice settings, or kit writing rules, and optionally publish it, under the same rules as the Brand Profile page. Call get_brand_kit first. Edits save to the kit's draft; content generation keeps using the published version until publish is true, which creates a new immutable version (the Brand Profile page can restore earlier ones). A guidance entry without find replaces the whole field with text (empty text clears it); with find, text replaces that passage, which must occur exactly once in the field text get_brand_kit returned (empty text deletes it). Voice settings take 1-5 or "auto"; omitted settings keep their value. Rules: add new ones, update by id (omitted fields keep their value; category "" clears it), or remove by id. Kit rules need the writing rules feature on the plan. A rule that contradicts an existing kit or global rule is refused with the explanation and nothing is saved; a rename to a name another kit uses is refused. When the result says the kit changed in another session, call get_brand_kit again and retry. outcome saved_publish_failed means the draft was saved but not published; publish_error says why. Global writing rules are changed with update_global_rules, not here.
| Parameter | Type | Description |
|---|---|---|
| name | string | A new name, unique on the website. |
| rules | object | Writing rules to add, update by id, or remove by id. Ids come from get_brand_kit. |
| kit_id * | string | The brand kit, from get_brand_kit's available_kits. |
| publish | boolean | true publishes the saved draft as a new version, which content generation uses from then on. Only when the user asked to publish. |
| guidance | array | Guidance text changes, one entry per field. Without find, text replaces the whole field (empty text clears it). With find, text replaces that passage (empty text deletes it). |
Add, update or remove the website's global writing rules, the ones the Global rules tab holds and every brand kit and every future piece of content follows. Call get_brand_kit first: its global_rules carry the ids. Add new rules, update by id (omitted fields keep their value; category "" clears it), or remove by id. There is no draft: the change is live for all content generation as soon as it is saved, as a new version the Global rules tab's change history can restore. A rule that contradicts an existing global or kit rule is refused with the explanation and nothing is saved; when the result says the rules changed in another session, call get_brand_kit again and retry. Needs the writing rules feature on the plan. A rule meant for one kit only belongs in update_brand_kit, not here.
| Parameter | Type | Description |
|---|---|---|
| add | array | |
| remove | array | Rule ids to delete. |
| update | array | By id; omitted fields keep their value. |
| website_id * | string |
{
"name": "update_global_rules",
"description": "Add, update or remove the website's global writing rules, the ones the Global rules tab holds and every brand kit and every future piece of content follows. Call get_brand_kit first: its global_rules carry the ids. Add new rules, update by id (omitted fields keep their value; category \"\" clears it), or remove by id. There is no draft: the change is live for all content generation as soon as it is saved, as a new version the Global rules tab's change history can restore. A rule that contradicts an existing global or kit rule is refused with the explanation and nothing is saved; when the result says the rules changed in another session, call get_brand_kit again and retry. Needs the writing rules feature on the plan. A rule meant for one kit only belongs in update_brand_kit, not here.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id"
],
"properties": {
"add": {
"type": "array",
"items": {
"type": "object",
"required": [
"text"
],
"properties": {
"text": {
"type": "string",
"maxLength": 2000,
"minLength": 1,
"description": "One writing rule, as an instruction to the writer."
},
"category": {
"type": "string",
"maxLength": 100,
"description": "A short grouping label; \"\" clears it."
}
},
"additionalProperties": false
}
},
"remove": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Rule ids to delete."
},
"update": {
"type": "array",
"items": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"text": {
"type": "string",
"maxLength": 2000,
"minLength": 1,
"description": "One writing rule, as an instruction to the writer."
},
"category": {
"type": "string",
"maxLength": 100,
"description": "A short grouping label; \"\" clears it."
},
"is_active": {
"type": "boolean",
"description": "false keeps the rule but stops applying it."
}
},
"additionalProperties": false
},
"description": "By id; omitted fields keep their value."
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"added": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"rules": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"text",
"category",
"is_active",
"truncated"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"text": {
"type": "string"
},
"category": {
"type": [
"string",
"null"
]
},
"is_active": {
"type": "boolean"
},
"truncated": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"removed": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"updated": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"version": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
}
},
"additionalProperties": false
},
"annotations": {
"title": "Update global rules",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}
}Add or remove identifiers on the website's brand, or on one competitor, under the same rules as the Competitors page. Call get_identifiers first. The name and domain cannot be removed. An identifier that is already listed, or that another tracked brand or competitor on this website already uses, is refused, and nothing is saved. New AI responses use the change right away. Past responses are reanalyzed only when someone runs the backfill on the Competitors page, which costs credits; this tool never starts it. changes_awaiting_backfill counts the edits waiting for it, not responses.
| Parameter | Type | Description |
|---|---|---|
| add | array | Identifiers to add, exactly as they should match (trimmed). |
| remove | array | Identifiers to remove, exactly as get_identifiers lists them. |
| website_id * | string | |
| competitor_id | string | The competitor to read or edit, from get_competitors. Omit it for the website's own brand. |
{
"name": "update_identifiers",
"description": "Add or remove identifiers on the website's brand, or on one competitor, under the same rules as the Competitors page. Call get_identifiers first. The name and domain cannot be removed. An identifier that is already listed, or that another tracked brand or competitor on this website already uses, is refused, and nothing is saved. New AI responses use the change right away. Past responses are reanalyzed only when someone runs the backfill on the Competitors page, which costs credits; this tool never starts it. changes_awaiting_backfill counts the edits waiting for it, not responses.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id"
],
"properties": {
"add": {
"type": "array",
"items": {
"type": "string",
"maxLength": 500
},
"description": "Identifiers to add, exactly as they should match (trimmed)."
},
"remove": {
"type": "array",
"items": {
"type": "string",
"maxLength": 500
},
"description": "Identifiers to remove, exactly as get_identifiers lists them."
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"competitor_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "The competitor to read or edit, from get_competitors. Omit it for the website's own brand."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"added": {
"type": "array",
"items": {
"type": "string"
}
},
"entity": {
"type": "object",
"required": [
"type",
"id",
"name",
"url"
],
"properties": {
"id": {
"type": "string"
},
"url": {
"type": "string"
},
"name": {
"type": "string"
},
"type": {
"enum": [
"brand",
"competitor"
],
"type": "string"
}
},
"additionalProperties": false
},
"removed": {
"type": "array",
"items": {
"type": "string"
}
},
"identifiers": {
"type": "array",
"items": {
"type": "string"
}
},
"case_sensitive": {
"type": "boolean"
},
"default_identifiers": {
"type": "array",
"items": {
"type": "string"
}
},
"changes_awaiting_backfill": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "How many edits on this website, from anyone, wait for the backfill on the Competitors page. A count of edits, not of responses."
}
},
"additionalProperties": false
},
"annotations": {
"title": "Update identifiers",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": true
}
}Update a location for a website
| Parameter | Type | Description |
|---|---|---|
| country | string | |
| location | string | |
| prompt_ids | array | |
| website_id * | string | |
| location_id * | string |
{
"name": "update_location",
"description": "Update a location for a website",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"location_id"
],
"properties": {
"country": {
"type": "string",
"minLength": 1
},
"location": {
"type": "string",
"maxLength": 500,
"minLength": 1
},
"prompt_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"location_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"id": {
"type": "string"
},
"before": {
"type": "object",
"required": [
"location",
"country"
],
"properties": {
"country": {
"type": [
"string",
"null"
]
},
"location": {
"type": "string"
}
},
"additionalProperties": false
},
"country": {
"type": [
"string",
"null"
]
},
"location": {
"type": "string"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Update location",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
}
}Edit a cited page's Outreach contact: author name, email, LinkedIn, or the draft's subject and body. Creates the contact when the page has none. Supply at least one field; only the fields supplied change, and null clears a field. A changed email is labeled as entered manually. Each change is recorded in the contact's activity history. Obtain user confirmation of the new values before calling.
| Parameter | Type | Description |
|---|---|---|
| url * | string | Cited page URL, e.g. "example.com/blog/best-tools". A contact already saved under this exact URL (for example one the Outreach page saved for a query variant its URL rules list separately) is used first. Otherwise protocol, "www." and the query string (tracking parameters) are ignored, as on the Out… |
| any | Email to pitch. Null clears it; omit to keep it. | |
| message | any | Draft body. Null clears it; omit to keep it. |
| subject | any | Draft subject. Null clears it; omit to keep it. |
| any | Author LinkedIn URL. Null clears it; omit to keep it. | |
| website_id * | string | |
| author_name | any | Author name. Null clears it; omit to keep it. |
Update a Knowledge Base pillar's name, description, or status. At least one of name, description, or status must be provided; only provided fields change, and description: "" clears the stored description. Renaming fails with a conflict when another pillar already uses the name. Status accepts published or archived: archiving hides the pillar from get_pillars and stops its facts feeding content generation, while keeping the facts stored.
| Parameter | Type | Description |
|---|---|---|
| name | string | |
| status | string | one of ["published","archived"] |
| pillar_id * | string | |
| website_id * | string | |
| description | string |
{
"name": "update_pillar",
"description": "Update a Knowledge Base pillar's name, description, or status. At least one of name, description, or status must be provided; only provided fields change, and description: \"\" clears the stored description. Renaming fails with a conflict when another pillar already uses the name. Status accepts published or archived: archiving hides the pillar from get_pillars and stops its facts feeding content generation, while keeping the facts stored.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"pillar_id"
],
"properties": {
"name": {
"type": "string",
"maxLength": 120,
"minLength": 1
},
"status": {
"enum": [
"published",
"archived"
],
"type": "string"
},
"pillar_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": {
"type": "string",
"maxLength": 2000
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"before": {
"type": "object",
"required": [
"name",
"description",
"status"
],
"properties": {
"name": {
"type": "string"
},
"status": {
"enum": [
"researching",
"published",
"draft",
"archived"
],
"type": "string"
},
"description": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"pillar": {
"type": "object",
"required": [
"id",
"name",
"description",
"status"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"status": {
"enum": [
"researching",
"published",
"draft",
"archived"
],
"type": "string"
},
"description": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"title": "Update pillar",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
}
}Update a prompt's metadata (text, type, topic, geography)
| Parameter | Type | Description |
|---|---|---|
| type | any | |
| prompt | string | |
| volume | ["string","null"] | |
| topic_id | any | |
| countries | array | |
| prompt_id * | string | |
| website_id * | string | |
| location_ids | array | |
| primary_country | ["string","null"] |
{
"name": "update_prompt",
"description": "Update a prompt's metadata (text, type, topic, geography)",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"prompt_id"
],
"properties": {
"type": {
"anyOf": [
{
"enum": [
"discovery",
"high_intent"
],
"type": "string"
},
{
"type": "null"
}
]
},
"prompt": {
"type": "string",
"maxLength": 2000
},
"volume": {
"type": [
"string",
"null"
]
},
"topic_id": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "null"
}
]
},
"countries": {
"type": "array",
"items": {
"type": "string"
}
},
"prompt_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"location_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"primary_country": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"id": {
"type": "string"
},
"text": {
"type": "string"
},
"type": {
"type": [
"string",
"null"
]
},
"before": {
"type": "object",
"required": [
"text",
"type",
"volume",
"topic_id",
"countries",
"location_ids"
],
"properties": {
"text": {
"type": "string"
},
"type": {
"type": [
"string",
"null"
]
},
"volume": {
"type": [
"string",
"null"
]
},
"topic_id": {
"type": [
"string",
"null"
]
},
"countries": {
"type": "array",
"items": {
"type": "string"
}
},
"location_ids": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"volume": {
"type": [
"string",
"null"
]
},
"topic_id": {
"type": [
"string",
"null"
]
},
"countries": {
"type": "array",
"items": {
"type": "string"
}
},
"locations": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Update prompt",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
}
}Set the work status (todo, in_progress, or dismissed for not an issue) or the assignee of a whole Site Health issue: every unresolved finding of one check across the website, in one write, as the status and assignee controls on an issue do. Omit a field to leave it as it is; unassign true (or assignee_user_id null) unassigns every page. Returns how many task rows changed; a repeated write changes none. The assignee is emailed once for the pages they now hold. Signed-in connections only: an API key has no teammate to act as, so API-key connections are not offered this tool and a direct call is refused with 403. Requires Site Health on the website's plan; otherwise the call fails with 403.
| Parameter | Type | Description |
|---|---|---|
| check * | string | The check id of the issue, from the issue list. |
| unassign | boolean | true clears the assignee. Chat tools must use this: a null assignee_user_id is dropped as unspecified. Cannot be sent with an assignee_user_id. |
| website_id * | string | |
| work_status | string | todo, in_progress or dismissed (not an issue). |
| assignee_user_id | any | A teammate with analytics access on the website, as get_user_by_email or an earlier assignee.id gives it; null unassigns every page (chat tools send unassign true instead); absent leaves assignees as they are. |
{
"name": "update_site_health_issue",
"description": "Set the work status (todo, in_progress, or dismissed for not an issue) or the assignee of a whole Site Health issue: every unresolved finding of one check across the website, in one write, as the status and assignee controls on an issue do. Omit a field to leave it as it is; unassign true (or assignee_user_id null) unassigns every page. Returns how many task rows changed; a repeated write changes none. The assignee is emailed once for the pages they now hold. Signed-in connections only: an API key has no teammate to act as, so API-key connections are not offered this tool and a direct call is refused with 403. Requires Site Health on the website's plan; otherwise the call fails with 403.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"check"
],
"properties": {
"check": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "The check id of the issue, from the issue list."
},
"unassign": {
"type": "boolean",
"description": "true clears the assignee. Chat tools must use this: a null assignee_user_id is dropped as unspecified. Cannot be sent with an assignee_user_id."
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"work_status": {
"enum": [
"todo",
"in_progress",
"dismissed"
],
"type": "string",
"description": "todo, in_progress or dismissed (not an issue)."
},
"assignee_user_id": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "null"
}
],
"description": "A teammate with analytics access on the website, as get_user_by_email or an earlier assignee.id gives it; null unassigns every page (chat tools send unassign true instead); absent leaves assignees as they are."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"check": {
"type": "string"
},
"updated": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"work_status": {
"anyOf": [
{
"enum": [
"todo",
"in_progress",
"dismissed"
],
"type": "string"
},
{
"type": "null"
}
]
},
"assignee_user_id": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "Update site health issue",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
}
}Assign one Site Health finding to a teammate or set its work status: todo, in_progress, ready_to_verify, or dismissed (not an issue, which stays closed even when a later audit finds it again). Pass the page's finding_id and task_revision from the issue list or the issue pages read as finding_id and revision; a revision that is no longer current, or a finding that has since recurred, is refused with 409, so re-read first. unassign true (or assignee_user_id null) clears the assignee; the teammate must have analytics access on the website. A newly assigned teammate is emailed. Returns the new revision with the before and after assignee and status. Signed-in connections only: an API key has no teammate to act as, so API-key connections are not offered this tool and a direct call is refused with 403. Requires Site Health on the website's plan; otherwise the call fails with 403.
| Parameter | Type | Description |
|---|---|---|
| revision * | integer | The page's `task_revision` from the same read; a stale value is refused. |
| unassign | boolean | true clears the assignee. Chat tools must use this: a null assignee_user_id is dropped as unspecified. Cannot be sent with an assignee_user_id. |
| finding_id * | string | The finding, as `finding_id` names it on an affected page. |
| website_id * | string | |
| work_status | string | todo, in_progress, ready_to_verify or dismissed (not an issue). |
| assignee_user_id | any | A teammate with analytics access on the website, as get_user_by_email or an earlier assignee.id gives it; null clears the assignee (chat tools send unassign true instead). |
Update a topic's name or description
| Parameter | Type | Description |
|---|---|---|
| name | string | |
| topic_id * | string | |
| website_id * | string | |
| description | any |
{
"name": "update_topic",
"description": "Update a topic's name or description",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"topic_id"
],
"properties": {
"name": {
"type": "string",
"maxLength": 255,
"minLength": 1
},
"topic_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": {
"anyOf": [
{
"type": "string",
"maxLength": 2000
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"before": {
"type": "object",
"required": [
"name",
"description"
],
"properties": {
"name": {
"type": "string"
},
"description": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"description": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "Update topic",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
}
}Names, descriptions and schemas were written by the server and are shown as data.
Pattern matches on what the server declares. They show what it says it can do, not what it does.
None yet. Changes appear after a server's second daily check.
{
"name": "get_tracked_content",
"description": "List tracked content (1st-party drafts, imported pages, 3rd-party placements) with citation, mention, and impression metrics for the supplied date range and filters. Supports pagination via page_num / page_size and optional filtering by Content Hub sheet_id or content_type. A sheet_id of a view-type tab (see get_content_hub_sheets sheet_type) lists the shared main pool: content not filed in any sheet. In-flight pipeline items (drafts, briefs, running generations) never appear here; enumerate those with list_content. A returned item can still lack a url (pipeline finished but not published anywhere yet).",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"filters"
],
"properties": {
"filters": {
"type": "object",
"required": [
"start_date"
],
"properties": {
"models": {
"type": "array",
"items": {
"enum": [
"chatgpt",
"perplexity",
"gemini",
"google_ai_overview",
"copilot",
"claude",
"ai_mode",
"grok",
"deepseek",
"meta_ai",
"mistral"
],
"type": "string"
},
"description": "AI models to include, as an array even for one model — e.g. [\"chatgpt\", \"perplexity\"]. Omit to include all models."
},
"end_date": {
"type": "string",
"description": "End of the date range, inclusive. Date-only values include the UTC day through 23:59:59.999; timestamps keep their exact instant. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"prompt_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Prompt UUIDs to filter to, as an array even for one id. Omit for all prompts."
},
"start_date": {
"type": "string",
"description": "Start of the date range. Required. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"persona_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Persona UUIDs to filter to, as an array even for one id. Omit for all personas."
},
"prompt_tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Prompt tag IDs to filter prompts by, as an array (list tags with get_prompt_tags). Omit for all tags."
},
"prompt_type": {
"enum": [
"branded",
"non_branded"
],
"type": "string",
"description": "Filter prompts by type: \"branded\" (mentions the brand) or \"non_branded\". Omit for both."
},
"schedule_id": {
"anyOf": [
{
"enum": [
"default",
"manual"
],
"type": "string"
},
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
],
"description": "One schedule: \"default\" or a custom/archived schedule UUID. Omit for Default, which includes all pre-cutover history and ad hoc runs. The retired \"manual\" token is accepted as an alias of \"default\". Schedules cannot be combined."
},
"location_ids": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "string",
"const": "no-location"
}
]
},
"description": "Location UUIDs to filter to, as an array even for one id. The literal string \"no-location\" selects responses that ran without a location. Omit for all locations."
},
"prompt_status": {
"enum": [
"active",
"paused"
],
"type": "string",
"description": "Filter prompts by tracking status: \"active\" or \"paused\". Omit for both."
},
"competitor_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Competitor UUIDs to filter to, as an array even for one id. Omit for all competitors."
},
"variation_filter": {
"type": "array",
"items": {
"enum": [
"variation",
"prompt"
],
"type": "string"
},
"description": "Which prompt rows to include, as an array: \"prompt\" for base prompts, \"variation\" for generated variations, or both. Omit for both."
},
"target_identifiers": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "string",
"const": "no-identifier"
}
]
},
"description": "Target identifier strings to filter to, as an array even for one value. The literal string \"no-identifier\" selects responses with no target identifier. Omit for all."
},
"prompt_tags_operator": {
"enum": [
"is_any_of",
"has_all_of"
],
"type": "string",
"description": "How prompt_tags combine: \"is_any_of\" matches prompts with any listed tag, \"has_all_of\" only prompts carrying every listed tag."
}
}
},
"page_num": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0
},
"sheet_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "Content Hub tab to list (get_content_hub_sheets). A sheet-type tab lists its own content; a view-type tab, the default tab included, lists the shared main pool (content not filed in any sheet), without the view's saved filters. Omit to list content on every tab."
},
"mentioned": {
"type": "boolean"
},
"page_size": {
"type": "integer",
"default": 50,
"maximum": 100,
"minimum": 1
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"content_type": {
"enum": [
"external",
"imported",
"athena_created",
"draft",
"snipe",
"optimize",
"slice",
"manual"
],
"type": "string"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"content",
"pagination"
],
"properties": {
"content": {
"type": "array",
"items": {
"type": "object",
"required": [
"content_id",
"title",
"url",
"normalized_url",
"type",
"topic_name",
"sheet_id",
"sheet_name",
"citations",
"citation_percent",
"estimated_impressions",
"total_responses",
"mark_as_done_time",
"created_at"
],
"properties": {
"url": {
"type": [
"string",
"null"
]
},
"type": {
"type": [
"string",
"null"
]
},
"title": {
"type": [
"string",
"null"
]
},
"sheet_id": {
"type": [
"string",
"null"
]
},
"citations": {
"type": "number"
},
"content_id": {
"type": "string"
},
"created_at": {
"type": "string"
},
"sheet_name": {
"type": [
"string",
"null"
]
},
"topic_name": {
"type": [
"string",
"null"
]
},
"normalized_url": {
"type": [
"string",
"null"
]
},
"total_responses": {
"type": "number"
},
"citation_percent": {
"type": "number"
},
"mark_as_done_time": {
"type": "string"
},
"estimated_impressions": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"required": [
"page_num",
"page_size",
"has_more"
],
"properties": {
"has_more": {
"type": "boolean"
},
"page_num": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"page_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get tracked content",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}| page_size |
| integer |
| prompt_id | string |
| website_id * | string |
| content_type | string | one of ["external","imported","athena_created","draft","snipe","optimize","slice","manual"] |
{
"name": "list_content",
"description": "Enumerate 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. Returns identity fields only (id, title, type, stage, sheet, URL, timestamps, target prompt ids), no metrics. Uncached and Postgres-backed, so an item created by create_content is listable immediately. Filter by sheet_id, content_type, stage, or prompt_id. stage is the raw pipeline workflow state, not a publication flag: null = no pipeline record (most tracked external / imported pages), and manual editor items carry 'generated'. Treat an item as published only when its stage is done (or it is an external / imported page) AND it has a url; done without a url is an unpublished orphan. A sheet_id of a view-type tab (see get_content_hub_sheets sheet_type) lists the shared main pool without the view's saved filters. Use get_tracked_content for citation and impression metrics on published content; use this tool to discover what exists. Each row carries prompt_ids: the prompts that item was WRITTEN FOR (what create_content was given), capped at 25 with the true size in prompt_count — resolve the ids to text with get_prompts rather than calling get_content_detail per row, and drill in with get_content_detail where prompt_count exceeds the ids returned (that read carries up to 100; associations past 100 are not currently readable). prompt_ids includes soft-deleted prompts, which get_prompts does NOT list — an id that fails to resolve there is a deleted prompt, and get_content_detail returns its text and status: \"deleted\". Empty prompt_ids means no targeting was recorded, which is normal for imported or externally tracked pages. This is not the same as being cited for a prompt — see get_content_citation_prompts for that. Filter by prompt_id for the reverse question: which content already targets a given prompt (coverage gaps).",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id"
],
"properties": {
"stage": {
"enum": [
"scheduled",
"pending",
"pending_brief",
"generated_brief",
"pending_article",
"generated",
"done",
"failed"
],
"type": "string"
},
"page_num": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0
},
"sheet_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"page_size": {
"type": "integer",
"default": 50,
"maximum": 100,
"minimum": 1
},
"prompt_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"content_type": {
"enum": [
"external",
"imported",
"athena_created",
"draft",
"snipe",
"optimize",
"slice",
"manual"
],
"type": "string"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"content",
"pagination"
],
"properties": {
"content": {
"type": "array",
"items": {
"type": "object",
"required": [
"content_id",
"title",
"type",
"stage",
"url",
"normalized_url",
"sheet_id",
"sheet_name",
"topic_name",
"prompt_ids",
"prompt_count",
"mark_as_done_time",
"created_at",
"updated_at"
],
"properties": {
"url": {
"type": [
"string",
"null"
]
},
"type": {
"type": [
"string",
"null"
]
},
"stage": {
"anyOf": [
{
"enum": [
"scheduled",
"pending",
"pending_brief",
"generated_brief",
"pending_article",
"generated",
"done",
"failed"
],
"type": "string"
},
{
"type": "null"
}
]
},
"title": {
"type": [
"string",
"null"
]
},
"sheet_id": {
"type": [
"string",
"null"
]
},
"content_id": {
"type": "string"
},
"created_at": {
"type": "string"
},
"prompt_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"sheet_name": {
"type": [
"string",
"null"
]
},
"topic_name": {
"type": [
"string",
"null"
]
},
"updated_at": {
"type": "string"
},
"prompt_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"normalized_url": {
"type": [
"string",
"null"
]
},
"mark_as_done_time": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"required": [
"page_num",
"page_size",
"has_more"
],
"properties": {
"has_more": {
"type": "boolean"
},
"page_num": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"page_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"title": "List content",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}{
"name": "get_content_detail",
"description": "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. For an optimize item, source_url is 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. source_url is null for other content types and for optimize items based on pasted text or a file. 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.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"content_id"
],
"properties": {
"content_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"content_id",
"title",
"url",
"normalized_url",
"source_url",
"type",
"sheet_id",
"status",
"brief",
"body",
"meta_description",
"cited_urls",
"internal_links",
"brief_cited_urls",
"brief_internal_links",
"optimize_summary",
"linkedin_post",
"x_post",
"facebook_post",
"instagram_post",
"reddit_post",
"topic_name",
"prompts",
"prompts_total",
"mark_as_done_time",
"created_at",
"updated_at"
],
"properties": {
"url": {
"type": [
"string",
"null"
]
},
"body": {
"type": [
"string",
"null"
]
},
"type": {
"type": [
"string",
"null"
]
},
"brief": {
"type": [
"string",
"null"
]
},
"title": {
"type": [
"string",
"null"
]
},
"status": {
"anyOf": [
{
"enum": [
"scheduled",
"pending",
"pending_brief",
"generated_brief",
"pending_article",
"generated",
"done",
"failed"
],
"type": "string"
},
{
"type": "null"
}
]
},
"x_post": {
"type": [
"string",
"null"
]
},
"prompts": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"prompt",
"topic_name",
"status"
],
"properties": {
"id": {
"type": "string"
},
"prompt": {
"type": "string"
},
"status": {
"enum": [
"active",
"paused",
"deleted"
],
"type": "string"
},
"topic_name": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
},
"sheet_id": {
"type": [
"string",
"null"
]
},
"cited_urls": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"content_id": {
"type": "string"
},
"created_at": {
"type": "string"
},
"source_url": {
"type": [
"string",
"null"
]
},
"topic_name": {
"type": [
"string",
"null"
]
},
"updated_at": {
"type": "string"
},
"reddit_post": {
"type": [
"string",
"null"
]
},
"facebook_post": {
"type": [
"string",
"null"
]
},
"linkedin_post": {
"type": [
"string",
"null"
]
},
"prompts_total": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"instagram_post": {
"type": [
"string",
"null"
]
},
"internal_links": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"normalized_url": {
"type": [
"string",
"null"
]
},
"brief_cited_urls": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"meta_description": {
"type": [
"string",
"null"
]
},
"optimize_summary": {
"anyOf": [
{
"type": "object",
"required": [
"overview",
"changes"
],
"properties": {
"changes": {
"type": "array",
"items": {
"type": "object",
"required": [
"description"
],
"properties": {
"description": {
"type": "string"
}
},
"additionalProperties": false
}
},
"overview": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"mark_as_done_time": {
"type": [
"string",
"null"
]
},
"brief_internal_links": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get content detail",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}| limit | integer | Max rows to return. |
| where | any | WHERE filter (before grouping). |
| having | any | HAVING filter (after grouping). References measure aliases and by dims. |
| compare | object | Compare the same measures across two slices. Each base measure `m` expands to `m_<baseline.label>` and `m_<current.label>`; the result also gets `m_delta` (= current − baseline) and `m_pct_change` (= (current − baseline) / baseline, null when baseline = 0). For a min/max of `date`, `m_delta` is in d… |
| orderBy | array | ORDER BY. Measure aliases and by dims allowed. |
| measures * | object | Aggregate expressions keyed by output column name. Example: { total: { fn: 'count_distinct', of: 'response_id' } } |
| schedule | any | One schedule from the catalog ("default" or a custom/archived UUID), or an array of them to combine their data. Omit to use the caller default. The retired "manual" token is accepted as a deprecated alias of "default". Website-level cubes are unaffected. |
| alsoSelect | array | Label dimensions carried via any(). Must be determined by a by dim (cube's dependentDims). Example: entity_name when entity_id is in by. |
| website_id * | string | The website to query. Must be a website your credentials can access. |
{
"name": "query_metrics",
"description": "Query aggregated metrics for brand performance, competitors, sources, citations, and response trends. Use query_rows for individual records.\n\nMentions: from \"response_mentions\". Citations: from \"citations\". On either, where { is_website: true } selects the brand; { is_competitor: true } selects competitors; { entity_id: { eq: \"<uuid>\" } } selects one entity.\nFilter/group models by model_category (display names like \"ChatGPT\", \"Claude\"), never \"model\". Dimensions vary by cube; source_mentions has no prompt/model dimensions.\nGroup by week (Monday start) or month wherever date groups. prompt_status is the paused flag (true = paused).\n\nMeasures: count, count_distinct, avg, sum, min, max; per-measure where enables conditional aggregation. Use compare for two date ranges.\nWhen grouping by IDs, use alsoSelect for names: entity_id/entity_name, prompt_id/prompt_text, prompt_topic_id/topic_name (prompts uses topic_id).\n\nCited pages mentioning competitors but not the brand: from \"sources\", where { source_mentions_entity: { hasSome: [competitorIds], hasNone: [brandId] } }. Also works on \"source_mentions\". Checks all stored page mentions per URL/website. Date/model on sources scope AI responses; extracted page content may be older than the live page.\n\nContent-hub attribution: on \"sources\", where { is_attributed_content: true }; by: [\"content_id\"], alsoSelect: [\"content_title\"]. Add content_type to by for type, or group by content_type alone. Read articles from \"contents\" via query_rows.\n\nSchedule: select one \"default\" or custom/archived UUID from the catalog, or an array of them to combine schedules. Omit for caller default (current page in Ask Athena); explicit schedule overrides it. Top-level prompt_schedule_kind/id equality filters remain supported but must not conflict with schedule. Historical provenance is independent of current prompt membership; website-level cubes are unaffected.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"from",
"measures",
"website_id"
],
"properties": {
"by": {
"type": "array",
"items": {
"type": "string"
},
"description": "GROUP BY dimensions. Omit for scalar result."
},
"from": {
"enum": [
"attributes",
"citations",
"competitors",
"contents",
"prompts",
"response_mentions",
"responses",
"source_mentions",
"sources",
"topics",
"websites"
],
"type": "string",
"description": "Dataset to query. Cubes and their contracts:\nEach cube lists its selectable fields, then: filter-only (usable only in where), alsoSelect (name←id: group by the id, pass the name in alsoSelect), groupable (the only fields accepted in by), max limit (the most rows one call returns), and order by index (dims in orderBy that are not in by must follow this order, skipping allowed).\nwebsites:\n created_at, default_language, industry, normalized_url, org_id, website_id, website_name, website_url | groupable: website_id, org_id, industry, default_language | max limit 1000 (default 100) | order by index: website_id\ncompetitors:\n created_at, entity_id, entity_name, website_id | alsoSelect: entity_name←entity_id | groupable: website_id, entity_id | max limit 1000 (default 100) | order by index: website_id, entity_id\nprompts:\n created_at, is_paused, language, monthly_searches, prompt_id, prompt_text, prompt_type, topic_id, topic_name, total_value, website_id | filter-only: prompt_tag_ids | alsoSelect: topic_name←topic_id | groupable: website_id, topic_id, prompt_type, is_paused | max limit 1000 (default 100) | order by index: website_id, monthly_searches, total_value, prompt_id\nresponses:\n cited, company_count, country, date, location_id, model_category, persona_id, prompt_id, prompt_is_deleted, prompt_language, prompt_status, prompt_text, prompt_topic_id, prompt_type, prompt_variation, response_id, sentiment, sentiment_score, target_identifiers, target_rank, topic_name, website_id, content | filter-only: is_base_prompt, prompt_tag_ids, response_mentions_entity | alsoSelect: prompt_text←prompt_id, topic_name←prompt_topic_id | groupable: website_id, date, prompt_id, model_category, sentiment, prompt_type, prompt_topic_id, persona_id, location_id | max limit 100 (default 100) | order by index: website_id, date, prompt_id, response_id\nresponse_mentions:\n country, date, entity_id, entity_name, identifier, is_website, location_id, mention_id, model_category, persona_id, position, prompt_id, prompt_is_deleted, prompt_language, prompt_status, prompt_text, prompt_topic_id, prompt_type, rank, rank_percentile, response_id, topic_name, website_id | filter-only: is_competitor, prompt_tag_ids, ranked_count, response_mentions_entity | alsoSelect: entity_name←entity_id, prompt_text←prompt_id, topic_name←prompt_topic_id | groupable: website_id, date, entity_id, is_website, prompt_id, model_category, prompt_topic_id, persona_id, location_id | max limit 10000 (default 1000) | order by index: website_id, date, entity_id\nattributes:\n attribute_id, attribute_mention_id, attribute_name, country, date, entity_id, entity_name, is_website, location_id, model_category, persona_id, positive, prompt_id, prompt_is_deleted, prompt_language, prompt_status, prompt_text, prompt_topic_id, prompt_type, response_id, topic_name, website_id | filter-only: is_competitor, prompt_tag_ids, response_mentions_entity | alsoSelect: entity_name←entity_id, attribute_name←attribute_id, prompt_text←prompt_id, topic_name←prompt_topic_id | groupable: website_id, date, entity_id, attribute_id, positive, is_website, prompt_topic_id | max limit 10000 (default 1000) | order by index: website_id, date, entity_id, attribute_id\nsources:\n content_id, content_title, content_type, country, date, domain, full_url, location_id, model_category, normalized_url, persona_id, prompt_id, prompt_is_deleted, prompt_language, prompt_status, prompt_text, prompt_topic_id, prompt_type, response_id, source_id, topic_name, website_id | filter-only: is_attributed_content, prompt_tag_ids, response_mentions_entity, source_tag | alsoSelect: prompt_text←prompt_id, topic_name←prompt_topic_id, content_title←content_id | groupable: website_id, date, domain, normalized_url, full_url, prompt_id, model_category, prompt_topic_id, content_id, content_type | max limit 10000 (default 1000) | order by index: website_id, date, domain\ncitations:\n citation_id, country, date, domain, entity_id, entity_name, is_website, location_id, model_category, normalized_url, persona_id, prompt_id, prompt_is_deleted, prompt_language, prompt_status, prompt_text, prompt_topic_id, prompt_type, response_id, source_id, topic_name, website_id | filter-only: is_competitor, prompt_tag_ids, response_mentions_entity, source_tag | alsoSelect: entity_name←entity_id, prompt_text←prompt_id, topic_name←prompt_topic_id | groupable: website_id, date, entity_id, domain, normalized_url, source_id, prompt_id, model_category, prompt_topic_id | max limit 10000 (default 1000) | order by index: website_id, date, entity_id, domain\nsource_mentions:\n date, domain, entity_id, entity_name, is_website, normalized_url, source_unique_id, website_id | filter-only: is_competitor | alsoSelect: entity_name←entity_id | groupable: website_id, date, entity_id, is_website, domain, normalized_url, source_unique_id | max limit 10000 (default 1000) | order by index: website_id, domain, date, entity_id\ntopics:\n created_at, topic_description, topic_id, topic_name, website_id | groupable: website_id, topic_id | max limit 1000 (default 100) | order by index: website_id, topic_id\ncontents:\n content_id, content_type, created_at, date, effective_date, normalized_url, sheet_id, status, title, topic_id, topic_name, updated_at, url, website_id | alsoSelect: topic_name←topic_id, title←content_id | groupable: website_id, status, topic_id, content_type | max limit 1000 (default 100) | order by index: website_id, effective_date, created_at, content_id"
},
"limit": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Max rows to return."
},
"where": {
"allOf": [
{
"$ref": "#/definitions/Filter"
}
],
"description": "WHERE filter (before grouping)."
},
"having": {
"allOf": [
{
"$ref": "#/definitions/Filter"
}
],
"description": "HAVING filter (after grouping). References measure aliases and by dims."
},
"compare": {
"type": "object",
"required": [
"baseline",
"current"
],
"properties": {
"current": {
"$ref": "#/definitions/CompareSlice"
},
"baseline": {
"$ref": "#/definitions/CompareSlice"
}
},
"description": "Compare the same measures across two slices. Each base measure `m` expands to `m_<baseline.label>` and `m_<current.label>`; the result also gets `m_delta` (= current − baseline) and `m_pct_change` (= (current − baseline) / baseline, null when baseline = 0). For a min/max of `date`, `m_delta` is in days and `m_pct_change` is null. Default labels are 'baseline' and 'current'; override per side for non-temporal compares (e.g. brand vs competitors). One scan; orderBy on `m_delta` works push-down."
},
"orderBy": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"description": "Dim or measure name, ascending."
},
{
"type": "object",
"required": [
"dim"
],
"properties": {
"dim": {
"type": "string"
},
"desc": {
"type": "boolean"
}
}
},
{
"type": "object",
"required": [
"measure"
],
"properties": {
"desc": {
"type": "boolean"
},
"measure": {
"type": "string"
}
}
}
]
},
"description": "ORDER BY. Measure aliases and by dims allowed."
},
"measures": {
"type": "object",
"description": "Aggregate expressions keyed by output column name. Example: { total: { fn: 'count_distinct', of: 'response_id' } }",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"anyOf": [
{
"type": "object",
"required": [
"fn"
],
"properties": {
"fn": {
"enum": [
"count",
"count_distinct",
"avg",
"sum",
"min",
"max"
],
"type": "string",
"description": "Aggregate function."
},
"of": {
"type": "string",
"description": "Dimension to aggregate. Required for all functions except count. Bare `count` (no `of`) counts distinct facts (responses, mentions, citations...) on fact cubes. It throws on pre-aggregated tables (MVs) where rows are groups, not facts — use `{ fn: 'count_distinct', of: '<id-dim>' }` instead (e.g. `of: 'response_id'` on mentions/citations) to hit the MV's pre-computed aggregate."
},
"where": {
"allOf": [
{
"$ref": "#/definitions/Filter"
}
],
"description": "Per-measure conditional filter (compiles to countIf, avgIf, etc.)."
}
},
"description": "Aggregate expression."
},
{
"type": "object",
"required": [
"expr"
],
"properties": {
"expr": {
"$ref": "#/definitions/Expr"
}
},
"description": "Derived measure — an s-expression computed over other measures. Refs resolve to other measure aliases in the same query. Example: { expr: [\"/\", \"brand\", [\"nullIf\", \"total\", 0]] }"
}
]
}
},
"schedule": {
"anyOf": [
{
"anyOf": [
{
"enum": [
"default",
"manual"
],
"type": "string"
},
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
]
},
{
"type": "array",
"items": {
"anyOf": [
{
"enum": [
"default",
"manual"
],
"type": "string"
},
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
]
},
"maxItems": 50,
"minItems": 1
}
],
"description": "One schedule from the catalog (\"default\" or a custom/archived UUID), or an array of them to combine their data. Omit to use the caller default. The retired \"manual\" token is accepted as a deprecated alias of \"default\". Website-level cubes are unaffected."
},
"alsoSelect": {
"type": "array",
"items": {
"type": "string"
},
"description": "Label dimensions carried via any(). Must be determined by a by dim (cube's dependentDims). Example: entity_name when entity_id is in by."
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "The website to query. Must be a website your credentials can access."
}
},
"definitions": {
"Expr": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/definitions/Expr"
},
"minItems": 1
}
],
"description": "S-expression. Strings are refs (to a measure alias or by-dim). Numbers/booleans/null are literals. Arrays are [op, ...args] where op is a binary operator (+ - * / % = != < <= > >= AND OR) or one of the allowed scalar functions: nullIf, coalesce, ifNull, if, multiIf, abs, round, floor, ceil, sqrt, pow, least, greatest, log, exp, sign. Examples: [\"-\", \"n_current\", \"n_baseline\"], [\"/\", \"num\", [\"nullIf\", \"denom\", 0]], [\"coalesce\", \"value\", 0]."
},
"Filter": {
"type": "object",
"properties": {
"OR": {
"type": "array",
"items": {
"$ref": "#/definitions/Filter"
},
"minItems": 1
},
"AND": {
"anyOf": [
{
"$ref": "#/definitions/Filter"
},
{
"type": "array",
"items": {
"$ref": "#/definitions/Filter"
},
"minItems": 1
}
]
},
"NOT": {
"allOf": [
{
"$ref": "#/definitions/Filter"
}
]
}
},
"description": "Prisma-style filter. A bare scalar value on a dim is shorthand for `eq` (e.g. `{ is_website: true }`); bare arrays and op-less objects throw — use `{ in: [...] }` / `{ hasSome: [...] }` explicitly. Operators: eq, neq, in, notIn, gt, gte, lt, lte, isNull, like, ilike, startsWith, hasSome, hasEvery, hasNone. Combinators: AND, OR, NOT. On semi-join dims (e.g. `response_mentions_entity`, `prompt_tag_ids`), `hasSome`/`in` emit `IN (SELECT …)` and `hasNone`/`notIn` emit `NOT IN (SELECT …)`; combine both on one dim to express \"includes any of A but none of B\". Empty `AND: []` / `OR: []` throw (the math identities are asymmetric — drop the clause before passing). Empty list operators (`hasSome: []` / `hasNone: []` / `hasEvery: []`) also throw — drop the predicate or supply at least one value. NOT accepts a single Filter only — for arrays use `NOT: { AND: [...] }` (`not all`) or `NOT: { OR: [...] }` (`none`). NOT keeps rows whose value is NULL: `NOT { sentiment: { eq: \"positive\" } }` returns unanalyzed responses as well as negative and neutral ones, because \"not positive\" is true of a row with no sentiment. Exclude them explicitly with `AND: [{ NOT: {...} }, { sentiment: { isNull: false } }]`.",
"additionalProperties": {}
},
"CompareSlice": {
"type": "object",
"required": [
"where"
],
"properties": {
"label": {
"type": "string"
},
"where": {
"$ref": "#/definitions/Filter"
}
},
"description": "One side of a compare. `where` is the filter that scopes this slice (non-empty — empty means 'all rows', which trivializes the comparison). `label` defaults to 'baseline' / 'current' and forms the suffix on expanded column names; override for non-temporal compares."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"rows"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"notice": {
"type": "string"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Query metrics",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}| orderBy | array | ORDER BY. If omitted, uses cube default order. |
| schedule | any | One schedule from the catalog ("default" or a custom/archived UUID), or an array of them to combine their data. Omit to use the caller default. The retired "manual" token is accepted as a deprecated alias of "default". Website-level cubes are unaffected. |
| website_id * | string | The website to query. Must be a website your credentials can access. |
{
"name": "query_rows",
"description": "Query individual analytics rows. Use for qualitative data like response text, specific identifiers, or individual mentions.\n\nSchedule selection: pass schedule: \"default\" or a custom/archived UUID from the schedule catalog, or an array of them to combine schedules. Omit to use the caller default (Ask Athena uses the current page selection). Explicit selection overrides that default. Existing top-level equality predicates on prompt_schedule_kind/id remain supported, but cannot conflict with schedule. Historical provenance does not change with current prompt membership. Website-level cubes are unaffected.\n\nCubes (same set as query_metrics): attributes, citations, competitors, contents, prompts, response_mentions, responses, source_mentions, sources, topics, websites.\nReturns { rows, nextCursor, hasMore }. Pass nextCursor back as \"after\" to paginate.\nprompt_status is the prompt's paused flag (boolean, true = paused), not a status string.\nOn the responses cube, content is hydrated from Postgres and can only be selected. Do not filter or sort by content. Use search_terms_in_responses for text frequency analysis.\nUse query_metrics for aggregates instead.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"from",
"fields",
"website_id"
],
"properties": {
"from": {
"enum": [
"attributes",
"citations",
"competitors",
"contents",
"prompts",
"response_mentions",
"responses",
"source_mentions",
"sources",
"topics",
"websites"
],
"type": "string",
"description": "Dataset to query. Cubes and their contracts:\nEach cube lists its selectable fields, then: filter-only (usable only in where), alsoSelect (name←id: group by the id, pass the name in alsoSelect), groupable (the only fields accepted in by), max limit (the most rows one call returns), and order by index (dims in orderBy that are not in by must follow this order, skipping allowed).\nwebsites:\n created_at, default_language, industry, normalized_url, org_id, website_id, website_name, website_url | groupable: website_id, org_id, industry, default_language | max limit 1000 (default 100) | order by index: website_id\ncompetitors:\n created_at, entity_id, entity_name, website_id | alsoSelect: entity_name←entity_id | groupable: website_id, entity_id | max limit 1000 (default 100) | order by index: website_id, entity_id\nprompts:\n created_at, is_paused, language, monthly_searches, prompt_id, prompt_text, prompt_type, topic_id, topic_name, total_value, website_id | filter-only: prompt_tag_ids | alsoSelect: topic_name←topic_id | groupable: website_id, topic_id, prompt_type, is_paused | max limit 1000 (default 100) | order by index: website_id, monthly_searches, total_value, prompt_id\nresponses:\n cited, company_count, country, date, location_id, model_category, persona_id, prompt_id, prompt_is_deleted, prompt_language, prompt_status, prompt_text, prompt_topic_id, prompt_type, prompt_variation, response_id, sentiment, sentiment_score, target_identifiers, target_rank, topic_name, website_id, content | filter-only: is_base_prompt, prompt_tag_ids, response_mentions_entity | alsoSelect: prompt_text←prompt_id, topic_name←prompt_topic_id | groupable: website_id, date, prompt_id, model_category, sentiment, prompt_type, prompt_topic_id, persona_id, location_id | max limit 100 (default 100) | order by index: website_id, date, prompt_id, response_id\nresponse_mentions:\n country, date, entity_id, entity_name, identifier, is_website, location_id, mention_id, model_category, persona_id, position, prompt_id, prompt_is_deleted, prompt_language, prompt_status, prompt_text, prompt_topic_id, prompt_type, rank, rank_percentile, response_id, topic_name, website_id | filter-only: is_competitor, prompt_tag_ids, ranked_count, response_mentions_entity | alsoSelect: entity_name←entity_id, prompt_text←prompt_id, topic_name←prompt_topic_id | groupable: website_id, date, entity_id, is_website, prompt_id, model_category, prompt_topic_id, persona_id, location_id | max limit 10000 (default 1000) | order by index: website_id, date, entity_id\nattributes:\n attribute_id, attribute_mention_id, attribute_name, country, date, entity_id, entity_name, is_website, location_id, model_category, persona_id, positive, prompt_id, prompt_is_deleted, prompt_language, prompt_status, prompt_text, prompt_topic_id, prompt_type, response_id, topic_name, website_id | filter-only: is_competitor, prompt_tag_ids, response_mentions_entity | alsoSelect: entity_name←entity_id, attribute_name←attribute_id, prompt_text←prompt_id, topic_name←prompt_topic_id | groupable: website_id, date, entity_id, attribute_id, positive, is_website, prompt_topic_id | max limit 10000 (default 1000) | order by index: website_id, date, entity_id, attribute_id\nsources:\n content_id, content_title, content_type, country, date, domain, full_url, location_id, model_category, normalized_url, persona_id, prompt_id, prompt_is_deleted, prompt_language, prompt_status, prompt_text, prompt_topic_id, prompt_type, response_id, source_id, topic_name, website_id | filter-only: is_attributed_content, prompt_tag_ids, response_mentions_entity, source_tag | alsoSelect: prompt_text←prompt_id, topic_name←prompt_topic_id, content_title←content_id | groupable: website_id, date, domain, normalized_url, full_url, prompt_id, model_category, prompt_topic_id, content_id, content_type | max limit 10000 (default 1000) | order by index: website_id, date, domain\ncitations:\n citation_id, country, date, domain, entity_id, entity_name, is_website, location_id, model_category, normalized_url, persona_id, prompt_id, prompt_is_deleted, prompt_language, prompt_status, prompt_text, prompt_topic_id, prompt_type, response_id, source_id, topic_name, website_id | filter-only: is_competitor, prompt_tag_ids, response_mentions_entity, source_tag | alsoSelect: entity_name←entity_id, prompt_text←prompt_id, topic_name←prompt_topic_id | groupable: website_id, date, entity_id, domain, normalized_url, source_id, prompt_id, model_category, prompt_topic_id | max limit 10000 (default 1000) | order by index: website_id, date, entity_id, domain\nsource_mentions:\n date, domain, entity_id, entity_name, is_website, normalized_url, source_unique_id, website_id | filter-only: is_competitor | alsoSelect: entity_name←entity_id | groupable: website_id, date, entity_id, is_website, domain, normalized_url, source_unique_id | max limit 10000 (default 1000) | order by index: website_id, domain, date, entity_id\ntopics:\n created_at, topic_description, topic_id, topic_name, website_id | groupable: website_id, topic_id | max limit 1000 (default 100) | order by index: website_id, topic_id\ncontents:\n content_id, content_type, created_at, date, effective_date, normalized_url, sheet_id, status, title, topic_id, topic_name, updated_at, url, website_id | alsoSelect: topic_name←topic_id, title←content_id | groupable: website_id, status, topic_id, content_type | max limit 1000 (default 100) | order by index: website_id, effective_date, created_at, content_id"
},
"after": {
"type": "object",
"description": "Last row from previous page for keyset pagination. Must include values for all orderBy dims.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"limit": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Max rows to return."
},
"where": {
"allOf": [
{
"$ref": "#/definitions/Filter"
}
],
"description": "WHERE filter."
},
"fields": {
"type": "array",
"items": {
"type": "string"
},
"description": "Columns to SELECT."
},
"orderBy": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"description": "Dim or measure name, ascending."
},
{
"type": "object",
"required": [
"dim"
],
"properties": {
"dim": {
"type": "string"
},
"desc": {
"type": "boolean"
}
}
},
{
"type": "object",
"required": [
"measure"
],
"properties": {
"desc": {
"type": "boolean"
},
"measure": {
"type": "string"
}
}
}
]
},
"description": "ORDER BY. If omitted, uses cube default order."
},
"schedule": {
"anyOf": [
{
"anyOf": [
{
"enum": [
"default",
"manual"
],
"type": "string"
},
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
]
},
{
"type": "array",
"items": {
"anyOf": [
{
"enum": [
"default",
"manual"
],
"type": "string"
},
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
]
},
"maxItems": 50,
"minItems": 1
}
],
"description": "One schedule from the catalog (\"default\" or a custom/archived UUID), or an array of them to combine their data. Omit to use the caller default. The retired \"manual\" token is accepted as a deprecated alias of \"default\". Website-level cubes are unaffected."
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "The website to query. Must be a website your credentials can access."
}
},
"definitions": {
"Filter": {
"type": "object",
"properties": {
"OR": {
"type": "array",
"items": {
"$ref": "#/definitions/Filter"
},
"minItems": 1
},
"AND": {
"anyOf": [
{
"$ref": "#/definitions/Filter"
},
{
"type": "array",
"items": {
"$ref": "#/definitions/Filter"
},
"minItems": 1
}
]
},
"NOT": {
"allOf": [
{
"$ref": "#/definitions/Filter"
}
]
}
},
"description": "Prisma-style filter. A bare scalar value on a dim is shorthand for `eq` (e.g. `{ is_website: true }`); bare arrays and op-less objects throw — use `{ in: [...] }` / `{ hasSome: [...] }` explicitly. Operators: eq, neq, in, notIn, gt, gte, lt, lte, isNull, like, ilike, startsWith, hasSome, hasEvery, hasNone. Combinators: AND, OR, NOT. On semi-join dims (e.g. `response_mentions_entity`, `prompt_tag_ids`), `hasSome`/`in` emit `IN (SELECT …)` and `hasNone`/`notIn` emit `NOT IN (SELECT …)`; combine both on one dim to express \"includes any of A but none of B\". Empty `AND: []` / `OR: []` throw (the math identities are asymmetric — drop the clause before passing). Empty list operators (`hasSome: []` / `hasNone: []` / `hasEvery: []`) also throw — drop the predicate or supply at least one value. NOT accepts a single Filter only — for arrays use `NOT: { AND: [...] }` (`not all`) or `NOT: { OR: [...] }` (`none`). NOT keeps rows whose value is NULL: `NOT { sentiment: { eq: \"positive\" } }` returns unanalyzed responses as well as negative and neutral ones, because \"not positive\" is true of a row with no sentiment. Exclude them explicitly with `AND: [{ NOT: {...} }, { sentiment: { isNull: false } }]`.",
"additionalProperties": {}
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"rows",
"nextCursor",
"hasMore"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"notice": {
"type": "string"
},
"hasMore": {
"type": "boolean"
},
"nextCursor": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "Query rows",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}| one of ["asc","desc"] |
| source_tags_operator | string | How source_tags combine: "is_any_of" (default) keeps sources with any listed tag, "is_not_any_of" drops them, "has_all_of" keeps sources carrying every listed tag. |
| competitors_mentioned | string | one of ["yes","no"] |
{
"name": "get_sources",
"description": "List top cited sources (root domains) for a website with citation, mention, brand-mention, and impression metrics. Each row is classified as owned / competitor / partner / third_party. Supports filters (date range, models, prompts, competitors, locations, personas), source_tags (tag IDs from source_tags__list, owned, competitor, other, untagged), sort, and pagination via page_num / page_size.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"filters"
],
"properties": {
"search": {
"type": [
"string",
"null"
]
},
"filters": {
"type": "object",
"required": [
"start_date"
],
"properties": {
"models": {
"type": "array",
"items": {
"enum": [
"chatgpt",
"perplexity",
"gemini",
"google_ai_overview",
"copilot",
"claude",
"ai_mode",
"grok",
"deepseek",
"meta_ai",
"mistral"
],
"type": "string"
},
"description": "AI models to include, as an array even for one model — e.g. [\"chatgpt\", \"perplexity\"]. Omit to include all models."
},
"end_date": {
"type": "string",
"description": "End of the date range, inclusive. Date-only values include the UTC day through 23:59:59.999; timestamps keep their exact instant. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"prompt_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Prompt UUIDs to filter to, as an array even for one id. Omit for all prompts."
},
"start_date": {
"type": "string",
"description": "Start of the date range. Required. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"persona_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Persona UUIDs to filter to, as an array even for one id. Omit for all personas."
},
"prompt_tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Prompt tag IDs to filter prompts by, as an array (list tags with get_prompt_tags). Omit for all tags."
},
"prompt_type": {
"enum": [
"branded",
"non_branded"
],
"type": "string",
"description": "Filter prompts by type: \"branded\" (mentions the brand) or \"non_branded\". Omit for both."
},
"schedule_id": {
"anyOf": [
{
"enum": [
"default",
"manual"
],
"type": "string"
},
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
],
"description": "One schedule: \"default\" or a custom/archived schedule UUID. Omit for Default, which includes all pre-cutover history and ad hoc runs. The retired \"manual\" token is accepted as an alias of \"default\". Schedules cannot be combined."
},
"location_ids": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "string",
"const": "no-location"
}
]
},
"description": "Location UUIDs to filter to, as an array even for one id. The literal string \"no-location\" selects responses that ran without a location. Omit for all locations."
},
"prompt_status": {
"enum": [
"active",
"paused"
],
"type": "string",
"description": "Filter prompts by tracking status: \"active\" or \"paused\". Omit for both."
},
"competitor_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Competitor UUIDs to filter to, as an array even for one id. Omit for all competitors."
},
"variation_filter": {
"type": "array",
"items": {
"enum": [
"variation",
"prompt"
],
"type": "string"
},
"description": "Which prompt rows to include, as an array: \"prompt\" for base prompts, \"variation\" for generated variations, or both. Omit for both."
},
"target_identifiers": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "string",
"const": "no-identifier"
}
]
},
"description": "Target identifier strings to filter to, as an array even for one value. The literal string \"no-identifier\" selects responses with no target identifier. Omit for all."
},
"prompt_tags_operator": {
"enum": [
"is_any_of",
"has_all_of"
],
"type": "string",
"description": "How prompt_tags combine: \"is_any_of\" matches prompts with any listed tag, \"has_all_of\" only prompts carrying every listed tag."
}
}
},
"page_num": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0
},
"mentioned": {
"enum": [
"yes",
"no"
],
"type": "string"
},
"page_size": {
"type": "integer",
"default": 30,
"maximum": 100,
"minimum": 1
},
"sort_field": {
"enum": [
"citation_percentage",
"mention_percentage",
"competitor_mention_percentage",
"brand_mention_percentage",
"estimated_impressions",
"total_mentions",
"domain_count",
"mentions_count",
"root_domain",
"response_count",
"first_seen"
],
"type": "string",
"default": "citation_percentage"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"source_tags": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"enum": [
"owned",
"competitor",
"other",
"untagged"
],
"type": "string"
}
]
},
"description": "Source tags to filter by, as an array: tag IDs from source_tags__list (built-in tags such as Media or PR Wire, and custom tags), \"owned\", \"competitor\", \"other\" (sources the Tags column badges Other) or \"untagged\" (sources with no tag). Omit for all sources."
},
"sort_direction": {
"enum": [
"asc",
"desc"
],
"type": "string",
"default": "desc"
},
"source_tags_operator": {
"enum": [
"is_any_of",
"is_not_any_of",
"has_all_of"
],
"type": "string",
"description": "How source_tags combine: \"is_any_of\" (default) keeps sources with any listed tag, \"is_not_any_of\" drops them, \"has_all_of\" keeps sources carrying every listed tag."
},
"competitors_mentioned": {
"enum": [
"yes",
"no"
],
"type": "string"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"sources",
"pagination"
],
"properties": {
"notice": {
"type": "string"
},
"sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"root_domain",
"total_mentions",
"response_count",
"estimated_impressions",
"domain_count",
"mention_percentage",
"citation_percentage",
"competitor_mention_percentage",
"brand_mention_percentage",
"mentions_count",
"responses_mentioned_count",
"competitor_ids",
"default_source_type",
"source_type_ids",
"first_seen"
],
"properties": {
"first_seen": {
"type": "string"
},
"root_domain": {
"type": "string"
},
"domain_count": {
"type": "number"
},
"competitor_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"mentions_count": {
"type": "number"
},
"response_count": {
"type": "number"
},
"total_mentions": {
"type": "number"
},
"source_type_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"mention_percentage": {
"type": "number"
},
"citation_percentage": {
"type": "number"
},
"default_source_type": {
"enum": [
"owned",
"competitor",
"partner",
"third_party"
],
"type": "string"
},
"estimated_impressions": {
"type": "number"
},
"brand_mention_percentage": {
"type": "number"
},
"responses_mentioned_count": {
"type": "number"
},
"competitor_mention_percentage": {
"type": "number"
}
},
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"required": [
"page_num",
"page_size",
"total"
],
"properties": {
"total": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"page_num": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"page_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get sources",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}| one of ["asc","desc"] |
| source_tags_operator | string | How source_tags combine: "is_any_of" (default) keeps sources with any listed tag, "is_not_any_of" drops them, "has_all_of" keeps sources carrying every listed tag. |
| competitors_mentioned | string | one of ["yes","no"] |
{
"name": "get_source_pages",
"description": "List individual cited URLs (pages) for a website with citation, mention, and impression metrics plus a per-URL daily sparkline. Each row is classified as owned / competitor / partner / third_party. Companion to get_sources (root-domain-level). Supports filters (date range, models, prompts, competitors, locations, personas), source_tags (tag IDs from source_tags__list, owned, competitor, other, untagged), search, sort, and pagination.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"filters"
],
"properties": {
"search": {
"type": [
"string",
"null"
]
},
"filters": {
"type": "object",
"required": [
"start_date"
],
"properties": {
"models": {
"type": "array",
"items": {
"enum": [
"chatgpt",
"perplexity",
"gemini",
"google_ai_overview",
"copilot",
"claude",
"ai_mode",
"grok",
"deepseek",
"meta_ai",
"mistral"
],
"type": "string"
},
"description": "AI models to include, as an array even for one model — e.g. [\"chatgpt\", \"perplexity\"]. Omit to include all models."
},
"end_date": {
"type": "string",
"description": "End of the date range, inclusive. Date-only values include the UTC day through 23:59:59.999; timestamps keep their exact instant. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"prompt_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Prompt UUIDs to filter to, as an array even for one id. Omit for all prompts."
},
"start_date": {
"type": "string",
"description": "Start of the date range. Required. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"persona_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Persona UUIDs to filter to, as an array even for one id. Omit for all personas."
},
"prompt_tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Prompt tag IDs to filter prompts by, as an array (list tags with get_prompt_tags). Omit for all tags."
},
"prompt_type": {
"enum": [
"branded",
"non_branded"
],
"type": "string",
"description": "Filter prompts by type: \"branded\" (mentions the brand) or \"non_branded\". Omit for both."
},
"schedule_id": {
"anyOf": [
{
"enum": [
"default",
"manual"
],
"type": "string"
},
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
],
"description": "One schedule: \"default\" or a custom/archived schedule UUID. Omit for Default, which includes all pre-cutover history and ad hoc runs. The retired \"manual\" token is accepted as an alias of \"default\". Schedules cannot be combined."
},
"location_ids": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "string",
"const": "no-location"
}
]
},
"description": "Location UUIDs to filter to, as an array even for one id. The literal string \"no-location\" selects responses that ran without a location. Omit for all locations."
},
"prompt_status": {
"enum": [
"active",
"paused"
],
"type": "string",
"description": "Filter prompts by tracking status: \"active\" or \"paused\". Omit for both."
},
"competitor_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Competitor UUIDs to filter to, as an array even for one id. Omit for all competitors."
},
"variation_filter": {
"type": "array",
"items": {
"enum": [
"variation",
"prompt"
],
"type": "string"
},
"description": "Which prompt rows to include, as an array: \"prompt\" for base prompts, \"variation\" for generated variations, or both. Omit for both."
},
"target_identifiers": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "string",
"const": "no-identifier"
}
]
},
"description": "Target identifier strings to filter to, as an array even for one value. The literal string \"no-identifier\" selects responses with no target identifier. Omit for all."
},
"prompt_tags_operator": {
"enum": [
"is_any_of",
"has_all_of"
],
"type": "string",
"description": "How prompt_tags combine: \"is_any_of\" matches prompts with any listed tag, \"has_all_of\" only prompts carrying every listed tag."
}
}
},
"page_num": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0
},
"mentioned": {
"enum": [
"yes",
"no"
],
"type": "string"
},
"page_size": {
"type": "integer",
"default": 30,
"maximum": 100,
"minimum": 1
},
"sort_field": {
"enum": [
"citation_percentage",
"estimated_impressions",
"total_mentions",
"mentions_count",
"normalized_url",
"competitor_ids",
"first_seen"
],
"type": "string",
"default": "citation_percentage"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"source_tags": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"enum": [
"owned",
"competitor",
"other",
"untagged"
],
"type": "string"
}
]
},
"description": "Source tags to filter by, as an array: tag IDs from source_tags__list (built-in tags such as Media or PR Wire, and custom tags), \"owned\", \"competitor\", \"other\" (sources the Tags column badges Other) or \"untagged\" (sources with no tag). Omit for all sources."
},
"sort_direction": {
"enum": [
"asc",
"desc"
],
"type": "string",
"default": "desc"
},
"source_tags_operator": {
"enum": [
"is_any_of",
"is_not_any_of",
"has_all_of"
],
"type": "string",
"description": "How source_tags combine: \"is_any_of\" (default) keeps sources with any listed tag, \"is_not_any_of\" drops them, \"has_all_of\" keeps sources carrying every listed tag."
},
"competitors_mentioned": {
"enum": [
"yes",
"no"
],
"type": "string"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"pages",
"pagination"
],
"properties": {
"pages": {
"type": "array",
"items": {
"type": "object",
"required": [
"normalized_url",
"domain",
"root_domain",
"normalized_root_domain",
"total_mentions",
"estimated_impressions",
"citation_percentage",
"mentions_count",
"competitor_ids",
"default_source_type",
"source_type_ids",
"first_seen",
"daily_mentions"
],
"properties": {
"domain": {
"type": "string"
},
"first_seen": {
"type": "string"
},
"root_domain": {
"type": "string"
},
"competitor_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"daily_mentions": {
"type": "array",
"items": {
"type": "object",
"required": [
"date",
"citation_percentage"
],
"properties": {
"date": {
"type": "string"
},
"citation_percentage": {
"type": "number"
}
},
"additionalProperties": false
}
},
"mentions_count": {
"type": "number"
},
"normalized_url": {
"type": "string"
},
"total_mentions": {
"type": "number"
},
"source_type_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"citation_percentage": {
"type": "number"
},
"default_source_type": {
"enum": [
"owned",
"competitor",
"partner",
"third_party"
],
"type": "string"
},
"estimated_impressions": {
"type": "number"
},
"normalized_root_domain": {
"type": "string"
}
},
"additionalProperties": false
}
},
"notice": {
"type": "string"
},
"pagination": {
"type": "object",
"required": [
"page_num",
"page_size",
"total"
],
"properties": {
"total": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"page_num": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"page_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get source pages",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}| website_id * | string |
| attribute_ids | array | Attribute UUIDs to filter to (from get_attributes), as an array even for one id. Omit for every active attribute. |
{
"name": "get_attribute_observations",
"description": "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.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"filters"
],
"properties": {
"sort": {
"enum": [
"intensity",
"recent"
],
"type": "string",
"default": "intensity",
"description": "\"intensity\" (default): strongest first, unscored last, then newest. \"recent\": newest first."
},
"filters": {
"type": "object",
"required": [
"start_date"
],
"properties": {
"models": {
"type": "array",
"items": {
"enum": [
"chatgpt",
"perplexity",
"gemini",
"google_ai_overview",
"copilot",
"claude",
"ai_mode",
"grok",
"deepseek",
"meta_ai",
"mistral"
],
"type": "string"
},
"description": "AI models to include, as an array even for one model — e.g. [\"chatgpt\", \"perplexity\"]. Omit to include all models."
},
"end_date": {
"type": "string",
"description": "End of the date range, inclusive. Date-only values include the UTC day through 23:59:59.999; timestamps keep their exact instant. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"prompt_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Prompt UUIDs to filter to, as an array even for one id. Omit for all prompts."
},
"start_date": {
"type": "string",
"description": "Start of the date range. Required. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected."
},
"persona_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Persona UUIDs to filter to, as an array even for one id. Omit for all personas."
},
"prompt_tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Prompt tag IDs to filter prompts by, as an array (list tags with get_prompt_tags). Omit for all tags."
},
"prompt_type": {
"enum": [
"branded",
"non_branded"
],
"type": "string",
"description": "Filter prompts by type: \"branded\" (mentions the brand) or \"non_branded\". Omit for both."
},
"schedule_id": {
"anyOf": [
{
"enum": [
"default",
"manual"
],
"type": "string"
},
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
],
"description": "One schedule: \"default\" or a custom/archived schedule UUID. Omit for Default, which includes all pre-cutover history and ad hoc runs. The retired \"manual\" token is accepted as an alias of \"default\". Schedules cannot be combined."
},
"location_ids": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "string",
"const": "no-location"
}
]
},
"description": "Location UUIDs to filter to, as an array even for one id. The literal string \"no-location\" selects responses that ran without a location. Omit for all locations."
},
"prompt_status": {
"enum": [
"active",
"paused"
],
"type": "string",
"description": "Filter prompts by tracking status: \"active\" or \"paused\". Omit for both."
},
"variation_filter": {
"type": "array",
"items": {
"enum": [
"variation",
"prompt"
],
"type": "string"
},
"description": "Which prompt rows to include, as an array: \"prompt\" for base prompts, \"variation\" for generated variations, or both. Omit for both."
},
"target_identifiers": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "string",
"const": "no-identifier"
}
]
},
"description": "Target identifier strings to filter to, as an array even for one value. The literal string \"no-identifier\" selects responses with no target identifier. Omit for all."
},
"prompt_tags_operator": {
"enum": [
"is_any_of",
"has_all_of"
],
"type": "string",
"description": "How prompt_tags combine: \"is_any_of\" matches prompts with any listed tag, \"has_all_of\" only prompts carrying every listed tag."
}
},
"additionalProperties": false
},
"page_num": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Zero-indexed page number. Defaults to 0."
},
"positive": {
"type": "boolean",
"description": "true for favorable observations only, false for critical ones only. Omit for both directions."
},
"page_size": {
"type": "integer",
"default": 40,
"maximum": 100,
"minimum": 1,
"description": "Rows per page, 1 to 100. Defaults to 40."
},
"entity_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"maxItems": 100,
"description": "Entity UUIDs to filter to, as an array even for one id: the website_id for the brand itself, competitor ids from get_competitors for competitors. Omit for every entity."
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"attribute_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"maxItems": 100,
"description": "Attribute UUIDs to filter to (from get_attributes), as an array even for one id. Omit for every active attribute."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"data",
"page_num",
"page_size",
"has_more"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"observation_id",
"response_id",
"entity_id",
"entity_name",
"is_website",
"attribute_id",
"attribute_name",
"positive",
"score",
"text_span",
"model",
"created_at"
],
"properties": {
"model": {
"type": "string"
},
"score": {
"type": [
"number",
"null"
]
},
"positive": {
"type": "boolean"
},
"entity_id": {
"type": "string"
},
"text_span": {
"type": "string"
},
"created_at": {
"type": "string"
},
"is_website": {
"type": "boolean"
},
"entity_name": {
"type": "string"
},
"response_id": {
"type": "string"
},
"attribute_id": {
"type": "string"
},
"attribute_name": {
"type": "string"
},
"observation_id": {
"type": "string"
}
},
"additionalProperties": false
}
},
"notice": {
"type": "string"
},
"has_more": {
"type": "boolean"
},
"page_num": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"page_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get attribute observations",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}| run_id | string |
| status | string |
| fact_id | string |
| severity | string | one of ["critical","major","minor"] |
| prompt_id | string |
| lineage_id | string |
| source_url | string |
| website_id * | string |
| response_id | string |
{
"name": "get_oracle_findings",
"description": "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. List Oracle accuracy findings for a website: places where an AI response contradicted a verified brand fact (type 'inaccuracy' or 'kb_issue', with quote, claim, and reason) or where two knowledge-base facts conflict ('kb_duplicate' / 'kb_contradiction', pairing fact_text with related_fact_text). Findings from every status are included by default (pending, acknowledged, ignored, ...), each row carrying its status — pass the status filter for pending items only. Filters (run_id, fact_id, lineage_id, response_id, prompt_id, source_url, type, kind, severity, status) AND-compose; source_url matches evidence URLs exactly after normalization (protocol and trailing slash ignored). 'total' is the pre-limit count. 'latest_run' is the newest scan of any kind and is null only when the website has never been scanned, so latest_run plus empty findings means it scanned clean, while latest_run null means never scanned, not clean. Archived findings from before the current scanner ARE included: their run carries 'is_imported': true and keeps its original started_at, so an import can be the newest run — say the history is archived rather than calling it a current scan. 'has_imported_history' is true when any such archived run exists, and every finding row carries 'run_is_imported' so archival and current rows stay distinguishable in one list. Returns status 'no_access' if the brand does not have Oracle v2; that response carries the status alone, with no counts or findings.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id"
],
"properties": {
"kind": {
"enum": [
"false",
"outdated",
"overclaim",
"underclaim",
"misattributed"
],
"type": "string"
},
"type": {
"enum": [
"inaccuracy",
"kb_issue",
"kb_duplicate",
"kb_contradiction",
"model_disagreement"
],
"type": "string"
},
"limit": {
"type": "integer",
"default": 50,
"maximum": 200,
"minimum": 1
},
"model": {
"type": "string",
"description": "Filter to one AI model by product name (ChatGPT, Claude, Gemini, Perplexity, Copilot, Muse Spark); raw identifiers also match exactly"
},
"run_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"status": {
"type": "string"
},
"fact_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"severity": {
"enum": [
"critical",
"major",
"minor"
],
"type": "string"
},
"prompt_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"lineage_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"source_url": {
"type": "string"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"response_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"status"
],
"properties": {
"total": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"notice": {
"type": "string"
},
"status": {
"enum": [
"no_access",
"ready"
],
"type": "string"
},
"findings": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"run_id",
"lineage_id",
"fact_id",
"fact_text",
"related_fact_id",
"related_fact_text",
"prompt_id",
"prompt_text",
"model",
"response_id",
"quote",
"claim",
"reason",
"type",
"kind",
"severity",
"status",
"created_at",
"evidence_urls",
"run_is_imported"
],
"properties": {
"id": {
"type": "string"
},
"kind": {
"type": [
"string",
"null"
]
},
"type": {
"type": "string"
},
"claim": {
"type": [
"string",
"null"
]
},
"model": {
"type": [
"string",
"null"
]
},
"quote": {
"type": [
"string",
"null"
]
},
"reason": {
"type": [
"string",
"null"
]
},
"run_id": {
"type": "string"
},
"status": {
"type": "string"
},
"fact_id": {
"type": "string"
},
"severity": {
"type": "string"
},
"fact_text": {
"type": [
"string",
"null"
]
},
"grounding": {
"anyOf": [
{
"type": "object",
"required": [
"kind",
"statement",
"confirmationId",
"sourceFindingId",
"facts"
],
"properties": {
"kind": {
"type": "string",
"const": "confirmed_statement"
},
"facts": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"text"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"text": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
},
"minItems": 1
},
"statement": {
"type": "string",
"minLength": 1
},
"confirmationId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"sourceFindingId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "When present, the complete team-confirmed statement and ALL supporting facts are the evidence. The legacy fact ID and text are only a compatibility anchor, not independent proof."
},
"prompt_id": {
"type": [
"string",
"null"
]
},
"created_at": {
"type": "string"
},
"lineage_id": {
"type": "string"
},
"prompt_text": {
"type": [
"string",
"null"
]
},
"response_id": {
"type": [
"string",
"null"
]
},
"evidence_urls": {
"type": "array",
"items": {
"type": "string"
}
},
"related_fact_id": {
"type": [
"string",
"null"
]
},
"run_is_imported": {
"type": "boolean"
},
"related_fact_text": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
},
"latest_run": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"status",
"started_at",
"finished_at",
"is_imported"
],
"properties": {
"id": {
"type": "string"
},
"status": {
"type": "string"
},
"started_at": {
"type": "string"
},
"finished_at": {
"type": [
"string",
"null"
]
},
"is_imported": {
"type": "boolean"
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"has_imported_history": {
"type": "boolean"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get oracle findings",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}{
"name": "create_brand_kit",
"description": "Create a brand kit from text the user provides: a name, guidance text per field (voice is the writing direction), voice settings and writing rules, all authored by the caller; nothing is generated. The kit starts as a draft; content generation uses it only once published, which publish: true does as version 1 (or update_brand_kit later). The website's first kit becomes its default. A name another kit uses is refused; a rule that contradicts an existing global rule is refused with the explanation and no kit is created. Kit rules need the writing rules feature on the plan. To change an existing kit, use update_brand_kit; to generate a kit from the website or uploaded documents, use the Brand Profile page.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "The kit's name, unique on the website."
},
"rules": {
"type": "object",
"properties": {
"add": {
"type": "array",
"items": {
"type": "object",
"required": [
"text"
],
"properties": {
"text": {
"type": "string",
"maxLength": 2000,
"minLength": 1,
"description": "One writing rule, as an instruction to the writer."
},
"category": {
"type": "string",
"maxLength": 100,
"description": "A short grouping label; \"\" clears it."
}
},
"additionalProperties": false
}
}
},
"description": "Writing rules for this kit.",
"additionalProperties": false
},
"publish": {
"type": "boolean",
"description": "true publishes the new kit as version 1 so content generation can use it. Only when the user asked to publish."
},
"guidance": {
"type": "array",
"items": {
"type": "object",
"required": [
"field",
"text"
],
"properties": {
"text": {
"type": "string",
"maxLength": 12000,
"minLength": 1,
"description": "The field's text. Markdown paragraphs, headings, bullets and numbered items are kept as structure."
},
"field": {
"enum": [
"voice",
"audience",
"perspective",
"author",
"terminology",
"channel",
"locale",
"disclosures"
],
"type": "string",
"description": "voice is the writing direction; the others are audience, perspective (point of view), author (author guidance), terminology, channel (format and channel), locale (language and locale), disclosures (claims and disclosures)."
}
},
"additionalProperties": false
},
"description": "Guidance text per field, one entry per field."
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"voice_settings": {
"type": "object",
"properties": {
"humor": {
"anyOf": [
{
"type": "integer",
"maximum": 5,
"minimum": 1
},
{
"type": "string",
"const": "auto"
}
]
},
"stance": {
"anyOf": [
{
"type": "integer",
"maximum": 5,
"minimum": 1
},
{
"type": "string",
"const": "auto"
}
]
},
"formality": {
"anyOf": [
{
"type": "integer",
"maximum": 5,
"minimum": 1
},
{
"type": "string",
"const": "auto"
}
]
},
"expression": {
"anyOf": [
{
"type": "integer",
"maximum": 5,
"minimum": 1
},
{
"type": "string",
"const": "auto"
}
]
},
"technicality": {
"anyOf": [
{
"type": "integer",
"maximum": 5,
"minimum": 1
},
{
"type": "string",
"const": "auto"
}
]
}
},
"description": "Each 1 (formality: casual, expression: reserved, humor: serious, stance: neutral, technicality: plain) to 5 (formal, expressive, playful, opinionated, technical), or \"auto\" to let the writer decide. Omitted dimensions keep their value.",
"additionalProperties": false
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"kit": {
"type": "object",
"required": [
"id",
"name",
"is_default",
"draft_version",
"published_version",
"has_unpublished_changes",
"generation_status"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"name": {
"type": "string"
},
"is_default": {
"type": "boolean"
},
"draft_version": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"generation_status": {
"anyOf": [
{
"enum": [
"generating",
"failed"
],
"type": "string"
},
{
"type": "null"
}
]
},
"published_version": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
{
"type": "null"
}
]
},
"has_unpublished_changes": {
"type": "boolean"
}
},
"additionalProperties": false
},
"changed": {
"type": "object",
"required": [
"name",
"guidance_fields",
"voice_settings",
"rules_added",
"rules_updated",
"rules_removed"
],
"properties": {
"name": {
"type": "boolean"
},
"rules_added": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"rules_removed": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"rules_updated": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"voice_settings": {
"type": "boolean"
},
"guidance_fields": {
"type": "array",
"items": {
"enum": [
"voice",
"audience",
"perspective",
"author",
"terminology",
"channel",
"locale",
"disclosures"
],
"type": "string",
"description": "voice is the writing direction; the others are audience, perspective (point of view), author (author guidance), terminology, channel (format and channel), locale (language and locale), disclosures (claims and disclosures)."
}
}
},
"additionalProperties": false
},
"outcome": {
"enum": [
"saved",
"saved_and_published",
"saved_publish_failed"
],
"type": "string"
},
"publish_error": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "Create brand kit",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}
}| website_id * | string |
| fact_review | object |
| auto_approve | boolean | Draft mode only. Defaults to true, which continues from brief generation to article generation. Set false to pause at generated_brief until approve_brief is called. |
| brand_kit_id | string |
| pinned_claim_ids | array |
| selected_topic_ids | array |
| content_format_type | string |
| custom_instructions | string |
| use_content_memories | boolean |
| use_kb_internal_links | boolean |
| pdf_file_name_or_r2_key | string |
| scrape_additional_links | boolean |
{
"name": "create_content",
"description": "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.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"mode"
],
"properties": {
"url": {
"type": "string",
"maxLength": 2048,
"minLength": 1,
"description": "Source page URL. Required for snipe, optimize, and slice modes. A URL without a protocol, such as example.com/article, is accepted."
},
"mode": {
"enum": [
"draft",
"snipe",
"optimize",
"slice"
],
"type": "string",
"description": "draft: generate a brief and optionally an article from tracked prompts. snipe: draft an article using a competitor URL as input. optimize: improve an existing page for AI search. slice: turn one source URL into several articles."
},
"title": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Article title. Required for draft, snipe, and optimize modes."
},
"rec_id": {
"type": "string",
"maxLength": 2048
},
"kb_mode": {
"enum": [
"auto",
"manual",
"none"
],
"type": "string"
},
"rec_kind": {
"enum": [
"on_page_topic",
"on_page_snipe"
],
"type": "string"
},
"sheet_id": {
"anyOf": [
{
"type": "string",
"maxLength": 200
},
{
"type": "null"
}
]
},
"prompt_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Existing tracked prompt UUIDs, up to 100. Required and nonempty for draft; omit for slice. Use IDs from the website's tracked prompt list; never invent them."
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"fact_review": {
"type": "object",
"required": [
"topic_ids",
"kept_claim_ids",
"excluded_claim_ids"
],
"properties": {
"topic_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"kept_claim_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"excluded_claim_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"additionalProperties": false
},
"auto_approve": {
"type": "boolean",
"description": "Draft mode only. Defaults to true, which continues from brief generation to article generation. Set false to pause at generated_brief until approve_brief is called."
},
"brand_kit_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"pinned_claim_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"selected_topic_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"content_format_type": {
"type": "string",
"maxLength": 100
},
"custom_instructions": {
"type": "string",
"maxLength": 5000
},
"use_content_memories": {
"type": "boolean"
},
"use_kb_internal_links": {
"type": "boolean"
},
"pdf_file_name_or_r2_key": {
"type": "string",
"maxLength": 2048
},
"scrape_additional_links": {
"type": "boolean"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"status": {
"type": "string",
"const": "generating"
},
"content_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"slice_titles": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Generate an article or content brief",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}
}{
"name": "create_saved_view",
"description": "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\", the states \"other\" (the Other badge) and \"untagged\" (no tag), 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 / Other / No tag sources), never internal tokens, field keys, operator strings, or icon identifiers.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"name",
"filters"
],
"properties": {
"icon": {
"anyOf": [
{
"type": "string",
"maxLength": 255
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 255,
"minLength": 1
},
"filters": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"olympus_layout": {
"type": "object",
"required": [
"version",
"selectedViews",
"viewOrder",
"cardSettings"
],
"properties": {
"version": {
"type": "number",
"const": 1
},
"viewOrder": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-z][a-z0-9-]{0,79}$"
},
"maxItems": 100
},
"cardSettings": {
"type": "object",
"maxProperties": 100,
"propertyNames": {
"type": "string",
"pattern": "^[a-z][a-z0-9-]{0,79}$"
},
"additionalProperties": {
"type": "object",
"properties": {
"size": {
"type": "object",
"required": [
"colSpan",
"rowSpan"
],
"properties": {
"colSpan": {
"anyOf": [
{
"type": "number",
"const": 1
},
{
"type": "number",
"const": 2
}
]
},
"rowSpan": {
"anyOf": [
{
"type": "number",
"const": 1
},
{
"type": "number",
"const": 2
},
{
"type": "number",
"const": 3
}
]
}
},
"additionalProperties": false
},
"rateMode": {
"enum": [
"relevant",
"absolute"
],
"type": "string"
},
"viewMode": {
"enum": [
"average",
"all",
"annual",
"monthly"
],
"type": "string"
},
"sovByModelMode": {
"enum": [
"brand",
"competitors"
],
"type": "string"
}
},
"additionalProperties": false
}
},
"selectedViews": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-z][a-z0-9-]{0,79}$"
},
"maxItems": 100
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"id": {
"type": "string"
},
"icon": {
"type": [
"string",
"null"
]
},
"name": {
"type": "string"
},
"filters": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"user_id": {
"type": [
"string",
"null"
]
},
"created_at": {
"type": [
"string",
"null"
]
},
"created_by": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"email",
"first_name",
"last_name",
"display_name"
],
"properties": {
"id": {
"type": "string"
},
"email": {
"type": "string"
},
"last_name": {
"type": [
"string",
"null"
]
},
"first_name": {
"type": [
"string",
"null"
]
},
"display_name": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"updated_at": {
"type": [
"string",
"null"
]
},
"website_id": {
"type": "string"
},
"olympus_layout": {
"anyOf": [
{
"type": "object",
"required": [
"version",
"selected_views",
"view_order",
"card_settings"
],
"properties": {
"version": {
"type": "number",
"const": 1
},
"view_order": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-z][a-z0-9-]{0,79}$"
}
},
"card_settings": {
"type": "object",
"propertyNames": {
"type": "string",
"pattern": "^[a-z][a-z0-9-]{0,79}$"
},
"additionalProperties": {
"type": "object",
"properties": {
"size": {
"type": "object",
"required": [
"col_span",
"row_span"
],
"properties": {
"col_span": {
"anyOf": [
{
"type": "number",
"const": 1
},
{
"type": "number",
"const": 2
}
]
},
"row_span": {
"anyOf": [
{
"type": "number",
"const": 1
},
{
"type": "number",
"const": 2
},
{
"type": "number",
"const": 3
}
]
}
},
"additionalProperties": false
},
"rate_mode": {
"enum": [
"relevant",
"absolute"
],
"type": "string"
},
"view_mode": {
"enum": [
"average",
"all",
"annual",
"monthly"
],
"type": "string"
},
"sov_by_model_mode": {
"enum": [
"brand",
"competitors"
],
"type": "string"
}
},
"additionalProperties": false
}
},
"selected_views": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-z][a-z0-9-]{0,79}$"
}
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"creator_has_access": {
"type": [
"boolean",
"null"
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "Create saved view",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
}
}{
"name": "get_credit_usage_events",
"description": "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.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id"
],
"properties": {
"limit": {
"type": "integer",
"maximum": 50,
"minimum": 1
},
"range": {
"enum": [
"24h",
"7d",
"30d",
"90d",
"all"
],
"type": "string"
},
"offset": {
"type": "integer",
"maximum": 1000000,
"minimum": 0
},
"window": {
"type": "object",
"required": [
"start_at_utc",
"end_at_utc"
],
"properties": {
"end_at_utc": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
},
"start_at_utc": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
}
},
"description": "Explicit UTC interval within recorded history, ending no later than now. For the current month or today, use the current UTC time as endAtUtc, not the next calendar boundary. Reuse both returned boundaries when paging.",
"additionalProperties": false
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"originating_website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "Optional originating website in this organization; this is different from the charged group pool."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"limit": {
"type": "number"
},
"events": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"timestamp_utc",
"credits_used",
"website_id",
"website_name",
"charged_entity_id",
"charged_entity_name",
"charged_entity_kind",
"action",
"action_label"
],
"properties": {
"id": {
"type": "string"
},
"action": {
"type": [
"string",
"null"
]
},
"website_id": {
"type": [
"string",
"null"
]
},
"action_label": {
"type": "string"
},
"credits_used": {
"type": "number"
},
"website_name": {
"type": [
"string",
"null"
]
},
"timestamp_utc": {
"type": "string"
},
"charged_entity_id": {
"type": [
"string",
"null"
]
},
"charged_entity_kind": {
"anyOf": [
{
"enum": [
"website",
"group",
"organization"
],
"type": "string"
},
{
"type": "null"
}
]
},
"charged_entity_name": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
},
"offset": {
"type": "number"
},
"window": {
"type": "object",
"required": [
"start_at_utc",
"end_at_utc"
],
"properties": {
"end_at_utc": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
},
"start_at_utc": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
}
},
"additionalProperties": false
},
"has_more": {
"type": "boolean"
},
"next_offset": {
"type": "number"
},
"attribution_note": {
"type": "string"
},
"originating_website_id": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get credit usage events",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}| Groups per page, 25 by default and 200 at most (25 at most when a tool calls it). |
| page_urls | array | Only issues on these pages, up to 50, in the stored URL form: no protocol, no trailing slash, www kept. |
| website_id * | string |
{
"name": "get_site_health_issues",
"description": "List a website's Site Health issues: one group per kind of problem (check) with its title, why it matters, severity (critical, warning, opportunity), priority (high, medium, low), owner (writer, developer or either; null when unknown), effort (minutes, hours, days), whether it is site-wide, counts of affected pages by status (open, in_progress, fixed, verified, dismissed), up to three sections it concentrates in, and sample affected pages with each page's detail, recommendation, evidence, assignee and task_revision. Filter by status, check, a search term, the stored URLs of specific pages (page_urls), or assignee \"me\" (signed-in connections only). Groups are paged: page is 0-based, page_size defaults to 25 (max 200) and total counts the groups that match; counts totals pages by status across the whole site, ignoring the status filter. A group carries at most 50 sample pages (10 when a tool calls it, which also caps page_size at 25); has_more_pages says to read the rest with the issue pages read (get_site_health_issue_pages or POST /v1/seo/issues/pages), whose page 0 repeats the sample pages. has_evidence false means the site has never been crawled or audited. Requires Site Health on the website's plan; otherwise the call fails with 403.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id"
],
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Zero-based page of groups."
},
"check": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "One check id, as `check` names it in an earlier result."
},
"search": {
"type": "string",
"maxLength": 200,
"description": "Matches the issue title or an affected page URL."
},
"status": {
"enum": [
"open",
"in_progress",
"fixed",
"verified",
"dismissed"
],
"type": "string",
"description": "Only groups with at least one page in this status. Group and site counts ignore it."
},
"assignee": {
"type": "string",
"const": "me",
"description": "Only pages assigned to the signed-in user. Not available to API keys."
},
"page_size": {
"type": "integer",
"maximum": 200,
"minimum": 1,
"description": "Groups per page, 25 by default and 200 at most (25 at most when a tool calls it)."
},
"page_urls": {
"type": "array",
"items": {
"type": "string",
"maxLength": 2048
},
"description": "Only issues on these pages, up to 50, in the stored URL form: no protocol, no trailing slash, www kept."
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"total": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"counts": {
"type": "object",
"required": [
"open",
"in_progress",
"fixed",
"verified"
],
"properties": {
"open": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"fixed": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"verified": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"dismissed": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"in_progress": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
}
},
"additionalProperties": false
},
"groups": {
"type": "array",
"items": {
"type": "object",
"required": [
"check",
"title",
"why_it_matters",
"owner",
"effort",
"bucket",
"severity",
"priority",
"site_wide",
"counts",
"sections",
"pages",
"has_more_pages"
],
"properties": {
"check": {
"type": "string"
},
"owner": {
"anyOf": [
{
"enum": [
"writer",
"developer",
"either"
],
"type": "string"
},
{
"type": "null"
}
]
},
"pages": {
"type": "array",
"items": {
"type": "object",
"required": [
"finding_id",
"page_id",
"property_id",
"url",
"status",
"page_title",
"detail",
"recommendation",
"shared_value",
"evidence",
"evidence_links",
"robots_txt_rule",
"first_seen_at",
"last_seen_at",
"resolved_at",
"last_checked_at",
"assignee",
"task_revision",
"draft"
],
"properties": {
"url": {
"type": "string"
},
"draft": {
"anyOf": [
{
"type": "object",
"required": [
"run_id",
"status"
],
"properties": {
"run_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"status": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"detail": {
"type": "string"
},
"status": {
"enum": [
"open",
"in_progress",
"fixed",
"verified",
"dismissed"
],
"type": "string"
},
"page_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"assignee": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"evidence": {
"type": "array",
"items": {
"type": "string"
}
},
"finding_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"page_title": {
"type": [
"string",
"null"
]
},
"property_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"resolved_at": {
"type": [
"string",
"null"
]
},
"last_seen_at": {
"type": "string"
},
"shared_value": {
"type": [
"string",
"null"
]
},
"first_seen_at": {
"type": "string"
},
"task_revision": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"evidence_links": {
"type": "array",
"items": {
"type": "object",
"required": [
"label",
"url"
],
"properties": {
"url": {
"type": "string"
},
"label": {
"type": "string"
}
},
"additionalProperties": false
}
},
"recommendation": {
"type": [
"string",
"null"
]
},
"last_checked_at": {
"type": [
"string",
"null"
]
},
"robots_txt_rule": {
"anyOf": [
{
"type": "object",
"required": [
"url",
"line",
"excerpt"
],
"properties": {
"url": {
"type": "string"
},
"line": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
"excerpt": {
"type": "array",
"items": {
"type": "object",
"required": [
"line",
"text"
],
"properties": {
"line": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
"text": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
},
"title": {
"type": "string"
},
"bucket": {
"enum": [
"technical_cleanup",
"content_restructuring",
"content_enrichment"
],
"type": "string"
},
"counts": {
"type": "object",
"required": [
"open",
"in_progress",
"fixed",
"verified"
],
"properties": {
"open": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"fixed": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"verified": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"dismissed": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"in_progress": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
}
},
"additionalProperties": false
},
"effort": {
"anyOf": [
{
"enum": [
"minutes",
"hours",
"days"
],
"type": "string"
},
{
"type": "null"
}
]
},
"priority": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"sections": {
"type": "array",
"items": {
"type": "object",
"required": [
"section",
"open",
"audited"
],
"properties": {
"open": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"audited": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"section": {
"type": "string"
}
},
"additionalProperties": false
}
},
"severity": {
"enum": [
"critical",
"warning",
"opportunity"
],
"type": "string"
},
"site_wide": {
"type": "boolean"
},
"has_more_pages": {
"type": "boolean"
},
"why_it_matters": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
},
"page_size": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
"has_evidence": {
"type": "boolean"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get site health issues",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}{
"name": "source_tags__list",
"description": "Read every source tag this website sees: Owned and Competitor (entity), the built-in classes AthenaHQ classifies automatically (platform: Media, Social, Government, E-Commerce, Review sites, PR Wire, Academic and research, Wiki) and the website's custom tags. Built-in tags list only what this website added or removed, never the platform's own patterns; custom tags list their patterns. Read this before proposing, creating, editing or deleting tags, and prefer adding hosts to a built-in tag over creating a near-duplicate. To find sources no tag covers, call source_tags__get_sources with untagged true. The Source Tag filter also takes two values that are not tags and are not listed here: 'other' (sources the Tags column badges Other) and 'untagged' (sources with no tag). Filter by name substring or tag ID; page tags with offset, page one tag's patterns with tag ID and pattern offset.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id"
],
"properties": {
"limit": {
"type": "integer",
"maximum": 50,
"minimum": 1,
"description": "Tags per page: 1 through 50, default 20. Use offset for the next page."
},
"query": {
"type": "string",
"maxLength": 255,
"description": "Optional tag-name substring. Omit to list all names."
},
"offset": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"tag_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "Actual UUID returned by this tool. Omit to list all tags; never use a placeholder."
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"pattern_limit": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"description": "Patterns per tag: 1 through 500, default 50."
},
"pattern_offset": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"tags": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"kind",
"icon",
"color",
"editable",
"deletable",
"patterns",
"removed_patterns",
"revision",
"pattern_count",
"has_more_patterns"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"icon": {
"type": [
"string",
"null"
]
},
"kind": {
"enum": [
"entity",
"platform",
"custom"
],
"type": "string"
},
"name": {
"type": "string"
},
"color": {
"type": "string"
},
"editable": {
"type": "boolean"
},
"patterns": {
"type": "array",
"items": {
"type": "string"
}
},
"revision": {
"type": "string"
},
"deletable": {
"type": "boolean"
},
"pattern_count": {
"type": "number"
},
"removed_patterns": {
"type": "array",
"items": {
"type": "string"
}
},
"has_more_patterns": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"total": {
"type": "number"
},
"has_more": {
"type": "boolean"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Source tags list",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}{
"name": "source_tags__update",
"description": "Edit a source tag. Custom tag: rename, add patterns, remove exact patterns from the listing. Built-in tag (platform): add patterns to this website's copy so they carry the tag here, or remove patterns so they stop carrying it here; a removal is accepted only for a pattern the tag currently applies to (by a platform rule, by automatic classification, or by your own addition), and an addition is accepted only when the pattern does not already carry the tag. Owned and Competitor cannot be edited here; their patterns live in Brand Profile and Competitors. Read the listing first and pass the tag's revision as expected-revision. Obtain explicit user confirmation of the exact changes before calling; MCP executes immediately after authorization; Athena AI chat presents an approval card. If the tag changed, read again. Never retry a declined proposal unless asked. Up to 500 additions and 500 removals. A false analytics-refresh result means the edit saved but filtered analytics may still be cached.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"tag_id",
"expected_revision"
],
"properties": {
"name": {
"type": "string",
"maxLength": 255,
"minLength": 1,
"description": "Custom tag name. Names of built-in tags (Media, Social, Government, …) and of Owned and Competitor are reserved."
},
"tag_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"add_patterns": {
"type": "array",
"items": {
"type": "string",
"maxLength": 2048,
"minLength": 1,
"description": "Host (example.com), subtree (*.example.com), path section (example.com/blog), exact page (example.com/blog$) or query constraint (youtube.com/watch?v=abc)."
}
},
"remove_patterns": {
"type": "array",
"items": {
"type": "string",
"maxLength": 2048,
"minLength": 1
}
},
"expected_revision": {
"type": "string",
"maxLength": 64,
"minLength": 64
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"icon": {
"type": [
"string",
"null"
]
},
"kind": {
"enum": [
"entity",
"platform",
"custom"
],
"type": "string"
},
"name": {
"type": "string"
},
"added": {
"type": "array",
"items": {
"type": "string"
}
},
"color": {
"type": "string"
},
"before": {
"type": "object",
"required": [
"id",
"name",
"kind",
"icon",
"color",
"editable",
"deletable",
"patterns",
"removed_patterns",
"revision"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"icon": {
"type": [
"string",
"null"
]
},
"kind": {
"enum": [
"entity",
"platform",
"custom"
],
"type": "string"
},
"name": {
"type": "string"
},
"color": {
"type": "string"
},
"editable": {
"type": "boolean"
},
"patterns": {
"type": "array",
"items": {
"type": "string"
}
},
"revision": {
"type": "string"
},
"deletable": {
"type": "boolean"
},
"removed_patterns": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"removed": {
"type": "array",
"items": {
"type": "string"
}
},
"editable": {
"type": "boolean"
},
"patterns": {
"type": "array",
"items": {
"type": "string"
}
},
"revision": {
"type": "string"
},
"deletable": {
"type": "boolean"
},
"removed_patterns": {
"type": "array",
"items": {
"type": "string"
}
},
"analytics_refreshed": {
"type": "boolean"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Source tags update",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": true
}
}| string |
| Required when brand_guidelines (Custom instructions) is selected. Focus discovery on the customer's requested topics. |
{
"name": "start_prompt_discovery",
"description": "Start a Discover study to find evidence-grounded, untracked prompt opportunities for a website. Invoke after explicit user intent to start research and review the sources, country, language, requested prompt count and custom instructions with the user. This launches asynchronous external research and model calls; the prompt count is a target, not a guaranteed yield. Sources: website_analysis (website), social (market discussions), search_console (connected Search Console), keyword_gaps (plan-gated keyword opportunities), competitive_landscape (plan-gated category questions and comparisons researched from the website's tracked competitors; requires at least one tracked competitor), brand_guidelines (requires custom instructions). Returns the run ID and version when startup succeeds. Prompts are not automatically added to tracking. Poll the discovery history/progress tool with the returned run ID; do not start another study to check status. Requires prompt-management permission and source entitlements. Candidate results can be reviewed in the application's Discover page.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"name",
"sources"
],
"properties": {
"name": {
"type": "string",
"maxLength": 255,
"minLength": 1
},
"country": {
"type": "string",
"description": "Country name or ISO code; defaults to United States."
},
"sources": {
"type": "array",
"items": {
"enum": [
"website_analysis",
"search_console",
"social",
"brand_guidelines",
"keyword_gaps",
"competitive_landscape"
],
"type": "string"
}
},
"language": {
"type": "string",
"description": "Supported locale, for example en-US. Defaults to en-US."
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"prompt_count_range": {
"type": "object",
"required": [
"min",
"max"
],
"properties": {
"max": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"min": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
}
},
"description": "Supported min/max targets: 25/50 (default), 50/75, 75/100, 100/150, or 150/200.",
"additionalProperties": false
},
"custom_instructions": {
"type": "string",
"maxLength": 10000,
"description": "Required when brand_guidelines (Custom instructions) is selected. Focus discovery on the customer's requested topics."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"run_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"version": {
"type": "string",
"const": "v2"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Start prompt discovery",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}
}| prompt_variations | integer |
{
"name": "start_response_streaming",
"description": "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_response_streaming_status over MCP or GET /api/v1/response-streaming/status over the API for progress.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id"
],
"properties": {
"prompt_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Specific tracked prompt UUIDs to run, from 1 to 1,000. Overrides schedule prompt selectors when supplied. Omit to use schedule_id selectors, or every active prompt when schedule_id is also omitted. Paused prompts are skipped."
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"schedule_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "Schedule UUID to attribute this run to and take prompt selectors from. A nonempty prompt_ids selection overrides those selectors. Omit to attribute the run to Default and run every active prompt unless prompt_ids is supplied. Explicit model, fan-out, persona and location choices apply to this run."
},
"use_personas": {
"type": "boolean"
},
"use_locations": {
"type": "boolean"
},
"only_locations": {
"type": "boolean"
},
"selected_models": {
"type": "object",
"description": "Map of model id to enabled flag, e.g. { \"chatgpt\": true, \"ai_overview\": true, \"ai_mode\": false }. Model ids: chatgpt, ai_overview (Google AI Overviews; google_ai_overview is also accepted), perplexity, gemini, copilot, ai_mode, grok, claude, deepseek, meta_ai, mistral. An id set to true that names no model is rejected. Omit to run all enabled models.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "boolean"
}
},
"prompt_variations": {
"type": "integer",
"maximum": 10,
"minimum": 0
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"status": {
"type": "string",
"const": "running"
},
"workflow_id": {
"type": "string"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Run prompts and collect AI responses",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}
}{
"name": "start_site_health_audit",
"description": "Start a Site Health audit of one property. mode full (the default) crawls the property, then audits every page the crawl leaves; a crawl already running is joined and audits when it ends. mode sample audits a few pages from every section plus the priority pages; page_ids (1 to 100) re-audits only those pages, which is how a fix is checked. Refused with 400 when the property is disabled. mode full is refused with 409 when a full audit already covers the property or a sample or page_ids audit holds it (try again once that ends). mode sample and page_ids are refused with 409 while any crawl or audit of the property runs, with 400 when the property has no pages yet, and with 404 when a page id is not in the current inventory. Returns the run id (null while a crawl runs first, since its audit run is created when the crawl ends), the property name, how many pages the run reads (in mode full, the inventory before the crawl), whether it is a sample and whether a crawl runs first. Results reach the issue list as the run progresses; the properties list shows the run's status. Requires Site Health on the website's plan; otherwise the call fails with 403.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"property_id"
],
"properties": {
"mode": {
"enum": [
"full",
"sample"
],
"type": "string",
"description": "full crawls the property first and audits every page it leaves; sample audits a few pages per section plus the priority pages."
},
"page_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Re-audit only these pages (1 to 100), from the inventory or an issue's affected pages. Overrides mode."
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"property_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "The property to audit, from the properties list."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"run_id": {
"type": [
"string",
"null"
]
},
"sample": {
"type": "boolean"
},
"page_count": {
"type": "number"
},
"crawl_first": {
"type": "boolean"
},
"property_name": {
"type": "string"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Start site health audit",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}
}{
"name": "track_content_urls",
"description": "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 pages cited in the website's monitored AI responses accrue metrics with no publish step (use it for guest posts, partner placements, or any page Athena did not generate). Idempotent per URL: a URL already present on the website (any content type) is not duplicated; the response lists it under skipped with the existing content_id and type. Check that type before chaining destructive calls (a skip can resolve to first-party generated content that shares the URL). Rows are created without page text, which citation tracking does not need; the body can be filled from the app later. Duplicate URLs within one call (including tracking-param variants of the same page) collapse to one row, first occurrence wins. Optional sheet_id files rows under a Content Hub tab; view-type tabs resolve to the main pool (null), echoed per row. Optional per-URL fields set the customer's own Content Hub columns on the created row, addressed by column name as shown on the destination tab (text, number, date, checkbox, link, and multi-select columns; unknown multi-select options are created). An unknown column name or a value that does not fit the column type rejects the whole call and nothing is tracked; skipped URLs keep their existing values. If the user names a destination tab, resolve its id with get_content_hub_sheets before tracking. Omitting sheet_id uses the shared pool, not the user's currently open tab. After the call, report created_count and skipped_count separately, name the returned destination_name, and share content_hub_url so the user can open each item. Skipped rows keep their existing tab: use their returned destination and never describe them as newly added or moved.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"urls"
],
"properties": {
"urls": {
"type": "array",
"items": {
"type": "object",
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"maxLength": 2048,
"minLength": 1
},
"title": {
"type": "string",
"maxLength": 500,
"minLength": 1
},
"fields": {
"type": "array",
"items": {
"type": "object",
"required": [
"column",
"value"
],
"properties": {
"value": {
"anyOf": [
{
"type": "string",
"maxLength": 10000
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "array",
"items": {
"type": "string",
"maxLength": 200
}
}
]
},
"column": {
"type": "string",
"maxLength": 200,
"minLength": 1
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
},
"sheet_id": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "null"
}
]
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"created": {
"type": "array",
"items": {
"type": "object",
"required": [
"content_id",
"url",
"sheet_id",
"destination_name",
"content_hub_url"
],
"properties": {
"url": {
"type": "string"
},
"sheet_id": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "null"
}
]
},
"content_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"content_hub_url": {
"type": "string",
"format": "uri",
"description": "Direct link to this Content Hub item with its website and destination selected."
},
"destination_name": {
"type": "string",
"description": "Name of the tab displaying this row, or Shared pool when no view exists."
}
},
"additionalProperties": false
}
},
"skipped": {
"type": "array",
"items": {
"type": "object",
"required": [
"content_id",
"url",
"type",
"sheet_id",
"destination_name",
"content_hub_url"
],
"properties": {
"url": {
"type": "string"
},
"type": {
"type": "string"
},
"sheet_id": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "null"
}
]
},
"content_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"content_hub_url": {
"type": "string",
"format": "uri",
"description": "Direct link to the existing item at its current location. Skipped rows are not moved."
},
"destination_name": {
"type": "string",
"description": "Existing row's destination, which may differ from the requested tab."
}
},
"additionalProperties": false
}
},
"success": {
"type": "boolean",
"const": true
},
"created_count": {
"type": "number"
},
"skipped_count": {
"type": "number"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Track content urls",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
}
}| website_id * | string |
| voice_settings | object | Each 1 (formality: casual, expression: reserved, humor: serious, stance: neutral, technicality: plain) to 5 (formal, expressive, playful, opinionated, technical), or "auto" to let the writer decide. Omitted dimensions keep their value. |
{
"name": "update_brand_kit",
"description": "Change one brand kit's name, guidance text, voice settings, or kit writing rules, and optionally publish it, under the same rules as the Brand Profile page. Call get_brand_kit first. Edits save to the kit's draft; content generation keeps using the published version until publish is true, which creates a new immutable version (the Brand Profile page can restore earlier ones). A guidance entry without find replaces the whole field with text (empty text clears it); with find, text replaces that passage, which must occur exactly once in the field text get_brand_kit returned (empty text deletes it). Voice settings take 1-5 or \"auto\"; omitted settings keep their value. Rules: add new ones, update by id (omitted fields keep their value; category \"\" clears it), or remove by id. Kit rules need the writing rules feature on the plan. A rule that contradicts an existing kit or global rule is refused with the explanation and nothing is saved; a rename to a name another kit uses is refused. When the result says the kit changed in another session, call get_brand_kit again and retry. outcome saved_publish_failed means the draft was saved but not published; publish_error says why. Global writing rules are changed with update_global_rules, not here.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"kit_id"
],
"properties": {
"name": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "A new name, unique on the website."
},
"rules": {
"type": "object",
"properties": {
"add": {
"type": "array",
"items": {
"type": "object",
"required": [
"text"
],
"properties": {
"text": {
"type": "string",
"maxLength": 2000,
"minLength": 1,
"description": "One writing rule, as an instruction to the writer."
},
"category": {
"type": "string",
"maxLength": 100,
"description": "A short grouping label; \"\" clears it."
}
},
"additionalProperties": false
}
},
"remove": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Rule ids to delete."
},
"update": {
"type": "array",
"items": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"text": {
"type": "string",
"maxLength": 2000,
"minLength": 1,
"description": "One writing rule, as an instruction to the writer."
},
"category": {
"type": "string",
"maxLength": 100,
"description": "A short grouping label; \"\" clears it."
},
"is_active": {
"type": "boolean",
"description": "false keeps the rule but stops applying it."
}
},
"additionalProperties": false
},
"description": "By id; omitted fields keep their value."
}
},
"description": "Writing rules to add, update by id, or remove by id. Ids come from get_brand_kit.",
"additionalProperties": false
},
"kit_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "The brand kit, from get_brand_kit's available_kits."
},
"publish": {
"type": "boolean",
"description": "true publishes the saved draft as a new version, which content generation uses from then on. Only when the user asked to publish."
},
"guidance": {
"type": "array",
"items": {
"type": "object",
"required": [
"field",
"text"
],
"properties": {
"find": {
"type": "string",
"maxLength": 12000,
"minLength": 1,
"description": "A passage to replace with text, copied exactly from the field text get_brand_kit returned; it must occur exactly once. Omit it to replace the whole field."
},
"text": {
"type": "string",
"maxLength": 12000,
"description": "The new text. Markdown paragraphs, headings, bullets and numbered items are kept as structure."
},
"field": {
"enum": [
"voice",
"audience",
"perspective",
"author",
"terminology",
"channel",
"locale",
"disclosures"
],
"type": "string",
"description": "voice is the writing direction; the others are audience, perspective (point of view), author (author guidance), terminology, channel (format and channel), locale (language and locale), disclosures (claims and disclosures)."
}
},
"additionalProperties": false
},
"description": "Guidance text changes, one entry per field. Without find, text replaces the whole field (empty text clears it). With find, text replaces that passage (empty text deletes it)."
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"voice_settings": {
"type": "object",
"properties": {
"humor": {
"anyOf": [
{
"type": "integer",
"maximum": 5,
"minimum": 1
},
{
"type": "string",
"const": "auto"
}
]
},
"stance": {
"anyOf": [
{
"type": "integer",
"maximum": 5,
"minimum": 1
},
{
"type": "string",
"const": "auto"
}
]
},
"formality": {
"anyOf": [
{
"type": "integer",
"maximum": 5,
"minimum": 1
},
{
"type": "string",
"const": "auto"
}
]
},
"expression": {
"anyOf": [
{
"type": "integer",
"maximum": 5,
"minimum": 1
},
{
"type": "string",
"const": "auto"
}
]
},
"technicality": {
"anyOf": [
{
"type": "integer",
"maximum": 5,
"minimum": 1
},
{
"type": "string",
"const": "auto"
}
]
}
},
"description": "Each 1 (formality: casual, expression: reserved, humor: serious, stance: neutral, technicality: plain) to 5 (formal, expressive, playful, opinionated, technical), or \"auto\" to let the writer decide. Omitted dimensions keep their value.",
"additionalProperties": false
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"kit": {
"type": "object",
"required": [
"id",
"name",
"is_default",
"draft_version",
"published_version",
"has_unpublished_changes",
"generation_status"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"name": {
"type": "string"
},
"is_default": {
"type": "boolean"
},
"draft_version": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"generation_status": {
"anyOf": [
{
"enum": [
"generating",
"failed"
],
"type": "string"
},
{
"type": "null"
}
]
},
"published_version": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
{
"type": "null"
}
]
},
"has_unpublished_changes": {
"type": "boolean"
}
},
"additionalProperties": false
},
"changed": {
"type": "object",
"required": [
"name",
"guidance_fields",
"voice_settings",
"rules_added",
"rules_updated",
"rules_removed"
],
"properties": {
"name": {
"type": "boolean"
},
"rules_added": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"rules_removed": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"rules_updated": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"voice_settings": {
"type": "boolean"
},
"guidance_fields": {
"type": "array",
"items": {
"enum": [
"voice",
"audience",
"perspective",
"author",
"terminology",
"channel",
"locale",
"disclosures"
],
"type": "string",
"description": "voice is the writing direction; the others are audience, perspective (point of view), author (author guidance), terminology, channel (format and channel), locale (language and locale), disclosures (claims and disclosures)."
}
}
},
"additionalProperties": false
},
"outcome": {
"enum": [
"saved",
"saved_and_published",
"saved_publish_failed"
],
"type": "string"
},
"publish_error": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "Update brand kit",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": true
}
}{
"name": "update_outreach_contact",
"description": "Edit a cited page's Outreach contact: author name, email, LinkedIn, or the draft's subject and body. Creates the contact when the page has none. Supply at least one field; only the fields supplied change, and null clears a field. A changed email is labeled as entered manually. Each change is recorded in the contact's activity history. Obtain user confirmation of the new values before calling.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"url"
],
"properties": {
"url": {
"type": "string",
"maxLength": 2048,
"minLength": 1,
"description": "Cited page URL, e.g. \"example.com/blog/best-tools\". A contact already saved under this exact URL (for example one the Outreach page saved for a query variant its URL rules list separately) is used first. Otherwise protocol, \"www.\" and the query string (tracking parameters) are ignored, as on the Outreach page. The page is always read at the URL given."
},
"email": {
"anyOf": [
{
"type": "string",
"maxLength": 320
},
{
"type": "null"
}
],
"description": "Email to pitch. Null clears it; omit to keep it."
},
"message": {
"anyOf": [
{
"type": "string",
"maxLength": 20000
},
{
"type": "null"
}
],
"description": "Draft body. Null clears it; omit to keep it."
},
"subject": {
"anyOf": [
{
"type": "string",
"maxLength": 500
},
{
"type": "null"
}
],
"description": "Draft subject. Null clears it; omit to keep it."
},
"linkedin": {
"anyOf": [
{
"type": "string",
"maxLength": 2048
},
{
"type": "null"
}
],
"description": "Author LinkedIn URL. Null clears it; omit to keep it."
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"author_name": {
"anyOf": [
{
"type": "string",
"maxLength": 200
},
{
"type": "null"
}
],
"description": "Author name. Null clears it; omit to keep it."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"contact": {
"type": "object",
"required": [
"url",
"status",
"author_name",
"email",
"email_source",
"page_emails",
"contact_page_url",
"linkedin",
"subject",
"message",
"assignee_email",
"created_at"
],
"properties": {
"url": {
"type": "string"
},
"email": {
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"New",
"Todo",
"In Progress",
"Done",
"Rejected"
],
"type": "string"
},
"message": {
"type": [
"string",
"null"
]
},
"subject": {
"type": [
"string",
"null"
]
},
"linkedin": {
"type": [
"string",
"null"
]
},
"created_at": {
"type": "string"
},
"author_name": {
"type": [
"string",
"null"
]
},
"page_emails": {
"type": "array",
"items": {
"type": "string"
},
"description": "Up to five addresses the page or its linked contact page publishes, the chosen one first. Not a complete inventory."
},
"email_source": {
"anyOf": [
{
"enum": [
"page_author",
"page_contact",
"hunter",
"manual"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "Where the email came from: page_author (published on the page and matches the author), page_contact (the site's own address, may not reach the author), hunter (Hunter.io match, not published on the page, check before sending), manual (entered by a person). Null when unknown."
},
"assignee_email": {
"type": [
"string",
"null"
]
},
"contact_page_url": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"created": {
"type": "boolean",
"description": "True when this call created the page's contact."
}
},
"additionalProperties": false
},
"annotations": {
"title": "Edit an Outreach contact",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": true
}
}{
"name": "update_site_health_task",
"description": "Assign one Site Health finding to a teammate or set its work status: todo, in_progress, ready_to_verify, or dismissed (not an issue, which stays closed even when a later audit finds it again). Pass the page's finding_id and task_revision from the issue list or the issue pages read as finding_id and revision; a revision that is no longer current, or a finding that has since recurred, is refused with 409, so re-read first. unassign true (or assignee_user_id null) clears the assignee; the teammate must have analytics access on the website. A newly assigned teammate is emailed. Returns the new revision with the before and after assignee and status. Signed-in connections only: an API key has no teammate to act as, so API-key connections are not offered this tool and a direct call is refused with 403. Requires Site Health on the website's plan; otherwise the call fails with 403.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"website_id",
"finding_id",
"revision"
],
"properties": {
"revision": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "The page's `task_revision` from the same read; a stale value is refused."
},
"unassign": {
"type": "boolean",
"description": "true clears the assignee. Chat tools must use this: a null assignee_user_id is dropped as unspecified. Cannot be sent with an assignee_user_id."
},
"finding_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "The finding, as `finding_id` names it on an affected page."
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"work_status": {
"enum": [
"todo",
"in_progress",
"ready_to_verify",
"dismissed"
],
"type": "string",
"description": "todo, in_progress, ready_to_verify or dismissed (not an issue)."
},
"assignee_user_id": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "null"
}
],
"description": "A teammate with analytics access on the website, as get_user_by_email or an earlier assignee.id gives it; null clears the assignee (chat tools send unassign true instead)."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"after": {
"type": "object",
"required": [
"assignee_user_id",
"work_status"
],
"properties": {
"work_status": {
"type": "string"
},
"assignee_user_id": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"check": {
"type": "string"
},
"before": {
"type": "object",
"required": [
"assignee_user_id",
"work_status"
],
"properties": {
"work_status": {
"type": "string"
},
"assignee_user_id": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"task_id": {
"type": "string"
},
"revision": {
"type": "number"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Update site health task",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
}
}