Документация › Для разработчиков › Публичный API
Публичный API и ключи dos_sk_live_…
Обновлено 1 октября 2026 г.
[для разработчиков]Дёргай платформу из своего кода: API-ключdos_sk_live_…авторизует запросы как тебя самого, с теми же правами на проекты, что и в браузере.
⏱ 8 мин · 👤 для разработчика · 🟢 live
За 30 секунд:
- Ключ формата
dos_sk_live_…, передаётся в заголовкеAuthorization: Bearer ….- Ключ работает от имени твоего аккаунта: действуют те же роли/доступы, что и в кабинете.
- Ключи бывают read и read+write, на весь аккаунт или на один проект.
- Хранится только SHA-256-хеш, сырой ключ показывается один раз при создании. Потерял, выпусти новый.
Создание ключа
В кабинете → управление API-ключами → создать. При создании:
- задаёшь права: только чтение (
read) или чтение+запись (read+write); - задаёшь область: весь аккаунт (все твои проекты) или один проект;
- опционально, срок жизни (1-365 дней).
🔑 Сырой ключ виден ОДИН раз. Платформа хранит только его SHA-256-хеш и не может показать ключ повторно. Скопируй сразу в надёжное место. Потерял, просто отзови и выпусти новый.
Лимиты: до 50 ключей на аккаунт; запросы по ключу до 120 в минуту (при превышении API вернёт 429 Too Many Requests, сделайте паузу и повторите). Управлять ключами можно только из браузера (залогиненная сессия), сам ключ не может создавать другие ключи (защита от эскалации прав).
Использование
Передавай ключ в заголовке:
Authorization: Bearer dos_sk_live_…Платформа резолвит ключ в твоего пользователя, дальше работают те же правила доступа, что и в кабинете: ключ видит ровно те проекты и может ровно то, что роль твоего аккаунта на этих проектах. Никаких отдельных «прав ключа» сверх твоих собственных нет.
| Свойство | Поведение |
|---|---|
| Права | read: только GET; write, позволяет POST/PUT/PATCH/DELETE. Ключ только для чтения на мутирующем запросе → отказ |
| Область | account-scoped (все проекты) или project-scoped (заблокирован на один) |
| RBAC | наследует роли твоего аккаунта на проектах, не выше |
| Отзыв | отозванный ключ перестаёт работать сразу |
Базовый адрес: https://dosai.pro. Пример запроса:
curl https://dosai.pro/api/projects \
-H "Authorization: Bearer dos_sk_live_…"Машиночитаемое описание
| Адрес | Что это |
|---|---|
https://dosai.pro/api/openapi.json | Полная спецификация OpenAPI 3.1: все эндпоинты, параметры, коды ошибок. Открыта без ключа, подходит для генераторов клиентов и Postman |
https://dosai.pro/llms.txt | Короткая памятка для ИИ-агентов: что за платформа, как авторизоваться, куда идти дальше |
https://dosai.pro/api/mcp | MCP-сервер: тот же каталог как готовые инструменты для Claude Code, Codex и Cursor. См. Подключить ИИ-агента |
Каталог эндпоинтов
Все пути, относительно https://dosai.pro, авторизация, Authorization: Bearer dos_sk_live_… (мутирующие запросы требуют ключ с правом write).
Проекты
| Метод | Путь | Что делает |
|---|---|---|
| GET | /api/projects | Список всех проектов пользователя |
| POST | /api/projects | Создать новый проект: { name, company_name, industry, … } |
| GET | /api/projects/:id | Получить проект по ID |
| PATCH | /api/projects/:id | Обновить проект |
| DELETE | /api/projects/:id | Удалить проект |
Лиды
| Метод | Путь | Что делает |
|---|---|---|
| GET | /api/projects/:id/leads | Список лидов. Query: page, limit, status (none/potential/qualified/hot/converted/reserve/lost), before (курсор) |
| GET | /api/projects/:id/leads/:leadId | Получить лид по ID |
| PATCH | /api/projects/:id/leads/:leadId | Обновить лид: { lead_status, client_name, phone, email } |
| DELETE | /api/projects/:id/leads | Массовое удаление: { ids: string[] } |
| GET | /api/projects/:id/leads/export | Экспорт лидов в CSV |
| GET | /api/projects/:id/lead-statuses | Статусы воронки проекта |
| GET | /api/projects/:id/leads/:leadId/activity | История лида |
| GET | /api/projects/:id/leads/:leadId/reminders | Напоминания по лиду |
| POST | /api/projects/:id/leads/:leadId/reminders | Поставить напоминание: { due_at, note? } |
| GET | /api/projects/:id/tags | Теги проекта |
Записи (подтверждение и напоминания)
Если клиент записывается у вас в CRM, на сайте или в сервисе записи, ваша система сообщает нам о записи одним запросом, а платформа сама подтверждает её клиенту в WhatsApp или Telegram и напоминает перед визитом. Тексты и сроки владелец задаёт в кабинете: Автоматизации → Записи (подробно).
| Метод | Путь | Что делает |
|---|---|---|
| POST | /api/projects/:id/bookings | Создать или обновить запись: { external_id, phone, client_name, service, start_at, end_at?, status?, confirm? }. Повтор того же external_id обновляет, новое start_at переносит, status: "cancelled" отменяет |
| GET | /api/projects/:id/bookings | Список записей с планом сообщений. Query: status (upcoming/past/cancelled/all), from, to, q, page, limit |
| GET | /api/projects/:id/bookings/:externalId | Одна запись по вашему номеру и её сообщения |
| DELETE | /api/projects/:id/bookings/:externalId | Отменить запись: ожидающие сообщения снимаются |
| GET | /api/projects/:id/booking-settings | Настройки подтверждения и напоминаний |
| PATCH | /api/projects/:id/booking-settings | Изменить настройки: { enabled, confirmation: { enabled, text }, reminders: [{ offset_minutes, text? }], template } |
Пример: ваша CRM создала запись.
curl -X POST https://dosai.pro/api/projects/<id проекта>/bookings \
-H "Authorization: Bearer dos_sk_live_…" \
-H "Content-Type: application/json" \
-d '{"external_id":"A-1024","phone":"+77011234567","client_name":"Анна","service":"Маникюр","start_at":"2026-09-23 15:00"}'Что важно знать программисту:
- Время без смещения (
2026-09-23 15:00) читается по часовому поясу проекта. В ответе естьstart_at_local: сверьте, так ли мы поняли время. - Писать первыми можно только знакомым. Поле
contactв ответе это подсказка на момент записи, перед каждой отправкой проверка повторяется: known: сообщения уйдут;unknown: человек ни разу не писал на номер WhatsApp проекта. Запись сохранена, но первыми мы ему не пишем, так номер не заблокируют. Такие записи видны в кабинете с кнопкой «Написать со своего телефона»;unverified: проверить не удалось прямо сейчас (например, канал проекта в этот момент офлайн), платформа попробует позже;instagram: у Instagram окно ответа 24 часа, напоминание за сутки туда не пролезет.- Ночью не пишем: сообщения уходят с 9:00 до 21:00 по часам проекта. Ночное напоминание уходит накануне в 20:30.
- Подтверждение не уходит, если в этом чате за последние 30 минут был разговор (клиент только что записался через бота).
confirm: falseвыключает его явно, если ваша система подтверждает сама. - Ключ нужен со скоупом
write. Лимит 120 запросов в минуту.
Диалоги
| Метод | Путь | Что делает |
|---|---|---|
| GET | /api/projects/:id/conversations | Список диалогов. Query: page, limit, status (open/resolved/closed), include_archived |
| GET | /api/projects/:id/conversations/:convId | Детали диалога |
| PATCH | /api/projects/:id/conversations/:convId | Изменить диалог: { client_name, phone, tags[], status, archived_at, pinned_at } |
| GET | /api/projects/:id/conversations/:convId/messages | Сообщения диалога |
| POST | /api/projects/:id/conversations/:convId/send | Отправить сообщение от оператора: { text: string }, опционально заголовок Idempotency-Key. Ответ 200 ещё не значит «доставлено»: смотрите поле ok |
| GET | /api/projects/:id/conversations/ai-paused | Сколько диалогов бот сейчас не ведёт: { count } |
| POST | /api/projects/:id/conversations/:convId/toggle-ai | Переключить бота в одном диалоге (вкл ↔ выкл), ответ { ai_on } после переключения |
| GET | /api/projects/:id/conversations/:convId/notes | Внутренние заметки к диалогу |
| POST | /api/projects/:id/conversations/:convId/notes | Добавить заметку: { body } |
| GET | /api/projects/:id/conversations/:convId/scheduled | Отложенные сообщения клиенту |
| POST | /api/projects/:id/conversations/:convId/scheduled | Запланировать сообщение клиенту: { text, send_at } (от минуты до 31 дня) |
| GET | /api/projects/:id/conversations/:convId/search | Поиск по сообщениям одного диалога. Query: q |
| GET | /api/projects/:id/broadcasts | Рассылки и их итоги (запуск только в кабинете) |
Функции ассистента
| Метод | Путь | Что делает |
|---|---|---|
| GET | /api/projects/:id/functions | Список функций бота. Значения секретов (токены, ключи) маскируются сервером |
Интеграции
| Метод | Путь | Что делает |
|---|---|---|
| GET | /api/projects/:id/integrations | Список интеграций |
| POST | /api/projects/:id/integrations | Создать интеграцию (webhook): { name, type, url, events[], headers? } |
| PUT | /api/projects/:id/integrations/:intId | Изменить интеграцию: те же поля, что при создании |
| DELETE | /api/projects/:id/integrations/:intId | Удалить интеграцию |
Аналитика и отчёты
| Метод | Путь | Что делает |
|---|---|---|
| GET | /api/projects/:id/analytics | Статистика проекта это query from, to (YYYY-MM-DD) |
| GET | /api/projects/:id/reports | Скачать PDF-отчёт за месяц, query period=2026-03 |
| GET | /api/projects/:id/analytics/funnel | Воронка, источники и когорты за период (по умолчанию 30 дней). Query: from, to |
| GET | /api/projects/:id/logs | Журнал событий. Query: category, search, dateFrom, dateTo, event_type, before, limit, page |
| GET | /api/projects/:id/report-config | Отчёты по расписанию (владелец) |
Биллинг
| Метод | Путь | Что делает |
|---|---|---|
| GET | /api/projects/:id/tokens | Баланс токенов проекта |
| GET | /api/projects/:id/tokens/history | История транзакций |
| GET | /api/projects/:id/payments/invoices | Счета клиентам бизнеса (только просмотр). Query: page, per_page, status |
Бот, база знаний, функции и автоматизации
Эти же маршруты зовут кнопки кабинета и ИИ-ассистенты (ChatGPT, Claude по кнопке «Разрешить»), поэтому ответы приходят в том виде, в каком их получает экран кабинета.
| Метод | Путь | Что делает |
|---|---|---|
| GET | /api/projects/:id/overview-insights | Неделя против прошлой (диалоги, лиды, % изменения), лиды по статусам, минуты с последнего диалога и лида |
| GET | /api/projects/:id/baileys/status | Состояние WhatsApp-номера проекта |
| GET | /api/projects/:id/telegram/status | Состояние Telegram-бота |
| GET | /api/projects/:id/agent-config | Настройки бота: кому отвечает, расписание, буфер, пауза оператора, дожимы, память |
| PUT | /api/projects/:id/agent-config | Изменить настройки: только нужные ключи, ответ это настройки целиком |
| GET | /api/projects/:id/prompt-versions | Сохранённые версии системного промпта |
| POST | /api/projects/:id/test-chat | Спросить бота в тест-чате как клиент: { message, history? }, списывает с баланса как обычный ответ |
| GET | /api/projects/:id/knowledge | Документы базы знаний. Query: limit, offset |
| POST | /api/projects/:id/knowledge | Добавить документ: { name, file_type, content?, file_url? } |
| PATCH | /api/projects/:id/knowledge/:kbId | Включить или выключить документ, переименовать, прикреплять к каждому ответу: { is_active?, always_include?, name? } |
| GET | /api/projects/:id/knowledge/:kbId/chunks | Текст документа кусками, как его видит бот |
| GET | /api/projects/:id/media | Медиатека, которую бот отправляет клиентам |
| GET | /api/projects/:id/functions/:funcId | Одна функция, секреты замаскированы |
| PATCH | /api/projects/:id/functions/:funcId | Изменить функцию, например { is_active: false } |
| GET | /api/projects/:id/functions/:funcId/executions | Последние вызовы функции. Query: limit |
| GET | /api/projects/:id/functions/health | Вызовы, ошибки и доля успешных по каждой функции. Query: range (24h/7d/30d) |
| GET | /api/projects/:id/drip | Клиенты в дожимах. Query: page, limit |
| GET | /api/projects/:id/drip/stats | Результаты дожимов по статусам и касаниям |
| GET | /api/projects/:id/automations | Правила «когда, если, то» |
| PATCH | /api/projects/:id/automations | Включить или выключить правило: { ruleId, is_active } |
| GET | /api/projects/:id/automations/runs | Когда правила сработали. Query: limit, kind |
| GET | /api/help/articles | Оглавление этого руководства: название, ссылка, выжимка (для ИИ-ассистентов, отвечающих «как сделать») |
Лимиты запросов
- API-ключ: до 120 запросов/мин на ключ; сверх:
429 Too Many Requests. - Ориентиры по типам: GET ≈ 30-60/мин, POST/PATCH ≈ 10-30/мин, PDF-отчёты ≈ 5/мин (точные значения у каждого роута свои).
- В каждом ответе, заголовки
X-RateLimit-Limit/X-RateLimit-Remaining/X-RateLimit-Reset; при 429 ещё иRetry-After(секунды до сброса).
Безопасность ключа
- Это пароль доступа к твоим проектам: храни как секрет, не коммить в репозиторий, не клади в открытый фронтенд.
- Светанул ключ, немедленно отзови и выпусти новый.
- Для интеграции, которой нужно только читать, выдавай read-only ключ.
- Нужен доступ только к одному проекту это делай project-scoped ключ, не account-wide.
Простыми словами
Если ты разработчик и хочешь дёргать платформу из своего кода, заводишь API-ключ. Это длинная строка вида dos_sk_live_…, которую ты прикладываешь к запросам в заголовке Authorization. Важная идея: ключ это «ты в виде кода». Он видит ровно те проекты и умеет ровно то, что и ты сам в кабинете, не больше. Хочешь дать интеграции только читать, выпусти ключ «только чтение». Хочешь ограничить одним проектом: выпусти ключ на этот проект.
Главное правило безопасности: ключ показывается один-единственный раз при создании, мы храним только его «отпечаток» и заново показать не сможем. Скопировал, сохранил надёжно. Потерял или засветил, не страшно, заходишь и отзываешь, выпускаешь новый. И никогда не клади такой ключ в открытый код или фронтенд: это как пароль.
Дальше: → Кастомные вебхуки
Связано: Роли и права · Формат данных
Не получилось? → напиши в саппорт