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
ParameterdialogId (path) Typestring Requiredyes DescriptionDialog 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
FieldengineCode Typestring Requiredyes DescriptionCode 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.result Typeboolean Descriptiontrue — 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
HTTP400 CodeINVALID_PARAMS DescriptionengineCode 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
HTTP404 CodeENTITY_NOT_FOUND DescriptionBitrix24 returned "not found". The portal code is in error.b24Code
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 refused with WRONG_MESSAGE_TYPE in error.b24Code — the chat is not a CoPilot chat
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 refused with IDENTICAL_ENGINE in error.b24Code — the chat already uses this model
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 refused with ENGINE_NOT_FOUND in error.b24Code — no model with this code
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 refused with COPILOT_NOT_INSTALLED in error.b24Code — CoPilot is not installed on the portal
HTTP502 CodeME_ALIAS_RESOLUTION_FAILED DescriptionFailed to resolve the user when using the me alias
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the im scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only — the call changes the chat
HTTP401 CodeTOKEN_MISSING DescriptionThe 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