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/{chatId}/tool/{toolName}

    POST /v1/sandbox/{chatId}/tool/{toolName}

    Run a sandbox tool — Runs a named tool in your chat's isolated code sandbox, for example sandbox_exec, sandbox_python, sandbox_rscript, sandbox_notebook…

    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.

    Runs a named tool in your chat's isolated code sandbox, for example sandbox_exec, sandbox_python, sandbox_rscript, sandbox_notebook, sandbox_read, sandbox_files, sandbox_write, sandbox_edit, sandbox_grep, sandbox_glob or sandbox_export. An unrecognised toolName returns 400.

    The JSON body is passed to the tool as its parameters, so its fields depend on the tool. An optional numeric timeout (seconds, capped at 300; shell and script tools are further capped at 120) sets the time budget. The response is the tool's own JSON result. Returns 503 SANDBOX_NOT_READY while the sandbox is starting.

    Request

    Path parameters

    chatIdstring

    ID of the chat that owns the sandbox

    toolNamestring

    Name of the sandbox tool to run

    Request body

    timeoutnumber

    Time budget in seconds, capped at 300. Shell and script tools are capped at 120.

    Responses

    200 OK

    Tool result; the shape depends on the tool

    Response shape: object

    400 Bad Request

    Unknown tool, or the body is not a JSON object

    Response shape: object

    401 Unauthorized

    Authentication required

    Response shape: object

    403 Forbidden

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

    Response shape: object

    404 Not Found

    Resource not found

    Response shape: object

    429 Too Many Requests

    Rate limit exceeded

    Response shape: object

    502 Bad Gateway

    The sandbox failed to start and will not recover on retry

    Response shape: object

    503 Service Unavailable

    The sandbox is still starting; retry shortly

    Response shape: object

    504 Gateway Timeout

    The tool exceeded its time budget

    Response shape: object

    curl -X POST 'https://ivybiosciences.com/api/v1/sandbox/{chatId}/tool/{toolName}' \
  -H "Authorization: Bearer $IVY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{}'

    Was this page helpful?

    POST /v1/sandbox/{chatId}/exec

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

    POST /v1/sandbox/{chatId}/terminate

    Terminate the sandbox — Shuts down your chat's sandbox. The route reads no body fields. A new sandbox can be created for the chat afterwards.

    Loading...