Start the Marketplace trial

POST /v1/cowork/activate-market-trial

Starts the one-time Marketplace trial for the Bitrix24 account the Cowork/Code desktop key is bound to. The account is taken from the key binding; there is no path parameter.

Before showing the activation step, read activation.marketTrial.available in the subscription state — that flag is computed in advance and tells you whether the activation is worth offering. Availability depends on the account region: an account in an international region is not eligible, so the flag comes back false and a call to this endpoint is refused without changing anything.

Request fields (body)

Examples

The endpoint accepts the Cowork/Code desktop key only, so there are two examples: an application key with a user session gets 403 COWORK_DESKTOP_KEY_REQUIRED.

curl — Cowork/Code desktop key

curl -X POST https://vibecode.bitrix24.com/v1/cowork/activate-market-trial \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"acknowledgedOneTimeConsumption": true}'

JavaScript — Cowork/Code desktop key

const res = await fetch('https://vibecode.bitrix24.com/v1/cowork/activate-market-trial', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ acknowledgedOneTimeConsumption: true }),
})

if (!res.ok) {
  const { error } = await res.json()
  console.error(error.code, error.message)
} else {
  const { data } = await res.json()
  console.log(data.status === 'activated'
    ? `Trial active until ${data.trialEndsAt}`
    : `Status: ${data.status}`)
}

Response fields

Response example

{
  "success": true,
  "data": {
    "status": "activated",
    "trialEndsAt": "2026-09-01T00:00:00.000Z"
  }
}

The activation went through, but the confirmation has not arrived yet:

{
  "success": true,
  "data": {
    "status": "pending"
  }
}

Error response example

400 — a body with no confirmation:

{
  "success": false,
  "error": {
    "code": "DISCLOSURE_REQUIRED",
    "message": "Body must contain {\"acknowledgedOneTimeConsumption\": true} — confirm that the user was shown that this starts a one-time trial and when it ends."
  }
}

Errors

The full list of common API errors — Errors.

Known specifics

The trial is one-time and cannot be revoked. The countdown starts at the moment of the successful response, and the operation cannot be cancelled — neither on our side nor on the Bitrix24 side. That is why the activation requires confirmation in the request body.

The length of the trial is set by Bitrix24. Show the user the date from trialEndsAt rather than a day count of your own: it has changed before and may differ from what you saw earlier.

The pending status is not a reason to repeat the request. The activation has already happened — only the confirmation from Bitrix24 is missing. A repeat call consumes an attempt and returns 409 ALREADY_ACTIVATED. There is no separate outward sign of that confirmation today: the subscription state already reads status: activated and its endsAt is filled in straight away. Show the user the started trial and the date from the state, and treat the pending answer itself as success.

The available flag is a forecast, not a guarantee. The value true in the subscription state means the activation can be offered, but the final decision stays with Bitrix24: the conditions can change between the state request and the activation, so keep the refusal handling in place.

The desktop key is issued when the user signs in to the Cowork/Code application. This endpoint does not accept a personal key or an application key — for those, activation lives at a different endpoint. An agent seat key carries the same vibe:cowork scope but is refused as well: there is no person behind it who could be shown that a one-time resource is being spent.

The three attempts per hour are counted per account, not per key, and are spent on refusals too. All devices of one person and all employees of one account share this limit, and the rate limit is checked before the other guards: a request with no confirmation or with a key of another class counts against the remaining attempts just like a successful one.

A missing confirmation always comes back as the same code. An empty body, a missing Content-Type header, and a different content type with no body are all 400 DISCLOSURE_REQUIRED, not an internal request-parsing error. No separate branch is needed for such cases.

See also

• Activate the Marketplace trial
• Cowork/Code subscription state
• Cowork/Code subscription summary
• Tier change preview
• Cowork/Code
• Errors