Read / Write / Delete File

GEThttps://agent.blackbox.ai/api/v1/tasks/{runId}/files/{path}

Read, create/overwrite, or delete a single file in the task's sandbox workspace using GET, PUT, or DELETE.

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

Authorizationstringrequired

API Key of the form Bearer <api_key>.

Example: Bearer sk_b41b647ffbfed27f616560

Content-Typestring

Required for PUT requests. Must be application/json.

Path Parameters

runIdstringrequired

The unique run identifier returned when the task was created.

pathstringrequired

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)

pathstring

Absolute path of the file inside the sandbox.

contentstring

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

encodingstring

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

mimeTypestring

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

sizenumber

File size in bytes.

PUT — Write a File

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

Request Body (PUT)

contentstringrequired

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

encodingstringdefault: text

Encoding of the content field.

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

Response Fields (PUT)

successboolean

Whether the write succeeded.

pathstring

Absolute path of the written file.

sizenumber

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)

successboolean

Whether the deletion succeeded.

pathstring

Absolute path of the deleted file or directory.

Request Example

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

curl -X PUT 'https://agent.blackbox.ai/api/v1/tasks/RUN_ID/files/vercel/sandbox/config.json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "content": "{ \"version\": \"1.0.0\" }",
    "encoding": "text"
  }'

curl -X DELETE 'https://agent.blackbox.ai/api/v1/tasks/RUN_ID/files/vercel/sandbox/old-file.txt' \
  -H 'Authorization: Bearer YOUR_API_KEY'

const API_KEY = "YOUR_API_KEY";
const RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
const FILE_PATH = "vercel/sandbox/README.fr.md";

const response = await fetch(
  `https://agent.blackbox.ai/api/v1/tasks/${RUN_ID}/files/${FILE_PATH}`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);
const data = await response.json();
console.log(data.content);

const API_KEY = "YOUR_API_KEY";
const RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
const FILE_PATH = "vercel/sandbox/config.json";

const response = await fetch(
  `https://agent.blackbox.ai/api/v1/tasks/${RUN_ID}/files/${FILE_PATH}`,
  {
    method: "PUT",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      content: JSON.stringify({ version: "1.0.0" }, null, 2),
      encoding: "text",
    }),
  }
);
const data = await response.json();
console.log(`Written ${data.size} bytes to ${data.path}`);

import requests

API_KEY = "YOUR_API_KEY"
RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
FILE_PATH = "vercel/sandbox/README.fr.md"

response = requests.get(
    f"https://agent.blackbox.ai/api/v1/tasks/{RUN_ID}/files/{FILE_PATH}",
    headers={"Authorization": f"Bearer {API_KEY}"},
)
data = response.json()
print(data["content"])

import requests

API_KEY = "YOUR_API_KEY"
RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
FILE_PATH = "vercel/sandbox/config.json"

response = requests.put(
    f"https://agent.blackbox.ai/api/v1/tasks/{RUN_ID}/files/{FILE_PATH}",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={"content": '{"version": "1.0.0"}', "encoding": "text"},
)
print(response.json())

Response Example

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

{
  "path": "/vercel/sandbox/image.png",
  "content": "iVBORw0KGgoAAAANSUhEUgAA...",
  "encoding": "base64",
  "mimeType": "application/octet-stream",
  "size": 20480
}

{
  "success": true,
  "path": "/vercel/sandbox/config.json",
  "size": 22
}

{
  "success": true,
  "path": "/vercel/sandbox/old-file.txt"
}

{
  "error": "File not found"
}

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