curl 'https://agent.blackbox.ai/api/v1/tasks/RUN_ID/files/vercel/sandbox/README.fr.md' \
-H 'Authorization: Bearer YOUR_API_KEY'
curl -X PUT 'https://agent.blackbox.ai/api/v1/tasks/RUN_ID/files/vercel/sandbox/config.json' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"content": "{ \"version\": \"1.0.0\" }",
"encoding": "text"
}'
curl -X DELETE 'https://agent.blackbox.ai/api/v1/tasks/RUN_ID/files/vercel/sandbox/old-file.txt' \
-H 'Authorization: Bearer YOUR_API_KEY'
const API_KEY = "YOUR_API_KEY";
const RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
const FILE_PATH = "vercel/sandbox/README.fr.md";
const response = await fetch(
`https://agent.blackbox.ai/api/v1/tasks/${RUN_ID}/files/${FILE_PATH}`,
{ headers: { Authorization: `Bearer ${API_KEY}` } }
);
const data = await response.json();
console.log(data.content);
const API_KEY = "YOUR_API_KEY";
const RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
const FILE_PATH = "vercel/sandbox/config.json";
const response = await fetch(
`https://agent.blackbox.ai/api/v1/tasks/${RUN_ID}/files/${FILE_PATH}`,
{
method: "PUT",
headers: {
Authorization: `Bearer ${API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
content: JSON.stringify({ version: "1.0.0" }, null, 2),
encoding: "text",
}),
}
);
const data = await response.json();
console.log(`Written ${data.size} bytes to ${data.path}`);
import requests
API_KEY = "YOUR_API_KEY"
RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
FILE_PATH = "vercel/sandbox/README.fr.md"
response = requests.get(
f"https://agent.blackbox.ai/api/v1/tasks/{RUN_ID}/files/{FILE_PATH}",
headers={"Authorization": f"Bearer {API_KEY}"},
)
data = response.json()
print(data["content"])
import requests
API_KEY = "YOUR_API_KEY"
RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
FILE_PATH = "vercel/sandbox/config.json"
response = requests.put(
f"https://agent.blackbox.ai/api/v1/tasks/{RUN_ID}/files/{FILE_PATH}",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json={"content": '{"version": "1.0.0"}', "encoding": "text"},
)
print(response.json())
{
"path": "/vercel/sandbox/README.fr.md",
"content": "# Bienvenue\n\nCeci est le README en français...",
"encoding": "text",
"mimeType": "text/plain",
"size": 648
}
{
"path": "/vercel/sandbox/image.png",
"content": "iVBORw0KGgoAAAANSUhEUgAA...",
"encoding": "base64",
"mimeType": "application/octet-stream",
"size": 20480
}
{
"success": true,
"path": "/vercel/sandbox/config.json",
"size": 22
}
{
"success": true,
"path": "/vercel/sandbox/old-file.txt"
}
{
"error": "File not found"
}
File Management
Read / Write / Delete File
Read, create/overwrite, or delete a single file in the task’s sandbox workspace using GET, PUT, or DELETE.
GET
/
api
/
v1
/
tasks
/
{runId}
/
files
/
{path}
curl 'https://agent.blackbox.ai/api/v1/tasks/RUN_ID/files/vercel/sandbox/README.fr.md' \
-H 'Authorization: Bearer YOUR_API_KEY'
curl -X PUT 'https://agent.blackbox.ai/api/v1/tasks/RUN_ID/files/vercel/sandbox/config.json' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"content": "{ \"version\": \"1.0.0\" }",
"encoding": "text"
}'
curl -X DELETE 'https://agent.blackbox.ai/api/v1/tasks/RUN_ID/files/vercel/sandbox/old-file.txt' \
-H 'Authorization: Bearer YOUR_API_KEY'
const API_KEY = "YOUR_API_KEY";
const RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
const FILE_PATH = "vercel/sandbox/README.fr.md";
const response = await fetch(
`https://agent.blackbox.ai/api/v1/tasks/${RUN_ID}/files/${FILE_PATH}`,
{ headers: { Authorization: `Bearer ${API_KEY}` } }
);
const data = await response.json();
console.log(data.content);
const API_KEY = "YOUR_API_KEY";
const RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
const FILE_PATH = "vercel/sandbox/config.json";
const response = await fetch(
`https://agent.blackbox.ai/api/v1/tasks/${RUN_ID}/files/${FILE_PATH}`,
{
method: "PUT",
headers: {
Authorization: `Bearer ${API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
content: JSON.stringify({ version: "1.0.0" }, null, 2),
encoding: "text",
}),
}
);
const data = await response.json();
console.log(`Written ${data.size} bytes to ${data.path}`);
import requests
API_KEY = "YOUR_API_KEY"
RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
FILE_PATH = "vercel/sandbox/README.fr.md"
response = requests.get(
f"https://agent.blackbox.ai/api/v1/tasks/{RUN_ID}/files/{FILE_PATH}",
headers={"Authorization": f"Bearer {API_KEY}"},
)
data = response.json()
print(data["content"])
import requests
API_KEY = "YOUR_API_KEY"
RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
FILE_PATH = "vercel/sandbox/config.json"
response = requests.put(
f"https://agent.blackbox.ai/api/v1/tasks/{RUN_ID}/files/{FILE_PATH}",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json={"content": '{"version": "1.0.0"}', "encoding": "text"},
)
print(response.json())
{
"path": "/vercel/sandbox/README.fr.md",
"content": "# Bienvenue\n\nCeci est le README en français...",
"encoding": "text",
"mimeType": "text/plain",
"size": 648
}
{
"path": "/vercel/sandbox/image.png",
"content": "iVBORw0KGgoAAAANSUhEUgAA...",
"encoding": "base64",
"mimeType": "application/octet-stream",
"size": 20480
}
{
"success": true,
"path": "/vercel/sandbox/config.json",
"size": 22
}
{
"success": true,
"path": "/vercel/sandbox/old-file.txt"
}
{
"error": "File not found"
}
This endpoint provides full CRUD access to individual files in the task’s sandbox workspace. Use
GET to read a file, PUT to create or overwrite it, and DELETE to remove it.
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_b41b647ffbfed27f616560string
Required for
PUT requests. Must be application/json.Path Parameters
string
required
The unique run identifier returned when the task was created.
string
required
Absolute path to the file inside the sandbox, without a leading slash in the URL.Example: For file
/vercel/sandbox/src/index.ts, use vercel/sandbox/src/index.ts in the URL path.GET — Read a File
Returns the file content as text (UTF-8) or base64 for binary files.Response Fields (GET)
string
Absolute path of the file inside the sandbox.
string
File content. UTF-8 text for text files, base64-encoded for binary files.
string
"text" for text files, "base64" for binary files.string
MIME type:
"text/plain" for text, "application/octet-stream" for binary.number
File size in bytes.
PUT — Write a File
Creates or overwrites a file. Parent directories are created automatically.Request Body (PUT)
string
required
File content to write. Use UTF-8 text or base64-encoded string depending on
encoding.string
default:"text"
Encoding of the
content field."text"— plain UTF-8 string (default)"base64"— base64-encoded binary content
Response Fields (PUT)
boolean
Whether the write succeeded.
string
Absolute path of the written file.
number
Size of the written file in bytes.
DELETE — Delete a File or Directory
Deletes a file or directory (recursively). Cannot delete the workspace root (/vercel/sandbox or /).
Response Fields (DELETE)
boolean
Whether the deletion succeeded.
string
Absolute path of the deleted file or directory.
curl 'https://agent.blackbox.ai/api/v1/tasks/RUN_ID/files/vercel/sandbox/README.fr.md' \
-H 'Authorization: Bearer YOUR_API_KEY'
curl -X PUT 'https://agent.blackbox.ai/api/v1/tasks/RUN_ID/files/vercel/sandbox/config.json' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"content": "{ \"version\": \"1.0.0\" }",
"encoding": "text"
}'
curl -X DELETE 'https://agent.blackbox.ai/api/v1/tasks/RUN_ID/files/vercel/sandbox/old-file.txt' \
-H 'Authorization: Bearer YOUR_API_KEY'
const API_KEY = "YOUR_API_KEY";
const RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
const FILE_PATH = "vercel/sandbox/README.fr.md";
const response = await fetch(
`https://agent.blackbox.ai/api/v1/tasks/${RUN_ID}/files/${FILE_PATH}`,
{ headers: { Authorization: `Bearer ${API_KEY}` } }
);
const data = await response.json();
console.log(data.content);
const API_KEY = "YOUR_API_KEY";
const RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
const FILE_PATH = "vercel/sandbox/config.json";
const response = await fetch(
`https://agent.blackbox.ai/api/v1/tasks/${RUN_ID}/files/${FILE_PATH}`,
{
method: "PUT",
headers: {
Authorization: `Bearer ${API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
content: JSON.stringify({ version: "1.0.0" }, null, 2),
encoding: "text",
}),
}
);
const data = await response.json();
console.log(`Written ${data.size} bytes to ${data.path}`);
import requests
API_KEY = "YOUR_API_KEY"
RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
FILE_PATH = "vercel/sandbox/README.fr.md"
response = requests.get(
f"https://agent.blackbox.ai/api/v1/tasks/{RUN_ID}/files/{FILE_PATH}",
headers={"Authorization": f"Bearer {API_KEY}"},
)
data = response.json()
print(data["content"])
import requests
API_KEY = "YOUR_API_KEY"
RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
FILE_PATH = "vercel/sandbox/config.json"
response = requests.put(
f"https://agent.blackbox.ai/api/v1/tasks/{RUN_ID}/files/{FILE_PATH}",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json={"content": '{"version": "1.0.0"}', "encoding": "text"},
)
print(response.json())
{
"path": "/vercel/sandbox/README.fr.md",
"content": "# Bienvenue\n\nCeci est le README en français...",
"encoding": "text",
"mimeType": "text/plain",
"size": 648
}
{
"path": "/vercel/sandbox/image.png",
"content": "iVBORw0KGgoAAAANSUhEUgAA...",
"encoding": "base64",
"mimeType": "application/octet-stream",
"size": 20480
}
{
"success": true,
"path": "/vercel/sandbox/config.json",
"size": 22
}
{
"success": true,
"path": "/vercel/sandbox/old-file.txt"
}
{
"error": "File not found"
}
Error Codes
| Status Code | Error | Description |
|---|---|---|
| 200 | Success | Operation completed |
| 400 | Bad Request | Invalid body or attempt to delete workspace root |
| 401 | Unauthorized | Invalid or missing API key |
| 403 | Forbidden | Task belongs to a different user |
| 404 | Not Found | Task, sandbox, or file not found |
| 500 | Internal Server Error | Read/write/delete failed |