Connectors for Cowork and Vibe applications

GET /v1/connectors

POST /v1/connectors/{slug}/access-requests

Access requests are available only to Cowork.

GET /v1/connectors/write-tickets/{id}

Cowork device keys with purpose cowork-desktop keep their employee access flow. A personal application key or OAuth application key is admitted only with explicit effective vibe:connectors, an active application, and matching key owner and Bitrix24 account. While the feature is not enabled for the account, routes return 404 ROUTE_NOT_FOUND. When it is enabled, other keys receive 403 CONNECTOR_KEY_NOT_ALLOWED.

The application acts as the key owner, never the browser viewer or a user supplied in headers. It sees only shared PORTAL connections allowed by the administrator and owner permissions. The scope creates neither a connection nor an administrator rule and grants no employee-viewer access.

The exact application allowlist is GET /v1/connectors, POST /v1/connectors/mcp, GET /v1/connectors/write-tickets/{id} and GET /v1/me. Every other host route or operation, including access requests and connection management, is denied with CONNECTOR_KEY_NOT_ALLOWED. A restricted Cowork employee still receives the catalog with ACCESS_RESTRICTED states; a restricted application owner receives 403 PORTAL_ACCESS_BLOCKED.

The host keeps the key away from the agent. The owner approves writes in the web account. Application polling and pending counts are isolated to this account and the same application and the same key; another application or key cannot read the ticket even with the same owner. Cowork keeps its employee-based flow.

Parameters

Examples

curl — list connectors

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

curl — request access

curl -X POST https://vibecode.bitrix24.com/v1/connectors/bridge-test/access-requests \
  -H "X-Api-Key: YOUR_COWORK_DEVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"note":"Project access"}'

curl — confirmation outcome

curl https://vibecode.bitrix24.com/v1/connectors/write-tickets/5f0c1f7e-2b8a-4c1e-9d6f-3a7b9e2c4d10 \
  -H "X-Api-Key: YOUR_COWORK_DEVICE_KEY"

bridge-test is an example name. Use a slug from the list.

JavaScript — confirmation outcome

const response = await fetch(
  'https://vibecode.bitrix24.com/v1/connectors/write-tickets/5f0c1f7e-2b8a-4c1e-9d6f-3a7b9e2c4d10',
  { headers: { 'X-Api-Key': 'YOUR_COWORK_DEVICE_KEY' } },
)
const result = await response.json()
console.log(result)

Response fields

Success is wrapped in { success: true, data }. The list has the following fields in data.

Cowork opens these regular web account URLs in the system browser. Application keys omit manageUrl, addUrl, and addOwnUrl; existing fields and list ordering are preserved.

type identifies the origin, while connectionScope identifies the connection scope: PORTAL for a company, USER for a personal connection. The built-in Browser is a separate Cowork desktop row. modes describes supported session modes and does not replace the read/write access field mode. Adding these fields preserves existing fields and list order; the query parameter mode (cowork or code) filters by Connector.modes, and omitting it keeps both modes visible.

An access request returns 201 with data.id and data.status = "PENDING". The confirmation outcome has the following fields.

States

Confirmation statuses

Paid call refusals

A tool with a price above zero charges it to the Vibe credit balance of the Bitrix24 account for each successful call. A failure of the external service, a timeout and any gateway refusal are not charged. Before calling the external service, the gateway checks the balance, the daily cap of the account rule and the company budget. On refusal the call is not made, and tools/call answers with a tool error: isError: true and a code in _meta["vibe/error"].code.

For a write tool the check runs before the write confirmation. Without funds no confirmation is created, and an approved confirmation is not consumed by a refusal and stays valid until it expires. After a top-up the repeated call runs without a new approval.

Response example

Example shape of a pending confirmation outcome.

{
  "success": true,
  "data": {
    "status": "PENDING",
    "summary": "bridge-test \u00b7 update_record",
    "expiresAt": "2026-10-01T12:10:00.000Z",
    "webUrl": "https://vibecode.bitrix24.com/connectors/confirm/5f0c1f7e-2b8a-4c1e-9d6f-3a7b9e2c4d10",
    "continueText": null
  }
}

Error response example

429 CONNECTOR_ACCESS_REQUEST_COOLDOWN — the request was rejected less than a day ago.

{
  "success": false,
  "error": {
    "code": "CONNECTOR_ACCESS_REQUEST_COOLDOWN",
    "message": "The request was rejected recently",
    "retryAfter": "2026-10-02T12:00:00.000Z"
  }
}

error.retryAfter is a separate ISO 8601 timestamp. When present for an input error, error.details contains a list of validation paths and messages.

Errors

For common authorization and deletion-freeze errors, see Errors.

Known specifics

• With restricted access, the list returns 200 and every entry has state ACCESS_RESTRICTED. The count includes only accessible Bitrix24 accounts with both flags, active membership and no pending self-deletion.

• Reading a ticket requires both connectors and connectors-write, a live Bitrix24 account, active membership, permitted access and no pending self-deletion in the key’s account. The ticket belongs to that account and the key owner.

• Poll at most once every 3 seconds. Platform-wide ceilings: list 120/min per key, request 10/hour per key, polling 1200/min total per key and 60/min per key-ticket pair. Ceilings are divided across replicas, and the active route limit is returned in x-ratelimit-limit.

• Pass continueText to the agent verbatim for every status except PENDING. The gateway uses the approval before calling the external service. The repeated call’s result, rather than status CONSUMED, reports whether the write succeeded or failed.

• Writing also requires connectors-write and an eligible desktop version. In production, connectorsWriteMinDesktopVersion remains null until the operator decides to enable it. An empty setting blocks writing for everyone.

See also

• Connector gateway
• Keys and authorization

Long-running BRIDGE operations

The host retains the action UUID in params._meta["vibe/idempotencyKey"] and retries a lost start with the same UUID and arguments. To retrieve pending work it calls connectors_get_result({operationId}) through POST /v1/connectors/mcp with the original key. No new V1 URL or key is needed. Live access and ownership checks also apply to replay; reconnecting or revoking access hides the old payload but does not cancel settlement of accepted successful work.

A paid WRITE first requires owner approval; retry the same UUID afterwards. Replaying an accepted operation consumes no second ticket and incurs no second charge. A timeout does not mean cancellation. Pending remains in the journal with the original call time and no paid amount until completion. Examples, lifetimes and limits: MCP BRIDGE operations.

Request-local gateway selection

POST /v1/connectors/mcp

Send optional X-Cowork-Connectors-Enabled: bridge-test,crm and X-Cowork-Mode: cowork (or code) on every HTTP request. Enabled is an ASCII CSV of at most 100 connector slugs and 8192 bytes. An empty header disables all connectors; absence preserves the original set. Invalid headers return 400 INVALID_BODY. Individual tool selection is not supported.

The stateless gateway does not retain headers from initialize. Filtering applies before the direct-tool threshold, to list/discovery and to direct calls and connectors_run_tool. Account rules and platform-disabled tools still apply. Mode filters a connector when its modes metadata is available; legacy records without metadata retain availability. Omitting both headers preserves the original response. Retrieve already accepted jobs through connectors_get_result with the existing ownership and live-access checks.

curl https://vibecode.bitrix24.com/v1/connectors/mcp \
  -H "X-Api-Key: YOUR_COWORK_DEVICE_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-Cowork-Connectors-Enabled: bridge-test" \
  -H "X-Cowork-Mode: cowork" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Omit the last two headers for the original selection. Connection setup, OAuth and rule changes are performed in the web cabinet.

Published connector card

GET /v1/connectors/{slug}

Only Cowork device keys can read this card; the Application allowlist remains unchanged. The response is { success: true, data } for one catalog connector.

data.tools contains { name, title, readOnly } from the published version, excluding platform-disabled tools. These labels describe tools; the gateway checks execution permission separately. Company and publisher are independent: vendor is { name, url } or null, publisher is { name, url }. For catalog connectors, verified is derived and always true. modes contains cowork and/or code; legacy metadata supports both. When company metadata is absent, vendor is null rather than copied from publisher.

The card also includes title, summary, description, setupHint, category, iconUrl, connectionScope, state, mode, retryAfter, pendingRequestId, pricing, authType, grant, dataLocation, dataLocationNote, webUrl and companyConnected. addedAt is the visible connection creation time or null; vaultReady indicates whether connection storage is configured. No connection forms or secret values are returned. A personal connection is scoped to the owner. Company connection metadata is visible only to administrators; other employees receive connection: null and addedAt: null. A connector blocked by the account is hidden from everyone, including administrators, with 404 CONNECTOR_NOT_FOUND. Missing or unpublished connectors return the same error. Restricted owners receive 403 PORTAL_ACCESS_BLOCKED.

curl https://vibecode.bitrix24.com/v1/connectors/bridge-test \
  -H "X-Api-Key: YOUR_COWORK_DEVICE_KEY"

Connection setup and settings use webUrl in the browser. The Cowork card and catalog share the cabinet URL /extensions/connectors/<slug>.