# Cowork subscription

Cowork is a single subscription: the desktop app, Code mode, and autonomous agents share one AI quota. The endpoints in this section report the current subscription state — the tier, quota usage across three windows as a percentage, and advice on when to wait for a reset or move to a higher tier. The subscription covers AI only, and only while it is connected and active: the agent's own server is paid for separately, from the account wallet. Beyond reading state, the section issues a project key with deploy rights and creates a personal application together with its key.

**Scope:** `vibe:cowork` | **Base URL:** `https://vibecode.bitrix24.com/v1` | **Authorization:** `X-Api-Key`

[Three quota windows](#three-quota-windows) | [Tiers](#tiers) | [How to start](#how-to-start) | [Quick start](#quick-start) | [Full example](#full-example-tracking-the-quota) | [Endpoint reference](#endpoint-reference) | [Error codes](#error-codes) | [Your own agent](/docs/cowork/harness)

## What Cowork is

One subscription gives one quota for AI requests — three tools spend it from a shared balance:

- **Cowork** — a desktop app with an AI assistant for working with a Bitrix24 account.
- **Code** — a mode for writing and publishing applications inside the desktop app.
- **AI Agent** — autonomous AI agents.

The quota covers AI only, and only while the subscription is connected and active. The agent's own server is paid for separately, from the account wallet.

Advantages of a single subscription:

- A shared balance across three tools instead of separate limits.
- The free tier is active immediately — no payment is required to start.
- Usage is shown as a percentage, with no overage — the limit is predictable.
- Scales through the `×1` → `×5` → `×20` tiers as your workload grows.

As long as the subscription is connected and active, agents and Code mode spend its quota automatically — nothing needs to be configured separately. The AI agent's own server, however, is paid for from the account wallet and is not included in the subscription quota.

Disabling Cowork at the platform level does not change AI billing for an already-issued `vibe:cowork` key: chat and [audio transcription](/docs/ai/audio/transcriptions) continue to use the active subscription quota. Audio also requires an administrator-configured per-minute or per-call price for a model available to you. Without an active subscription, audio retains its standard billing path without drawing on subscription quota.

## Three quota windows

Quota usage is counted simultaneously in three nested windows:

| Window | Purpose |
|------|------------|
| 5 hours | limits short-term bursts |
| Week | mid-term limit |
| Month | matches the subscription billing period |

Work is blocked when **any** of the windows is exhausted. Each window has a usage percentage and a reset time. Absolute quota numbers are not exposed — both `/v1/cowork/state` and `/v1/cowork/me` show percentages only.

## Tiers

| Tier | Multiplier | Quota volume |
|-------|-----------|-------------|
| Free | — | base quota, active immediately |
| Pro | `×1` | base paid volume |
| Max | `×5` | five times the volume of Pro |
| Ultra | `×20` | twenty times the volume of Pro |

The `×N` multiplier sets the quota volume across all three windows relative to the Pro tier (`×1`). Each tier's price is returned separately, in the `feeVibes` field (in Vibe credits per month), and is current as of the time of the request.

## How to start

1. Open the Cowork section in your Vibecode account.
2. The free tier is active immediately — the quota is available without connecting anything.
3. If you need more quota, pick the Pro, Max, or Ultra tier.
4. To call the endpoints in this section, use an authorization key with the `vibe:cowork` scope — pass it in the `X-Api-Key` header.
5. Agents and Code mode use this subscription's quota automatically, as long as it is connected and active.

More on keys and scopes — [Keys and authorization](/docs/keys-auth).

## Quick start

The current subscription state in a single request:

```bash
curl https://vibecode.bitrix24.com/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" } }
}
```

## Full example: tracking the quota

The script polls the subscription state and reacts when the limit is approaching and when the quota is exhausted.

```javascript
const BASE = 'https://vibecode.bitrix24.com/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:', error.code, error.message)
    return
  }

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

  // The busiest window
  const tight = windows[bottleneck]
  console.log(`Window ${bottleneck}: ${tight.pctUsed}%`)

  // Quota exhausted — show when work can resume
  if (recommendation.wait) {
    const seconds = Math.ceil((new Date(recommendation.wait.resetAt) - new Date(state.serverTime)) / 1000)
    console.log(`Limit exhausted, reset in ${seconds} s`)
  }

  // Approaching the limit — suggest a higher tier
  if (recommendation.reason === 'approaching' && recommendation.upgrade.nextTier) {
    console.log(`Consider moving to the ${recommendation.upgrade.nextTier} tier`)
  }
}

// Poll once every 30 seconds
setInterval(checkQuota, 30_000)
checkQuota()
```

## Endpoint reference

| Method | Path | Description |
|-------|------|----------|
| GET | [/v1/cowork/state](/docs/cowork/state) | Full state: quota windows, recommendation, tier catalog |
| GET | [/v1/cowork/me](/docs/cowork/me) | Short summary: tier, state, quota percentages |
| GET | [/v1/cowork/subscription/preview](/docs/cowork/subscription-preview) | Preview: how much will be debited right now when switching to the specified tier |
| GET | [/v1/cowork/applications/defaults](/docs/cowork/applications-defaults) | Create-application wizard defaults: scope presets, key mode, quota, server parameters |
| POST | [/v1/cowork/applications](/docs/cowork/applications-create) | Creates a personal application together with its key |
| POST | [/v1/cowork/applications/:id/key](/docs/cowork/applications-key) | Issues a key into an empty application slot or replaces the issued one, or issues a development team member key |
| POST | [/v1/cowork/deploy-key](/docs/cowork/deploy-key) | Project key with deploy rights (scopes `vibe:infra` + `vibe:storage`, 7 days) |

An interactive method switcher with examples and response fields — [Endpoints](/docs/cowork/endpoints).

## Error codes

| HTTP | Code | Description |
|------|-----|----------|
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not passed |
| 401 | `INVALID_API_KEY` | The key is not recognized — no such key exists on the platform |
| 403 | `INSUFFICIENT_SCOPE` | The key lacks the `vibe:cowork` scope |
| 404 | `COWORK_NOT_ACTIVATED` | No Cowork subscription found for the user and portal |
| 500 | `INVALID_TIER_CONFIGURATION` | The tier configuration on the platform is invalid |
| 503 | `COWORK_FEATURE_DISABLED` | Cowork is disabled at the platform level |
| 503 | `APP_CREATE_DISABLED` | Creating applications from Cowork is disabled at the platform level |

The full list of common API errors — [Errors](/docs/errors).

## See also

- [Endpoints](/docs/cowork/endpoints)
- [Off-peak hours in the Cowork subscription](/docs/cowork/off-peak)
- [Keys and authorization](/docs/keys-auth)
- [Limits and optimization](/docs/optimization)
- [Errors](/docs/errors)