# Key context

Which key is making the request, what it can see and which limits apply to it right now.

Base URL: https://api.melioralab.io/v1. Pass the key in the `Authorization: Bearer mel_live_...` header.

Endpoints:

- `GET /v1/me`: Retrieve API key details

## The ApiContext object

Details of the key used for the request: organization, permissions, scope, limits and collection status.

| Field | Type | Description |
|---|---|---|
| `object` | string | Object type, always `api_context`. |
| `key_id` | string (uuid) | Key ID. The key secret is never returned in responses. |
| `organization` | object | The organization on whose behalf the key acts. |
| `organization.id` | string (uuid) | Organization ID. |
| `organization.name` | string | Organization name. |
| `scopes` | array of string | Read permissions granted to the key. |
| `scope` | object | Key scope: which workspaces and campaigns it can see. |
| `scope.workspace_mode` | string | `all`: all workspaces of the organization; `selected`: only the listed ones. Values: `all`, `selected`. |
| `scope.workspace_ids` | array of string | Selected workspaces. An empty array when `workspace_mode=all`. |
| `scope.workspace_include_future` | boolean | Whether workspaces created after the key was issued are included in the scope. |
| `scope.campaign_mode` | string | `all`: all campaigns in the selected workspaces; `selected`: only the listed ones. Values: `all`, `selected`. |
| `scope.campaign_ids` | array of string | Selected campaigns. An empty array when `campaign_mode=all`. |
| `scope.campaign_include_future` | boolean | Whether campaigns created after the key was issued are included in the scope. |
| `scope.scope_version` | integer | Scope version number. Increases with every change to the key's scope or permissions. |
| `api_version` | string | API version, always `v1`. |
| `expires_at` | string (date-time) or null | When the key expires. `null` if no expiry is set. |
| `limits` | object | Rate limits currently applied to the key. |
| `limits.key_second` | integer | Weight units per second per key. |
| `limits.key_minute` | integer | Weight units per minute per key. |
| `limits.org_second` | integer | Weight units per second per organization, across all keys combined. |
| `limits.org_minute` | integer | Weight units per minute per organization, across all keys combined. |
| `limits.key_concurrent` | integer | Concurrent requests per key. |
| `limits.org_concurrent` | integer | Concurrent requests per organization. |
| `limits.max_response_bytes` | string | Maximum response size in bytes (1 MiB). Long pages are shortened, no data is lost. Always `1048576`. |
| `limits.mode` | string | `normal`: normal mode; `emergency`: temporarily reduced limits. Values: `normal`, `emergency`. |
| `collection` | object | Status of saved conversation collection for the API. |
| `collection.state` | string | `running`: collection is active; `paused`: paused in Meliora; `preparing`: preparing after being enabled; `degraded`: data may be incomplete. Values: `running`, `paused`, `preparing`, `degraded`. |
| `collection.enabled_at` | string (date-time) or null | When collection was enabled. `null` if it has not been enabled yet. |
| `collection.pause_pending` | boolean | A pause or resume was requested in Meliora but has not been applied yet. |

Example:

```json
{
  "object": "api_context",
  "key_id": "9b1e7c42-5a6d-4f83-9e0b-2d7c4a8f1e65",
  "organization": {
    "id": "2c8f4a61-7d3e-4b9a-8f21-6a0d5e9c3b17",
    "name": "Example"
  },
  "scopes": [
    "campaigns:read",
    "events:read",
    "leads:read",
    "messages:read"
  ],
  "scope": {
    "workspace_mode": "all",
    "workspace_ids": [],
    "workspace_include_future": true,
    "campaign_mode": "all",
    "campaign_ids": [],
    "campaign_include_future": true,
    "scope_version": 1
  },
  "api_version": "v1",
  "expires_at": null,
  "limits": {
    "key_second": 5,
    "key_minute": 300,
    "org_second": 10,
    "org_minute": 600,
    "key_concurrent": 5,
    "org_concurrent": 10,
    "max_response_bytes": 1048576,
    "mode": "normal"
  },
  "collection": {
    "state": "running",
    "enabled_at": "2026-10-20T08:00:00.000Z",
    "pause_pending": false
  }
}
```

## Retrieve API key details

`GET /v1/me`

Returns the organization, permissions, scope and limits of the key. Use it as the first request to check the connection. Available to a key with any set of permissions.

Permission: any read permission. Request weight: 1.

### Parameters

No parameters.

### Response

Returns a `ApiContext` object.

### Endpoint-specific errors

- `scope_required` (403): The key does not have permission for this read. Texts also require "Message text" to be enabled.
- `not_found` (404): The object was not found or is outside the key's scope. An unknown path also returns 404.

Common errors: https://docs.melioralab.io/en/md/errors.md

### Example request

```bash
curl https://api.melioralab.io/v1/me \
  -H "Authorization: Bearer $MELIORA_API_KEY"
```

### Example response

```json
{
  "object": "api_context",
  "key_id": "9b1e7c42-5a6d-4f83-9e0b-2d7c4a8f1e65",
  "organization": {
    "id": "2c8f4a61-7d3e-4b9a-8f21-6a0d5e9c3b17",
    "name": "Example"
  },
  "scopes": [
    "campaigns:read",
    "events:read",
    "leads:read",
    "messages:read"
  ],
  "scope": {
    "workspace_mode": "all",
    "workspace_ids": [],
    "workspace_include_future": true,
    "campaign_mode": "all",
    "campaign_ids": [],
    "campaign_include_future": true,
    "scope_version": 1
  },
  "api_version": "v1",
  "expires_at": null,
  "limits": {
    "key_second": 5,
    "key_minute": 300,
    "org_second": 10,
    "org_minute": 600,
    "key_concurrent": 5,
    "org_concurrent": 10,
    "max_response_bytes": 1048576,
    "mode": "normal"
  },
  "collection": {
    "state": "running",
    "enabled_at": "2026-10-20T08:00:00.000Z",
    "pause_pending": false
  }
}
```