Clomni

Scope и endpoint: AI-агенты, база знаний, центр помощи

Обновлено: 11 ноября 2026 · 13 мин чтения

Scope для чтения, обучения и публикации AI-агентов, получения от них ответов, базы знаний и центра помощи. Изменение AI-агента идёт в два шага: ai_agents:write готовит черновик, ai_agents:publish делает его рабочим.

Шаги

  1. 1

    Как читать эту статью

    • Пути пишутся после https://api.clomni.ai/v1: GET /v1/agents означает https://api.clomni.ai/v1/agents. В пути нет ID workspace, потому что токен привязан к одному workspace.
    • В каждом запросе есть заголовок Authorization: Bearer clomni_pat_xxx. Как получить токен: Токены и аутентификация в Developer API.
    • Риск: низкий (нет персональных данных), средний (читает данные клиентов или меняет внутренние данные), высокий (отправляет клиентам, удаляет, массово выгружает, меняет рабочие настройки).
    • Каждый scope проходит review, в public app тоже. Подробнее: Review: проверка scope и причины отказа.
    • «Дополнительно даёт»: write и manage дают и read того же ресурса. send, delete, publish, assign, run ничего не дают.
    • Если endpoint открывается несколькими scope, достаточно одного. Без scope API отвечает 403 insufficient_scope, в ответе есть required_scopes.
    • Каждый POST принимает заголовок Idempotency-Key: повторный запрос не выполняется дважды.
  2. 2

    Видеть AI-агентов (ai_agents:read)

    Читает AI-агентов: настройки, инструкции, черновик, версии, FAQ (в панели «Вопросы с ответами»), сценарии (в панели «Ситуации»), тестовые вопросы и прогоны, инструменты агента и inbox, где он отвечает.

    • Риск: низкий.
    • Проверка: проходит review, scope с низким риском смотрят быстро.
    • Дополнительно даёт: ничего больше.

    Endpoint:

    • GET /v1/ai_agent_faqs: Список FAQ
    • GET /v1/ai_agent_faqs/{faq_id}: Получить FAQ
    • GET /v1/ai_agent_tools: Список инструментов AI-агента
    • GET /v1/ai_agent_tools/{ai_agent_tool_id}: Получить инструмент AI-агента
    • GET /v1/ai_agents: Список AI-агентов
    • GET /v1/ai_agents/tools: Инструменты, доступные AI-агенту
    • GET /v1/ai_agents/{ai_agent_id}: Получить AI-агента
    • GET /v1/ai_agents/{ai_agent_id}/draft: Черновик AI-агента
    • GET /v1/ai_agents/{ai_agent_id}/inboxes: Inbox, в которых отвечает AI-агент
    • GET /v1/ai_agents/{ai_agent_id}/scenarios: Список ситуаций
    • GET /v1/ai_agents/{ai_agent_id}/scenarios/{scenario_id}: Получить ситуацию
    • GET /v1/ai_agents/{ai_agent_id}/test_questions: Список тестовых вопросов
    • GET /v1/ai_agents/{ai_agent_id}/test_runs/{test_run_id}: Получить тестовый прогон
    • GET /v1/ai_agents/{ai_agent_id}/versions: Версии AI-агента

    Пример:

    curl "https://api.clomni.ai/v1/ai_agents" \
  -H "Authorization: Bearer clomni_pat_xxx"
    curl "https://api.clomni.ai/v1/ai_agent_faqs" \
  -H "Authorization: Bearer clomni_pat_xxx"
  3. 3

    Черновики AI-агентов (ai_agents:write)

    Создаёт AI-агентов, меняет настройки черновика, сохраняет и удаляет ситуации в черновике. Работающего агента не трогает: черновик публикует ai_agents:publish.

    • Риск: средний.
    • Проверка: проходит review. Конкретно напишите, какие данные, когда и зачем Вы используете.
    • Дополнительно даёт: ai_agents:read.

    Endpoint:

    • POST /v1/ai_agents: Создать AI-агента
    • PATCH /v1/ai_agents/{ai_agent_id}/draft: Изменить черновик AI-агента
    • POST /v1/ai_agents/{ai_agent_id}/draft/scenarios: Сохранить ситуацию в черновике
    • DELETE /v1/ai_agents/{ai_agent_id}/draft/scenarios/{scenario_id}: Удалить ситуацию из черновика

    Пример:

    curl -X POST "https://api.clomni.ai/v1/ai_agents" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Помощник продаж", "description": "Отвечает на вопросы о заказах и доставке", "config": {"product_name": "Demo Store"}}'
  4. 4

    Обучать AI-агентов (ai_agents:train)

    Обучает AI-агента: добавляет, меняет и удаляет FAQ, ситуации и тестовые вопросы, импортирует вопросы, запускает тесты, оценивает результаты, перестраивает знания агента. Тесты и перестройка расходуют AI-кредит.

    • Риск: средний.
    • Проверка: проходит review. Конкретно напишите, какие данные, когда и зачем Вы используете.
    • Дополнительно даёт: ничего больше.

    Endpoint:

    • POST /v1/ai_agent_faqs: Создать FAQ
    • PATCH /v1/ai_agent_faqs/{faq_id}: Изменить FAQ
    • DELETE /v1/ai_agent_faqs/{faq_id}: Удалить FAQ
    • POST /v1/ai_agents/{ai_agent_id}/scenarios: Создать ситуацию
    • PATCH /v1/ai_agents/{ai_agent_id}/scenarios/{scenario_id}: Изменить ситуацию
    • DELETE /v1/ai_agents/{ai_agent_id}/scenarios/{scenario_id}: Удалить ситуацию
    • POST /v1/ai_agents/{ai_agent_id}/test_questions: Создать тестовый вопрос
    • POST /v1/ai_agents/{ai_agent_id}/test_questions/import: Импорт тестовых вопросов
    • PATCH /v1/ai_agents/{ai_agent_id}/test_questions/{test_question_id}: Изменить тестовый вопрос
    • DELETE /v1/ai_agents/{ai_agent_id}/test_questions/{test_question_id}: Удалить тестовый вопрос
    • PATCH /v1/ai_agents/{ai_agent_id}/test_results/{test_result_id}: Оценить результат теста
    • POST /v1/ai_agents/{ai_agent_id}/test_runs: Запустить тест
    • POST /v1/ai_agents/{ai_agent_id}/train: Переобучить AI-агента

    Пример:

    curl -X POST "https://api.clomni.ai/v1/ai_agent_faqs" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"question": "Сколько идёт доставка?", "answer": "По Баку 1 рабочий день, в регионы 2-3 рабочих дня.", "assistant_id": 4}'
  5. 5

    Публиковать AI-агентов (ai_agents:publish)

    Меняет работающего агента: публикует черновик, восстанавливает старую версию, сразу меняет настройки через PATCH /v1/ai_agents/{ai_agent_id}, подключает агента к inbox и отключает, меняет режим работы в inbox, удаляет агента. Меняются ответы, которые получают клиенты, поэтому риск высокий.

    • Риск: высокий.
    • Проверка: проходит review и проверяется внимательнее. Нужны подробное объяснение и короткое видео функции, целевой срок 2 рабочих дня.
    • Дополнительно даёт: ничего больше.

    Endpoint:

    • PATCH /v1/ai_agents/{ai_agent_id}: Изменить работающего AI-агента
    • DELETE /v1/ai_agents/{ai_agent_id}: Удалить AI-агента
    • POST /v1/ai_agents/{ai_agent_id}/draft/publish: Опубликовать черновик AI-агента
    • POST /v1/ai_agents/{ai_agent_id}/inboxes: Подключить AI-агента к inbox
    • PATCH /v1/ai_agents/{ai_agent_id}/inboxes/{inbox_id}: Изменить режим работы AI-агента в inbox
    • DELETE /v1/ai_agents/{ai_agent_id}/inboxes/{inbox_id}: Отключить AI-агента от inbox
    • POST /v1/ai_agents/{ai_agent_id}/versions/{version}/restore: Восстановить версию AI-агента

    Пример:

    curl -X POST "https://api.clomni.ai/v1/ai_agents/4/draft/publish" \
  -H "Authorization: Bearer clomni_pat_xxx"
    curl -X POST "https://api.clomni.ai/v1/ai_agents/4/inboxes" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"inbox": {"inbox_id": 5}}'
  6. 6

    Получать ответы AI-агента (ai_agents:ask)

    Получает ответы AI-агента на Вашей платформе, как в тестовой панели агента. В диалоги ничего не пишется. Каждый ответ списывается с AI-кредита, когда он заканчивается, приходит 402 ai_credit_spent. При handoff: true передайте вопрос человеку.

    • Риск: средний.
    • Проверка: проходит review. Конкретно напишите, какие данные, когда и зачем Вы используете.
    • Дополнительно даёт: ничего больше.

    Endpoint:

    • POST /v1/ai_agents/{ai_agent_id}/ask: Получить ответ AI-агента

    Пример:

    curl -X POST "https://api.clomni.ai/v1/ai_agents/4/ask" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"question": "А в регионы?", "history": [{"role": "user", "content": "Сколько идёт доставка?"}, {"role": "assistant", "content": "По Баку 1 рабочий день."}]}'
  7. 7

    Видеть базу знаний (knowledge:read)

    Читает документы и ссылки базы знаний и состояние их обработки (status, sync_status).

    • Риск: низкий.
    • Проверка: проходит review, scope с низким риском смотрят быстро.
    • Дополнительно даёт: ничего больше.

    Endpoint:

    • GET /v1/knowledge: Документы базы знаний
    • GET /v1/knowledge/{document_id}: Получить документ

    Пример:

    curl "https://api.clomni.ai/v1/knowledge?assistant_id=4" \
  -H "Authorization: Bearer clomni_pat_xxx"
  8. 8

    Менять базу знаний (knowledge:write)

    Добавляет веб-страницу по ссылке или файл и удаляет документы. Документ обрабатывается в фоне, status показывает готовность. Отдельного endpoint для обновления нет: когда страница меняется, удалите старый документ и добавьте заново.

    • Риск: средний.
    • Проверка: проходит review. Конкретно напишите, какие данные, когда и зачем Вы используете.
    • Дополнительно даёт: knowledge:read.

    Endpoint:

    • POST /v1/knowledge: Добавить документ или ссылку
    • DELETE /v1/knowledge/{document_id}: Удалить документ базы знаний

    Пример:

    curl -X POST "https://api.clomni.ai/v1/knowledge" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"document": {"name": "Правила доставки", "external_link": "https://demo-store.example/delivery", "assistant_id": 4}}'
  9. 9

    Читать журнал AI (ai_logs:read)

    Читает журнал AI: вопросы, на которые агент не ответил, проверки ответов и результаты агента.

    • Риск: средний.
    • Проверка: проходит review. Конкретно напишите, какие данные, когда и зачем Вы используете.
    • Дополнительно даёт: ничего больше.

    Endpoint:

    • GET /v1/ai_agents/{ai_agent_id}/gaps: Вопросы, на которые AI-агент не ответил
    • GET /v1/ai_agents/{ai_agent_id}/results: Результаты AI-агента
    • GET /v1/ai_agents/{ai_agent_id}/reviews: Проверки ответов AI
    • GET /v1/ai_agents/{ai_agent_id}/reviews/{review_id}: Проверка ответа AI

    Пример:

    curl "https://api.clomni.ai/v1/ai_agents/4/gaps" \
  -H "Authorization: Bearer clomni_pat_xxx"
  10. 10

    Видеть центр помощи (help_center:read)

    Читает порталы центра помощи, категории и статьи, ищет по статьям.

    • Риск: низкий.
    • Проверка: проходит review, scope с низким риском смотрят быстро.
    • Дополнительно даёт: ничего больше.

    Endpoint:

    • GET /v1/portals: Список порталов центра помощи
    • GET /v1/portals/{portal_id}: Получить портал
    • GET /v1/portals/{portal_id}/articles: Список статей
    • GET /v1/portals/{portal_id}/articles/{article_id}: Получить статью
    • GET /v1/portals/{portal_id}/categories: Список категорий
    • GET /v1/portals/{portal_id}/categories/{category_id}: Получить категорию
    • GET /v1/search/articles: Поиск по статьям центра помощи

    Пример:

    curl "https://api.clomni.ai/v1/portals" \
  -H "Authorization: Bearer clomni_pat_xxx"
  11. 11

    Менять центр помощи (help_center:write)

    Пишет, меняет, публикует и удаляет статьи, создаёт категории, меняет порядок и настройки портала.

    • Риск: средний.
    • Проверка: проходит review. Конкретно напишите, какие данные, когда и зачем Вы используете.
    • Дополнительно даёт: help_center:read.

    Endpoint:

    • PATCH /v1/portals/{portal_id}: Изменить портал
    • POST /v1/portals/{portal_id}/articles: Создать статью
    • POST /v1/portals/{portal_id}/articles/reorder: Изменить порядок статей
    • PATCH /v1/portals/{portal_id}/articles/{article_id}: Изменить статью
    • DELETE /v1/portals/{portal_id}/articles/{article_id}: Удалить статью
    • POST /v1/portals/{portal_id}/categories: Создать категорию
    • POST /v1/portals/{portal_id}/categories/reorder: Изменить порядок категорий
    • PATCH /v1/portals/{portal_id}/categories/{category_id}: Изменить категорию
    • DELETE /v1/portals/{portal_id}/categories/{category_id}: Удалить категорию

    Пример:

    curl -X POST "https://api.clomni.ai/v1/portals/demo-store/articles" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"title": "Как отследить заказ?", "content": "Номер заказа указан в разделе «Мои заказы».", "category_id": 11, "status": "published", "locale": "ru"}'
  12. 12

    О центре помощи

    Сайта помощи для клиентов (портал, категории, статьи) нет в пакетах Clomni с 5 ноября 2026 года, в панели он не отображается. Scope help_center:* и их endpoint остаются в каталоге, но не стройте на них новые интеграции. Для автоматических ответов клиентам используйте базу знаний AI-агента (knowledge:write) и FAQ (ai_agents:train).

  13. 13

    Связанные статьи

Документ

Платформа для разработчиков: руководство v1.0 · 41 стр. Открыть Скачать