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

Connection guides for Cursor, Claude, Codex, Antigravity, and n8n live on the MCP hub.

Short URLs for agents (they redirect here): docs.mencionai.com/mcp.

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).

Dashboard product reads (Public API v2)

These routes require workspaces:read. They expose the same non-sensitive Command Center product a logged-in user sees. They do not return site keys, API secrets, people, or billing internals. Answer snippets on prompt detail require visibility:answers:read (stripped to null without it).

Path	Returns
`GET /workspaces/:id/prompts`	Tracked questions
`GET /workspaces/:id/prompts/:promptId`	Prompt visibility, citations, latest answers
`GET /workspaces/:id/weekly-report`	Weekly summary, coverage, competitors
`GET /workspaces/:id/action-plan`	Monthly GEO checklist (read only)
`GET /workspaces/:id/ars`	ARS score, eight components, series
`GET /workspaces/:id/ai-sources`	Cited/consulted domains and gaps
`GET /workspaces/:id/brand-perception`	Brand vs competitor attributes
`GET /workspaces/:id/crawl-insights`	Crawler hit aggregates vs citations
`GET /workspaces/:id/settings`	Brand name, domain, competitor list

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