Skip to main content

​
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)
  • 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 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"

​
Event Triggers

Automatically start workflows when files change in your filestorage collection. Triggers can be set at collection-level (all files) or file-level (specific files). Supported events:
  • onCreate - New files uploaded (collection-level only)
  • onEdit - Files modified or updated (collection or file-level)
  • onDelete - Files removed (collection or file-level)
For complete documentation on setting up triggers, payload formats, rate limiting, and best practices, see the Event Triggers guide. Quick example: 
{
  "file": [file buffer],
  "metadata": {"type": "configuration"},
  "triggerUrls": [
    {
      "event": "onEdit",
      "url": "https://triggers.app.pinkfish.ai/ext/triggers/abc123",
      "apiKey": "your-api-key"
    }
  ]
}
File-specific trigger payload includes:
  • Signed URL for file access (valid 7 days)
  • File metadata (filename, size, mime type)
  • Collection and event information

​
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