Filestorage Guide

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)
query_params - JSON-encoded key-value pairs to include as query parameters in the signed URL (see Query Parameters in Signed URLs)
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)

Query Parameters in Signed URLs

You can include custom query parameters in signed URLs so that HTML files can read contextual data at load time. This is useful when serving HTML dashboards or web apps from file storage that need to know which data to fetch. Parameter: query_params — a JSON-encoded object of key-value string pairs Example: query_params={"id":"123","mode":"preview"} The parameters are appended to the signed URL:

file_url:  https://skills.pinkfish.ai/files/{collectionId}/app.html?signed-key=xxx&id=123&mode=preview

For share links, query parameters are stored in the database and appended via a 302 redirect when the short URL is accessed. The short URL itself remains clean:

short_url: https://skills.pinkfish.ai/files/s/aBcD1234xY
→ redirects to: https://skills.pinkfish.ai/files/s/aBcD1234xY?id=123&mode=preview

JavaScript in the HTML file can read them:

const params = new URLSearchParams(window.location.search);
const id = params.get('id'); // "123"
const mode = params.get('mode'); // "preview"

Supported on: create, get, list, and sharelink operations.

Response Format

File creation/update:

{
  "message": "File created successfully",
  "file_url": "https://skills.pinkfish.ai/files/{collectionId}/file.txt?signed-key=..."
}

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": false,
  "signedUrl": "https://...",
  "accessList": [
    {
      "action": "create",
      "providerId": "user-id",
      "date": "2024-11-17T18:04:22.197Z"
    }
  ]
}

Share link response:

{
  "message": "Share link created successfully",
  "short_url": "https://skills.pinkfish.ai/files/s/aBcD1234xY",
  "expiresAt": "2026-02-08T12:00:00.000Z",
  "queryParams": {"id": "123", "mode": "preview"}
}

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
query_params (optional) - JSON key-value pairs to include in the signedUrl (see Query Parameters in Signed URLs)

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
query_params (optional) - JSON key-value pairs to include in the signedUrls (see Query Parameters in Signed URLs)

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

Create a short, shareable URL for a file with a specified expiration. Each call generates a unique short URL. Optionally store query parameters that are appended to the URL via redirect when accessed. Parameters:

action (required) - Set to “sharelink”
filename (required) - Name of the file
file_links_expire_in_days (optional) - Expiry: 1-7 days. At least one of days or minutes is required
file_links_expire_in_minutes (optional) - Minute-level precision
query_params (optional) - JSON key-value pairs stored with the link and appended via redirect on access

Examples: Create a share link with 1-day expiry:

/selected-filestore create share link:
filename: report.pdf
file_links_expire_in_days: "1"

Create a share link with stored query params:

/selected-filestore create share link:
filename: dashboard.html
file_links_expire_in_days: "7"
query_params: {"id": "customer-123", "mode": "readonly"}

Multiple share links for the same file are supported — each has its own unique short code and independent expiry.

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"

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
Share Links: Use the sharelink action to explicitly create short, shareable URLs for files. Each share link has its own unique short code and independent expiry. Query parameters can be stored with the link and are appended via 302 redirect when the short URL is accessed. Share links are not automatically generated — they must be explicitly created

Get Started

Organization

Agents

Workflows

Resources

Integrations

Orchestration

Credits & Pricing

Release Notes

Support

How to use it?

Basic Command Structure

Parameters

File Link Expiration

Query Parameters in Signed URLs

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

Event Triggers

Notes

Get Started

Organization

Agents

Workflows

Resources

Integrations

Orchestration

Credits & Pricing

Release Notes

Support

​How to use it?

​Basic Command Structure

​Parameters

​File Link Expiration

​Query Parameters in Signed URLs

​Response Format

​Tools

​Upload File

​Create or Replace Document

​Append to Document

​Get Document

​List Files

​Create Share Link

​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

​Event Triggers

​Notes

How to use it?

Basic Command Structure

Parameters

File Link Expiration

Query Parameters in Signed URLs

Response Format

Tools

Upload File

Create or Replace Document

Append to Document

Get Document

List Files

Create Share Link

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

Event Triggers

Notes