> ## Documentation Index
> Fetch the complete documentation index at: https://docs.royaltyport.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox

> Connect to project sandboxes and execute commands.

The sandbox provides a file-system view of a project's structured data. Connect to a sandbox, then execute bash commands against the project's data.

<Note>
  Sandbox operations require the token to be scoped to the requested project.
</Note>

***

## Connect Sandbox

Starts a sandbox session for a project. Must be called before using any other sandbox endpoints.

### Request

```
POST /v1/projects/{project_id}/sandbox/connect
```

### Path Parameters

| Parameter    | Type | Required | Description    |
| ------------ | ---- | -------- | -------------- |
| `project_id` | UUID | Yes      | The project ID |

### Headers

| Header          | Required | Description      |
| --------------- | -------- | ---------------- |
| `Authorization` | Yes      | `Bearer <token>` |

### Response

```json theme={null}
{
  "data": {
    "sandboxId": "sandbox-abc123",
    "status": "connected"
  }
}
```

| Field       | Type   | Description                               |
| ----------- | ------ | ----------------------------------------- |
| `sandboxId` | string | Unique identifier for the sandbox session |
| `status`    | string | Always `"connected"` on success           |

### Example

```bash theme={null}
curl -X POST https://api.royaltyport.com/v1/projects/a1b2c3d4-.../sandbox/connect \
  -H "Authorization: Bearer rp_your_token_here"
```

***

## Read Files

Reads a file or lists a directory in the sandbox. The sandbox must be connected first.

### Request

```
GET /v1/projects/{project_id}/sandbox/files
```

### Path Parameters

| Parameter    | Type | Required | Description    |
| ------------ | ---- | -------- | -------------- |
| `project_id` | UUID | Yes      | The project ID |

### Query Parameters

| Parameter | Type   | Required | Description                                     |
| --------- | ------ | -------- | ----------------------------------------------- |
| `path`    | string | Yes      | Path to read in the sandbox (file or directory) |

### Headers

| Header          | Required | Description      |
| --------------- | -------- | ---------------- |
| `Authorization` | Yes      | `Bearer <token>` |

### Response (Directory)

```json theme={null}
{
  "data": {
    "type": "directory",
    "entries": ["contracts/", "entities/", "stats.yaml"]
  }
}
```

### Response (File)

```json theme={null}
{
  "data": {
    "type": "file",
    "content": "total_contracts: 42\ntotal_recordings: 1205\n"
  }
}
```

### Errors

| Status | Description                    |
| ------ | ------------------------------ |
| `400`  | Missing `path` query parameter |
| `404`  | Path not found in sandbox      |

### Examples

List the sandbox root:

```bash theme={null}
curl "https://api.royaltyport.com/v1/projects/a1b2c3d4-.../sandbox/files?path=/" \
  -H "Authorization: Bearer rp_your_token_here"
```

Read a file:

```bash theme={null}
curl "https://api.royaltyport.com/v1/projects/a1b2c3d4-.../sandbox/files?path=contracts/contract_123/extracted/royalties.yaml" \
  -H "Authorization: Bearer rp_your_token_here"
```

***

## Disconnect Sandbox

Terminates the sandbox session for a project.

### Request

```
DELETE /v1/projects/{project_id}/sandbox/disconnect
```

### Path Parameters

| Parameter    | Type | Required | Description    |
| ------------ | ---- | -------- | -------------- |
| `project_id` | UUID | Yes      | The project ID |

### Headers

| Header          | Required | Description      |
| --------------- | -------- | ---------------- |
| `Authorization` | Yes      | `Bearer <token>` |

### Response

```json theme={null}
{
  "data": {
    "status": "disconnected"
  }
}
```

### Example

```bash theme={null}
curl -X DELETE https://api.royaltyport.com/v1/projects/a1b2c3d4-.../sandbox/disconnect \
  -H "Authorization: Bearer rp_your_token_here"
```

***

## Execute Commands

Runs one or more bash commands sequentially in the sandbox. Commands execute with the sandbox workspace root as the working directory. The sandbox instance is reused across all commands in a single request, avoiding repeated connection overhead.

### Request

```
POST /v1/projects/{project_id}/sandbox/exec
```

### Path Parameters

| Parameter    | Type | Required | Description    |
| ------------ | ---- | -------- | -------------- |
| `project_id` | UUID | Yes      | The project ID |

### Request Body

```json theme={null}
{
  "commands": ["ls contracts/", "cat stats.yaml"]
}
```

| Field      | Type      | Required | Description                                    |
| ---------- | --------- | -------- | ---------------------------------------------- |
| `commands` | string\[] | Yes      | Array of bash commands to execute sequentially |

### Headers

| Header          | Required | Description        |
| --------------- | -------- | ------------------ |
| `Authorization` | Yes      | `Bearer <token>`   |
| `Content-Type`  | Yes      | `application/json` |

### Response

Returns an array of results, one per command. Each result includes the `command` field for correlation.

```json theme={null}
{
  "data": [
    {
      "command": "ls contracts/",
      "stdout": "contract_123/\ncontract_456/\n",
      "stderr": "",
      "exitCode": 0
    },
    {
      "command": "cat stats.yaml",
      "stdout": "total_contracts: 2\n",
      "stderr": "",
      "exitCode": 0
    }
  ]
}
```

<Note>
  For a single command, pass a one-element array: `{ "commands": ["ls"] }`. The response is always an array.
</Note>

### Errors

| Status | Description                       |
| ------ | --------------------------------- |
| `400`  | Missing or empty `commands` array |

### Examples

Single command:

```bash theme={null}
curl -X POST https://api.royaltyport.com/v1/projects/a1b2c3d4-.../sandbox/exec \
  -H "Authorization: Bearer rp_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"commands": ["cat contracts/contract_123/extracted/royalties.yaml"]}'
```

Batch execution:

```bash theme={null}
curl -X POST https://api.royaltyport.com/v1/projects/a1b2c3d4-.../sandbox/exec \
  -H "Authorization: Bearer rp_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"commands": ["ls contracts/", "cat stats.yaml", "wc -l entities/*"]}'
```