Getting Started - MentionLab

Overview

Use the MentionLab REST API to manage projects, queries, entities and tags, and to pull every analytics surface the app shows. This page covers what you need before your first request.

The REST API is currently in beta and is subject to breaking changes.

Base URL

https://api.mentionlab.io

Versioning

Routes come in two shapes:

Shape	Meaning
`/api/…`	The original, unversioned routes
`/api/v1/…`	Version 1 — the consolidated replacements

Newer endpoints ship only under /api/v1. Where a v1 route replaces an older one, the old route keeps working but is deprecated: it responds with

Deprecation: true
Link: </api/v1/…>; rel="successor-version"

and is hidden from the API reference. No sunset dates are published today, but new integrations should prefer /api/v1 wherever it exists.

If a path you’re using is missing from the reference, check your response headers — a Link header names its replacement.

Requests and responses

All requests and responses use JSON.

Content-Type: application/json
Accept: application/json

Many list endpoints are POST rather than GET, because filters and sorting are sent in the body. Check the reference for each endpoint’s verb.

Pagination

Offset-based, via page and limit. Both are query-string parameters, even on a POST:

Parameter	Default	Notes
`page`	`1`	Minimum 1
`limit`	`50`	Minimum 1; each endpoint has its own maximum

curl -X POST "https://api.mentionlab.io/api/queries/list?page=1&limit=50" \
  -H "x-api-key: ml_live_abc123xyz789..." \
  -H "x-project-id: fedcba98-7654-3210-fedc-ba9876543210" \
  -H "Content-Type: application/json" \
  -d '{}'

Do not put page or limit in the body. The body rejects unknown properties, so they return 400.

Responses wrap results:

{
  "results": [ ... ],
  "page": {
    "totalRecords": 250,
    "limit": 50,
    "currentPage": 1,
    "totalPages": 5,
    "nextPage": 2
  }
}

nextPage is omitted on the last page, prevPage on the first.

Sorting

Sorting goes in the body, not the query string:

{ "sort": [{ "field": "name", "direction": "ASC" }] }

Each endpoint allows a specific set of fields. Sending anything else returns a 400 listing the permitted fields.

Filtering

Filters are named properties on the request body. Note that most filters are scope filters — they narrow the underlying dataset, so aggregates and denominators change with them.

Errors

A validation error returns one entry per offending property:

{
  "statusCode": 400,
  "message": [
    {
      "property": "page",
      "constraints": { "whitelistValidation": "property page should not exist" }
    }
  ],
  "error": "Bad Request"
}

Code	Meaning
`400`	The body, query or path parameters are malformed or out of range
`401`	Missing or invalid authentication credentials
`403`	The key lacks the required permission, or access to that organisation/project
`409`	The action collides with a recent or in-flight run. See below
`503`	The query exceeded the database statement timeout. Narrow the date range or filters and retry

Unknown properties in a request body are rejected, not ignored. A typo’d field name returns 400 rather than being silently dropped.

409 in detail

Launching a job returns 409 with "code": "RECENT_JOB_EXISTS" when the same project already launched one in the last 10 minutes, along with lastTriggeredAt and windowMinutes. Resend with "force": true to override it. Topic extraction returns 409 while one of its runs is still in flight.

Endpoint groups

The reference is generated from the OpenAPI spec and organized into these groups:

Group	Description
Projects	List, get, update and delete projects; locales, models and last execution date
Organisations	List your organisations
Queries	Manage queries and their counts
Entities	CRUD for entities, aliases, merge and unmerge
Entity Groups	Groups and divisions, and entity assignment
Tags	Create, update, delete and link/unlink query tags
Execution Tags	Manage tags applied to AI responses
Jobs	Trigger executions and track job status
Job Executions	Detail for a single run
Reference	Provider/model country restrictions and the supported-locales allowlist
Source Categories	The source-type taxonomy
Source Topics	Topic extraction runs and content-gap analysis
Shopping Products	Per-appearance shopping product rows
Theme Analysis	Theme clustering status and runs
Analytics – Visibility	Mention rate, share of voice, timeseries
Analytics – Models	Per-model mention rate, SoV, citations, position trends
Analytics – Queries	Per-query stats, sources, entities, raw results
Analytics – Tags	Per-tag stats, trends, entity and source breakdowns
Analytics – Sources	Domain reach, top domains, URL-level drill-downs, breakdowns
Analytics – Sentiment	Sentiment overview, timeseries, per-entity breakdown
Analytics – Shopping	Shopping overview, products, brands, merchants
Analytics – Social	YouTube videos, channels, countries and KPIs
Analytics – Fan Outs	Follow-up question stats and per-query breakdowns
Analytics – Ads	Sponsored-ad brands, formats and advertisers
Analytics – Custom Metrics	Metrics provisioned for your organization
Analytics – Themes	Theme and perception analytics
Tag Groups	Create, update and delete tag groups, and file tags into them

API keys themselves are managed in the app, not through the API — those endpoints are deliberately absent from the reference.

Next steps

Authentication

Get your API key and set required headers.

Context Headers

Learn about organization and project headers.

Rate Limits

Understand API limits and retry behavior.

MCP Server

Reach the same data from Claude, Cursor and other AI tools.

​Overview

​Base URL

​Versioning

​Requests and responses

​Pagination

​Sorting

​Filtering

​Errors

​409 in detail

​Endpoint groups

​Next steps

Authentication

Context Headers

Rate Limits

MCP Server

Overview

Base URL

Versioning

Requests and responses

Pagination

Sorting

Filtering

Errors

409 in detail

Endpoint groups

Next steps