## 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](/docs/cowork/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)

| Field | Type | Required | Description |
|------|-----|:-----:|----------|
| `acknowledgedOneTimeConsumption` | boolean | yes | Literal `true` only. Confirms that the user was shown that this starts a one-time trial, that it cannot be revoked, and when it ends. Any other value or an empty body returns `400 DISCLOSURE_REQUIRED` |

## 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

```bash
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

```javascript
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

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | `true` on a successful response |
| `data.status` | string | Activation outcome: `activated` — the trial has started, `already_active` — a trial or a subscription is already in effect, `pending` — the activation went through but confirmation from Bitrix24 has not arrived yet |
| `data.trialEndsAt` | string or null | When the trial ends, as reported by Bitrix24 (ISO 8601). Present when `status: activated` |

## Response example

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

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

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

## Error response example

400 — a body with no confirmation:

```json
{
  "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

| HTTP | Code | Description |
|------|-----|----------|
| 400 | `DISCLOSURE_REQUIRED` | The body does not contain `acknowledgedOneTimeConsumption` set to `true`. The same code is returned for an empty body and for a request without a `Content-Type` header |
| 400 | `INVALID_JSON_BODY` | A body was sent but does not parse as JSON |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |
| 401 | `INVALID_API_KEY` | Invalid API key |
| 403 | `INSUFFICIENT_SCOPE` | The key has no `vibe:cowork` scope |
| 403 | `COWORK_DESKTOP_KEY_REQUIRED` | A key of another class: a personal key, an application key or an agent seat key |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key was issued as read-only |
| 404 | `NOT_FOUND` | The account was not found or has been deleted |
| 409 | `ALREADY_ACTIVATED` | The trial for this account has already been started through us |
| 409 | `TRIAL_ACTIVATION_UNAVAILABLE` | Activation is unavailable: the account does not meet the conditions, the Marketplace trial is used up, or Bitrix24 issued a final refusal |
| 429 | `RATE_LIMITED` | More than three requests per hour per account |
| 503 | `TRIAL_ACTIVATION_RETRY` | A temporary error on our side; a retry is safe |

The full list of common API errors — [Errors](/docs/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](/docs/cowork/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](/docs/activate-market-trial)
- [Cowork/Code subscription state](/docs/cowork/state)
- [Cowork/Code subscription summary](/docs/cowork/me)
- [Tier change preview](/docs/cowork/subscription-preview)
- [Cowork/Code](/docs/cowork)
- [Errors](/docs/errors)