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

# Upload Files

> Upload one or more files into the task's sandbox workspace using multipart/form-data.

This endpoint uploads one or more files into the sandbox workspace associated with a task run. Files are uploaded via `multipart/form-data`. The target directory is created automatically if it doesn't exist.

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

<ParamField header="Content-Type" type="string" required>
  Must be `multipart/form-data` (set automatically by most HTTP clients when using form data).
</ParamField>

## Path Parameters

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

## Form Fields

<ParamField body="file" type="file" required>
  One or more file fields. Each `file` field uploads one file. You can include multiple `file` fields in a single request.
</ParamField>

<ParamField body="path" type="string">
  Target directory inside the sandbox where files will be uploaded.

  Default: `/vercel/sandbox`

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

## Response Fields

<ResponseField name="uploaded" type="array">
  Array of successfully uploaded file entries.

  <Expandable title="Uploaded File">
    <ResponseField name="name" type="string">
      Original file name.
    </ResponseField>

    <ResponseField name="path" type="string">
      Full absolute path inside the sandbox where the file was written.
    </ResponseField>

    <ResponseField name="size" type="number">
      File size in bytes.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash Single File theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl -X POST 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/files/upload' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -F 'file=@./data.csv' \
    -F 'path=/vercel/sandbox/data'
  ```

  ```bash Multiple Files theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl -X POST 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/files/upload' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -F 'file=@./schema.sql' \
    -F 'file=@./seed.sql' \
    -F 'path=/vercel/sandbox/db'
  ```

  ```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 formData = new FormData();
  formData.append("file", new Blob([fs.readFileSync("data.csv")]), "data.csv");
  formData.append("path", "/vercel/sandbox/data");

  const response = await fetch(
    `https://agent.blackbox.ai/api/v1/tasks/${RUN_ID}/files/upload`,
    {
      method: "POST",
      headers: { Authorization: `Bearer ${API_KEY}` },
      body: formData,
    }
  );

  const data = await response.json();
  data.uploaded.forEach(f => console.log(`Uploaded: ${f.path} (${f.size} bytes)`));
  ```

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

  with open("data.csv", "rb") as f:
      response = requests.post(
          f"https://agent.blackbox.ai/api/v1/tasks/{RUN_ID}/files/upload",
          headers={"Authorization": f"Bearer {API_KEY}"},
          files={"file": ("data.csv", f, "text/csv")},
          data={"path": "/vercel/sandbox/data"},
      )

  data = response.json()
  for uploaded in data["uploaded"]:
      print(f"Uploaded: {uploaded['path']} ({uploaded['size']} bytes)")
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "uploaded": [
      {
        "name": "data.csv",
        "path": "/vercel/sandbox/data/data.csv",
        "size": 4096
      }
    ]
  }
  ```

  ```json Multiple Files theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "uploaded": [
      {
        "name": "schema.sql",
        "path": "/vercel/sandbox/db/schema.sql",
        "size": 2048
      },
      {
        "name": "seed.sql",
        "path": "/vercel/sandbox/db/seed.sql",
        "size": 1024
      }
    ]
  }
  ```

  ```json Error - No Files theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "error": "No files provided. Include at least one 'file' field."
  }
  ```

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

## Error Codes

| Status Code | Error                 | Description                            |
| ----------- | --------------------- | -------------------------------------- |
| 201         | Created               | Files uploaded successfully            |
| 400         | Bad Request           | No files provided or invalid form data |
| 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 upload files                 |