API Documentation

BrandCrux REST API & MCP

Everything you need to wire AI visibility into your code. REST from any language, MCP for AI agents.

REST APIhttps://apis.brandcrux.ai

MCPhttps://apis.brandcrux.ai/mcp

Authentication

All API requests require an API key passed in the X-API-Key header.

Getting your API key

Sign in to your BrandCrux dashboard
Go to Settings → API Keys
Click "+ Create Key", name it, and select a business
Copy the key. It is shown only once.

Example request

curl https://apis.brandcrux.ai/api/v1/visibility-score \
  -H "X-API-Key: bcx_abc123..."

Use Cases

📡

Monitor brand visibility across AI engines

Track how ChatGPT, Claude, Gemini, Perplexity, and Google AIO mention, recommend, and cite your business.

📊

Automate weekly AI visibility reports

Schedule scans, pull data via API, and build custom dashboards in your existing BI tools.

🔍

Track competitor mentions in AI

Monitor when AI engines recommend competitors instead of you and understand their positioning.

🔗

Feed AI visibility into your SEO stack

Integrate BrandCrux data with your existing SEO tools, CRMs, or analytics platforms via API.

🔔

Build custom AI visibility alerts

Trigger webhooks or custom notifications when your visibility score changes across any engine.

REST API Endpoints

POST/api/v1/competitorsAdd a competitor to your business profile▼

GET/api/v1/source-recommendationsEarn-coverage publisher targets, gap-aware▼

GET/api/v1/visibility-scoreLatest visibility score with confidence block▼

GET/api/v1/businessGet business info▼

GET/api/v1/queriesList tracked prompts▼

POST/api/v1/queriesAdd a prompt▼

GET/api/v1/scansList scans▼

GET/api/v1/scans/{scan_id}Get scan details + per-cell results with confidence▼

GET/api/v1/scans/{scan_id}/attemptsPer-pull attempt log for diagnostics▼

POST/api/v1/scansRun a new scan▼

GET/api/v1/competitorsList competitors▼

GET/api/v1/analyticsFull analytics dashboard▼

GET/api/v1/scan-diffCompare two scans▼

GET/api/v1/trendsVisibility trends over time▼

GET/api/v1/content/briefsList content briefs▼

GET/api/v1/content/briefs/{brief_id}Get content brief▼

POST/api/v1/content/advisoryGenerate content briefs (5 credits)▼

GET/api/v1/content/artifactsList content artifacts▼

GET/api/v1/content/artifacts/{artifact_id}Get content artifact▼

POST/api/v1/content/generateGenerate content (5-30 credits)▼

GET/api/v1/content/artifacts/{id}/exportExport content▼

GET/api/v1/content/artifacts/{id}/versionsContent version history▼

GET/api/v1/analytics/externalSynced GSC/GA4 data▼

GET/api/v1/analytics/correlationAI x Organic correlation▼

POST/api/v1/geo-auditStart GEO audit (1 credit/page)▼

GET/api/v1/geo-audit/{audit_id}Get audit status & results▼

GET/api/v1/geo-audit/{audit_id}/pagesPage-level audit results▼

GET/api/v1/geo-auditsList audit history▼

GET/api/v1/geo-audit/compareCompare vs competitors▼

GET/api/v1/prompt-notificationsList notification configs▼

PUT/api/v1/prompt-notifications/{query_id}Set notification▼

DELETE/api/v1/prompt-notifications/{query_id}Remove notification▼

MCP Server

Connect BrandCrux to AI agents via the Model Context Protocol. The MCP server exposes all API functionality as tools that Claude, Cursor, Windsurf, and other MCP-compatible AI assistants can call directly.

Quick Connect

Add this endpoint to any MCP client that supports remote servers over Streamable HTTP. Every request must carry your own API key in a header: Authorization: Bearer bcx_... or X-API-Key: bcx_.... Requests without a key are refused.

https://apis.brandcrux.ai/mcp

Option 1: Bearer token

Add to your client's MCP config file (for example .cursor/mcp.json in Cursor, or the project .mcp.json).

{
  "mcpServers": {
    "brandcrux": {
      "type": "http",
      "url": "https://apis.brandcrux.ai/mcp",
      "headers": {
        "Authorization": "Bearer bcx_your_key_here"
      }
    }
  }
}

Option 2: X-API-Key header

Clients that set custom headers but not bearer tokens can send the same key as X-API-Key, just like the REST API.

"headers": {
  "X-API-Key": "bcx_your_key_here"
}

Replace bcx_your_key_here with your API key from Settings → API Keys. Keep the key out of the URL.

Connect your AI assistant

1Generate an API key in Settings → API Keys (Growth or Scale plan)

2Open your assistant's MCP server settings and add a remote server that uses Streamable HTTP

3Paste the JSON config above (replace bcx_your_key_here with your actual key)

4Reload the assistant. BrandCrux tools appear in its tools list, each marked as read only or as an action that changes data.

Available MCP Tools

get_visibility_score

Get the latest AI visibility score and per-source breakdown.

get_business

Get business profile: name, domain, categories, products, competitors.

list_queries

List all tracked search prompts with categories and active status.

add_query

Add a new prompt to track across AI sources.

list_scans

List recent visibility scans with status and summary scores.

get_scan_results

Get detailed results for a scan: per-prompt scores, AI answers, citations.

run_scan

Run a new visibility scan. Returns results when complete (20-60s).

list_competitors

List competitors detected in AI answers, ranked by mentions.

get_analytics

Full analytics: citations, entity leaderboard, cross-source matrix, sentiment.

get_trends

Visibility metrics trended over time across recent scans.

get_scan_diff

Compare two scans: improvements, declines, new/lost mentions.

list_content_briefs

List AI-generated content recommendations.

get_content_brief

Get content brief details: target queries, keywords, outline.

run_content_advisory

Generate content briefs from scan results and analytics (5 credits).

list_content_artifacts

List generated content: drafts, published, archived.

get_content_artifact

Get content artifact with full body and SEO metadata.

generate_content

Generate content from a brief using Claude, GPT-4, or Gemini.

export_content

Export content in markdown, HTML, or JSON.

list_artifact_versions

Version history for a content artifact.

get_external_analytics

Get synced Google Search Console or Analytics data.

get_visibility_correlation

Correlate AI visibility with organic search metrics.

run_geo_audit

Start a GEO audit: crawl and score pages for AI citation readiness.

get_geo_audit_status

Get audit status and results. Poll until completed.

get_geo_audit_pages

Page-level results with scores, issues, and recommendations.

list_geo_audits

List all GEO audit history with scores.

compare_geo_audits

Compare your audit scores against competitors.

list_prompt_notifications

List prompt notification configs.

set_prompt_notification

Set alerts for citation, mention, or lost mention changes.

delete_prompt_notification

Remove a prompt notification.

Rate Limits

Requests exceeding the limit receive a 429 Too Many Requests response with a Retry-After header.

Free

requests / min

Starter

requests / min

Growth

requests / min

Scale

120

requests / min

Error Codes

All errors return a JSON body with a detail field describing the issue.

CodeStatusDescription

200OKRequest succeeded. Response body contains the requested data.

400Bad RequestInvalid parameters or malformed request body. Check the detail field.

401UnauthorizedMissing or invalid API key. Ensure X-API-Key header is set.

403ForbiddenValid key but insufficient permissions. May require a higher plan.

404Not FoundThe requested resource does not exist. Check the ID or path.

429Too Many RequestsRate limit exceeded. Retry after the Retry-After header duration.

500Internal Server ErrorSomething went wrong. Retry shortly or contact support@brandcrux.ai.