# Meliora API

> Публичный API Meliora v1: чтение кампаний, лидов, переписки и ленты событий по ключу организации. Только чтение, ранний доступ.

Базовый адрес: https://api.melioralab.io/v1. Аутентификация: заголовок `Authorization: Bearer <ключ>`, ключ никогда не передается в адресе запроса.

## Для агентов

- [Вся документация одним файлом](https://docs.melioralab.io/llms-full.txt): руководства и справочник в Markdown.
- [Спецификация OpenAPI 3.1](https://docs.melioralab.io/openapi.json): маршруты, параметры и схемы ответов.
- [Промпт для ИИ-агента](https://docs.melioralab.io/agent-prompt.txt): правила интеграции для помощника.

## Руководства

- [API Meliora](https://docs.melioralab.io/md/index.md): Публичный API Meliora v1: читайте кампании, лиды, сохраненную переписку и ленту событий вашего кабинета из CRM или своей системы.
- [Быстрый старт](https://docs.melioralab.io/md/quickstart.md): Первый запрос к API Meliora за 5 минут: ключ, проверка доступа, кампании, лиды и подписка на ленту событий.
- [Аутентификация и ключи](https://docs.melioralab.io/md/authentication.md): Ключи API Meliora: как получить, права чтения, охват, срок действия, IP-адреса, ротация, отзыв и безопасное хранение.
- [Ошибки](https://docs.melioralab.io/md/errors.md): Формат ошибок API Meliora (application/problem+json, RFC 9457), таблица кодов, заголовок Request-Id и какие ошибки повторять.
- [Пагинация](https://docs.melioralab.io/md/pagination.md): Как листать списки API Meliora: курсоры, параметр limit, поля has_more и next_cursor, срок жизни курсора и порядок записей.
- [Лимиты и повторы](https://docs.melioralab.io/md/rate-limits.md): Лимиты запросов API Meliora в весовых единицах по тарифам, заголовки RateLimit, обработка 429 и 503 и безопасные повторы.
- [Версии API](https://docs.melioralab.io/md/versioning.md): Как версионируется API Meliora, какие изменения считаются совместимыми и как писать клиент, который их переживет.
- [Опрос событий](https://docs.melioralab.io/md/events-polling.md): Надежный опрос ленты событий API Meliora: хранение курсора, атомарное применение страницы, дедупликация по event.id, start=now, ответ 410 и восстановление после простоя.
- [Связь с CRM](https://docs.melioralab.io/md/crm-mapping.md): Как сопоставить лидов и события API Meliora с записями CRM через fields.record_id, что означает record_id_status и почему ник Telegram не годится как ключ.
- [Статусы лида и доставки](https://docs.melioralab.io/md/lead-states.md): Значения status, delivery_state, automation_state и reason_code в API Meliora простыми словами, включая значения, которые пока не приходят.
- [ИИ-агенты и MCP](https://docs.melioralab.io/md/ai-agents.md): Как подключить документацию API Meliora к Claude, ChatGPT, Cursor и Claude Code: llms.txt, llms-full.txt, openapi.json, Markdown страниц, готовый промпт и безопасная работа с ключом.
- [Журнал изменений](https://docs.melioralab.io/md/changelog.md): Изменения публичного API Meliora по версиям.
- [Что дальше](https://docs.melioralab.io/md/roadmap.md): Возможности, над которыми мы работаем для следующих версий API Meliora. Без сроков.
- [Поддержка](https://docs.melioralab.io/md/support.md): Как связаться с поддержкой Meliora по вопросам API и что приложить к обращению.

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

- [Справочник API](https://docs.melioralab.io/md/reference.md): Справочник API Meliora v1: базовый адрес, аутентификация, формат данных, маршруты, заголовки ответа и объект ошибки.
- [Справочник: Контекст ключа](https://docs.melioralab.io/md/reference/api-context.md): Какой ключ выполняет запрос, что он видит и какие лимиты у него сейчас.
- [Справочник: Пространства](https://docs.melioralab.io/md/reference/workspaces.md): Пространства: отдельные рабочие области кабинета. У каждого свои кампании, аккаунты и контакты.
- [Справочник: Кампании](https://docs.melioralab.io/md/reference/campaigns.md): Кампания: цепочка сообщений, которую аккаунты Telegram отправляют контактам по расписанию.
- [Справочник: Лиды](https://docs.melioralab.io/md/reference/leads.md): Лид: участие одного контакта в одной кампании. Если один человек есть в двух кампаниях, это два лида с разными id.
- [Справочник: Переписка](https://docs.melioralab.io/md/reference/messages.md): Сохраненные сообщения переписки аккаунта с лидом: исходящие шаги цепочки, ручные сообщения и ответы.
- [Справочник: События](https://docs.melioralab.io/md/reference/events.md): Лента событий: первое сообщение лиду и ответ лида. Читайте ее по курсору, чтобы узнавать об изменениях без обхода всех лидов.

## Другие языки

- [English version](https://docs.melioralab.io/en/llms.txt)