AI Router

A single OpenAI-compatible API for working with language models from different providers. Free Bitrix24 models are available right away — for paid models and for your own provider keys (BYOK), connect your credentials.

This is an API, not a chat interface. There is no chat window for talking to a model in your Vibecode account — you don't need to look for one. You enter the request (prompt) in your AI tool, agent, or code (Cursor, IDE agent, the openai library, your own application), which calls this API at the address below. Free Bitrix24 models work the same way as paid and BYOK models — through the same API.

Scope: vibe:ai | Base URL: https://vibecode.bitrix24.com/v1 | Authorization: the X-Api-Key header or Authorization: Bearer YOUR_API_KEY

You can pay with a subscription. Every router model can be paid for not only from the account wallet but also with the Cowork/Code subscription — including from your own agent. Get the subscription key on the Cowork/Code page; configuring popular agents is covered in Your own agent on the subscription.

OpenAI SDK compatibility

All responses are returned in the raw OpenAI format. Connect any OpenAI-compatible tool (Cursor, IDE agents, the openai library) through the standard settings:

Base URL: https://vibecode.bitrix24.com/v1
API Key:  your key vibe_api_... or vibe_app_...

By default the SDK passes the key in the Authorization: Bearer header — Vibecode accepts both (X-Api-Key and Authorization: Bearer). The request parameters (model, messages, temperature, tools, stream, response_format) and response fields (id, choices, usage) match the POST /v1/chat/completions contract from the OpenAI API.

Documentation sections

• Chat completions — generating a model response in synchronous or streaming mode (Server-Sent Events)
• Models — the list of available models and details of a single model
• Speech recognition — converting audio to text via Whisper Large v3 Turbo
• Embeddings — converting text into vector representations (OpenAI format)
• Your own keys (BYOK) — connecting your own provider keys
• Usage and limits — statistics per key, the company's monthly quota, and off-peak hours
• Your own agent on the subscription — connecting a third-party agent (OpenCode, Crush, Cline, Aider) billed against the Cowork/Code subscription instead of the account wallet
• OpenAI SDK compatibility — configuring Cursor, IDE agents, and any OpenAI-compatible clients
• Model lifecycle — the behavior of ACTIVE / DEPRECATED / DISABLED and the related headers
• Migration from legacy routes — for projects that still call /v1/ai/chat/completions and similar routes

Quick start

1. Generate a response with a free model

curl -X POST https://vibecode.bitrix24.com/v1/chat/completions \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bitrix/bitrixgpt-5.5",
    "messages": [{"role": "user", "content": "What is CRM?"}]
  }'

Response:

{
  "id": "chatcmpl-a1a73c6eb3f180fd",
  "object": "chat.completion",
  "created": 1777289339,
  "model": "bitrix/bitrixgpt-5.5",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "CRM is a customer relationship management system."
      }
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 18,
    "total_tokens": 30
  }
}

2. View available models

curl -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.com/v1/models

Returns only the models that have provider credentials configured in your account. Bitrix24 models (bitrix/*) are available to everyone without separate BYOK keys. Most of them are free.

3. Check token consumption

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://vibecode.bitrix24.com/v1/ai/usage?days=7"

Common use cases

• Lead classification: request leads via GET /v1/leads, run them through a chat completion with response_format: json_object, update CRM fields via PATCH /v1/leads/:id.
• Content generation: read products via GET /v1/products, generate descriptions, update the product cards in the catalog.
• Data extraction: take comments from GET /v1/timeline-logs, extract phone / email / company name, write them to CRM.
• Chatbot: register a bot via POST /v1/bots, receive events via GET /v1/bots/:botId/events, generate an AI response, send it via POST /v1/bots/:botId/messages.
• Reports: collect data via POST /v1/batch, generate a summary, send a notification.

Full example: call transcription → classification → timeline entry

Scenario: get a call recording, transcribe it via Whisper, classify the lead quality via the model's JSON response, write the result to the deal timeline.

Step 1. Speech recognition

curl -X POST https://vibecode.bitrix24.com/v1/audio/transcriptions \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "file=@call-recording.mp3" \
  -F "language=en" \
  -F "response_format=json"

Response:

{
  "text": "Hello, this is Acme LLC. We want a CRM for 50 users, budget up to 500,000 per month."
}

Step 2. Lead classification with guaranteed `JSON`

curl -X POST https://vibecode.bitrix24.com/v1/chat/completions \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bitrix/bitrixgpt-5.5",
    "messages": [
      {
        "role": "system",
        "content": "Classify the lead from the call text. Return JSON: {\"quality\": \"high|medium|low\", \"score\": 0-100, \"reason\": \"...\"}."
      },
      {
        "role": "user",
        "content": "Acme LLC. CRM for 50 users, budget up to 500,000 per month."
      }
    ],
    "response_format": {"type": "json_object"}
  }'

Response:

{
  "id": "chatcmpl-acdb112cf9cdf9f9",
  "object": "chat.completion",
  "model": "bitrix/bitrixgpt-5.5",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "{\"quality\":\"high\",\"score\":88,\"reason\":\"Legal entity, specific volume (50 users) and a budget of 500,000 per month.\"}"
      }
    }
  ],
  "usage": {"prompt_tokens": 92, "completion_tokens": 36, "total_tokens": 128}
}

Step 3. Write the result to the deal timeline

Parse choices[0].message.content as JSON and send it to the timeline:

curl -X POST https://vibecode.bitrix24.com/v1/timeline-logs \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "deal",
    "entityId": 1234,
    "title": "AI classification: high (88/100)",
    "text": "Legal entity, specific volume (50 users) and a budget of 500,000 per month."
  }'

All three endpoints work with the same API key and the same authorization — no separate integrations are required.

Endpoint reference

Error codes

Endpoints fall into two groups by their error response format:

Raw OpenAI format (/v1/chat/completions, /v1/models, /v1/audio/transcriptions):

{
  "error": {
    "message": "...",
    "type": "invalid_request_error",
    "code": "ai_model_not_found"
  }
}

type takes the following values: invalid_request_error (4xx), insufficient_quota (402), service_unavailable (503), server_error (5xx). code is always lowercase.

V1 format (/v1/ai/usage, /v1/ai/credentials/*, /v1/ai/providers):

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "Credential not found"
  }
}

These endpoints return their own expected errors in the V1 format. An unexpected 5xx server error on any /v1/ai/* route is returned in the raw OpenAI format. It also works the other way round: quota and pacing rejections (402 ai_quota_exhausted, 429 ai_pacing_limited) on the OpenAI-compatible endpoints arrive in the envelope with success: false. An error handler must accept both envelopes on either route family.

Whisper / /v1/audio/transcriptions: the processing window is up to 15 minutes. Long / noisy audio may take several minutes. For audio longer than ~30 min, consider splitting it into parts.

System errors

Applicable to any Vibecode API endpoint, including the AI Router section:

For the full list of common API errors, see Errors.

Migration from legacy routes

If your code still calls routes like /v1/ai/chat/completions, /v1/ai/models, or /v1/ai/audio/transcriptions, they keep working in backward-compatibility mode. The response headers carry:

Deprecation: true
X-Deprecated-Use: /v1/chat/completions

X-Deprecated-Use indicates the canonical path. Move the calls to the canonical routes — this removes the Deprecation header and eliminates the risk of the old path being removed in the future.

The routes /v1/ai/usage, /v1/ai/credentials/*, /v1/ai/providers have no legacy equivalent — they are canonical paths.

See also

• Limits and optimization
• Keys and authorization
• CRM Timeline
• Bot platform