Справочник API веб пилота
Сервер и конфигурация
main-enterprise-web слушает только loopback (по умолчанию порт 4452). HTTPS и домен обслуживает обратный прокси. YADRO_WEB_CONFIG указывает на закрытый JSON конфигурации, YADRO_WEB_ASSETS — каталог пяти статических файлов. Конфигурация перечитывается при каждом запросе; секреты нельзя размещать в каталоге сайта.
Конфигурация: origin (точный HTTPS origin), coreUrl (HTTP loopback Двигателя), modelReady (готовность подтверждённого подключения модели), accounts — записи id, label, passwordHash, опциональные staffToken и operatorToken. passwordHash — SHA-256 случайного длинного кода доступа, а не обычного короткого пароля. Это локальные демонстрационные учётные записи, не корпоративный SSO.
Вход и сеансы
Каждый интерфейс имеет самостоятельный префикс /yadro/staff/api/ или /yadro/helm/api/ и отдельную cookie. POST session принимает {login,password}, требует точный Origin, JSON и X-Yadro-Web: 1. Ответ и GET session: {user:{id,label},csrf,modelReady}. Все изменения требуют X-Yadro-CSRF из текущей сессии, JSON и точный Origin. DELETE session с телом {} завершает сеанс.
Сеансы существуют только в памяти: максимум 8 часов, 30 минут бездействия. Перезапуск завершает все сеансы. Cookies: Secure, HttpOnly, SameSite=Strict, Path=/, префикс __Host. Изменение учётной записи, ключей или привязки Двигателя отзывает сеанс. На каждом запросе проверяются действующие права в Двигателе. Браузер не получает bearer-ключей и не выбирает actor/user или адрес Двигателя.
Маршруты Штата
- GET
agents,snapshot?agent_ref=…,history?agent_ref=…,status?agent_ref=…. - GET
poll?cursor=…&wait=…(ожидание максимум 25 секунд) отдаёт только сообщения и статусы печати. Команды компьютера и браузера не передаются. - POST
message:{agent_ref,text,client_message_id,attachments?}. Без готовой модели возвращает 503; повторное сообщение не инициируется веб-шлюзом. - POST
interrupt:{agent_ref}. - POST
ack:{command_ids:[…]}— только сообщения, ранее выданные этой сессии.
Маршруты Штурвала
- GET
agents,access,agent-state?agent_id=…. - POST
agent-changes/prepare:{agentId,expectedRevision,reason,change}, гдеchange—{kind:"settings.update",patch:{name?,description?,language?}}. - POST
agent-changes/commit:{operationId,digest}— только предложение, подготовленное в текущей сессии. Двигатель дополнительно проверяет владельца, ревизию, срок и подтверждение. - GET
agent-changes/<operationId>читает результат собственного предложения. В случае неопределённого ответа на запись необходимо читать статус; веб-шлюз автоматически не повторяет изменение.
Ограничения транспорта
Другие маршруты, поля и произвольные адреса запрещены. Вход и ответ ограничены 4 МиБ; параллельные API-запросы, входы, число сессий и предложений ограничены. Upstream timeout — 35 секунд с ограничением и заголовков, и тела; перенаправления не выполняются. Ответы не кэшируются; статические файлы разрешены точным списком, CSP не разрешает inline-скрипты и встраивание в чужие страницы.