API

У платформы три API. Все три отвечают JSON, адреса — на домене вашей организации в облаке HolyCode (для агента — на его машине).

Как входить

Куда	Чем
Персонал	ключ доступа (PAT) в заголовке Authorization: Bearer <ключ>; права read или read, write задаются при выпуске в разделе API Keys
Рабочее пространство	сессия человека или токен агента; токены агентов хранятся хэшами и отзываются в администрировании
Агент	служебный ключ панели агента на его машине; наружу агент ничего не слушает

Ключ read получает 403 на любой запрос записи. Сервисные интеграции получают свой ключ, общих секретов между организациями нет.

Персонал (workforce)

Группы эндпоинтов, с которыми работают скрипты и внешние системы:

• Роли и команды — каталог ролей по командам, версии, выпуск, снятие, возврат версии.
• Сценарии — реестр сценариев (hpl/v1), версии, выпуск; см. формат сценариев.
• Задания — постановка задания по сценарию, статус, чекпоинты, транскрипт прогона, бюджет задания.
• Одобрения — очередь одобрений, решение по карточке (сообщение наружу, слияние данных, коммерческие условия, повышенный риск, найм, бюджет).
• Узлы — список агентов организации, статус, версия, руководитель, одноразовые ключи регистрации и их отзыв, пауза и включение агента, месячный бюджет.
• Пакет компании — выгрузка и загрузка ролей и сценариев файлом; см. пакет компании.
• Ключи доступа — выпуск, список, отзыв.

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

Рабочее пространство

• Комнаты и сообщения — комнаты, треды, упоминания; агенты пишут своими токенами.
• Задачи — доска, назначение человеку или агенту, чекпоинты и результат в задаче.
• Проекты и сборки — проекты, прогоны сборщиков, окружения, одобрение выката, входящие вебхуки сборок с подписью.
• Организация — люди, приглашения, роли людей, токены агентов.

Агент

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

Контракты

Замороженные схемы, по которым проверяются данные:

• hpl/v1 — структура сценария: декларативный граф заданий и шагов, роли по версиям, разрешённые коннекторы, у каждого шага таймаут, повторы, идемпотентность, ручная проверка, класс бюджета, побочный эффект, обратимость, компенсация и артефакты. Опубликованный сценарий неизменяем и адресуется хешем SHA-256.
• workforce-runtime/v1 — граница между персоналом и агентом: выданные пакеты исполнения, чекпоинты, доказательства и происхождение результата.
• oggo-daenerys/v1 — интеграция с платформой заказов OGGO, для организаций с этим коннектором.

Публичные OpenAPI-описания появятся вместе с самозаписью в облако; до этого схемы выдаём по запросу.