Authentication - MentionLab

Overview

All MentionLab REST API requests require an API key sent in the x-api-key header. Your API key is scoped to a single organization and can access all projects within that organization.

Project-scoped API keys are on the roadmap.

Get Your API Key

You can retrieve your API key from the dashboard:

Go to app.mentionlab.io and sign in to your account.

Open API Keys

Use the organization switcher in the top bar, choose Organization settings, then Developer settings → API Keys in the sidebar.

Create the key

Click Create API Key and set a Name, a Permission (Read only or Read & Write) and an optional Expiration Date — leave it empty for a key that never expires.

Copy and store securely

Copy your API key immediately. For security reasons, you will not be able to see it again.

Only organization Administrators can create or delete keys. Editors can see the list.

Permissions

Permission	What the key can do
Read only	Read organizations, projects and analytics
Read & Write	The above, plus create and update project data

Read & Write is not full access. It cannot delete projects, manage members, or change organization settings and billing — those actions return 403 regardless of the key.

Your API key is only shown once when generated. Store it securely in a password manager or environment variable. If you lose it, you will need to generate a new one.

API Key Format

MentionLab API keys use the following format:

ml_live_abc123xyz789def456...

API keys always start with ml_live_ for production keys.

Using Your API Key

Include your API key in the x-api-key header of every request:

x-api-key: ml_live_abc123xyz789def456...

Example

curl -X GET "https://api.mentionlab.io/api/v1/projects" \
  -H "x-api-key: ml_live_abc123xyz789..."

const apiKey = process.env.MENTIONLAB_API_KEY;

const response = await fetch('https://api.mentionlab.io/api/v1/projects', {
  headers: {
    'x-api-key': apiKey
  }
});

import os
import requests

api_key = os.environ['MENTIONLAB_API_KEY']

response = requests.get(
    'https://api.mentionlab.io/api/v1/projects',
    headers={
        'x-api-key': api_key
    }
)

GET /api/v1/projects needs no project header, so it’s the natural first call to verify a key and discover your project IDs.

Environment Variables

We recommend storing your API key in environment variables:

Unix/Linux/macOS
.env file

export MENTIONLAB_API_KEY="your-api-key-here"

# .env file (add to .gitignore!)
MENTIONLAB_API_KEY=your-api-key-here
MENTIONLAB_PROJECT_ID=your-default-project-id

Always add .env files to your .gitignore to prevent accidentally committing secrets to version control.

Required Headers

Header	Required	Description
`x-api-key`	Always	Your API key (format: `ml_live_...`)
`x-project-id`	For project endpoints	Project UUID for project-scoped operations

Example Request

Most list endpoints are POST, with filters and paging in the body:

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

Project Context

Project-specific endpoints require the x-project-id header so the API knows which project to operate on. You can store a default project ID in your environment if most requests target a single project.

A missing or invalid context header returns 403, not 400 — for example Missing project id context or Project does not belong to specified organisation.

Invalid keys

Situation	Response
No `x-api-key` header	`401 Missing API key header`
Unrecognised key	`401 Invalid API key`
Key past its expiration date	`401 API key has expired`
Key lacks the permission the route needs	`403` naming the missing permission
Endpoint not available to API keys	`403 API key authentication is not allowed for this endpoint`

Rate Limits

The MentionLab API implements rate limiting to ensure fair usage and maintain service stability for all users. Understanding these limits helps you design efficient integrations that avoid throttling.

Default Rate Limits

All accounts share the same default rate limits:

Metric	Limit
Requests per Second	10
Requests per Minute	300
Requests per Hour	10,000

If you have a custom agreement with MentionLab, your rate limits may differ from the defaults listed here. Please refer to your agreement documentation for your specific limits.

Rate Limit Headers

Every API response includes headers to help you track your usage:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the rate limit resets
`Retry-After`	Seconds to wait before retrying (only on 429 responses)

Handling Rate Limits

When you exceed the rate limit, the API returns a 429 Too Many Requests response:

{
  "statusCode": 429,
  "message": "Too many requests. Please retry after 30 seconds.",
  "error": "Too Many Requests"
}

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1701234567
Retry-After: 30

Error Codes

Code	Description	Action
`429`	Rate limit exceeded	Wait for `Retry-After` seconds and retry
`503`	Service temporarily unavailable	Wait 30 seconds and retry with backoff

​Overview

​Get Your API Key

​Permissions

​API Key Format

​Using Your API Key

​Example

​Environment Variables

​Required Headers

​Example Request

​Project Context

​Invalid keys

​Rate Limits

​Default Rate Limits

​Rate Limit Headers

​Handling Rate Limits

​Error Codes

​Next Steps

Context Headers

REST API Getting Started

Overview

Get Your API Key

Permissions

API Key Format

Using Your API Key

Example

Environment Variables

Required Headers

Example Request

Project Context

Invalid keys

Rate Limits

Default Rate Limits

Rate Limit Headers

Handling Rate Limits

Error Codes

Next Steps