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 creation parameters also include the scope presets and the access mode the issued key will get.

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. Personal keys and OAuth application keys lack the vibe:cowork scope, so requests using them return 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_…",
    "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": 40, "limit": 40, "requested": 1, "scope": "portal" }
  }
}

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.

A failure that happened after Bitrix24 was contacted is replayed the same way — see Retry after a failure.

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 portal, 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.

Retry after a failure

If the first attempt failed AFTER Bitrix24 was already contacted (the connector was unreachable, the Bitrix24 account refused, an internal write failed), the platform stores that outcome and, for 20 minutes, returns it verbatim on a retry with the same Idempotency-Key: the same HTTP status, the same error.code, the same body, plus the Idempotent-Replayed: true header. Aside from that header, the platform's response is indistinguishable from the first failure — use the header to tell a replay from the first attempt.

After 20 minutes the outcome is forgotten: the platform physically frees the idempotency key, and a retry with it runs as a brand-new attempt — every check runs again, including a chance to succeed. The retry body must still match the first attempt's body, or, as always, 409 IDEMPOTENCY_KEY_BODY_MISMATCH is returned; the exception is when the outcome is already forgotten (20 minutes have passed) — then the body is not compared against the forgotten failure at all, and a retry with ANY body starts a new attempt.

If the first failure happened AFTER Bitrix24 was already contacted (for example 502 BITRIX_UNAVAILABLE), the account may already have received a webhook from the first attempt — a retry past the 20-minute window does not check for that and can mint a SECOND key on top of the first. Changing the Idempotency-Key value does not protect against that here — the same key and a new one both run as a new attempt past the window. Usually there is nothing on the platform to check either: a failed reservation is removed together with its outcome, and at most failure stages no key is minted at all — so look for a possible duplicate on the Bitrix24 account itself, if you can, and treat the risk as part of the cost of retrying past the window. The exception is 500 APPLICATION_CREATE_FAILED: there the key is sometimes ALREADY issued (see the error table above), and then you can find and revoke the extra key in the API Keys section of your Vibecode account.

A refusal by one of the checks that run BEFORE the idempotency key is claimed (body validation failed, the key quota is exhausted, the account is not linked to Bitrix24 Network, the platform's Bitrix24 plan check did not pass) is not covered by this guarantee: the key is not kept in that case, and a retry with it is indistinguishable from the first request as far as the platform is concerned. Most plan-related refusals arrive before the key is claimed and are not replayed, but a refusal that the Bitrix24 account returned while the key was being issued is stored and replayed for 20 minutes. The response body does not tell them apart, so rely on the Idempotent-Replayed header: absent means the answer is fresh.

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 does not show whether the key was issued. If the key was already issued but the card could not be created, the quota slot is taken — find and revoke the extra key. If the key-issuing step itself threw, there is usually no key, but the outcome is still stored. In both cases a retry with the same idempotency key within 20 minutes returns the stored failure, and the Idempotent-Replayed: true header alone does not prove an extra key exists — check your key list. If the reservation insert itself failed, neither the key nor the card exists — the reservation was never claimed, there is no stored outcome, and a retry runs as a brand-new attempt right away.

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