File Manager API

Overview

The File Manager API enables file operations within protocols.io workspaces, including uploading files, organizing folders, searching content, and managing file lifecycle. This is useful for attaching data files, images, documents, and other resources to protocols.

Base URL

All file manager endpoints use the base URL: https://protocols.io/api/v3

Search and Browse

Search Workspace Files

Search for files and folders within a workspace.

Endpoint: GET /workspaces/{workspace_id}/files/search

Path Parameters: - workspace_id: The workspace's unique identifier

Query Parameters: - query: Search keywords (searches filenames and metadata) - type: Filter by type - file: Files only - folder: Folders only - all: Both files and folders (default) - folder_id: Limit search to specific folder - page_size: Number of results per page (default: 20, max: 100) - page_id: Page number for pagination (starts at 0)

Response includes: - File/folder ID and name - File size and type - Creation and modification dates - File path in workspace - Download URL (for files)

Example Request:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://protocols.io/api/v3/workspaces/12345/files/search?query=microscopy&type=file"

List Folder Contents

Browse files and folders within a specific folder.

Endpoint: GET /workspaces/{workspace_id}/folders/{folder_id}

Path Parameters: - workspace_id: The workspace's unique identifier - folder_id: The folder's unique identifier (use root for workspace root)

Query Parameters: - order_by: Sort field (name, size, created, modified) - order_dir: Sort direction (asc, desc) - page_size: Number of results per page - page_id: Page number for pagination

Example Request:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://protocols.io/api/v3/workspaces/12345/folders/root?order_by=modified&order_dir=desc"

File Upload

Upload File

Upload a file to a workspace folder.

Endpoint: POST /workspaces/{workspace_id}/files/upload

Request Format: multipart/form-data

Form Parameters: - file (required): The file to upload - folder_id: Target folder ID (omit or use root for workspace root) - name: Custom filename (optional, uses original filename if omitted) - description: File description - tags: Comma-separated tags

Example Request:

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@/path/to/local/data.xlsx" \
  -F "folder_id=67890" \
  -F "description=Experimental results from trial #3" \
  -F "tags=experiment,data,2025" \
  "https://protocols.io/api/v3/workspaces/12345/files/upload"

Upload Verification

After upload, verify the file was processed correctly.

Endpoint: GET /workspaces/{workspace_id}/files/{file_id}/status

Response includes: - Upload status (processing, complete, failed) - File metadata - Any processing errors

File Operations

Download File

Download a file from the workspace.

Endpoint: GET /workspaces/{workspace_id}/files/{file_id}/download

Path Parameters: - workspace_id: The workspace's unique identifier - file_id: The file's unique identifier

Response: Binary file data with appropriate Content-Type header

Example Request:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  -o "downloaded_file.xlsx" \
  "https://protocols.io/api/v3/workspaces/12345/files/67890/download"

Get File Metadata

Retrieve file information without downloading.

Endpoint: GET /workspaces/{workspace_id}/files/{file_id}

Response includes: - File name, size, and type - Upload date and author - Description and tags - File path and location - Download URL - Sharing permissions

Update File Metadata

Update file description, tags, or other metadata.

Endpoint: PATCH /workspaces/{workspace_id}/files/{file_id}

Request Body: - name: New filename - description: Updated description - tags: Updated tags (comma-separated) - folder_id: Move to different folder

Example Request:

curl -X PATCH \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Experimental results from trial #3 - REVISED",
    "tags": "experiment,data,2025,revised"
  }' \
  "https://protocols.io/api/v3/workspaces/12345/files/67890"

Delete File

Move a file to trash (soft delete).

Endpoint: DELETE /workspaces/{workspace_id}/files/{file_id}

Note: Deleted files may be recoverable from trash for a limited time

Restore File

Restore a deleted file from trash.

Endpoint: POST /workspaces/{workspace_id}/files/{file_id}/restore

Folder Operations

Create Folder

Create a new folder in the workspace.

Endpoint: POST /workspaces/{workspace_id}/folders

Request Body: - name (required): Folder name - parent_folder_id: Parent folder ID (omit for workspace root) - description: Folder description

Example Request:

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "2025 Experiments",
    "parent_folder_id": "root",
    "description": "All experimental data from 2025"
  }' \
  "https://protocols.io/api/v3/workspaces/12345/folders"

Rename Folder

Endpoint: PATCH /workspaces/{workspace_id}/folders/{folder_id}

Request Body: - name: New folder name - description: Updated description

Delete Folder

Delete a folder and optionally its contents.

Endpoint: DELETE /workspaces/{workspace_id}/folders/{folder_id}

Query Parameters: - recursive: Set to true to delete folder and all contents (default: false)

Warning: Recursive deletion cannot be easily undone

Common Use Cases

1. Protocol Data Attachment

Attach experimental data files to protocols:

Upload data files: POST /workspaces/{id}/files/upload
Verify upload completion
Reference file IDs in protocol steps
Include download links in protocol description

Example Workflow:

# Upload the data file
curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@results.csv" \
  -F "description=Results from protocol execution" \
  "https://protocols.io/api/v3/workspaces/12345/files/upload"

# Note the file_id from response, then reference in protocol

2. Workspace Organization

Organize files into logical folder structures:

Create folder hierarchy: POST /workspaces/{id}/folders
Upload files to appropriate folders
Use consistent naming conventions
Tag files for easy search

Example Structure:

Workspace Root
├── Protocols
│   ├── Published
│   └── Drafts
├── Data
│   ├── Raw
│   └── Processed
├── Images
│   ├── Microscopy
│   └── Gels
└── Documents
    ├── Papers
    └── Presentations

3. File Search and Discovery

Find files across workspace:

Search by keywords: GET /workspaces/{id}/files/search?query=keywords
Filter by type and date
Download relevant files
Update metadata for better organization

4. Batch File Upload

Upload multiple related files:

Create target folder
For each file:
Upload file
Verify upload status
Add consistent tags
Create index or manifest file listing all uploads

5. Data Backup and Export

Export workspace files for backup:

List all folders: GET /workspaces/{id}/folders/root
For each folder, list files
Download all files: GET /workspaces/{id}/files/{file_id}/download
Maintain folder structure locally
Store metadata separately for restoration

6. File Versioning

Manage file versions manually:

Upload new version with versioned name (e.g., data_v2.csv)
Update previous version metadata to indicate superseded
Maintain version history in folder structure
Reference specific versions in protocols

Supported File Types

Protocols.io supports various file types:

Data Files: - Spreadsheets: .xlsx, .xls, .csv, .tsv - Statistical data: .rds, .rdata, .sav, .dta - Plain text: .txt, .log, .json, .xml

Images: - Common formats: .jpg, .jpeg, .png, .gif, .bmp, .tif, .tiff - Scientific: .czi, .nd2, .lsm (may require special handling)

Documents: - PDF: .pdf - Word: .docx, .doc - PowerPoint: .pptx, .ppt

Code and Scripts: - Python: .py, .ipynb - R: .r, .rmd - Shell: .sh, .bash

Multimedia: - Video: .mp4, .avi, .mov - Audio: .mp3, .wav

Archives: - Compressed: .zip, .tar.gz, .7z

File Size Limits: - Standard files: Check workspace limits (typically 100 MB - 1 GB) - Large files: May require chunked upload or special handling

Best Practices

File Naming
Use descriptive, consistent naming conventions
Include dates in ISO format (YYYY-MM-DD)
Avoid special characters and spaces (use underscores)
Example: experiment_results_2025-10-26.csv
Organization
Create logical folder hierarchy
Group related files together
Separate raw data from processed results
Keep protocol-specific files in dedicated folders
Metadata
Add detailed descriptions
Tag files consistently
Include version information
Document processing steps
Storage Management
Regularly review and archive old files
Delete unnecessary duplicates
Compress large datasets
Monitor workspace storage limits
Collaboration
Use clear file names for team members
Document file purposes in descriptions
Maintain consistent folder structures
Communicate major organizational changes
Security
Avoid uploading sensitive data without proper permissions
Be aware of workspace visibility settings
Use appropriate access controls
Regularly audit file access

Error Handling

Common error responses:

400 Bad Request: Invalid file format or parameters
401 Unauthorized: Missing or invalid access token
403 Forbidden: Insufficient workspace permissions
404 Not Found: File or folder not found
413 Payload Too Large: File exceeds size limit
422 Unprocessable Entity: File validation failed
429 Too Many Requests: Rate limit exceeded
507 Insufficient Storage: Workspace storage limit reached

Performance Considerations

Large Files
Consider chunked upload for files > 100 MB
Use compression for large datasets
Upload during off-peak hours if possible
Batch Operations
Implement retry logic for failed uploads
Use exponential backoff for rate limits
Process uploads in parallel where possible
Download Optimization
Cache frequently accessed files locally
Use streaming for large file downloads
Implement resume capability for interrupted downloads

references/file_manager.md

File Manager API

Overview

Base URL

Search and Browse

Search Workspace Files

List Folder Contents

File Upload

Upload File

Upload Verification

File Operations

Download File

Get File Metadata

Update File Metadata

Delete File

Restore File

Folder Operations

Create Folder

Rename Folder

Delete Folder

Common Use Cases

1. Protocol Data Attachment

2. Workspace Organization

3. File Search and Discovery

4. Batch File Upload

5. Data Backup and Export

6. File Versioning

Supported File Types

Best Practices

Error Handling

Performance Considerations