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 application

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 — non-fatal advisory entries; rejected binds return PLACEMENT_BIND_FAILED
console.log(body.data.placements)

JavaScript — OAuth application

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.

`PLACEMENT_BIND_FAILED` failure fields

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.

A rejected requested bind is independent of that rollout flag: on either side it answers 502 PLACEMENT_BIND_FAILED and does not move the app to PUBLISHED. When removal of an old placement is also unconfirmed in the same request, the outer code still remains PLACEMENT_BIND_FAILED and the old placement is listed in error.failedUnbinds. If Bitrix24 rejects the developer key with a credential-only HTTP 401 and the app has an OAuth token, publication first retries the bind through OAuth; a successful fallback remains HTTP 200 and is recorded in the audit log. A response that explicitly names a non-credential cause, such as an account-policy refusal or a missing scope, remains authoritative at every HTTP status and is never retried through OAuth.

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

• OAuth authorization provides the primary or fallback transport. On an account without a developer key, placement binding uses the OAuth token. When developer-key transport is selected and Bitrix24 rejects that credential with a credential-only HTTP 401, the same OAuth token becomes the fallback channel. Named account-policy and missing-scope refusals are authoritative regardless of HTTP status and never enter that fallback. With no usable transport, publication returns NO_USER_TOKEN or NETWORK_DEVKEY_REQUIRED. The authorization sequence — Application user authorization.
• 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 application 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.
• Every requested placement must bind. Codes are bound separately, so some can already be registered on the account. If any bind is not confirmed, publication returns 502 PLACEMENT_BIND_FAILED, the app does not become PUBLISHED, and the successfully bound codes already remain in its placements field.

See also

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