> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mentionlab.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Learn the basics of the MentionLab REST API

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

<Warning>
  The REST API is currently in beta and is subject to breaking changes.
</Warning>

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

<Tip>
  If a path you're using is missing from the reference, check your response headers — a `Link`
  header names its replacement.
</Tip>

## Requests and responses

All requests and responses use JSON.

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

<Note>
  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.
</Note>

### 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:

```json theme={null}
{
  "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:

```json theme={null}
{ "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

```json theme={null}
{
  "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                      |

<Warning>
  Unknown properties in a request body are **rejected**, not ignored. A typo'd field name returns
  400 rather than being silently dropped.
</Warning>

## 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                                                 |

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

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/rest-api/authentication">
    Get your API key and set required headers.
  </Card>

  <Card title="Context Headers" icon="list" href="/rest-api/headers">
    Learn about organization and project headers.
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/rest-api/authentication#rate-limits">
    Understand API limits and retry behavior.
  </Card>

  <Card title="MCP Server" icon="plug" href="/rest-api/mcp-server">
    Reach the same data from Claude, Cursor and other AI tools.
  </Card>
</CardGroup>