Upload Files

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

{
  "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"
}

POST

api

tasks

{runId}

files

upload

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

{
  "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"
}

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

string

required

API Key of the form Bearer <api_key>.Example: Bearer sk_b41b647ffbfed27f616560

string

required

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

Path Parameters

string

required

The unique run identifier returned when the task was created.

Form Fields

file

required

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

string

Target directory inside the sandbox where files will be uploaded.Default: /vercel/sandboxExample: path=/vercel/sandbox/uploads

Response Fields

array

Array of successfully uploaded file entries.

Show Uploaded File

string

Original file name.

string

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

number

File size in bytes.

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

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

Getting Started

API Reference

Authentication

Headers

Path Parameters

Form Fields

Response Fields

Error Codes

​Authentication

​Headers

​Path Parameters

​Form Fields

​Response Fields

​Error Codes

Authentication

Headers

Path Parameters

Form Fields

Response Fields

Error Codes