Для 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 — личный ключ
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-приложение
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 — личный ключ
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-приложение
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 |
Полеwarnings |
Типarray<string> | ОписаниеПриходит, только если есть что сказать. Поводов два: присланная строка потеряла не-ASCII символы по дороге, или подпись части встроек приложения не обновляется при переименовании (см. «Известные особенности»). Запись при этом выполняется, ответ остаётся 200 |
Пример ответа
{
"success": true,
"data": {
"id": "6b23309f-7d0b-4cc3-a8f0-24183d48770e",
"name": "my-crm-app",
"displayName": "Помощник по сделкам",
"description": "Бот для CRM. Отвечает на вопросы по сделкам."
}
}
Вызов без поля description — прежнее описание сохраняется, ключа в ответе нет:
{
"success": true,
"data": {
"id": "6b23309f-7d0b-4cc3-a8f0-24183d48770e",
"name": "my-crm-app",
"displayName": "Помощник по сделкам"
}
}
Пример ответа при ошибке
404 — сервер с таким ID не существует или привязан к другому API-ключу, и вы не состоите в его команде разработки:
{
"success": false,
"error": {
"code": "SERVER_NOT_FOUND",
"message": "Server not found"
}
}
Ошибки
| HTTP | Код | Описание |
|---|---|---|
| HTTP400 | КодINVALID_BODY |
ОписаниеНарушена валидация тела: не передан displayName, имя короче 2 или длиннее 100 символов, описание длиннее 500 символов, в теле есть неизвестное поле. В message приходит текст первой сработавшей проверки, имя поля в нём есть не всегда |
| HTTP400 | КодNO_USER_TOKEN |
ОписаниеУ приложения сервера есть встройки, а приложение не авторизовано в Битрикс24, поэтому подпись встроек обновить нельзя. Имя не изменено |
| HTTP400 | КодBOX_NO_DEVELOPER_KEY, APP_NOT_INSTALLED_ON_BOX |
ОписаниеТо же на коробочном Битрикс24: у автора приложения нет ключа разработчика, или приложение там не установлено. Имя не изменено |
| HTTP401 | КодMISSING_API_KEY |
ОписаниеНе передан заголовок X-Api-Key |
| HTTP401 | КодINVALID_API_KEY |
ОписаниеКлюч не опознан: такой строки на платформе нет |
| HTTP403 | КодINFRA_FORBIDDEN_FOR_COWORK_KEY |
ОписаниеВызов сделан ключом Коворк/Код — такой ключ работает только с данными, изменяющие операции ему закрыты. Что делать — Проектный ключ для деплоя |
| HTTP403 | КодWRITE_BLOCKED_READONLY_KEY |
ОписаниеКлючу закрыта запись в данные Битрикс24, а переименование перепривязало бы встройки приложения сервера. Условия те же, что у переименования приложения через PATCH /v1/apps/:id, — Режим доступа. Имя не изменено |
| HTTP403 | КодSERVER_ROLE_FORBIDDEN |
ОписаниеВы состоите в команде разработки этого сервера с ролью «Разработчик», а операция открыта роли «Администратор». В error.hint придут ваша роль, требуемый порог и перечень открытых вам вызовов. Разбор ролей — Список серверов |
| HTTP403 | КодEXTERNAL_COLLABORATOR_KEY_SERVER_MISMATCH |
ОписаниеВызов сделан ключом внешнего участника разработки, а в адресе указан не тот сервер, для которого ключ выпущен. Такой ключ действует ровно на одном сервере, и ответ не сообщает, существует ли запрошенный сервер. Для работы с другим сервером нужен ключ того внешнего членства |
| HTTP403 | КодEXTERNAL_COLLABORATOR_NOT_A_MEMBER |
ОписаниеКлюч внешнего участника обращается к своему серверу, но доступа сейчас нет: членство снято, истёк его срок либо для аккаунта Битрикс24, которому принадлежит сервер, отключены внешние участники разработки. Код эти причины не различает и сведений о сервере не раскрывает. Членство перечитывается на каждом запросе, поэтому снятый доступ перестаёт работать сразу |
| HTTP404 | КодSERVER_NOT_FOUND |
ОписаниеСервер не найден или привязан к другому API-ключу, и вы не состоите в его команде разработки. У GET и DELETE того же ресурса код другой — NOT_FOUND |
| HTTP404 | КодNOT_FOUND |
ОписаниеСервер принадлежит порталу Битрикс24, который платформа пометила удалённым. Операции над такими серверами закрыты |
| HTTP409 | КодAPPLICATION_OP_IN_PROGRESS |
ОписаниеС приложением сервера сейчас идёт другая операция. Имя не изменено, повторите вызов через несколько секунд |
| HTTP429 | КодRATE_LIMITED |
ОписаниеПревышен лимит запросов: общий лимит платформы или лимит частоты этого вызова |
| HTTP502 | КодBITRIX_PARTIAL_REBIND |
ОписаниеБитрикс24 не принял новую подпись встройки. Коды встроек — в error.unbound (встройка снята и не привязана заново) и error.restored (вернулась прежняя подпись). Имя не изменено, вызов можно повторить |
Полный список общих ошибок API — Ошибки.
Известные особенности
- Правка уходит в карточку приложения в каталоге Битрикс24. Отображаемое имя передаётся как название карточки, описание — как её описание. Синхронизацию ведёт фоновый процесс, поэтому в каталоге значение появляется не в момент ответа. Карточка обновляется только у приложения, которое уже опубликовано в каталоге.
- Приложение в личном кабинете показывает эти же два значения. Если сервер привязан к приложению, кабинет берёт имя и описание с сервера, поэтому правка видна там сразу после ответа. Обратное тоже верно: имя, изменённое у приложения в кабинете, меняет
displayNameсервера — это одно значение с двумя способами правки, и последняя правка выигрывает. - Подпись встройки следует за именем. Вкладка в карточке CRM или пункт левого меню называются по имени приложения. Если у приложения сервера есть встройки, смена
displayNameсначала перепривязывает их с новым названием в Битрикс24 и только потом сохраняет имя. Когда Битрикс24 привязку не подтвердил, имя не меняется ни у сервера, ни у приложения, и повторный вызов безопасен. Части встроек подпись не обновляется вовсе — их коды перечислены вwarnings. Сервер без приложения, приложение без встроек и правка одного описания в Битрикс24 не обращаются. - Вызов, который ничего не изменил, остаётся без последствий. Если переданные значения совпадают с текущими, платформа не пишет в базу, не заносит запись в журнал аудита и не ставит синхронизацию с каталогом. Ответ при этом обычный,
200— по нему нельзя судить, изменилась ли запись. - Кириллица в
displayNameиdescriptionиз Windows PowerShell. Отправленная без явной сериализации в UTF-8, она сохраняется знаками вопроса (?): байты теряются на стороне клиента, до отправки запроса. Готовый вызов сUTF8.GetBytes— Windows / PowerShell и UTF-8. Платформа такую строку принимает и записывает как есть, но называет потерю: в ответе приходитwarningsс именами пострадавших полей. Предупреждение выдаётся только на поле, которое этот вызов действительно изменил, — повторная присылка того же значения молчит. - Ключ приложения здесь не подхватывается.
GET /v1/infra/servers/:idотдаёт сервер и по личному ключу приложения, к которому сервер привязан. Правка так не работает: она требует именно тот ключ, который управляет сервером, иначе ответ404. Как сменить управляющий ключ — Восстановление доступа к серверу.