Read / Write / Delete File

This endpoint provides full CRUD access to individual files in the task’s sandbox workspace. Use GET to read a file, PUT to create or overwrite it, and DELETE to remove it.

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

Authorization

string

required

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

Content-Type

string

Required for PUT requests. Must be application/json.

Path Parameters

runId

string

required

The unique run identifier returned when the task was created.

path

string

required

Absolute path to the file inside the sandbox, without a leading slash in the URL.Example: For file /vercel/sandbox/src/index.ts, use vercel/sandbox/src/index.ts in the URL path.

GET — Read a File

Returns the file content as text (UTF-8) or base64 for binary files.

Response Fields (GET)

path

string

Absolute path of the file inside the sandbox.

content

string

File content. UTF-8 text for text files, base64-encoded for binary files.

encoding

string

"text" for text files, "base64" for binary files.

mimeType

string

MIME type: "text/plain" for text, "application/octet-stream" for binary.

size

number

File size in bytes.

PUT — Write a File

Creates or overwrites a file. Parent directories are created automatically.

Request Body (PUT)

content

string

required

File content to write. Use UTF-8 text or base64-encoded string depending on encoding.

encoding

string

default:"text"

Encoding of the content field.

"text" — plain UTF-8 string (default)
"base64" — base64-encoded binary content

Response Fields (PUT)

success

boolean

Whether the write succeeded.

path

string

Absolute path of the written file.

size

number

Size of the written file in bytes.

DELETE — Delete a File or Directory

Deletes a file or directory (recursively). Cannot delete the workspace root (/vercel/sandbox or /).

Response Fields (DELETE)

success

boolean

Whether the deletion succeeded.

path

string

Absolute path of the deleted file or directory.

curl 'https://agent.blackbox.ai/api/v1/tasks/RUN_ID/files/vercel/sandbox/README.fr.md' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "path": "/vercel/sandbox/README.fr.md",
  "content": "# Bienvenue\n\nCeci est le README en français...",
  "encoding": "text",
  "mimeType": "text/plain",
  "size": 648
}

Error Codes

Status Code	Error	Description
200	Success	Operation completed
400	Bad Request	Invalid body or attempt to delete workspace root
401	Unauthorized	Invalid or missing API key
403	Forbidden	Task belongs to a different user
404	Not Found	Task, sandbox, or file not found
500	Internal Server Error	Read/write/delete failed

​Authentication

​Headers

​Path Parameters

​GET — Read a File

​Response Fields (GET)

​PUT — Write a File

​Request Body (PUT)

​Response Fields (PUT)

​DELETE — Delete a File or Directory

​Response Fields (DELETE)

​Error Codes

Authentication

Headers

Path Parameters

GET — Read a File

Response Fields (GET)

PUT — Write a File

Request Body (PUT)

Response Fields (PUT)

DELETE — Delete a File or Directory

Response Fields (DELETE)

Error Codes