Последние операции сервера

GET /v1/infra/servers/:id/operations

Возвращает последние операции на сервере от текущего API-ключа, от новых к старым. Видов операций два — выкладки POST /deploy и команды POST /exec, и каждая строка называет свой вид в поле kind. По умолчанию список отдаёт только выкладки: ручка появилась раньше команд, и без параметра возвращается тот же набор строк, что и прежде. Сами строки при этом дополнительно несут поле kind. Команды показывает kind=exec, смешанную ленту — kind=all. Это канал восстановления, когда ответ потерян раньше, чем клиент успел получить operationId — в частности, при обрыве связи во время сборки galaxy-приложения или при обрыве ожидания длительной команды.

Ручка только читает общую запись исхода: она не будит сервер, не чинит туннель и не снимает mutex. Право на сервер совпадает с правом на deploy, но строки дополнительно фильтруются по точному API-ключу, который начал операцию. Поэтому связанный с приложением ключ может читать только собственные запуски, а id общего galaxy-хоста не даёт доступа к запускам его приложений. Владелец может сверить свои операции после мягкого удаления сервера.

Параметры

Пример

curl -H "X-Api-Key: YOUR_API_KEY" \
  'https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/operations?limit=5'

{
  "success": true,
  "data": {
    "operations": [
      {
        "operationId": "clz9k2m4x0001qw8h3f7d2n5p",
        "kind": "deploy",
        "serverId": "8f14e45f-ceea-467a-9c8d-2f1c5a6b7e30",
        "status": "running",
        "outcomeAvailable": true,
        "step": "build",
        "startedAt": "2026-08-26T09:14:22.117Z",
        "finishedAt": null,
        "error": null
      }
    ]
  }
}

Пустое значение параметра — это переданное значение, а не опущенный параметр. ?kind= и ?limit= рождаются из шаблона с незаполненной переменной, то есть сузить выдачу хотели, но не сумели. Такой вызов получает отказ, а не молчаливое умолчание: подставить умолчание значило бы отдать ленту, за которой клиент не приходил. Умолчания kind=deploy и limit=5 действуют только тогда, когда ключа в строке запроса нет вовсе.

Поля операции

У строк kind: "exec" судите по паре exitCode + status, а не по одному полю. Число приходит только у succeeded и означает, что команда отработала до конца. Само по себе null не означает «исход не доказан»: у succeeded оно означает, что команда отработала, а кода агент не назвал, — повторять её не нужно; у failed — что она не запускалась и повтор безопасен; у running — что она ещё идёт; и только у unknown не доказано ничего. Подробный разбор статусов — GET /v1/infra/operations/:operationId.

Терминальный исход хранится 7 суток. После этого строка некоторое время остаётся в списке с outcomeAvailable: false, но её статус, шаг и ошибка больше не раскрываются. unknown — устойчивый терминальный ответ, когда платформа не может доказать удалённый исход, например после GATEWAY_UNREACHABLE; просроченная операция, оставшаяся в running, также отображается как unknown.

Безопасное восстановление после обрыва

1. Не повторяйте выкладку или изменяющую команду вслепую. Найдите свежую операцию этого ключа в списке. Ищете команду — передайте kind=exec: без параметра список показывает только выкладки.
2. Пока она running, ждите и опрашивайте список или адресную ручку раз в несколько секунд.
3. При succeeded или failed используйте подтверждённый исход. При unknown либо отсутствии записи сверьте GET /v1/infra/servers/:id и логи.
4. Если следующий запрос подтвердил EXEC_BUSY, смотрите на error.hint.holder в этом же ответе 409: он называет операцию, которая держит замок, независимо от того, каким ключом она запущена. Держатель есть — значит операция идёт: ждите, а не освобождайте замок силой. По списку операций этот вопрос не решается: список показывает только запуски вашего ключа, поэтому операция, начатая другим ключом того же портала, в нём отсутствует, и пустой список не доказывает, что сервер свободен. Держателя нет — это НЕ зеркальное доказательство простоя: чтение держателя fail-open, поэтому «держателя нет» приходит и тогда, когда прочитать его не удалось. Отсутствие даёт право на обычный повтор после Retry-After и на гардированный POST /v1/infra/servers/:id/unstick — он на живой операции без force отвечает 409. Независимое подтверждение простоя — состоянием сервера (GET /v1/infra/servers/:id) и логами — нужно ОБОИМ шагам: и /unstick, чей разрыв туннеля убивает всё, что выполняет агент, и тем более безусловному DELETE /lock после него. Дальше учитывайте вид сервера. Для STANDALONE можно вызвать POST /v1/infra/servers/:id/unstick и снова выполнить read-only проверки. У GALAXY_APP exec-канал принадлежит общему хосту: tenant-вызов unstick не поддерживается; подождите 30–60 секунд, а при устойчивом EXEC_BUSY обратитесь в поддержку. После любого recovery снова сверьте список, состояние и логи до повторной выкладки.

Ответ standalone-deploy с транспортной причиной GATEWAY_UNREACHABLE, DEPLOY_CONNECTION_TERMINATED, DEPLOY_TIMEOUT или DEPLOY_TUNNEL_STALE, а также post-drop ответы Galaxy GALAXY_DEPLOY_INTERRUPTED и GALAXY_HOST_UNREACHABLE, содержат эту read-first последовательность в error.hint. У Galaxy такой ответ несёт error.retryable: false: сам по себе обрыв не доказывает ни успех, ни провал операции. Слот, контейнер и /data при неизвестном исходе сохранены — не удаляйте и не пересоздавайте приложение.

Ошибки

Полный список общих ошибок API — Ошибки.

Смотрите также

• Исход по идентификатору
• Выложить приложение
• Логи приложения
• Лента событий сервера