Перейти к содержанию
OctomaticaДокументация

Разработчикам

API: обзор

Встройте агента в своё приложение через HTTP API: ключи и их область, end_user_ref, жизненный цикл запроса, вебхуки, оплата и первый запрос за минуту.

Обновлено:

На этой странице
  1. Что даёт API
  2. Ключи и доступ
  3. Первый запрос
  4. Жизненный цикл и вебхуки
  5. Оплата и лимиты

Что даёт API

API позволяет вашему серверу создавать изолированные пространства, настраивать их (инструкция, секреты, инструменты, MCP-серверы), отправлять запросы с файлами и получать ответы и созданные агентом файлы. Оплата идёт с вашего аккаунта, а расход разбит по вашим клиентам.

Ключи и доступ

  • Базовый адрес: https://dash.octomatica.ru/v1
  • Каждый запрос: заголовок Authorization: Bearer octo_live_…
  • Ключи создаются в кабинете: Интеграции → API-ключи. Ключ показывается один раз.
  • API предназначен для вызовов с сервера: не встраивайте ключ в браузер или мобильное приложение.
Область ключаЧем может управлять
Только созданные им пространства (рекомендуется)Пространства, созданные через POST /v1/spaces этим ключом
Одно пространствоОдно пространство, которое вы указали
Все мои пространстваВсе пространства аккаунта

end_user_ref: ваш собственный идентификатор клиента. Он не создаёт аккаунт у нас, но по нему считается расход и задаются лимиты на клиента.

Первый запрос

Создайте пространство, отправьте запрос с Idempotency-Key и опрашивайте его до конечного состояния. Примеры на Python и TypeScript: в справочнике.

bash
BASE=https://dash.octomatica.ru/v1
KEY=octo_live_xxxxxxxxxxxxxxxx

SLUG=$(curl -s -X POST $BASE/spaces -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' -d '{"title":"My first space"}' | jq -r .space_id)

TURN=$(curl -s -X POST $BASE/turns -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' -H "Idempotency-Key: $(uuidgen)" \
  -d '{"space":"'"$SLUG"'","end_user_ref":"customer-42","text":"Hello"}' | jq -r .turn_id)

curl -s $BASE/turns/$TURN -H "Authorization: Bearer $KEY" | jq '{state, result}'

Жизненный цикл и вебхуки

  • Запрос асинхронный: queued → running → done | failed | cancelled.
  • Вместо опроса зарегистрируйте вебхук: платформа пришлёт подписанное событие на каждый переход. Вебхуки
  • Результат запроса: текст для человека. Структурированные данные агент передаёт через ваши инструменты (MCP или REST). Инструменты и MCP

Оплата и лимиты

  • Каждый запрос списывается с аккаунта владельца ключа; стоимость в поле billed_cost_usd.
  • 402 INSUFFICIENT_CREDITS: баланс исчерпан, нужно пополнение.
  • 429 QUOTA_EXCEEDED: дневной лимит ключа, лимит клиента или оконный лимит; соблюдайте Retry-After.
  • Ограничения частоты запросов нет: расход ограничивают баланс и лимиты.

Все коды ошибок · Ограничения · Оплата