Эндпоинты раздела «Cowork/Code»

Методы раздела Cowork/Code: чтение состояния подписки — тариф, состояние и расход квоты по трём окнам в процентах, предрасчёт списания при смене тарифа, включение пробного периода Маркета, самостоятельная выдача проектного ключа с правом деплоя, отключение текущего устройства, выдача десктопу билета для телефонного доступа, создание личного приложения вместе с его ключом, а также проверка и погашение купона на тариф.

Скоуп: vibe:cowork

Состояние подписки Cowork/Code

GET /v1/cowork/state

Возвращает полный снимок состояния подписки Cowork/Code: тариф, состояние подписки, расход трёх окон квоты в процентах, рекомендацию по ожиданию или переходу на тариф выше и каталог тарифов для сравнительной таблицы.

Примеры

curl — личный ключ

curl https://vibecode.bitrix24.tech/v1/cowork/state \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth-приложение

curl https://vibecode.bitrix24.tech/v1/cowork/state \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — личный ключ

const res = await fetch('https://vibecode.bitrix24.tech/v1/cowork/state', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

if (!res.ok) {
  const { error } = await res.json()
  console.error(error.code, error.message)
} else {
  const state = await res.json()
  const tight = state.windows[state.bottleneck]
  console.log(`Окно ${state.bottleneck}: ${tight.pctUsed}%`, tight.exhausted ? 'исчерпано' : 'ок')
}

JavaScript — OAuth-приложение

const res = await fetch('https://vibecode.bitrix24.tech/v1/cowork/state', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const state = await res.json()

Поля ответа

Ключи offPeak и touSavedPct приходят в каждом успешном ответе.

Ключ relief приходит в каждом успешном ответе. null внутри блока — это отдельный смысл, а не отсутствие данных.

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

{
  "portal": {
    "id": "d41f0b93-6c85-42e7-9a13-58bd0e7c2f46",
    "domain": "mycompany.bitrix24.ru"
  },
  "subscription": {
    "tier": "FREE",
    "state": "ACTIVE",
    "currentPeriodStart": "2026-06-01T00:00:00.000Z",
    "currentPeriodEnd": "2026-07-01T00:00:00.000Z",
    "nextChargeAt": null,
    "cancelAtPeriodEnd": false,
    "pendingTier": null,
    "termMonths": 1,
    "paidThroughAt": "2026-05-15T00:00:00.000Z"
  },
  "windows": {
    "fiveHour": { "pctUsed": 40, "resetAt": "2026-06-09T17:30:00.000Z", "exhausted": false },
    "week":     { "pctUsed": 24, "resetAt": "2026-06-12T09:00:00.000Z", "exhausted": false },
    "month":    { "pctUsed": 20, "resetAt": "2026-07-01T00:00:00.000Z", "exhausted": false }
  },
  "bottleneck": "fiveHour",
  "recommendation": {
    "reason": "none",
    "triggerWindow": null,
    "wait": null,
    "upgrade": { "available": true, "nextTier": "PRO" }
  },
  "tiers": [
    { "tier": "FREE",  "multiplier": null,  "feeVibes": 0,     "current": true,  "isNext": false },
    { "tier": "PRO",   "multiplier": "×1",  "feeVibes": 2000,  "current": false, "isNext": true  },
    { "tier": "MAX",   "multiplier": "×5",  "feeVibes": 10000, "current": false, "isNext": false },
    { "tier": "ULTRA", "multiplier": "×20", "feeVibes": 20000, "current": false, "isNext": false }
  ],
  "serverTime": "2026-06-09T14:05:00.000Z",
  "offPeak": {
    "enabled": true,
    "visible": "now",
    "timezone": "Europe/Moscow",
    "currentMultiplier": 0.5,
    "currentWindowEndsInHours": 6,
    "nextAtOrBelow": { "inHours": 1, "multiplier": 0.5 },
    "perModel": false,
    "modelName": null,
    "grid": [
      [0.75, 0.87, 0.87, 0.87, 0.87, 0.87, 0.87, 0.87, 0.75, 0.75, 0.75, 0.75, 0.62, 0.5, 0.75, 0.87, 1, 1, 0.87, 0.87, 0.87, 0.75, 0.75, 0.75],
      [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.62, 0.62, 0.62, 0.62, 0.75, 0.75, 0.87, 0.87, 0.75, 0.75, 0.75, 0.75, 0.62, 0.5, 0.5],
      [0.5, 0.5, 0.62, 0.62, 0.75, 0.62, 0.62, 0.62, 0.75, 0.75, 0.87, 1, 1, 0.87, 0.75, 0.87, 0.87, 0.75, 0.75, 0.62, 0.62, 0.62, 0.62, 0.62],
      [0.75, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.62, 0.62, 0.62, 0.75, 0.75, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0.87],
      [1, 1, 1, 1, 1, 0.87, 0.87, 0.87, 0.87, 1, 1, 1, 1, 1, 1, 0.87, 0.75, 0.75, 0.75, 0.87, 1, 1, 1, 1],
      [1, 1, 1, 1, 1, 0.87, 0.87, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0.87, 0.87, 0.75, 0.87],
      [0.75, 0.62, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.62, 0.75, 0.75, 0.62, 0.62, 0.75, 0.75, 0.87, 0.87, 1, 1, 1, 1, 0.87]
    ],
    "nowCell": { "dow": 1, "hour": 3 }
  },
  "touSavedPct": 12.4,
  "activation": {
    "model": "tariff",
    "tariffInfoUrl": "https://www.bitrix24.ru/prices/",
    "marketTrial": {
      "available": false,
      "unavailableReason": "region_not_supported",
      "status": "not_attempted",
      "endsAt": null,
      "activatedAt": null
    }
  },
  "relief": {
    "resetGrantedAt": "2026-06-09T12:00:00.000Z",
    "boostGrantedAt": null
  }
}

В примере показан аккаунт тарифного региона. У российского и белорусского аккаунта activation.model будет subscription, а ключа tariffInfoUrl не будет вовсе. Значение marketTrial.available у такого аккаунта может быть true. Оно приходит false с причиной not_required_for_data, когда платформа больше не считает подписку Маркета условием для чтения данных компании этим ключом — предлагать включение пробного периода в этом случае не нужно. Тип аккаунта на это не влияет: облачный и на собственном сервере отвечают одинаково.

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

404 — подписка не активирована:

{
  "success": false,
  "error": {
    "code": "COWORK_NOT_ACTIVATED",
    "message": "No active Cowork/Code subscription for this user+portal"
  }
}

Ошибки

Полный список общих ошибок API — Ошибки.

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

Успешный ответ (200) — это сам объект состояния, без обёртки success. Ошибки приходят в конверте { success: false, error: { code, message } }. Определяйте успех по HTTP-статусу (res.ok).

Признак исчерпания окна — поле exhausted, а не pctUsed === 100. Значение pctUsed округляется до целого: 99,6 % отображается как 100, хотя окно ещё не исчерпано.

Время до сброса отсчитывайте от serverTime, а не от часов устройства — расхождение часов клиента и сервера исказит счётчик.

Окна сбрасываются лениво при чтении — если запросов не было с момента сброса, он применяется при обращении к эндпоинту, поэтому снимок всегда актуален.

Опрашивайте не чаще одного раза в 15–30 секунд. Ответ не кэшируется (Cache-Control: no-store). У эндпоинта есть предел частоты — общий на аккаунт и владельца ключа, то есть все устройства одного человека делят его. Рекомендованный интервал укладывается в предел с большим запасом, а сверх него приходит 429 RATE_LIMITED.

PARKED — место без активного владельца. Платное место переходит в это состояние, когда его владелец перестаёт быть активным участником портала, а оплаченный срок ещё не закончился. За такое место ничего не списывается, а тариф и оплаченный срок сохраняются. Администратор портала может передать место другому сотруднику. В течение суток после окончания оплаченного срока место переходит в PAUSED.

Блока activation может не быть в ответе вовсе — так отвечает платформа, которая про него ещё не знает. Это штатное состояние: блока нет — работайте как раньше. Если блок есть, поля available и unavailableReason внутри него присутствуют всегда, поэтому проверяйте наличие БЛОКА и читайте ЗНАЧЕНИЕ поля, а не наоборот.

activation.marketTrial.available — прогноз, а не гарантия. Значение false окончательно: шаг включения пробного периода показывать не нужно. Значение true означает «предлагать можно», но не обещает успех: состояние аккаунта может измениться между запросом и нажатием, а окончательное решение остаётся за Битрикс24 — обработку отказа на самом включении оставьте.

Список причин в unavailableReason может пополняться. Неизвестное значение читайте как «активацию не предлагать», без отдельной ветки. Так же и со status.

Ссылка activation.tariffInfoUrl — общая страница условий, а не адрес вашего аккаунта. Значение постоянное, в ответе оно может отсутствовать (подписочный регион, коробочный аккаунт) — экран обязан пережить отсутствие ссылки. Не сохраняйте её у себя и не разбирайте домен.

Пустое relief.boostGrantedAt не означает, что увеличения лимитов нет. Отметка нужна для разового уведомления и видна 7 суток, а само увеличение выдают на срок до 30 суток. Увеличение, выданное больше семи суток назад, отдаёт пустую отметку и при этом продолжает действовать. Действует увеличение или нет, показывает только boostPct.

Значение блока relief совпадает с тем, что отдаёт сводка по подписке. Отметку, о которой вы уже сообщили пользователю, запоминайте один раз на приложение, а не отдельно по каждому эндпоинту, иначе одна компенсация будет показана дважды. Уведомляйте только когда пришло непустое значение, отличное от запомненного: сервер намеренно переводит отметку в null (закрылось окно видимости, истёк или отозван буст, место передали), и правило «изменилось — покажи» дало бы ложное уведомление на каждом таком переходе.

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

• Сводка по подписке Cowork/Code
• Выгодные часы в подписке Cowork/Code
• Cowork/Code
• Лимиты и оптимизация
• Ошибки