Send a solution event

POST /v1/solution-events

A solution reports an event to the Bitrix24 account, and business processes with the "Vibecode solution event" trigger start on that account on behalf of the owner of the solution card in the account's catalog. The call is synchronous: the platform passes the event to the Bitrix24 account immediately.

Access

Call the endpoint with an application key. Use the application's personal key or the key of the OAuth application it is built on. Key types are described in Keys and authorization. A developer key not bound to an application gets 403 SOLUTION_KEY_REQUIRED. The application's external API key does not work here: 403 APP_API_KEY_OUT_OF_SCOPE. The platform finds the card and the Bitrix24 account by the key; you do not need to pass them.

Until the feature is enabled for the Bitrix24 account, the endpoint responds with 409 SOLUTION_EVENTS_NOT_ENABLED.

A key in "read-only" mode cannot send events and gets 403 WRITE_BLOCKED_READONLY_KEY: the card owner's processes change Bitrix24 account data.

Request fields (body)

The body must contain no other fields: otherwise 400 UNKNOWN_FIELD.

Size and bytes of `data`

• Size is measured on the compact serialization of data without spaces or line breaks, in UTF-8 bytes.
• The Bitrix24 account remembers the event by the key and the exact bytes of data. Send a retry with the same object and the same key order, otherwise you get 409 EVENT_KEY_CONFLICT.
• Integers larger than 2^53 lose precision when parsed: send them as strings.
• JavaScript puts integer keys such as "1" and "20" at the start of an object. This does no harm as long as the retry is built by the same code.

Examples

The request body is the same in all examples. Only the headers differ.

curl — personal key

curl -X POST "https://vibecode.bitrix24.com/v1/solution-events" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"idempotencyKey": "order-8812-paid", "data": {"orderId": 8812, "status": "paid"}}'

curl — OAuth application

curl -X POST "https://vibecode.bitrix24.com/v1/solution-events" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"idempotencyKey": "order-8812-paid", "data": {"orderId": 8812, "status": "paid"}}'

JavaScript — personal key

const event = { idempotencyKey: 'order-8812-paid', data: { orderId: 8812, status: 'paid' } };

const res = await fetch('https://vibecode.bitrix24.com/v1/solution-events', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  // Retry with the same event object: the Bitrix24 account compares the key and the exact bytes of data.
  body: JSON.stringify(event),
});
const body = await res.json();
if (!body.success && body.error.retryable) {
  const waitSeconds = Number(res.headers.get('retry-after') ?? 30);
  // Retry the request with the same event no sooner than waitSeconds seconds later.
}

JavaScript — OAuth application

const event = { idempotencyKey: 'order-8812-paid', data: { orderId: 8812, status: 'paid' } };

const res = await fetch('https://vibecode.bitrix24.com/v1/solution-events', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  // Retry with the same event object: the Bitrix24 account compares the key and the exact bytes of data.
  body: JSON.stringify(event),
});
const body = await res.json();
if (!body.success && body.error.retryable) {
  const waitSeconds = Number(res.headers.get('retry-after') ?? 30);
  // Retry the request with the same event no sooner than waitSeconds seconds later.
}

Response fields

accepted does not mean a process has started. One event starts as many processes as there are templates on the Bitrix24 account waiting for this trigger, and none if there are no such templates: the Bitrix24 account still responds with accepted. A retry of an accepted event gets duplicate, even if the feature was later turned off on the Bitrix24 account itself or the card was made inactive.

Response example

{ "success": true, "data": { "status": "accepted", "idempotencyKey": "order-8812-paid" } }

Error response example

409 — the solution card is inactive on the Bitrix24 account:

{ "success": false, "error": { "code": "CARD_INACTIVE", "message": "The solution's catalog card is inactive on the Bitrix24 account.", "retryable": false } }

error.retryable appears only in the method's own responses: true — retry after a pause.

Errors

Common responses for all key methods: 401 for a missing, invalid or expired key and NO_PORTAL, 402 ACCOUNT_FROZEN, 403 for blocks on the key owner or the Bitrix24 account and for key-mode restrictions, 429 CALLER_RATE_LIMITED, 429 QUOTA_EXCEEDED, 503 POOL_EXHAUSTED, 503 user_self_deletion_pending. The last one means the key owner is deleting their user account on the Bitrix24 account: Retry-After is 604800, and retrying is pointless until the deletion is cancelled. Common responses have no error.retryable field.

Events are not billed as API calls. But the key's daily quota is shared by all methods: a key that has exhausted it with Bitrix24 calls while the prepaid balance is empty gets 429 QUOTA_EXCEEDED on events too.

The full list of common API errors — Errors.

What to do with the response

The pause is at least Retry-After and doubles with each attempt: 30 s, 1 min, 2 min and so on up to 1 hour. Retries count against the same limit as new events: retries during a long Bitrix24 account outage crowd out fresh events. Set your client's timeout to at least 30 seconds.

Event history: when the same key is safe

On a retry, send the same key and data. Decide by the whole event history, not by the last response. An attempt with a "yes" response is one whose response falls in a table row where the Bitrix24 account could have accepted the event.

• The 24-hour window is counted from the first attempt with a "yes" response and is not reset by later responses. After that, decide whether to treat the event as lost or accepted, and show it to a person.
• The history is closed by the Bitrix24 account's response to an attempt sent no sooner than 6 minutes after the last attempt with a "yes" response. 200 — the event is accepted; the history ends. 409 PORTAL_FEATURE_DISABLED, CARD_NOT_FOUND, CARD_INACTIVE, OWNER_INACTIVE, SOLUTION_NOT_ELIGIBLE, TARIFF_RESTRICTED, CARD_NOT_BOUND and 503 LOOKUP_FAILED, BIZPROC_UNAVAILABLE, START_FAILED — the Bitrix24 account checked the key and did not find it; earlier "yes" attempts are cleared. EVENT_KEY_CONFLICT with an uncleared "yes" means "accepted".
• The history is not closed by the remaining 409 responses. These are platform refusals before the Bitrix24 account is called: SOLUTION_EVENTS_NOT_ENABLED, CARD_NOT_PUBLISHED, PORTAL_NOT_PAIRED, PORTAL_DOMAIN_NOT_SUPPORTED, and PORTAL_NOT_SUPPORTED from an outdated Bitrix24 account module. All of them arrive before the key check and know nothing about past attempts, as do 502, 429, 401, 402, 403, 503 CHANNEL_UNAVAILABLE, POOL_EXHAUSTED, STORAGE_FAILED, EVENT_IN_PROGRESS.
• The same key is safe at any time if the history has no "yes", or none since it was closed.
• The ceiling without a "yes": the whole history lasts no longer than 24 hours from the first attempt or, after a closing response, from that response. You cannot fix 409 responses or QUOTA_EXCEEDED yourself: retry them no more than once an hour. When time runs out, show the event to a person as undelivered with the last code. Only that person resends it, with the same key.

Limits

No more than 60 events per minute per key and 120 per minute per Bitrix24 account, counting all solutions on the Bitrix24 account together. The x-ratelimit-limit header shows the per-key limit: 60 where the counter is shared, and a share of one platform node where it is not. The Bitrix24 account limit is visible only through a 429 refusal.

See also

• Application external API
• A long-running method in a business process
• Keys and authorization
• Errors