---
title: POST /v1/sandbox/create
description: "Create a sandbox for a chat — Starts your chat's isolated code sandbox. You must own the chat, and campaignId must be that chat's campaign."
full: true
---

**Auth:** required. Send an `ivy_` API key (`Authorization: Bearer ivy_…` or `X-Ivy-Api-Key`), a Clerk session JWT (`Authorization: Bearer …`) or the Clerk `__session` cookie (browser sessions). See [Authentication](/docs/api/authentication).

Starts your chat's isolated code sandbox. You must own the chat, and `campaignId` must be that chat's campaign. A cold start returns `status: "provisioning"` with HTTP 200; poll `getSandboxStatus` until it is `active`. If another create for the same chat is already in flight, the call returns HTTP 202 with `deduped: true`, or HTTP 200 with `status: "ready"` and `deduped: true` when that sandbox is already up.

Send the key as `Authorization: Bearer ivy_xxx`; this route reads the Authorization header, so `X-Ivy-Api-Key` alone is not enough.

## Request

#### Request body

- `sessionId` (string) —
Session ID for this sandbox

- `chatId` (string) —
Chat to create the sandbox for. You must own it.

- `campaignId` (string) —
The chat's campaign. A different campaign is rejected.

## Responses

### `200` OK

Sandbox created (still provisioning) or ready, including `{status: "ready", deduped: true}` when a concurrent create already finished

Response shape:

- `status` (string) —
`provisioning` or `creating` while starting, `active` or `ready` once usable

- `phase` (enum ("compute" | "mount" | "ready" | "failed")) —
Launch phase of the sandbox

- `etaSeconds` (integer) —
Estimated seconds until ready; present while provisioning

- `success` (boolean) —
Present only on a deduplicated response

- `deduped` (boolean) —
True when another create for this chat was already in flight

- `sandboxId` (string) —
Present on a deduplicated `ready` response

- `tunnelUrl` (string) —
Present on a deduplicated `ready` response

### `202` Accepted

A create for this chat is already in flight; poll the status route

Response shape:

- `status` (string) —
`provisioning` or `creating` while starting, `active` or `ready` once usable

- `phase` (enum ("compute" | "mount" | "ready" | "failed")) —
Launch phase of the sandbox

- `etaSeconds` (integer) —
Estimated seconds until ready; present while provisioning

- `success` (boolean) —
Present only on a deduplicated response

- `deduped` (boolean) —
True when another create for this chat was already in flight

- `sandboxId` (string) —
Present on a deduplicated `ready` response

- `tunnelUrl` (string) —
Present on a deduplicated `ready` response

### `400` Bad Request

Missing `sessionId`, `chatId` or `campaignId`, or `campaignId` is not the chat's campaign

Response shape: `object`

### `401` Unauthorized

Authentication required

Response shape: `object`

### `403` Forbidden

You do not own the chat, or your key's project scope excludes it

Response shape: `object`

### `429` Too Many Requests

Rate limit exceeded

Response shape: `object`

### `500` Internal Server Error

Sandbox creation failed, for example the sandbox started but its session could not be stored securely

Response shape: `object`

### `503` Service Unavailable

Sandbox creation failed transiently; retry shortly

Response shape: `object`

**curl**

```bash
curl -X POST 'https://ivybiosciences.com/api/v1/sandbox/create' \
  -H "Authorization: Bearer $IVY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "sessionId": "",
  "chatId": "",
  "campaignId": ""
}'
```

**JavaScript**

```js
const res = await fetch('https://ivybiosciences.com/api/v1/sandbox/create', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.IVY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "sessionId": "",
  "chatId": "",
  "campaignId": ""
}),
});
const data = await res.json();
```

**Python**

```python
import os, requests

res = requests.post(
    "https://ivybiosciences.com/api/v1/sandbox/create",
    headers={"Authorization": f"Bearer {os.environ['IVY_API_KEY']}"},
    json={
  "sessionId": "",
  "chatId": "",
  "campaignId": ""
},
)
data = res.json()
```