## Application creation parameters

`GET /v1/cowork/applications/defaults`

Returns everything the application creation wizard needs before asking the user its first question: the available scope presets, the access mode for the new key, the remaining key quota, and the server parameters. This read-only endpoint has no side effects: it creates neither an application nor a key. Call it whenever the wizard opens and again before deployment to confirm the price.

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

The `server` block contains the parameters to pass to [`POST /v1/infra/servers`](/docs/infra/servers/create). Pass its values **verbatim**; no conversion is required.

## Examples

This endpoint accepts only a Cowork/Code key, so only two examples are provided. A key without the `vibe:cowork` scope receives `403 INSUFFICIENT_SCOPE`.

### curl — Cowork/Code key

```bash
curl https://vibecode.bitrix24.com/v1/cowork/applications/defaults \
  -H "X-Api-Key: YOUR_COWORK_KEY"
```

### JavaScript — Cowork/Code key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/cowork/applications/defaults', {
  headers: { 'X-Api-Key': 'YOUR_COWORK_KEY' },
})
const { data } = await res.json()

if (!data.available) {
  // Application creation is disabled — hide the wizard entry point before the user reaches it
  return
}

// Render presets by their stable id and load labels from your own dictionaries
const presets = data.scopePresets.map(p => ({ id: p.id, scopes: p.b24Scopes }))

// Show the price only when it is available
const priceKnown = data.server.priceMonthly !== null
```

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | Always `true` on success |
| `data.available` | boolean | `false` — application creation is disabled at the platform level. Hide the wizard entry point: `POST /v1/cowork/applications` returns `503 APP_CREATE_DISABLED`. All other fields are still returned in full when it is `false` |
| `data.scopePresets` | array | Scope presets for the step that asks which Bitrix24 account data the application needs |
| `data.scopePresets[].id` | string | Stable preset identifier — `crm`, `tasks`, `people`. Use it to look up a label in your own dictionary: the platform returns no labels |
| `data.scopePresets[].b24Scopes` | array | The Bitrix24 scopes the preset requests. This array is never empty. Pass these values in the `b24Scopes` field when [creating an application](./applications-create.md) |
| `data.mode` | string | The access mode the Bitrix24 account assigns to new keys — `READONLY` or `READWRITE`. Show this value: on a Bitrix24 account in `READONLY` mode, an application that writes to CRM fails only after it is published |
| `data.keyExpiresInDays` | number | Lifetime of the new key in days, per the Bitrix24 account policy |
| `data.quota.keysUsed` | number | Number of key quota slots currently in use |
| `data.quota.keysLimit` | number | Maximum number of keys allowed by the Bitrix24 account administrator. The same quota values are included in the `details` of a `409 KEY_LIMIT_REACHED` refusal |
| `data.server.placement` | string | Placement for the new server — `galaxy`, `galaxy-preferred` or `standalone`. These values are covered in "Known specifics" |
| `data.server.serverWillLink` | boolean | Whether the server you create will be linked to this application's card. This field is returned separately so clients do not have to derive it from `placement` |
| `data.server.provider` | string \| null | Provider identifier for the `provider` field when creating a server. See [`GET /v1/infra/providers`](/docs/infra/providers/list) for available values |
| `data.server.plan` | string \| null | Plan identifier for the `plan` field. See [`GET /v1/infra/providers/:providerId/plans`](/docs/infra/providers/plans) for available values |
| `data.server.region` | string \| null | Region identifier for the `region` field. See [`GET /v1/infra/providers/:providerId/regions`](/docs/infra/providers/regions) for available values |
| `data.server.priceMonthly` | number \| null | Catalog price of the server per month, in `currency` units. Actual charges for a given Bitrix24 account may differ. `null` means that no price was returned; it does not mean that the server is free |
| `data.server.currency` | string \| null | Unit in which the price is expressed |
| `data.warningCodes` | array | Warning codes. The only code is `SERVER_DEFAULTS_UNAVAILABLE`: the provider catalog could not be retrieved, so the plan and price are unavailable. The `placement` and `serverWillLink` fields remain reliable because they are derived from the Bitrix24 account policy |

## Response example

```json
{
  "success": true,
  "data": {
    "available": true,
    "scopePresets": [
      { "id": "crm", "b24Scopes": ["crm"] },
      { "id": "tasks", "b24Scopes": ["task", "tasks"] },
      { "id": "people", "b24Scopes": ["user_brief", "department"] }
    ],
    "mode": "READWRITE",
    "keyExpiresInDays": 90,
    "quota": { "keysUsed": 1, "keysLimit": 10 },
    "server": {
      "placement": "standalone",
      "serverWillLink": true,
      "provider": "bitrix-cloud",
      "plan": "bc-small",
      "region": "bc-eu-central",
      "priceMonthly": 24,
      "currency": "Vibes"
    },
    "warningCodes": []
  }
}
```

## Error response example

403 — no active Cowork/Code subscription:

```json
{
  "success": false,
  "error": {
    "code": "COWORK_NOT_ACTIVATED",
    "message": "No active Cowork/Code subscription for this user+portal — an application cannot be created."
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |
| 401 | `INVALID_API_KEY` | The key was not found or was revoked |
| 401 | `KEY_INACTIVE` | The key is disabled |
| 401 | `KEY_EXPIRED` | The key has expired |
| 402 | `ACCOUNT_FROZEN` | The account balance is depleted — top it up. This read endpoint also returns the error; it is not exempt from the freeze |
| 403 | `INSUFFICIENT_SCOPE` | The key lacks the `vibe:cowork` scope |
| 403 | `COWORK_HARNESS_KEY_FORBIDDEN` | The call was made with a third-party agent key issued for the subscription. The application creation wizard is unavailable to such a key — see [Your own agent on the subscription](/docs/cowork/harness) |
| 403 | `COWORK_NOT_ACTIVATED` | No active Cowork/Code subscription for the user and portal |
| 429 | `RATE_LIMITED` | The platform-wide limit is 30 requests per minute. The effective value for your key is returned in the `x-ratelimit-limit` header. It is lower than the platform-wide limit because that limit is divided across replicas |
| 429 | `QUOTA_EXCEEDED` | The daily free-call quota is exhausted while the prepaid balance is zero |
| 503 | `COWORK_FEATURE_DISABLED` | Cowork/Code is disabled at the platform level. Disabling the wizard itself does not produce this error — it is reported as `available: false` with status `200` |

See [Errors](/docs/errors) for the full list of common API errors.

## Known specifics

**Three `placement` values, not two.** With `standalone`, the server is provisioned as a separate billable virtual machine, and the price in the `server` block refers to that machine. With `galaxy`, the server must be deployed as a container on a shared host. With `galaxy-preferred`, a container is preferred, but deployment uses a separate machine if container placement is unavailable. With container placement, the application starts only after it is first published, so the post-creation text says "created, now publish it" rather than "the server is starting".

**A missing price with no warning is a normal response for container placement.** `SERVER_DEFAULTS_UNAVAILABLE` appears only with `placement: "standalone"`. With `galaxy` and `galaxy-preferred`, the `plan`, `region`, `priceMonthly` and `currency` fields may be `null` while `warningCodes` remains an empty array: no separate machine is created, so there is nothing to bill. Decide whether to show a price based on `priceMonthly` itself, not on the presence of a warning.

**The fields in the `server` block do not necessarily become `null` together.** `provider` is determined before the plan catalog is retrieved, so a response may include `provider` while `plan`, `region`, `priceMonthly` and `currency` are `null`. Check every field you pass when creating a server instead of treating one field as a proxy for the others.

**The `image` field is intentionally absent from the `server` block — do not pass it.** When the field is omitted, the platform automatically selects a current operating system image. No separate request to the image catalog or client-side check for an incomplete catalog is required.

**Pass the values from the `server` block verbatim when creating a server.** There is no conversion between this response and [`POST /v1/infra/servers`](/docs/infra/servers/create): `provider`, `plan` and `region` are accepted exactly as returned.

**The Cowork/Code desktop key does not consume a quota slot.** `quota.keysUsed` counts the employee's personal keys and application keys on this Bitrix24 account, as well as agent keys and project deploy keys. A revoked key frees its slot; deleting it is unnecessary.

**The warning fields of the two endpoints differ, and that is not a typo.** Only `warningCodes` is returned here; the response has no `warnings` field, whereas [creating an application](./applications-create.md) returns both. A single type cannot represent both responses.

**The set of scope presets may grow.** Render only presets with recognized `id` values and skip unfamiliar ones; otherwise, a new preset will appear in the interface without a label. The contents of `b24Scopes` may change, but `id` may not because it is part of the contract.

## See also

- [Create an application from Cowork/Code](./applications-create.md)
- [Create a server](/docs/infra/servers/create)
- [Provider plans](/docs/infra/providers/plans)
- [Application catalog](/docs/applications)
- [Cowork/Code](/docs/cowork)
- [Errors](/docs/errors)