Skip to main content
GET
/
api
/
v1
/
tasks
/
{runId}
/
files
curl 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/files' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "files": [
    {
      "name": "src",
      "path": "/vercel/sandbox/src",
      "type": "directory",
      "size": null
    },
    {
      "name": "package.json",
      "path": "/vercel/sandbox/package.json",
      "type": "file",
      "size": 1024
    },
    {
      "name": "README.md",
      "path": "/vercel/sandbox/README.md",
      "type": "file",
      "size": 512
    },
    {
      "name": "README.fr.md",
      "path": "/vercel/sandbox/README.fr.md",
      "type": "file",
      "size": 648
    }
  ],
  "path": "/vercel/sandbox",
  "recursive": false
}
This endpoint lists files and directories inside the sandbox workspace associated with a task run. By default it lists the top-level contents of /vercel/sandbox. Use the path and recursive parameters to navigate subdirectories.

​
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

​
Path Parameters

​
runId
string
required
The unique run identifier returned when the task was created.Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

​
Query Parameters

​
path
string
default:"/vercel/sandbox"
Directory path to list inside the sandbox.Default: /vercel/sandboxExample: path=/vercel/sandbox/src
​
recursive
boolean
default:"false"
Whether to list files recursively in all subdirectories.Default: falseExample: recursive=true

​
Response Fields

​
files
array
Array of file and directory entries.
​
path
string
The directory path that was listed.
​
recursive
boolean
Whether the listing was recursive.
curl 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/files' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "files": [
    {
      "name": "src",
      "path": "/vercel/sandbox/src",
      "type": "directory",
      "size": null
    },
    {
      "name": "package.json",
      "path": "/vercel/sandbox/package.json",
      "type": "file",
      "size": 1024
    },
    {
      "name": "README.md",
      "path": "/vercel/sandbox/README.md",
      "type": "file",
      "size": 512
    },
    {
      "name": "README.fr.md",
      "path": "/vercel/sandbox/README.fr.md",
      "type": "file",
      "size": 648
    }
  ],
  "path": "/vercel/sandbox",
  "recursive": false
}

​
Error Codes

Status CodeErrorDescription
200SuccessFile list returned
401UnauthorizedInvalid or missing API key
403ForbiddenTask belongs to a different user
404Not FoundTask not found or no sandbox available
500Internal Server ErrorFailed to list files