curl -OJ 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/files/download' \
-H 'Authorization: Bearer YOUR_API_KEY'
curl -OJ 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/files/download?format=tar' \
-H 'Authorization: Bearer YOUR_API_KEY'
const API_KEY = "YOUR_API_KEY";
const RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
const fs = require("fs");
const response = await fetch(
`https://agent.blackbox.ai/api/v1/tasks/${RUN_ID}/files/download?format=zip`,
{ headers: { Authorization: `Bearer ${API_KEY}` } }
);
const buffer = await response.arrayBuffer();
fs.writeFileSync("workspace.zip", Buffer.from(buffer));
console.log("Downloaded workspace.zip");
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/download",
headers={"Authorization": f"Bearer {API_KEY}"},
params={"format": "zip"},
)
with open("workspace.zip", "wb") as f:
f.write(response.content)
print(f"Downloaded {len(response.content)} bytes")
HTTP/1.1 200 OK
Content-Type: application/zip
Content-Disposition: attachment; filename="workspace-a1b2c3d4.zip"
Content-Length: 204800
<binary zip data>
{
"error": "No sandbox available for this task"
}
{
"error": "Failed to create archive: zip: command not found"
}
File Management
Download Workspace
Download the entire sandbox workspace (or a subdirectory) as a zip or tar.gz archive.
GET
/
api
/
v1
/
tasks
/
{runId}
/
files
/
download
curl -OJ 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/files/download' \
-H 'Authorization: Bearer YOUR_API_KEY'
curl -OJ 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/files/download?format=tar' \
-H 'Authorization: Bearer YOUR_API_KEY'
const API_KEY = "YOUR_API_KEY";
const RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
const fs = require("fs");
const response = await fetch(
`https://agent.blackbox.ai/api/v1/tasks/${RUN_ID}/files/download?format=zip`,
{ headers: { Authorization: `Bearer ${API_KEY}` } }
);
const buffer = await response.arrayBuffer();
fs.writeFileSync("workspace.zip", Buffer.from(buffer));
console.log("Downloaded workspace.zip");
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/download",
headers={"Authorization": f"Bearer {API_KEY}"},
params={"format": "zip"},
)
with open("workspace.zip", "wb") as f:
f.write(response.content)
print(f"Downloaded {len(response.content)} bytes")
HTTP/1.1 200 OK
Content-Type: application/zip
Content-Disposition: attachment; filename="workspace-a1b2c3d4.zip"
Content-Length: 204800
<binary zip data>
{
"error": "No sandbox available for this task"
}
{
"error": "Failed to create archive: zip: command not found"
}
This endpoint packages the sandbox workspace into a downloadable archive. You can download the entire workspace or a specific subdirectory, in either
zip or tar.gz format.
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.
Query Parameters
string
default:"/vercel/sandbox"
Workspace path to archive.Default:
/vercel/sandboxExample: path=/vercel/sandbox/srcstring
default:"zip"
Archive format.
"zip"— ZIP archive (default)"tar"— gzipped tarball (.tar.gz)
format=tarResponse
Returns a binary file download with appropriate headers:Content-Type:application/ziporapplication/gzipContent-Disposition:attachment; filename="workspace-<runId-prefix>.<ext>"Content-Length: size in bytes
curl -OJ 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/files/download' \
-H 'Authorization: Bearer YOUR_API_KEY'
curl -OJ 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/files/download?format=tar' \
-H 'Authorization: Bearer YOUR_API_KEY'
const API_KEY = "YOUR_API_KEY";
const RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
const fs = require("fs");
const response = await fetch(
`https://agent.blackbox.ai/api/v1/tasks/${RUN_ID}/files/download?format=zip`,
{ headers: { Authorization: `Bearer ${API_KEY}` } }
);
const buffer = await response.arrayBuffer();
fs.writeFileSync("workspace.zip", Buffer.from(buffer));
console.log("Downloaded workspace.zip");
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/download",
headers={"Authorization": f"Bearer {API_KEY}"},
params={"format": "zip"},
)
with open("workspace.zip", "wb") as f:
f.write(response.content)
print(f"Downloaded {len(response.content)} bytes")
HTTP/1.1 200 OK
Content-Type: application/zip
Content-Disposition: attachment; filename="workspace-a1b2c3d4.zip"
Content-Length: 204800
<binary zip data>
{
"error": "No sandbox available for this task"
}
{
"error": "Failed to create archive: zip: command not found"
}
Error Codes
| Status Code | Error | Description |
|---|---|---|
| 200 | Success | Archive downloaded |
| 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 create or stream archive |