Getting started with the API

Use the MencionAI API to read brand visibility data and trigger scans from your own apps, dashboards, or automations.

Before you begin

You need a MencionAI account with at least one workspace (brand/domain) set up.

Step 1 — Create an API key

Sign in to MencionAI.
Open Settings → API Keys.
Click Create API key and copy the value immediately. It is shown only once.

Keys look like mak_live_… (production) or mak_test_… (sandbox).

Store the key in a secret manager or environment variable — never commit it to git or expose it in client-side code.

For AI referral traffic on your customer domain, use a separate browser site key from Settings → AI Traffic (prefix msk_…). See the AI traffic install guide.

Step 2 — Make your first request

v2 (recommended for new integrations):

curl -s \
  -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.mencionai.com/v2/organization

v1 (frozen, still supported):

curl -s \
  -H "Authorization: Bearer YOUR_API_KEY" \
  https://www.mencionai.com/api/v1/organization

Example response:

{
  "id": 1,
  "name": "Acme Inc",
  "plan": "Growth",
  "subscription_status": "active"
}

Step 3 — List workspaces and read visibility

# List workspaces
curl -s \
  -H "Authorization: Bearer YOUR_API_KEY" \
  https://www.mencionai.com/api/v1/workspaces

# Visibility summary for workspace 42
curl -s \
  -H "Authorization: Bearer YOUR_API_KEY" \
  https://www.mencionai.com/api/v1/workspaces/42/visibility/summary

What you can build

| Goal | Start here | |------|------------| | Internal BI dashboard | GET /workspaces/:id/visibility/summary | | Alert when a scan finishes | Webhooks + visibility.scan.completed | | Embedded chart in your product | Embed tokens → iframe | | Automated re-scans | POST /workspaces/:id/scans + poll GET /jobs/:id |

Next steps

Full endpoint reference on the API docs page (includes interactive OpenAPI explorer)
MCP server for Cursor / Claude Desktop: MCP guide
TypeScript client: SDK guide
Partners embedding visibility: Partners guide

MencionAI MCP

Use the MencionAI MCP server to read AI search visibility and enqueue scans from Cursor, Claude Desktop, or any MCP client.

The MCP server is a thin adapter over Public API v2. It uses your API key and the same scopes as the HTTP API. Tools never talk to the database directly.

Before you begin

Create an API key under Settings → API Keys (mak_live_… or mak_test_…). Settings also has copy-paste MCP install snippets.
Install Node.js 20+ (for local stdio).
Grant scopes that match what you need:
- organization:read + workspaces:read — list workspaces and read visibility
- jobs:read + workspaces:write (or the scan/write scopes your key UI offers) — enqueue / wait for scans
- visibility:answers:read — only if you need get_visibility_responses (answer excerpts)

Never pass the API key as a tool argument. Put it in the MCP process environment (stdio) or as Authorization: Bearer (hosted).

Local stdio (good for getting started)

pnpm add -g @mencionai/mcp
# or: npx -y @mencionai/mcp

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "mencionai": {
      "command": "npx",
      "args": ["-y", "@mencionai/mcp"],
      "env": {
        "MENCIONAI_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "mencionai": {
      "command": "npx",
      "args": ["-y", "@mencionai/mcp"],
      "env": {
        "MENCIONAI_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Optional: set MENCIONAI_API_BASE_URL to point at a non-production v2 base URL.

Hosted MCP (preferred for production agents)

Use the hosted Streamable HTTP endpoint when you want rate limits and product telemetry. Stdio from customer machines does not write usage events.

URL: https://mcp.mencionai.com/mcp

Example remote client config (replace the key; exact JSON shape depends on your MCP client):

{
  "mcpServers": {
    "mencionai": {
      "url": "https://mcp.mencionai.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Authenticate with Authorization: Bearer YOUR_API_KEY. Never pass the API key as a tool argument.

Preferred tool flow

For how-to / setup questions, call list_docs then get_doc (api, sdk, whitelabel, ars, mcp, llms) before inventing answers. Docs tools do not need an API key.

For visibility data, use this path unless the user asks for a raw slice:

list_workspaces
get_visibility_overview
explain_visibility_gaps / compare_competitors
wait_for_visibility_scan when a refresh is needed (uses plan quota)
get_visibility_series for trends

Do not call thin visibility tools (get_visibility_summary, get_visibility_mentions, get_visibility_competitors, get_visibility_coverage, get_visibility_citations) unless composed output is insufficient or the user asks for that slice. get_visibility_responses requires visibility:answers:read and fails closed without it.

Tools

| Tool | Purpose | |------|---------| | list_docs / get_doc | Public guides (API, SDK, whitelabel, ARS, MCP, llms.txt) | | get_visibility_overview | Start here — composed snapshot (summary + coverage + competitors + citations) | | compare_competitors | Rank rivals by mentions/citations vs brand | | explain_visibility_gaps | Prompts where competitors appear but the brand does not | | wait_for_visibility_scan | Enqueue + poll scan (default 60s, max 120s; consumes quota) | | get_visibility_series | Daily scores including ARS (7d | 30d | 90d) | | get_traffic_summary / get_traffic_series | AI referral visits from the site snippet (ChatGPT/Gemini/…) | | get_organization / list_workspaces / get_workspace | Org & workspace reads | | get_visibility_responses | Answer excerpts (requires visibility:answers:read) | | get_visibility_coverage / citations / summary / mentions / competitors | Power-user thin reads | | enqueue_visibility_scan / get_job | Manual scan + poll (prefer wait_for_visibility_scan) |

Example prompts

Share of voice: “Using MencionAI, open my workspace and summarize where we lose share versus the top three competitors on ChatGPT.”
Gaps: “Which tracked prompts mention a competitor but not our brand? List the rival hosts.”
Citations: “From the visibility overview, what domains cite us most often, and which top URLs are not our own site?”
Rescan: “Enqueue a visibility scan for my primary workspace, wait up to 60 seconds, then refresh the overview.”
Trends: “Show 30-day visibility series for my primary workspace and call out the latest score change.”

Troubleshooting

| Symptom | What to check | |---------|----------------| | 401 / unauthorized | API key missing, revoked, or wrong environment (mak_live_ vs mak_test_) | | Scope / forbidden errors | Key lacks workspaces:read (or scan write scopes) | | get_visibility_responses fails closed | Add visibility:answers:read when creating the key | | Scan slow or rejected | Plan quota; prefer wait_for_visibility_scan with a timeout ≤ 120s | | Agent asks for your API key | Misconfigured MCP — key belongs in env / Bearer header, never in tool args |

Next steps

API reference

The MencionAI REST API lets you access organization and workspace data, visibility metrics, scans, webhooks, and embed tokens.

Base URL: https://www.mencionai.com/api/v1

OpenAPI spec: Download YAML

All requests require authentication unless noted otherwise.

Authentication

Pass your API key in the Authorization header:

Authorization: Bearer mak_live_xxxxxxxx

| Key prefix | Use for | |------------|---------| | mak_live_ | Production data | | mak_test_ | Testing and development |

Create keys in the MencionAI dashboard under Settings → API Keys.

Scopes

When creating a key, it is granted a set of scopes. Each endpoint requires a specific scope:

| Scope | Allows | |-------|--------| | organization:read | Read organization info | | workspaces:read | List workspaces and visibility data | | workspaces:write | Enqueue visibility scans | | jobs:read | Check scan job status | | embed:create | Create short-lived embed tokens | | webhooks:manage | Register and manage webhook endpoints |

If a scope is missing, the API returns 403 with code MISSING_SCOPE.

Rate limits

Limits apply per organization and depend on your plan:

| Plan | Requests per minute | |------|---------------------| | Free | 30 | | Starter | 60 | | Growth | 300 | | Enterprise | 1,000 |

Every response includes:

X-RateLimit-Limit — your plan limit
X-RateLimit-Remaining — requests left in the current window

When you exceed the limit, the API returns 429 with a Retry-After header (seconds until you can retry).

Errors

Errors use a consistent JSON shape:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or revoked API key",
    "request_id": "req_abc123"
  }
}

Common codes:

| Code | HTTP | Meaning | |------|------|---------| | UNAUTHORIZED | 401 | Missing or invalid API key | | FORBIDDEN | 403 | Scope missing or feature not on your plan | | NOT_FOUND | 404 | Workspace or resource not found | | RATE_LIMIT_EXCEEDED | 429 | Too many requests | | IDEMPOTENCY_KEY_REQUIRED | 422 | POST scan without Idempotency-Key | | VALIDATION_ERROR | 422 | Invalid request body or path parameter |

Include request_id when contacting support.

Organization

`GET /organization`

Returns your organization name, plan, and subscription status.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://www.mencionai.com/api/v1/organization

Workspaces

A workspace represents one brand/domain you track in MencionAI.

`GET /workspaces`

List all workspaces in your organization.

{
  "workspaces": [
    {
      "id": 42,
      "domain": "acme.com",
      "brand_name": "Acme",
      "created_at": "2026-01-15T10:00:00.000Z"
    }
  ]
}

`GET /workspaces/:id`

Returns metadata for a single workspace.

Visibility

All visibility endpoints require workspaces:read.

`GET /workspaces/:id/visibility/summary`

High-level visibility metrics: mentions, citations, prompts tracked, providers, last sync time.

On Public API v2, also returns ars_score (AI Recommendation Score, 0–100) and ars_components (breakdown). Scores are not available on v1. See the ARS guide.

`GET /workspaces/:id/visibility/series`

Daily score series (7d | 30d | 90d). Points include legacy ai_score / visibility_score and ars_score (preferred headline trend).

`GET /workspaces/:id/visibility/mentions`

Mentions grouped by prompt/keyword.

`GET /workspaces/:id/visibility/competitors`

Competitor visibility stats (mentions and citations per host).

Scans

Trigger a new AI visibility scan for a workspace.

`POST /workspaces/:id/scans`

Requires workspaces:write and an Idempotency-Key header (unique per logical request). Reusing the same key with the same body returns the original response instead of enqueueing twice.

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: scan-2026-07-06-acme-001" \
  https://www.mencionai.com/api/v1/workspaces/42/scans

Response (202):

{
  "job_id": 901,
  "status": "pending"
}

`GET /jobs/:id`

Poll job status. Requires jobs:read.

{
  "id": 901,
  "type": "ai_scan",
  "status": "completed",
  "created_at": "2026-07-06T12:00:00.000Z"
}

Status values: pending, processing, completed, failed.

Typical flow: enqueue scan → poll every few seconds until completed → fetch updated visibility summary.

Webhooks

Receive HTTP callbacks when events happen in your organization. Available on Starter plans and above.

Register an endpoint

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/mencionai",
    "events": ["visibility.scan.completed"]
  }' \
  https://www.mencionai.com/api/v1/webhooks

The response includes a secret — save it immediately. You need it to verify signatures.

Event types

| Event | When it fires | |-------|----------------| | visibility.scan.enqueued | A scan was accepted | | visibility.scan.completed | A scan finished successfully | | report.generated | A report is ready |

Payload format

{
  "id": "evt_uuid",
  "type": "visibility.scan.completed",
  "created_at": "2026-07-06T12:05:00.000Z",
  "data": {
    "workspace_id": 42,
    "job_id": 901,
    "result_id": 555
  }
}

Verify signatures

Each delivery includes:

X-MencionAI-Signature: t=1710000000,v1=abc123...

Verify by computing HMAC-SHA256 over {timestamp}.{raw_body} using your endpoint secret, then compare to v1.

Manage endpoints

| Method | Path | Action | |--------|------|--------| | GET | /webhooks | List endpoints | | GET | /webhooks/:id | Get one endpoint | | PATCH | /webhooks/:id | Update URL or events | | DELETE | /webhooks/:id | Disable endpoint |

Embed tokens

Show MencionAI visibility inside your product via a secure iframe.

`POST /embed-tokens`

Requires embed:create.

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "workspace_id": 42, "ttl_sec": 3600 }' \
  https://www.mencionai.com/api/v1/embed-tokens

{
  "token": "met_...",
  "expires_in": 3600,
  "workspace_id": 42
}

Load in an iframe:

https://www.mencionai.com/embed/v1/workspaces/42/summary?token=met_...

Tokens are short-lived. Create a new one server-side when the previous expires — do not expose your API key in the browser.

See the Partners guide for embedding best practices.

Public API v1

Getting started with the API

Before you begin

Step 1 — Create an API key

Step 2 — Make your first request

Step 3 — List workspaces and read visibility

What you can build

Next steps

MencionAI MCP

Before you begin

Local stdio (good for getting started)

Hosted MCP (preferred for production agents)

Preferred tool flow

Tools

Example prompts

Troubleshooting

Next steps

API reference

Authentication

Scopes

Rate limits

Errors

Organization

GET /organization

Workspaces

GET /workspaces

GET /workspaces/:id

Visibility

GET /workspaces/:id/visibility/summary

GET /workspaces/:id/visibility/series

GET /workspaces/:id/visibility/mentions

GET /workspaces/:id/visibility/competitors

Scans

POST /workspaces/:id/scans

GET /jobs/:id

Webhooks

Register an endpoint

Event types

Payload format

Verify signatures

Manage endpoints

Embed tokens

POST /embed-tokens

`GET /organization`

`GET /workspaces`

`GET /workspaces/:id`

`GET /workspaces/:id/visibility/summary`

`GET /workspaces/:id/visibility/series`

`GET /workspaces/:id/visibility/mentions`

`GET /workspaces/:id/visibility/competitors`

`POST /workspaces/:id/scans`

`GET /jobs/:id`

`POST /embed-tokens`