Publish app

POST /v1/apps/:id/publish

Moves the app to PUBLISHED, binds placements to the Bitrix24 account, and makes the app visible to all employees.

Parameters

Request fields (body)

The body is optional. With an empty body, values are taken from the app record — this is the primary scenario for re-publishing without changes. If you send a body, add the Content-Type: application/json header — without it, a request with a body returns 413 PAYLOAD_TOO_LARGE.

Examples

curl — personal key

curl -X POST "https://vibecode.bitrix24.com/v1/apps/YOUR_APP_ID/publish" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "placements": ["CRM_DEAL_DETAIL_TAB"] }'

curl — OAuth app

curl -X POST "https://vibecode.bitrix24.com/v1/apps/YOUR_APP_ID/publish" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "placements": ["CRM_DEAL_DETAIL_TAB"] }'

JavaScript — personal key

const res = await fetch(
  'https://vibecode.bitrix24.com/v1/apps/YOUR_APP_ID/publish',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ placements: ['CRM_DEAL_DETAIL_TAB'] }),
  }
)
const body = await res.json()
if (!body.success) throw new Error(body.error.code)
// body.warnings — array, present if some placements failed to bind
console.log(body.data.placements)

JavaScript — OAuth app

const res = await fetch(
  'https://vibecode.bitrix24.com/v1/apps/YOUR_APP_ID/publish',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ placements: ['CRM_DEAL_DETAIL_TAB'] }),
  }
)

Response fields

Response example

The data field mirrors the app object with a filled placements array:

{
  "success": true,
  "data": {
    "id": "33c4d5e6-f7a8-49b0-1234-5c6d7e8f9012",
    "title": "Sales dashboard",
    "description": null,
    "scopes": ["crm", "user", "placement"],
    "handlerUrl": "https://vibecode.bitrix24.com/v1/bitrix-handler",
    "appUrl": "https://app-abc12345.vibecode.bitrix24.com",
    "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-24T10:03:18.204Z",
    "placements": ["CRM_DEAL_DETAIL_TAB"],
    "catalogStatus": "PUBLISHED",
    "publishedAt": "2026-06-24T10:03:18.204Z"
  }
}

Error response example

400 — the OAuth key lacks the placement scope:

{
  "success": false,
  "error": {
    "code": "MISSING_SCOPE",
    "message": "OAuth API key must have the placement scope to publish (catalog publishing binds placements on Bitrix24)."
  }
}

Errors

Full list of common API errors — Errors.

The account-side check for removing extra placements is currently rolling out per account, so there are two cases:

• While the capability is not enabled on the account — publication answers 200 even when the extra placements could not be removed on the account. The code that was not removed STAYS in the app'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 you have to parse warnings. 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 with the list of codes in error.placements, and the app is not published at all. 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: which transport confirmed the removal, and whether the second transport refused. 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.

A 502 here does not mean "nothing changed". The app's placements field is written BEFORE the refusal is raised and already reflects the actual state on the account: the codes removed successfully are gone from it, and the unconfirmed ones remain. So re-read the app through Application data before retrying. A retry without the placements field publishes exactly the set the app holds now — including the placement you believed removed. To remove it, retry with an explicit placements that omits that code.

Known specifics

• Publication requires the app to be authorized on the Bitrix24 account. Placement binding is performed by the app's OAuth token, so the app must be authorized on the Bitrix24 account at least once before the first publication. Without it, publication returns NO_USER_TOKEN. The authorization sequence — Application user authorization. Consent on the Bitrix24 account is enough to publish. You do not need to fetch the session token — the platform stores the app token on the return redirect.
• Signing in on the app's own page does not create the app token. The "Sign in with Bitrix24" button at your app address grants access to the app — that is a different surface, and it has no effect on NO_USER_TOKEN at publication. The token appears only at the OAuth consent step on the Bitrix24 account side: the authorization linked above, installing the app on the account, or the first time an embedded placement is opened. If publication still returns NO_USER_TOKEN after signing in on the app page, the account-side authorization never happened.
• The token is long-lived and renews itself. Authorization is needed once, not before every publication: the platform refreshes the token with its refresh token. Re-authorization is required only if access was revoked on the account or the OAuth app was recreated.
• A deploy's autoSaved: true does not always satisfy the publish check. The deploy auto-save stores the sources with the server you deployed to. If that server does not belong to the published app's OAuth key — for example, you deployed with a personal vibe_api_ key — the snapshot is kept with the server, and the publish check, which looks at the app's own snapshots by default, does not see it. Pass sourceServerId for that same server and publication will take the sources from there — saving them again through POST /v1/apps/:id/sources is unnecessary. The server identifier is the one in the deploy URL. The server's snapshots are listed by GET /v1/infra/servers/:serverId/sources.
• The placement title is the app name. The left-menu item and the CRM tabs are labelled with the resolved catalogTitle — there is no separate name for the menu. Renaming the app through updating the application also changes the placement labels.
• Unpublished apps can be published again. Publication is accepted in UNPUBLISHED status too — the app returns to PUBLISHED with the same or new placements. Catalog metadata is preserved on unpublish, so with an empty body the catalog is restored without refilling it.
• Some placements may not bind. Each code is bound separately. Codes that could not be bound do not interrupt publication — the app becomes PUBLISHED, and the codes that did not bind are listed in warnings.

See also

• Applications
• Application user authorization
• Unpublish
• Update an application
• Application data
• Source storage
• Portal event subscriptions