#Обновить статус

POST /v1/infra/servers/:id/refresh

Принудительно опрашивает облачного провайдера, получает актуальный статус и IP сервера, и обновляет запись в базе, если что-то изменилось. Полезно, когда статус в платформе расходится с реальностью — например, после провайдерских работ, зависания в provisioning или ручной остановки виртуальной машины через панель провайдера.

#Параметры

Параметр В Тип Обяз. Описание
id path string (UUID) да ID сервера

Тело запроса пустое.

#Примеры

#curl — личный ключ

Terminal 
curl -X POST -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/refresh

#curl — OAuth-приложение

Terminal 
curl -X POST -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/refresh

#JavaScript — личный ключ

javascript 
const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/refresh`,
  { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)
const { data: status } = await res.json()
console.log(`Актуальный статус: ${status}`)

#JavaScript — OAuth-приложение

javascript 
await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/refresh`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)

#Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data string Актуальный статус в верхнем регистре: PROVISIONING, RUNNING, SLEEPING, ERROR
currentState object Снимок состояния — те же поля, что в error.currentState для 422 SERVER_WRONG_STATE: status, blackholeStatus, hasExternalId, lastSeenAt
availableActions string[] Подмножество ['wake','start','reboot','sleep-now','repair','delete'] — действия, которые имеет смысл вызывать в текущем состоянии

Поле data — это строка со статусом для обратной совместимости. Снимок состояния и список действий вынесены в соседние поля currentState и availableActions. Для полного снимка сервера (IP, политика и т. п.) запросите `GET /v1/infra/servers/:id`.

#Пример ответа

JSON 
{
  "success": true,
  "data": "RUNNING",
  "currentState": {
    "status": "RUNNING",
    "blackholeStatus": "CONNECTED",
    "hasExternalId": true,
    "lastSeenAt": null
  },
  "availableActions": ["reboot", "sleep-now", "delete"]
}

#Пример ответа при ошибке

404 — сервер не существует:

JSON 
{
  "success": false,
  "error": {
    "code": "SERVER_NOT_FOUND",
    "message": "Server not found"
  }
}

#Ошибки

HTTP Код Описание
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 INVALID_API_KEY Неверный или просроченный API-ключ
404 SERVER_NOT_FOUND Сервер не существует, удалён или принадлежит другому API-ключу
429 RATE_LIMIT_EXCEEDED Превышен общий лимит запросов платформы
502 PROVIDER_ERROR Облачный провайдер вернул ошибку при опросе виртуальной машины

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

#Известные особенности

  • Может переписать статус в базе. Если провайдер сообщает статус, отличный от текущего в базе (например, stopped у провайдера при running в базе), запись обновляется: running → sleeping, sleeping → running, появляется IP и т. п. Это главный способ «самолечения» записи в error.
  • Подводный камень сравнения: data === 'RUNNING', а не data.status === 'RUNNING' — поле data намеренно сохранено как строка ради обратной совместимости. Снимок состояния и список доступных действий — соседние поля currentState и availableActions. Это отличается от `GET /v1/infra/servers/:id`, где вся информация внутри data.
  • Идемпотентно и безопасно. Частые вызовы не создают записи, не запускают виртуальную машину, не финализируют биллинг. Подходит для ad-hoc сверки. Для циклов опроса готовности лучше подходит `GET /v1/infra/servers/:id` — он даёт полный объект.
  • Не сбивает таймер фонового монитора. Если провайдер вернул тот же статус и IP, что уже в базе, /refresh не обновляет updatedAt — чтобы не сбить таймер внутреннего монитора, который отсчитывает таймауты provisioning (10 минут).

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