HTTP API канал

Интегрируйте внешние приложения с Cradle через локальный REST API — sync, async, webhook и scoped-аутентификация.

HTTP API channel выставляет Cradle как локальный сервер для мобильных приложений, web-фронтендов, CLI-инструментов, cron-задач и платформ автоматизации. Он использует тот же поток triage → RAG → agent → operator, что и Telegram и виджет, поэтому все возможности работают идентично.

Порт по умолчанию: 31416. Виджет занимает 31415.

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

Все endpoint'ы под /api/v1/*, кроме /api/v1/health, требуют ключ:

Authorization: Bearer <api-key>

или

X-Api-Key: <api-key>

Ключи scoped. См. Аутентификация и scopes для грамматики scopes и переключения проектов.

Scopes по endpoint'ам

Endpoint	Method	Scope
`/api/v1/health`	GET	(нет)
`/api/v1/messages`	POST	`messages:write`
`/api/v1/messages/:chatId`	GET	`messages:read`
`/api/v1/admin/agents`	GET / POST	`agents:read` / `agents:write`
`/api/v1/admin/agents/:id/execute`	POST	`agents:execute`
`/api/v1/admin/kb`	GET	`kb:read`
`/api/v1/admin/models`	GET	`models:read`
`/api/v1/admin/models/:catalogId/pull`	GET	`models:write`
`/api/v1/admin/tickets`	GET	`tickets:read`
`/api/v1/admin/keys`	GET / POST	`admin:*`
`/api/v1/projects`	*	`admin:*`

Заголовок проекта

Admin-ключи могут переключать проект на каждый запрос:

curl -H "x-api-key: ck_live_…" \
     -H "x-cradle-project: support" \
     http://127.0.0.1:31416/api/v1/admin/agents

Scoped-ключи должны использовать свой проект, иначе сервер вернёт 403.

POST /api/v1/messages

Отправить сообщение в Cradle.

{
  "text": "Какая у вас политика возврата?",
  "chatId": "client-42",
  "userId": "user-123",
  "meta": { "anything": "you-want" },
  "mode": "sync",
  "webhookUrl": "https://your-app.example.com/cradle-webhook",
  "timeoutMs": 60000
}

Поле	Тип	Обязательное	Описание
`text`	string	да	Текст сообщения, 1–50 000 символов
`chatId`	string	нет	ID беседы; генерируется UUID, если не указан. Используйте один и тот же для нити сообщений.
`userId`	string	нет	Внешний id пользователя, сохраняется в meta.
`meta`	object	нет	Произвольные данные, сохраняются в `tickets.channel_meta`.
`mode`	enum	нет	`sync` (default), `async`, `webhook`
`webhookUrl`	string	нет	Callback URL. Принудительно включает `webhook` mode.
`timeoutMs`	number	нет	Максимальное ожидание для sync/webhook. По умолчанию из настроек, max 120 000.

sync режим

Long-poll до ответа агента или timeout. Ответ (200):

{
  "ok": true,
  "mode": "sync",
  "chatId": "client-42",
  "ticketId": "550e8400-e29b-41d4-a716-446655440000",
  "replies": [
    { "type": "message", "text": "Гарантия 24 месяца...", "markdown": false },
    { "type": "attachment", "filename": "warranty.xlsx", "mime": "...", "base64": "..." }
  ]
}

replies — массив. Markdown-таблицы могут возвращаться как XLSX-вложения.

async режим

Сервер сразу возвращает 202. Ответы накапливаются в буфере и забираются через GET /api/v1/messages/:chatId.

{
  "ok": true,
  "mode": "async",
  "chatId": "client-42",
  "ticketId": "550e8400-...",
  "drainUrl": "/api/v1/messages/client-42"
}

webhook режим

Сервер сразу возвращает 202, а когда агент закончит, делает POST на webhookUrl с подписью HMAC-SHA256:

X-Cradle-Signature: sha256=<hex>

Секрет по умолчанию — API key, если webhookSecret не задан в настройках канала.

GET /api/v1/messages/:chatId

Забрать накопленные ответы для chat.

Параметр	Тип	Описание
`:chatId`	string	Тот же chatId, что в POST
`wait`	number	`0` — мгновенно; значение больше `0` — long-poll до N мс (max 60 000)

Ответ:

{
  "ok": true,
  "chatId": "client-42",
  "replies": [ { "type": "message", "text": "..." } ]
}

Пустой replies — не ошибка.

Rate limits

По умолчанию: 120 запросов / минуту / (IP + key).

Включение канала

В desktop-приложении: Integrations → HTTP API:

Сгенерируйте API key (минимум 16 символов для legacy-миграции, или используйте scoped admin:* ключ из CLI).
Выберите bindHost:
- 127.0.01 — только локальные процессы.
- 0.0.0.0 — доступ из локальной сети (откройте файрвол только доверенным машинам).
Сохраните и запустите.

На headless-сервере API channel включается по умолчанию после cradle server init.

HTTP API канал

On this page