Клиент и сервер
Сервер получает сообщение клиента и отправляет POST /v1/turns. Bearer-ключ не передаётся в браузер.
Octo API · HTTP /v1
Интеграция
с Octo API
Сервер приложения отправляет ход в пространство через POST /v1/turns. Ответ и файлы доступны по идентификатору хода; агент может вызывать разрешённые инструменты.
Схема взаимодействия
Клиент обращается к приложению. Сервер приложения вызывает Octo API; агент использует доступные внешние и внутренние API через инструменты.
Ход агента
В ходе работы агент может вызывать инструменты, разрешённые конфигурацией пространства.
Ответ и файлы
Приложение получает result и список files при завершении хода.
Состав API
Ход, пространство и инструменты
Пространство
POST /v1/spaces создаёт пространство. Манифест, секреты, инструменты и политика моделей настраиваются отдельными запросами.
Ход
POST /v1/turns принимает текст, пространство и при необходимости вложения. Результат читается по turn_id.
Приложение самостоятельно реализует интерфейс, авторизацию клиентов и проверку операций во внутренних API.
Запрос и ответ
Запрос авторизуется Bearer-ключом. POST /v1/turns возвращает 202 и turn_id; состояние и результат доступны через GET /v1/turns/{turn_id} или вебхук.
01 · ЗапросPOST /v1/turns
POST https://dash.octomatica.ru/v1/turns
Authorization: Bearer octo_live_…
Content-Type: application/json
Idempotency-Key: <uuid>
{
"space": "<space_id>",
"end_user_ref": "customer-42",
"text": "Подготовь отчёт по заказу",
"file_ids": ["<file_id>"]
}02 · ОтветGET /v1/turns/{turn_id}
202 {"turn_id":"<turn_id>","state":"queued"}
GET /v1/turns/<turn_id>
{
"state": "done",
"result": "Отчёт готов",
"files": [
{"file_id":"<file_id>",
"name":"report.pdf",
"source":"agent",
"url":"/v1/files/<file_id>"}
],
"energy_used": <число>
}Текст задачи, ответ и идентификаторы условные; названия полей соответствуют справочнику API.
Файлы
POST /v1/spaces/{slug}/files принимает multipart-поле file. Передайте file_id в file_ids; созданные агентом файлы скачиваются через GET /v1/files/{file_id} с Bearer-ключом.
Ход и доставка
queued → running → done, failed или cancelled. Опросите GET /v1/turns/{turn_id} либо получите подписанное событие вебхука. Текстовый ответ в result.
Справочник описывает опрос и вебхуки для получения состояния и результата; отдельный потоковый endpoint ответа в нём не указан.
Пространства и память
Связь клиента и пространства
POST /v1/spaces возвращает space_id. Приложение хранит соответствие своего клиента и пространства и указывает space в запросах ходов.
Создание пространства
POST /v1/spacesс необязательным полемtitleсоздаёт отдельное API-пространство и возвращаетspace_id.Идентификатор пользователя
end_user_refсодержит идентификатор клиента приложения. Он используется для группировки расхода энергии и лимитов; регистрация клиента в Octo не требуется.Продолжение разговора
Повторно используйте идентификатор пространства для следующих ходов. Сессия может возобновляться; при смене сессии механизм dream консолидирует её в память.
Сессия и память пространства
Состояние сессии и последняя консолидация памяти доступны через политику пространства. При принудительном переключении модели сессия завершается с сохранением памяти.
Сессия
Текущий запуск
В model_state.session доступны resumable и число ходов turns.
Контекст
Размер сессии
model_state.context содержит долю использованного порога консолидации.
Dream
Смена сессии
При консолидации сессии сохраняется память. В model_state доступно поле last_dream_at.
Политика модели
Применение изменений
switch: soft ожидает следующую консолидацию, switch: force выполняет её перед следующим ходом.
Поля состояния модели описаны в разделе Routing policies справочника /v1.
Конфигурация пространства
Манифест содержит инструкции агенту. Секреты, разрешённые инструменты и политика моделей настраиваются отдельными методами.
01 · Создать
Пространство
POST /v1/spaces с {"title":"Support"} возвращает space_id.
02 · Настроить
Манифест
PUT /v1/spaces/{slug}/manifest с полем manifest задаёт инструкции агенту.
03 · Подключить
MCP и секреты
PUT /v1/spaces/{slug}/tools задаёт allowlist и MCP-серверы. PUT /v1/spaces/{slug}/secrets сохраняет именованные значения.
04 · Маршрутизировать
Политика моделей
GET /v1/models возвращает каталог и настройки платформы. PUT /v1/spaces/{slug}/policy задаёт override для orchestration.
MCP · инструменты приложения
Конфигурация MCP-инструментов
Манифест задаёт условия вызова инструментов. MCP-сервер предоставляет операции приложения; список allow ограничивает встроенные инструменты.
КонфигурацияPUT /v1/spaces/{slug}/tools
{
"allow": ["web", "files"],
"mcp_servers": [
{
"name": "my-app",
"url": "https://mcp.example.com",
"headers": {"Authorization": "Bearer …"}
}
]
}Типизированный инструмент
Определите вывод как инструмент MCP или REST-действие с вашей схемой. Агент вызывает его; ваш сервер проверяет поля и возвращает ошибку для корректировки. Не извлекайте контракт из свободного текста ответа.
Разрешённые возможности
allow ограничивает встроенные инструменты. Секреты хранятся на стороне пространства; права во внутренних API остаются под вашим контролем.
Личное пространство Commander не управляется через API. Для приложения создайте отдельное API-пространство; MCP-серверы родительского пространства не наследуются tenant-пространствами.
Учёт и ограничения
Вызовы агента, маршрутизация моделей, файлы, лимиты и расход энергии доступны через API пространства и аккаунта.
Единый баланс
Расход идёт с аккаунта владельца. GET /v1/usage разбивает энергию по клиентам, пространствам и ключам.
Политика моделей
Политика выбирает модель для разных видов работы; у пространства есть override для orchestration.
Лимиты и доступ
Область действия ключа, дневной предел, лимит клиента и список доступных инструментов.
Файлы через API
Вложения загружаются в пространство; файлы результата доступны по GET /v1/files/{file_id} с Bearer-ключом.
Документация
Справочник Octo API
Полные схемы запросов и ответов, ошибки и ограничения методов приведены в справочнике /v1.