Public API v1

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

1. Sign in to MencionAI.
2. Open Settings → API Keys.
3. 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.

Step 2 — Make your first request

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)
• TypeScript client: SDK guide
• Partners embedding visibility: Partners guide

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.

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.