Filestorage Guide - Pinkfish - AI Agents & Workflows for Getting Work Done

How to use it?

Basic Command Structure

/selected-filestore [action] [filename] [content]

Parameters

Required:

action - Operation to perform (upload, create, append, get, list, delete, update)
filename - Name of the file (required for most operations)

Optional:

content - File content for upload/create/append operations
metadata - Additional information about the file
file_links_expire_in_days - Link expiry: 1-7 days or “never” for public files
file_links_expire_in_minutes - Minute-level precision for link expiry
get_file_contents - Set to true to retrieve file content along with metadata
format - Set to “light” for minimal file listing
replaceExisting - Whether to replace existing files with same filename (defaults to “true”; if “false”, adds timestamp to filename)
triggerUrls - Array of trigger objects that fire when the file changes (see Triggers section)

File Link Expiration

Days: 1-7 days or “never” to make file public
Minutes: Can be used for minute-level precision
Combined: Use both (e.g., days=“1”, minutes=“30” = 1 day 30 minutes)
Default: 1 day if not specified
Maximum: 7 days total
Public files: Use days=“never” (minutes ignored)

Response Format

File creation/update:

{
  "message": "File created successfully",
  "file_url": "URL HERE"
}

File metadata (full details):

{
  "filename": "test999.json",
  "filepath": "file-storage/path/test999.json",
  "type": "application/json",
  "createdAt": "2024-11-17T18:04:22.197Z",
  "updatedAt": "2024-11-17T18:09:46.455Z",
  "metadata": "file metadata",
  "isPublic": true,
  "signedUrl": "https://...",
  "accessList": [
    {
      "action": "create",
      "providerId": "user-id",
      "date": "2024-11-17T18:04:22.197Z"
    }
  ]
}

File listing (light format):

{
  "id": "XmWSUYJ3P3FJTmSz0gyz",
  "filename": "sample-chunk-1-pages-1-1-2025-07-08-21-19-44.pdf",
  "filepath": "file-storage/GL7O7FAfCY3RvWgv4E56/sample-chunk-1-pages-1-1-2025-07-08-21-19-44.pdf",
  "type": "application/pdf",
  "mime_type": "application/pdf",
  "file_size": 101655,
  "isPublic": false,
  "collectionId": "GL7O7FAfCY3RvWgv4E56",
  "createdAt": "2025-07-08T21:19:45.824Z",
  "updatedAt": "2025-07-08T21:19:45.824Z",
  "metadata": {
    "project": "onboarding",
    "originalFilename": "sample.pdf",
    "batchId": "batch_2025-07-08_21-19-44"
  }
}

Tools

Upload File

Upload a file from buffer or file input Parameters:

action (required) - Set to “upload”
file (required) - File or buffer to upload
metadata (optional) - File metadata
file_links_expire_in_days (optional) - Link expiry (1-7 days or “never”)
file_links_expire_in_minutes (optional) - Minute-level precision
replaceExisting (optional) - Whether to replace existing files with same filename (defaults to “true”)
triggerUrls (optional) - Array of trigger objects (see Triggers section)

Example:

/selected-filestore upload file with:
file: [file buffer or file input]
metadata: "Document uploaded from automation"
file_links_expire_in_days: "7"
replaceExisting: "false"

Create or Replace Document

Create a new file or replace existing one with text content Parameters:

action (required) - Set to “create”
filename (required) - Name of the file
content (required) - File content
metadata (optional) - File metadata
file_links_expire_in_days (optional) - Link expiry (1-7 days or “never”)
file_links_expire_in_minutes (optional) - Minute-level precision
replaceExisting (optional) - Whether to replace existing files with same filename (defaults to “true”)

Example:

/selected-filestore create a new file with:
filename: config.json
content: {"api_endpoint": "https://api.example.com", "timeout": 30}
metadata: "Production configuration file"
file_links_expire_in_days: "never"
replaceExisting: "true"

Append to Document

Append content to an existing file Parameters:

action (required) - Set to “append”
filename (required) - Name of the file
content (required) - Content to append
metadata (optional) - Updated metadata
file_links_expire_in_days (optional) - Link expiry (1-7 days or “never”)
file_links_expire_in_minutes (optional) - Minute-level precision

Example:

/selected-filestore append to file:
filename: system-logs.txt
content: "New log entry at 2024-03-15T15:30:00Z"
metadata: "Updated log file"
file_links_expire_in_days: "1"

Get Document

Retrieve file metadata or content Parameters:

action (required) - Set to “get”
filename (required) - Name of the file
get_file_contents (optional) - Set to true to retrieve content
file_links_expire_in_days (optional) - Link expiry for returned signedUrl

Examples: Get metadata only:

/selected-filestore get file metadata:
filename: quarterly-report.txt

Get metadata and content:

/selected-filestore get file with content:
filename: quarterly-report.txt
get_file_contents: true

Get with custom link expiry:

/selected-filestore get file:
filename: quarterly-report.txt
file_links_expire_in_days: "7"

List Files

List all files with full or light details Parameters:

action (required) - Set to “list”
format (optional) - Set to “light” for minimal info
file_links_expire_in_days (optional) - Link expiry for returned signedUrls

Response includes:

Full details: All metadata, signedUrl, and accessList
Light format: File ID, filename, filepath, type, mime_type, file_size, isPublic status, collectionId, timestamps, and metadata object

Examples: List with full details:

/selected-filestore list files with:
file_links_expire_in_days: "7"

List with minimal info:

/selected-filestore list files:
format: light

Delete Document

Delete a file from storage Parameters:

action (required) - Set to “delete”
filename (required) - Name of the file

Example:

/selected-filestore delete file:
filename: old-report.txt

Update File Link Expiry

Update link expiration settings for existing files Parameters:

action (required) - Set to “update”
filename (required) - Name of the file
file_links_expire_in_days (required) - New link expiry (1-7 days or “never”)
file_links_expire_in_minutes (optional) - Minute-level precision
metadata (optional) - Updated metadata

Examples: Make file public:

/selected-filestore update file expiry:
filename: public-document.pdf
file_links_expire_in_days: "never"

Set custom expiry:

/selected-filestore update file expiry:
filename: temp-file.txt
file_links_expire_in_days: "2"
file_links_expire_in_minutes: "30"

What can you do with it?

Store, retrieve, update, and manage files in the cloud storage system. Supports text and binary files with metadata, link expiration control, and public file sharing options. Perfect for configuration management, system logging, document storage, and file sharing with controlled access periods.

File Types and Content Extraction

Supported File Types

Document files: PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT Image files: PNG, JPG, JPEG, WEBP Audio files: MP3, WAV Video files: MP4, MOV Data files: CSV, JSON, HTML Archive files: ZIP

Content Extraction

For supported document types (PDF, DOCX, XLSX, PPTX, CSV), the system automatically extracts content when retrieving files. This works for:

PDF files
Word documents (DOC, DOCX)
Excel files (XLS, XLSX)
PowerPoint files (PPT, PPTX)
CSV files

File Type Handling

Text files (JSON, TXT, HTML, CSV):

Use get_file_contents: true to retrieve content directly
Can be updated with POST method

Binary files (PNG, JPG, PDF, MP3, etc.):

Use signedUrl from metadata to access file content
Use PATCH method to update metadata and link expiry without resending content

Examples

Configuration Management

/selected-filestore create a new file with:
filename: app-config.json
content: {"api_endpoint": "https://api.example.com", "timeout": 30, "retry_attempts": 3}
metadata: "Production environment configuration v2.1"
file_links_expire_in_days: "7"
replaceExisting: "true"

System Logging

/selected-filestore create a new file with:
filename: system-logs-2024-03.txt
content: "Initial log entry"
metadata: "System logs for March 2024"
file_links_expire_in_days: "never"

Document Storage

/selected-filestore create a new file with:
filename: quarterly-report-q1-2024.txt
content: "Q1 2024 Financial Report Content"
metadata: "Finance department quarterly report - draft status"
file_links_expire_in_days: "3"
replaceExisting: "false"

Log File Management

/selected-filestore append to file:
filename: system-logs-2024-03.txt
content: "ERROR: Database connection failed at 2024-03-15T15:30:00Z"
metadata: "Log updated with error entry"
file_links_expire_in_days: "1"

Making Files Public

/selected-filestore update file expiry:
filename: public-document.pdf
file_links_expire_in_days: "never"
metadata: "Document made public for external sharing"

Triggers

Filestorage supports event-driven triggers that automatically start workflows when files change. Triggers can be set at two levels: collection-wide (affects all files) or file-specific (affects individual files).

Trigger Events

onCreate: Fires when new files are uploaded or created (collection-level only)
onEdit: Fires when existing files are modified or updated (collection or file level)
onDelete: Fires when files are deleted (collection or file level)

Trigger Levels

Collection-Level Triggers: Set on the entire file collection to monitor all files

Automatically fire for every file in the collection
Perfect for system-wide file processing and monitoring
Set via file collection management interface

File-Level Triggers: Set on individual files to monitor specific files

Only fire for that particular file
Ideal for monitoring important documents or configuration files
Set via the triggerUrls parameter when uploading/creating/updating files

Trigger Structure

Triggers use an array format with multiple trigger objects:

triggerUrls: [
  {
    "event": "onEdit",
    "url": "https://triggers.app.pinkfish.ai/ext/triggers/d2nia2isg8tc7112frtg",
    "apiKey": "your-api-key"
  },
  {
    "event": "onDelete",
    "url": "https://triggers.app.pinkfish.ai/ext/triggers/a3bcd4efg9ud8223hsui",
    "apiKey": "your-api-key-2"
  }
]

Trigger Payload

When triggers fire, they receive detailed information about the file event: For onCreate and onDelete events:

{
  "event": "onCreate",
  "itemId": "file-abc123",
  "providerId": "user-id",
  "collectionId": "collection-id",
  "collectionType": "filestorage",
  "filename": "config.json",
  "filepath": "file-storage/collection-id/config.json",
  "fileSize": 1024,
  "mimeType": "application/json",
  "signedUrl": "https://storage.googleapis.com/signed-url",
  "metadata": { "version": "1.0", "environment": "production" },
  "isPublic": false,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "triggerLevel": "file"
}

For onEdit events (same structure as above):

File modifications (content updates, metadata changes, public status changes)
The signedUrl provides access to the updated file content
updatedAt timestamp reflects when the change occurred

Examples

Upload File with Multiple Triggers

/selected-filestore upload file with:
file: [your file buffer]
metadata: {"type": "configuration", "environment": "production"}
file_links_expire_in_days: "7"
triggerUrls: [
  {
    "event": "onEdit",
    "url": "https://triggers.app.pinkfish.ai/ext/triggers/config-monitor",
    "apiKey": "your-api-key"
  },
  {
    "event": "onDelete",
    "url": "https://triggers.app.pinkfish.ai/ext/triggers/config-deleted",
    "apiKey": "your-api-key-2"
  }
]

Create File with Trigger

/selected-filestore create a new file with:
filename: system-config.json
content: {"database_url": "postgresql://...", "api_key": "secret"}
metadata: {"type": "system_config", "critical": true}
file_links_expire_in_days: "never"
triggerUrls: [
  {
    "event": "onEdit",
    "url": "https://triggers.app.pinkfish.ai/ext/triggers/system-config-changed",
    "apiKey": "your-api-key"
  }
]

Update File (Will Fire onEdit Triggers)

/selected-filestore update file expiry:
filename: system-config.json
file_links_expire_in_days: "1"
metadata: {"type": "system_config", "critical": true, "last_reviewed": "2024-01-15"}

File Processing Pipeline

/selected-filestore upload file with:
file: [document buffer]
metadata: {"stage": "raw", "needs_processing": true}
triggerUrls: [
  {
    "event": "onCreate",
    "url": "https://triggers.app.pinkfish.ai/ext/triggers/document-processor",
    "apiKey": "your-api-key"
  }
]

Rate Limiting and Logs

Rate Limiting: onEdit triggers are limited to 2 executions per minute per file to prevent infinite loops
Trigger Logs: All trigger executions are logged with status, execution time, and error details
Error Handling: Failed triggers are logged but don’t prevent the original file operation from completing
File Access: Triggers receive signed URLs that are valid for 7 days to access file content

Best Practices

Use Collection-Level Triggers for automated file processing pipelines (e.g., document conversion, backup systems)
Use File-Level Triggers for monitoring critical files (e.g., configuration files, important documents)
Monitor file access through signed URLs provided in trigger payloads
Test triggers thoroughly before production use to ensure reliable file processing
Handle file types appropriately - use signed URLs for binary files, content extraction for text files
Consider file size limits when processing large files in triggered workflows

Notes

Each file must have a unique filename within your storage
Files can include optional metadata for organization and tracking
Default link expiry is 1 day if not specified
Maximum expiry is 7 days (except for public files)
Use file_links_expire_in_days: "never" to make files public
Access history is automatically tracked for all files
Content extraction is available for common document formats
For binary files, use the signedUrl to access content
Race conditions: There is no race condition prevention in place. If you have multiple automations writing to the same file, you will experience unexpected results
File overwriting: By default, creating a file with an existing filename will overwrite the existing file completely. Use replaceExisting: "false" to add a timestamp to the filename instead
Signed URLs: Files are accessible via signed URLs that expire based on the file_links_expire_in_days setting. Access history is maintained in the accessList with entries including action performed, provider ID, and timestamp

Get Started

Organization

Agents

Workflows

Resources

Integrations

Orchestration

Credits & Pricing

Skills

How To Guides

Release Notes

Support

​How to use it?

​Basic Command Structure

​Parameters

​File Link Expiration

​Response Format

​Tools

​Upload File

​Create or Replace Document

​Append to Document

​Get Document

​List Files

​Delete Document

​Update File Link Expiry

​What can you do with it?

​File Types and Content Extraction

​Supported File Types

​Content Extraction

​File Type Handling

​Examples

​Configuration Management

​System Logging

​Document Storage

​Log File Management

​Making Files Public

​Triggers

​Trigger Events

​Trigger Levels

​Trigger Structure

​Trigger Payload

​Examples

​Upload File with Multiple Triggers

​Create File with Trigger

​Update File (Will Fire onEdit Triggers)

​File Processing Pipeline

​Rate Limiting and Logs

​Best Practices

​Notes

How to use it?

Basic Command Structure

Parameters

File Link Expiration

Response Format

Tools

Upload File

Create or Replace Document

Append to Document

Get Document

List Files

Delete Document

Update File Link Expiry

What can you do with it?

File Types and Content Extraction

Supported File Types

Content Extraction

File Type Handling

Examples

Configuration Management

System Logging

Document Storage

Log File Management

Making Files Public

Triggers

Trigger Events

Trigger Levels

Trigger Structure

Trigger Payload

Examples

Upload File with Multiple Triggers

Create File with Trigger

Update File (Will Fire onEdit Triggers)

File Processing Pipeline

Rate Limiting and Logs

Best Practices

Notes