Meikai monitors and optimizes how your brand is represented across ChatGPT, Gemini, Perplexity, Grok, Copilot, and more.
Ask your favorite AI engine to check your share of voice, track which topics drive brand mentions, benchmark your visibility against competitors, analyze citation sources, or get prioritized optimization recommendations for your brand's presence in AI.
Connect Meikai to your AI assistant in a few steps.
Meikai
Meikaihttps://mcp.meikai.aiVerify: ask Claude “List my Meikai brands” or “What is our share of voice over the last 7 days?”
MeikaiOptimize your brand across AI engineshttps://mcp.meikai.aiVerify: ask ChatGPT “Show my brands in Meikai” or “Which URLs are most cited for my brand?”
MeikaiOptimize your brand across AI engineshttps://mcp.meikai.aiVerify: ask Perplexity “List my Meikai brands” or “What is our share of voice over the last 7 days?”
Meikaihttps://mcp.meikai.aiGrok auto-detects OAuth from Meikai’s MCP metadata — you do not need to enter Client ID or token URLs manually.
Verify: ask Grok “List my Meikai brands” or “Which topics drive the most brand mentions?”
Use this for any MCP client that supports OAuth over Streamable HTTP (Gemini CLI, Windsurf, or other IDE integrations).
Example — add to your client's MCP config (same OAuth block as Cursor):
{
"mcpServers": {
"meikai": {
"url": "https://mcp.meikai.ai",
"auth": {
"CLIENT_ID": "mcp",
"scopes": ["openid", "profile", "offline_access", "mcp"]
}
}
}
}
client_id=mcp).Note: ChatGPT, Claude, Perplexity, and Grok cannot reach localhost. For local Docker dev, expose the stack over HTTPS (for example a Cloudflare Quick Tunnel) and use that public URL as the MCP server URL.
Verify: ask your assistant to list your Meikai brands or fetch visibility metrics.
Use these URLs when configuring a custom client:
| Role | URL |
|---|---|
| MCP server | https://mcp.meikai.ai |
| Documentation | https://mcp.meikai.ai/docs/ |
| OAuth authorize | https://mcp.meikai.ai/oauth/authorize/ |
| OAuth token | https://mcp.meikai.ai/oauth/token/ |
| Meikai dashboard | https://admin.meikai.ai |
Browse available Meikai MCP tools by product area in the Tools tab. Each tool returns data from your workspace; most are read-only. Your AI client chooses which tools to call based on your question.
Slice by topic, funnel, platform, and date where parameters allow. Sentiment is not tracked in Brand Monitor (LLMs tend to express similar sentiment across brands); use Brand Perception tools for perception ratings.
Get daily visibility data for a brand over a date range.
Brand Monitor mentions card: average target-brand mentions per response that mentions the brand (not raw mention volume).
Get responses count metric showing the total number of LLM responses analyzed for a brand, with period-over-period comparison.
Get share of model metrics showing visibility breakdown by AI model (e.g.
Get share of platform metrics showing visibility breakdown by AI platform (e.g.
Get share of voice metrics showing what percentage of total brand mentions belong to your brand versus competitors.
Get share of voice card data showing what percentage of total brand mentions belong to your brand versus competitors, with period-over-period comparison.
Brand Monitor visibility card: share of analyzed responses that mention the target brand.
Get visibility metrics for a brand within a date range.
Get visibility ranking data showing how your brand ranks compared to competitors.
Prompt list and fanouts explain what is tested and what models search for.
Get detailed information about a specific prompt in Brand Monitor specialized format.
Get list of prompts in Brand Monitor specialized format.
Get simplified list of topics for a brand in Brand Monitor format (id + text only).
Get distinct iteration start dates for a brand.
List Prompt Studio personas available for Brand Monitor filtering.
Get query fanouts for a brand: list of prompts with the distinct web-search queries that each prompt triggered (and how often each query was used).
Media type filters use VALID_MEDIA_TYPES strings (see citation_media_types).
Get daily correlation between visibility and citation rate (Earned Media).
Get a ranked list of domains by citation rate (Earned Media).
Get the citation rate metric for the company (publisher).
Get citations with filters, pagination, and sorting.
Get distribution of citations by media type (percentages).
Get citation statistics by AI platform (Earned Media).
Get domain-level citation analysis with aggregated metrics.
Get prompts where the publisher has higher share of citations (Earned Media).
Get prompts where the publisher has lower share of citations (Earned Media).
Get the most cited URLs for the company's domain (Earned Media).
Get source of citations breakdown by media type showing where citations come from (Earned Media, Competition, Social Media, Owned Media).
Get top domains by AI platform ranked by EIVA (Estimated Incremental Visible Answers).
Older prompt/response paths; prefer Brand Monitor tools when both exist.
Get detailed information about a specific prompt by its ID.
Get all responses for a specific prompt or brand.
Get list of prompts with filters, pagination, and sorting.
Get details of a specific response by its ID.
Pair with getPixelInstallationGuide and getCDNLogsGuide for instrumentation setup.
Get verified bot traffic data from CDN logs for a brand website or a publisher company website.
Get referral traffic data from tracking_events (website traffic captured by tracking pixel) for a brand website or publisher company website.
Analyze a specific page for GEO (Generative Engine Optimization) readiness using Vertex AI grounded search with URL context.
Analyze web page content, SEO, content gaps, and provide technical recommendations using Vertex AI Grounded Search.
Demand and trend signals complement Brand Monitor outcomes.
Get the number of distinct keywords for the selected period (badge).
Get keyword momentum (lifecycle/scatter) data: keyword_share, mentions_current, mentions_prev, change_in_mentions, unique_users, repetition.
Get top keywords by keyword_share (popular keywords).
Get trending keywords by change_in_mentions_pct.
KPI definitions under getKPIDefinitions category shopping.
Get share of shelf by brand (target and competitors) over time.
Get comparison of brand metrics vs competitors in shopping results (share of shelf, position, rating, price).
Get average position (rank) in shopping carousels over time.
Get price competitiveness analytics over time (average price, etc.) for products in shopping carousels.
Get paginated list of products from shopping results with search and sort.
Get paginated list of product rows (one per response/product) from shopping results.
Get average rating and review count over time for products in shopping carousels.
Get summary card metrics for the Product Tracker (shopping) dashboard.
Get top retailers for the brand's products (share of offers by retailer).
Get top products by frequency of recommendation in shopping carousels.
Structured 1–5 perception ratings on brand attributes and products, with topic-level and competitor comparisons. Replaces deprecated aggregate sentiment tracking, which was low-signal because LLMs express similar sentiment for most brands.
Get average ratings by topic category (Attribute vs Product).
Get list of topic categories (Attribute and Product) with counts for Brand Perception analysis.
Compare target brand vs competitors over time showing how ratings evolve for your brand compared to top competitors.
Get list of competitors appearing in Brand Perception analysis.
Get distribution of ratings (1-5 scale) for target brand and competitors.
Get brand perception trends over time showing how ratings and perceptions have changed.
Get radar chart data showing brand perception across multiple categories or attributes.
Get detailed view of a specific Brand Perception response including full text and all competitor ratings.
Get paginated list of Brand Perception responses with ratings and explanations.
Get summary card metrics for brand perception dashboard.
Get list of topics available for Brand Perception analysis for a brand.
Competitive matrices and presence distributions by topic.
Get comparative metrics with favorite competitors (share of voice, mentions, etc.).
Get competitive presence distribution showing how responses are distributed across three categories for each brand (your brand and favorite competitors):...
Get visibility scores matrix for topics × competitors showing a heatmap of visibility scores for each topic × competitor combination.
Tied to optimization agents (onsite, offsite, shared_media, pdp).
Get list of content folders (recommendation folders) generated by OnSite, OffSite, and Shared Media agents.
Get detailed view of a specific content page (recommendation page) including full recommendation content, structured output, SEO recommendations, FAQ items,...
Get list of content pages (recommendation pages) generated by OnSite and OffSite agents.
Get list of content recommendations generated by OnSite, OffSite, Shared Media, and PDP agents.
Panel-based real user behavior; see getKPIDefinitions real_traffic.
Get breakdown of real user traffic by dimension (models, apps, devices, languages, subscriptions).
Get demographic breakdown of real user traffic (age, gender, income, etc.).
Get overview of real user traffic: number of panelists and time-series events (messages over time).
Get sample real user messages from the traffic.
Custom narrative decks: getSlideDeckSpecGuide (data_collection_workflow per slide) → build spec → validateSlideDeckSpec → renderSlideDeck. Never expose validation errors.
Generate a PowerPoint or PDF file from a SlideDeckSpec.
Call BEFORE writing any slide for a PowerPoint export.
Confirmation step before renderSlideDeck.
Brand navigation, guarded management mutations, and in-product agent conversations.
Get conversation history with the AI agent.
Get topics for a specific brand.
Create a brand through the existing brand management REST flow with preview/apply confirmation.
Create or update one competitor through POST /api/competitors-list/ with preview/apply confirmation.
Invite one user through POST /api/users/invite/ with preview/apply confirmation.
Get available brands (paginated).
Safely update a brand's AI guidelines using a two-step flow.
In-product guides and KPI definitions you can ask the assistant to retrieve.
Get customer-focused guide for setting up CDN logs integration with Meikai.
Get explanation of core Meikai entities and concepts (Company, Brand, Topic, Prompt), product pillars (Brand Monitor, Site Scanner, Trend Explorer, Ads...
Get comprehensive guide on Generative Engine Optimization (GEO) best practices.
Get definitions and explanations of KPIs (Key Performance Indicators) and metrics used in Meikai.
Get step-by-step instructions for connecting or installing Meikai MCP on external AI clients: ChatGPT (Settings → Apps → Developer mode → Create app),...
Get comprehensive guide for installing the Meikai tracking pixel on your website.
Get documentation explaining what query fanouts are in Brand Monitor.
Get a Meikai-native playbook for improving AI visibility.
Other Meikai MCP tools available on your account.
Bulk create brands through POST /api/brands/import/ with preview/apply confirmation.
Bulk create or update competitors through POST /api/competitors-list/import/ with preview/apply confirmation.
Invite up to 100 users through POST /api/users/invite/bulk/ with preview/apply confirmation.
Generate the Ads dashboard PDF or PowerPoint report for the selected brand and date range.
Generate the Audience dashboard PDF or PowerPoint report for the selected brand and month range.
Generate the standard Brand Monitor visibility PDF report for the selected brand and date range.
Generate the standard Brand Monitor visibility PowerPoint report for the selected brand and date range.
Generate the Brand Perception dashboard PDF or PowerPoint report for the selected brand and date range.
Generate the Competitors dashboard PDF or PowerPoint report for the selected brand and date range.
Generate the Portfolio dashboard PDF or PowerPoint report for the selected company and date range.
Generate the Shopping (Product Tracker) dashboard PDF or PowerPoint report for the selected brand and date range.
Get the prompts that trigger ads most frequently, up to 50 results.
Get ad metrics aggregated by topic/intent, ordered by responses with ads.
Get individual ad creative cards observed in AI responses, up to 100 results ordered by most recent.
Get daily advertiser share of ad cards over time, showing the top 7 advertisers plus 'Others'.
Get summary card metrics for the Ads Analytics dashboard.
Get the top advertisers (brands) appearing in ads, sorted by frequency.
Get daily ad penetration trend for AI responses over the selected date range.
Compare organic brand visibility against ad coverage in AI responses.
Get async export download info by export_job_id.
Get status for an async export job by export_job_id.
Get available companies (paginated).
Get competitive breakdown: target brand metrics, favorite competitor rows, and optional by_dimension slice (topic, funnel, or platform).
Get the aggregated Competitor Detail for a single competitor: compact snapshot (visibility, share of voice, average mentions, rank), the topics where the...
Fetch robots.txt for a domain and evaluate crawl permissions by path and user agent.
Get prompt-level performance breakdown (share of voice, mentions, citations).
List prompts whose AI responses cited a specific citation URL or domain.
Get the Branded vs Unbranded split (Bain-style cohorts) for the period.
Get the number of distinct topic labels in the panel for a vertical and topic_type (intent or product_category).
Get the intent x product_category co-occurrence matrix for the selected period.
Get the share of panel activity per topic_label in a vertical, sorted by volume.
Get a time series of topic shares across the selected period.
Get company users (paginated).
Get visibility, share of voice, mentions, and response counts grouped by one dimension (platform, funnel, topic, or model).
Set one or more brand statuses through POST /api/brands/bulk-status/ with preview/apply confirmation.
Replace a user's home-company brand access through POST /api/users/brand-access/ with preview/apply confirmation.
Activate or deactivate up to 100 users through POST /api/users/bulk-status/ with preview/apply confirmation.
Start an async export job for Brand Monitor.
Patch brand management settings through PATCH /api/brands/{id}/ with preview/apply confirmation.
Validate bulk brand import via POST /api/brands/import/validate/ without persisting.
Validate bulk competitor import via POST /api/competitors-list/import/validate/ without persisting.
Validate bulk user invites via POST /api/users/invite/bulk-validate/ without persisting.
Validate brand create payload via POST /api/brands/validate/ without persisting.
Validate competitor create payload via POST /api/competitors-list/validate/ without persisting.
Validate user invite payload via POST /api/users/invite/validate/ without persisting.
Validate bulk brand status change via POST /api/brands/bulk-status/validate/ without persisting.
Validate brand access replacement via POST /api/users/brand-access/validate/ without persisting.
Validate bulk user status change via POST /api/users/bulk-status/validate/ without persisting.
Validate brand settings patch via POST /api/brands/{id}/validate/ without persisting.
Try these once connected (replace with your brand or date range):
| Use case | Example prompt |
|---|---|
| Visibility | What is our share of voice vs competitors over the last 7 days? |
| Citations | Which domains cite us most often in AI answers? |
| Competitors | How does our visibility compare to favorite competitors by topic? |
| Prompts | Which monitored prompts mention our brand least often? |
| Shopping | What is our share of shelf in AI shopping results? |
| Recommendations | What are our highest-priority GEO recommendations? |
| Guides | What are Meikai’s GEO best practices for improving AI visibility? |
| Getting oriented | Explain Meikai’s core concepts and main product areas. |
| Issue | What to do |
|---|---|
Client cannot reach localhost |
Remote clients (ChatGPT, Claude, Perplexity, Grok) need a public HTTPS URL — use a tunnel for local Docker dev. |
invalid_request after OAuth redirect |
Ensure production is deployed with support for your client’s callback URL (Perplexity: www.perplexity.ai/rest/connections/oauth_callback; Grok: grok.com/connectors-oauth-exchange-code). |
| 401 or tools stop working | Reconnect via OAuth; verify prod vs staging MCP URL matches your account. |
| Connector / Apps option missing | Confirm Team/Enterprise plan; ask workspace admin to allow custom connectors. |
| OAuth redirect loop (local dev) | Tunnel URL changed — re-run OAuth setup with the new public base URL, then reconnect. |
| Claude Client ID field | Optional — leave empty; Meikai defaults to client_id=mcp. |
For connector issues, include your AI client (Claude, ChatGPT, Perplexity, Grok, Cursor, etc.), the MCP server URL you configured, and a screenshot of any error after sign-in.
For additional help, email support@meikai.ai with your client name, MCP server URL, and any error screenshots.
JSON schemas and full tool descriptions for API clients.
Execute tools via POST /tools/<name>/execute/ with a Bearer token,
or browse the tools JSON API.
Customer REST API: Swagger UI.
Analyze a specific page for GEO (Generative Engine Optimization) readiness using Vertex AI grounded search with URL context. Returns citation readiness gaps, structured-data opportunities when accurate, and a prioritized people-first action plan aligned with Google Search guidance for AI Overviews and AI Mode.
{
"type": "object",
"properties": {
"page_url": {
"type": "string",
"description": "Full HTTP/HTTPS URL of the page to analyze for GEO readiness."
},
"focus_query": {
"type": "string",
"description": "Optional business/query angle to prioritize in the analysis, for example: 'private banking for entrepreneurs in switzerland'."
}
},
"required": [
"page_url"
]
}{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"text": {
"type": "string"
},
"model": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"success",
"text",
"model"
],
"description": "Vertex AI grounded analysis text response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Analyze web page content, SEO, content gaps, and provide technical recommendations using Vertex AI Grounded Search. When the user provides a single target page URL for GEO or on-page optimization, prefer the analyzePageGEO tool instead; use analyzeWebContent for multi-URL or non-page-specific questions, or as a fallback if analyzePageGEO fails. This tool uses Google Search to provide real-time analysis including SEO recommendations, content gap identification, content quality assessment, competitive analysis, and technical improvements. Recommendations should align with Search Essentials and avoid scaled-content or low-value AI-content tactics. The query should be specific about what to analyze, e.g., 'Analyze content and SEO for https://example.com/page', 'What content gaps exist for topic X?', 'Compare content quality with competitors for topic Y', or 'Technical SEO recommendations for page Z'
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "The analysis query. Should be specific about what to analyze. Examples: 'Analyze content and SEO for https://example.com/page', 'What content gaps exist for topic X?', 'Compare content quality with competitors for topic Y', or 'Technical SEO recommendations for page Z'"
}
},
"required": [
"query"
]
}{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"text": {
"type": "string"
},
"model": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"success",
"text",
"model"
],
"description": "Vertex AI grounded analysis text response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Bulk create brands through POST /api/brands/import/ with preview/apply confirmation. Each brand plan defaults to starter when omitted. Superusers auto-purchase plan licenses by default (set auto_purchase_plan_license=false to opt out). Each brand row accepts tracking_level ('brand' default, or 'product' for single-product brands).
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"preview",
"apply"
]
},
"confirmation_token": {
"type": "string"
},
"confirmation_phrase": {
"type": "string",
"enum": [
"CONFIRM_MANAGEMENT_CHANGE"
]
},
"company_id": {
"type": "string"
},
"auto_purchase_plan_license": {
"type": "boolean"
},
"brands": {
"type": "array",
"maxItems": 100
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Bulk brand creation preview or apply result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Bulk create or update competitors through POST /api/competitors-list/import/ with preview/apply confirmation.
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"preview",
"apply"
]
},
"confirmation_token": {
"type": "string"
},
"confirmation_phrase": {
"type": "string",
"enum": [
"CONFIRM_MANAGEMENT_CHANGE"
]
},
"brand_id": {
"type": "string"
},
"competitors": {
"type": "array",
"maxItems": 100
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Bulk competitor creation preview or apply result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Invite up to 100 users through POST /api/users/invite/bulk/ with preview/apply confirmation. Always call mode=preview first; the response includes confirmation_token required for apply. Each user object supports email, company_id (superusers), brand_access_assignments [{brand_id, role}], or legacy brand_ids + brand_role.
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"preview",
"apply"
]
},
"confirmation_token": {
"type": "string"
},
"confirmation_phrase": {
"type": "string",
"enum": [
"CONFIRM_MANAGEMENT_CHANGE"
]
},
"users": {
"type": "array",
"maxItems": 100
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Bulk user invitation preview or apply result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Create a brand through the existing brand management REST flow with preview/apply confirmation. Plan defaults to starter when omitted. Superusers auto-purchase plan licenses by default (set auto_purchase_plan_license=false to opt out). The brand object accepts tracking_level ('brand' default, or 'product' when the tracked subject is a single product such as 'Lipton Ice Tea'); product-level brands surface competing products rather than whole-company competitors in auto-discovery. Same payload as POST /api/brands/.
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"preview",
"apply"
]
},
"confirmation_token": {
"type": "string"
},
"confirmation_phrase": {
"type": "string",
"enum": [
"CONFIRM_MANAGEMENT_CHANGE"
]
},
"brand": {
"type": "object"
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Brand creation preview or apply result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Create or update one competitor through POST /api/competitors-list/ with preview/apply confirmation.
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"preview",
"apply"
]
},
"confirmation_token": {
"type": "string"
},
"confirmation_phrase": {
"type": "string",
"enum": [
"CONFIRM_MANAGEMENT_CHANGE"
]
},
"competitor": {
"type": "object"
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Competitor creation preview or apply result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Generate the Ads dashboard PDF or PowerPoint report for the selected brand and date range. Returns pdfUrl or pptxUrl (signed GCS download, 7 days). Requires feature flag dashboard_deck_export. Same payload as GET /api/ads/export/ or GET /api/ads/export/ppt/.
{
"type": "object",
"properties": {
"format": {
"type": "string",
"enum": [
"pdf",
"pptx"
],
"description": "Output format: pdf or pptx (PowerPoint)."
},
"brand_id": {
"type": "string",
"description": "Brand UUID (optional if context brand is available)."
},
"start_date": {
"type": "string",
"description": "Start date YYYY-MM-DD (optional; defaults from MCP context)."
},
"end_date": {
"type": "string",
"description": "End date YYYY-MM-DD (optional; defaults from MCP context)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Optional inclusive lookback window in days ending today. When set, overrides start_date/end_date."
},
"topic_id": {
"type": "string",
"description": "Optional topic UUID or comma-separated UUIDs."
},
"platform": {
"type": "string",
"description": "Optional AI platform filter (e.g. chatgpt, gemini)."
},
"model": {
"type": "string",
"description": "Optional model filter."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Optional funnel filter."
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter)."
}
},
"required": [
"format"
]
}{
"oneOf": [
{
"type": "object",
"properties": {
"pdfUrl": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"pdfUrl"
],
"description": "Ads dashboard PDF export signed GCS URL."
},
{
"type": "object",
"properties": {
"pptxUrl": {
"type": "string"
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false,
"required": [
"pptxUrl",
"warnings"
],
"description": "Ads dashboard PPT export signed GCS URL."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Generate the Audience dashboard PDF or PowerPoint report for the selected brand and month range. Returns pdfUrl or pptxUrl (signed GCS download, 7 days). Requires feature flag dashboard_deck_export. Use start_month/end_month (YYYY-MM), not start_date/end_date. Same payload as GET /api/audience/export/ (format=pdf) or GET /api/audience/export/ppt/ (format=pptx).
{
"type": "object",
"properties": {
"format": {
"type": "string",
"enum": [
"pdf",
"pptx"
],
"description": "Output format: pdf or pptx (PowerPoint)."
},
"brand_id": {
"type": "string",
"description": "Brand UUID (optional if context brand is available)."
},
"start_month": {
"type": "string",
"description": "Start month YYYY-MM (required)."
},
"end_month": {
"type": "string",
"description": "End month YYYY-MM (defaults to start_month)."
},
"gender": {
"type": "string",
"description": "Optional audience filter."
},
"age_band": {
"type": "string",
"description": "Optional audience filter."
},
"language": {
"type": "string",
"description": "Optional audience filter."
},
"platform": {
"type": "string",
"description": "Optional AI platform filter (e.g. chatgpt, gemini)."
},
"country_code": {
"type": "string",
"description": "Optional audience filter."
},
"household_income": {
"type": "string",
"description": "Optional audience filter."
}
},
"required": [
"format",
"start_month"
]
}{
"oneOf": [
{
"type": "object",
"properties": {
"pdfUrl": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"pdfUrl"
],
"description": "Audience dashboard PDF export signed GCS URL."
},
{
"type": "object",
"properties": {
"pptxUrl": {
"type": "string"
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false,
"required": [
"pptxUrl",
"warnings"
],
"description": "Audience dashboard PPT export signed GCS URL."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Generate the standard Brand Monitor visibility PDF report for the selected brand and date range. Returns pdfUrl (signed GCS download, 7 days). Use when the user asks for a Brand Monitor PDF export or report download in chat. Prefer this over startAsyncExportJob when the user wants an immediate download link. Same payload as GET /api/brand-visibility/export/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand UUID (optional if context brand is available)."
},
"start_date": {
"type": "string",
"description": "Start date YYYY-MM-DD (optional; defaults from MCP context)."
},
"end_date": {
"type": "string",
"description": "End date YYYY-MM-DD (optional; defaults from MCP context)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Optional inclusive lookback window in days ending today. When set, overrides start_date/end_date."
},
"topic_id": {
"type": "string",
"description": "Optional topic UUID or comma-separated UUIDs."
},
"platform": {
"type": "string",
"description": "Optional AI platform filter (e.g. chatgpt, gemini)."
},
"model": {
"type": "string",
"description": "Optional model filter."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Optional funnel filter."
},
"white_label": {
"type": "string",
"description": "Optional allowlisted partner id for PDF header branding."
}
}
}{
"oneOf": [
{
"type": "object",
"properties": {
"pdfUrl": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"pdfUrl"
],
"description": "Brand Monitor PDF export signed GCS download URL."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Generate the standard Brand Monitor visibility PowerPoint report for the selected brand and date range. Returns pptxUrl (signed GCS download, 7 days) and warnings. Requires feature flag brand_visibility_ppt_export. Use when the user asks for a Brand Monitor PPT/PowerPoint export in chat. Same payload as GET /api/brand-visibility/export/ppt/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand UUID (optional if context brand is available)."
},
"start_date": {
"type": "string",
"description": "Start date YYYY-MM-DD (optional; defaults from MCP context)."
},
"end_date": {
"type": "string",
"description": "End date YYYY-MM-DD (optional; defaults from MCP context)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Optional inclusive lookback window in days ending today. When set, overrides start_date/end_date."
},
"topic_id": {
"type": "string",
"description": "Optional topic UUID or comma-separated UUIDs."
},
"platform": {
"type": "string",
"description": "Optional AI platform filter (e.g. chatgpt, gemini)."
},
"model": {
"type": "string",
"description": "Optional model filter."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Optional funnel filter."
}
}
}{
"oneOf": [
{
"type": "object",
"properties": {
"pptxUrl": {
"type": "string"
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false,
"required": [
"pptxUrl",
"warnings"
],
"description": "Brand Monitor PPT export signed GCS URL and non-fatal warnings."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Generate the Brand Perception dashboard PDF or PowerPoint report for the selected brand and date range. Returns pdfUrl or pptxUrl (signed GCS download, 7 days). Requires feature flag dashboard_deck_export and BRAND_PERCEPTION permission. Same payload as GET /api/brand-perception/export/ or GET /api/brand-perception/export/ppt/.
{
"type": "object",
"properties": {
"format": {
"type": "string",
"enum": [
"pdf",
"pptx"
],
"description": "Output format: pdf or pptx (PowerPoint)."
},
"brand_id": {
"type": "string",
"description": "Brand UUID (optional if context brand is available)."
},
"start_date": {
"type": "string",
"description": "Start date YYYY-MM-DD (optional; defaults from MCP context)."
},
"end_date": {
"type": "string",
"description": "End date YYYY-MM-DD (optional; defaults from MCP context)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Optional inclusive lookback window in days ending today. When set, overrides start_date/end_date."
},
"topic_id": {
"type": "string",
"description": "Optional topic UUID or comma-separated UUIDs."
},
"platform": {
"type": "string",
"description": "Optional AI platform filter (e.g. chatgpt, gemini)."
},
"model": {
"type": "string",
"description": "Optional model filter."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Optional funnel filter."
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter)."
},
"topic_category": {
"type": "string",
"enum": [
"Attribute",
"Product"
],
"description": "Perception topic category (default Attribute)."
}
},
"required": [
"format"
]
}{
"oneOf": [
{
"type": "object",
"properties": {
"pdfUrl": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"pdfUrl"
],
"description": "Brand Perception dashboard PDF export signed GCS URL."
},
{
"type": "object",
"properties": {
"pptxUrl": {
"type": "string"
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false,
"required": [
"pptxUrl",
"warnings"
],
"description": "Brand Perception dashboard PPT export signed GCS URL."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Generate the Competitors dashboard PDF or PowerPoint report for the selected brand and date range. Returns pdfUrl or pptxUrl (signed GCS download, 7 days). Requires feature flag dashboard_deck_export and COMPETITORS permission. Same payload as GET /api/competitors/export/ or GET /api/competitors/export/ppt/.
{
"type": "object",
"properties": {
"format": {
"type": "string",
"enum": [
"pdf",
"pptx"
],
"description": "Output format: pdf or pptx (PowerPoint)."
},
"brand_id": {
"type": "string",
"description": "Brand UUID (optional if context brand is available)."
},
"start_date": {
"type": "string",
"description": "Start date YYYY-MM-DD (optional; defaults from MCP context)."
},
"end_date": {
"type": "string",
"description": "End date YYYY-MM-DD (optional; defaults from MCP context)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Optional inclusive lookback window in days ending today. When set, overrides start_date/end_date."
},
"topic_id": {
"type": "string",
"description": "Optional topic UUID or comma-separated UUIDs."
},
"platform": {
"type": "string",
"description": "Optional AI platform filter (e.g. chatgpt, gemini)."
},
"model": {
"type": "string",
"description": "Optional model filter."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Optional funnel filter."
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter)."
}
},
"required": [
"format"
]
}{
"oneOf": [
{
"type": "object",
"properties": {
"pdfUrl": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"pdfUrl"
],
"description": "Competitors dashboard PDF export signed GCS URL."
},
{
"type": "object",
"properties": {
"pptxUrl": {
"type": "string"
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false,
"required": [
"pptxUrl",
"warnings"
],
"description": "Competitors dashboard PPT export signed GCS URL."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Generate the Portfolio dashboard PDF or PowerPoint report for the selected company and date range. Returns pdfUrl or pptxUrl (signed GCS download, 7 days). Requires feature flag dashboard_deck_export. Use company_id plus start_date/end_date. Same payload as GET /api/portfolio/export/ or GET /api/portfolio/export/ppt/.
{
"type": "object",
"properties": {
"format": {
"type": "string",
"enum": [
"pdf",
"pptx"
],
"description": "Output format: pdf or pptx (PowerPoint)."
},
"company_id": {
"type": "string",
"description": "Company UUID (required)."
},
"start_date": {
"type": "string",
"description": "Start date YYYY-MM-DD (required)."
},
"end_date": {
"type": "string",
"description": "End date YYYY-MM-DD (required)."
},
"brand_id": {
"type": "string",
"description": "Optional comma-separated brand UUIDs."
},
"countries": {
"type": "string",
"description": "Optional comma-separated country codes."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Optional funnel filter."
},
"platform": {
"type": "string",
"description": "Optional AI platform filter (e.g. chatgpt, gemini)."
}
},
"required": [
"format",
"company_id",
"start_date",
"end_date"
]
}{
"oneOf": [
{
"type": "object",
"properties": {
"pdfUrl": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"pdfUrl"
],
"description": "Portfolio dashboard PDF export signed GCS URL."
},
{
"type": "object",
"properties": {
"pptxUrl": {
"type": "string"
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false,
"required": [
"pptxUrl",
"warnings"
],
"description": "Portfolio dashboard PPT export signed GCS URL."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Generate the Shopping (Product Tracker) dashboard PDF or PowerPoint report for the selected brand and date range. Returns pdfUrl or pptxUrl (signed GCS download, 7 days). Requires feature flag dashboard_deck_export. Same payload as GET /api/shopping/export/ or GET /api/shopping/export/ppt/.
{
"type": "object",
"properties": {
"format": {
"type": "string",
"enum": [
"pdf",
"pptx"
],
"description": "Output format: pdf or pptx (PowerPoint)."
},
"brand_id": {
"type": "string",
"description": "Brand UUID (optional if context brand is available)."
},
"start_date": {
"type": "string",
"description": "Start date YYYY-MM-DD (optional; defaults from MCP context)."
},
"end_date": {
"type": "string",
"description": "End date YYYY-MM-DD (optional; defaults from MCP context)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Optional inclusive lookback window in days ending today. When set, overrides start_date/end_date."
},
"topic_id": {
"type": "string",
"description": "Optional topic UUID or comma-separated UUIDs."
},
"platform": {
"type": "string",
"description": "Optional AI platform filter (e.g. chatgpt, gemini)."
},
"model": {
"type": "string",
"description": "Optional model filter."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Optional funnel filter."
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter)."
}
},
"required": [
"format"
]
}{
"oneOf": [
{
"type": "object",
"properties": {
"pdfUrl": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"pdfUrl"
],
"description": "Shopping dashboard PDF export signed GCS URL."
},
{
"type": "object",
"properties": {
"pptxUrl": {
"type": "string"
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false,
"required": [
"pptxUrl",
"warnings"
],
"description": "Shopping dashboard PPT export signed GCS URL."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get the prompts that trigger ads most frequently, up to 50 results. Returns prompt text, topic name, total responses, responses with ads, ads penetration %, brand-in-ads %, and top advertisers per prompt. Use when users want to know which queries trigger ads, or whether their brand appears in ads for specific prompts. Same payload as GET /api/ads/by-prompt/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)."
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days). Ads data is available from 2026-04-09; earlier dates are clamped automatically."
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Use getBrandTopics to discover topic IDs."
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (optional). Defaults to 'chatgpt'; use 'googleaioverview' for Google AI Overview ads."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Ads by prompt (GET /api/ads/by-prompt/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get ad metrics aggregated by topic/intent, ordered by responses with ads. Returns topic name, total responses, responses with ads, ads penetration %, brand-in-ads %, and top advertisers per topic. Use when users want to know which topics or intents attract the most advertising activity. Same payload as GET /api/ads/by-topic/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)."
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days). Ads data is available from 2026-04-09; earlier dates are clamped automatically."
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Use getBrandTopics to discover topic IDs."
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (optional). Defaults to 'chatgpt'; use 'googleaioverview' for Google AI Overview ads."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Ads by topic (GET /api/ads/by-topic/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get individual ad creative cards observed in AI responses, up to 100 results ordered by most recent. Returns date, prompt text, topic name, brand name, brand URL, brand favicon, card title, card body, card URL, and card image for each creative. Use when users want to inspect actual ad content, copy, or creative details seen in AI responses. Same payload as GET /api/ads/creatives/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)."
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days). Ads data is available from 2026-04-09; earlier dates are clamped automatically."
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Use getBrandTopics to discover topic IDs."
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (optional). Defaults to 'chatgpt'; use 'googleaioverview' for Google AI Overview ads."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Ad creatives (GET /api/ads/creatives/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get daily advertiser share of ad cards over time, showing the top 7 advertisers plus 'Others'. Returns a time series with date, brand_name, and cards_count per day, suitable for a stacked area chart. Use when users want to see how ad share evolved over time or compare advertiser dominance. Same payload as GET /api/ads/share-over-time/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)."
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days). Ads data is available from 2026-04-09; earlier dates are clamped automatically."
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Use getBrandTopics to discover topic IDs."
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (optional). Defaults to 'chatgpt'; use 'googleaioverview' for Google AI Overview ads."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Ads share over time (GET /api/ads/share-over-time/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get summary card metrics for the Ads Analytics dashboard. Returns ads penetration rate, period-over-period change, share of shelf for the monitored brand, total responses with ads, unique ad brands, and total ad cards. Use when users ask about ad presence, ad penetration, or share of shelf in AI responses. If brand_id, start_date, or end_date are not provided, uses defaults from UI context. Same payload as GET /api/ads/summary/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)."
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days). Ads data is available from 2026-04-09; earlier dates are clamped automatically."
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Use getBrandTopics to discover topic IDs."
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (optional). Defaults to 'chatgpt'; use 'googleaioverview' for Google AI Overview ads."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Ads summary KPI row."
},
"description": "GET /api/ads/summary/"
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get the top advertisers (brands) appearing in ads, sorted by frequency. Returns up to 50 brands with ad count, total cards, brand URL, and favicon. Use when users ask who is advertising most in AI responses, or which competitors run ads. Same payload as GET /api/ads/top-advertisers/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)."
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days). Ads data is available from 2026-04-09; earlier dates are clamped automatically."
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Use getBrandTopics to discover topic IDs."
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (optional). Defaults to 'chatgpt'; use 'googleaioverview' for Google AI Overview ads."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Top advertisers (GET /api/ads/top-advertisers/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get daily ad penetration trend for AI responses over the selected date range. Returns a time series with date, responses_with_ads, total_responses, and ads_penetration_pct per day. Use when users ask about ad trends, how ad presence evolved over time, or for charting ad penetration. Same payload as GET /api/ads/trend/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)."
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days). Ads data is available from 2026-04-09; earlier dates are clamped automatically."
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Use getBrandTopics to discover topic IDs."
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (optional). Defaults to 'chatgpt'; use 'googleaioverview' for Google AI Overview ads."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Ads trend series (GET /api/ads/trend/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Compare organic brand visibility against ad coverage in AI responses. Returns aggregate counts split by whether the brand is organically visible or not, each further split by ad presence: visible_with_ads, visible_without_ads, not_visible_with_ads, not_visible_without_ads (plus totals). Use when users want to understand the relationship between their organic presence and competitor ad activity. Same payload as GET /api/ads/vs-visibility/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)."
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days). Ads data is available from 2026-04-09; earlier dates are clamped automatically."
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Use getBrandTopics to discover topic IDs."
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (optional). Defaults to 'chatgpt'; use 'googleaioverview' for Google AI Overview ads."
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Ads vs visibility aggregate (GET /api/ads/vs-visibility/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get conversation history with the AI agent. Can list conversations or get details of a specific conversation. Supports filtering by brand, archived status, and search by title. Returns maximum 20 conversations per page and maximum 100 messages per conversation to prevent token limit issues. Same payload as GET /api/conversations/.
{
"type": "object",
"properties": {
"conversation_id": {
"type": "string",
"description": "If provided, returns details of a specific conversation. If not provided, returns list of conversations."
},
"brand_id": {
"type": "string",
"description": "Filter conversations by brand (optional)"
},
"archived": {
"type": "boolean",
"description": "Filter by archived status (optional, true/false)"
},
"search": {
"type": "string",
"description": "Search conversations by title (case-insensitive partial match, optional)"
},
"page": {
"type": "number",
"description": "Page number for pagination (for list, optional, default: 1)"
},
"page_size": {
"type": "number",
"description": "Number of conversations per page (optional, default: 10, max: 20)"
},
"limit_messages": {
"type": "number",
"description": "Maximum number of messages to return in conversation details (optional, default: 50, max: 100)"
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"properties": {},
"additionalProperties": true,
"description": "Conversation list, detail, or messages payload."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get async export download info by export_job_id. Returns download_url when job is completed. Same payload as GET /api/exports/jobs/{job_id}/download/.
{
"type": "object",
"properties": {
"export_job_id": {
"type": "string",
"description": "Export job UUID returned by startAsyncExportJob."
}
},
"required": [
"export_job_id"
]
}{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Export download metadata or file info."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get status for an async export job by export_job_id. Same payload as GET /api/exports/jobs/{job_id}/.
{
"type": "object",
"properties": {
"export_job_id": {
"type": "string",
"description": "Export job UUID returned by startAsyncExportJob."
}
},
"required": [
"export_job_id"
]
}{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Export job status."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get daily correlation between visibility and citation rate (Earned Media). Returns date, visibility, citation_rate per day for charts. Same payload as GET /api/authority/correlation-data/.
{
"type": "object",
"properties": {
"company_id": {
"type": "string",
"description": "The UUID of the company (optional, defaults to context company_id; required for publisher context)"
},
"brand_id": {
"type": "string",
"description": "The UUID of the brand to scope to (optional; if provided with company_id, filters to that brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to context or last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to context or today)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID)"
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., chatgpt, gemini, perplexity, googleaioverview)"
},
"model": {
"type": "string",
"description": "Filter by AI model name"
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Authority correlation series (GET /api/authority/correlation-data/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get verified bot traffic data from CDN logs for a brand website or a publisher company website. This data only includes crawler traffic that matches both a known bot User-Agent and official vendor IP ranges. It shows which pages on your website are being crawled by verified AI platforms like OpenAI, Perplexity, Google, and Microsoft. Returns verified platform breakdown, verified bot-agent breakdown, daily trends, top pages (readable pages), and unreadable pages with HTTP status >= 400 (for example 404/403/500) so you can see what LLM bots cannot read. Bot-agent labels use canonical Site Scanner names (for example: 'GPTBot (OpenAI training crawler)' and 'Googlebot (Google search crawler)') and are aligned with domain robots policy summaries. Provide exactly one of brand_id or company_id (publisher company). Requires CDN log customer IDs configured on the brand or company. If ids or dates are not provided, uses defaults from UI context when available. Same payload as GET /api/site-scanner/bots/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand UUID for brand website scope (XOR with company_id). Requires CDN log customer IDs on the brand."
},
"company_id": {
"type": "string",
"description": "Company UUID for publisher corporate website scope (XOR with brand_id). Requires publisher company type and CDN log customer IDs on the company."
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (required)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (required)"
},
"host": {
"type": "string",
"description": "Optional host filter (e.g., 'www.meikai.ai'). If not provided, returns data for all hosts."
},
"platform": {
"type": "string",
"enum": [
"OpenAI",
"Perplexity",
"Google",
"Microsoft"
],
"description": "Optional verified platform filter. Only verified bot platforms are supported."
},
"bot_agent": {
"type": "string",
"description": "Optional verified bot-agent label filter (for example: 'GPTBot (OpenAI training crawler)' or 'Googlebot (Google search crawler)')."
},
"path_contains": {
"type": "string",
"description": "Optional case-insensitive substring filter for path coverage checks (for example: 'pricing', '/blog/', 'product'). Useful to check whether specific page groups are crawled by verified bots."
}
},
"required": [
"start_date",
"end_date"
]
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Bot traffic data (GET /api/site-scanner/bots/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get average ratings by topic category (Attribute vs Product). Returns average ratings for your brand and competitors broken down by category type. Use this to compare how your brand is perceived in Attribute topics (brand attributes like quality, innovation) versus Product topics (product-specific features). Shows target_avg_rating, competitor_avg_rating, and sample_size for each category. Use this when users ask about 'perception by category', 'attribute vs product perception', or want to compare perception across category types. Supports filtering by ai_platform and model. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/brand-perception/metrics/by-category/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., 'chatgpt', 'gemini', 'perplexity', 'grok', 'copilot', 'openai', 'google-ai-mode', 'googleaioverview'). Common values: chatgpt, gemini, perplexity, grok, copilot, googleaioverview"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g., 'gpt-5', 'gpt-5-t-mini', 'gemini-2.5-flash', 'grok-3', 'grok-4-auto', 'perplexity'). Model names vary by platform"
},
"iteration_start_date": {
"type": "string",
"description": "Optional Prompt Studio cycle/iteration start date (YYYY-MM-DD) to restrict results to that iteration's evergreen topics. Get valid values from getIterationStartDates with classification='evergreen'."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Perception by category."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get list of topic categories (Attribute and Product) with counts for Brand Perception analysis. Categories group topics into two main types: 'Attribute' (brand attributes like quality, innovation, trustworthiness) and 'Product' (product-specific topics). Returns the count of topics and responses for each category. Use this to understand the distribution of perception data across category types. Supports filtering by ai_platform and model. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/brand-perception/metadata/categories/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., 'chatgpt', 'gemini', 'perplexity', 'grok', 'copilot', 'openai', 'google-ai-mode', 'googleaioverview'). Common values: chatgpt, gemini, perplexity, grok, copilot, googleaioverview"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g., 'gpt-5', 'gpt-5-t-mini', 'gemini-2.5-flash', 'grok-3', 'grok-4-auto', 'perplexity'). Model names vary by platform"
},
"iteration_start_date": {
"type": "string",
"description": "Optional Prompt Studio cycle/iteration start date (YYYY-MM-DD) to restrict results to that iteration's evergreen topics. Get valid values from getIterationStartDates with classification='evergreen'."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Perception categories metadata."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Compare target brand vs competitors over time showing how ratings evolve for your brand compared to top competitors. Returns time-series data with average ratings for your brand and selected competitors for each period, allowing side-by-side trend comparison. Use this when users ask about 'competitor comparison', 'how do I compare to competitors', 'perception vs competitors over time', or want to see competitive positioning trends. Supports filtering by topic_id (from getBrandPerceptionTopics), topic_category (from getBrandPerceptionCategories), ai_platform, model, granularity ('daily' or 'weekly', default: 'weekly'), and top_n_competitors (number of top competitors to include, default: 5). If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/brand-perception/trends/competitor-comparison/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from getBrandPerceptionTopics results or user message."
},
"topic_category": {
"type": "string",
"enum": [
"Attribute",
"Product"
],
"description": "Filter by topic category: 'Attribute' (brand attributes) or 'Product' (product-specific topics)"
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., 'chatgpt', 'gemini', 'perplexity', 'grok', 'copilot', 'openai', 'google-ai-mode', 'googleaioverview'). Common values: chatgpt, gemini, perplexity, grok, copilot, googleaioverview"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g., 'gpt-5', 'gpt-5-t-mini', 'gemini-2.5-flash', 'grok-3', 'grok-4-auto', 'perplexity'). Model names vary by platform"
},
"iteration_start_date": {
"type": "string",
"description": "Optional Prompt Studio cycle/iteration start date (YYYY-MM-DD) to restrict results to that iteration's evergreen topics. Get valid values from getIterationStartDates with classification='evergreen'."
},
"granularity": {
"type": "string",
"enum": [
"daily",
"weekly"
],
"description": "Time granularity: 'daily' for day-by-day data or 'weekly' for weekly aggregation (optional, default: 'weekly')"
},
"top_n_competitors": {
"type": "number",
"description": "Number of top competitors to include in comparison (optional, default: 5)"
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Competitor comparison series."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get list of competitors appearing in Brand Perception analysis. Returns competitors with their mention counts, average ratings, and number of topics they appeared in. Use this to identify which competitors are most frequently compared to your brand and understand competitive landscape. Supports filtering by topic_id (from getBrandPerceptionTopics), topic_category (Attribute or Product), ai_platform, and model. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/brand-perception/metadata/competitors/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from getBrandPerceptionTopics results or user message."
},
"topic_category": {
"type": "string",
"enum": [
"Attribute",
"Product"
],
"description": "Filter by topic category: 'Attribute' (brand attributes) or 'Product' (product-specific topics)"
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., 'chatgpt', 'gemini', 'perplexity', 'grok', 'copilot', 'openai', 'google-ai-mode', 'googleaioverview'). Common values: chatgpt, gemini, perplexity, grok, copilot, googleaioverview"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g., 'gpt-5', 'gpt-5-t-mini', 'gemini-2.5-flash', 'grok-3', 'grok-4-auto', 'perplexity'). Model names vary by platform"
},
"iteration_start_date": {
"type": "string",
"description": "Optional Prompt Studio cycle/iteration start date (YYYY-MM-DD) to restrict results to that iteration's evergreen topics. Get valid values from getIterationStartDates with classification='evergreen'."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Perception competitors metadata."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get distribution of ratings (1-5 scale) for target brand and competitors. Returns the count and percentage of responses for each rating level (1 through 5), showing how ratings are distributed across the scale. This helps understand if perceptions are concentrated at high ratings (4-5), low ratings (1-2), or spread across the scale. Use this when users ask about 'rating distribution', 'how are ratings distributed', 'perception distribution', or want to see the spread of ratings. Supports filtering by topic_id (from getBrandPerceptionTopics), topic_category (from getBrandPerceptionCategories), ai_platform, and model. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/brand-perception/trends/distribution/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from getBrandPerceptionTopics results or user message."
},
"topic_category": {
"type": "string",
"enum": [
"Attribute",
"Product"
],
"description": "Filter by topic category: 'Attribute' (brand attributes) or 'Product' (product-specific topics)"
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., 'chatgpt', 'gemini', 'perplexity', 'grok', 'copilot', 'openai', 'google-ai-mode', 'googleaioverview'). Common values: chatgpt, gemini, perplexity, grok, copilot, googleaioverview"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g., 'gpt-5', 'gpt-5-t-mini', 'gemini-2.5-flash', 'grok-3', 'grok-4-auto', 'perplexity'). Model names vary by platform"
},
"iteration_start_date": {
"type": "string",
"description": "Optional Prompt Studio cycle/iteration start date (YYYY-MM-DD) to restrict results to that iteration's evergreen topics. Get valid values from getIterationStartDates with classification='evergreen'."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Perception distribution."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get brand perception trends over time showing how ratings and perceptions have changed. Returns time-series data with perception metrics (ratings, sample sizes, topic counts) for each period in the range, allowing trend analysis and identification of perception shifts. Use this when users ask about 'how has perception changed', 'trends in brand perception', 'perception over time', 'perception evolution', or want to see if brand perception is improving or declining. Supports filtering by topic_id (from getBrandPerceptionTopics), topic_category (from getBrandPerceptionCategories), ai_platform, model, and granularity ('daily' or 'weekly', default: 'weekly'). If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/brand-perception/trends/over-time/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from getBrandPerceptionTopics results or user message."
},
"topic_category": {
"type": "string",
"enum": [
"Attribute",
"Product"
],
"description": "Filter by topic category: 'Attribute' (brand attributes) or 'Product' (product-specific topics)"
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., 'chatgpt', 'gemini', 'perplexity', 'grok', 'copilot', 'openai', 'google-ai-mode', 'googleaioverview'). Common values: chatgpt, gemini, perplexity, grok, copilot, googleaioverview"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g., 'gpt-5', 'gpt-5-t-mini', 'gemini-2.5-flash', 'grok-3', 'grok-4-auto', 'perplexity'). Model names vary by platform"
},
"iteration_start_date": {
"type": "string",
"description": "Optional Prompt Studio cycle/iteration start date (YYYY-MM-DD) to restrict results to that iteration's evergreen topics. Get valid values from getIterationStartDates with classification='evergreen'."
},
"granularity": {
"type": "string",
"enum": [
"daily",
"weekly"
],
"description": "Time granularity: 'daily' for day-by-day data or 'weekly' for weekly aggregation (optional, default: 'weekly')"
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Perception over time."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get radar chart data showing brand perception across multiple categories or attributes. The radar chart visualizes how your brand is perceived across different dimensions (e.g., quality, innovation, value, trustworthiness) compared to competitors or industry benchmarks. Returns data formatted for radar chart visualization with ratings for each topic, comparing your brand against top competitors. Use this when users ask about 'brand perception', 'how is my brand perceived', 'brand attributes', 'perception radar', or want to see a comprehensive view of brand perception across multiple dimensions. Supports filtering by topic_category (from getBrandPerceptionCategories), ai_platform, model, and top_n_competitors (number of top competitors to include, default: 5). If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/brand-perception/metrics/radar/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"topic_category": {
"type": "string",
"enum": [
"Attribute",
"Product"
],
"description": "Filter by topic category: 'Attribute' (brand attributes) or 'Product' (product-specific topics)"
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., 'chatgpt', 'gemini', 'perplexity', 'grok', 'copilot', 'openai', 'google-ai-mode', 'googleaioverview'). Common values: chatgpt, gemini, perplexity, grok, copilot, googleaioverview"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g., 'gpt-5', 'gpt-5-t-mini', 'gemini-2.5-flash', 'grok-3', 'grok-4-auto', 'perplexity'). Model names vary by platform"
},
"iteration_start_date": {
"type": "string",
"description": "Optional Prompt Studio cycle/iteration start date (YYYY-MM-DD) to restrict results to that iteration's evergreen topics. Get valid values from getIterationStartDates with classification='evergreen'."
},
"top_n_competitors": {
"type": "number",
"description": "Number of top competitors to include in the radar chart (optional, default: 5)"
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Perception radar chart data."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get detailed view of a specific Brand Perception response including full text and all competitor ratings. Returns complete information about a single response including target brand rating and reason, all competitor ratings with their reasons and rankings, full raw response text, extraction confidence, and citations (URLs/sources from the LLM response when available). Use this when users ask about a specific response, want to see full details of a rating, or need to understand why a particular rating was given. Requires response_id (extract from getBrandPerceptionResponses results or user message) and brand_id for authorization. If brand_id is not provided, uses default from UI context (current brand). Same payload as GET /api/brand-perception/responses/{response_id}/.
{
"type": "object",
"properties": {
"response_id": {
"type": "string",
"description": "The UUID of the response. Extract this from getBrandPerceptionResponses results or user message when they mention a specific response ID."
},
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand, required for authorization)"
}
},
"required": [
"response_id"
]
}{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Perception response detail."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get paginated list of Brand Perception responses with ratings and explanations. Returns individual responses that contain brand perception ratings, including target brand rating, competitor ratings, extraction confidence, and response preview. Use this when users ask about 'perception responses', 'individual ratings', 'response details', or want to see specific responses with their ratings. Supports filtering by topic_id (from getBrandPerceptionTopics), topic_category (from getBrandPerceptionCategories), ai_platform, model, min_rating (1-5), max_rating (1-5), confidence (high, medium, low), and sorting by date, rating, or confidence. IMPORTANT: When user asks for 'all' or comprehensive data, use limit up to 100 (maximum allowed). ALWAYS use appropriate sorting: sort_by='date' with sort_order='desc' for newest, sort_by='rating' with sort_order='desc' for highest ratings, sort_by='confidence' with sort_order='desc' for highest confidence. Never rely on default sorting - always specify sort_by and sort_order based on the query intent. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/brand-perception/responses/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from getBrandPerceptionTopics results or user message."
},
"topic_category": {
"type": "string",
"enum": [
"Attribute",
"Product"
],
"description": "Filter by topic category: 'Attribute' (brand attributes) or 'Product' (product-specific topics)"
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., 'chatgpt', 'gemini', 'perplexity', 'grok', 'copilot', 'openai', 'google-ai-mode', 'googleaioverview'). Common values: chatgpt, gemini, perplexity, grok, copilot, googleaioverview"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g., 'gpt-5', 'gpt-5-t-mini', 'gemini-2.5-flash', 'grok-3', 'grok-4-auto', 'perplexity'). Model names vary by platform"
},
"iteration_start_date": {
"type": "string",
"description": "Optional Prompt Studio cycle/iteration start date (YYYY-MM-DD) to restrict results to that iteration's evergreen topics. Get valid values from getIterationStartDates with classification='evergreen'."
},
"min_rating": {
"type": "number",
"description": "Minimum target brand rating filter (optional, 1-5)"
},
"max_rating": {
"type": "number",
"description": "Maximum target brand rating filter (optional, 1-5)"
},
"confidence": {
"type": "string",
"enum": [
"high",
"medium",
"low"
],
"description": "Filter by extraction confidence: 'high' (high confidence extractions), 'medium' (medium confidence), 'low' (low confidence)"
},
"limit": {
"type": "number",
"description": "Number of results per page (optional, default: 50, max: 100)"
},
"offset": {
"type": "number",
"description": "Number of results to skip for pagination (optional, default: 0)"
},
"sort_by": {
"type": "string",
"enum": [
"date",
"rating",
"confidence"
],
"description": "Field to sort by. ALWAYS use appropriate sorting based on query intent: 'date' for newest/oldest (with sort_order='desc' for newest, sort_order='asc' for oldest), 'rating' for highest/lowest ratings (with sort_order='desc' for highest, sort_order='asc' for lowest), 'confidence' for highest/lowest confidence (with sort_order='desc' for highest, sort_order='asc' for lowest). NEVER rely on defaults - always specify sort_by and sort_order."
},
"sort_order": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Sort order: 'asc' for ascending or 'desc' for descending. ALWAYS specify: Use 'desc' for newest/highest, 'asc' for oldest/lowest. Must ALWAYS be provided when sort_by is used."
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get summary card metrics for brand perception dashboard. Returns key aggregate metrics including overall average rating, total responses, number of topics analyzed, number of competitors identified, rating difference vs competitors (positive means better than competitors), and high confidence percentage. Use this when users ask about 'brand perception summary', 'overall perception', 'perception metrics', or want a quick overview of brand perception performance. Supports filtering by topic_category (from getBrandPerceptionCategories), ai_platform, and model. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/brand-perception/metrics/summary/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"topic_category": {
"type": "string",
"enum": [
"Attribute",
"Product"
],
"description": "Filter by topic category: 'Attribute' (brand attributes) or 'Product' (product-specific topics)"
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., 'chatgpt', 'gemini', 'perplexity', 'grok', 'copilot', 'openai', 'google-ai-mode', 'googleaioverview'). Common values: chatgpt, gemini, perplexity, grok, copilot, googleaioverview"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g., 'gpt-5', 'gpt-5-t-mini', 'gemini-2.5-flash', 'grok-3', 'grok-4-auto', 'perplexity'). Model names vary by platform"
},
"iteration_start_date": {
"type": "string",
"description": "Optional Prompt Studio cycle/iteration start date (YYYY-MM-DD) to restrict results to that iteration's evergreen topics. Get valid values from getIterationStartDates with classification='evergreen'."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Perception summary KPI."
},
"description": "GET /api/brand-perception/metrics/summary/"
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get list of topics available for Brand Perception analysis for a brand. Brand Perception measures how users rate and perceive your brand across different attributes and categories. Use this tool to get the list of topics that can be analyzed for brand perception metrics. Topics represent different aspects or attributes of the brand that users can rate (e.g., quality, innovation, trustworthiness). This is typically the first step when analyzing brand perception - get the available topics, then use other Brand Perception tools with specific topic_id values. Returns topics with their category (Attribute or Product), response counts, and average ratings. Supports filtering by topic_category (Attribute or Product), ai_platform, and model. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/brand-perception/metadata/topics/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"topic_category": {
"type": "string",
"enum": [
"Attribute",
"Product"
],
"description": "Filter by topic category: 'Attribute' (brand attributes like quality, innovation) or 'Product' (product-specific topics)"
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., 'chatgpt', 'gemini', 'perplexity', 'grok', 'copilot', 'openai', 'google-ai-mode', 'googleaioverview'). Common values: chatgpt, gemini, perplexity, grok, copilot, googleaioverview"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g., 'gpt-5', 'gpt-5-t-mini', 'gemini-2.5-flash', 'grok-3', 'grok-4-auto', 'perplexity'). Model names vary by platform"
},
"iteration_start_date": {
"type": "string",
"description": "Optional Prompt Studio cycle/iteration start date (YYYY-MM-DD) to restrict results to that iteration's evergreen topics. Get valid values from getIterationStartDates with classification='evergreen'."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Perception topics metadata."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get topics for a specific brand. Returns a list of topics associated with the brand. If brand_id is not provided, uses the current brand from UI context. Same payload as GET /api/topics/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"page_size": {
"type": "number",
"description": "Number of topics to return per page. Use large values when user wants 'all' topics or comprehensive data."
},
"page": {
"type": "number",
"description": "Page number for pagination"
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get available brands (paginated). Response includes pagination.total_count and pagination.total_pages; use page and page_size (max 50 per call) for additional pages. When the user names or partially names a brand, pass search with that substring to narrow results (matches brand name or company name, case-insensitive). Optional ordering: name, -name, created_at, -created_at, updated_at, -updated_at, company_name, -company_name. When brand_id is provided (or in context), prioritizes the currently selected brand. When company_id is provided (or in context), returns brands for that company (superusers only can filter by company_id; others see their own company's brands). Same payload as GET /api/brands/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of a specific brand to prioritize/filter (optional, defaults to current selected brand from context)"
},
"company_id": {
"type": "string",
"description": "The UUID of the company to list brands for (optional, defaults to context company_id; superusers only when different from own company)"
},
"page_size": {
"type": "number",
"description": "Number of brands to return per page"
},
"page": {
"type": "number",
"description": "Page number for pagination"
},
"search": {
"type": "string",
"description": "Substring to match against brand name or company name (case-insensitive). Use when listing many brands or the user gives a partial name."
},
"ordering": {
"type": "string",
"description": "Sort field: name, -name, created_at, -created_at, updated_at, -updated_at, company_name, -company_name",
"enum": [
"name",
"-name",
"created_at",
"-created_at",
"updated_at",
"-updated_at",
"company_name",
"-company_name"
]
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get customer-focused guide for setting up CDN logs integration with Meikai. CRITICAL: ALWAYS use this tool when users ask 'how to setup CDN logs', 'CDN logs integration', 'bot traffic tracking setup', 'configure CDN logs', or any question about setting up CDN logs or bot traffic analysis. Returns step-by-step instructions for configuring your CDN provider (Vercel, AWS CloudFront, Cloudflare, Netlify, Fastly, Akamai) to send logs to Meikai for bot traffic analysis. Includes what credentials you'll need from Meikai and how to configure each CDN provider.
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"enum": [
"vercel",
"aws",
"cloudflare",
"netlify",
"fastly",
"akamai",
"all",
"overview"
],
"description": "Which CDN provider guide to show. 'overview' for general architecture and setup, specific provider name for provider-specific instructions, 'all' for all providers (default)."
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false,
"required": [
"success",
"data"
],
"description": "Static product documentation payload."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get citation statistics by AI platform (Earned Media). Citation rate per platform = company domain citations / total Earned Media citations for that platform. Same payload as GET /api/authority/citation-by-platform/.
{
"type": "object",
"properties": {
"company_id": {
"type": "string",
"description": "The UUID of the company (optional, defaults to context company_id; required for publisher context)"
},
"brand_id": {
"type": "string",
"description": "The UUID of the brand to scope to (optional; if provided with company_id, filters to that brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to context or last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to context or today)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID)"
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., chatgpt, gemini, perplexity, googleaioverview)"
},
"model": {
"type": "string",
"description": "Filter by AI model name"
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Citations by platform (GET /api/authority/citation-by-platform/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get distribution of citations by media type (percentages). Use for citation source breakdown. Same payload as GET /api/authority/citation-media-type/.
{
"type": "object",
"properties": {
"company_id": {
"type": "string",
"description": "The UUID of the company (optional, defaults to context company_id; required for publisher context)"
},
"brand_id": {
"type": "string",
"description": "The UUID of the brand to scope to (optional; if provided with company_id, filters to that brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to context or last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to context or today)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID)"
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., chatgpt, gemini, perplexity, googleaioverview)"
},
"model": {
"type": "string",
"description": "Filter by AI model name"
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Citation media-type breakdown (GET /api/authority/citation-media-type/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get a ranked list of domains by citation rate (Earned Media). Returns paginated data with rank, domain, citation_rate, total_citations, trend. Use for domain ranking or citation leaderboard. Same payload as GET /api/authority/citation-rank/.
{
"type": "object",
"properties": {
"company_id": {
"type": "string",
"description": "The UUID of the company (optional, defaults to context company_id; required for publisher context)"
},
"brand_id": {
"type": "string",
"description": "The UUID of the brand to scope to (optional; if provided with company_id, filters to that brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to context or last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to context or today)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID)"
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., chatgpt, gemini, perplexity, googleaioverview)"
},
"model": {
"type": "string",
"description": "Filter by AI model name"
},
"page": {
"type": "integer",
"description": "Page number (default 1)"
},
"page_size": {
"type": "integer",
"description": "Items per page (default 20, max 200)"
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get the citation rate metric for the company (publisher). Citation rate = company_domain_citations / total_earned_media_citations (Earned Media only). Returns value (0-1), previous_value, change, total_citations, previous_total_citations, total_opportunities. Use when user asks about citation rate, share of citations, or authority metrics. Same payload as GET /api/authority/citation-rate/.
{
"type": "object",
"properties": {
"company_id": {
"type": "string",
"description": "The UUID of the company (optional, defaults to context company_id; required for publisher context)"
},
"brand_id": {
"type": "string",
"description": "The UUID of the brand to scope to (optional; if provided with company_id, filters to that brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to context or last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to context or today)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID)"
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., chatgpt, gemini, perplexity, googleaioverview)"
},
"model": {
"type": "string",
"description": "Filter by AI model name"
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Citation rate KPI row."
},
"description": "Citation rate card (GET /api/authority/citation-rate/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get citations with filters, pagination, and sorting. Returns a list of citations matching the criteria. CRITICAL: ALWAYS prefer using topic_id or prompt_id filter over search when you have topic_id or prompt_id (from getBrandTopics, getPrompts, or user message). Use search ONLY when filtering by URL/title text and you don't have a specific topic_id or prompt_id. Supports filtering by topic_id (PREFERRED), prompt_id (single UUID or comma-separated list for multiple prompts), media_type (Reference & Informational, Public & Institutional, Competitor, Earned Media, Commercial Media, Owned Media, Shared Media), funnel (awareness, consideration, conversion), platform, model, is_mentioning_brand ('true', 'false', or 'unknown' to filter by whether the citation URL mentions the brand), favorite_competitor_mentioned_not_brand ('true' or 'false' to filter URLs where a favorite competitor is mentioned but not the brand; may be null in response until data is available), exclude_domains (comma-separated domains to exclude), and search (use only when topic_id/prompt_id filters are not available). IMPORTANT: When user asks for 'all', 'top', 'most', or comprehensive analysis, use page_size up to 200 (maximum allowed to prevent token limit issues). ALWAYS use appropriate sorting: sort_by='citationsCount' with order='desc' for most cited, sort_by='domainBrandMentions' with order='desc' for domains with most URLs mentioning brand, sort_by='shareOfCitation' with order='desc' for highest share, sort_by='lastSeenAt' with order='desc' for recent, sort_by='url' with order='asc' for alphabetical. Never rely on default sorting - always specify sort_by and order based on the query intent. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/citations/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). PREFERRED over search when filtering by topic - use this when you have topic_id from getBrandTopics or user message."
},
"prompt_id": {
"type": "string",
"description": "Filter by prompt ID(s). Can be a single UUID or comma-separated list of UUIDs. Use this to get citations for specific prompts (e.g., prompts in a cluster)."
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID (restricts to that persona's assigned active regular prompts)."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage"
},
"platform": {
"type": "string",
"description": "Filter by AI platform (e.g., 'chatgpt', 'gemini', 'perplexity', 'grok', 'copilot', 'openai', 'google-ai-mode', 'googleaioverview'). Common values: chatgpt, gemini, perplexity, grok, copilot, googleaioverview"
},
"platforms": {
"type": "string",
"description": "Filter by multiple AI platforms in one query (comma-separated, e.g. 'chatgpt,gemini,google-ai-mode'). Prefer over repeated single-platform calls."
},
"per_platform_url_cap": {
"type": "integer",
"description": "With multi-platform platforms filter, keep only the top N citation URLs per platform before merging across platforms. Used by OffSite earned-media analysis to preserve legacy per-platform top-N semantics in one query."
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g., 'gpt-5', 'gpt-5-t-mini', 'gemini-2.5-flash', 'grok-3', 'grok-4-auto', 'perplexity'). Model names vary by platform"
},
"media_type": {
"type": "string",
"enum": [
"Reference & Informational",
"Public & Institutional",
"Competitor",
"Earned Media",
"Commercial Media",
"Owned Media",
"Shared Media"
],
"description": "Filter by media type. Valid values: 'Reference & Informational' (reference sites, informational content), 'Public & Institutional' (public institutions, government sites), 'Competitor' (competitor websites), 'Earned Media' (unpaid media coverage like press mentions, reviews, articles), 'Commercial Media' (commercial/advertising media), 'Owned Media' (content you own/control like your website, blog), 'Shared Media' (shared/social platforms)"
},
"is_mentioning_brand": {
"type": "string",
"enum": [
"true",
"false",
"unknown"
],
"description": "Filter citations by whether the URL mentions the brand. 'true' = only URLs that mention the brand; 'false' = only URLs that do not mention the brand; 'unknown' = only URLs where brand mention status is unknown. Omit to return all citations."
},
"favorite_competitor_mentioned_not_brand": {
"type": "string",
"enum": [
"true",
"false"
],
"description": "Filter by competitor-only: 'true' = only URLs where a favorite competitor is mentioned in scraped content but the brand is not; 'false' = only URLs that do not match that. Response fields isMentioningAnyFavoriteCompetitor and isFavoriteCompetitorMentionedNotBrand may be null until backend data is available."
},
"exclude_domains": {
"type": "string",
"description": "Exclude citations from these domains. Comma-separated list of domain names (e.g. 'example.com, foo.org'). Case-insensitive."
},
"domain": {
"type": "string",
"description": "Filter URL rows to a specific domain (case-insensitive, supports apex/subdomain matching in backend)."
},
"view": {
"type": "string",
"enum": [
"urls",
"domains"
],
"description": "Result mode: 'urls' (default) for URL-level rows, or 'domains' for grouped domain rows."
},
"search": {
"type": "string",
"description": "Search query for URL or title text. Use ONLY when you don't have topic_id or prompt_id filters available. Prefer ID-based filters (topic_id, prompt_id) over search when possible."
},
"include_total": {
"type": "boolean",
"description": "When true (default in backend), include totalCount in pagination metadata."
},
"count_only": {
"type": "boolean",
"description": "When true, only returns pagination totals (no data rows). Useful to fetch counts quickly."
},
"page": {
"type": "number",
"description": "Page number for pagination"
},
"page_size": {
"type": "number",
"description": "Number of citations per page. Maximum allowed is 200 to prevent token limit issues. Use values up to 200 when user wants comprehensive data, 'all' results, or analysis of top/most items. Default is 50."
},
"sort_by": {
"type": "string",
"enum": [
"url",
"domain",
"mediaType",
"title",
"citationsCount",
"domainCitationCount",
"domainUrlCount",
"isMentioningBrand",
"isFavoriteCompetitorMentionedNotBrand",
"domainBrandMentions",
"domainCompetitorOnlyMentions",
"domainCompetitorOnlyPresence",
"shareOfCitation",
"shareOfCitationDomain",
"promptsImpactedByUrl",
"promptsImpactedByDomain",
"lastSeenAt",
"firstSeenAt"
],
"description": "Field to sort by. ALWAYS use appropriate sorting based on query intent: 'citationsCount' for most/least cited (with order='desc' for most, order='asc' for least), 'domainBrandMentions' for most/least URLs mentioning brand per domain (with order='desc' for most, order='asc' for least), 'shareOfCitation' for highest/lowest share (with order='desc' for highest, order='asc' for lowest), 'lastSeenAt' for recent/oldest (with order='desc' for recent, order='asc' for oldest), 'firstSeenAt' for earliest/latest first appearance (with order='asc' for earliest, order='desc' for latest), 'isFavoriteCompetitorMentionedNotBrand' for competitor-only flag, 'url' or 'domain' for alphabetical (with order='asc'). NEVER rely on defaults - always specify sort_by and order. Valid values: url, domain, mediaType, title, citationsCount, domainCitationCount, isMentioningBrand, isFavoriteCompetitorMentionedNotBrand, domainBrandMentions, shareOfCitation, shareOfCitationDomain, promptsImpactedByUrl, promptsImpactedByDomain, lastSeenAt, firstSeenAt"
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Sort order: 'asc' for ascending or 'desc' for descending. ALWAYS specify: Use 'desc' for top/most/highest/recent, 'asc' for least/lowest/oldest/alphabetical. Must ALWAYS be provided when sort_by is used - never rely on defaults."
},
"include_prompt_ids": {
"type": "boolean",
"description": "When true and prompt_id is set, response includes promptIds (array of prompt UUIDs) per citation row for client-side batching (e.g. split citations by cluster)."
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get available companies (paginated). Response includes pagination.total_count and pagination.total_pages; use page and page_size (max 50 per call) for additional pages. Superusers receive all companies; other users receive only their home company. Optional search filters by company name (case-insensitive substring). Optional type filters by company type: advertiser, publisher, or agency. Same payload as GET /api/companies/.
{
"type": "object",
"properties": {
"page_size": {
"type": "number",
"description": "Number of companies to return per page"
},
"page": {
"type": "number",
"description": "Page number for pagination"
},
"search": {
"type": "string",
"description": "Substring to match against company name (case-insensitive). Use when listing many companies or the user gives a partial name."
},
"type": {
"type": "string",
"description": "Filter by company type",
"enum": [
"advertiser",
"publisher",
"agency"
]
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get competitive breakdown: target brand metrics, favorite competitor rows, and optional by_dimension slice (topic, funnel, or platform). Default date range: last 7 days. Supports weighted mode (calculation_mode=weighted). Same payload as GET /api/competitive-breakdown/. Success: targetBrand, competitors[], optional byDimension[]. Response always includes weightMetadata with calculationMode and unit='ratio_0_1'. In weighted mode weightMetadata also includes weightCoverage and platformsWithoutWeight. weightCoverage is a ratio between 0 and 1 when coverage can be computed (1.0 = all measured platforms have a weight, 0-1 = partial coverage). weightCoverage may be null when coverage is not computed or not applicable for the current aggregation (e.g. market-share data unavailable for the period). platformsWithoutWeight lists measured platforms excluded from weighted normalization because no weight was available. Note: platformsWithoutWeight=[] does not imply weightCoverage=1.0 when weightCoverage is null. Competitor list sort: sort_by (visibility, share_of_voice, mentions, rank [default], name) and order (asc [default], desc). Dimension slice sort: dimension_sort_by (target_visibility [default], target_share_of_voice, gap_visibility, gap_share_of_voice, key) and dimension_order (desc [default], asc). by_dimension also exposes gapVisibility and gapShareOfVoice (target minus top competitor). Pagination (page, page_size up to 200) applies to by_dimension rows when group_by is set. Only favorite competitors are included by default; competitor_name can filter to a specific competitor (if not a favorite, a suggestion is returned). Filters: brand_id, lookback_days, start_date, end_date, group_by, calculation_mode, COMPETITORS permission. Error: {success:false,error:string}.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string"
},
"start_date": {
"type": "string"
},
"end_date": {
"type": "string"
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days ending today (language-agnostic). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"group_by": {
"type": "string",
"enum": [
"topic",
"funnel",
"platform"
],
"description": "Optional single dimension for by_dimension array"
},
"topic_id": {
"type": "string"
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
]
},
"platform": {
"type": "string"
},
"model": {
"type": "string"
},
"competitor_name": {
"type": "string"
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies LLM/platform market-share weighting."
},
"sort_by": {
"type": "string",
"enum": [
"visibility",
"share_of_voice",
"mentions",
"rank",
"name"
],
"description": "Sort field for competitor list (default: rank)"
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Sort order for competitor list (default: asc)"
},
"dimension_sort_by": {
"type": "string",
"enum": [
"target_visibility",
"target_share_of_voice",
"gap_visibility",
"gap_share_of_voice",
"key"
],
"description": "Sort field for by_dimension rows (default: target_visibility)"
},
"dimension_order": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Sort order for by_dimension rows (default: desc)"
},
"page": {
"type": "number"
},
"page_size": {
"type": "number"
}
}
}{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"additionalProperties": true,
"description": "Competitive breakdown (target, competitors, optional by_dimension). GET /api/competitive-breakdown/."
}
},
"additionalProperties": true,
"required": [
"success",
"data"
]
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get the aggregated Competitor Detail for a single competitor: compact snapshot (visibility, share of voice, average mentions, rank), the topics where the competitor outperforms the current brand (biggest visibility advantages), the domains where the competitor appears in more prompts than the current brand (citation advantage), and the prompts where the competitor performs best. Requires competitor_name and a single brand_id. Use this when a user wants to understand why a specific competitor is performing well. Same payload as GET /api/competitors/detail/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand UUID. Optional when MCP context provides the current brand."
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Required by the API unless MCP context supplies start_date or resolves date_range_preset."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Required by the API unless MCP context supplies end_date or resolves date_range_preset."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days ending today (language-agnostic). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic UUID (comma-separated UUIDs allowed)."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage."
},
"platform": {
"type": "string",
"description": "Filter by AI platform (maps to query param ai_platform), e.g. chatgpt, gemini, googleaioverview."
},
"model": {
"type": "string",
"description": "Filter by AI model name (platform-specific)."
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter). Use getPromptPersonas to list valid ids for the brand."
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies LLM/platform market-share weighting."
},
"competitor_name": {
"type": "string",
"description": "Exact competitor name to inspect (required)."
}
},
"required": [
"competitor_name"
]
}{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"additionalProperties": true,
"description": "Aggregated competitor detail (competitor, currentBrand, snapshot, topicAdvantages, citationAdvantages, topProducts, topPrompts). GET /api/competitors/detail/."
}
},
"additionalProperties": true,
"required": [
"success",
"data"
]
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get comparative metrics with favorite competitors (share of voice, mentions, etc.). Enables competitive analysis. Returns all favorite competitors configured for the brand. When competitor_name is provided and it is not a favorite competitor, the response includes a suggestion to add it as favorite first. Same payload as GET /api/favorite-competitor-metrics/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand UUID. Optional when MCP context provides the current brand."
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Required by the API unless MCP context supplies start_date or resolves date_range_preset."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Required by the API unless MCP context supplies end_date or resolves date_range_preset."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days ending today (language-agnostic). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic UUID (comma-separated UUIDs allowed)."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage."
},
"platform": {
"type": "string",
"description": "Filter by AI platform (maps to query param ai_platform), e.g. chatgpt, gemini, googleaioverview."
},
"model": {
"type": "string",
"description": "Filter by AI model name (platform-specific)."
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter). Use getPromptPersonas to list valid ids for the brand."
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies LLM/platform market-share weighting."
},
"competitor_name": {
"type": "string",
"description": "Optional exact competitor name to compare. If this competitor is not in the brand's favorite competitors, the response will include a suggestion to add it as a favorite first."
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Competitor metric row with optional assistant_suggestion."
}
}
},
"additionalProperties": true,
"required": [
"success",
"data"
]
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get competitive presence distribution showing how responses are distributed across three categories for each brand (your brand and favorite competitors): 'brandOnly' (brand present, no competitors present), 'shared' (brand + ≥1 competitor present), and 'competitorOnly' (≥1 competitor present, brand absent). This helps understand competitive positioning - high 'brandOnly' means your brand dominates those responses, high 'shared' means competitive overlap, high 'competitorOnly' means missed opportunities. Use this when users ask about 'presence distribution', 'competitive presence', 'where do competitors appear', or want to understand competitive overlap. Supports filtering by topic_id (from getBrandTopics), funnel (awareness, consideration, conversion), platform, and model. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/competitors/presence-distribution/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand UUID. Optional when MCP context provides the current brand."
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Required by the API unless MCP context supplies start_date or resolves date_range_preset."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Required by the API unless MCP context supplies end_date or resolves date_range_preset."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days ending today (language-agnostic). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic UUID (comma-separated UUIDs allowed)."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage."
},
"platform": {
"type": "string",
"description": "Filter by AI platform (maps to query param ai_platform), e.g. chatgpt, gemini, googleaioverview."
},
"model": {
"type": "string",
"description": "Filter by AI model name (platform-specific)."
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter). Use getPromptPersonas to list valid ids for the brand."
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies LLM/platform market-share weighting."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Competitive presence distribution (GET /api/competitors/presence-distribution/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get visibility scores matrix for topics × competitors showing a heatmap of visibility scores for each topic × competitor combination. Returns visibility scores (percentage) for your brand and favorite competitors across all topics or a specific topic. Use this when users ask about 'competitors matrix', 'topics matrix', 'visibility by topic and competitor', or want to see a comprehensive comparison of visibility across topics and competitors. The matrix shows which topics each competitor dominates and where your brand has opportunities. Supports filtering by topic_id (from getBrandTopics), funnel (awareness, consideration, conversion), platform, and model. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/competitors/topics-matrix/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand UUID. Optional when MCP context provides the current brand."
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Required by the API unless MCP context supplies start_date or resolves date_range_preset."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Required by the API unless MCP context supplies end_date or resolves date_range_preset."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days ending today (language-agnostic). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic UUID (comma-separated UUIDs allowed)."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage."
},
"platform": {
"type": "string",
"description": "Filter by AI platform (maps to query param ai_platform), e.g. chatgpt, gemini, googleaioverview."
},
"model": {
"type": "string",
"description": "Filter by AI model name (platform-specific)."
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter). Use getPromptPersonas to list valid ids for the brand."
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies LLM/platform market-share weighting."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Topics x competitors matrix (GET /api/competitors/topics-matrix/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get list of content folders (recommendation folders) generated by OnSite, OffSite, and Shared Media agents. Content folders organize recommendations by topic and agent type. Each folder contains content pages with detailed recommendations for improving brand visibility. Folders are organized by topic (from getBrandTopics) and agent_type (onsite for content recommendations, offsite for earned media, shared_media for shared media - YouTube, TikTok, Instagram, LinkedIn, Pinterest). Use this when users ask about 'content folders', 'recommendation folders', 'what folders exist', or want to see how recommendations are organized. Supports filtering by brand_id, agent_type (onsite, offsite, shared_media), topic_id (from getBrandTopics), and search (folder name). IMPORTANT: When user asks for 'all' or comprehensive data, use appropriate page_size values. If brand_id is not provided, uses default from UI context (current brand). Same payload as GET /api/content-folders/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"agent_type": {
"type": "string",
"enum": [
"onsite",
"offsite",
"shared_media"
],
"description": "Filter by agent type: 'onsite' (content recommendations for owned media), 'offsite' (earned media recommendations), 'shared_media' (shared media - YouTube, TikTok, Instagram, LinkedIn, Pinterest)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from getBrandTopics results or user message."
},
"search": {
"type": "string",
"description": "Search folders by name (case-insensitive)"
},
"page": {
"type": "number",
"description": "Page number for pagination"
},
"page_size": {
"type": "number",
"description": "Number of folders per page. Default is 20."
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get detailed view of a specific content page (recommendation page) including full recommendation content, structured output, SEO recommendations, FAQ items, evidence sources, and progress tracking. Returns complete information about a single content page with all its recommendations and metadata. Use this when users ask about a specific content page, want to see full recommendation details, or need to understand what actions are recommended. Requires page_id (extract from getContentPages results or user message). If brand_id is not provided, uses default from UI context (current brand). Same payload as GET /api/content-pages/{id}/.
{
"type": "object",
"properties": {
"page_id": {
"type": "string",
"description": "The UUID of the content page. Extract this from getContentPages results or user message when they mention a specific page ID."
},
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
}
},
"required": [
"page_id"
]
}{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Content page detail."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get list of content pages (recommendation pages) generated by OnSite and OffSite agents. Content pages contain detailed recommendations for improving brand visibility, including structured content suggestions, SEO recommendations, FAQ items, and evidence sources. Each page is associated with a content folder (organized by topic and agent type) and contains actionable recommendations. Use this when users ask about 'content recommendations', 'recommendation pages', 'what content pages exist', or want to see detailed content plans. Supports filtering by brand_id, folder_id (from getContentFolders), and status (active, disabled, deleted). IMPORTANT: When user asks for 'all' or comprehensive data, use appropriate page_size values. ALWAYS use appropriate sorting: sort_by='created_at' with order='desc' for newest, sort_by='updated_at' with order='desc' for recently updated. If brand_id is not provided, uses default from UI context (current brand). Same payload as GET /api/content-pages/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"folder_id": {
"type": "string",
"description": "Filter by folder ID (UUID). Extract from getContentFolders results or user message."
},
"status": {
"type": "string",
"enum": [
"active",
"disabled",
"deleted"
],
"description": "Filter by page status: 'active' (active pages), 'disabled' (disabled pages), 'deleted' (deleted pages)"
},
"page": {
"type": "number",
"description": "Page number for pagination"
},
"page_size": {
"type": "number",
"description": "Number of pages per page. Default is 20."
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get explanation of core Meikai entities and concepts (Company, Brand, Topic, Prompt), product pillars (Brand Monitor, Site Scanner, Trend Explorer, Ads Analytics, Product Tracker), funnel stages, citation media types, a grouped map of MCP data tools by product area, and an index of documentation-only MCP tools. Optional `sections` filters the response for smaller payloads: overview, mcp_map, permissions, citation_media_types, hierarchy, prompt_studio, clustering, optimization, insights, or all (default). Use this when users ask 'how is the data structured', 'what is a topic', 'what are prompts', 'what products does Meikai have', 'which MCP tool should I use', 'how does Meikai work', 'explain the hierarchy', or questions about citation media types (Earned Media, Owned Media, etc.).
{
"type": "object",
"properties": {
"sections": {
"oneOf": [
{
"type": "array",
"items": {
"type": "string",
"enum": [
"overview",
"mcp_map",
"permissions",
"citation_media_types",
"hierarchy",
"prompt_studio",
"clustering",
"optimization",
"insights",
"all"
]
},
"description": "Subset of core-concepts payload to return. Omit for full response. Use ['overview'] for mission/pillars/funnel only; ['mcp_map'] for tool map + doc catalog; ['all'] is explicit full payload."
},
{
"type": "string",
"enum": [
"overview",
"mcp_map",
"permissions",
"citation_media_types",
"hierarchy",
"prompt_studio",
"clustering",
"optimization",
"insights",
"all"
],
"description": "Single section id (same ids as array form)."
}
]
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false,
"required": [
"success",
"data"
],
"description": "Static product documentation payload."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get daily visibility data for a brand over a date range. Visibility is the percentage of LLM responses that mention the brand (responses_with_mentions / total_responses). Returns per-day visibility values for each date in the range, allowing day-over-day trend analysis. Each result includes: date, brandName, value (visibility percentage), responses_with_mentions (count of responses mentioning the brand), and total_responses (total responses analyzed for that date). IMPORTANT: To enable dimensional analysis, use the 'dimensions' parameter. Provide dimensions as an array of strings, e.g., ['topic', 'funnel'] to include both topic and funnel as dimensions in the result set. When 'topic' is in dimensions, each result row will include a 'topicId' field. When 'funnel' is in dimensions, each result row will include a 'funnel' field. You can also provide topic_id and/or funnel as separate filter parameters to filter the data while including dimensions. For example: dimensions=['topic', 'funnel'] with topic_id='xxx' will show visibility broken down by topic and funnel dimensions, filtered to the specified topic. Also supports filtering by platform and model (these do not appear as dimensions). If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/daily-visibility/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days ending today (language-agnostic). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from the user's message or from previous tool results (e.g., from getBrandTopics). Use this to filter data to a specific topic. To include topic as a dimension in the output, use dimensions=['topic'] instead or in addition."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage. Use this to filter data to a specific funnel stage. To include funnel as a dimension in the output, use dimensions=['funnel'] instead or in addition."
},
"platform": {
"type": "string",
"description": "Filter by AI platform (e.g. 'chatgpt', 'gemini', 'googleaioverview')"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g. 'gpt-5', 'gemini-2.5-flash'). Model names vary by platform"
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter). Use getPromptPersonas to list valid ids for the brand."
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies LLM/platform market-share weighting."
},
"dimensions": {
"type": "array",
"items": {
"type": "string",
"enum": [
"topic",
"funnel"
]
},
"description": "Dimensions to include in the result set. Provide an array of dimension names, e.g., ['topic', 'funnel']. When 'topic' is included, each result row will have a 'topicId' field. When 'funnel' is included, each result row will have a 'funnel' field. This enables dimensional analysis. You can combine this with topic_id and/or funnel filter parameters to filter while including dimensions."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Daily visibility time series (GET /api/daily-visibility/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get domain-level citation analysis with aggregated metrics. Canonical route for domain-level analysis. Returns a list of domains with citation statistics including total citations per domain, number of URLs, brand mentions, brand presence percentage, competitor-only mentions and presence, share of citations, prompts impacted, and top URLs. Supports filtering by topic_id (PREFERRED), prompt_id (single UUID or comma-separated list for multiple prompts), media_type (Reference & Informational, Public & Institutional, Competitor, Earned Media, Commercial Media, Owned Media, Shared Media), funnel (awareness, consideration, conversion), platform, model, and exclude_domains. IMPORTANT: When user asks for 'all', 'top', 'most', or comprehensive analysis, use page_size up to 200 (maximum allowed to prevent token limit issues). ALWAYS use appropriate sorting: sort_by='domainCitationCount' with order='desc' for most cited domains, sort_by='domainBrandMentions' with order='desc' for domains with most brand mentions, sort_by='shareOfCitationDomain' with order='desc' for highest share, sort_by='lastSeenAt' with order='desc' for recent, sort_by='domain' with order='asc' for alphabetical. Never rely on default sorting - always specify sort_by and order based on the query intent. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/domain-analysis/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days ending today (language-agnostic). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). PREFERRED over other filters when filtering by topic - use this when you have topic_id from getBrandTopics or user message."
},
"prompt_id": {
"type": "string",
"description": "Filter by prompt ID(s). Can be a single UUID or comma-separated list of UUIDs. Use this to get domain analysis for specific prompts (e.g., prompts in a cluster)."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage"
},
"platform": {
"type": "string",
"description": "Filter by AI platform (e.g., 'chatgpt', 'gemini', 'perplexity', 'grok', 'copilot', 'openai', 'google-ai-mode', 'googleaioverview'). Common values: chatgpt, gemini, perplexity, grok, copilot, googleaioverview"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g., 'gpt-5', 'gpt-5-t-mini', 'gemini-2.5-flash', 'grok-3', 'grok-4-auto', 'perplexity'). Model names vary by platform"
},
"media_type": {
"type": "string",
"enum": [
"Reference & Informational",
"Public & Institutional",
"Competitor",
"Earned Media",
"Commercial Media",
"Owned Media",
"Shared Media"
],
"description": "Filter by media type. Valid values: 'Reference & Informational' (reference sites, informational content), 'Public & Institutional' (public institutions, government sites), 'Competitor' (competitor websites), 'Earned Media' (unpaid media coverage like press mentions, reviews, articles), 'Commercial Media' (commercial/advertising media), 'Owned Media' (content you own/control like your website, blog), 'Shared Media' (shared/social platforms)"
},
"exclude_domains": {
"type": "string",
"description": "Exclude domains from results. Comma-separated list of domain names (case-insensitive)"
},
"page": {
"type": "number",
"description": "Page number for pagination"
},
"page_size": {
"type": "number",
"description": "Number of domains per page. Maximum allowed is 200 to prevent token limit issues. Use values up to 200 when user wants comprehensive data, 'all' results, or analysis of top/most domains. Default is 50."
},
"sort_by": {
"type": "string",
"enum": [
"domain",
"domainCitationCount",
"domainUrlCount",
"domainBrandMentions",
"domainBrandPresence",
"domainCompetitorOnlyMentions",
"domainCompetitorOnlyPresence",
"promptsImpactedByDomain",
"shareOfCitationDomain",
"lastSeenAt",
"firstSeenAt"
],
"description": "Field to sort by. ALWAYS use appropriate sorting based on query intent: 'domainCitationCount' for most/least cited domains (with order='desc' for most, order='asc' for least), 'domainBrandMentions' for most/least URLs mentioning brand per domain (with order='desc' for most, order='asc' for least), 'domainBrandPresence' for brand presence ratio, 'domainCompetitorOnlyMentions' for domains where only competitors are mentioned (not the target brand), 'domainCompetitorOnlyPresence' for competitor-only presence ratio, 'shareOfCitationDomain' for highest/lowest share (with order='desc' for highest, order='asc' for lowest), 'lastSeenAt' for recent/oldest (with order='desc' for recent, order='asc' for oldest), 'firstSeenAt' for earliest/latest first appearance (with order='asc' for earliest, order='desc' for latest), 'domain' for alphabetical (with order='asc'). NEVER rely on defaults - always specify sort_by and order."
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Sort order: 'asc' for ascending or 'desc' for descending. ALWAYS specify: Use 'desc' for top/most/highest/recent, 'asc' for least/lowest/oldest/alphabetical. Must ALWAYS be provided when sort_by is used - never rely on defaults."
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Fetch robots.txt for a domain and evaluate crawl permissions by path and user agent. Use this when the user asks for domain/site analysis about crawlability, indexability, citation eligibility, robots policy, or site-level GEO diagnostics. Do not use this for generic strategy questions with no domain/site analysis request. Input requires a domain or URL; if missing, ask for one. Returns ai_platform_summary (platform -> agent details), path_checks (path -> agent -> allowed), and checks for '/'. AI agent labels are aligned as closely as possible with Site Scanner canonical bot-agent labels.
{
"type": "object",
"properties": {
"domain": {
"type": "string",
"description": "Domain or URL to validate (e.g. example.com or https://example.com/page)."
},
"paths": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional list of paths to validate (e.g. ['/','/culture','/voyages']). Defaults to ['/']."
},
"user_agents": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional list of user agents to validate. Defaults to ['*','GPTBot','Googlebot','PerplexityBot','ClaudeBot']."
}
},
"required": [
"domain"
]
}{
"oneOf": [
{
"type": "object",
"properties": {},
"additionalProperties": true,
"description": "Parsed robots.txt policy for a domain."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get comprehensive guide on Generative Engine Optimization (GEO) best practices. Use this when users ask 'how to optimize for AI', 'GEO tips', 'how to improve AI visibility', 'best practices for LLMs', or any question about optimizing content for AI platforms. Returns actionable advice on content structure, authority, citations, technical optimization, plus Google Search Essentials alignment for AI Overviews and AI Mode.
{
"type": "object",
"properties": {},
"required": []
}{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false,
"required": [
"success",
"data"
],
"description": "Static product documentation payload."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get prompts where the publisher has higher share of citations (Earned Media). Returns prompt_id, citations, total_citations, citation_rate, domain_urls (top 20). Same payload as GET /api/authority/highly-cited-prompts/.
{
"type": "object",
"properties": {
"company_id": {
"type": "string",
"description": "The UUID of the company (optional, defaults to context company_id; required for publisher context)"
},
"brand_id": {
"type": "string",
"description": "The UUID of the brand to scope to (optional; if provided with company_id, filters to that brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to context or last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to context or today)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID)"
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., chatgpt, gemini, perplexity, googleaioverview)"
},
"model": {
"type": "string",
"description": "Filter by AI model name"
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Highly cited prompts (GET /api/authority/highly-cited-prompts/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get distinct iteration start dates for a brand. Returns dates from Topic model, sorted most recent first. Each result includes the date value (ISO format YYYY-MM-DD) and an index (where 1 is the oldest iteration). Optionally pass classification='standard' to restrict to cycles containing ≥1 unbranded prompt under a regular topic (Visibility dashboard scope), or classification='evergreen' for cycles containing ≥1 branded prompt under an evergreen topic (Perception dashboards scope). Same payload as GET /api/iteration-start-date/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"classification": {
"type": "string",
"enum": [
"standard",
"evergreen"
],
"description": "Optional dashboard classification. 'standard' = cycles with \u22651 unbranded prompt under a regular topic (Visibility scope). 'evergreen' = cycles with \u22651 branded prompt under an evergreen topic (Perception scope). Omit to return all cycles."
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "array",
"items": {
"type": "string"
},
"description": "Iteration start dates (YYYY-MM-DD)."
}
},
"additionalProperties": false,
"required": [
"success",
"data"
]
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get definitions and explanations of KPIs (Key Performance Indicators) and metrics used in Meikai. CRITICAL: ALWAYS use this tool when users ask 'what does KPI mean', 'what is visibility score', 'explain share of voice', 'what are the metrics', 'how is X calculated', 'what does priority tier mean', 'what is very high priority', 'explain strategic debt', 'what is share of shelf', 'explain average position', 'what is panels count', 'explain real traffic metrics', 'what is sample quality', 'sample quality band', 'qualité échantillon', 'qualite echantillon', 'explain EIVA reliability', or any question about metric definitions, KPI meanings, priority tiers, or how metrics work. Returns comprehensive definitions of visibility metrics (Visibility Score, Share of Voice, Mentions, Citations), engagement metrics, brand perception metrics, commerce metrics, shopping metrics (Share of Shelf, Average Position), real traffic metrics (Panelists, App/Web share), recommendation priority tiers (very_high, high, medium, strategic_debt, deprioritized), citation insights fields including sample_quality_band (sample quality / qualité échantillon), and other key performance indicators with formulas and explanations.
{
"type": "object",
"properties": {
"category": {
"type": "string",
"enum": [
"visibility",
"engagement",
"brand_perception",
"commerce",
"shopping",
"real_traffic",
"all"
],
"description": "Which category of KPIs to show. 'visibility' for brand visibility metrics, 'engagement' for user engagement metrics, 'brand_perception' for brand perception scores, 'commerce' for commerce conversion metrics, 'shopping' for Product Tracker metrics, 'real_traffic' for panel-based real user metrics, 'all' for all categories (default)."
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false,
"required": [
"success",
"data"
],
"description": "Static product documentation payload."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get the number of distinct keywords for the selected period (badge). Use when users ask for keyword count or volume. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/v1/keywords/count/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Keywords count KPI."
},
"description": "GET /api/v1/keywords/count/"
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get keyword momentum (lifecycle/scatter) data: keyword_share, mentions_current, mentions_prev, change_in_mentions, unique_users, repetition. Paginated. Use for keyword lifecycle or momentum analysis. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/v1/keywords/momentum/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"page": {
"type": "number",
"description": "Page number (optional, default: 1)."
},
"page_size": {
"type": "number",
"description": "Items per page (optional, default: 500, max: 1000)."
},
"sort_by": {
"type": "string",
"description": "Sort field(s), comma-separated (optional). Allowed: keyword, keyword_share, mentions_current, mentions_prev, change_in_mentions_abs, change_in_mentions_pct, unique_users_current, unique_messages_current, repetition. Default: mentions_current."
},
"order": {
"type": "string",
"description": "Sort order(s), comma-separated to match sort_by (optional). 'asc' or 'desc'. Default: desc."
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get top keywords by keyword_share (popular keywords). Paginated. Use when users ask for most popular or top keywords. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/v1/keywords/popular/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"page": {
"type": "number",
"description": "Page number (optional, default: 1)."
},
"page_size": {
"type": "number",
"description": "Items per page (optional, default: 10)."
},
"sort_by": {
"type": "string",
"description": "Sort field(s), comma-separated (optional). Allowed: keyword, keyword_share, mentions_current. Default: keyword_share."
},
"order": {
"type": "string",
"description": "Sort order(s), comma-separated to match sort_by (optional). 'asc' or 'desc'. Default: desc."
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get trending keywords by change_in_mentions_pct. Filter by min_mentions_current (default 5). Use when users ask for trending or rising keywords. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/v1/keywords/trending/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"min_mentions_current": {
"type": "number",
"description": "Minimum mentions in current period to include keyword (optional, default: 5)."
},
"page": {
"type": "number",
"description": "Page number (optional, default: 1)."
},
"page_size": {
"type": "number",
"description": "Items per page (optional, default: 10)."
},
"sort_by": {
"type": "string",
"description": "Sort field(s), comma-separated (optional). Allowed: keyword, change_in_mentions_abs, change_in_mentions_pct, mentions_current, mentions_prev. Default: change_in_mentions_pct."
},
"order": {
"type": "string",
"description": "Sort order(s), comma-separated to match sort_by (optional). 'asc' or 'desc'. Default: desc."
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get prompts where the publisher has lower share of citations (Earned Media). Returns prompt_id, citations, citation_rate (top 20). Same payload as GET /api/authority/lowly-cited-prompts/.
{
"type": "object",
"properties": {
"company_id": {
"type": "string",
"description": "The UUID of the company (optional, defaults to context company_id; required for publisher context)"
},
"brand_id": {
"type": "string",
"description": "The UUID of the brand to scope to (optional; if provided with company_id, filters to that brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to context or last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to context or today)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID)"
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., chatgpt, gemini, perplexity, googleaioverview)"
},
"model": {
"type": "string",
"description": "Filter by AI model name"
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Lowly cited prompts (GET /api/authority/lowly-cited-prompts/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get step-by-step instructions for connecting or installing Meikai MCP on external AI clients: ChatGPT (Settings → Apps → Developer mode → Create app), Claude.ai (Customize → Connectors), Perplexity (Customize → Connectors → Custom connector), Grok (Add connector → Custom), Cursor (.cursor/mcp.json), and any custom MCP client (OAuth + Streamable HTTP). Covers staging vs production MCP server URLs, OAuth setup (client_id mcp, no secret, PKCE), mcp.json configuration, connector/app install steps, sign-in with Meikai (including SSO), verification prompts, and troubleshooting (localhost, 401, missing connector, SAML loop). Use when users ask how to connect, install, or configure Meikai MCP, add Meikai as a ChatGPT app/connector, set up Claude/Perplexity/Grok MCP, configure Cursor mcp.json, or which MCP URL to use for dev vs enterprise.
{
"type": "object",
"properties": {
"client": {
"type": "string",
"enum": [
"chatgpt",
"claude",
"perplexity",
"grok",
"cursor",
"custom",
"all"
],
"description": "Which client to focus on: chatgpt, claude, perplexity, grok, cursor, custom (generic MCP client), or all. Omit or 'all' for every client together."
},
"environment": {
"type": "string",
"enum": [
"production",
"staging",
"local",
"all"
],
"description": "Which Meikai deployment. Default production for customer/enterprise; staging for internal dev QA; local for Docker/localhost."
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false,
"required": [
"success",
"data"
],
"description": "Static product documentation payload."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Brand Monitor mentions card: average target-brand mentions per response that mentions the brand (not raw mention volume). Same payload as GET /api/mentions-card/. Success: JSON array (usually one row). value = brand_mentions / responses_with_mentions; previous_value; pct_change; brand_mentions (raw weighted count); responses_with_mentions (denominator). Filters: brand_id, lookback_days (preferred for relative periods; overrides dates), start_date, end_date (API-required unless MCP context fills them), topic_id, funnel, platform (maps to ai_platform), model, calculation_mode. Error: {success:false,error:string}.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand UUID. Optional when MCP context provides the current brand."
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Required by the API unless MCP context supplies start_date or resolves date_range_preset."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Required by the API unless MCP context supplies end_date or resolves date_range_preset."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days ending today (language-agnostic). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic UUID (comma-separated UUIDs allowed)."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage."
},
"platform": {
"type": "string",
"description": "Filter by AI platform (maps to query param ai_platform), e.g. chatgpt, gemini, googleaioverview."
},
"model": {
"type": "string",
"description": "Filter by AI model name (platform-specific)."
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter). Use getPromptPersonas to list valid ids for the brand."
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies LLM/platform market-share weighting."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": [
"number",
"null"
],
"description": "Metric value for the current period."
},
"previous_value": {
"type": [
"number",
"null"
],
"description": "Metric value for the previous period of equal length."
},
"pct_change": {
"type": [
"number",
"null"
],
"description": "Relative change vs previous_value (decimal, e.g. 0.1 = +10%)."
},
"brand_mentions": {
"type": [
"number",
"null"
],
"description": "Weighted sum of target-brand mention counts in the period."
},
"responses_with_mentions": {
"type": [
"number",
"null"
],
"description": "Weighted count of responses that mention the target brand."
}
},
"additionalProperties": false,
"description": "Mentions card row: value = brand_mentions / responses_with_mentions (average mentions per response with a brand mention)."
},
"description": "Mentions card rows (GET /api/mentions-card/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get the most cited URLs for the company's domain (Earned Media). Returns URLs that received the most citations within the period (top 20). Same payload as GET /api/authority/most-cited-urls/.
{
"type": "object",
"properties": {
"company_id": {
"type": "string",
"description": "The UUID of the company (optional, defaults to context company_id; required for publisher context)"
},
"brand_id": {
"type": "string",
"description": "The UUID of the brand to scope to (optional; if provided with company_id, filters to that brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to context or last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to context or today)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID)"
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., chatgpt, gemini, perplexity, googleaioverview)"
},
"model": {
"type": "string",
"description": "Filter by AI model name"
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Top cited URLs (GET /api/authority/most-cited-urls/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get comprehensive guide for installing the Meikai tracking pixel on your website. CRITICAL: ALWAYS use this tool when users ask 'how to install pixel', 'install tracking', 'setup pixel', 'how to add tracking', 'pixel installation', or any question about installing or setting up Meikai tracking. Returns step-by-step instructions for different integration methods including simple script tag, Google Tag Manager (client-side and server-side), with code examples, tracking endpoint URL (https://track.meikai.ai/api/v1/track), and best practices. Provides ready-to-use code snippets that users can copy and paste.
{
"type": "object",
"properties": {
"method": {
"type": "string",
"enum": [
"script_tag",
"gtm_client",
"gtm_server",
"all"
],
"description": "Which installation method to show. 'script_tag' for simple script tag method, 'gtm_client' for Google Tag Manager client-side, 'gtm_server' for Google Tag Manager server-side, 'all' for all methods (default)."
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false,
"required": [
"success",
"data"
],
"description": "Static product documentation payload."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get detailed information about a specific prompt by its ID. Extract the prompt_id (UUID) from the user's message when they mention a prompt ID. Same payload as GET /api/prompt-detail/{prompt_id}/.
{
"type": "object",
"properties": {
"prompt_id": {
"type": "string",
"description": "The UUID of the prompt. Extract this from the user's message when they mention a prompt ID."
}
},
"required": [
"prompt_id"
]
}{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Prompt detail (GET /api/prompt-detail/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get detailed information about a specific prompt in Brand Monitor specialized format. Different from getPromptDetail which uses the ViewSet. This endpoint provides a view optimized for the Brand Monitor dashboard. Same payload as GET /api/prompt-detail/{prompt_id}/.
{
"type": "object",
"properties": {
"prompt_id": {
"type": "string",
"description": "The UUID of the prompt. Extract this from the user's message when they mention a prompt ID."
}
},
"required": [
"prompt_id"
]
}{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Prompt detail (GET /api/prompt-detail/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get list of prompts in Brand Monitor specialized format. Different from getPrompts which uses the ViewSet. This endpoint provides a view optimized for the Brand Monitor dashboard with potentially different metrics and structure. Supports filtering by topic_id, funnel, platform, model, and search; pagination (page, page_size); and sorting (sort_by, order). Same payload as GET /api/prompt-list/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID)"
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage"
},
"platform": {
"type": "string",
"description": "Filter by AI platform (e.g., 'chatgpt', 'gemini', 'perplexity', 'grok', 'copilot', 'googleaioverview')"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g., 'gpt-5', 'gemini-2.5-flash', 'grok-3')"
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID (assigned active regular prompts)."
},
"search": {
"type": "string",
"description": "Search query for prompt text (optional)"
},
"sort_by": {
"type": "string",
"enum": [
"last_run_date",
"mentions",
"share_of_voice",
"share_of_voice_position",
"runs_count",
"latest_response_text_trunc",
"last_five_responses",
"prompt_text",
"topic_text",
"funnel",
"competitors",
"citations",
"presence",
"platforms"
],
"description": "Field to sort by (optional). Valid values: last_run_date, mentions, share_of_voice, share_of_voice_position, runs_count, latest_response_text_trunc, last_five_responses, prompt_text, topic_text, funnel, competitors, citations, presence, platforms. Default: mentions (desc). For perception questions, use Brand Perception tools instead of sorting by sentiment."
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Sort order: 'asc' or 'desc' (optional). Default: desc"
},
"page": {
"type": "number",
"description": "Page number for pagination"
},
"page_size": {
"type": "number",
"description": "Number of prompts per page (optional, default: 20, max: 50)"
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get prompt-level performance breakdown (share of voice, mentions, citations). Classic-only in V1 — weighted metrics are not meaningful at prompt level. Default date range: last 7 days. Same payload as GET /api/prompt-performance-breakdown/. Success: paginated prompt rows with optional fanout and competitor slices. Optional include_fanouts (default false) adds fanout aggregate fields per prompt (avgQueriesPerResponse, responsesWithWebSearch, fanoutsCount, totalQueries). Fanout fields may be null when no fanout data is available, when fanout data is not joinable for the prompt/date/platform filters, or when the backend did not compute fanouts for that scope. null means not available / not computed, not zero. A numeric 0 means fanout data was computed and the count is zero. Do not treat null fanout values as 0 when aggregating across prompts. Optional include_competitors adds top 3 competitors by mentions. sort_by: last_run_date (default), share_of_voice, mentions, citations. Note: 'visibility' and 'avg_queries_per_response' are not supported sort fields in V1. Filters: brand_id, lookback_days, start_date, end_date, include_fanouts, include_competitors, search, sort_by. Error: {success:false,error:string}.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string"
},
"start_date": {
"type": "string"
},
"end_date": {
"type": "string"
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days ending today (language-agnostic). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string"
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
]
},
"platform": {
"type": "string"
},
"model": {
"type": "string"
},
"persona_id": {
"type": "string",
"description": "Prompt Studio persona UUID (assigned active regular prompts)."
},
"search": {
"type": "string"
},
"include_fanouts": {
"type": "boolean",
"description": "Include fanout aggregates (default false)"
},
"include_competitors": {
"type": "boolean"
},
"sort_by": {
"type": "string",
"enum": [
"last_run_date",
"share_of_voice",
"mentions",
"citations"
],
"description": "Sort field (default: last_run_date). 'visibility' and 'avg_queries_per_response' are not supported in V1."
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
]
},
"page": {
"type": "number"
},
"page_size": {
"type": "number"
}
}
}{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"additionalProperties": true,
"description": "Prompt performance breakdown (rows, pagination, optional fanouts). GET /api/prompt-performance-breakdown/."
}
},
"additionalProperties": true,
"required": [
"success",
"data"
]
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}List Prompt Studio personas available for Brand Monitor filtering. Returns personas that have at least one assigned active regular prompt for the brand. Use the returned id values as persona_id when calling visibility, prompt list, citations, query fanouts, competitor, or export tools. Same payload as GET /api/prompt-list/personas/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"iteration_start_date": {
"type": "string",
"description": "Optional Prompt Studio iteration start date (YYYY-MM-DD). Restricts to personas with prompt assignments in that iteration. Get valid values from getIterationStartDates."
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"id",
"name"
]
},
"description": "Prompt Studio personas available for filtering."
}
},
"additionalProperties": false,
"required": [
"success",
"data"
]
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get all responses for a specific prompt or brand. Supports filtering by date range, prompt, AI platform, and model. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/responses/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"prompt_id": {
"type": "string",
"description": "The UUID of the prompt (optional)"
},
"platform": {
"type": "string",
"description": "Filter by AI platform (e.g., 'chatgpt', 'gemini', 'perplexity', 'grok', 'copilot', 'openai', 'google-ai-mode', 'googleaioverview'). Common values: chatgpt, gemini, perplexity, grok, copilot, googleaioverview"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g., 'gpt-5', 'gpt-5-t-mini', 'gemini-2.5-flash', 'grok-3', 'grok-4-auto', 'perplexity'). Model names vary by platform"
},
"page": {
"type": "number",
"description": "Page number for pagination"
},
"page_size": {
"type": "number",
"description": "Number of responses per page. Maximum allowed is 100 to prevent token limit issues. Use values up to 100 when user wants comprehensive data or 'all' results. Default is 20."
}
},
"required": [
"brand_id"
]
}{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get list of prompts with filters, pagination, and sorting. Returns one row per prompt (prompt-grain only — NOT topic aggregates). topicName is context for each prompt, not a unique ranking dimension; multiple prompts share the same topicName. For slide deck 'Top N topics' use getVisibilityBreakdown with group_by=topic instead. CRITICAL: ALWAYS prefer using topic_id filter over search when you have a topic ID (from getBrandTopics or user message). Using topic_id typically returns fewer than 50 prompts per topic, making results more manageable. Use search ONLY when filtering by text content and you don't have a specific topic_id. Supports filtering by topic_id (PREFERRED - keeps results under 50), funnel (awareness, consideration, conversion), platform (chatgpt, gemini, perplexity, etc.), model, and search (use only when topic_id is not available). IMPORTANT: When fetching prompts, prefer topic_id filtering to keep result sets manageable (typically <50 prompts per topic). When user asks for 'all', 'top', 'best', 'worst', or comprehensive analysis, use page_size up to 50 (maximum allowed to prevent token limit issues) but prefer topic_id filtering first. ALWAYS use appropriate sorting: sort_by='share_of_voice' with order='desc' for top/best prompts, sort_by='last_run_date' with order='desc' for recent, sort_by='mentions' with order='desc' for most mentioned, sort_by='share_of_voice' with order='asc' for worst/lowest. Never rely on default sorting - always specify sort_by and order based on the query intent. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/prompt-list/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). PREFERRED over search when filtering by topic - use this when you have topic_id from getBrandTopics or user message."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage"
},
"platform": {
"type": "string",
"description": "Filter by AI platform (e.g., 'chatgpt', 'gemini', 'perplexity', 'grok', 'copilot', 'openai', 'google-ai-mode', 'googleaioverview'). Common values: chatgpt, gemini, perplexity, grok, copilot, googleaioverview"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g., 'gpt-5', 'gpt-5-t-mini', 'gemini-2.5-flash', 'grok-3', 'grok-4-auto', 'perplexity'). Model names vary by platform"
},
"search": {
"type": "string",
"description": "Search query for prompt text. Use ONLY when you don't have topic_id filter available. Prefer topic_id filter over search when possible."
},
"page": {
"type": "number",
"description": "Page number for pagination"
},
"page_size": {
"type": "number",
"description": "Number of prompts per page. Maximum allowed is 50 to prevent token limit issues. When using topic_id filter, results are typically under 50 prompts per topic, so page_size of 50 is usually sufficient. Use values up to 50 when user wants comprehensive data, 'all' results, or analysis of top/best/worst items. Default is 20."
},
"sort_by": {
"type": "string",
"enum": [
"last_run_date",
"mentions",
"share_of_voice",
"share_of_voice_position",
"runs_count",
"latest_response_text_trunc",
"last_five_responses",
"prompt_text",
"topic_text",
"funnel",
"competitors",
"citations",
"presence",
"platforms",
"brand_position"
],
"description": "Field to sort by. ALWAYS use appropriate sorting based on query intent: 'share_of_voice' for top/best/worst prompts (with order='desc' for top, order='asc' for worst), 'mentions' for most/least mentioned (with order='desc' for most, order='asc' for least), 'last_run_date' for recent/oldest (with order='desc' for recent, order='asc' for oldest), 'prompt_text' for alphabetical (with order='asc'). NEVER rely on defaults - always specify sort_by and order. Valid values: last_run_date, mentions, share_of_voice, share_of_voice_position, runs_count, latest_response_text_trunc, last_five_responses, prompt_text, topic_text, funnel, competitors, citations, presence, platforms, brand_position. For perception questions, use Brand Perception tools instead of sorting by sentiment."
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Sort order: 'asc' for ascending or 'desc' for descending. ALWAYS specify: Use 'desc' for top/best/highest/most/recent, 'asc' for worst/lowest/least/oldest/alphabetical. Must ALWAYS be provided when sort_by is used - never rely on defaults."
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}List prompts whose AI responses cited a specific citation URL or domain. UTM and other tracking query parameters are stripped from the URL before matching, so https://example.com/page?utm_source=chatgpt.com matches https://example.com/page. Provide either url or domain (url preferred when both are known). Returns promptId, promptText, citationsCount, firstSeenAt, lastSeenAt, topic metadata. Use when the user asks which prompts generated or linked to a citation URL. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/prompts-by-citation/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"url": {
"type": "string",
"description": "Citation URL to match (UTM/tracking params are stripped before lookup)."
},
"domain": {
"type": "string",
"description": "Citation domain to match (alternative to url)."
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"topic_id": {
"type": "string",
"description": "Optional topic UUID filter."
},
"prompt_id": {
"type": "string",
"description": "Optional prompt UUID filter (comma-separated list supported)."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Optional funnel stage filter."
},
"platform": {
"type": "string",
"description": "Optional AI platform filter (e.g. chatgpt, gemini)."
},
"model": {
"type": "string",
"description": "Optional AI model filter."
},
"page": {
"type": "number",
"description": "Page number for pagination (default 1)."
},
"page_size": {
"type": "number",
"description": "Prompts per page (default 50, max 200)."
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get query fanouts for a brand: list of prompts with the distinct web-search queries that each prompt triggered (and how often each query was used). Use this to see how each prompt 'fans out' into multiple search queries when AI platforms perform web search. Supports filtering by topic_id, funnel (awareness, consideration, conversion), platform, and search (filters by prompt text or fanout query text). Use sort_by and order to control sorting (default: total_queries, desc). If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/query-fanouts/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID)"
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID (same as Brand Monitor persona filter)."
},
"prompt_ids": {
"type": "string",
"description": "Optional comma-separated prompt UUIDs to restrict fanouts to a cluster or prompt subset"
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage"
},
"platform": {
"type": "string",
"description": "Filter by AI platform (e.g., 'chatgpt', 'gemini', 'perplexity', 'grok', 'copilot', 'googleaioverview')"
},
"search": {
"type": "string",
"description": "Search in prompt text or fanout query text (case-insensitive)"
},
"sort_by": {
"type": "string",
"enum": [
"total_queries",
"responses_with_web_search",
"avg_queries_per_response",
"fanouts_count",
"prompt_text",
"prompt_id"
],
"description": "Field to sort prompts by (default: total_queries)"
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Sort order (default: desc)"
},
"page": {
"type": "number",
"description": "Page number for pagination (default: 1)"
},
"page_size": {
"type": "number",
"description": "Items per page. Maximum allowed is 200 to match the backend API ceiling."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Query fanouts by prompt (GET /api/query-fanouts/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get documentation explaining what query fanouts are in Brand Monitor. Use this when users ask 'what are query fanouts', 'what is query fanout', 'explain query fanouts', 'how does query fanout work', or what the Query Fanouts tab shows. Returns a clear explanation of how prompts fan out into web-search queries, why it matters, and how to use the data.
{
"type": "object",
"properties": {},
"required": []
}{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false,
"required": [
"success",
"data"
],
"description": "Static product documentation payload."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get breakdown of real user traffic by dimension (models, apps, devices, languages, subscriptions). Data is only available monthly (no daily granularity). Latest available data depends on current date: after the 20th of current month, previous month is available; before the 20th, month before previous is available. Returns top N results per dimension to limit size. Maximum 20 items per dimension. Same payload as GET /api/real-traffic/ (models, apps, devices, languages, subscriptions).
{
"type": "object",
"properties": {
"dimension": {
"type": "string",
"enum": [
"models",
"apps",
"devices",
"languages",
"subscriptions"
],
"description": "Dimension to breakdown by: 'models' (model usage), 'apps' (app usage), 'devices' (device breakdown), 'languages' (language breakdown), 'subscriptions' (subscription breakdown)"
},
"start_month": {
"type": "string",
"description": "Start month in YYYY-MM format (optional). If not provided, uses latest available month only. If only start_month is provided, uses it as both start and end (single month)."
},
"end_month": {
"type": "string",
"description": "End month in YYYY-MM format (optional). If not provided, uses latest available month only. If only end_month is provided, uses it as both start and end (single month)."
},
"limit": {
"type": "number",
"description": "Number of results to return (optional, default: 10, max: 20)"
},
"brand_id": {
"type": "string",
"description": "Brand UUID (optional). If provided, automatically filters by the brand's country."
}
},
"required": [
"dimension"
]
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Real traffic breakdown by dimension."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get demographic breakdown of real user traffic (age, gender, income, etc.). Data is only available monthly (no daily granularity). Latest available data depends on current date: after the 20th of current month, previous month is available; before the 20th, month before previous is available. Returns aggregated data, not individual records. Same payload as GET /api/real-traffic/demographics/.
{
"type": "object",
"properties": {
"start_month": {
"type": "string",
"description": "Start month in YYYY-MM format (optional). If not provided, uses latest available month only. If only start_month is provided, uses it as both start and end (single month)."
},
"end_month": {
"type": "string",
"description": "End month in YYYY-MM format (optional). If not provided, uses latest available month only. If only end_month is provided, uses it as both start and end (single month)."
},
"demographic_dimension": {
"type": "string",
"enum": [
"age",
"gender",
"income",
"education",
"employment",
"marital_status"
],
"description": "Demographic dimension to breakdown by (optional, defaults to all). Options: 'age' (age_band), 'gender', 'income' (household_income), 'education', 'employment', 'marital_status'"
},
"brand_id": {
"type": "string",
"description": "Brand UUID (optional). If provided, automatically filters by the brand's country."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Demographics (GET /api/real-traffic/demographics/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get overview of real user traffic: number of panelists and time-series events (messages over time). Data is only available monthly (no daily granularity). Latest available data depends on current date: after the 20th of current month, previous month is available; before the 20th, month before previous is available. Maximum 12 months of data returned to prevent token limit issues. Same payload as GET /api/real-traffic/panelists/ and GET /api/real-traffic/events/.
{
"type": "object",
"properties": {
"start_month": {
"type": "string",
"description": "Start month in YYYY-MM format (optional). If not provided, uses latest available month only. If only start_month is provided, uses it as both start and end (single month)."
},
"end_month": {
"type": "string",
"description": "End month in YYYY-MM format (optional). If not provided, uses latest available month only. If only end_month is provided, uses it as both start and end (single month)."
},
"brand_id": {
"type": "string",
"description": "Brand UUID (optional). If provided, automatically filters by the brand's country."
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"properties": {},
"additionalProperties": true,
"description": "Panelists and events overview (GET /api/real-traffic/panelists/ and events/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get sample real user messages from the traffic. Useful for understanding query patterns. Data is only available monthly (no daily granularity). Latest available data depends on current date: after the 20th of current month, previous month is available; before the 20th, month before previous is available. Returns maximum 10 examples to avoid huge results. IMPORTANT: This tool returns metadata only (date, platform, model, country, device, etc.) but NOT the actual message content for privacy protection. When presenting results, focus on aggregated statistics and patterns from metadata, not specific message text. Same payload as GET /api/real-traffic/messages/.
{
"type": "object",
"properties": {
"start_month": {
"type": "string",
"description": "Start month in YYYY-MM format (optional). If not provided, uses latest available month only. If only start_month is provided, uses it as both start and end (single month)."
},
"end_month": {
"type": "string",
"description": "End month in YYYY-MM format (optional). If not provided, uses latest available month only. If only end_month is provided, uses it as both start and end (single month)."
},
"limit": {
"type": "number",
"description": "Number of sample messages to return (optional, default: 5, max: 10)"
},
"platform": {
"type": "string",
"description": "Filter by platform (optional, e.g., 'chatgpt', 'perplexity', 'googleaioverview')"
},
"model": {
"type": "string",
"description": "Filter by model (optional, e.g., 'gpt-4', 'gemini-2.5-flash')"
},
"brand_id": {
"type": "string",
"description": "Brand UUID (optional). If provided, automatically filters by the brand's country."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Sample messages metadata (GET /api/real-traffic/messages/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get list of content recommendations generated by OnSite, OffSite, Shared Media, and PDP agents. Recommendations are actionable content plans that help improve brand visibility in LLM responses and follow Google Search people-first guidance (no llms.txt/chunking hacks). OnSite agent generates content recommendations (content_update, new_content) for owned media, OffSite agent generates earned media recommendations, Shared Media agent generates shared media recommendations (YouTube, TikTok, Instagram, LinkedIn, Pinterest), PDP agent generates product-detail-page (pdp) recommendations. Returns paginated list of recommendation plans with metrics including priority_tier (very_high, high, medium, strategic_debt, deprioritized), progress_percentage, and status. Earned media recommendation items may include activation_profile (partner id/name, activation route, market, needs_review, confidence) when domain activation enrichment has run; use recommendation_type=earned_media with activation filters (activation_partner_id, activation_route, activation_market, activation_needs_review) or domain to query activation metadata — activation filters apply to earned media only. Persisted onsite/offsite plans may include metadata.google_ai_alignment scores from runtime guardrails. Use this when users ask about 'content recommendations', 'recommendations from agents', 'what content should I create', 'earned media opportunities', 'activation partners', 'media buy routes', 'shared media', 'high priority recommendations', 'very high priority recommendations', or want to see actionable content plans. Supports filtering by topic_id (from getBrandTopics), recommendation_type (earned_media, content_update, new_content, pdp, shared_media), agent_type (onsite, offsite, shared_media, pdp), status (not_started, in_progress, done), tier (priority tier: very_high, high, medium, strategic_debt, deprioritized - comma-separated for multiple), domain (publisher hostname), search, and earned-media activation filters. IMPORTANT: When user asks for 'all', 'comprehensive', or wants to see all recommendations, use page_size up to 100 (maximum allowed). ALWAYS use appropriate sorting: sort_by='priority_tier' with order='desc' for highest priority (very_high first), sort_by='created_at' with order='desc' for newest, sort_by='progress_percentage' with order='desc' for most progress. Never rely on default sorting - always specify sort_by and order based on the query intent. If brand_id is not provided, uses default from UI context (current brand). Same payload as GET /api/recommendations-list/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from getBrandTopics results or user message."
},
"recommendation_type": {
"type": "string",
"enum": [
"earned_media",
"content_update",
"new_content",
"pdp",
"shared_media"
],
"description": "Filter by recommendation type: 'earned_media' (OffSite agent - PR/media opportunities), 'content_update' (OnSite agent - update existing content), 'new_content' (OnSite agent - create new content), 'pdp' (PDP agent - product detail page recommendations), 'shared_media' (Shared Media agent - YouTube, TikTok, Instagram, LinkedIn, Pinterest)"
},
"agent_type": {
"type": "string",
"enum": [
"onsite",
"offsite",
"shared_media",
"pdp"
],
"description": "Filter by agent type: 'onsite' (content recommendations for owned media), 'offsite' (earned media recommendations), 'shared_media' (shared media recommendations - YouTube, TikTok, Instagram, LinkedIn, Pinterest), 'pdp' (product detail page recommendations)"
},
"status": {
"type": "string",
"enum": [
"not_started",
"in_progress",
"done",
"all"
],
"description": "Filter by recommendation status: 'not_started' (not yet started), 'in_progress' (work in progress), 'done' (completed), 'all' (all statuses)"
},
"tier": {
"type": "string",
"description": "Filter by priority tier. Can be a single tier or comma-separated list: 'very_high' (top 5% - highest priority, urgent), 'high' (top 10% - high priority), 'medium' (top 25% - opportunity), 'strategic_debt' (above median - long-term strategic value), 'deprioritized' (below median - hygiene). Example: 'very_high,high' to get both very high and high priority recommendations."
},
"search": {
"type": "string",
"description": "Search in plan titles, topic names, and summaries"
},
"domain": {
"type": "string",
"description": "Filter to plans with at least one recommendation on this publisher domain (normalized hostname, e.g. runnersworld.com). Response recommendations are pruned to matching items. Combine with recommendation_type=earned_media and activation filters to inspect activation_profile for one domain."
},
"activation_partner_id": {
"type": "string",
"description": "Filter earned media recommendations by activation partner UUID."
},
"activation_route": {
"type": "string",
"description": "Filter earned media recommendations by activation route. Single value or comma-separated list. Allowed: sponsored_editorial, direct_media_buy, editorial_outreach, product_review, affiliate_commerce, unknown."
},
"activation_market": {
"type": "string",
"description": "Filter earned media recommendations by activation market ISO2 code."
},
"activation_needs_review": {
"type": "boolean",
"description": "Filter earned media recommendations by activation-profile review status."
},
"page": {
"type": "number",
"description": "Page number for pagination"
},
"page_size": {
"type": "number",
"description": "Number of recommendations per page. Maximum allowed is 100 to prevent token limit issues. Use values up to 100 when user wants comprehensive data or 'all' results. Default is 50."
},
"sort_by": {
"type": "string",
"enum": [
"created_at",
"plan_title",
"priority_tier",
"progress_percentage"
],
"description": "Field to sort by. ALWAYS use appropriate sorting based on query intent: 'priority_tier' for highest/lowest priority (with order='desc' for highest priority - very_high first, order='asc' for lowest priority), 'created_at' for newest/oldest (with order='desc' for newest, order='asc' for oldest), 'progress_percentage' for most/least progress (with order='desc' for most, order='asc' for least), 'plan_title' for alphabetical sorting. NEVER rely on defaults - always specify sort_by and order."
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Sort order: 'asc' for ascending or 'desc' for descending. ALWAYS specify: Use 'desc' for highest/newest/most, 'asc' for lowest/oldest/least. Must ALWAYS be provided when sort_by is used."
},
"include_summary": {
"type": "boolean",
"description": "When true, adds data.summary with counts by priority_tier, agent_type, and recommendation_type for the filtered set."
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get referral traffic data from tracking_events (website traffic captured by tracking pixel) for a brand website or publisher company website. This data shows website visitors who came from LLM platforms (OpenAI, Perplexity, Anthropic, Google, Microsoft, You.com, DeepSeek) based on the utm_source parameter in the URL. When users click links from LLM platforms, those links contain utm_source that identifies the source platform. Returns platform breakdown, daily trends, and top pages. This is different from getBotsData which uses CDN logs - this uses actual user traffic data from tracking pixels. Provide exactly one of brand_id or company_id (publisher). If ids or dates are not provided, uses defaults from UI context when available. Same payload as GET /api/site-scanner/referral/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand UUID (XOR with company_id)."
},
"company_id": {
"type": "string",
"description": "Publisher company UUID for corporate website pixel (XOR with brand_id)."
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (required)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (required)"
},
"platform": {
"type": "string",
"enum": [
"OpenAI",
"Perplexity",
"Anthropic",
"Gemini",
"Google Search",
"Bing",
"Copilot",
"You.com",
"DeepSeek"
],
"description": "Optional platform filter. If not provided, returns data for all platforms."
}
},
"required": [
"start_date",
"end_date"
]
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Referral data (GET /api/site-scanner/referral/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get details of a specific response by its ID. Extract the response_id (UUID) from the user's message when they mention a response ID. Same payload as GET /api/responses/{response_id}/.
{
"type": "object",
"properties": {
"response_id": {
"type": "string",
"description": "The UUID of the response. Extract this from the user's message when they mention a response ID."
}
},
"required": [
"response_id"
]
}{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Response detail (GET /api/responses/{id}/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get responses count metric showing the total number of LLM responses analyzed for a brand, with period-over-period comparison. This is the denominator used in visibility calculations (visibility = mentions / responses_count). Returns current response count, previous count, and percentage change. Supports filtering by funnel (awareness, consideration, conversion), platform, model, and topic. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/responses-count/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days ending today (language-agnostic). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from the user's message or from previous tool results (e.g., from getBrandTopics)."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage"
},
"platform": {
"type": "string",
"description": "Filter by AI platform (e.g. 'chatgpt', 'gemini', 'googleaioverview')"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g. 'gpt-5', 'gemini-2.5-flash'). Model names vary by platform"
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter). Use getPromptPersonas to list valid ids for the brand."
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies LLM/platform market-share weighting."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": [
"number",
"null"
],
"description": "Total responses in the current period."
},
"promptCount": {
"type": [
"number",
"null"
],
"description": "Distinct prompts in the period."
},
"modelCount": {
"type": [
"number",
"null"
],
"description": "Distinct models in the period."
}
},
"additionalProperties": false,
"description": "Responses count card (single object, not period comparison)."
},
"description": "Responses count card (GET /api/responses-count/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get share of model metrics showing visibility breakdown by AI model (e.g. GPT-5, Gemini 2.5 Flash). Shows which specific models mention your brand most often and the visibility percentage for each model. Helps identify which models are most important for your brand's AI visibility. Supports filtering by funnel (awareness, consideration, conversion), platform, model, and topic. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/share-of-model/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days ending today (language-agnostic). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from the user's message or from previous tool results (e.g., from getBrandTopics)."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage"
},
"platform": {
"type": "string",
"description": "Filter by AI platform (e.g. 'chatgpt', 'gemini', 'googleaioverview')"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g. 'gpt-5', 'gemini-2.5-flash'). Model names vary by platform"
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter). Use getPromptPersonas to list valid ids for the brand."
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies LLM/platform market-share weighting."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Share of model breakdown (GET /api/share-of-model/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get share of platform metrics showing visibility breakdown by AI platform (e.g. ChatGPT, Gemini). Shows which platforms mention your brand most often and the visibility percentage for each platform. Helps identify which platforms are most important for your brand's AI visibility. Supports filtering by funnel (awareness, consideration, conversion), platform, model, and topic. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/share-of-platform/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days ending today (language-agnostic). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from the user's message or from previous tool results (e.g., from getBrandTopics)."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage"
},
"platform": {
"type": "string",
"description": "Filter by AI platform (e.g. 'chatgpt', 'gemini', 'googleaioverview')"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g. 'gpt-5', 'gemini-2.5-flash'). Model names vary by platform"
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter). Use getPromptPersonas to list valid ids for the brand."
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies LLM/platform market-share weighting."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Share of platform breakdown (GET /api/share-of-platform/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get share of voice metrics showing what percentage of total brand mentions belong to your brand versus competitors. Share of voice is calculated as your brand's mentions divided by total mentions across all brands. A higher share means your brand dominates the conversation in LLM responses. Returns breakdown by brand with percentages. Supports filtering by funnel (awareness, consideration, conversion), platform, model, and topic. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/share-of-voice/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days ending today (language-agnostic). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from the user's message or from previous tool results (e.g., from getBrandTopics)."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage"
},
"platform": {
"type": "string",
"description": "Filter by AI platform (e.g. 'chatgpt', 'gemini', 'googleaioverview')"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g. 'gpt-5', 'gemini-2.5-flash'). Model names vary by platform"
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter). Use getPromptPersonas to list valid ids for the brand."
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies LLM/platform market-share weighting."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Share of voice breakdown (GET /api/share-of-voice/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get share of voice card data showing what percentage of total brand mentions belong to your brand versus competitors, with period-over-period comparison. Share of voice = your_brand_mentions / total_mentions_all_brands. Returns current share percentage, previous share, and percentage change to track competitive positioning trends. Supports filtering by funnel (awareness, consideration, conversion), platform, model, and topic. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/share-of-voice-card/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days ending today (language-agnostic). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from the user's message or from previous tool results (e.g., from getBrandTopics)."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage"
},
"platform": {
"type": "string",
"description": "Filter by AI platform (e.g. 'chatgpt', 'gemini', 'googleaioverview')"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g. 'gpt-5', 'gemini-2.5-flash'). Model names vary by platform"
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter). Use getPromptPersonas to list valid ids for the brand."
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies LLM/platform market-share weighting."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": [
"number",
"null"
],
"description": "Metric value for the current period."
},
"previous_value": {
"type": [
"number",
"null"
],
"description": "Metric value for the previous period of equal length."
},
"pct_change": {
"type": [
"number",
"null"
],
"description": "Relative change vs previous_value (decimal, e.g. 0.1 = +10%)."
},
"brand_mentions": {
"type": [
"number",
"null"
],
"description": "Target brand mention count (weighted)."
},
"total_mentions": {
"type": [
"number",
"null"
],
"description": "Total mentions across target brand and competitors (weighted)."
}
},
"additionalProperties": false,
"description": "Share-of-voice card row: value = brand_mentions / total_mentions."
},
"description": "Share-of-voice card rows (GET /api/share-of-voice-card/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get comparison of brand metrics vs competitors in shopping results (share of shelf, position, rating, price). If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/shopping/brand-comparison/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from getBrandTopics or user message."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Brand comparison (GET /api/shopping/brand-comparison/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get average position (rank) in shopping carousels over time. Lower position is better (1 = first). If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/shopping/positioning/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from getBrandTopics or user message."
},
"granularity": {
"type": "string",
"enum": [
"day",
"week"
],
"description": "Time granularity: 'day' or 'week' (optional, default: 'day')."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Positioning (GET /api/shopping/positioning/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get price competitiveness analytics over time (average price, etc.) for products in shopping carousels. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/shopping/pricing/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from getBrandTopics or user message."
},
"granularity": {
"type": "string",
"enum": [
"day",
"week"
],
"description": "Time granularity: 'day' or 'week' (optional, default: 'day')."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Pricing (GET /api/shopping/pricing/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get paginated list of products from shopping results with search and sort. Use page_size up to 100. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/shopping/product-list/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from getBrandTopics or user message."
},
"brand_category": {
"type": "string",
"enum": [
"target_brand",
"competitor",
"all"
],
"description": "Filter by brand category (optional, default: 'all')."
},
"page": {
"type": "number",
"description": "Page number (optional, default: 1)."
},
"page_size": {
"type": "number",
"description": "Items per page (optional, default: 20, max: 100)."
},
"search": {
"type": "string",
"description": "Search in product_title, product_link, matched_brand, or retailer (optional)."
},
"retailer": {
"type": "string",
"description": "Filter by retailer name contains (optional)."
},
"sort_by": {
"type": "string",
"enum": [
"appearance_count",
"avg_position",
"avg_rating",
"total_reviews",
"product_title",
"brand_category",
"matched_brand",
"retailer"
],
"description": "Sort field (optional, default: 'appearance_count')."
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Sort order (optional, default: 'desc')."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Product list (GET /api/shopping/product-list/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get paginated list of product rows (one per response/product) from shopping results. Use page_size up to 100. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/shopping/products/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from getBrandTopics or user message."
},
"brand_category": {
"type": "string",
"enum": [
"target_brand",
"competitor",
"all"
],
"description": "Filter by brand category (optional, default: 'all')."
},
"page": {
"type": "number",
"description": "Page number (optional, default: 1)."
},
"page_size": {
"type": "number",
"description": "Items per page (optional, default: 20, max: 100)."
},
"sort_by": {
"type": "string",
"enum": [
"date",
"position",
"rating",
"reviews",
"product_title"
],
"description": "Sort field (optional, default: 'date')."
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Sort order (optional, default: 'desc')."
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get average rating and review count over time for products in shopping carousels. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/shopping/reputation/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from getBrandTopics or user message."
},
"granularity": {
"type": "string",
"enum": [
"day",
"week"
],
"description": "Time granularity: 'day' or 'week' (optional, default: 'day')."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Reputation (GET /api/shopping/reputation/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get share of shelf by brand (target and competitors) over time. Share of shelf is the percentage of products in shopping carousels per brand. Use for share-of-shelf trends and competitor comparison. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/shopping/share-of-shelf/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from getBrandTopics or user message."
},
"granularity": {
"type": "string",
"enum": [
"day",
"week"
],
"description": "Time granularity: 'day' or 'week' (optional, default: 'day')."
},
"top_brands": {
"type": "number",
"description": "Max number of brands before aggregating into 'Others' (optional, default: 10, max: 50)."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Share of shelf (GET /api/shopping/share-of-shelf/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get summary card metrics for the Product Tracker (shopping) dashboard. Returns share of shelf, average position, average rating, total products, total responses with shopping data, visibility_shopping_pct (% visibility), and responses_with_brand_product (count of responses with brand), with period-over-period change. Use when users ask about shopping metrics, product visibility in AI carousels, or share of shelf. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/shopping/summary/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from getBrandTopics or user message."
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (optional, e.g. chatgpt or googleaimode). Defaults to chatgpt."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Shopping summary KPI row."
},
"description": "GET /api/shopping/summary/"
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get top products by frequency of recommendation in shopping carousels. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/shopping/top-products/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from getBrandTopics or user message."
},
"brand_category": {
"type": "string",
"enum": [
"target_brand",
"competitor",
"all"
],
"description": "Filter by brand category (optional, default: 'target_brand')."
},
"limit": {
"type": "number",
"description": "Number of top products to return (optional, default: 10)."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Top products (GET /api/shopping/top-products/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get top retailers for the brand's products (share of offers by retailer). If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/shopping/top-retailers/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from getBrandTopics or user message."
},
"limit": {
"type": "number",
"description": "Number of top retailers to return (optional, default: 10)."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Top retailers (GET /api/shopping/top-retailers/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Call BEFORE writing any slide for a PowerPoint export. Returns the complete SlideDeckSpec contract: field_catalog (every field with type, maxLength, enum, counts), data_collection_workflow (per-slide budget-first fetch rules), construction_recipes (step-by-step chart/metrics/table/ranking rules), and full enums. Plan each slide's layout and data budget before MCP data calls — do not over-fetch then slice. Optional sections filter the payload: field_catalog, enums, construction_recipes, data_collection, field_limits, layout_selection, layout_templates, example, or all (default).
{
"type": "object",
"properties": {
"sections": {
"oneOf": [
{
"type": "array",
"items": {
"type": "string",
"enum": [
"field_catalog",
"enums",
"construction_recipes",
"data_collection",
"field_limits",
"layout_selection",
"layout_templates",
"example",
"all"
]
}
},
{
"type": "string",
"enum": [
"field_catalog",
"enums",
"construction_recipes",
"data_collection",
"field_limits",
"layout_selection",
"layout_templates",
"example",
"all"
]
}
],
"description": "Subset of guide sections; omit for full payload."
}
}
}{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false,
"required": [
"success",
"data"
],
"description": "Static product documentation payload."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get source of citations breakdown by media type showing where citations come from (Earned Media, Competition, Social Media, Owned Media). Citations are URLs/sources that LLMs reference when mentioning your brand. This shows the distribution of citation sources, helping understand which types of media drive your brand's AI visibility. Supports filtering by funnel (awareness, consideration, conversion), platform, model, and topic. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/citations-media-type/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days ending today (language-agnostic). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from the user's message or from previous tool results (e.g., from getBrandTopics)."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage"
},
"platform": {
"type": "string",
"description": "Filter by AI platform (e.g. 'chatgpt', 'gemini', 'googleaioverview')"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g. 'gpt-5', 'gemini-2.5-flash'). Model names vary by platform"
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter). Use getPromptPersonas to list valid ids for the brand."
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies LLM/platform market-share weighting."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Citation media-type breakdown (GET /api/citations-media-type/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get top domains by AI platform ranked by EIVA (Estimated Incremental Visible Answers). Use this when users ask which domains or sources are associated with the strongest estimated visibility lift opportunity per platform, or ask for citation opportunity insights. Interpretation is observational: cited vs not-cited prompt-group comparison, not causal proof. Near term, impact is expected mostly on citation-using prompts; over time, effects may extend more broadly as citation behavior diffuses. Each row includes sample_quality_band (French UI: « Qualité échantillon »): how statistically supported the lift/EIVA estimate is from cited vs not-cited response counts—not site or content quality. For a full explanation use getKPIDefinitions (common_metrics.sample_quality_band). Supports optional filtering by topic_id, platform, and price_availability; pagination (page, page_size), legacy limit alias for page_size, tuning with shrinkage_k, and optional sorting via sort_by/sort_order (including whitepress_price). Each row includes platform_breakdown (per-platform cited/not_cited counts and visibility rates). Same payload as GET /api/insights/top-domains-by-platform/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand context)."
},
"topic_id": {
"type": "string",
"description": "Optional topic UUID filter."
},
"platform": {
"type": "string",
"description": "Optional AI platform filter (e.g. chatgpt, gemini, perplexity)."
},
"page": {
"type": "integer",
"description": "Optional page number (default 1, min 1)."
},
"page_size": {
"type": "integer",
"description": "Optional page size (default 20, min 1, max 50 for this tool)."
},
"limit": {
"type": "integer",
"description": "Optional legacy alias for page_size when page_size is omitted (min 1, max 50)."
},
"shrinkage_k": {
"type": "integer",
"description": "Optional shrinkage constant (default 100, min 1, max 10000). Higher is more conservative."
},
"sort_by": {
"type": "string",
"description": "Optional sort field: domain, cited_response_count, not_cited_response_count, visibility_rate_when_cited, raw_visibility_lift, estimated_incremental_visible_answers, whitepress_price."
},
"sort_order": {
"type": "string",
"description": "Optional sort order: asc or desc."
},
"price_availability": {
"type": "string",
"description": "Optional price filter: all (default), with, without."
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get simplified list of topics for a brand in Brand Monitor format (id + text only). Returns only regular topics (excludes evergreen). Different from getBrandTopics which returns more detailed information from the ViewSet. Same payload as GET /api/topic/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Topic id and label."
},
"description": "Brand topics list."
}
},
"additionalProperties": false,
"required": [
"success",
"data"
]
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get the Branded vs Unbranded split (Bain-style cohorts) for the period. Returns three slices: overall counts per cohort, per-intent split, and per-product_category split. Use to answer 'how often does the LLM introduce brands vs how often do users name them' or to find intents where the AI is the dominant brand-introducer. Same payload as GET /api/v1/topics/cohort-breakdown/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional)"
},
"vertical_id": {
"type": "string",
"description": "The vertical id (e.g. 'luxury'). Required."
},
"start_date": {
"type": "string",
"description": "Start date YYYY-MM-DD (optional)"
},
"end_date": {
"type": "string",
"description": "End date YYYY-MM-DD (optional)"
}
},
"required": [
"vertical_id"
]
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Topics cohort breakdown (GET /api/v1/topics/cohort-breakdown/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get the number of distinct topic labels in the panel for a vertical and topic_type (intent or product_category). Use when users ask 'how many topics' or 'how many intents/categories' are active. Same payload as GET /api/v1/topics/count/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"vertical_id": {
"type": "string",
"description": "The vertical id (e.g. 'luxury'). Required."
},
"start_date": {
"type": "string",
"description": "Start date YYYY-MM-DD (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date YYYY-MM-DD (optional, defaults to today)"
},
"topic_type": {
"type": "string",
"enum": [
"intent",
"product_category"
],
"description": "Which taxonomy axis to count over."
}
},
"required": [
"vertical_id",
"topic_type"
]
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Topics count KPI."
},
"description": "GET /api/v1/topics/count/"
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get the intent x product_category co-occurrence matrix for the selected period. Use to answer 'what intents apply to which products?' or to build a heatmap. Returns one row per (intent, product_category) pair with message_count and cell_share. Same payload as GET /api/v1/topics/cross/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional)"
},
"vertical_id": {
"type": "string",
"description": "The vertical id (e.g. 'luxury'). Required."
},
"start_date": {
"type": "string",
"description": "Start date YYYY-MM-DD (optional)"
},
"end_date": {
"type": "string",
"description": "End date YYYY-MM-DD (optional)"
}
},
"required": [
"vertical_id"
]
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Topics cross analysis (GET /api/v1/topics/cross/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get the share of panel activity per topic_label in a vertical, sorted by volume. Use to answer 'what intents / product categories are most common?' or to build a distribution chart. Returns: topic_label, message_count, unique_users, topic_share. Same payload as GET /api/v1/topics/distribution/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional)"
},
"vertical_id": {
"type": "string",
"description": "The vertical id (e.g. 'luxury'). Required."
},
"start_date": {
"type": "string",
"description": "Start date YYYY-MM-DD (optional)"
},
"end_date": {
"type": "string",
"description": "End date YYYY-MM-DD (optional)"
},
"topic_type": {
"type": "string",
"enum": [
"intent",
"product_category"
],
"description": "Which taxonomy axis."
},
"page": {
"type": "number",
"description": "Page number (default 1)."
},
"page_size": {
"type": "number",
"description": "Items per page (default 20, max 100)."
},
"sort_by": {
"type": "string",
"description": "Sort field(s), comma-separated. Allowed: topic_label, message_count, unique_users, topic_share. Default: message_count."
},
"order": {
"type": "string",
"description": "Sort order(s), comma-separated. 'asc' or 'desc'. Default: desc."
}
},
"required": [
"vertical_id",
"topic_type"
]
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Topics distribution (GET /api/v1/topics/distribution/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get a time series of topic shares across the selected period. Use to chart how intent or product_category mix evolves over time. Returns: date, topic_label, message_count, topic_share. Configurable granularity (day, week, month). Same payload as GET /api/v1/topics/over-time/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional)"
},
"vertical_id": {
"type": "string",
"description": "The vertical id (e.g. 'luxury'). Required."
},
"start_date": {
"type": "string",
"description": "Start date YYYY-MM-DD (optional)"
},
"end_date": {
"type": "string",
"description": "End date YYYY-MM-DD (optional)"
},
"topic_type": {
"type": "string",
"enum": [
"intent",
"product_category"
],
"description": "Which taxonomy axis."
},
"granularity": {
"type": "string",
"enum": [
"day",
"week",
"month"
],
"description": "Time bucket size (default 'day')."
}
},
"required": [
"vertical_id",
"topic_type"
]
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Topics over time (GET /api/v1/topics/over-time/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get company users (paginated). Mirrors GET /api/users/company/. Use search to match email, username, or name. Superusers may pass company_id; others are scoped to their home company.
{
"type": "object",
"properties": {
"page_size": {
"type": "number",
"description": "Number of users to return per page"
},
"page": {
"type": "number",
"description": "Page number for pagination"
},
"search": {
"type": "string",
"description": "Substring match on email, username, first_name, or last_name"
},
"company_id": {
"type": "string",
"description": "Company scope (required for superusers listing another account)"
},
"brand_id": {
"type": "string",
"description": "Filter to users assigned to this brand"
},
"role": {
"type": "string",
"description": "Filter by effective role bucket",
"enum": [
"superuser",
"admin",
"company_admin",
"brand_owner",
"user",
"editor",
"viewer",
"monitor_only",
"no_brand_access"
]
},
"sort_by": {
"type": "string",
"enum": [
"username",
"is_active",
"last_login"
]
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
]
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get visibility, share of voice, mentions, and response counts grouped by one dimension (platform, funnel, topic, or model). V1: exactly one dimension is supported — arrays are rejected. Ratios are 0-1, not percentages. Default date range: last 7 days. Supports calculation_mode classic (default) or weighted (panel market-share weights). Same payload as GET /api/visibility-breakdown/. Success: paginated list of breakdown rows (visibility, share_of_voice, mentions, rank, key). Response always includes weightMetadata with calculationMode and unit='ratio_0_1'. In weighted mode weightMetadata also includes weightCoverage and platformsWithoutWeight. weightCoverage is a ratio between 0 and 1 when coverage can be computed (1.0 = all measured platforms have a weight, 0-1 = partial coverage). weightCoverage may be null when coverage is not computed or not applicable for the current aggregation (e.g. market-share data unavailable for the period). platformsWithoutWeight lists measured platforms excluded from weighted normalization because no weight was available. Note: platformsWithoutWeight=[] does not imply weightCoverage=1.0 when weightCoverage is null. sort_by: visibility (default), share_of_voice, mentions, mentions_avg, responses_count, responses_with_mentions, rank, key. order: desc (default) or asc. Pagination: page and page_size (max 200). Slide decks: use group_by=topic for 'Top N topics' rankings (one row per topic via label). Do NOT use getPrompts + topicName for topic leaderboards — multiple prompts share a topic. For prompt-level rankings use getPrompts or getPromptPerformanceBreakdown instead. Filters: brand_id, lookback_days, start_date, end_date, group_by, topic_id, funnel, platform, model, calculation_mode. Error: {success:false,error:string}.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand UUID"
},
"start_date": {
"type": "string",
"description": "YYYY-MM-DD"
},
"end_date": {
"type": "string",
"description": "YYYY-MM-DD"
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days ending today (language-agnostic). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"group_by": {
"type": "string",
"enum": [
"platform",
"funnel",
"topic",
"model"
],
"description": "Single dimension to group by (required)"
},
"topic_id": {
"type": "string"
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
]
},
"platform": {
"type": "string"
},
"model": {
"type": "string"
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies LLM/platform market-share weighting."
},
"page": {
"type": "number"
},
"page_size": {
"type": "number"
},
"sort_by": {
"type": "string",
"enum": [
"visibility",
"share_of_voice",
"mentions",
"mentions_avg",
"responses_count",
"responses_with_mentions",
"rank",
"key"
]
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
]
}
},
"required": [
"group_by"
]
}{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"additionalProperties": true,
"description": "Visibility breakdown (calculationMode, data rows, pagination, optional weightMetadata). GET /api/visibility-breakdown/."
}
},
"additionalProperties": true,
"required": [
"success",
"data"
]
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get a Meikai-native playbook for improving AI visibility. Use this when users ask 'how do I improve my visibility', 'how can I increase mentions in AI answers', 'how do I improve citations', 'how do I beat competitors in AI results', 'why is my brand not visible', or any question about what to do next to improve brand presence in LLM responses. Returns a practical diagnose-prioritize-implement-measure framework, maps actions to Meikai metrics and tools, and gives focus-specific guidance for visibility, citations, share of voice, technical foundation, owned content, earned media, and shopping visibility. Also includes sharp scenario playbooks for low visibility, competitor citation gaps, mentions without citations, and shopping visibility issues.
{
"type": "object",
"properties": {
"focus_area": {
"type": "string",
"enum": [
"visibility",
"citations",
"share_of_voice",
"owned_content",
"earned_media",
"technical_foundation",
"shopping",
"all"
],
"description": "Which improvement angle to emphasize. 'visibility' focuses on mentions and response presence, 'citations' on source inclusion, 'share_of_voice' on competitive standing, 'owned_content' on onsite content actions, 'earned_media' on offsite authority building, 'technical_foundation' on crawlability and structure, 'shopping' on Product Tracker/product visibility, 'all' for a full playbook (default)."
},
"time_horizon": {
"type": "string",
"enum": [
"quick_wins",
"30_day_plan",
"90_day_plan"
],
"description": "How far ahead to plan. 'quick_wins' focuses on immediate fixes, '30_day_plan' on the next month, '90_day_plan' on strategic improvements. Defaults to '30_day_plan'."
},
"include_measurement_plan": {
"type": "boolean",
"description": "Whether to include a section mapping actions to Meikai metrics and tools. Defaults to true."
},
"scenario": {
"type": "string",
"enum": [
"auto",
"low_visibility",
"competitors_cited_more",
"mentions_without_citations",
"shopping_visibility_low",
"all"
],
"description": "Optional scenario-specific playbook. 'low_visibility' for weak mention presence, 'competitors_cited_more' when rivals are cited more often, 'mentions_without_citations' when mentions exist but citations are weak, 'shopping_visibility_low' for Product Tracker / shopping issues, 'all' for all scenarios, 'auto' (default) returns all core scenarios."
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false,
"required": [
"success",
"data"
],
"description": "Static product documentation payload."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Brand Monitor visibility card: share of analyzed responses that mention the target brand. Same payload as GET /api/visibility-card/. Success: JSON array (usually one row). value = responses_with_mentions / total_responses; previous_value; pct_change; responses_with_mentions; total_responses. Filters: brand_id, lookback_days (preferred for relative periods; overrides dates), start_date, end_date (API-required unless MCP context fills them), topic_id, funnel, platform (maps to ai_platform), model, calculation_mode. Error: {success:false,error:string}.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand UUID. Optional when MCP context provides the current brand."
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Required by the API unless MCP context supplies start_date or resolves date_range_preset."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Required by the API unless MCP context supplies end_date or resolves date_range_preset."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days ending today (language-agnostic). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic UUID (comma-separated UUIDs allowed)."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage."
},
"platform": {
"type": "string",
"description": "Filter by AI platform (maps to query param ai_platform), e.g. chatgpt, gemini, googleaioverview."
},
"model": {
"type": "string",
"description": "Filter by AI model name (platform-specific)."
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter). Use getPromptPersonas to list valid ids for the brand."
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies LLM/platform market-share weighting."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": [
"number",
"null"
],
"description": "Metric value for the current period."
},
"previous_value": {
"type": [
"number",
"null"
],
"description": "Metric value for the previous period of equal length."
},
"pct_change": {
"type": [
"number",
"null"
],
"description": "Relative change vs previous_value (decimal, e.g. 0.1 = +10%)."
},
"responses_with_mentions": {
"type": [
"number",
"null"
],
"description": "Responses mentioning the target brand (weighted)."
},
"total_responses": {
"type": [
"number",
"null"
],
"description": "Total responses analyzed (weighted)."
}
},
"additionalProperties": false,
"description": "Visibility card row: value = responses_with_mentions / total_responses."
},
"description": "Visibility card rows (GET /api/visibility-card/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get visibility metrics for a brand within a date range. Returns visibility data (percentage of LLM responses mentioning the brand) and trends with period-over-period comparison. Visibility = responses_with_mentions / total_responses. This is a comprehensive metric showing how visible your brand is in AI responses. Supports filtering by funnel (awareness, consideration, conversion), platform, model, and topic. If brand_id, start_date, end_date, or topic_id are not provided, uses defaults from UI context (current brand, last 7 days, and current topic if available). Same payload as GET /api/visibility-card/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days ending today (language-agnostic). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Optional, defaults to current topic from UI context if available."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage"
},
"platform": {
"type": "string",
"description": "Filter by AI platform (e.g. 'chatgpt', 'gemini', 'googleaioverview')"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g. 'gpt-5', 'gemini-2.5-flash'). Model names vary by platform"
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter). Use getPromptPersonas to list valid ids for the brand."
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies LLM/platform market-share weighting."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": [
"number",
"null"
],
"description": "Metric value for the current period."
},
"previous_value": {
"type": [
"number",
"null"
],
"description": "Metric value for the previous period of equal length."
},
"pct_change": {
"type": [
"number",
"null"
],
"description": "Relative change vs previous_value (decimal, e.g. 0.1 = +10%)."
},
"responses_with_mentions": {
"type": [
"number",
"null"
],
"description": "Responses mentioning the target brand (weighted)."
},
"total_responses": {
"type": [
"number",
"null"
],
"description": "Total responses analyzed (weighted)."
}
},
"additionalProperties": false,
"description": "Visibility card row: value = responses_with_mentions / total_responses."
},
"description": "Visibility card rows (GET /api/visibility-card/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Get visibility ranking data showing how your brand ranks compared to competitors. Returns a ranked list of brands ordered by how often they're mentioned in LLM responses, with your brand's position highlighted. Visibility rank shows competitive positioning - lower rank numbers mean more mentions. IMPORTANT: use each row's `rank` value as-is (do not subtract 1 or recompute excluding the target brand). Supports filtering by funnel (awareness, consideration, conversion), platform, model, and topic. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Same payload as GET /api/visibility-rank/.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to today)"
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days ending today (language-agnostic). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from the user's message or from previous tool results (e.g., from getBrandTopics)."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage"
},
"platform": {
"type": "string",
"description": "Filter by AI platform (e.g. 'chatgpt', 'gemini', 'googleaioverview')"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g. 'gpt-5', 'gemini-2.5-flash'). Model names vary by platform"
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter). Use getPromptPersonas to list valid ids for the brand."
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies LLM/platform market-share weighting."
}
},
"required": []
}{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Visibility rank rows (GET /api/visibility-rank/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Invite one user through POST /api/users/invite/ with preview/apply confirmation.
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"preview",
"apply"
]
},
"confirmation_token": {
"type": "string"
},
"confirmation_phrase": {
"type": "string",
"enum": [
"CONFIRM_MANAGEMENT_CHANGE"
]
},
"user": {
"type": "object"
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "User invitation preview or apply result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Generate a PowerPoint or PDF file from a SlideDeckSpec. ONLY call after validateSlideDeckSpec returned valid:true. Pass normalizedSpec unchanged. Returns pptxUrl or pdfUrl (signed GCS download, ~1 hour) and warnings. Prefer ≤20 slides and ≤4 charts for reliable generation. User-facing failures should only be infra (502), never spec validation. Same payload as POST /api/decks/render/.
{
"type": "object",
"properties": {
"spec": {
"type": "object",
"description": "normalizedSpec from validateSlideDeckSpec.",
"additionalProperties": true
},
"downloadFilename": {
"type": "string",
"description": "Optional download filename (e.g. hennessy-brand-monitor-2026-05-01_2026-05-26.pptx). Overrides spec.title for the file name only."
},
"format": {
"type": "string",
"enum": [
"pptx",
"pdf"
],
"description": "Output format. Default pptx."
}
},
"required": [
"spec"
]
}{
"oneOf": [
{
"type": "object",
"properties": {
"pptxUrl": {
"type": "string"
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": true,
"required": [
"pptxUrl",
"warnings"
],
"description": "Rendered PPTX download URL and non-fatal warnings."
},
{
"type": "object",
"properties": {
"pdfUrl": {
"type": "string"
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": true,
"required": [
"pdfUrl",
"warnings"
],
"description": "Rendered PDF download URL and non-fatal warnings."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Safely update a brand's AI guidelines using a two-step flow. First call with mode='preview' to validate and receive a confirmation_token. Then call with mode='apply', confirmation_token, and confirmation_phrase='CONFIRM_AI_GUIDELINES_UPDATE' to persist the change. Requires brand_settings permission.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand UUID (optional if present in context)."
},
"proposed_ai_guidelines": {
"type": "string",
"description": "Proposed brand ai_guidelines content. Use empty string to clear."
},
"mode": {
"type": "string",
"enum": [
"preview",
"apply"
],
"description": "preview validates and returns confirmation_token; apply persists only when confirmation requirements are met."
},
"confirmation_token": {
"type": "string",
"description": "Token returned by preview; required for apply mode."
},
"confirmation_phrase": {
"type": "string",
"description": "Must be exactly CONFIRM_AI_GUIDELINES_UPDATE in apply mode."
}
},
"required": [
"proposed_ai_guidelines"
]
}{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"additionalProperties": true,
"description": "Updated brand AI guidelines."
}
},
"additionalProperties": false,
"required": [
"success",
"data"
]
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Set one or more brand statuses through POST /api/brands/bulk-status/ with preview/apply confirmation.
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"preview",
"apply"
]
},
"confirmation_token": {
"type": "string"
},
"confirmation_phrase": {
"type": "string",
"enum": [
"CONFIRM_MANAGEMENT_CHANGE"
]
},
"brand_ids": {
"type": "array",
"maxItems": 100
},
"status": {
"type": "string"
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Brand status update preview or apply result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Replace a user's home-company brand access through POST /api/users/brand-access/ with preview/apply confirmation. Each assignment needs brand_id and role (OWNER | EDITOR | VIEWER | MONITOR_ONLY). UI label Brand Owner = role OWNER.
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"preview",
"apply"
]
},
"confirmation_token": {
"type": "string"
},
"confirmation_phrase": {
"type": "string",
"enum": [
"CONFIRM_MANAGEMENT_CHANGE"
]
},
"user_id": {
"type": "string"
},
"assignments": {
"type": "array",
"maxItems": 100,
"items": {
"type": "object",
"properties": {
"brand_id": {
"type": "string"
},
"role": {
"type": "string",
"enum": [
"OWNER",
"EDITOR",
"VIEWER",
"MONITOR_ONLY"
],
"description": "Brand Owner in the UI is OWNER, not BRAND_OWNER."
}
},
"required": [
"brand_id",
"role"
]
}
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "User brand access preview or apply result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Activate or deactivate up to 100 users through POST /api/users/bulk-status/ with preview/apply confirmation. Pass user_ids and/or emails; when using emails as a superuser, include company_id.
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"preview",
"apply"
]
},
"confirmation_token": {
"type": "string"
},
"confirmation_phrase": {
"type": "string",
"enum": [
"CONFIRM_MANAGEMENT_CHANGE"
]
},
"user_ids": {
"type": "array",
"maxItems": 100
},
"emails": {
"type": "array",
"maxItems": 100
},
"company_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive"
]
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "User status update preview or apply result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Start an async export job for Brand Monitor. Supports export_type: citations, prompt_list, prompts, brand_visibility. Use getAsyncExportJobStatus to poll and getAsyncExportJobDownload to retrieve download URL. Same payload as POST /api/citations/export/async/ (or prompt-list, prompts, brand-visibility async export).
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand UUID (optional if context brand is available)."
},
"export_type": {
"type": "string",
"enum": [
"citations",
"prompt_list",
"prompts",
"brand_visibility"
],
"description": "Async export type to create."
},
"format": {
"type": "string",
"enum": [
"csv",
"xlsx",
"pdf"
],
"description": "Requested export format. Use pdf for brand_visibility."
},
"start_date": {
"type": "string",
"description": "Start date YYYY-MM-DD (optional for citations/prompt_list/brand_visibility)."
},
"end_date": {
"type": "string",
"description": "End date YYYY-MM-DD (optional for citations/prompt_list/brand_visibility)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Optional inclusive lookback window in days ending today. When set, overrides start_date/end_date."
},
"topic_id": {
"type": "string",
"description": "Optional topic UUID or comma-separated UUIDs for prompt_list/brand_visibility."
},
"platform": {
"type": "string",
"description": "Optional platform filter for prompt_list/brand_visibility."
},
"model": {
"type": "string",
"description": "Optional model filter for prompt_list/brand_visibility."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Optional funnel filter for brand_visibility."
},
"media_type": {
"type": "string",
"description": "Optional citations media type filter."
},
"is_mentioning_brand": {
"type": "string",
"enum": [
"true",
"false",
"unknown"
],
"description": "Optional citations filter by brand mention state."
},
"favorite_competitor_mentioned_not_brand": {
"type": "string",
"enum": [
"true",
"false",
"unknown"
],
"description": "Optional citations filter for competitor-only mentions."
},
"sort_by": {
"type": "string",
"description": "Optional citations sort field."
},
"search": {
"type": "string",
"description": "Optional search filter for citations/prompt_list."
},
"persona_id": {
"type": "string",
"description": "Optional Prompt Studio persona UUID for citations/prompt_list exports."
},
"order_by": {
"type": "string",
"description": "Optional prompts sort field (default id)."
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Optional sort order for prompts."
},
"send_email": {
"type": "boolean",
"description": "Whether to send completion email. Defaults to true for chat-triggered exports unless explicitly set to false."
},
"email": {
"type": "string",
"description": "Email destination when send_email=true."
}
},
"required": [
"export_type"
]
}{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Async export job created (HTTP 202 payload)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Patch brand management settings through PATCH /api/brands/{id}/ with preview/apply confirmation. The settings object accepts tracking_level ('brand' or 'product') to mark whether the tracked subject is a whole brand or a single product, which steers competitor auto-discovery.
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"preview",
"apply"
]
},
"confirmation_token": {
"type": "string"
},
"confirmation_phrase": {
"type": "string",
"enum": [
"CONFIRM_MANAGEMENT_CHANGE"
]
},
"brand_id": {
"type": "string"
},
"settings": {
"type": "object"
}
},
"required": []
}{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Brand settings update preview or apply result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Validate bulk brand import via POST /api/brands/import/validate/ without persisting.
{
"type": "object",
"properties": {
"company_id": {
"type": "string"
},
"auto_purchase_plan_license": {
"type": "boolean"
},
"brands": {
"type": "array",
"maxItems": 100
}
},
"required": [
"brands"
]
}{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Bulk brand creation validation result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Validate bulk competitor import via POST /api/competitors-list/import/validate/ without persisting.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string"
},
"competitors": {
"type": "array",
"maxItems": 100
}
},
"required": [
"brand_id",
"competitors"
]
}{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Bulk competitor creation validation result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Validate bulk user invites via POST /api/users/invite/bulk-validate/ without persisting.
{
"type": "object",
"properties": {
"users": {
"type": "array",
"maxItems": 100
}
},
"required": [
"users"
]
}{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Bulk user invitation validation result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Validate brand create payload via POST /api/brands/validate/ without persisting.
{
"type": "object",
"properties": {
"brand": {
"type": "object"
}
},
"required": [
"brand"
]
}{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Brand creation validation result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Validate competitor create payload via POST /api/competitors-list/validate/ without persisting.
{
"type": "object",
"properties": {
"competitor": {
"type": "object"
}
},
"required": [
"competitor"
]
}{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Competitor creation validation result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Validate user invite payload via POST /api/users/invite/validate/ without persisting.
{
"type": "object",
"properties": {
"user": {
"type": "object"
}
},
"required": [
"user"
]
}{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "User invitation validation result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Validate bulk brand status change via POST /api/brands/bulk-status/validate/ without persisting.
{
"type": "object",
"properties": {
"brand_ids": {
"type": "array",
"maxItems": 100
},
"status": {
"type": "string"
}
},
"required": [
"brand_ids",
"status"
]
}{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Brand status validation result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Validate brand access replacement via POST /api/users/brand-access/validate/ without persisting.
{
"type": "object",
"properties": {
"user_id": {
"type": "string"
},
"assignments": {
"type": "array",
"maxItems": 100
}
},
"required": [
"user_id",
"assignments"
]
}{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "User brand access validation result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Validate bulk user status change via POST /api/users/bulk-status/validate/ without persisting.
{
"type": "object",
"properties": {
"user_ids": {
"type": "array",
"maxItems": 100
},
"emails": {
"type": "array",
"maxItems": 100
},
"company_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"status"
]
}{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "User status validation result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Confirmation step before renderSlideDeck. Expected outcome: valid:true with normalizedSpec. Call after building the full spec using getSlideDeckSpecGuide (data_collection_workflow + field_catalog). If valid:false, re-read the guide, fix internally, re-validate once — never expose validation details to the user.
{
"type": "object",
"properties": {
"spec": {
"type": "object",
"description": "Complete SlideDeckSpec (title, optional theme, slides[]).",
"additionalProperties": true
}
},
"required": [
"spec"
]
}{
"oneOf": [
{
"type": "object",
"properties": {
"valid": {
"type": "boolean",
"const": true
},
"normalizedSpec": {
"type": "object",
"additionalProperties": true,
"description": "Validated SlideDeckSpec."
}
},
"additionalProperties": true,
"required": [
"valid",
"normalizedSpec"
],
"description": "Successful validation with normalized spec."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}Validate brand settings patch via POST /api/brands/{id}/validate/ without persisting.
{
"type": "object",
"properties": {
"brand_id": {
"type": "string"
},
"settings": {
"type": "object"
}
},
"required": [
"brand_id",
"settings"
]
}{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Brand settings validation result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
]
}