> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blackbox.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Download Workspace

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

1. Go to [app.blackbox.ai/agent-api](https://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](https://app.blackbox.ai/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

<ParamField header="Authorization" type="string" required>
  API Key of the form `Bearer <api_key>`.

  Example: `Bearer sk_b41b647ffbfed27f616560`
</ParamField>

## Path Parameters

<ParamField path="runId" type="string" required>
  The unique run identifier returned when the task was created.
</ParamField>

## Query Parameters

<ParamField query="path" type="string" default="/vercel/sandbox">
  Workspace path to archive.

  Default: `/vercel/sandbox`

  Example: `path=/vercel/sandbox/src`
</ParamField>

<ParamField query="format" type="string" default="zip">
  Archive format.

  * `"zip"` — ZIP archive (default)
  * `"tar"` — gzipped tarball (`.tar.gz`)

  Example: `format=tar`
</ParamField>

## 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

<RequestExample>
  ```bash Download as ZIP theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl -OJ 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/files/download' \
    -H 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```bash Download as TAR theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl -OJ 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/files/download?format=tar' \
    -H 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  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");
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  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")
  ```
</RequestExample>

<ResponseExample>
  ```text Success Response theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  HTTP/1.1 200 OK
  Content-Type: application/zip
  Content-Disposition: attachment; filename="workspace-a1b2c3d4.zip"
  Content-Length: 204800

  <binary zip data>
  ```

  ```json Error - No Sandbox theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "error": "No sandbox available for this task"
  }
  ```

  ```json Error - Archive Failed theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "error": "Failed to create archive: zip: command not found"
  }
  ```
</ResponseExample>

## 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     |