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

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

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

## Параметры

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

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

## Примеры

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

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

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

```bash
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`](/docs/infra/servers/get).

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

```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-ключ |
| 403 | `INFRA_FORBIDDEN_FOR_COWORK_KEY` | Вызов сделан ключом Cowork/Code — такой ключ работает только с данными, изменяющие операции ему закрыты. Что делать — [Проектный ключ для деплоя](/docs/cowork/deploy-key) |
| 403 | `SERVER_ROLE_FORBIDDEN` | Вы состоите в команде разработки этого сервера с ролью «Разработчик», а операция открыта роли «Администратор». В `error.hint` придут ваша роль, требуемый порог и перечень открытых вам вызовов. Разбор ролей — [Список серверов](/docs/infra/servers/list) |
| 404 | `SERVER_NOT_FOUND` | Сервер не существует, удалён или привязан к другому API-ключу, и вы не состоите в его команде разработки |
| 429 | `RATE_LIMITED` | Превышен общий лимит запросов платформы |
| 502 | `PROVIDER_ERROR` | Облачный провайдер вернул ошибку при опросе виртуальной машины |

Полный список общих ошибок API — [Ошибки](/docs/errors).

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

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

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

- [Получить сервер](/docs/infra/servers/get)
- [Восстановить туннель](./repair.md)
- [Запустить сервер](./start.md)