Download Workspace

GEThttps://agent.blackbox.ai/api/v1/tasks/{runId}/files/download

Download the entire sandbox workspace (or a subdirectory) as a zip or tar.gz archive.

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

Your API key will be in the format: sk-xxxxxxxxxxxxxxxxxxxxxx

Headers

Authorizationstringrequired

API Key of the form Bearer <api_key>.

Example: Bearer sk_b41b647ffbfed27f616560

Path Parameters

runIdstringrequired

The unique run identifier returned when the task was created.

Query Parameters

pathstringdefault: /vercel/sandbox

Workspace path to archive.

Default: /vercel/sandbox

Example: path=/vercel/sandbox/src

formatstringdefault: 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

Request Example

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")

Response Example

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