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

# Context Headers

> Understanding x-organisation-id and x-project-id headers

## Overview

In addition to API key authentication, MentionLab uses context headers to scope API requests to specific organisations and projects. These headers ensure you're working with the correct data and have appropriate access.

## Required Headers

### x-project-id

<ParamField header="x-project-id" type="string">
  The unique identifier (UUID) of the project. Required for project-scoped operations.
</ParamField>

The project ID determines:

* Which project's queries, tags, and results you access
* Project-specific settings and configurations

**Format:** UUID (e.g., `fedcba98-7654-3210-fedc-ba9876543210`)

### Finding Your Project ID

**From the Dashboard:**

1. Go to [app.mentionlab.io](https://app.mentionlab.io)
2. Open your project and navigate to **Project Settings** → **General**
3. Your Project ID is displayed on this page

**From the API:** List your projects to retrieve their IDs

<CodeGroup>
  ```bash List Projects theme={null}
  curl -X GET "https://api.mentionlab.io/api/v1/projects" \
    -H "x-api-key: ml_live_abc123xyz789..."
  ```

  ```json Response theme={null}
  [
    {
      "id": "fedcba98-7654-3210-fedc-ba9876543210",
      "name": "My Brand",
      "slug": "my-brand",
      ...
    }
  ]
  ```
</CodeGroup>

## Organisation context

<ParamField header="x-organisation-id" type="string">
  The unique identifier (UUID) of the organisation. **Do not send it** — it is filled in
  automatically from your API key.
</ParamField>

Organisation-scoped endpoints do need organisation context, but your API key already carries it: the
API sets the header from the key before any permission check runs. Any value you send is overwritten,
so the header can never be used to reach a different organisation. To work with a second
organisation, create a key in that organisation.

## Endpoints that need no project header

A handful of endpoints are not project-scoped:

| Endpoint                                      | Notes                                  |
| --------------------------------------------- | -------------------------------------- |
| `GET /api/v1/projects`                        | Your projects — the natural first call |
| `GET /api/organisations`                      | Your organisations                     |
| `GET /api/v1/reference/provider-restrictions` | Public; no authentication required     |
| `GET /api/v1/reference/locales`               | Public; no authentication required     |

## Missing or mismatched headers

Header problems return **403**, not 400:

| Situation                                   | Message                                             |
| ------------------------------------------- | --------------------------------------------------- |
| No `x-project-id` on a project-scoped route | `Missing project id context`                        |
| Project ID is not a UUID                    | `Invalid Project ID`                                |
| Project ID is unknown                       | `Project not found`                                 |
| Project belongs to another organisation     | `Project does not belong to specified organisation` |

## Best Practices

<AccordionGroup>
  <Accordion title="Use environment variables" icon="terminal">
    Store IDs in environment variables for easy management across environments:

    ```bash theme={null}
    # .env
    MENTIONLAB_PROJECT_ID=fedcba98-7654-3210-fedc-ba9876543210
    ```
  </Accordion>

  <Accordion title="Create a centralized API client" icon="code">
    Build a wrapper that automatically includes the required headers to avoid repetition and errors.
  </Accordion>

  <Accordion title="Handle multiple projects" icon="folder-tree">
    If you work with multiple projects, pass the project ID as a parameter rather than hardcoding it.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="REST API Getting Started" icon="code" href="/rest-api/getting-started">
    Review base URL, JSON requirements, and rate limits.
  </Card>

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