curl 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/files' \
-H 'Authorization: Bearer YOUR_API_KEY'
curl 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/files?recursive=true' \
-H 'Authorization: Bearer YOUR_API_KEY'
const API_KEY = "YOUR_API_KEY";
const RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
const response = await fetch(
`https://agent.blackbox.ai/api/v1/tasks/${RUN_ID}/files?recursive=true`,
{ headers: { Authorization: `Bearer ${API_KEY}` } }
);
const data = await response.json();
data.files.forEach(f => console.log(`${f.type}\t${f.path}\t${f.size ?? "-"}`));
import requests
API_KEY = "YOUR_API_KEY"
RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
response = requests.get(
f"https://agent.blackbox.ai/api/v1/tasks/{RUN_ID}/files",
headers={"Authorization": f"Bearer {API_KEY}"},
params={"recursive": "true"},
)
data = response.json()
for f in data["files"]:
print(f"{f['type']}\t{f['path']}\t{f.get('size', '-')}")
{
"files": [
{
"name": "src",
"path": "/vercel/sandbox/src",
"type": "directory",
"size": null
},
{
"name": "package.json",
"path": "/vercel/sandbox/package.json",
"type": "file",
"size": 1024
},
{
"name": "README.md",
"path": "/vercel/sandbox/README.md",
"type": "file",
"size": 512
},
{
"name": "README.fr.md",
"path": "/vercel/sandbox/README.fr.md",
"type": "file",
"size": 648
}
],
"path": "/vercel/sandbox",
"recursive": false
}
{
"error": "No sandbox available for this task"
}
File Management
List Workspace Files
List files and directories in the task’s sandbox workspace. Supports recursive listing.
GET
/
api
/
v1
/
tasks
/
{runId}
/
files
curl 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/files' \
-H 'Authorization: Bearer YOUR_API_KEY'
curl 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/files?recursive=true' \
-H 'Authorization: Bearer YOUR_API_KEY'
const API_KEY = "YOUR_API_KEY";
const RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
const response = await fetch(
`https://agent.blackbox.ai/api/v1/tasks/${RUN_ID}/files?recursive=true`,
{ headers: { Authorization: `Bearer ${API_KEY}` } }
);
const data = await response.json();
data.files.forEach(f => console.log(`${f.type}\t${f.path}\t${f.size ?? "-"}`));
import requests
API_KEY = "YOUR_API_KEY"
RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
response = requests.get(
f"https://agent.blackbox.ai/api/v1/tasks/{RUN_ID}/files",
headers={"Authorization": f"Bearer {API_KEY}"},
params={"recursive": "true"},
)
data = response.json()
for f in data["files"]:
print(f"{f['type']}\t{f['path']}\t{f.get('size', '-')}")
{
"files": [
{
"name": "src",
"path": "/vercel/sandbox/src",
"type": "directory",
"size": null
},
{
"name": "package.json",
"path": "/vercel/sandbox/package.json",
"type": "file",
"size": 1024
},
{
"name": "README.md",
"path": "/vercel/sandbox/README.md",
"type": "file",
"size": 512
},
{
"name": "README.fr.md",
"path": "/vercel/sandbox/README.fr.md",
"type": "file",
"size": 648
}
],
"path": "/vercel/sandbox",
"recursive": false
}
{
"error": "No sandbox available for this task"
}
This endpoint lists files and directories inside the sandbox workspace associated with a task run. By default it lists the top-level contents of
/vercel/sandbox. Use the path and recursive parameters to navigate subdirectories.
Authentication
To use this API, you need a BLACKBOX API Key. Follow these steps to get your API key:- Go to app.blackbox.ai/agent-api and click Get an API Key (requires a Pro subscription)
- Once provisioning completes, you will be redirected to your Dashboard
- From the Dashboard, create an API key to use with all Agent API requests
sk-xxxxxxxxxxxxxxxxxxxxxx
Headers
string
required
API Key of the form
Bearer <api_key>.Example: Bearer sk_b41b647ffbfed27f616560Path Parameters
string
required
The unique run identifier returned when the task was created.Example:
a1b2c3d4-e5f6-7890-abcd-ef1234567890Query Parameters
string
default:"/vercel/sandbox"
Directory path to list inside the sandbox.Default:
/vercel/sandboxExample: path=/vercel/sandbox/srcboolean
default:"false"
Whether to list files recursively in all subdirectories.Default:
falseExample: recursive=trueResponse Fields
array
string
The directory path that was listed.
boolean
Whether the listing was recursive.
curl 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/files' \
-H 'Authorization: Bearer YOUR_API_KEY'
curl 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/files?recursive=true' \
-H 'Authorization: Bearer YOUR_API_KEY'
const API_KEY = "YOUR_API_KEY";
const RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
const response = await fetch(
`https://agent.blackbox.ai/api/v1/tasks/${RUN_ID}/files?recursive=true`,
{ headers: { Authorization: `Bearer ${API_KEY}` } }
);
const data = await response.json();
data.files.forEach(f => console.log(`${f.type}\t${f.path}\t${f.size ?? "-"}`));
import requests
API_KEY = "YOUR_API_KEY"
RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
response = requests.get(
f"https://agent.blackbox.ai/api/v1/tasks/{RUN_ID}/files",
headers={"Authorization": f"Bearer {API_KEY}"},
params={"recursive": "true"},
)
data = response.json()
for f in data["files"]:
print(f"{f['type']}\t{f['path']}\t{f.get('size', '-')}")
{
"files": [
{
"name": "src",
"path": "/vercel/sandbox/src",
"type": "directory",
"size": null
},
{
"name": "package.json",
"path": "/vercel/sandbox/package.json",
"type": "file",
"size": 1024
},
{
"name": "README.md",
"path": "/vercel/sandbox/README.md",
"type": "file",
"size": 512
},
{
"name": "README.fr.md",
"path": "/vercel/sandbox/README.fr.md",
"type": "file",
"size": 648
}
],
"path": "/vercel/sandbox",
"recursive": false
}
{
"error": "No sandbox available for this task"
}
Error Codes
| Status Code | Error | Description |
|---|---|---|
| 200 | Success | File list returned |
| 401 | Unauthorized | Invalid or missing API key |
| 403 | Forbidden | Task belongs to a different user |
| 404 | Not Found | Task not found or no sandbox available |
| 500 | Internal Server Error | Failed to list files |