Octo API · HTTP /v1 · для инженеров

Octo API
в вашем приложении

HTTP-контракт для backend: ходы, пространства, MCP, память, маршрутизация и биллинг. Справочник: dash.octomatica.ru/v1/docs.

Схема одного хода

вызов ответ. Метод и поле в подписи взяты из справочника /v1; подписи без них описывают роль шага.

Агент как сервис или API модели

Что остаётся на вашей стороне в каждом варианте.

Задача	API модели	Octo API
Единица вызова	Запрос completion, синхронный ответ или поток токенов	Ход в пространстве: `202` и `turn_id`, выполнение асинхронно
Цикл инструментов	Ваш код: разбор вызовов инструментов, выполнение, повторный запрос	Цикл ведёт агент; вы публикуете операции через MCP
Состояние	История передаётся в каждом запросе, обрезка и суммаризация на вас	Сессия и память живут в пространстве
Модель и провайдер	Зашиты в код; отказ провайдера обрабатываете вы	Политика пространства с резервными кандидатами
Структурированный вывод	JSON mode и валидация текста ответа	Вызов вашего инструмента с вашей схемой ввода
Файлы	Кодирование во входе, отдельный файловый API провайдера	Хранилище пространства, файлы результата в `files[]`
Учёт	Счёт каждого провайдера в токенах	Энергия с одного баланса, разбивка по `end_user_ref`

Запрос и ответ

Base URL: https://dash.octomatica.ru/v1
Авторизация: Authorization: Bearer octo_live_… на каждом запросе; ключ только на сервере
Ошибки: {"error":{code, message, details, trace_id}} и заголовок X-Trace-Id
Схема: /api/openapi.json

ЗапросPOST /v1/turns

POST /v1/turns
Authorization: Bearer octo_live_…
Content-Type: application/json
Idempotency-Key: 6f1c…-uuid

{
  "space": "api-1a2b3c4d5e6f",
  "text": "Сверь заказ 1042 со складом",
  "end_user_ref": "customer-42",
  "file_ids": ["9f3c…"],
  "metadata": {"order": 1042},
  "webhook_url": "https://app.example.com/octo"
}

→ 202 {"turn_id": "turn_ab12…",
       "state": "queued", "trace_id": "…"}
Location: /v1/turns/turn_ab12…

ОтветGET /v1/turns/{turn_id}

{
  "turn_id": "turn_ab12…",
  "state": "done",
  "current_activity": "…",
  "result": "Расхождение в 2 позициях…",
  "result_truncated": false,
  "error": null,
  "files": [{"file_id": "9f3c…",
    "name": "сверка.xlsx", "source": "agent",
    "url": "/v1/files/9f3c…"}],
  "usage": {"provider": "…", "model": "…",
    "total_tokens": …, "turn_energy": …,
    "linked_energy": …, "linked_calls": …},
  "energy_used": 0.123,
  "metadata": {"order": 1042}
}

queuedturn.queued
runningturn.running
doneturn.completed
failedturn.failed · error
cancelledturn.cancelled

Механизм	Контракт
Опрос	`GET /v1/turns/{turn_id}` раз в 1-2 с, backoff до 10 с. Клиенту ждать не меньше 180 с; ход без прогресса 2 часа закрывается как `failed` (`stale_reaped`) без списания.
Вебхук	`POST /v1/webhooks` `{url, events?, space?, secret?}`, секрет показывается один раз; до 10 на ключ. Разово: `webhook_url` в самом ходе. Только https на публичный адрес.
Подпись	`X-OOIH-Signature: t=<unix>,v1=<hex>`, где `v1 = HMAC-SHA256(secret, "<t>.<raw body>")`; отклоняйте `t` старше 5 минут. Дедупликация по `id` события.
Доставка	Ответ 2xx за 10 с. Повторы через 1 мин, 5 мин, 30 мин, 2 ч, 12 ч; затем `redeliver`. `410` отключает вебхук. Упавший endpoint не блокирует ход.
Идемпотентность	Тот же `Idempotency-Key` с тем же `space` и `text` возвращает исходный ход; с другими: `409 IDEMPOTENCY_CONFLICT`.
Файлы на вход	`POST /v1/spaces/{slug}/files`, multipart-поле `file`, до 200 МБ; затем до 10 `file_ids` на ход.
Файлы на выход	`files[].source`: `upload` или `agent`. Скачивание `GET /v1/files/{file_id}` с Bearer; имя в UTF-8 в `filename*`.
Пределы	`metadata` 8 КБ, `result` 1 МБ (дальше `result_truncated`), списки до 200 элементов.

В публичном контракте /v1 нет потокового ответа и отдельных эндпоинтов памяти (wiki, recall): результат приходит целиком по опросу или вебхуку.

Чат-интерфейсы

Во всех каналах работает один агент; канал определяет только доставку сообщений. Каждый чат становится отдельным пространством.

Канал	Где работает
Telegram	личные чаты и группы с @octomatica_bot
Веб-чат	кабинет dash.octomatica.ru; приглашения участников на 7 дней
Bitrix24	чат-бот в чатах портала
Яндекс Мессенджер	бот в чатах организации Яндекс 360
API	ваш собственный интерфейс

Свой чат: Храните space_id рядом с разговором; сообщение пользователя равно одному ходу, Idempotency-Key равен id сообщения.
Индикатор: current_activity из опроса показывает, что агент делает сейчас.
Стоп: POST /v1/turns/{turn_id}/cancel; после терминального состояния 409 ALREADY_TERMINAL.

Пространства: создание и настройка

Пространство = ядро агента + канал + инструменты + манифест + политика маршрутизации. Память и файлы одного пространства недоступны другому.

Метод	Тело	Что задаёт
`POST /v1/spaces`	`{title?}`	`201 {space_id: "api-<12 hex>", origin: "api"}`. Без переопределения пространство маршрутизируется политикой платформы.
`PUT /v1/spaces/{slug}/manifest`	`{manifest}`	Постоянные инструкции: роль агента, когда вызывать какие инструменты, каким вызовом сдавать результат.
`PUT /v1/spaces/{slug}/secrets`	`{secrets: {NAME: value}}`	Шифруются, не читаются обратно, доступны инструментам как переменные окружения. Имя `[A-Z_][A-Z0-9_]`; `OOIH_`, `OPENAI_`, `ANTHROPIC_`, `GEMINI_`, `OPENROUTER_` отклоняются (`RESERVED_SECRET_NAME`).
`PUT \| PATCH /v1/spaces/{slug}/tools`	`{allow, mcp_servers}`	Встроенные возможности и ваши MCP-серверы (раздел MCP). `PATCH` меняет только переданные поля.
`PUT /v1/spaces/{slug}/policy`	`{orchestration, switch?}`	Модель пространства (раздел Политики).
`GET /v1/spaces`		Доступные ключу пространства с флагами `has_manifest`, `has_secret`, `has_tools`.

Личное пространство Commander через API не управляется: для приложения создайте отдельное API-пространство.

MCP в вашем приложении

Ваши внутренние операции агент вызывает через ваш MCP-сервер. Права пользователя на операцию проверяет ваш сервер.

КонфигурацияPUT /v1/spaces/{slug}/tools

{
  "allow": ["web", "files", "code"],
  "mcp_servers": [{
    "name": "shop",
    "url": "https://mcp.shop.example.com",
    "headers": {"Authorization": "Bearer …"}
  }]
}

Результат

Вызов вместо разбора текста

Опишите вывод как инструмент с входной схемой, например submit_report(title, sections), и потребуйте в манифесте сдавать результат им. Ошибка валидации уходит агенту, он повторяет вызов с исправленными аргументами.

Встроенные

`allow`

null снимает ограничение. Каталог: GET /v1/tools/catalog. Платные: image, media, seo, lizard; с проверкой баланса: higgsfield, elevenlabs.

Доступ

Заголовки и секреты

headers авторизуют Octo на вашем MCP-сервере. Ключи ваших сервисов для встроенного кода кладите в секреты пространства, а не в манифест.

Память

Контекст не растёт бесконечно: в следующую сессию переходит то, что консолидация записала в память пространства.

Этап	Что происходит	Видно через API
Сессия	Ходы продолжают одну сессию агента, пока контекст ниже порога консолидации.	`model_state.session`: `resumable`, `turns`, `age_sec`; `model_state.context`: `used_tokens`, `threshold_tokens`, `used_pct`
Dream	Консолидация идёт на копии сессии той же моделью. Устойчивые факты пишутся в память пространства со ссылкой на источник: сессия и диапазон байтов.	`last_dream_at`, `estimate.turns_until_dream`
Новая сессия	Старая запечатывается. Новая стартует с базовых инструкций, индекса памяти, списка запечатанных сессий и короткого хвоста разговора.	`session.id` меняется
Первоисточник	По ссылке из памяти агент читает нужный фрагмент запечатанной сессии, не загружая историю целиком.	внутри агента
Явная запись	«Запомни» пишется во входящие. Dream сверяет: дубликат не меняет память, исправление заменяет факт, противоречие помечается к уточнению.	внутри агента
Параллельные ходы	Смена сессии сериализована на пространство; конкурирующий ход присоединяется к новой сессии.	внутри агента

Маршрутизация и политики

Модель выбирается на старте сессии по политике для каждого вида работы и сохраняется, пока сессия продолжается.

Маршрутизация по провайдерам

Вид работы	Кто настраивает
`orchestration`	ход агента; пространство может переопределить
`coding-plan`, `coding-design`, `coding-exec`	оператор платформы (`403 OPERATOR_ONLY`)
`thinking`	фиксированная эскалация платформы
без вида	по умолчанию пространства

Кандидаты: GET /v1/models отдаёт каталог и fleet_default: вид работы → список моделей, первый предпочтителен. Движки: claude-code, codex, opencode.
Резерв: Модель пропускается с причиной INELIGIBLE, OUT_OF_BUDGET, AT_CAPACITY или UNHEALTHY, запускается следующий кандидат.
На один ход: "model": "opus55" в POST /v1/turns; итог в model_override. Смена движка закрывает сессию через dream.
Факт: usage.provider и usage.model в ответе хода.

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

ПереопределениеPUT /v1/spaces/{slug}/policy

{"orchestration": "<id из GET /v1/models>",
 "switch": "force"}

DELETE /v1/spaces/{slug}/policy/orchestration
→ {"cleared": true, "source": "fleet_default"}

`switch`	Когда применяется
`soft`	по умолчанию: на следующем dream, кэш сессии сохраняется; без dream 6 часов, на следующем ходе
`force`	перед следующим ходом: dream и перезапуск сессии
`cancel`	снимает ожидающее переключение

Состояние: GET /v1/spaces/{slug}/policy: по каждому виду configured, resolved, source, reasons, плюс model_state с pending, forced, capacity.
Отказы: 400 UNKNOWN_MODEL, 403 INELIGIBLE. Премиум-модель сверх баланса сохраняется с warning.code: OUT_OF_BUDGET, до пополнения работает резерв.
Ключ: Область доступа: own (только созданные ключом пространства, по умолчанию), space (одно), account (все API-пространства аккаунта).

Единый биллинг

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

Поле или метод	Смысл
`energy_used`	фактическое списание за весь ход со всеми множителями
`usage.turn_energy`	собственный запуск агента
`usage.linked_energy`, `linked_calls`	субагенты, инструменты, память, вызванные ходом
`GET /v1/usage`	`group_by=end_user\|space\|key`, `scope=account\|key` → `breakdown[{key, energy_used, turns}]` для перевыставления счетов своим пользователям

Ограничение	Ответ
баланс владельца исчерпан	`402 INSUFFICIENT_CREDITS`; повтор без пополнения не поможет
дневной лимит ключа: 50 энергии по умолчанию, до 10 000, сброс 00:00 UTC	`429 QUOTA_EXCEEDED`, `daily_cap`, `Retry-After`
месячный лимит ключа	`429`, `monthly_cap`, `Retry-After`
лимит пользователя: `PATCH /v1/spaces/{slug}/end-users/{ref}` `{total_limit_energy}`	`429`, `end_user_limit`, без `Retry-After`
оконные лимиты из кабинета	`429`, `usage_window`, `Retry-After`

Octo APIв вашем приложении