Files API Reference

Complete file and document management operations including upload, download, copy, move, search, sharing, and synchronization.

Overview

The Files API provides comprehensive file management capabilities built on top of S3-compatible storage. All file operations support both single files and folders with recursive operations.

Base Path: /files

Authentication

All endpoints require authentication. Include session token in headers:

Authorization: Bearer <token>

File Operations

List Files

List files and folders in a bucket or path.

Endpoint: GET /files/list

Query Parameters:

bucket (optional) - Bucket name
path (optional) - Folder path

Response:

{
  "success": true,
  "data": [
    {
      "name": "document.pdf",
      "path": "/documents/document.pdf",
      "is_dir": false,
      "size": 1048576,
      "modified": "2024-01-15T10:30:00Z",
      "icon": "📄"
    },
    {
      "name": "images",
      "path": "/images",
      "is_dir": true,
      "size": null,
      "modified": "2024-01-15T09:00:00Z",
      "icon": "📁"
    }
  ]
}

Example:

curl -X GET "http://localhost:3000/files/list?bucket=my-bucket&path=/documents" \
  -H "Authorization: Bearer <token>"

Read File

Read file content from storage.

Endpoint: POST /files/read

Request Body:

{
  "bucket": "my-bucket",
  "path": "/documents/file.txt"
}

Response:

{
  "content": "File content here..."
}

Example:

curl -X POST "http://localhost:3000/files/read" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"bucket":"my-bucket","path":"/file.txt"}'

Get File Contents

Alias for read file with alternative naming.

Endpoint: POST /files/getContents

Same parameters and response as /files/read.

Write File

Write or update file content.

Endpoint: POST /files/write

Request Body:

{
  "bucket": "my-bucket",
  "path": "/documents/file.txt",
  "content": "New file content"
}

Response:

{
  "success": true,
  "message": "File written successfully"
}

Save File

Alias for write file.

Endpoint: POST /files/save

Same parameters and response as /files/write.

Upload File

Upload file to storage.

Endpoint: POST /files/upload

Request Body:

{
  "bucket": "my-bucket",
  "path": "/documents/upload.pdf",
  "content": "base64_encoded_content_or_text"
}

Response:

{
  "success": true,
  "message": "File uploaded successfully"
}

Download File

Download file from storage.

Endpoint: POST /files/download

Request Body:

{
  "bucket": "my-bucket",
  "path": "/documents/file.pdf"
}

Response:

{
  "content": "file_content"
}

Copy File

Copy file or folder to another location.

Endpoint: POST /files/copy

Request Body:

{
  "source_bucket": "my-bucket",
  "source_path": "/documents/original.pdf",
  "dest_bucket": "my-bucket",
  "dest_path": "/backup/copy.pdf"
}

Response:

{
  "success": true,
  "message": "File copied successfully"
}

Move File

Move file or folder to another location.

Endpoint: POST /files/move

Request Body:

{
  "source_bucket": "my-bucket",
  "source_path": "/documents/file.pdf",
  "dest_bucket": "archive-bucket",
  "dest_path": "/archived/file.pdf"
}

Response:

{
  "success": true,
  "message": "File moved successfully"
}

Note: Move operation copies the file and then deletes the source.

Delete File

Delete file or folder.

Endpoint: POST /files/delete

Request Body:

{
  "bucket": "my-bucket",
  "path": "/documents/file.pdf"
}

Response:

{
  "success": true,
  "message": "Deleted successfully"
}

Note: If path ends with /, all objects with that prefix are deleted (recursive folder deletion).

Create Folder

Create a new folder.

Endpoint: POST /files/createFolder

Request Body:

{
  "bucket": "my-bucket",
  "path": "/documents",
  "name": "new-folder"
}

Response:

{
  "success": true,
  "message": "Folder created successfully"
}

Alternative Endpoint: POST /files/create-folder (dash notation)

List Folder Contents

List contents of a specific folder.

Endpoint: POST /files/dirFolder

Request Body:

{
  "bucket": "my-bucket",
  "path": "/documents"
}

Response:

[
  {
    "name": "file1.pdf",
    "path": "/documents/file1.pdf",
    "is_dir": false,
    "size": 1024,
    "modified": "2024-01-15T10:30:00Z",
    "icon": "📄"
  }
]

Search and Discovery

Search Files

Search for files across buckets.

Endpoint: GET /files/search

Query Parameters:

bucket (optional) - Limit search to specific bucket
query (required) - Search term
file_type (optional) - File extension filter (e.g., “.pdf”)

Response:

[
  {
    "name": "matching-file.pdf",
    "path": "/documents/matching-file.pdf",
    "is_dir": false,
    "size": 2048576,
    "modified": "2024-01-15T10:30:00Z",
    "icon": "📄"
  }
]

Example:

curl -X GET "http://localhost:3000/files/search?query=report&file_type=.pdf" \
  -H "Authorization: Bearer <token>"

Recent Files

Get recently modified files.

Endpoint: GET /files/recent

Query Parameters:

bucket (optional) - Filter by bucket

Response:

[
  {
    "name": "recent-file.txt",
    "path": "/documents/recent-file.txt",
    "is_dir": false,
    "size": 1024,
    "modified": "2024-01-15T14:30:00Z",
    "icon": "📃"
  }
]

Note: Returns up to 50 most recently modified files, sorted by modification date descending.

Favorite Files

List user’s favorite files.

Endpoint: GET /files/favorite

Response:

[]

Note: Currently returns empty array. Favorite functionality to be implemented.

Share folder with other users.

Endpoint: POST /files/shareFolder

Request Body:

{
  "bucket": "my-bucket",
  "path": "/documents/shared",
  "users": ["user1@example.com", "user2@example.com"],
  "permissions": "read-write"
}

Response:

{
  "share_id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://share.example.com/550e8400-e29b-41d4-a716-446655440000",
  "expires_at": "2024-01-22T10:30:00Z"
}

List Shared Files

Get files and folders shared with user.

Endpoint: GET /files/shared

Response:

[]

Get Permissions

Get permissions for file or folder.

Endpoint: GET /files/permissions

Query Parameters:

bucket (required) - Bucket name
path (required) - File/folder path

Response:

{
  "bucket": "my-bucket",
  "path": "/documents/file.pdf",
  "permissions": {
    "read": true,
    "write": true,
    "delete": true,
    "share": true
  },
  "shared_with": []
}

Storage Management

Get Quota

Check storage quota information.

Endpoint: GET /files/quota

Response:

{
  "total_bytes": 100000000000,
  "used_bytes": 45678901234,
  "available_bytes": 54321098766,
  "percentage_used": 45.68
}

Example:

curl -X GET "http://localhost:3000/files/quota" \
  -H "Authorization: Bearer <token>"

Synchronization

Sync Status

Get current synchronization status.

Endpoint: GET /files/sync/status

Response:

{
  "status": "idle",
  "last_sync": "2024-01-15T10:30:00Z",
  "files_synced": 0,
  "bytes_synced": 0
}

Status values:

idle - No sync in progress
syncing - Sync in progress
error - Sync error occurred
paused - Sync paused

Start Sync

Start file synchronization.

Endpoint: POST /files/sync/start

Response:

{
  "success": true,
  "message": "Sync started"
}

Stop Sync

Stop file synchronization.

Endpoint: POST /files/sync/stop

Response:

{
  "success": true,
  "message": "Sync stopped"
}

File Icons

Files are automatically assigned icons based on extension:

Extension	Icon	Type
.bas	⚙️	BASIC script
.ast	🔧	AST file
.csv	📊	Spreadsheet
.gbkb	📚	Knowledge base
.json	🔖	JSON data
.txt, .md	📃	Text
.pdf	📕	PDF document
.zip, .tar, .gz	📦	Archive
.jpg, .png, .gif	🖼️	Image
folder	📁	Directory
.gbai	🤖	Bot package
default	📄	Generic file

Error Handling

Common error responses:

Service Unavailable:

{
  "error": "S3 service not available"
}

Status: 503

File Not Found:

{
  "error": "Failed to read file: NoSuchKey"
}

Status: 500

Invalid UTF-8:

{
  "error": "File is not valid UTF-8"
}

Status: 500

Best Practices

Large Files: For files > 5MB, consider chunked uploads
Batch Operations: Use batch endpoints when operating on multiple files
Path Naming: Use forward slashes, avoid special characters
Permissions: Always check permissions before operations
Error Handling: Implement retry logic for transient failures
Quotas: Monitor quota usage to prevent storage exhaustion

Examples

// 1. Upload file
const uploadResponse = await fetch('/files/upload', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    bucket: 'my-bucket',
    path: '/documents/report.pdf',
    content: fileContent
  })
});

// 2. Share with team
const shareResponse = await fetch('/files/shareFolder', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    bucket: 'my-bucket',
    path: '/documents',
    users: ['team@example.com'],
    permissions: 'read-write'
  })
});

const { url } = await shareResponse.json();
console.log('Share URL:', url);

Search and Download

import requests

# Search for files
response = requests.get(
    'http://localhost:3000/files/search',
    params={'query': 'report', 'file_type': '.pdf'},
    headers={'Authorization': 'Bearer token'}
)

files = response.json()

# Download first result
if files:
    download_response = requests.post(
        'http://localhost:3000/files/download',
        json={
            'bucket': 'my-bucket',
            'path': files[0]['path']
        },
        headers={'Authorization': 'Bearer token'}
    )
    
    content = download_response.json()['content']
    with open('downloaded.pdf', 'w') as f:
        f.write(content)

Next Steps

Document Processing API - Convert and merge documents
Storage API - Advanced storage operations
Backup API - Backup and restore

Keyboard shortcuts

General Bots Documentation