## Обновить имя и описание сервера

`PATCH /v1/infra/servers/:id`

Меняет отображаемое имя сервера и его описание — два текстовых поля, которые видит человек в личном кабинете и в карточке приложения в каталоге Битрикс24. Технический идентификатор сервера задаётся при создании и этим эндпоинтом не меняется.

## Параметры

| Параметр | В | Тип | Обяз. | Описание |
|----------|---|-----|:-----:|----------|
| `id` | path | string (UUID) | да | ID сервера из [`POST /v1/infra/servers`](./create.md) или [`GET /v1/infra/servers`](./list.md) |

## Поля запроса (body)

| Поле | Тип | Обяз. | Описание |
|------|-----|:-----:|----------|
| `displayName` | string | да | Отображаемое имя на любом языке: русский, китайский, эмодзи. 2–100 символов, без управляющих байтов, обрезается по краям. Передавайте его в каждом вызове, в том числе когда меняете только описание |
| `description` | string \| null | нет | Описание приложения для карточки каталога Битрикс24, до 500 символов. Переносы строк и табуляции разрешены, прочие управляющие байты запрещены. Значение обрезается по краям, поэтому строка из одних пробелов очищает описание. Пустая строка и `null` тоже очищают описание. Если поле не передано, прежнее описание сохраняется |

Других полей тело не принимает — например, технический идентификатор `name` в теле вернёт `400`.

## Примеры

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

```bash
curl -X PATCH https://vibecode.bitrix24.tech/v1/infra/servers/6b23309f-7d0b-4cc3-a8f0-24183d48770e \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Помощник по сделкам",
    "description": "Бот для CRM. Отвечает на вопросы по сделкам."
  }'
```

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

```bash
curl -X PATCH https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Помощник по сделкам",
    "description": "Бот для CRM. Отвечает на вопросы по сделкам."
  }'
```

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

```javascript
const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}`,
  {
    method: 'PATCH',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      displayName: 'Помощник по сделкам',
      description: 'Бот для CRM. Отвечает на вопросы по сделкам.',
    }),
  }
)
const { data } = await res.json()
console.log(data.displayName, data.description)
```

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

```javascript
const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}`,
  {
    method: 'PATCH',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      displayName: 'Помощник по сделкам',
      description: 'Бот для CRM. Отвечает на вопросы по сделкам.',
    }),
  }
)
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | Всегда `true` при успехе |
| `data.id` | string (UUID) | ID сервера |
| `data.name` | string | Технический идентификатор сервера. Значение неизменяемо и приходит для сверки |
| `data.displayName` | string | Отображаемое имя после правки |
| `data.description` | string \| null | Описание после правки. Ключ приходит, только если поле `description` было в запросе. Вызов без него описание не трогает и в ответе не показывает. Полное состояние сервера — [`GET /v1/infra/servers/:id`](./get.md) |

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

```json
{
  "success": true,
  "data": {
    "id": "6b23309f-7d0b-4cc3-a8f0-24183d48770e",
    "name": "my-crm-app",
    "displayName": "Помощник по сделкам",
    "description": "Бот для CRM. Отвечает на вопросы по сделкам."
  }
}
```

Вызов без поля `description` — прежнее описание сохраняется, ключа в ответе нет:

```json
{
  "success": true,
  "data": {
    "id": "6b23309f-7d0b-4cc3-a8f0-24183d48770e",
    "name": "my-crm-app",
    "displayName": "Помощник по сделкам"
  }
}
```

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

404 — сервер с таким ID не существует или принадлежит другому API-ключу:

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

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 400 | `INVALID_BODY` | Нарушена валидация тела: не передан `displayName`, имя короче 2 или длиннее 100 символов, описание длиннее 500 символов, в теле есть неизвестное поле. В `message` приходит текст первой сработавшей проверки, имя поля в нём есть не всегда |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `INVALID_API_KEY` | Неверный или просроченный API-ключ |
| 403 | `INFRA_FORBIDDEN_FOR_COWORK_KEY` | Вызов сделан ключом Cowork. Такой ключ работает только с данными и не управляет серверами. В `error.details.requiredAction` приходит порядок получения ключа с правами на деплой |
| 404 | `SERVER_NOT_FOUND` | Сервер не найден или принадлежит другому API-ключу. У `GET` и `DELETE` того же ресурса код другой — `NOT_FOUND` |
| 404 | `NOT_FOUND` | Сервер принадлежит порталу Битрикс24, который платформа пометила удалённым. Операции над такими серверами закрыты |
| 429 | `RATE_LIMITED` | Превышен общий лимит запросов платформы |

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

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

- **Правка уходит в карточку приложения в каталоге Битрикс24.** Отображаемое имя передаётся как название карточки, описание — как её описание. Синхронизацию ведёт фоновый процесс, поэтому в каталоге значение появляется не в момент ответа. Карточка обновляется только у приложения, которое уже опубликовано в каталоге.
- **Вызов, который ничего не изменил, остаётся без последствий.** Если переданные значения совпадают с текущими, платформа не пишет в базу, не заносит запись в журнал аудита и не ставит синхронизацию с каталогом. Ответ при этом обычный, `200` — по нему нельзя судить, изменилась ли запись.
- **Кириллица в `displayName` и `description` из Windows PowerShell.** Отправленная без явной сериализации в UTF-8, она сохраняется знаками вопроса (`?`): байты теряются на стороне клиента, до отправки запроса. Готовый вызов с `UTF8.GetBytes` — [Windows / PowerShell и UTF-8](/docs/infra#windows-powershell-и-utf-8).
- **Ключ приложения здесь не подхватывается.** [`GET /v1/infra/servers/:id`](./get.md) отдаёт сервер и по личному ключу приложения, к которому сервер привязан. Правка так не работает: она требует именно тот ключ, который управляет сервером, иначе ответ `404`. Как сменить управляющий ключ — [Восстановление доступа к серверу](/docs/infra/server-access-recovery).

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

- [Создать сервер](./create.md)
- [Получить сервер](./get.md)
- [Список серверов](./list.md)
- [Удалить сервер](./delete.md)
- [Иконка приложения](/docs/infra/app-icon)