Getting Started

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

Paths

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

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

Continue to send the x-organisation-id or x-project-id header. Its value must match the ID in the path. See Context Headers.

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:

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:

{ "page": 2, "limit": 50 }

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:

{
  "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:

{ "sort": "mr:desc" }

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

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.

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

Overview

Provider Restrictions

Jobs

Recurrence settings

What “alpha” means for v2

Use v1 and v2 together

Base URL

Authentication

Paths

Requests and responses

Two kinds of list

Sorting

Filtering

Errors

Changes from v1

​What “alpha” means for v2

​Use v1 and v2 together

​Base URL

​Authentication

​Paths

​Requests and responses

​Two kinds of list

​Pagination

​Sorting

​Filtering

​Errors

​Changes from v1

What “alpha” means for v2

Use v1 and v2 together

Base URL

Authentication

Paths

Requests and responses

Two kinds of list

Pagination

Sorting

Filtering

Errors

Changes from v1