---
title: "POST /v1/sandbox/{chatId}/tool/{toolName}"
description: "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…"
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).

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

- `chatId` (string) —
ID of the chat that owns the sandbox

- `toolName` (string) —
Name of the sandbox tool to run

#### Request body

- `timeout` (number) —
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**

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

**JavaScript**

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

**Python**

```python
import os, requests

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