Files

Manage tenant-scoped files that can be attached to agent runs. Upload files to your tenant store, then reference them when creating agents or running journeys to copy them into the agent workspace.

Overview

There are two file storage contexts. The tenant file store is a shared space where you upload files via the API. The agent workspace is a private sandbox that each agent gets for the duration of its execution. Files flow from the tenant store into agent workspaces, not the other way around.

To get files into an agent, upload them to the tenant store first, then reference their paths when creating an agent or running a journey. The system copies the referenced files into the agent's workspace before execution begins. Once in the workspace, the agent can read, write, and organize files freely. It can also download files from the web and upload files to form inputs on pages.

Limits

Individual file uploads are limited to 50 MB. Total tenant storage is subject to your plan's quota. Uploads that would exceed the quota are rejected with a 507 Insufficient Storage response.

GET /api/v1/files

List directory

Lists files and subdirectories at the given path within the tenant file store.

Parameters

ParameterTypeInRequiredDescription
pathstringqueryNoRelative directory path to list (empty for root)

Status Codes

CodeDescription
200OK
401Unauthorized

Response Body

{
  "files": [
    {
      "name": "report.pdf",
      "path": "docs/reports/report.pdf",
      "size": 102400,
      "is_dir": false,
      "updated_at": "2025-01-15T10:30:00Z"
    },
    {
      "name": "images",
      "path": "docs/reports/images",
      "is_dir": true
    }
  ]
}
GET /api/v1/files
cURL 
Response 
GET /api/v1/files/download 
Download file
Downloads a single file from the tenant file store. Returns the raw file content as application/octet-stream.
Parameters
ParameterTypeInRequiredDescription
 
pathstringqueryYesRelative path of the file to download 
Status Codes
CodeDescription
 
200File content (binary stream)
400Missing path parameter
401Unauthorized
404File not found
GET /api/v1/files/download
 
 
cURL 
Response 
POST /api/v1/files/upload 
Upload files
Upload one or more files via multipart/form-data. Files are placed under the specified path prefix. Max 50MB per file.
Parameters
ParameterTypeInRequiredDescription
 
pathstringbodyNoDirectory prefix to place files under 
filesfile[]bodyYesOne or more files (multipart form field name: 'files') 
Status Codes
CodeDescription
 
200Files uploaded
400No files provided
401Unauthorized
413File too large (max 50MB)
507Storage quota exceeded
Response Body
{
  "uploaded": [
    {
      "path": "docs/report.pdf",
      "size": 102400
    }
  ]
}
POST /api/v1/files/upload
 
 
 
cURL 
Response 
DELETE /api/v1/files 
Delete file
Deletes a single file from the tenant file store.
Parameters
ParameterTypeInRequiredDescription
 
pathstringqueryYesRelative path of the file to delete 
Status Codes
CodeDescription
 
204File deleted
400Missing path parameter
401Unauthorized
DELETE /api/v1/files
 
 
cURL 
Response 
POST /api/v1/files/move 
Move or rename file
Moves or renames a file within the tenant file store.
Parameters
ParameterTypeInRequiredDescription
 
src_pathstringbodyYesCurrent path of the file 
dst_pathstringbodyYesNew path for the file 
Status Codes
CodeDescription
 
200File moved
400Validation error
401Unauthorized
Response Body
{
  "success": true
}
POST /api/v1/files/move
 
 
 
cURL 
Response 
POST /api/v1/files/mkdir 
Create directory
Creates a new directory in the tenant file store.
Parameters
ParameterTypeInRequiredDescription
 
pathstringbodyYesPath of the directory to create 
Status Codes
CodeDescription
 
200Directory created
400Validation error
401Unauthorized
Response Body
{
  "success": true
}
POST /api/v1/files/mkdir
 
 
cURL 
Response