Skip to main content
    Ivy Biosciences logo
    Ivy Biosciences.bloom* docs
    login.bloom*
    Ivy Biosciences Docs/Call the platform/API/Reference/Reference/Sandbox/POST /v1/sandbox/create

    POST /v1/sandbox/create

    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.

    Open in Claude(opens in a new tab)Open in ChatGPT(opens in a new tab)2 min read
    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.

    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

    sessionIdstring

    Session ID for this sandbox

    chatIdstring

    Chat to create the sandbox for. You must own it.

    campaignIdstring

    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:

    statusstring

    provisioning or creating while starting, active or ready once usable

    phaseenum ("compute" | "mount" | "ready" | "failed")

    Launch phase of the sandbox

    etaSecondsinteger

    Estimated seconds until ready; present while provisioning

    successboolean

    Present only on a deduplicated response

    dedupedboolean

    True when another create for this chat was already in flight

    sandboxIdstring

    Present on a deduplicated ready response

    tunnelUrlstring

    Present on a deduplicated ready response

    202 Accepted

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

    Response shape:

    statusstring

    provisioning or creating while starting, active or ready once usable

    phaseenum ("compute" | "mount" | "ready" | "failed")

    Launch phase of the sandbox

    etaSecondsinteger

    Estimated seconds until ready; present while provisioning

    successboolean

    Present only on a deduplicated response

    dedupedboolean

    True when another create for this chat was already in flight

    sandboxIdstring

    Present on a deduplicated ready response

    tunnelUrlstring

    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 -X POST 'https://ivybiosciences.com/api/v1/sandbox/create' \
  -H "Authorization: Bearer $IVY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "sessionId": "",
  "chatId": "",
  "campaignId": ""
}'

    Was this page helpful?

    GET /v1/sandbox/{chatId}/status

    Get sandbox status — Returns the current state of your chat's sandbox. status is none when the chat has no sandbox.

    POST /v1/sandbox/{chatId}/exec

    Run a shell command — Runs a shell command in your chat's isolated code sandbox and returns its output.

    Loading...