Документация для разработчиков

API Clero

Подключайте серверные системы партнёров, подготавливайте рабочие пространства клиентов, устанавливайте шаблоны агентов и отправляйте сообщения агентам автоматизации Clero с помощью постоянных серверных учётных данных.

OpenAPI JSON Документация Markdown

Базовый URL

https://clero.so/api/v1

Авторизация: Партнёрский Bearer-токен
Транспорт: HTTPS JSON и multipart
Выполнение: Приём сразу, ответы позже

Обзор

Для чего предназначен этот API

Публичный API предназначен для интеграций между серверными системами. Храните токены на сервере, используйте постоянные внешние идентификаторы для повторных запросов, а выполнение работы агентов в каждом пространстве доверьте Clero.

Подготавливайте пространства клиентов

Создайте или повторно используйте пространство Clero и установите одобренные шаблоны агентов из серверной части.

Используйте существующих агентов

Найдите пространства и агентов, а затем создайте источники API-чата для выбранных агентов автоматизации.

Отправляйте сообщения агентам

Объединяйте сообщения по session_id, устраняйте дубликаты через external_message_id, а затем опрашивайте API или получайте ответы.

Быстрый старт

От токена до первого сообщения агенту

Большинство партнёрских интеграций строится одинаково: авторизуйтесь, найдите или подготовьте рабочее пространство, подключите источник API-чата и отправляйте сообщения с постоянным ключом сессии.

Создайте партнёрский токен

Создайте токен в панели администрирования организации и предоставьте ему минимально необходимые разрешения.

Authorization: Bearer <PARTNER_TOKEN>

Найдите или подготовьте рабочее пространство

Получите список пространств существующих клиентов или используйте external_space_id, чтобы создать либо повторно использовать пространство клиента.

GET /automation/spaces/ or POST /automation/agent-templates/provision-space/

Подключите источник API-чата

Создайте или повторно используйте источник, принимающий сообщения для определённого агента.

POST /automation/spaces/<SPACE_ID>/agents/<AGENT_ID>/api-chat/

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

Используйте source_id, session_id и external_message_id, чтобы правильно объединять диалоги и безопасно повторять запросы.

POST /integrations/api-chat/message/

Авторизация

Партнёрские токены остаются на сервере

Передавайте партнёрские токены в заголовке Authorization. Ограничьте каждый токен только необходимыми интеграции разрешениями, а при постоянных исходящих IP-адресах рабочей среды добавьте список разрешённых IP.

Работа с токенами

Значение партнёрского токена показывается только один раз при создании. Храните его в менеджере секретов серверной части и никогда не передавайте браузерным клиентам.

Области разрешений

Предоставляйте только области доступа, необходимые интеграции, например spaces.read, agents.read, cron_jobs.write или области настройки и выполнения API-чата.

Списки разрешённых IP-адресов

Пустой список allowed_ip_cidrs разрешает запросы с любого IP-адреса. В рабочей среде по возможности ограничивайте токены известными исходящими IP-адресами партнёра или диапазонами CIDR.

Минимальный баланс

Для вызовов публичного API на балансе организации с оплатой по мере использования должен быть минимум $1 USD. При недостаточном балансе возвращается код 402, а запрос не обрабатывается.

Заголовок авторизации

Используйте один и тот же заголовок для запросов чтения, записи, настройки и выполнения.

curl -sS "https://clero.so/api/v1/automation/spaces/" \
  -H "Authorization: Bearer <PARTNER_TOKEN>" \
  -H "Accept: application/json"

Ресурсы

Группы конечных точек

Эта карта поможет быстро оценить возможности API. Файлы OpenAPI остаются основным источником точных схем запросов и ответов.

Пространства и подготовка

Создавайте рабочие пространства клиентов, получайте список доступных пространств и устанавливайте одобренные шаблоны агентов.

spaces.read / spaces.write

GET/automation/spaces/

Получить список пространств, доступных партнёрскому токену.

POST/automation/agent-templates/provision-space/

Создать или повторно использовать пространство и установить шаблоны агентов.

Агенты

Найдите существующих агентов в пространстве перед созданием интеграций выполнения.

agents.read

GET/automation/spaces/<SPACE_ID>/agents/

Получить список агентов пространства и общедоступные метаданные их интеграций.

POST/automation/spaces/<SPACE_ID>/agents/<AGENT_ID>/api-chat/

Создать или повторно использовать источник API-чата для существующего агента.

Выполнение API-чата

Отправляйте сообщения в Clero и получайте ответы ассистента после завершения обработки.

api_chat.write

POST/integrations/api-chat/message/

Зарегистрировать входящее сообщение для источника и сессии.

POST/integrations/api-chat/history/

Запрашивать историю сессии и ответы ассистента после указанного курсора сообщения.

Документы и файлы

Загружайте документы или файловые вложения, а затем используйте возвращённые идентификаторы в процессах агентов.

files.write

POST/automation/documents/

Загрузить или создать ресурсы документов для процессов автоматизации.

POST/automation/file-attachments/

Загрузить файловые вложения с помощью multipart-запросов.

Задачи cron

Планируйте повторяющуюся работу выбранного агента и сохраняйте возвращённые идентификаторы задач для поддержки.

cron_jobs.write

POST/automation/partner-cron-jobs/

Создать запланированную задачу автоматизации для существующего агента.

GET/automation/partner-cron-jobs/

Просмотреть запланированные задачи, доступные партнёрскому токену.

Выполнение

Как работает API-чат

API-чат сразу регистрирует входящие сообщения. Ответы ассистента доставляются позже через опрос или настроенные вебхуки, благодаря чему задержка запроса остаётся предсказуемой.

Сообщение принято

Конечная точка сообщений подтверждает регистрацию и возвращает внутренний идентификатор сообщения.

Агент начинает обработку

Режим маршрутизации источника определяет, попадёт ли сообщение во входящие агента или запустит независимый процесс сессии.

Ответы получены

Опрашивайте историю с after_message_id или используйте настроенные вебхуки для получения готовых сообщений ассистента.

Отправка сообщения в API-чат

Используйте source_id вместе с session_id, чтобы сохранять контекст диалога.

curl -sS "https://clero.so/api/v1/integrations/api-chat/message/" \
  -X POST \
  -H "Authorization: Bearer <PARTNER_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "<API_CHAT_SOURCE_ID>",
    "session_id": "customer-123",
    "text": "Can you check the latest booking details?",
    "external_message_id": "msg-123",
    "response_mode": "accepted"
  }'

Примеры

Готовые шаблоны curl

В этих фрагментах намеренно используются значения-заполнители. Не размещайте настоящие партнёрские токены, токены API-чата и идентификаторы клиентов в браузерном коде.

Получить список пространств

Найдите существующие пространства Clero, доступные токену этой организации.

curl -sS "https://clero.so/api/v1/automation/spaces/" \
  -H "Authorization: Bearer <PARTNER_TOKEN>" \
  -H "Accept: application/json"

Получить список агентов пространства

Найдите существующих агентов в выбранном пространстве Clero.

curl -sS "https://clero.so/api/v1/automation/spaces/<SPACE_ID>/agents/" \
  -H "Authorization: Bearer <PARTNER_TOKEN>" \
  -H "Accept: application/json"

Создать или использовать существующий API-чат

Создайте источник API-чата для отправки сообщений существующему агенту.

curl -sS "https://clero.so/api/v1/automation/spaces/<SPACE_ID>/agents/<AGENT_ID>/api-chat/" \
  -X POST \
  -H "Authorization: Bearer <PARTNER_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer API Chat",
    "reply_capable": true,
    "routing_mode": "agent_inbox"
  }'

Подготовить пространство

Создайте или повторно используйте пространство, а затем установите один или несколько одобренных шаблонов агентов.

curl -sS "https://clero.so/api/v1/automation/agent-templates/provision-space/" \
  -X POST \
  -H "Authorization: Bearer <PARTNER_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "external_space_id": "customer-123",
    "space": {
      "name": "Customer workspace",
      "description": "Workspace created by partner backend",
      "is_org_wide": true
    },
    "agents": [
      {
        "template_id": "<TEMPLATE_ID>",
        "name": "Customer agent",
        "auto_create_api_chat": true,
        "api_chat_routing_mode": "agent_inbox"
      }
    ]
  }'

Создать задачу cron

Запланируйте повторяющуюся работу существующего агента.

curl -sS "https://clero.so/api/v1/automation/partner-cron-jobs/" \
  -X POST \
  -H "Authorization: Bearer <PARTNER_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<AGENT_ID>",
    "name": "Daily partner sync",
    "instructions": "Review new documents and summarize open risks.",
    "schedule": {
      "type": "cron",
      "data": {
        "minute": "0",
        "hour": "9",
        "day_of_week": "1-5"
      },
      "timezone": "UTC"
    }
  }'

Надёжность

Повторные запросы, идемпотентность и ограничения

Повторные запросы интеграции должны быть безопасными там, где API предоставляет внешний идентификатор. Сохраняйте идентификаторы Clero из успешных ответов и используйте задержку перед повтором после устранимых ошибок.

Подготовка пространства

external_space_id

При повторных запросах передавайте тот же external_space_id, чтобы использовать существующее пространство клиента.

Сообщения API-чата

external_message_id

Используйте постоянный external_message_id для каждого сообщения источника и сессии. Повторный запрос с тем же идентификатором возвращает существующее сообщение вместо создания дубликата.

Опрос истории

after_message_id

При опросе новых ответов ассистента используйте внутренний message_id, возвращённый API, в качестве курсора.

Ограничения частоты

429 / Retry-After

Учитывайте Retry-After, если он присутствует. В остальных случаях используйте экспоненциальную задержку и не повторяйте неидемпотентные запросы создания.

Минимальный баланс

402 / organization_balance_too_low

Пополните баланс организации перед повторным запросом. Вызовы API при низком балансе отклоняются до обработки сообщений, сессий, файлов или задач.

Создание задачи cron

возвращённый идентификатор задачи cron

Сохраняйте возвращённый идентификатор задачи. Не повторяйте создание задачи cron без проверки, если серверная часть не защищает запрос от дублирования.

Справочник

Основная документация и схемы

Используйте руководство Markdown для людей, файлы llms для ИИ-агентов программирования и OpenAPI для проверки схем или генерации SDK.

Документация Markdown

Понятное человеку руководство по конечным точкам последней версии публичного API.

Индекс документации для ИИ

Компактный индексный файл для агентов, которым нужно быстро найти документацию API.

Полная документация для ИИ

Полный справочник API в виде обычного текста, оптимизированный для ИИ-агентов программирования.

OpenAPI JSON

Машиночитаемая схема для генераторов SDK и валидаторов.

OpenAPI YAML

Схема YAML для просмотра, импорта и локальных инструментов.

Вопросы и ответы

Частые вопросы об интеграции

Практические ответы о рабочих серверных интеграциях, объединении сообщений и обращении с учётными данными.

Как обеспечить идемпотентность?

При создании или повторном использовании пространства с шаблонами агентов передавайте external_space_id. Повторный запрос с тем же external_space_id использует существующее пространство вместо создания ещё одного пространства клиента.

При отправке сообщений API-чата используйте external_message_id. Повторный запрос с тем же external_message_id в той же сессии API-чата возвращает существующее сообщение с created=false.

Создание API-чата для существующего агента можно безопасно повторять. Clero повторно использует автоматически управляемый источник API-чата этого агента вместо создания дубликатов.

Сейчас создание задачи cron не является идемпотентным POST-запросом. Сохраняйте возвращённый идентификатор задачи и не повторяйте запрос без проверки, если серверная часть не защищает его от дублирования.

Нужно ли отправлять сообщения непосредственно в конечную точку агента?

Нет. Для работы с публичным API создайте или повторно используйте источник API-чата агента, а затем отправляйте сообщения в /integrations/api-chat/message/.

Так обмен сообщениями остаётся единообразным для режима входящих, режима процессов, опроса истории, вебхуков и файловых вложений.

Когда использовать agent_inbox, а когда session_workflow?

Используйте agent_inbox, когда агент должен работать как единый обработчик входящих и обрабатывать несколько связанных сообщений в одной ветке.

Используйте session_workflow, когда каждое сообщение API-чата должно запускать независимый процесс через автоматически управляемый триггер.

Какие идентификаторы должна хранить серверная часть?

Храните собственный external_space_id, идентификаторы Clero space_id и agent_id, source_id API-чата, идентификатор задачи cron и внутренний message_id, возвращённый API-чатом.

Сохраняйте external_message_id в собственном журнале запросов, чтобы повторять неудачные сетевые вызовы без создания дубликатов сообщений чата.

Считайте токены API-чата и партнёрские токены серверными секретами. Никогда не раскрывайте их в браузерном коде.

Какие запросы следует повторять?

Повторяйте запросы после сетевых ошибок и ответов 5xx с теми же идентификаторами идемпотентности. Для ответов 429 учитывайте Retry-After, если он присутствует, и используйте экспоненциальную задержку.

Не повторяйте неидемпотентные запросы создания, если серверная часть не использует собственный ключ дедупликации или не хранит результат первого успешного запроса.

Что происходит, если баланс организации меньше $1 USD?

Вызовы публичного API отклоняются с кодом HTTP 402 и кодом ошибки organization_balance_too_low.

Пополните баланс организации перед повторным запросом; не повторяйте запросы с ответом 402 при низком балансе.

Могут ли ИИ-агенты программирования использовать эту документацию?

Да. Для поиска документации используйте /docs/api/latest/llms.txt, для полного текстового руководства — /docs/api/latest/llms-full.txt, а для схем — /docs/api/latest/openapi.json.

На публичной странице и в документации намеренно используется заполнитель PARTNER_TOKEN; авторизованная сессия Clero не требуется.

Что происходит, если allowed_ip_cidrs пуст?

Пустой список разрешённых IP-адресов означает, что токен можно использовать с любого IP. Непустой список ограничивает токен указанными публичными исходящими IP-адресами или диапазонами CIDR.

Для рабочих серверных интеграций настройте allowed_ip_cidrs, если у партнёра есть постоянные исходящие IP-адреса.