# Справочник API

Все маршруты, поля и примеры ответов API Meliora v1.

API Meliora v1 отдает данные кабинета в JSON. Все маршруты используют метод GET и только читают данные. Справочник собран из спецификации [openapi.json](https://docs.melioralab.io/openapi.json).

## Базовый адрес

Все пути в справочнике указаны от адреса `https://api.melioralab.io`. Запросы выполняются по HTTPS с вашего сервера.

## Аутентификация

Передавайте ключ организации в заголовке `Authorization: Bearer mel_live_...`. Права и охват ключа описаны в руководстве [Аутентификация и ключи](https://docs.melioralab.io/authentication/).

## Формат данных

- JSON в UTF-8, имена полей в `snake_case`.
- Идентификаторы в формате UUID. Идентификатор сообщения и курсоры непрозрачные строки.
- Время в ISO 8601 по UTC с миллисекундами и суффиксом `Z`: `2026-10-26T07:30:00.000Z`.
- У каждого объекта есть поле `object` с его типом.
- Неизвестное значение передается как `unknown` или `null`, а не пропуском поля.

## Маршруты

| Маршрут | Что возвращает | Право |
|---|---|---|
| [`GET /v1/me`](https://docs.melioralab.io/reference/api-context/#getMe) | Получить сведения о ключе | любое |
| [`GET /v1/workspaces`](https://docs.melioralab.io/reference/workspaces/#listWorkspaces) | Список пространств | любое |
| [`GET /v1/campaigns`](https://docs.melioralab.io/reference/campaigns/#listCampaigns) | Список кампаний | `campaigns:read` |
| [`GET /v1/campaigns/{id}`](https://docs.melioralab.io/reference/campaigns/#getCampaign) | Получить кампанию | `campaigns:read` |
| [`GET /v1/leads`](https://docs.melioralab.io/reference/leads/#listLeads) | Список лидов | `leads:read` |
| [`GET /v1/leads/{id}`](https://docs.melioralab.io/reference/leads/#getLead) | Получить лида | `leads:read` |
| [`GET /v1/leads/{id}/messages`](https://docs.melioralab.io/reference/messages/#listLeadMessages) | Переписка с лидом | `messages:read` |
| [`GET /v1/events`](https://docs.melioralab.io/reference/events/#listEvents) | Лента событий | `events:read` |

## Заголовки ответа

| Заголовок | Описание |
|---|---|
| `Request-Id` | UUID запроса. Есть в каждом ответе, включая ошибки. |
| `Cache-Control` | Всегда `no-store`: ответы не кешируются. |
| `RateLimit-Policy`, `RateLimit` | Окна лимитов и остатки. См. [Лимиты и повторы](https://docs.melioralab.io/rate-limits/#zagolovki). |
| `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` | Лимит, остаток и время до сброса ближайшего к исчерпанию окна. |
| `Retry-After` | Секунд до повтора. Только у ответов 429 и 503. |

## Списки и ошибки

Списки возвращаются страницами по курсору, см. [Пагинация](https://docs.melioralab.io/pagination/). Ошибки приходят в формате `application/problem+json`, объект описан ниже, коды в руководстве [Ошибки](https://docs.melioralab.io/errors/).

## Объект Problem

Ошибка в формате RFC 9457 (`application/problem+json`).

| Поле | Тип | Описание |
|---|---|---|
| `type` | string | URI типа ошибки: `urn:meliora:problem:<code>`. |
| `title` | string | Короткое название ошибки на английском. |
| `status` | integer | HTTP-статус. |
| `detail` | string | Пояснение на русском или английском, по заголовку `Accept-Language`. Не разбирайте этот текст в коде. |
| `instance` | string | URI запроса: `urn:request:<request_id>`. |
| `code` | string | Машинный код ошибки. Обрабатывайте ошибки по `status` и `code`. |
| `param` | string или null | Параметр, к которому относится ошибка, или `null`. |
| `request_id` | string (uuid) | Идентификатор запроса, тот же, что в заголовке `Request-Id`. |

```json
{
  "type": "urn:meliora:problem:invalid_parameter",
  "title": "Invalid parameter",
  "status": 400,
  "detail": "Проверьте значение параметра",
  "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20",
  "code": "invalid_parameter",
  "param": "limit",
  "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20"
}
```