Update an application

PATCH /v1/apps/:id

Changes application properties. Send only the fields you want to change.

Parameters

Request fields (body)

handlerUrl cannot be changed — passing the field in the body results in 400 HANDLER_URL_READONLY.

Examples

curl — personal key

curl -X PATCH https://vibecode.bitrix24.com/v1/apps/APP_ID \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "appUrl": "https://app-abc12345.vibecode.bitrix24.com/dashboard" }'

curl — OAuth application

curl -X PATCH https://vibecode.bitrix24.com/v1/apps/APP_ID \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "appUrl": "https://app-abc12345.vibecode.bitrix24.com/dashboard" }'

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/apps/APP_ID', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    appUrl: 'https://app-abc12345.vibecode.bitrix24.com/dashboard',
  }),
})

const { data } = await res.json()

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/apps/APP_ID', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    appUrl: 'https://app-abc12345.vibecode.bitrix24.com/dashboard',
  }),
})

const { data } = await res.json()

Response fields

Response example

{
  "success": true,
  "data": {
    "id": "33c4d5e6-f7a8-49b0-1234-5c6d7e8f9012",
    "title": "Sales dashboard",
    "description": "Updated",
    "scopes": ["crm", "user", "placement"],
    "handlerUrl": "https://vibecode.bitrix24.com/v1/bitrix-handler",
    "appUrl": "https://app-abc12345.vibecode.bitrix24.com/dashboard",
    "redirectUris": [
      "https://vibecode.bitrix24.com/oauth/complete",
      "http://localhost"
    ],
    "bitrixClientId": "local.7c3d4e5f6a7b80.55556666",
    "prefix": "vibe_app_local_7c3",
    "suffix": "6666",
    "authorId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "authorBitrixUserId": 42,
    "authorBitrixUserIdSource": "member",
    "portalId": "8b1f0e2a-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
    "createdAt": "2026-06-24T09:12:45.781Z",
    "updatedAt": "2026-06-24T09:13:36.974Z",
    "placements": []
  }
}

Error response example

404 — application not found:

{
  "success": false,
  "error": {
    "code": "APP_NOT_FOUND",
    "message": "Application not found"
  }
}

Errors

Full list of common API errors — Errors.

The account-side placement-removal check is currently rolling out per account, so there are two cases:

• While the capability is not enabled on the account — a PATCH with a reduced placements set answers 200 even when the extra placements could not be removed on the account. The code that was not removed STAYS in the application's placements, and the reason arrives as a Failed to unbind <code> entry in warnings. That entry is the only sign the list has drifted from the account, so for now warnings has to be parsed. The codes PLACEMENT_UNBIND_FAILED and NETWORK_DEVKEY_REQUIRED do not occur on this endpoint.
• Once enabled — an unconfirmed removal answers 502 PLACEMENT_UNBIND_FAILED, and the rest of the request is not applied: neither the title re-binding nor the remaining fields. Retry the request — the placements listed in error.placements are still on the account. A 502 here does not mean "nothing changed": the placements list has already been rewritten with the removed set, so re-read the application through Application data instead of trusting the list you held before the call. A 200 carrying a placement that was not removed does not occur on this path — on a successful response the removal entries in warnings are limited to confirmation notes. Enabling it does not change the rest of the set — binding failures and the other reasons listed in the warnings row above arrive on this path too.

Known specifics

• Renaming an application in the catalog also changes the labels in the Bitrix24 account. The new title goes into the catalog card (the catalogTitle field is written together with title) and into the placements — the left-menu item and the CRM tabs. The rename therefore calls Bitrix24 and can return 400 NO_USER_TOKEN or 502 BITRIX_PARTIAL_REBIND. On a rejection the name is not saved. On BOX and developer-key paths, after a confirmed removal and a rejected new binding, the platform makes one attempt to restore the previous title. Successfully restored placements are listed in error.restored; they need no manual repair, but the rename is still refused. Only placements in error.unbound need checking: they were either left removed, or Bitrix24 never confirmed that the previous binding was removed. Restore them through POST /v1/placements/bind, then repeat the PATCH. The paired error.bitrixCodes and error.bitrixStatuses arrays contain the code and HTTP status for every rejected call, new title first and previous title second; missing values become B24_ERROR and 0, while raw rejection text and the developer-key URL are never returned. The cloud OAuth rebind does not compensate, but it refuses too when Bitrix24 confirmed neither the removal of the previous binding nor the new one: such a placement lands in error.unbound, the response is 502, and the name is not saved. Bitrix24 caches the left menu — the new name shows up after a hard page reload. For an application outside the catalog the rename changes title only.
• Changing scopes propagates the platform vibe:* scopes into the application's keys. The update compares the old and the new set and applies the vibe:* difference to every active key of the application — an added vibe:ai appears on the keys, a removed vibe:infra disappears from them. Bitrix24 account scopes (crm, user and the rest) are not propagated: their set is fixed when the key is issued and changes only by reissuing it.
• A key with a fixed rights set receives no platform scopes through propagation. That set is fixed on the paired key of an application created with a partner key, with a Cowork project key, with a personal key from the Vibecode dashboard form or with a key issued using exactScopes: true — Create an application. Removals reach it like any other key, additions do not: a vibe:infra added to the application's scopes will not appear on such a key, and POST /v1/infra/servers keeps answering 403 INFRA_SCOPE_REQUIRED. The required right is declared in scopes when the application is created.
• A mismatch between the application scopes and its key is fixed with two requests. The application's scopes can carry vibe:infra while its key does not — the key returns 403 when creating a server. Remove vibe:infra from scopes with the first request and put it back with the second: propagation applies exactly the difference, so the second edit adds the scope to the key. This has no effect on a key with a fixed rights set — see the paragraph above. The key's effective set is shown by GET /v1/me in data.scopes when called with that key.
• Changing placements of a published application triggers placement sync in the Bitrix24 account. Binding and unbinding happen directly in the Bitrix24 account, and some codes may fail to bind — then the response carries warnings with a list of such codes. On a cloud account without a user token the sync is impossible, and the request returns 400 NO_USER_TOKEN. For an application in PRIVATE status, placements are written to the database without contacting Bitrix24.
• An appUrl edit reaches the application card in the Bitrix24 catalog on its own. The card is queued for an update by this same request — no separate call is needed. The card opens the full address of the application — subpath, query parameters and fragment included — when that address points to the same Black Hole subdomain as the card's server. In every other case the card opens the server root — including when the address uses a different subdomain, a custom domain or a different scheme, is empty or unparsable, carries a username before the host, or is longer than 512 characters, a limit the query parameters count toward. A separate gateway limitation applies regardless of the card: on the first visit within a session the visitor lands on the subdomain root whatever the card address is — App deployment.
• Non-ASCII characters in title from Windows PowerShell. Sent without explicit UTF-8 serialization, they are stored as question marks (?): the bytes are lost on the client side, before the request is sent. A ready-to-run call with UTF8.GetBytes — Windows / PowerShell and UTF-8.
• The mobile field is not editable. A value sent in the body is ignored, and the response is 200 with no change to the record. Bitrix24 has no method for updating a local application, so the flag is set only at creation. For an existing application, turn the flag on in the application card on the Bitrix24 account, or create the application again.

See also

• Applications
• Create an application
• Application data
• Delete an application
• Publish