Getting Started

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, sorting and paging are sent in the body. Check the reference for each endpoint’s verb.

Pagination

Offset-based, via page and limit:

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

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

{
  "statusCode": 400,
  "message": "Validation failed",
  "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`	Conflict — a run of the same kind is already in progress

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

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 – Themes	Theme and perception analytics

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

Projects

Queries

Entities

Organisations

Jobs

Tags

Tag Groups

Execution Tags

Theme Analysis

Entity Groups

Source Categories

Job Executions

Analytics - Visibility

Analytics - Tags

Analytics - Sources

Analytics - Shopping

Analytics - Sentiment

Analytics - Queries

Analytics - Models

Analytics - Themes

Analytics - Fan Outs

Analytics - Social

Source Topics

Reference

Shopping Products

Overview

Base URL

Versioning

Requests and responses

Sorting

Filtering

Errors

Endpoint groups

Next steps

Authentication

Context Headers

Rate Limits

MCP Server

​Overview

​Base URL

​Versioning

​Requests and responses

​Pagination

​Sorting

​Filtering

​Errors

​Endpoint groups

​Next steps

Authentication

Context Headers

Rate Limits

MCP Server

Overview

Base URL

Versioning

Requests and responses

Pagination

Sorting

Filtering

Errors

Endpoint groups

Next steps