Register the Service ai.engine.register

If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the MCP server so that the assistant can utilize the official REST documentation.

Scope: ai_admin

Who can execute the method: administrator

The method ai.engine.register registers a custom AI service.

Method Parameters

Required parameters are marked with *

Name `type`	Description
name* `string`	The name of the service that will be displayed in the interface
code* `string`	A unique code for the service. Only characters `A-Za-z0-9-_` are allowed
category* `string`	The category of the service. Possible values: `text` `image` `audio` `call`
completions_url* `string`	The URL endpoint of the handler, which must respond with HTTP status `200` during registration verification (detailed description)
settings `object`	Additional settings for the service (detailed description)

Settings Parameter

The method accepts settings as a JSON object without a strict schema. The following fields are used in the service code:

Name `type`	Description
code_alias `string`	The alias of the model. Defaults to `ChatGPT`
model_context_type `string`	The method of calculating context. Possible values: `token` `symbol` Defaults to `token`
model_context_limit `integer`	The context limit. Defaults to `15666`

Endpoint

completions_url must point to your endpoint that accepts requests from Bitrix24 and processes them in the expected format.

Attention!

The endpoint code from the examples can be used as a foundation, but for production, it's better to separate the processing into different parts of the application.

The template endpoint can be used as a basis for your own service.

Endpoint Requirements

The endpoint must quickly accept the request and return a response or queue the task in its internal queue. The initial response time should not exceed 5 seconds — after the timeout, the connection is terminated.
For the image category, processing should be done asynchronously.
The request payload includes callbackUrl and errorCallbackUrl. After processing, the result should be sent to callbackUrl, and error information to errorCallbackUrl.
The endpoint must correctly return HTTP statuses:

200 — request processed immediately
202 — request accepted and queued
503 — service temporarily unavailable

The callbackUrl has a limited lifespan — it is provided in the ttl parameter (in seconds). If the endpoint does not send the result before this period expires, the link will become invalid, and the user will not receive a response.

Attention!

The endpoint's response to the initial request does not replace the callback mechanism. Upon successful acceptance of the request, the endpoint should return json_encode(['result' => 'OK']).

Features for the Audio Category

For the audio category, the prompt key receives an object with the following fields:

Name `type`	Description
file `string`	Link to the file. The file may come without an extension
fields `object`	Additional data about the file (detailed description)
fileExtension `string`	The file extension, if it can be determined. May come as an empty string

Fields Object

Name `type`	Description
type `string`	Content-Type of the file. Especially important if the file is sent without an extension, e.g., `audio/ogg`
prompt `string`	Auxiliary prompt for file recognition, e.g., company name

Features for the Image Category

For the image category, the prompt key receives an object with the following fields:

Name `type`	Description
prompt `string`	Text description of what needs to be generated
style `string`	The style of image generation. May be absent if no style was specified
format `string`	Image format, e.g., `square`, `landscape`. May come as `null` if no format was specified
images_number `integer`	The number of images to generate. May be absent if no value was specified

Additional Fields in the Request to the Endpoint

Name `type`	Description
auth `object`	Authorization data
payload_raw `string`	Raw value of the prompt. When using BitrixGPT, this may contain the symbolic code of the used prompt
payload_provider `string`	Symbolic code of the pre-prompt provider. When using BitrixGPT, this may contain `prompt`
payload_prompt_text `string`	If `payload_provider = prompt`, contains the raw instruction of the pre-prompt
payload_markers `object`	Additional user markers used in prompt formation
payload_role `string`	Role or instruction used in prompt formation. In GPT-like systems, this value is usually passed as a system message
collect_context `boolean`	A flag indicating whether to pass context to the model
context `array`	An array of previous messages in chronological order. The volume sent depends on the provider's settings and the type of context calculation
max_tokens `integer`	Maximum number of tokens in the response
temperature `number`	A parameter that controls the degree of randomness of the output
callbackUrl `string`	URL to which the result of successful processing should be sent
errorCallbackUrl `string`	URL to which error information should be sent
ttl `integer`	The lifespan of the `callbackUrl` link in seconds. After this period, the link will become invalid

Context should only be passed to the model if the request includes collect_context = true. If the parameter is absent or set to false, context can be omitted.

Example structure of a message for a GPT-like model:

[
            {
                "role": "system",
                "content": "$payload_role"
            },
            {
                "role": "user",
                "content": "$prompt"
            }
        ]

Code Examples

How to Use Examples in Documentation

cURL (Webhook)

cURL (OAuth)

PHP

BX24.js

PHP CRest

curl -X POST \
          -H "Content-Type: application/json" \
          -H "Accept: application/json" \
          -d '{
            "name": "Acme GPT",
            "code": "acme_gpt",
            "category": "text",
            "completions_url": "https://api.example.com/bitrix24/ai/completions",
            "settings": {
              "code_alias": "ChatGPT",
              "model_context_type": "token",
              "model_context_limit": 15666
            }
          }' \
          https://**put_your_bitrix24_address**/rest/**put_your_webhook_id**/**put_your_webhook_code**/ai.engine.register.json

curl -X POST \
          -H "Content-Type: application/json" \
          -H "Accept: application/json" \
          -d '{
            "name": "Acme GPT",
            "code": "acme_gpt",
            "category": "text",
            "completions_url": "https://api.example.com/bitrix24/ai/completions",
            "settings": {
              "code_alias": "ChatGPT",
              "model_context_type": "token",
              "model_context_limit": 15666
            },
            "auth": "**put_access_token_here**"
          }' \
          https://**put_your_bitrix24_address**/rest/ai.engine.register

try
        {
            const response = await $b24.callMethod(
                'ai.engine.register',
                {
                    name: 'Acme GPT',
                    code: 'acme_gpt',
                    category: 'text',
                    completions_url: 'https://api.example.com/bitrix24/ai/completions',
                    settings: {
                        code_alias: 'ChatGPT',
                        model_context_type: 'token',
                        model_context_limit: 15666
                    }
                }
            );
        
            const result = response.getData().result;
            console.log('Engine registered:', result);
        }
        catch (error)
        {
            console.error('Error:', error);
        }

try {
            $response = $b24Service
                ->core
                ->call(
                    'ai.engine.register',
                    [
                        'name' => 'Acme GPT',
                        'code' => 'acme_gpt',
                        'category' => 'text',
                        'completions_url' => 'https://api.example.com/bitrix24/ai/completions',
                        'settings' => [
                            'code_alias' => 'ChatGPT',
                            'model_context_type' => 'token',
                            'model_context_limit' => 15666,
                        ],
                    ]
                );
        
            $result = $response
                ->getResponseData()
                ->getResult();
        
            echo 'Success: ' . print_r($result, true);
        } catch (Throwable $e) {
            error_log($e->getMessage());
            echo 'Error registering AI engine: ' . $e->getMessage();
        }

BX24.callMethod(
            'ai.engine.register',
            {
                name: 'Acme GPT',
                code: 'acme_gpt',
                category: 'text',
                completions_url: 'https://api.example.com/bitrix24/ai/completions',
                settings: {
                    code_alias: 'ChatGPT',
                    model_context_type: 'token',
                    model_context_limit: 15666
                }
            },
            function(result)
            {
                if (result.error())
                {
                    console.error(result.error(), result.error_description());
                }
                else
                {
                    console.log(result.data());
                }
            }
        );

require_once('crest.php');
        
        $result = CRest::call(
            'ai.engine.register',
            [
                'name' => 'Acme GPT',
                'code' => 'acme_gpt',
                'category' => 'text',
                'completions_url' => 'https://api.example.com/bitrix24/ai/completions',
                'settings' => [
                    'code_alias' => 'ChatGPT',
                    'model_context_type' => 'token',
                    'model_context_limit' => 15666,
                ],
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';

Response Handling

HTTP Status: 200

{
            "result": 12,
            "time": {
                "start": 1774078200,
                "finish": 1774078200.315271,
                "duration": 0.31527090072631836,
                "processing": 0.02,
                "date_start": "2026-03-20T09:50:00+02:00",
                "date_finish": "2026-03-20T09:50:00+02:00",
                "operating_reset_at": 1774078800,
                "operating": 0
            }
        }

Returned Data

Name `type`	Description
result `integer`	Identifier of the registered service
time `time`	Information about the execution time of the request

Error Handling

HTTP Status: 400

{
            "error": "ENGINE_REGISTER_ERROR_CODE_UNIQUE",
            "error_description": "A record with this `code` already exists."
        }

Name `type`	Description
error `string`	String error code. It may consist of digits, Latin letters, and underscores
error_description `error_description`	Textual description of the error. The description is not intended to be shown to the end user in its raw form

Possible Error Codes

Code	Description	Value
`ENGINE_REGISTER_ERROR_NAME`	The `name` key with a string value is required	The `name` parameter is missing, an empty value is provided, or the value is not a string
`ENGINE_REGISTER_ERROR_CODE`	The `code` key with a string value is required	The `code` parameter is missing, an empty value is provided, or the value is not a string
`ENGINE_REGISTER_ERROR_CODE_FORMAT`	The `code` key must contain only characters `A-Za-z0-9-_`	Invalid characters are present in `code`
`ENGINE_REGISTER_ERROR_CODE_UNIQUE`	A record with this `code` already exists	A service with this code is already registered in the same category
`ENGINE_REGISTER_ERROR_CATEGORY`	The `category` key is required	The `category` parameter is missing or an empty value is provided
`ENGINE_REGISTER_ERROR_CATEGORY_FORMAT`	The `category` key can contain one of the values: `text, image, audio, call`	The provided `category` value is not in the list of available categories
`ENGINE_REGISTER_ERROR_COMPLETIONS_URL`	The `completions_url` key with a string value is required	The `completions_url` parameter is missing, an empty value is provided, or the value is not a string
`ENGINE_REGISTER_ERROR_COMPLETIONS_URL_FAIL`	The value of the `completions_url` key must be a valid URL that returns status `200` upon verification	The URL is unavailable, invalid, or returns a status other than `200` upon verification
`ENGINE_REGISTER_ERROR_SETTINGS_FORMAT`	The value of the `settings` key must be valid JSON	The `settings` parameter is not provided as an object

Statuses and System Error Codes

HTTP Status: 20x, 40x, 50x

The errors described below may occur when calling any method.

Status	Code Error Message	Description
`500`	`INTERNAL_SERVER_ERROR` Internal server error	An internal server error has occurred. Please contact the server administrator or Bitrix24 technical support
`500`	`ERROR_UNEXPECTED_ANSWER` Server returned an unexpected response	An internal server error has occurred. Please contact the server administrator or Bitrix24 technical support
`503`	`QUERY_LIMIT_EXCEEDED` Too many requests	The request intensity limit has been exceeded
`405`	`ERROR_BATCH_METHOD_NOT_ALLOWED` Method is not allowed for batch usage	The current method is not permitted for calls using batch
`400`	`ERROR_BATCH_LENGTH_EXCEEDED` Max batch length exceeded	The maximum length of parameters passed to the batch method has been exceeded
`401`	`NO_AUTH_FOUND` Wrong authorization data	Invalid access token or webhook code
`400`	`INVALID_REQUEST` Https required	The HTTPS protocol is required for method calls
`503`	`OVERLOAD_LIMIT` REST API is blocked due to overload	The REST API is blocked due to overload. This is a manual individual block; please contact Bitrix24 technical support to lift it
`403`	`ACCESS_DENIED` REST API is available only on commercial plans	The REST API is only available on commercial plans
`403`	`INVALID_CREDENTIALS` Invalid request credentials	The user associated with the access token or webhook used to call the method lacks the necessary permissions
`404`	`ERROR_MANIFEST_IS_NOT_AVAILABLE` Manifest is not available	The manifest is not available
`403`	`insufficient_scope` The request requires higher privileges than provided by the webhook token	The request requires higher privileges than those provided by the webhook token
`401`	`expired_token` The access token provided has expired	The provided access token has expired
`403`	`user_access_error` The user does not have access to the application	The user does not have access to the application. This means that the application is installed, but the portal administrator has restricted access to this application to specific users only
`500`	`PORTAL_DELETED` Portal was deleted	The public part of the site is closed. To open the public part of the site on an on-premise installation, disable the "Temporary closure of the public part of the site" option. Path to the setting: Desktop > Settings > Product Settings > Module Settings > Main Module > Temporary closure of the public part of the site

Continue Learning

Overview of Methods

Get List of Services

Register the Service ai.engine.register

Method ParametersMethod Parameters

Settings ParameterSettings Parameter

EndpointEndpoint

Endpoint RequirementsEndpoint Requirements

Features for the Audio CategoryFeatures for the Audio Category

Fields ObjectFields Object

Features for the Image CategoryFeatures for the Image Category

Additional Fields in the Request to the EndpointAdditional Fields in the Request to the Endpoint

Code ExamplesCode Examples

Response HandlingResponse Handling

Returned DataReturned Data

Error HandlingError Handling

Possible Error CodesPossible Error Codes

Statuses and System Error CodesStatuses and System Error Codes

Continue LearningContinue Learning