Create an application from Cowork/Code

POST /v1/cowork/applications

Creates a personal application and issues its key, which is returned exactly once. The endpoint does not create a server: a personal application has none by definition. Your deployment creates the server, which is then linked to the card automatically. The Idempotency-Key header is required.

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

Take the request field values from the application creation parameters. The same endpoint also returns the scope presets and the access mode that the Bitrix24 account assigns to new keys.

Parameters

Request fields (body)

The schema is strict: an extra field in the body returns 400 VALIDATION_ERROR, and the response names the field. The body size is limited to 64 KB.

Examples

The endpoint accepts only a Cowork/Code key, so only two examples are provided. A request made with a key that lacks the vibe:cowork scope receives 403 INSUFFICIENT_SCOPE.

curl — Cowork/Code key

curl -X POST https://vibecode.bitrix24.com/v1/cowork/applications \
  -H "X-Api-Key: YOUR_COWORK_KEY" \
  -H "Idempotency-Key: create-app-2026-08-25-01" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Deal report",
    "type": "personal",
    "b24Scopes": ["crm"]
  }'

JavaScript — Cowork/Code key

const res = await fetch('https://vibecode.bitrix24.com/v1/cowork/applications', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_COWORK_KEY',
    'Idempotency-Key': 'create-app-2026-08-25-01',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Deal report',
    type: 'personal',
    b24Scopes: ['crm'],
  }),
})

if (!res.ok) {
  const { error } = await res.json()
  throw new Error(`${res.status} ${error.code}`)
}

const { data } = await res.json()

// The raw key is returned only once — save it immediately
if (data.rawApiKey === null) {
  // This is a retry: the application already exists, so the key is not issued again
} else {
  saveKey(data.rawApiKey, data.keyExpiresAt)
}

Response fields

Response example

{
  "success": true,
  "data": {
    "application": {
      "id": "cmt8ht5u40005ensk4fp45ebx",
      "name": "Deal report",
      "description": null,
      "type": "PERSONAL",
      "iconUrl": null,
      "createdAt": "2026-08-25T09:59:01.324Z",
      "updatedAt": "2026-08-25T09:59:01.324Z",
      "viewerState": "owner",
      "pinned": false,
      "author": { "name": "Application author" },
      "isEmbedded": false,
      "openUrl": null,
      "openTarget": null,
      "server": null,
      "sources": { "hasVersions": false, "latestVersionId": null, "latestSavedAt": null },
      "activeOperation": null
    },
    "applicationId": "cmt8ht5u40005ensk4fp45ebx",
    "rawApiKey": "vibe_api_ge5crx6rXOgoFikYi7G2inWA6dx7VO1V_9bcf92",
    "keyExpiresAt": null,
    "mode": "READWRITE",
    "warnings": [],
    "warningCodes": []
  }
}

Error response example

409 — the key quota is exhausted:

{
  "success": false,
  "error": {
    "code": "KEY_LIMIT_REACHED",
    "message": "Maximum number of API keys reached",
    "details": { "used": 1, "limit": 1, "requested": 1 }
  }
}

Deleting the issued key in your Vibecode account does NOT cancel idempotency: the application remains, and a retry with the same idempotency key still returns 201 with the Idempotent-Replayed: true header and warningCodes: ["KEY_NOT_REPLAYABLE"]. That retry does not issue a new key — the raw key is returned exactly once, during initial creation. To get a working key for an existing application, use POST /v1/keys/:id/rotate.

Errors

The endpoint-specific error list is exhaustive: the endpoint does not return codes that are not listed here. Key issuance goes through Bitrix24 Network, whose errors are propagated verbatim and are also included in the table. For a self-hosted Bitrix24 account, key issuance uses a separate channel and can return its own codes, covered in Keys and authorization. The response shape is the same; branch on error.code.

See Errors for the full list of common API errors.

Idempotency

Unlike creating a server, this endpoint requires the Idempotency-Key header. It issues a key and consumes a quota slot, so without idempotency, retrying after a network interruption could create a second application and a second key.

A retry with the same key and request body returns 201, adds the Idempotent-Replayed: true response header, and returns the same card. The raw key is then null, and KEY_NOT_REPLAYABLE appears in warningCodes: the platform stores only the key hash, so the raw key cannot be recovered.

A lost key is not returned on a retry, and this Cowork/Code key cannot reissue it — the response contains no identifier for the issued key, and the /v1/keys section accepts only a management key. The only practical option is to create the application again with a NEW Idempotency-Key value, obtain a fresh key, and then remove the extra card and its key from your Vibecode account. Save rawApiKey immediately in the same response handler.

The fingerprint is calculated from a canonicalized request body. The order of fields and the order of values in b24Scopes do not affect the comparison, so reordering either still counts as the same request. Leading and trailing whitespace in name also has no effect, and expiresInDays: null is equivalent to omitting the field. Using the same key with a different body returns 409 IDEMPOTENCY_KEY_BODY_MISMATCH instead of a result for a different request.

Repeat the same request body without modifying it. Omitting an optional field and explicitly providing the value that the account would supply produce DIFFERENT fingerprints. For example, if the first request omitted mode and the retry includes it, the response is 409 IDEMPOTENCY_KEY_BODY_MISMATCH. For the same reason, ["crm"] and ["crm", "crm"] differ: the scopes are sorted before comparison, but duplicates are not removed.

Known specifics

The default key lifetime does not apply — the keyExpiresInDays field in the creation parameters is a hint, not a default. If expiresInDays is omitted, the key is issued with no expiry, and the response contains keyExpiresAt: null. To limit the lifetime, pass the number of days explicitly. You can present the value from the creation parameters as a suggestion to the user.

The placement, entity, and userfieldtype scopes are not included in the issued key. In a mixed set, they are dropped without an error because a personal key does not support them. An error is returned only when b24Scopes contains no other scopes. Check the scopes on the issued key rather than relying on the request you sent.

The issued key cannot call AI or web search. It carries vibe:infra, vibe:storage, and the requested Bitrix24 scopes, while vibe:ai and vibe:search are absent from both the scope string and the runtime scopes. An application created this way cannot spend the account wallet on AI models or web search.

The order of errors matters: first the calling key's permissions, then the product state, then the cost. The checks run in this order: the key's existence, expiry, read-only mode, and account balance freeze; the vibe:cowork scope and key class, whether Cowork/Code is enabled, whether the subscription is active, and whether the application creation wizard is enabled; idempotency and the request body schema; and finally the account's platform access, application creation policy, and key quota. When multiple conditions fail at once, the first error in this sequence is returned.

A 500 APPLICATION_CREATE_FAILED refusal means the key has already been issued. The quota slot is taken and there is no card. Retry with a new idempotency key and revoke the extra key — revoking frees the quota slot, deleting the key is not required.

Some card fields are not populated by this endpoint — retrieve them from the application catalog. The field set matches GET /v1/applications/:id, but pinned is always false here, and sources and activeOperation are always empty, even if the application has been deployed and the user has pinned it in their Vibecode account. Read those fields from the application catalog; use the creation response for the identifier, name, and key.

The server is linked to the card automatically. After creating the application, create the server by calling POST /v1/infra/servers with the parameters from the server block of the creation parameters. No separate call is needed to link the server to the card.

See also

• Application creation parameters
• Create a server
• Application card
• Keys and authorization
• Cowork/Code
• Errors