Коннекторы для Коворка и приложений Вайбкод

GET /v1/connectors

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

Заявки на доступ доступны только Коворку.

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

Ключ устройства Коворка с назначением cowork-desktop сохраняет доступ от лица сотрудника. Персональный ключ приложения Вайбкод или OAuth-ключ приложения допускается только с явно выданным действующим vibe:connectors, действующим приложением и совпадающими владельцем и порталом ключа. Пока функция не включена для портала, маршруты отвечают 404 ROUTE_NOT_FOUND. При включённой функции остальные ключи получают 403 CONNECTOR_KEY_NOT_ALLOWED.

Приложение действует от лица владельца ключа, а не сотрудника, открывшего страницу, или пользователя из заголовков. Оно видит только общие подключения PORTAL, разрешённые администратором и правами владельца. Скоуп не создаёт подключение или правило администратора и не выдаёт доступ по сотруднику-зрителю.

Точный белый список приложения: GET /v1/connectors, POST /v1/connectors/mcp, GET /v1/connectors/write-tickets/{id} и GET /v1/me. Все остальные ручки и операции хоста, включая заявки на доступ и управление подключениями, закрыты с CONNECTOR_KEY_NOT_ALLOWED. Ограниченный сотрудник Коворка по-прежнему получает каталог с состояниями ACCESS_RESTRICTED; ограниченный владелец приложения получает 403 PORTAL_ACCESS_BLOCKED.

Хост хранит ключ и не передаёт его агенту. Запись владелец подтверждает в веб-кабинете. Билеты приложения и счётчик ожидания ограничены текущим порталом и тем же приложением и тем же ключом; даже другой ключ того же владельца не прочитает билет. Коворк сохраняет прежнюю семантику сотрудника.

Параметры

Примеры

curl — список коннекторов

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

curl — заявка на доступ

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

curl — исход подтверждения

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

bridge-test — условное имя в примере. Подставьте slug из списка.

JavaScript — исход подтверждения

const response = await fetch(
  'https://vibecode.bitrix24.tech/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)

Поля ответа

Успех обёрнут в { success: true, data }. Для списка data содержит следующие поля.

Заявка отвечает 201 с data.id и data.status = "PENDING". Исход подтверждения содержит следующие поля.

Состояния

Статусы подтверждения

Отказы платного вызова

Инструмент с ценой больше нуля списывает её с баланса Вайбов портала за каждый успешный вызов. Сбой внешнего сервиса, таймаут и любой отказ шлюза не списываются. Перед обращением к внешнему сервису шлюз проверяет баланс, суточный потолок правила портала и бюджет компании. При отказе вызов не выполняется, а tools/call отвечает ошибкой инструмента: isError: true и код в _meta["vibe/error"].code.

Для пишущего инструмента проверка идёт до подтверждения записи. Без денег подтверждение не создаётся, а одобренное подтверждение при отказе не расходуется и действует до своего срока. После пополнения повторный вызов исполняется без нового одобрения.

Пример ответа

Пример структуры исхода ожидающего подтверждения.

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

Пример ответа при ошибке

429 CONNECTOR_ACCESS_REQUEST_COOLDOWN — заявка отклонена менее суток назад.

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

error.retryAfter — отдельное время ISO 8601. error.details, если присутствует при ошибке ввода, содержит список путей и сообщений проверки.

Ошибки

Общие ошибки авторизации и заморозки — Ошибки.

Известные особенности

• Список при ограниченном доступе отвечает 200, все записи имеют ACCESS_RESTRICTED. Счётчик учитывает только доступные порталы с обоими флагами, активным членством и без самоудаления.

• Чтение тикета требует обоих флагов connectors и connectors-write, живого портала, активного членства, разрешённого доступа и отсутствия самоудаления по порталу ключа. Тикет принадлежит этому же порталу и владельцу ключа.

• Опрос — не чаще раза в 3 секунды. Платформенные потолки: список 120/мин на ключ, заявка 10/час на ключ, опрос 1200/мин суммарно на ключ и 60/мин на пару ключ–тикет. Потолки делятся на реплики, действующее значение маршрута приходит в x-ratelimit-limit.

• Передавайте continueText агенту дословно для любого статуса кроме PENDING. Шлюз использует одобрение до обращения к внешнему сервису. Результат повторного вызова, а не статус CONSUMED, показывает успех или ошибку записи.

• Запись дополнительно требует connectors-write и подходящей версии десктопа. В продуктовой среде connectorsWriteMinDesktopVersion остаётся null до решения оператора. Пустая настройка закрывает запись всем.

Смотрите также

• Шлюз коннекторов
• Ключи и авторизация

Долгие операции BRIDGE

Хост сохраняет UUID действия в params._meta["vibe/idempotencyKey"] и повторяет потерянный запуск с теми же UUID и аргументами. Для результата pending он вызывает connectors_get_result({operationId}) через POST /v1/connectors/mcp с прежним ключом. Новый V1-адрес и новый ключ не нужны. Правила живого доступа и владения действуют и при повторе; переподключение или отзыв доступа скрывает старое содержимое, но не отменяет расчёт принятого успешного вызова.

Платный WRITE сначала требует одобрения владельца; после него повторяют тот же UUID. Повтор принятой операции не расходует второй билет и не создаёт второго списания. Таймаут не означает отмену. Pending остаётся в журнале с исходным временем вызова и без оплаченной суммы до завершения. Примеры, сроки и ограничения: операции MCP BRIDGE.