Skip to main content
POST
/
api
/
v1
/
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'

{
  "uploaded": [
    {
      "name": "data.csv",
      "path": "/vercel/sandbox/data/data.csv",
      "size": 4096
    }
  ]
}
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 and click Get an API Key (requires a Pro subscription)
  2. Once provisioning completes, you will be redirected to your 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

​
Authorization
string
required
API Key of the form Bearer <api_key>.Example: Bearer sk_b41b647ffbfed27f616560
​
Content-Type
string
required
Must be multipart/form-data (set automatically by most HTTP clients when using form data).

​
Path Parameters

​
runId
string
required
The unique run identifier returned when the task was created.

​
Form Fields

​
file
file
required
One or more file fields. Each file field uploads one file. You can include multiple file fields in a single request.
​
path
string
Target directory inside the sandbox where files will be uploaded.Default: /vercel/sandboxExample: path=/vercel/sandbox/uploads

​
Response Fields

​
uploaded
array
Array of successfully uploaded file entries.
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'

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

​
Error Codes

Status CodeErrorDescription
201CreatedFiles uploaded successfully
400Bad RequestNo files provided or invalid form data
401UnauthorizedInvalid or missing API key
403ForbiddenTask belongs to a different user
404Not FoundTask not found or no sandbox available
500Internal Server ErrorFailed to upload files