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.
Sandbox operations require the token to be scoped to the requested project.
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 |
| Header | Required | Description |
|---|
Authorization | Yes | Bearer <token> |
Response
{
"data": {
"sandboxId": "sandbox-abc123",
"status": "connected"
}
}
| Field | Type | Description |
|---|
sandboxId | string | Unique identifier for the sandbox session |
status | string | Always "connected" on success |
Example
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) |
| Header | Required | Description |
|---|
Authorization | Yes | Bearer <token> |
Response (Directory)
{
"data": {
"type": "directory",
"entries": ["contracts/", "entities/", "stats.yaml"]
}
}
Response (File)
{
"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:
curl "https://api.royaltyport.com/v1/projects/a1b2c3d4-.../sandbox/files?path=/" \
-H "Authorization: Bearer rp_your_token_here"
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 |
| Header | Required | Description |
|---|
Authorization | Yes | Bearer <token> |
Response
{
"data": {
"status": "disconnected"
}
}
Example
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
{
"commands": ["ls contracts/", "cat stats.yaml"]
}
| Field | Type | Required | Description |
|---|
commands | string[] | Yes | Array of bash commands to execute sequentially |
| 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.
{
"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
}
]
}
For a single command, pass a one-element array: { "commands": ["ls"] }. The response is always an array.
Errors
| Status | Description |
|---|
400 | Missing or empty commands array |
Examples
Single command:
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"]}'
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/*"]}'
