Upload Files

POSThttps://agent.blackbox.ai/api/v1/tasks/{runId}/files/upload

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:

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

Content-Typestringrequired

Must be multipart/form-data (set automatically by most HTTP clients when using form data).

Path Parameters

runIdstringrequired

The unique run identifier returned when the task was created.

Form Fields

filefilerequired

One or more file fields. Each file field uploads one file. You can include multiple file fields in a single request.

pathstring

Target directory inside the sandbox where files will be uploaded.

Default: /vercel/sandbox

Example: path=/vercel/sandbox/uploads

Response Fields

uploadedarray

Array of successfully uploaded file entries.

Uploaded File

namestring

Original file name.

pathstring

Full absolute path inside the sandbox where the file was written.

sizenumber

File size in bytes.

Request Example

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'

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'

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)`));

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

Response Example

{
  "uploaded": [
    {
      "name": "data.csv",
      "path": "/vercel/sandbox/data/data.csv",
      "size": 4096
    }
  ]
}

{
  "uploaded": [
    {
      "name": "schema.sql",
      "path": "/vercel/sandbox/db/schema.sql",
      "size": 2048
    },
    {
      "name": "seed.sql",
      "path": "/vercel/sandbox/db/seed.sql",
      "size": 1024
    }
  ]
}

{
  "error": "No files provided. Include at least one 'file' field."
}

{
  "error": "No sandbox available for this task"
}

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