# Контекст ключа

Какой ключ выполняет запрос, что он видит и какие лимиты у него сейчас.

Базовый адрес: https://api.melioralab.io/v1. Ключ передается в заголовке `Authorization: Bearer mel_live_...`.

Маршруты:

- `GET /v1/me`: Получить сведения о ключе

## Объект ApiContext

Сведения о ключе, которым выполнен запрос: организация, права, охват, лимиты и состояние сбора.

| Поле | Тип | Описание |
|---|---|---|
| `object` | string | Тип объекта, всегда `api_context`. |
| `key_id` | string (uuid) | Идентификатор ключа. Секрет ключа в ответах не возвращается. |
| `organization` | object | Организация (кабинет), от имени которой действует ключ. |
| `organization.id` | string (uuid) | Идентификатор организации. |
| `organization.name` | string | Название организации. |
| `scopes` | array of string | Права чтения, выданные ключу. |
| `scope` | object | Охват ключа: какие пространства и кампании он видит. |
| `scope.workspace_mode` | string | `all`: все пространства кабинета; `selected`: только перечисленные. Значения: `all`, `selected`. |
| `scope.workspace_ids` | array of string | Выбранные пространства. Пустой массив при `workspace_mode=all`. |
| `scope.workspace_include_future` | boolean | Попадают ли в охват пространства, созданные после выпуска ключа. |
| `scope.campaign_mode` | string | `all`: все кампании выбранных пространств; `selected`: только перечисленные. Значения: `all`, `selected`. |
| `scope.campaign_ids` | array of string | Выбранные кампании. Пустой массив при `campaign_mode=all`. |
| `scope.campaign_include_future` | boolean | Попадают ли в охват кампании, созданные после выпуска ключа. |
| `scope.scope_version` | integer | Номер версии охвата. Растет при каждом изменении охвата или прав ключа. |
| `api_version` | string | Версия API, всегда `v1`. |
| `expires_at` | string (date-time) или null | Когда ключ перестанет действовать. `null`, если срок не задан. |
| `limits` | object | Лимиты запросов, действующие для ключа сейчас. |
| `limits.key_second` | integer | Весовых единиц в секунду на ключ. |
| `limits.key_minute` | integer | Весовых единиц в минуту на ключ. |
| `limits.org_second` | integer | Весовых единиц в секунду на организацию, по всем ключам вместе. |
| `limits.org_minute` | integer | Весовых единиц в минуту на организацию, по всем ключам вместе. |
| `limits.key_concurrent` | integer | Одновременных запросов на ключ. |
| `limits.org_concurrent` | integer | Одновременных запросов на организацию. |
| `limits.max_response_bytes` | string | Наибольший размер ответа в байтах (1 МиБ). Длинные страницы сокращаются, данные не теряются. Всегда `1048576`. |
| `limits.mode` | string | `normal`: обычный режим; `emergency`: временно сниженные лимиты. Значения: `normal`, `emergency`. |
| `collection` | object | Состояние сбора сохраненной переписки для API. |
| `collection.state` | string | `running`: сбор идет; `paused`: приостановлен в кабинете; `preparing`: готовится после включения; `degraded`: данные могут быть неполными. Значения: `running`, `paused`, `preparing`, `degraded`. |
| `collection.enabled_at` | string (date-time) или null | Когда сбор был включен. `null`, если еще не включен. |
| `collection.pause_pending` | boolean | Пауза или возобновление запрошены в кабинете, но еще не применены. |

Пример:

```json
{
  "object": "api_context",
  "key_id": "9b1e7c42-5a6d-4f83-9e0b-2d7c4a8f1e65",
  "organization": {
    "id": "2c8f4a61-7d3e-4b9a-8f21-6a0d5e9c3b17",
    "name": "Пример"
  },
  "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
  }
}
```

## Получить сведения о ключе

`GET /v1/me`

Возвращает организацию, права, охват и лимиты ключа. Первый запрос для проверки подключения. Доступен ключу с любым набором прав.

Право: любое право чтения. Вес запроса: 1.

### Параметры

Параметров нет.

### Ответ

Объект `ApiContext`.

### Особые ошибки

- `scope_required` (403): Ключ не имеет права на это чтение. Для текстов нужен также включенный «Текст сообщений».
- `not_found` (404): Объект не найден или находится вне охвата ключа. Неизвестный путь тоже дает 404.

Общие ошибки: https://docs.melioralab.io/md/errors.md

### Пример запроса

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

### Пример ответа

```json
{
  "object": "api_context",
  "key_id": "9b1e7c42-5a6d-4f83-9e0b-2d7c4a8f1e65",
  "organization": {
    "id": "2c8f4a61-7d3e-4b9a-8f21-6a0d5e9c3b17",
    "name": "Пример"
  },
  "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
  }
}
```