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

GET /v1/cowork/state

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

Скоуп: vibe:cowork · Авторизация: X-Api-Key · Кэширование: Cache-Control: no-store

#Примеры

#curl

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

#JavaScript

const res = await fetch('https://vibecode.bitrix24.tech/v1/cowork/state', {
  headers: { 'X-Api-Key': 'YOUR_COWORK_KEY' }
})
if (!res.ok) {
  const { error } = await res.json()
  console.error(error.code, error.message)
} else {
  const { windows, recommendation, serverTime } = await res.json()
  const remaining = windows.fiveHour.remaining
  const resetIn = (new Date(windows.fiveHour.resetAt) - new Date(serverTime)) / 1000
  console.log(`Осталось квоты: ${remaining}, сброс через ${Math.ceil(resetIn)}с`)
}

#Поля ответа

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

{
  "subscription": {
    "tier": "FREE",
    "state": "ACTIVE",
    "currentPeriodStart": "2026-06-01T00:00:00.000Z",
    "currentPeriodEnd": "2026-07-01T00:00:00.000Z",
    "nextChargeAt": null,
    "cancelAtPeriodEnd": false
  },
  "windows": {
    "fiveHour": { "used": 40, "total": 100, "remaining": 60, "pctUsed": 40, "resetAt": "2026-06-02T17:30:00.000Z", "exhausted": false },
    "week":     { "used": 120, "total": 500, "remaining": 380, "pctUsed": 24, "resetAt": "2026-06-09T09:00:00.000Z", "exhausted": false },
    "month":    { "used": 300, "total": 1500, "remaining": 1200, "pctUsed": 20, "resetAt": "2026-07-01T00:00:00.000Z", "exhausted": false }
  },
  "bottleneck": "fiveHour",
  "recommendation": {
    "reason": "none",
    "triggerWindow": null,
    "wait": null,
    "upgrade": { "available": true, "nextTier": "START" }
  },
  "tiers": [
    { "tier": "FREE",  "feeVibes": 0,     "monthTotal": 1500,    "weekCap": 500,    "fiveHourCap": 100,   "current": true,  "isNext": false },
    { "tier": "START", "feeVibes": 2000,  "monthTotal": 50000,   "weekCap": 14000,  "fiveHourCap": 2500,  "current": false, "isNext": true  },
    { "tier": "PRO",   "feeVibes": 10000, "monthTotal": 250000,  "weekCap": 70000,  "fiveHourCap": 12500, "current": false, "isNext": false },
    { "tier": "MAX",   "feeVibes": 40000, "monthTotal": 1000000, "weekCap": 280000, "fiveHourCap": 50000, "current": false, "isNext": false }
  ],
  "serverTime": "2026-06-02T14:05:00.000Z"
}

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

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

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

#Ошибки

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

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

• Успешный ответ (200) — это сам объект состояния, без обёртки success. Ошибки возвращаются в конверте { success: false, error: { code, message } }. Определяйте успех по HTTP-статусу (res.ok), а не по полю success.
• Признак исчерпания — remaining === 0 или exhausted: true, не pctUsed === 100. Поле pctUsed округляется до целого числа: 99,6% отображается как 100, хотя остаток ещё есть. Для точного определения блокировки используйте exhausted или проверяйте remaining === 0.
• Время обратного отсчёта — от serverTime, не от часов устройства. Вычисляйте «до сброса» как new Date(resetAt) - new Date(serverTime). Разница между серверным и местным временем может существенно исказить счётчик.
• Три окна вложены друг в друга: 5ч ⊂ неделя ⊂ месяц. Блокировка наступает при исчерпании любого из них. Поле bottleneck всегда указывает на наиболее нагруженное окно.
• Окна сбрасываются лениво при чтении. Если пользователь не делал запросов с момента последнего сброса, сброс применяется в момент обращения к эндпоинту — снимок всегда актуален.
• Ответ не кэшируется. Заголовок Cache-Control: no-store — не кэшируйте ответ на стороне клиента. Рекомендуемый интервал опроса — 15–30 секунд в активном режиме.
• recommendation.upgrade.nextTier соответствует записи с isNext: true в массиве tiers. Лимиты следующего тарифа берите из этой записи — не нужен отдельный запрос.
• wait.resetAt — позднейший из сброшенных пустых окон. Когда несколько окон исчерпаны одновременно, wait.resetAt указывает на то, которое сбросится последним. После этого момента запросы снова будут приниматься.

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

• GET /v1/cowork/me — упрощённый эндпоинт: базовые данные о подписке (только проценты) без рекомендаций и каталога тарифов
• Ошибки
• Лимиты и оптимизация