Clomni

Scope и endpoint: workspace, операторы, команды

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

Scope для данных workspace, AI-кредита, журнала аудита, операторов и команд. Ниже: что разрешает каждый scope, его риск, проверка и endpoint, которые он открывает.

Шаги

  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

    Читать данные workspace (workspace:read)

    Читает название workspace, язык, настройки (например, автозакрытие) и данные пакета. Интеграция обычно начинает с этого, чтобы проверить, к какому workspace она подключена.

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

    Endpoint:

    • GET /v1/workspace: Данные workspace

    Пример:

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

    Менять настройки workspace (workspace:write)

    Меняет название workspace, язык и настройку автозакрытия. Оплата, пакет и удаление workspace через API недоступны. Рабочие часы inbox меняются через inboxes:write, а не через этот scope.

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

    Endpoint:

    • PATCH /v1/workspace: Изменить настройки workspace

    Пример:

    curl -X PATCH "https://api.clomni.ai/v1/workspace" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"auto_resolve_after": 1440}'
  4. 4

    Читать пакет и использование (billing:read)

    Читает баланс AI-кредита workspace: месячный кредит, израсходованную и оставшуюся сумму, расход по функциям. В каталоге также указаны пакет, использование и счета, но сейчас единственный endpoint этого scope показывает AI-кредит.

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

    Endpoint:

    • GET /v1/ai_credits: Баланс AI-кредита

    Пример:

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

    Читать журнал аудита (audit_logs:read)

    Читает журнал аудита: кто, когда и что изменил. Сначала самые новые, 15 записей на странице. Нужен, чтобы переносить журнал в систему безопасности или комплаенса.

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

    Endpoint:

    • GET /v1/audit_logs: Журнал аудита

    Пример:

    curl "https://api.clomni.ai/v1/audit_logs?page=1" \
  -H "Authorization: Bearer clomni_pat_xxx"
  6. 6

    Видеть операторов (agents:read)

    Читает список операторов, их роли (administrator, agent) и онлайн-статус. Нужен, чтобы выбрать, кому назначить диалог, и показывать имена в отчётах.

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

    Endpoint:

    • GET /v1/agents: Список операторов
    • GET /v1/assignable_agents: Операторы, которых можно назначить

    Пример:

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

    Управлять операторами (agents:manage)

    Приглашает оператора (ему уходит письмо-приглашение), меняет роль и статус, удаляет из workspace. Нужен, чтобы автоматически держать список операторов в соответствии с кадровой системой. Ошибочный запрос может закрыть оператору доступ, поэтому риск высокий.

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

    Endpoint:

    • POST /v1/agents: Пригласить оператора
    • PATCH /v1/agents/{agent_id}: Изменить роль или статус оператора
    • DELETE /v1/agents/{agent_id}: Удалить оператора из workspace

    Пример:

    curl -X POST "https://api.clomni.ai/v1/agents" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Kamran Aliyev", "email": "[email protected]", "role": "agent"}'
  8. 8

    Видеть команды (teams:read)

    Читает команды и их участников.

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

    Endpoint:

    • GET /v1/teams: Список команд
    • GET /v1/teams/{team_id}: Получить команду
    • GET /v1/teams/{team_id}/team_members: Участники команды

    Пример:

    curl "https://api.clomni.ai/v1/teams" \
  -H "Authorization: Bearer clomni_pat_xxx"
    curl "https://api.clomni.ai/v1/teams/3/team_members" \
  -H "Authorization: Bearer clomni_pat_xxx"
  9. 9

    Менять команды (teams:write)

    Создаёт, меняет и удаляет команды, добавляет и убирает операторов. PATCH /v1/teams/{team_id}/team_members заменяет состав: в команде остаются только переданные пользователи.

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

    Endpoint:

    • POST /v1/teams: Создать команду
    • PATCH /v1/teams/{team_id}: Изменить команду
    • DELETE /v1/teams/{team_id}: Удалить команду
    • POST /v1/teams/{team_id}/team_members: Добавить операторов в команду
    • PATCH /v1/teams/{team_id}/team_members: Заменить состав команды
    • DELETE /v1/teams/{team_id}/team_members: Убрать операторов из команды

    Пример:

    curl -X POST "https://api.clomni.ai/v1/teams/3/team_members" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"user_ids": [12]}'
  10. 10

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

Документ

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