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

> [!WARNING]
>
> The REST API v2 is in active development. We add endpoints one at a time, so this reference does
> not cover the full API yet.

## What "alpha" means for v2

"Alpha" describes the **coverage** of v2, not the stability of its endpoints.

* **Every endpoint in this reference is final.** Its path, parameters and response shape do not
  change in a breaking way. You can build production integrations on it.
* **The set of endpoints is incomplete.** We move the API to v2 endpoint by endpoint, not in one
  release. Each endpoint appears in this reference on the day it ships.
* **An endpoint that is not in this reference is not in v2 yet.** Use its v1 equivalent until it
  arrives.

## Use v1 and v2 together

v1 stays available. One integration can call v1 and v2 endpoints side by side, with the same API
key. See the [v1 reference](https://docs.mentionlab.io/rest-api/getting-started.md) for the endpoints that v2 does not cover
yet.

## Base URL

```
https://api.mentionlab.io/api/v2
```

## Authentication

v2 uses the same `x-api-key` header as v1. See [Authentication](https://docs.mentionlab.io/rest-api/authentication.md).

## Paths

A v2 path names the organization or project it acts on:

```
/api/v2/organisations/{organisationId}/...
/api/v2/projects/{projectId}/...
```

> [!NOTE]
>
> Continue to send the `x-organisation-id` or `x-project-id` header. Its value must match the ID in
> the path. See [Context Headers](https://docs.mentionlab.io/rest-api/headers.md).

## Requests and responses

All requests and responses use JSON.

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

### Two kinds of list

| Kind | Verb | Where `page`, `limit`, `sort` and filters go |
| - | - | - |
| Resource lists | `GET` | Query string |
| Analytics lists | `POST` | Body. The filter set is too large for a query string |

### Pagination

Offset-based, via `page` and `limit`:

| Parameter | Default | Notes |
| - | - | - |
| `page` | `1` | Minimum 1 |
| `limit` | `25` | Minimum 1, maximum 100 on every list |

On a `GET` list, send them in the query string:

```bash theme={null}
curl "https://api.mentionlab.io/api/v2/projects/{projectId}/{resource}?page=2&limit=50" \
  -H "x-api-key: ml_live_abc123xyz789..." \
  -H "x-project-id: {projectId}"
```

On a `POST` analytics list, send them in the body:

```json theme={null}
{ "page": 2, "limit": 50 }
```

> [!WARNING]
>
> This is the opposite of v1, where `page` and `limit` are always in the query string. A v2
> `POST` list reads them from the body only.

Responses wrap results:

```json theme={null}
{
  "results": [ ... ],
  "page": {
    "totalRecords": 250,
    "limit": 50,
    "currentPage": 2,
    "totalPages": 5,
    "nextPage": 3,
    "prevPage": 1
  }
}
```

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

### Sorting

A sort is a `field:asc` or `field:desc` pair, as a string.

On a `GET` list, send one or more comma-separated pairs in the query string:

```
?sort=name:asc,updatedAt:desc
```

On a `POST` analytics list, send one pair in the body:

```json theme={null}
{ "sort": "mr:desc" }
```

Each endpoint allows a specific set of fields. The reference lists them. Any other field returns
400\.

> [!NOTE]
>
> The v1 form, an array of `{ "field": ..., "direction": ... }` objects, returns 400 on v2.

### Filtering

Filters are named parameters. On a `GET` list, a list filter takes either form:

```
?languages=en,fr
?languages=en&languages=fr
```

On a `POST` analytics list, filters are properties of the body.

### Errors

Errors use the same format and status codes as v1. See [Errors](https://docs.mentionlab.io/rest-api/getting-started.md#errors).

> [!WARNING]
>
> Unknown properties are **rejected**, not ignored. A typo'd field name returns 400 rather than
> being silently dropped.

## Changes from v1

| | v1 | v2 |
| - | - | - |
| Tenant | Header only | Path, plus a matching header |
| List verb | Often `POST` | `GET` for resource lists, `POST` for analytics lists |
| `page` and `limit` | Always in the query string | Query string on `GET`, body on `POST` |
| Default `limit` | `50` | `25`, maximum 100 |
| `sort` | Array of `{ field, direction }` in the body | `field:asc` string |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.