Состояние подписки 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 приходят, только когда выгодные часы включены для аккаунта. Пока возможность не включена, их нет в теле ответа вовсе, и в примере ниже они не показаны.

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

{
  "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
  },
  "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",
  "activation": {
    "model": "tariff",
    "tariffInfoUrl": "https://www.bitrix24.ru/prices/",
    "marketTrial": {
      "available": false,
      "unavailableReason": "region_not_supported",
      "status": "not_attempted",
      "endsAt": null,
      "activatedAt": null
    }
  }
}

В примере показан аккаунт тарифного региона. У российского и белорусского аккаунта activation.model будет subscription, ключа tariffInfoUrl не будет вовсе, а marketTrial.available может быть true.

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

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.

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

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

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

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

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

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