For AI agents: markdown of this page — /docs-content-en/bots/management/transfer.md documentation index — /llms.txt

Transfer bot ownership

POST /v1/bots/:botId/transfer

Moves bot ownership to another API key of the same Bitrix24 account and the same user. A Bitrix24 account administrator can also perform the transfer. Resolves the case where the owning key is revoked and the bot stops working. The transfer changes only the key binding — the botId, chat history, subscriptions, and disabled state are preserved. No call to Bitrix24 is made during the transfer. For an active bot, verify the new key's access with a separate POST /v1/bots/:botId/reauth call; for a disabled bot, call it only when 410 BOT_DISABLED includes error.details.reauthAllowed=true. Other disabled states are protected: /reauth returns 409 BOT_REAUTH_NOT_ALLOWED, and transfer does not clear them.

Parameters

Parameter Type Required Description
botId (path) number yes Bot ID. List: GET /v1/bots. If the bot is not there, its ID is returned in the data.botId field of the 409 BOT_ALREADY_EXISTS response — see Bot access recovery

Request body

Field Type Required Description
targetApiKeyId string yes Identifier of the target key record, the id field in the GET /v1/keys response. Not the key string

The target key must be an active general-purpose key of the same Bitrix24 account, have the imbot scope, not be expired, and belong to the same Vibecode user who performs the transfer. A Bitrix24 account administrator transfers a bot to a key of any user of the same account. A key that fails the check is rejected with 400 TARGET_KEY_INVALID, and the specific cause is returned in the reason field — the causes are listed in the Errors table.

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/bots/42/transfer \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "targetApiKeyId": "3f9a1c20-5e6b-4d18-9a77-0c2b8e4f1d33" }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/bots/42/transfer', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ targetApiKeyId: '3f9a1c20-5e6b-4d18-9a77-0c2b8e4f1d33' }),
})
const { data } = await res.json()
console.log(data) // { transferred: true, botId: 42, fromApiKeyId: '...', toApiKeyId: '...' }

Response fields

Field Type Description
data.transferred boolean true if the binding changed. false if the key already owned the bot and the repeat call changed nothing
data.botId number Bot ID
data.fromApiKeyId string ID of the previous owner key. When transferred is false, it equals toApiKeyId
data.toApiKeyId string ID of the new owner key

Response example

JSON 
{
  "success": true,
  "data": {
    "transferred": true,
    "botId": 42,
    "fromApiKeyId": "8c41d5e7-2b90-4a63-b1f5-6d7e9a0c4b12",
    "toApiKeyId": "3f9a1c20-5e6b-4d18-9a77-0c2b8e4f1d33"
  }
}

Error response example

400 — the target key is not eligible (the specific cause is in the reason field):

JSON 
{
  "success": false,
  "error": {
    "code": "TARGET_KEY_INVALID",
    "message": "Target API key is not eligible to own this bot.",
    "reason": "wrong_user"
  }
}

Errors

HTTP Code Description
400 INVALID_BOT_ID botId is not a number
400 INVALID_PARAMS targetApiKeyId is missing, not a string, or an empty string
400 TARGET_KEY_INVALID The target key is not eligible. reason: not_active · wrong_portal · wrong_user · missing_scope · expired · system_key (platform-managed service key)
403 NOT_BOT_OWNER The caller does not own the bot (must be the same user as the owner key, or a portal admin)
403 SCOPE_DENIED The API key does not have the imbot scope
403 WRITE_BLOCKED_READONLY_KEY The key is in read-only mode
404 BOT_NOT_FOUND The bot was not found on the portal
404 TARGET_KEY_NOT_FOUND The target key was not found
409 BOT_TRANSFER_NOT_ALLOWED The bot is managed by an agent or a managed bot — transfer it via that resource, not directly
409 BOT_TRANSFER_CONFLICT Ownership changed concurrently — re-read the current owner and retry if still needed

Full list of common API errors — Errors.

Known specifics

A bot's operation does not depend on the app that registered it. Transferring to an active personal vibe_api_* key of the same account restores the bot regardless of which app registered it. The full procedure, including how to find the botId and the target key identifier, is in Bot access recovery.

Authorization is by user, not by key. The transfer is allowed for the bot owner, that is, the Vibecode user who owns the current owner key, even when that key is already revoked. A Bitrix24 account administrator can also perform the transfer. Holding the owner key is not required, which is exactly why the transfer works after the original key is revoked.

Idempotency. Transferring to the current owner key, including a revoked one, is safe: the binding stays unchanged and no audit entry is written.

See also