Skip to main content

​
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, pre-signed URL to download a specific file. GET /api/files/download?fileId={fileId} Response (200) 
{
  "success": true,
  "data": {
    "downloadUrl": "https://s3.amazonaws.com/...&Expires=..."
  }
}