​
Files

The Files API allows you to upload, download, and manage files within the secure virtual machines (sandboxes) of your deployments. This is essential for providing your AI agents with input data or retrieving the results of their work.

​
List files

Retrieve a list of all files currently tracked for a specific deployment. GET /api/files?deploymentId={deploymentId} Response (200) 
{
  "success": true,
  "data": {
    "files": [
      {
        "_id": "file_xxx",
        "deploymentId": "dep_xxx",
        "userId": "user_xxx",
        "fileName": "results.csv",
        "fileSize": 1024,
        "mimeType": "text/csv",
        "storagePath": "deployments/dep_xxx/results.csv",
        "status": "ready",
        "createdAt": "2023-10-27T10:00:00Z",
        "updatedAt": "2023-10-27T10:00:00Z"
      }
    ]
  }
}

​
Uploading Files (Two-Step Process)

To upload a file, you first request a pre-signed S3 URL, upload the file directly to S3, and then record the successful upload in the database.

​
1. Request Pre-signed URL

POST /api/files/presign Body 
{
  "deploymentId": "dep_xxx",
  "fileName": "data.csv",
  "fileSize": 2048,
  "mimeType": "text/csv"
}
Response (200) 
{
  "success": true,
  "data": {
    "uploadUrl": "https://s3.amazonaws.com/...", // URL to PUT your file to
    "storagePath": "deployments/dep_xxx/data.csv"
  }
}
After receiving this response, perform an HTTP PUT request to the uploadUrl with your file’s binary data.

​
2. Record Upload Completion

Once the S3 upload succeeds, notify the API so the file becomes available to the sandbox. POST /api/files/record Body 
{
  "deploymentId": "dep_xxx",
  "fileName": "data.csv",
  "fileSize": 2048,
  "mimeType": "text/csv",
  "storagePath": "deployments/dep_xxx/data.csv"
}
Response (200) 
{
  "success": true,
  "data": {
    "file": {
      "id": "file_xxx",
      "status": "ready",
      // ...
    }
  }
}

​
Download a file

Get a short-lived presigned URL to download a specific file. GET /api/files/download?fileId={fileId} Response (200) 
{
  "success": true,
  "data": {
    "downloadUrl": "https://s3.amazonaws.com/...&Expires=..."
  }
}

​
Sync files into a sandbox

Copies files from S3 into the live sandbox’s Desktop directory. Use this to load input data before the agent starts working. POST /api/deployments/{id}/files/sync Body 
{
  "files": ["deployments/dep_xxx/data.csv", "deployments/dep_xxx/config.json"]
}
Response (200) 
{
  "success": true,
  "message": "Files synced to sandbox Desktop"
}
The sandbox must be in running state before calling sync. Files are placed at /home/user/Desktop/ inside the sandbox.

​
Pull files from a sandbox

Extracts files from the sandbox Desktop back to S3, making them available for download. POST /api/deployments/{id}/files/pull Body 
{
  "files": ["result.csv", "report.pdf"]
}
Response (200) 
{
  "success": true,
  "data": {
    "pulledFiles": [
      {
        "fileName": "result.csv",
        "storagePath": "deployments/dep_xxx/result.csv",
        "fileSize": 4096
      }
    ]
  }
}
After pulling, the files are registered in the deployment’s file manifest and downloadable via GET /api/files/download.