Skip to main content
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'

HTTP/1.1 200 OK
Content-Type: application/zip
Content-Disposition: attachment; filename="workspace-a1b2c3d4.zip"
Content-Length: 204800

<binary zip data>
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:
  1. Go to app.blackbox.ai/agent-api and click Get an API Key (requires a Pro subscription)
  2. Once provisioning completes, you will be redirected to your Dashboard
  3. From the Dashboard, create an API key to use with all Agent API requests
Your API key will be in the format: sk-xxxxxxxxxxxxxxxxxxxxxx

​
Headers

​
Authorization
string
required
API Key of the form Bearer <api_key>.Example: Bearer sk_b41b647ffbfed27f616560

​
Path Parameters

​
runId
string
required
The unique run identifier returned when the task was created.

​
Query Parameters

​
path
string
default:"/vercel/sandbox"
Workspace path to archive.Default: /vercel/sandboxExample: path=/vercel/sandbox/src
​
format
string
default:"zip"
Archive format.
  • "zip" — ZIP archive (default)
  • "tar" — gzipped tarball (.tar.gz)
Example: format=tar

​
Response

Returns a binary file download with appropriate headers:
  • Content-Type: application/zip or application/gzip
  • Content-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'

HTTP/1.1 200 OK
Content-Type: application/zip
Content-Disposition: attachment; filename="workspace-a1b2c3d4.zip"
Content-Length: 204800

<binary zip data>

​
Error Codes

Status CodeErrorDescription
200SuccessArchive downloaded
401UnauthorizedInvalid or missing API key
403ForbiddenTask belongs to a different user
404Not FoundTask not found or no sandbox available
500Internal Server ErrorFailed to create or stream archive