> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blackbox.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Read / Write / Delete File

> 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:

1. Go to [app.blackbox.ai/agent-api](https://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](https://app.blackbox.ai/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

<ParamField header="Authorization" type="string" required>
  API Key of the form `Bearer <api_key>`.

  Example: `Bearer sk_b41b647ffbfed27f616560`
</ParamField>

<ParamField header="Content-Type" type="string">
  Required for `PUT` requests. Must be `application/json`.
</ParamField>

## Path Parameters

<ParamField path="runId" type="string" required>
  The unique run identifier returned when the task was created.
</ParamField>

<ParamField path="path" type="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.
</ParamField>

***

## GET — Read a File

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

### Response Fields (GET)

<ResponseField name="path" type="string">
  Absolute path of the file inside the sandbox.
</ResponseField>

<ResponseField name="content" type="string">
  File content. UTF-8 text for text files, base64-encoded for binary files.
</ResponseField>

<ResponseField name="encoding" type="string">
  `"text"` for text files, `"base64"` for binary files.
</ResponseField>

<ResponseField name="mimeType" type="string">
  MIME type: `"text/plain"` for text, `"application/octet-stream"` for binary.
</ResponseField>

<ResponseField name="size" type="number">
  File size in bytes.
</ResponseField>

***

## PUT — Write a File

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

### Request Body (PUT)

<ParamField body="content" type="string" required>
  File content to write. Use UTF-8 text or base64-encoded string depending on `encoding`.
</ParamField>

<ParamField body="encoding" type="string" default="text">
  Encoding of the `content` field.

  * `"text"` — plain UTF-8 string (default)
  * `"base64"` — base64-encoded binary content
</ParamField>

### Response Fields (PUT)

<ResponseField name="success" type="boolean">
  Whether the write succeeded.
</ResponseField>

<ResponseField name="path" type="string">
  Absolute path of the written file.
</ResponseField>

<ResponseField name="size" type="number">
  Size of the written file in bytes.
</ResponseField>

***

## DELETE — Delete a File or Directory

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

### Response Fields (DELETE)

<ResponseField name="success" type="boolean">
  Whether the deletion succeeded.
</ResponseField>

<ResponseField name="path" type="string">
  Absolute path of the deleted file or directory.
</ResponseField>

<RequestExample>
  ```bash Read File theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl 'https://agent.blackbox.ai/api/v1/tasks/RUN_ID/files/vercel/sandbox/README.fr.md' \
    -H 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```bash Write File theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  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"
    }'
  ```

  ```bash Delete File theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl -X DELETE 'https://agent.blackbox.ai/api/v1/tasks/RUN_ID/files/vercel/sandbox/old-file.txt' \
    -H 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```javascript Node.js - Read theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  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);
  ```

  ```javascript Node.js - Write theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  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}`);
  ```

  ```python Python - Read theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  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"])
  ```

  ```python Python - Write theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  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())
  ```
</RequestExample>

<ResponseExample>
  ```json GET - Text File theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "path": "/vercel/sandbox/README.fr.md",
    "content": "# Bienvenue\n\nCeci est le README en français...",
    "encoding": "text",
    "mimeType": "text/plain",
    "size": 648
  }
  ```

  ```json GET - Binary File theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "path": "/vercel/sandbox/image.png",
    "content": "iVBORw0KGgoAAAANSUhEUgAA...",
    "encoding": "base64",
    "mimeType": "application/octet-stream",
    "size": 20480
  }
  ```

  ```json PUT - Success theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "success": true,
    "path": "/vercel/sandbox/config.json",
    "size": 22
  }
  ```

  ```json DELETE - Success theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "success": true,
    "path": "/vercel/sandbox/old-file.txt"
  }
  ```

  ```json Error - File Not Found theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "error": "File not found"
  }
  ```
</ResponseExample>

## 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                         |