For AI agents: markdown of this page — /docs-content-en/chats/copilot/engine.md documentation index — /llms.txt

Change the CoPilot model

PUT /v1/chats/:dialogId/copilot/engine

Switches the artificial intelligence (AI) model that CoPilot uses to answer in a chat. Works only in a CoPilot chat. After the switch, a system message about the new model appears in the chat.

Parameters

Parameter Type Required Description
dialogId (path) string yes Dialog ID of a CoPilot chat — chatN. Get it from data.chat.dialogId of the draft chat or from recent dialogs called with onlyCopilot=true

Query parameters are not accepted and are rejected with 400 INVALID_PARAMS.

Request fields (body)

Field Type Required Description
engineCode string yes Code of an AI model available in the Bitrix24 account. The chat's current model is engine in data.copilot.chats returned by Load a chat

Other body fields are rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

Terminal 
curl -X PUT https://vibecode.bitrix24.com/v1/chats/chat2001/copilot/engine \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"engineCode": "engine_code"}'

curl — OAuth application

Terminal 
curl -X PUT https://vibecode.bitrix24.com/v1/chats/chat2001/copilot/engine \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"engineCode": "engine_code"}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/chat2001/copilot/engine', {
  method: 'PUT',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ engineCode: 'engine_code' }),
})

const { success, data } = await res.json()
console.log('Model switched:', data.result)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/chat2001/copilot/engine', {
  method: 'PUT',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ engineCode: 'engine_code' }),
})

const { success, data } = await res.json()
console.log('Model switched:', data.result)

Response fields

Field Type Description
success boolean Always true on success
data.result boolean true — the model was switched

Response example

JSON 
{
  "success": true,
  "data": {
    "result": true
  }
}

Error response example

422 — the chat is not a CoPilot chat:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "WRONG_MESSAGE_TYPE",
    "b24Code": "WRONG_MESSAGE_TYPE"
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS engineCode is missing or is not a non-empty string, or another body field or a query parameter was sent. Checked before any call to Bitrix24
404 ENTITY_NOT_FOUND Bitrix24 returned "not found". The portal code is in error.b24Code
422 BITRIX_ERROR Bitrix24 refused with WRONG_MESSAGE_TYPE in error.b24Code — the chat is not a CoPilot chat
422 BITRIX_ERROR Bitrix24 refused with IDENTICAL_ENGINE in error.b24Code — the chat already uses this model
422 BITRIX_ERROR Bitrix24 refused with ENGINE_NOT_FOUND in error.b24Code — no model with this code
422 BITRIX_ERROR Bitrix24 refused with COPILOT_NOT_INSTALLED in error.b24Code — CoPilot is not installed on the portal
502 ME_ALIAS_RESOLUTION_FAILED Failed to resolve the user when using the me alias
403 SCOPE_DENIED The API key does not have the im scope
403 WRITE_BLOCKED_READONLY_KEY The key is read-only — the call changes the chat
401 TOKEN_MISSING The API key has no Bitrix24 tokens configured

The full list of general API errors — Errors.

Known specifics

Switching to the same model again is refused. Before switching, compare engine from data.copilot.chats with the model you need.

The choice is remembered. The model is saved as the one the user selected last.

See also