Replace an application server

POST /v1/applications/:id/replace-server

Moves the application to another server: an existing server of the owner, or a new one that the method creates itself. The old server is not deleted. The application is unlinked from it, and the server stays with its owner. Before calling, find out whether a replacement is possible and choose the server through GET /v1/applications/:id/available-servers.

Only the card owner can call this method, and only with their own keys. An administrator of the Bitrix24 account who does not own the application replaces the server in their Vibecode account.

Authorization: X-Api-Key with the vibe:infra scope.

Parameters

Request fields (body)

The body takes one of two forms. Fields of the two forms cannot be mixed, and extra fields return 400 VALIDATION_ERROR.

Your own existing server.

A new server.

Examples

curl — personal key

curl -X POST \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"serverId": "srv_new"}' \
  https://vibecode.bitrix24.com/v1/applications/cmsw806qi0000tdskiw2aegii/replace-server

curl — OAuth application

curl -X POST \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"serverId": "srv_new"}' \
  https://vibecode.bitrix24.com/v1/applications/cmsw806qi0000tdskiw2aegii/replace-server

JavaScript — personal key

const id = 'cmsw806qi0000tdskiw2aegii'
const res = await fetch(`https://vibecode.bitrix24.com/v1/applications/${id}/replace-server`, {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ serverId: 'srv_new' }),
})
const { data } = await res.json()

for (const warning of data.warnings) {
  console.warn('Needs manual follow-up:', warning)
}

JavaScript — OAuth application

const id = 'cmsw806qi0000tdskiw2aegii'
const res = await fetch(`https://vibecode.bitrix24.com/v1/applications/${id}/replace-server`, {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ serverId: 'srv_new' }),
})
const { data } = await res.json()

A new server is created with the body {"provider": "bitrix-cloud", "plan": "bc-small", "region": "bc-eu-central"}. This call is paid. To keep a retry from creating a second server, send the Idempotency-Key header, see "Known behaviors".

Response fields

Values of data.warnings:

Response example

{
  "success": true,
  "data": {
    "serverId": "srv_new",
    "oldServerId": "srv_old",
    "branch": "existing",
    "appUrlMoved": true,
    "warnings": [],
    "callerKeyManagesServer": true
  }
}

Error response example

409 — the server is already linked to another application:

{
  "success": false,
  "error": {
    "code": "SERVER_ALREADY_LINKED",
    "message": "Server is linked to another application"
  }
}

Errors

The error.message text is in English and meant for logs: build interface texts from error.code. The full list of common API errors is in Errors.

Known behaviors

• A failure after the link is written does not become an error. Once the application points to the new server, the method answers 200 and lists what could not be completed in warnings. An error response happens only for what went wrong before the link was written. A client that looks at the response status alone will miss the warnings: always read warnings.
• Retrying the new form with Idempotency-Key. A retry with the same key and the same body within 24 hours of the first call creates no second server. If the replacement completed, the 200 response repeats the original data.serverId, data.oldServerId and data.appUrlMoved with an empty data.warnings and carries the Idempotent-Replayed: true header. If the outcome is unknown or the application has already moved to another server, the answer is 409 IDEMPOTENCY_KEY_ALREADY_USED. Then read GET /v1/applications/:id, where server.id is the application's current server, and check your Vibecode account for an unlinked server before buying again. After 24 hours the duplicate protection may expire. Without the header, a retry may create a second server.
• The key of the call is not reassigned. The managing key of the new server is the application's own key: the authorization key if it has one, otherwise the personal key. The key you called with stays as it was. callerKeyManagesServer tells whether it manages the new server. It is false when the application has an authorization key or the target server is a galaxy container.
• The server is created for the card owner. Limits and payment conditions apply to the owner, not to the administrator of the Bitrix24 account.
• The old server stays. It is unlinked from the application and keeps running for the owner. If you do not need it, delete it separately with DELETE /v1/infra/servers/:id.
• Whether to show the button is decided by available-servers. It also names the reason for a refusal of the new form in advance. All other reasons arrive as error codes from the table above.

See also

• Servers for moving an application
• Application card
• Create a server
• Application showcase
• Errors