Для AI-агентов: markdown этой страницы — /docs-content/infra/servers/update.md индекс документации — /llms.txt

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

PATCH /v1/infra/servers/:id

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

Параметры

Параметр В Тип Обяз. Описание
id path string (UUID) да ID сервера из POST /v1/infra/servers или GET /v1/infra/servers

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

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

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

Примеры

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

Terminal 
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-приложение

Terminal 
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

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

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 — Ошибки.

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

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

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