# Подписка Cowork/Code

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

**Скоуп:** `vibe:cowork` | **Базовый URL:** `https://vibecode.bitrix24.tech/v1` | **Авторизация:** `X-Api-Key`

[Три окна квоты](#три-окна-квоты) | [Тарифы](#тарифы) | [Как начать](#как-начать) | [Быстрый старт](#быстрый-старт) | [Полный пример](#полный-пример-слежение-за-квотой) | [Справочник эндпоинтов](#справочник-эндпоинтов) | [Коды ошибок](#коды-ошибок)

## Что такое Cowork/Code

Одна подписка даёт одну квоту на AI-запросы — её тратят три инструмента из общего баланса:

- **Cowork** — настольное приложение с AI-ассистентом для работы с порталом Битрикс24.
- **Code** — режим написания и публикации приложений внутри настольного приложения.
- **AI Agent** — автономные AI-агенты.

Квота покрывает только AI и только пока подписка подключена и активна. Собственный сервер, на котором работает AI-агент, оплачивается из кошелька портала отдельно.

Преимущества единой подписки:

- Общий баланс на три инструмента вместо отдельных лимитов.
- Бесплатный тариф активен сразу — оплата не требуется, чтобы начать.
- Расход показан в процентах, перерасхода нет — лимит предсказуем.
- Масштабируется тарифами `×1` → `×5` → `×20` под рост задач.

Пока подписка подключена и активна, агенты и режим Code расходуют её квоту автоматически — отдельно настраивать ничего не нужно. Собственный сервер AI-агента при этом оплачивается из кошелька портала и в квоту подписки не входит.

## Три окна квоты

Расход квоты считается одновременно в трёх вложенных окнах:

| Окно | Назначение |
|------|------------|
| 5 часов | ограничение кратковременных всплесков |
| Неделя | среднесрочный лимит |
| Месяц | совпадает с расчётным периодом подписки |

Работа блокируется при исчерпании **любого** из окон. У каждого окна есть процент использования и время сброса. Абсолютные числа квоты наружу не отдаются — и `/v1/cowork/state`, и `/v1/cowork/me` показывают только проценты.

## Тарифы

| Тариф | Множитель | Объём квоты |
|-------|-----------|-------------|
| Free | — | базовая квота, активна сразу |
| Pro | `×1` | базовый платный объём |
| Max | `×5` | в пять раз больше объёма, чем Pro |
| Ultra | `×20` | в двадцать раз больше объёма, чем Pro |

Множитель `×N` задаёт объём квоты во всех трёх окнах относительно тарифа Pro (`×1`). Стоимость каждого тарифа приходит отдельно, в поле `feeVibes` (в Вайбах за месяц), и актуальна на момент запроса.

## Как начать

1. Откройте раздел Cowork/Code в личном кабинете.
2. Бесплатный тариф активен сразу — квота доступна без подключения.
3. Нужно больше квоты — выберите тариф Pro, Max или Ultra.
4. Для вызова эндпоинтов этого раздела используйте ключ авторизации со скоупом `vibe:cowork` — передавайте его в заголовке `X-Api-Key`.
5. Агенты и режим Code используют квоту этой подписки автоматически, пока она подключена и активна.

Подробнее о ключах и скоупах — [Ключи и авторизация](/docs/keys-auth).

## Быстрый старт

Текущее состояние подписки одним запросом:

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

```json
{
  "subscription": { "tier": "FREE", "state": "ACTIVE", "nextChargeAt": null, "cancelAtPeriodEnd": false },
  "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", "upgrade": { "available": true, "nextTier": "PRO" } }
}
```

## Полный пример: слежение за квотой

Скрипт опрашивает состояние подписки и реагирует на приближение к лимиту и на исчерпание квоты.

```javascript
const BASE = 'https://vibecode.bitrix24.tech/v1'
const API_KEY = process.env.VIBE_KEY

async function checkQuota() {
  const res = await fetch(`${BASE}/cowork/state`, {
    headers: { 'X-Api-Key': API_KEY },
  })

  if (!res.ok) {
    const { error } = await res.json()
    console.error('Cowork/Code:', error.code, error.message)
    return
  }

  const state = await res.json()
  const { windows, bottleneck, recommendation } = state

  // Самое нагруженное окно
  const tight = windows[bottleneck]
  console.log(`Окно ${bottleneck}: ${tight.pctUsed}%`)

  // Квота исчерпана — показываем, когда снова можно работать
  if (recommendation.wait) {
    const seconds = Math.ceil((new Date(recommendation.wait.resetAt) - new Date(state.serverTime)) / 1000)
    console.log(`Лимит исчерпан, сброс через ${seconds} с`)
  }

  // Приближение к лимиту — предлагаем тариф выше
  if (recommendation.reason === 'approaching' && recommendation.upgrade.nextTier) {
    console.log(`Стоит перейти на тариф ${recommendation.upgrade.nextTier}`)
  }
}

// Опрос раз в 30 секунд
setInterval(checkQuota, 30_000)
checkQuota()
```

## Справочник эндпоинтов

| Метод | Путь | Описание |
|-------|------|----------|
| GET | [/v1/cowork/state](/docs/cowork/state) | Полное состояние: окна квоты, рекомендация, каталог тарифов |
| GET | [/v1/cowork/me](/docs/cowork/me) | Краткая сводка: тариф, состояние, проценты квоты |
| POST | [/v1/cowork/deploy-key](/docs/cowork/deploy-key) | Проектный ключ с правом деплоя (скоупы `vibe:infra` + `vibe:storage`, 7 дней) |

Интерактивный переключатель методов с примерами и полями ответа — [Эндпоинты](/docs/cowork/endpoints).

## Коды ошибок

| HTTP | Код | Описание |
|------|-----|----------|
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `INVALID_API_KEY` | Неверный API-ключ |
| 403 | `INSUFFICIENT_SCOPE` | У ключа нет скоупа `vibe:cowork` |
| 404 | `COWORK_NOT_ACTIVATED` | Подписка Cowork/Code не найдена для пары пользователь и портал |
| 500 | `INVALID_TIER_CONFIGURATION` | Конфигурация тарифов на платформе некорректна |
| 503 | `COWORK_FEATURE_DISABLED` | Cowork/Code отключён на уровне платформы |

Полный список общих ошибок API — [Ошибки](/docs/errors).

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

- [Эндпоинты](/docs/cowork/endpoints)
- [Выгодные часы в подписке Cowork/Code](/docs/cowork/off-peak)
- [Ключи и авторизация](/docs/keys-auth)
- [Лимиты и оптимизация](/docs/optimization)
- [Ошибки](/docs/errors)