REST API

The AnswerixAI REST API gives scripts and back-end services the same data the dashboard and the MCP server use. It lives under /api/mcp/*, returns JSON, and authenticates with an ans_ API key. It covers everything in the read-only Metrics API plus topics, prompts, search volumes, content opportunities, site audits and product visibility, and a few write actions.

What do you need before you call the REST API?#

To call the AnswerixAI REST API you need the base URL of the AnswerixAI app you sign in to and an ans_ API key sent as a bearer token. Requests are limited to 250 per 15 minutes per IP address, and every endpoint only sees brands of the key owner's organization.

• Base URL: the host of the AnswerixAI app you sign in to. Copy the MCP endpoint from Settings → API Keys and drop the trailing /api/mcp. The examples below use https://answerixai.com.
• Authentication: send Authorization: Bearer ans_YOUR_KEY on every request. See Authentication.
• Rate limit: 250 requests per 15 minutes per IP address.
• Scope: every endpoint only sees brands of the key owner's organization. Anything else returns 404.

curl "https://answerixai.com/api/mcp/brands" \
  -H "Authorization: Bearer ans_YOUR_KEY" \
  -H "Accept: application/json"

What conventions does the REST API follow?#

The AnswerixAI REST API uses the same date handling, shared filters and error format on every endpoint. Dates are YYYY-MM-DD in UTC, most endpoints require brand_id, and errors return {"error": "<message>"} with an HTTP status code.

How are dates handled?#

The AnswerixAI REST API reads date_from and date_to as UTC dates, and a bare date_to includes the whole of that day. Leave both out to use all tracked history.

• date_from and date_to accept YYYY-MM-DD dates in UTC. A full ISO 8601 timestamp also works.
• A bare date_to date is inclusive: date_to=2026-09-30 includes answers up to 23:59:59.999 UTC on September 30.
• Leave both out to use all tracked history.

Which filters are shared?#

Five filters work the same way on every AnswerixAI REST API endpoint that accepts them: brand_id (required), model, region, topic_id and limit. A missing brand_id returns 400, and a limit outside the endpoint's range is clamped to it.

Visibility, citation and trend numbers exclude ChatGPT Shopping answers; shopping data has its own endpoints.

What do errors look like?#

AnswerixAI REST API errors return {"error": "<message>"} with 400, 401, 402, 404, 429 or 500. The full table is in Authentication.

Which endpoints does the REST API have?#

The AnswerixAI REST API has 25 endpoints under /api/mcp/, grouped into account and brands, visibility, citations, topics and prompts, content opportunities, site audits, AI traffic and shopping. Most are GET reads; the write actions accept or dismiss topic suggestions, generate content briefs and drafts, change an opportunity's status and start a site audit.

Which endpoints return account and brand data?#

Two AnswerixAI REST API endpoints need no parameters: whoami tests your key, and brands lists the brand IDs you pass as brand_id everywhere else.

GET /api/mcp/whoami#

GET /api/mcp/whoami returns the user ID, email and organization ID that your API key resolves to, and takes no parameters.

{ "userId": "…", "email": "[email protected]", "organizationId": "…" }

GET /api/mcp/brands#

GET /api/mcp/brands returns a bare JSON array of your organization's brands, newest first, and takes no parameters.

[
  {
    "id": "5d1c2f0e-8a4b-4c3e-9f6a-2b7d1e0c9a88",
    "name": "Acme",
    "slug": "acme",
    "industry": "Software",
    "region": "US",
    "created_at": "2026-08-02T09:14:31+00:00"
  }
]

Which endpoints return visibility data?#

Four AnswerixAI REST API endpoints return visibility data for a brand: visibility-summary for headline totals, visibility-trend for daily or weekly buckets, competitor-comparison for share of voice, and prompt-performance for per-prompt results. Each one requires brand_id.

GET /api/mcp/visibility-summary#

GET /api/mcp/visibility-summary returns a brand's headline visibility totals and top competitors over a date range, and requires brand_id.

curl "https://answerixai.com/api/mcp/visibility-summary?brand_id=BRAND_ID&date_from=2026-09-01&date_to=2026-09-30" \
  -H "Authorization: Bearer ans_YOUR_KEY"

{
  "brand": { "id": "…", "name": "Acme" },
  "totals": {
    "resultCount": 840,
    "avgVisibility": 41.3,
    "totalMentions": 1210,
    "totalCitations": 305,
    "aiVisibilityScore": 38.6,
    "mentionAnswers": 452,
    "citationAnswers": 190,
    "positionFactor": 0.52
  },
  "topCompetitors": [
    { "name": "Globex", "mentions": 980, "avgVisibility": 22.4, "score": 33.1 }
  ]
}

GET /api/mcp/visibility-trend#

GET /api/mcp/visibility-trend returns a brand's visibility per UTC day or per ISO week, and requires brand_id. Set granularity to day (the default) or week.

{
  "granularity": "day",
  "buckets": [
    {
      "date": "2026-09-01",
      "result_count": 28,
      "avg_visibility_score": 42,
      "ai_visibility_score": 39.5,
      "total_mentions": 40,
      "total_citations": 9,
      "avg_competitor_score": 25
    }
  ]
}

• date is the UTC day, or for week the Monday that starts the ISO week.
• ai_visibility_score is the Visibility score for that day. It is null for weekly buckets.
• avg_visibility_score and avg_competitor_score are rounded averages of per-answer scores; avg_competitor_score is null when no competitor appeared.

GET /api/mcp/competitor-comparison#

GET /api/mcp/competitor-comparison returns your brand's visibility next to each tracked competitor's, plus share of voice overall and per platform, and requires brand_id.

{
  "brand": {
    "id": "…", "name": "Acme",
    "avg_visibility_score": 41, "ai_visibility_score": 38.6,
    "total_mentions": 1210, "total_citations": 305, "appearance_count": 840
  },
  "competitors": [
    {
      "competitor_id": "…", "name": "Globex",
      "avg_visibility_score": 30, "ai_visibility_score": 33.1,
      "total_mentions": 980, "total_citations": 120, "appearance_count": 610
    }
  ],
  "share_of_voice": {
    "overall_sov_pct": 55.3,
    "total_brand_mentions": 1210,
    "total_competitor_mentions": 980,
    "by_platform": [
      { "model_used": "…", "platform": "perplexity-web", "brand_mentions": 300, "competitor_mentions": 210, "sov_pct": 58.8 }
    ]
  }
}

Share of voice is your mentions ÷ (your mentions + competitor mentions), as a percentage with one decimal.

GET /api/mcp/prompt-performance#

GET /api/mcp/prompt-performance returns per-prompt visibility, mentions and citations for a brand, sorted by sort_by and capped by limit, and requires brand_id.

{
  "brand": { "id": "…", "name": "Acme" },
  "window": { "dateFrom": "2026-09-01", "dateTo": "2026-09-30" },
  "prompts": [
    {
      "prompt_id": "…",
      "prompt_text": "best project management tool for agencies",
      "topic_name": "Project management",
      "result_count": 30,
      "avg_visibility": 55,
      "total_mentions": 41,
      "total_citations": 12,
      "avg_competitor_score": 31
    }
  ]
}

Which endpoint returns citation data?#

The AnswerixAI REST API returns citation data from one endpoint, GET /api/mcp/citations, which lists the domains and URLs AI engines cite, classified into the same eight source types as the Citations page.

GET /api/mcp/citations#

GET /api/mcp/citations returns the domains and URLs AI engines cite in answers to a brand's prompts, with totals and a source type breakdown, and requires brand_id.

{
  "totals": {
    "domains": 212, "urls": 640, "citations": 1830,
    "results_with_citations": 700, "avg_citations_per_result": 2.2
  },
  "source_type_breakdown": [
    { "category": "editorial", "count": 80, "pct": 37.7 },
    { "category": "you", "count": 3, "pct": 1.4 }
  ],
  "top_domains": [
    {
      "domain": "example-review-site.com", "category": "review",
      "total_citations": 95, "results_citing": 60, "usage_pct": 7.1,
      "models": ["…"], "article_types": [{ "type": "…", "count": 40 }]
    }
  ],
  "top_urls": [
    {
      "url": "https://example-review-site.com/best-tools", "domain": "example-review-site.com",
      "category": "review", "title": "Best tools in 2026",
      "total_citations": 30, "results_citing": 25, "usage_pct": 3, "article_type": "…"
    }
  ]
}

• category is one of you, competitor, editorial, forum, social, review, institutional or other, matching the source types on the Citations page.
• source_type_breakdown counts each domain once and lists only categories with at least one domain.
• usage_pct is the share of answers that cite the domain or URL.
• article_types lists up to three detected article types for a domain.

Which endpoints work with topics and prompts?#

Six AnswerixAI REST API endpoints work with topics and prompts: list topics, list, accept or dismiss topic suggestions, list tracked prompts, and read prompt search volumes. Accepting and dismissing are POST calls on a suggestion ID; the others are GET calls that require brand_id.

GET /api/mcp/topics#

GET /api/mcp/topics returns all topics of a brand, oldest first, with each topic's prompt count, and requires brand_id.

[
  { "id": "…", "name": "Project management", "is_active": true, "prompt_count": 12, "created_at": "2026-08-02T09:20:00+00:00" }
]

GET /api/mcp/topic-suggestions#

GET /api/mcp/topic-suggestions returns a brand's pending AI topic suggestions, newest first, and requires brand_id. This endpoint lists suggestions that already exist; it doesn't generate new ones.

{
  "suggestions": [
    { "id": "…", "name": "Resource planning", "reason": "…", "generated_at": "2026-09-20T06:00:00+00:00" }
  ]
}

POST /api/mcp/topic-suggestions/{id}/accept#

POST /api/mcp/topic-suggestions/{id}/accept creates exactly one topic from a pending suggestion and marks the suggestion as added. It takes the suggestion ID in the path and no body.

{ "suggestion_id": "…", "topic_id": "…", "topic_name": "Resource planning" }

Calling it again for the same suggestion returns 404 {"error": "Suggestion not found, not pending, or already processed"} and never creates a second topic.

POST /api/mcp/topic-suggestions/{id}/dismiss#

POST /api/mcp/topic-suggestions/{id}/dismiss dismisses a pending suggestion so it doesn't come back in later batches. It takes the suggestion ID in the path and no body.

{ "id": "…", "status": "dismissed" }

A suggestion that isn't pending returns the same 404 as accept.

GET /api/mcp/prompts#

GET /api/mcp/prompts returns a brand's tracked prompts, newest first, and requires brand_id. You can narrow the list with topic_id and is_active.

[
  {
    "id": "…", "text": "best project management tool for agencies",
    "topic_id": "…", "topic_name": "Project management",
    "platforms": ["…"], "models": [], "regions": ["US"],
    "is_active": true, "created_at": "2026-08-02T09:22:00+00:00"
  }
]

GET /api/mcp/prompt-volumes#

GET /api/mcp/prompt-volumes returns search volume estimates for a brand's prompts from Built-in Search Intelligence, sorted by estimated AI volume, and requires brand_id.

Each row has prompt_id, prompt_text, intent, keywords, google_volumes, total_google_volume, est_ai_volume, ai_volume_multiplier, competition_index, competition and fetched_at. Prompts without a volume analysis aren't listed.

Which endpoints work with content opportunities?#

Content opportunities are the article ideas on the AnswerixAI Content page. Five REST API endpoints work with them: list opportunities, read one with its brief, generate a brief, generate a draft, and change an opportunity's status. Generating a brief or draft uses your monthly quota. See Content.

GET /api/mcp/content-opportunities#

GET /api/mcp/content-opportunities returns a brand's content opportunities, sorted by opportunity_score with the highest first, and requires brand_id. You can filter by status, impact and type.

[
  {
    "id": "…", "title": "Publish a comparison of agency PM tools",
    "description": "…", "type": "owned", "impact": "high",
    "opportunity_score": 82, "status": "new",
    "prompt_id": "…", "prompt_text": "best project management tool for agencies",
    "has_brief": false,
    "created_at": "2026-09-10T06:00:00+00:00", "updated_at": "2026-09-10T06:00:00+00:00"
  }
]

GET /api/mcp/content-opportunities/{id}#

GET /api/mcp/content-opportunities/{id} returns one content opportunity by its ID, with the same fields as the list plus source_data (the tracking signals behind the opportunity) and brief (the saved content brief, or null). Returns 404 {"error": "Content opportunity not found"} for unknown IDs. This is the way to read an existing brief without using quota.

POST /api/mcp/content-opportunities/{id}/brief#

POST /api/mcp/content-opportunities/{id}/brief generates a new content brief for the opportunity in the path and saves it. The call always generates a fresh brief, even if one exists, and each call uses one content brief from your monthly quota. When the quota is used up, it returns 402.

curl -X POST "https://answerixai.com/api/mcp/content-opportunities/OPPORTUNITY_ID/brief" \
  -H "Authorization: Bearer ans_YOUR_KEY"

{
  "id": "…",
  "brief": {
    "suggestedTitle": "…", "contentType": "…", "targetWordCount": 1800,
    "outline": [], "targetKeywords": [], "competitorInsights": "…", "callToAction": "…"
  },
  "generated_at": "2026-09-27T10:00:00+00:00",
  "regenerated": true
}

POST /api/mcp/content-opportunities/{id}/draft#

POST /api/mcp/content-opportunities/{id}/draft generates a full article draft from the opportunity's brief and saves it as the opportunity's content draft. The call always generates a fresh draft and uses one content draft from your monthly quota; at the limit it returns 402. Generate a brief first: without one, the call fails with the message "Generate a content brief before generating the full draft."

{
  "id": "…",
  "content": {
    "title": "…", "metaTitle": "…", "metaDescription": "…", "slug": "…",
    "contentHtml": "<h2>…</h2>", "faqs": [], "keyTakeaways": [], "structuredDataJsonLd": "…"
  },
  "generated_at": "2026-09-27T10:05:00+00:00",
  "regenerated": true
}

PATCH /api/mcp/content-opportunities/{id}/status#

PATCH /api/mcp/content-opportunities/{id}/status changes an opportunity's status. Send a JSON body with status set to new, sent, in_progress, done or dismissed. Any other value returns 400.

curl -X PATCH "https://answerixai.com/api/mcp/content-opportunities/OPPORTUNITY_ID/status" \
  -H "Authorization: Bearer ans_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "in_progress"}'

{ "id": "…", "status": "in_progress", "updated_at": "2026-09-27T10:10:00+00:00" }

Use this endpoint from your workflow tool to report progress on opportunities you received through the opportunity.sent webhook.

Which endpoints run and read site audits?#

Four AnswerixAI REST API endpoints handle site audits: list recent audits, start an audit of one page, check the monthly audit quota, and read one audit with its signals and recommendations. Starting an audit uses one site audit from your monthly quota. See Site audit for what an audit checks.

GET /api/mcp/site-audits#

GET /api/mcp/site-audits returns the 50 most recent site audits of a brand, newest first, and requires brand_id.

[
  { "id": "…", "url": "https://example.com/pricing", "status": "completed", "totalScore": 72.5, "signalsEvaluated": 40, "signalsTotal": 42, "createdAt": "2026-09-26T08:00:00+00:00" }
]

POST /api/mcp/site-audits#

POST /api/mcp/site-audits starts a site audit of one page. Send a JSON body with brand_id and url; both are required (400 otherwise). Each audit uses one site audit from your monthly quota; at the limit the call returns 402.

curl -X POST "https://answerixai.com/api/mcp/site-audits" \
  -H "Authorization: Bearer ans_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"brand_id": "BRAND_ID", "url": "https://example.com/pricing"}'

{ "id": "…", "brandId": "…", "url": "https://example.com/pricing", "status": "running" }

The audit runs in the background. Poll GET /api/mcp/site-audits/{id} until status is completed or failed.

GET /api/mcp/site-audits/quota#

GET /api/mcp/site-audits/quota returns your organization's site audit usage in the current monthly period as used, limit and remaining, and takes no parameters.

{ "used": 12, "limit": 100, "remaining": 88 }

A limit of -1 means unlimited.

GET /api/mcp/site-audits/{id}#

GET /api/mcp/site-audits/{id} returns one site audit in full by its ID: id, brandId, url, finalUrl, status, totalScore, categoryScores, signalsEvaluated, signalsTotal, recommendations, signals (each with key, category, status, score and evidence), error, createdAt and completedAt. Unknown IDs return 404 {"error": "Audit not found"}.

Which endpoint returns AI traffic data?#

The AnswerixAI REST API returns AI traffic from one endpoint, GET /api/mcp/ai-traffic, which reports the visits AI platforms refer to your website, as recorded by the tracking script.

GET /api/mcp/ai-traffic#

GET /api/mcp/ai-traffic returns a brand's AI-referred visits with platform, page and country breakdowns, and requires brand_id. See AI traffic analytics.

{
  "total_visits": 320,
  "platform_breakdown": [{ "platform": "…", "visits": 210 }],
  "top_pages": [{ "url": "/pricing", "visits": 44 }],
  "country_breakdown": [{ "country": "US", "visits": 150 }]
}

top_pages lists up to 10 page paths.

Which endpoints return shopping data?#

Two AnswerixAI REST API endpoints read the product cards collected when a brand has Shopping mode on: shopping-cards lists the cards, and product-visibility summarizes how often one product appears. See Shopping.

GET /api/mcp/shopping-cards#

GET /api/mcp/shopping-cards returns the product cards from AI shopping answers for a brand, newest first, with cursor pagination, and requires brand_id.

{
  "cards": [
    {
      "id": "…", "prompt_result_id": "…", "brand_id": "…", "position": 1,
      "product_title": "Acme Trail Shoe", "product_brand": "Acme",
      "price_amount": 129.99, "price_currency": "USD",
      "image_url": "https://…", "merchant_url": "https://…", "merchant_domain": "shop.example.com",
      "rating": 4.6, "review_count": 812, "raw": {},
      "matched_brand_id": "…", "matched_brand_role": "own",
      "platform": "chatgpt-shopping", "region": "US",
      "created_at": "2026-09-26T07:00:00+00:00"
    }
  ],
  "next_cursor": "eyJjcmVhdGVkX2F0Ijoi…"
}

Cards are newest first. next_cursor is null on the last page.

GET /api/mcp/product-visibility#

GET /api/mcp/product-visibility returns how often one product appears across shopping answers, by platform, region and date, and requires both brand_id and product_title.

Missing either parameter returns 400 {"error": "brand_id and product_title are required"}; a title with no cards returns 404 {"error": "Product not found"}.

{
  "product_title": "Acme Trail Shoe",
  "total_appearances": 18,
  "by_platform": [{ "platform": "chatgpt-shopping", "count": 18 }],
  "by_region": [{ "region": "US", "count": 18 }],
  "by_date": [{ "date": "2026-09-26", "count": 3 }],
  "latest_appearance": "2026-09-26T07:00:00+00:00",
  "average_rating": 4.6,
  "total_reviews": 14616,
  "merchant_domains": [{ "domain": "shop.example.com", "count": 12 }]
}