Skip to main content

​
Overview

The MentionLab API uses API key authentication and context headers to secure and scope your API requests. Every request must include proper authentication credentials.

​
Authentication Components

MentionLab requires three components for most API requests:

API Key

Your API key that authenticates who you are.

Organisation ID

Identifies which organisation context to use.

Project ID

Specifies which project to operate on (when required).

​
Required Headers

HeaderTypeRequiredDescription
x-api-keystringAlwaysYour API key. Format: ml_live_...
x-organisation-idstringAlwaysUUID of your organisation
x-project-idstringConditionalUUID of the project (required for project-scoped operations)

​
Example Request

Here’s a complete example showing all required headers: 
curl -X GET "https://api.mentionlab.io/api/queries/list" \
  -H "x-api-key: ml_live_abc123xyz789..." \
  -H "x-organisation-id: 01234567-89ab-cdef-0123-456789abcdef" \
  -H "x-project-id: fedcba98-7654-3210-fedc-ba9876543210" \
  -H "Content-Type: application/json"

​
When Each Header is Required

​
Organisation-Level Endpoints

These endpoints only require x-api-key and x-organisation-id:
  • All /api/projects/* endpoints
  • …

​
Project-Level Endpoints

These endpoints require all three headers (x-api-key, x-organisation-id and x-project-id):
  • All /api/queries/* endpoints
  • All /api/tags/* endpoints
  • All /api/result-analysis/* endpoints
  • All /api/cached-jobs/* endpoints
  • …

​
Security Best Practices

Never hardcode your API key in source code. Use environment variables or a secrets manager:
export MENTIONLAB_API_KEY="your-api-key"
export MENTIONLAB_ORG_ID="your-org-id"
export MENTIONLAB_PROJECT_ID="your-project-id"
All API requests must use HTTPS. The API will reject any HTTP requests.
If you believe your API key has been compromised, immediately delete it from your dashboard and update all your integrations.

​
Next Steps

Get Your API Key

Learn how to obtain and manage your API keys.

Header Reference

Detailed documentation for all authentication headers.