Files API

Each environment has a workspace for files, backed by Google Cloud Storage. The Files API lets you upload, download, list, and manage files that agents can access during execution.

Overview

Files in an environment workspace are:

Accessible to agents executing in that environment
Synced automatically with cloud storage
Persisted between executions
Isolated per environment

Files are scoped to environments. Each environment has its own isolated workspace.

List Files

Returns files in an environment workspace.


GET /v1/environments/:environmentId/files

Query Parameters

Parameter	Type	Default	Description
`path`	string	`/`	Directory path to list
`recursive`	boolean	`false`	Include subdirectories

Example

cURL


curl "https://api.computer-agents.com/v1/environments/env_abc123/files?path=/src" \
  -H "Authorization: Bearer $API_KEY"

Response


{
  "object": "list",
  "data": [
    {
      "name": "app.py",
      "path": "/src/app.py",
      "type": "file",
      "size": 2048,
      "mimeType": "text/x-python",
      "modifiedAt": "2025-01-15T10:30:00.000Z"
    },
    {
      "name": "utils",
      "path": "/src/utils",
      "type": "directory",
      "modifiedAt": "2025-01-14T08:00:00.000Z"
    }
  ],
  "path": "/src",
  "has_more": false,
  "total_count": 2
}

File Object

Attribute	Type	Description
`name`	string	File or directory name
`path`	string	Full path from workspace root
`type`	string	`file` or `directory`
`size`	number	Size in bytes (files only)
`mimeType`	string	MIME type (files only)
`modifiedAt`	string	Last modification time

Get File

Downloads a file’s content.


GET /v1/environments/:environmentId/files/:path

Path Parameters

Parameter	Description
`path`	URL-encoded file path (e.g., `src%2Fapp.py`)

Query Parameters

Parameter	Type	Description
`download`	boolean	Force download (vs inline)

Example


# Get file content
curl "https://api.computer-agents.com/v1/environments/env_abc123/files/src%2Fapp.py" \
  -H "Authorization: Bearer $API_KEY"
 
# Download as attachment
curl "https://api.computer-agents.com/v1/environments/env_abc123/files/src%2Fapp.py?download=true" \
  -H "Authorization: Bearer $API_KEY" \
  -o app.py

Response

Returns the file content with appropriate Content-Type header.


Content-Type: text/x-python
Content-Length: 2048

from flask import Flask

app = Flask(__name__)
...

Upload File

Uploads a file to the environment workspace.


PUT /v1/environments/:environmentId/files/:path

Path Parameters

Parameter	Description
`path`	Destination path (URL-encoded)

Headers

Header	Required	Description
`Content-Type`	Yes	File MIME type
`Content-Length`	Yes	File size in bytes

Example

cURL


curl -X PUT "https://api.computer-agents.com/v1/environments/env_abc123/files/src%2Fnew_file.py" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: text/x-python" \
  --data-binary @new_file.py

Response


{
  "success": true,
  "file": {
    "name": "new_file.py",
    "path": "/src/new_file.py",
    "type": "file",
    "size": 142,
    "mimeType": "text/x-python",
    "modifiedAt": "2025-01-20T12:00:00.000Z"
  }
}

Delete File

Deletes a file or directory.


DELETE /v1/environments/:environmentId/files/:path

Query Parameters

Parameter	Type	Default	Description
`recursive`	boolean	`false`	Delete directory contents

Deleting a directory requires recursive=true if it contains files.

Example


# Delete single file
curl -X DELETE "https://api.computer-agents.com/v1/environments/env_abc123/files/src%2Fold_file.py" \
  -H "Authorization: Bearer $API_KEY"
 
# Delete directory recursively
curl -X DELETE "https://api.computer-agents.com/v1/environments/env_abc123/files/old_folder?recursive=true" \
  -H "Authorization: Bearer $API_KEY"

Response


{
  "success": true
}

Create Directory

Creates a new directory in the workspace. Parent directories are created automatically if they don’t exist.


POST /v1/environments/:environmentId/files/mkdir

Request Body

Parameter	Type	Required	Description
`path`	string	Yes	Directory path to create (relative to workspace root)

Example

cURL


curl -X POST "https://api.computer-agents.com/v1/environments/env_abc123/files/mkdir" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "src/components"}'

JavaScript


await fetch(
  `https://api.computer-agents.com/v1/environments/${environmentId}/files/mkdir`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ path: 'src/components' })
  }
);

SDK


import { ComputerAgentsClient } from 'computer-agents';
 
const client = new ComputerAgentsClient({ apiKey: process.env.API_KEY });
 
await client.files.createDirectory('env_abc123', 'src/components');

Response


{
  "success": true,
  "path": "src/components",
  "environmentId": "env_abc123"
}

Parent directories are created recursively. Creating src/components/ui will also create src and src/components if they don’t exist.

Bulk Upload

Upload multiple files at once.


POST /v1/environments/:environmentId/files/bulk

Request Body (multipart/form-data)

Field	Type	Description
`files`	File[]	Files to upload
`basePath`	string	Base directory path

Example


curl -X POST "https://api.computer-agents.com/v1/environments/env_abc123/files/bulk" \
  -H "Authorization: Bearer $API_KEY" \
  -F "basePath=/src" \
  -F "files=@app.py" \
  -F "files=@utils.py" \
  -F "files=@config.py"

Response


{
  "success": true,
  "uploaded": [
    { "path": "/src/app.py", "size": 2048 },
    { "path": "/src/utils.py", "size": 1024 },
    { "path": "/src/config.py", "size": 512 }
  ],
  "total": 3
}

Errors

Status	Error	Description
400	`Bad Request`	Invalid path or content
404	`Not Found`	File or directory not found
409	`Conflict`	File already exists
413	`Payload Too Large`	File exceeds size limit
507	`Insufficient Storage`	Workspace quota exceeded

Size Limits

Limit	Value
Single file	100 MB
Bulk upload	500 MB total
Workspace	10 GB per environment

Environments - Parent resource
Threads - Agent executions with file access

Files API

Overview

List Files

Query Parameters

Example

cURL

JavaScript

Response

File Object

Get File

Path Parameters

Query Parameters

Example

Response

Upload File

Path Parameters

Headers

Example

cURL

JavaScript

Response

Delete File

Query Parameters

Example

Response

Create Directory

Request Body

Example

cURL

JavaScript

SDK

Response

Bulk Upload

Request Body (multipart/form-data)

Example

Response

Errors

Size Limits

Related