Connectors for the Cowork desktop

GET /v1/connectors

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

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

The Cowork desktop lists services for the employee, requests access and reads the outcome of a write confirmation.

Only a device key with purpose cowork-desktop is accepted. Other keys receive 403 CONNECTOR_KEY_NOT_ALLOWED. The host stores the key and never passes it to the agent. The person makes confirmation decisions in the web account.

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.

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

States

Confirmation statuses

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