For AI agents: markdown of this page — /docs-content-en/infra/servers/update.md documentation index — /llms.txt

Update the server name and description

PATCH /v1/infra/servers/:id

Changes the server's display name and its description — two text fields visible in your Vibecode account and on the application card in the Bitrix24 catalog. The technical server identifier is set at creation and is not changed by this endpoint.

Parameters

Parameter In Type Required Description
id path string (UUID) yes Server ID from POST /v1/infra/servers or GET /v1/infra/servers

Request fields (body)

Field Type Required Description
displayName string yes Display name in any language: Russian, Chinese, emoji. 2–100 characters, no control bytes, trimmed at both ends. Send it in every call, including when you change only the description
description string | null no Application description for the Bitrix24 catalog card, up to 500 characters. Line breaks and tabs are allowed, other control bytes are not. The value is trimmed at both ends, so a string of spaces clears the description. An empty string and null also clear the description. If the field is omitted, the previous description is kept

The body accepts no other fields — for example, sending the technical identifier name in the body returns 400.

Examples

curl — personal key

Terminal 
curl -X PATCH https://vibecode.bitrix24.com/v1/infra/servers/6b23309f-7d0b-4cc3-a8f0-24183d48770e \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Deal assistant",
    "description": "A bot for CRM. Answers questions about deals."
  }'

curl — OAuth application

Terminal 
curl -X PATCH https://vibecode.bitrix24.com/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": "Deal assistant",
    "description": "A bot for CRM. Answers questions about deals."
  }'

JavaScript — personal key

javascript 
const res = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}`,
  {
    method: 'PATCH',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      displayName: 'Deal assistant',
      description: 'A bot for CRM. Answers questions about deals.',
    }),
  }
)
const { data } = await res.json()
console.log(data.displayName, data.description)

JavaScript — OAuth application

javascript 
const res = await fetch(
  `https://vibecode.bitrix24.com/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: 'Deal assistant',
      description: 'A bot for CRM. Answers questions about deals.',
    }),
  }
)

Response fields

Field Type Description
success boolean Always true on success
data.id string (UUID) Server ID
data.name string Technical server identifier. The value is immutable and is returned for verification
data.displayName string Display name after the update
data.description string | null Description after the update. The key is returned only if the description field was present in the request. A call without it neither touches the description nor shows it in the response. Full server state — GET /v1/infra/servers/:id

Response example

JSON 
{
  "success": true,
  "data": {
    "id": "6b23309f-7d0b-4cc3-a8f0-24183d48770e",
    "name": "my-crm-app",
    "displayName": "Deal assistant",
    "description": "A bot for CRM. Answers questions about deals."
  }
}

A call without the description field — the previous description is kept, the key is absent from the response:

JSON 
{
  "success": true,
  "data": {
    "id": "6b23309f-7d0b-4cc3-a8f0-24183d48770e",
    "name": "my-crm-app",
    "displayName": "Deal assistant"
  }
}

Error response example

404 — a server with this ID does not exist or belongs to another API key:

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

Errors

HTTP Code Description
400 INVALID_BODY Body validation failed: displayName was not sent, the name is shorter than 2 or longer than 100 characters, the description is longer than 500 characters, the body contains an unknown field. message carries the text of the first check that fired, and it does not always name the field
401 MISSING_API_KEY The X-Api-Key header was not sent
401 INVALID_API_KEY Invalid or expired API key
403 INFRA_FORBIDDEN_FOR_COWORK_KEY The call was made with a Co-work key. Such a key works with data only and does not manage servers. error.details.requiredAction carries the steps for obtaining a key with deploy rights
404 SERVER_NOT_FOUND Server not found or belongs to another API key. GET and DELETE on the same resource use a different code — NOT_FOUND
404 NOT_FOUND The server belongs to a Bitrix24 portal that the platform marked as deleted. Operations on such servers are not available
429 RATE_LIMITED The platform's overall request limit was exceeded

The full list of common API errors — Errors.

Known specifics

  • The update propagates to the application card in the Bitrix24 catalog. The display name is sent as the card title, the description as its description. A background process performs the synchronization, so the value appears in the catalog some time after the response. The card is updated only for an application that is already published in the catalog.
  • A call that changed nothing has no effect. If the sent values match the current ones, the platform writes nothing to the database, records no audit log entry, and schedules no catalog synchronization. The response is the usual 200 — it cannot tell you whether the record changed.
  • An application key is not accepted here. GET /v1/infra/servers/:id also returns the server for the personal key of the application the server is bound to. The update does not work that way: it requires exactly the key that manages the server, otherwise the response is 404. How to change the managing key — Server access recovery.

See also