> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinkfish.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# filestorage
> File storage — upload, download, share, and manage files
**Server path:** `/filestorage` | **Type:** Embedded | **PCID required:** No
## Tools
| Tool | Description |
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [`filestorage_list_collections`](#filestorage_list_collections) | List all available filestorage collections. This is a tool that is used to get the collection ID for the other filestorage tools. |
| [`filestorage_create_collection`](#filestorage_create_collection) | Create a new file storage collection for storing files. Returns \{ id, name, type } - use the "id" field as collectionId for subsequent operations like uploading files. |
| [`filestorage_delete_collection`](#filestorage_delete_collection) | Delete a file storage collection and all its files. Returns \{ message } on success. WARNING: This is a destructive operation that cannot be undone. |
| [`filestorage_create_file_from_content`](#filestorage_create_file_from_content) | Create or replace a document in file storage with text content. This operation will overwrite existing files with the same filename by default. Returns file metadata including id, file\_size, mime\_type, and metadata. Agents: to share the created file, call filestorage\_create\_sharelink afterward — avoid requesting file\_url as it bloats context with storage credentials. Workflows: set returnFileUrl=true to include the file\_url in the response for convenient downstream use. Needs an EXISTING collection ID (not a name). |
| [`filestorage_get_item`](#filestorage_get_item) | Retrieve file metadata and optionally content from file storage. IMPORTANT: When a user asks to 'get a file', 'share a file', or 'send me a file', do NOT use this tool — use filestorage\_create\_sharelink instead, which returns a clean shareable URL (works for both public and private files). Only use this tool when you need to: (1) read the actual file contents for processing/analysis (set getFileContents=true), or (2) check file metadata (size, type, dates). Agents: avoid requesting the signedUrl as it is very long and bloats context — use filestorage\_create\_sharelink instead. Workflows: set returnSignedUrl=true when the URL is needed by downstream steps. |
| [`filestorage_update_item`](#filestorage_update_item) | Append content to existing text files or update metadata and link expiration settings. For text files (JSON, TXT, HTML, CSV): provide content to append. For binary files (PNG, JPG, PDF, etc.): omit content and only update metadata/expiration settings without resending file content. Can also be used to make files public or update link expiry. Agents: to share a file after update, use filestorage\_create\_sharelink. Workflows: set returnFileUrl=true to include the file\_url in the response. |
| [`filestorage_delete_item`](#filestorage_delete_item) | Delete a file from file storage. Permanently removes the file and all associated metadata. This operation cannot be undone. Supports both filename-based deletion and itemId-based deletion. Needs an EXISTING collection ID (not a name). |
| [`filestorage_list_items`](#filestorage_list_items) | List files in a file storage collection. Returns file metadata for browsing — no signed URLs or storage credentials are included. Recommended workflow: (1) list files to browse available files, (2) to read a specific file's content use filestorage\_get\_item with getFileContents=true, (3) to share a file with a user or third party use filestorage\_create\_sharelink which returns a clean short URL. |
| [`filestorage_create_file_from_file_url`](#filestorage_create_file_from_file_url) | Upload a file to file storage from a URL source. Downloads the file from the provided URL and stores it in the collection. By default, uploading with the same filename will overwrite existing files. Returns file metadata including id, file\_size, mime\_type, and metadata. Agents: to share the uploaded file, call filestorage\_create\_sharelink afterward — avoid requesting file\_url as it bloats context with storage credentials. Workflows: set returnFileUrl=true to include the file\_url in the response for convenient downstream use. Supports all file types (documents, images, audio, video, etc.). |
| [`filestorage_create_sharelink`](#filestorage_create_sharelink) | DEFAULT TOOL when a user asks to 'get', 'share', or 'send' a file. Works for both public and private files. Creates a clean, shareable URL that serves the file directly in the browser. For private files, returns a short URL that does not expose storage signatures. For public files, returns the public URL directly. When the user says 'get me file X' or 'can I have file X', use this tool — do NOT use filestorage\_get\_item unless the user explicitly wants the file contents for processing. Each call generates a unique short URL with its own independent expiration. Optionally store query parameters that will be appended to the URL when the link is accessed. |
| [`filestorage_make_file_public`](#filestorage_make_file_public) | Make a file public so anyone with the URL can access it. WARNING: This action makes the file accessible to anyone on the internet — confirm with the user before proceeding. Once public, the file will not expire and can be accessed without authentication. Returns the public URL. This is reversible — to make the file private again, use filestorage\_update\_item with a fileLinksExpireInDays value (1-7). |
***
## filestorage\_list\_collections
List all available filestorage collections. This is a tool that is used to get the collection ID for the other filestorage tools.
**Parameters:** None
```json theme={null}
{
"type": "object",
"properties": {}
}
```
***
## filestorage\_create\_collection
Create a new file storage collection for storing files. Returns \{ id, name, type } - use the "id" field as collectionId for subsequent operations like uploading files.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------------- | ------ | -------- | ------- | --------------------------------------------------------------------------------- |
| `name` | string | Yes | — | Display name for the file storage collection |
| `description` | string | No | — | Optional description of the collection purpose |
| `createdBy` | string | Yes | — | User ID creating the collection - use the current user ID or a service identifier |
| `createdByName` | string | Yes | — | Display name shown as creator - use the current user name or service name |
```json theme={null}
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Display name for the file storage collection"
},
"description": {
"type": "string",
"description": "Optional description of the collection purpose"
},
"createdBy": {
"type": "string",
"description": "User ID creating the collection - use the current user ID or a service identifier"
},
"createdByName": {
"type": "string",
"description": "Display name shown as creator - use the current user name or service name"
}
},
"required": [
"name",
"createdBy",
"createdByName"
]
}
```
***
## filestorage\_delete\_collection
Delete a file storage collection and all its files. Returns \{ message } on success. WARNING: This is a destructive operation that cannot be undone.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| -------------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
| `collectionId` | string | Yes | — | Collection ID to delete - e.g. "KCny7nGXpBzWNYpJzC0b". Use filestorage\_list\_collections to get collection IDs. |
```json theme={null}
{
"type": "object",
"properties": {
"collectionId": {
"type": "string",
"description": "Collection ID to delete - e.g. \"KCny7nGXpBzWNYpJzC0b\". Use filestorage_list_collections to get collection IDs."
}
},
"required": [
"collectionId"
]
}
```
***
## filestorage\_create\_file\_from\_content
Create or replace a document in file storage with text content. This operation will overwrite existing files with the same filename by default. Returns file metadata including id, file\_size, mime\_type, and metadata. Agents: to share the created file, call filestorage\_create\_sharelink afterward — avoid requesting file\_url as it bloats context with storage credentials. Workflows: set returnFileUrl=true to include the file\_url in the response for convenient downstream use. Needs an EXISTING collection ID (not a name).
**Parameters:**
| Parameter | Type | Required | Default | Description |
| -------------------------- | ------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `collectionId` | string | Yes | — | Collection ID to add the file to - e.g. "KCny7nGXpBzWNYpJzC0b" |
| `filename` | string | Yes | — | Name of the file to store (required) - e.g. "example.json" |
| `content` | string | Yes | — | Content of the file to store (required) - text content for the file |
| `metadata` | string | No | — | Optional metadata - can be an object with key-value pairs (e.g. \{"project": "onboarding", "originalFilename": "sample.pdf", "batchId": "batch\_2025-07-08\_21-19-44"}) or a simple string (e.g. "Document uploaded from automation"). If no metadata requested by user, add a description of the process that created this file. If a string is provided, it will be wrapped as \{"description": "your string"}. |
| `fileLinksExpireInDays` | string | No | `1` | File link expiration: 1-7 days or "never" to make file public. |
| `fileLinksExpireInMinutes` | number | No | — | Minute-level precision for file link expiration. Can be combined with days (max 7 days total). |
| `returnFileUrl` | boolean | No | `false` | Whether to include the file\_url (signed storage URL) in the response. Agents should generally leave this false and use filestorage\_create\_sharelink instead. Workflows should set true when the URL is needed by downstream steps. |
| `replaceExisting` | boolean | No | `true` | Whether to replace existing files with same filename. If false, adds timestamp to filename to avoid overwriting. |
| `queryParams` | object | No | — | Optional key-value pairs to include as query parameters in the signed URL. Useful for passing contextual data (e.g. \{"id": "123"}) that JavaScript in HTML files can read via URLSearchParams. |
| `proxyId` | string | No | — | Proxy ID to access a shared filestorage collection. Requires X-API-Key header. |
```json theme={null}
{
"type": "object",
"properties": {
"collectionId": {
"type": "string",
"description": "Collection ID to add the file to - e.g. \"KCny7nGXpBzWNYpJzC0b\""
},
"filename": {
"type": "string",
"description": "Name of the file to store (required) - e.g. \"example.json\""
},
"content": {
"type": "string",
"description": "Content of the file to store (required) - text content for the file"
},
"metadata": {
"oneOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "string"
}
],
"description": "Optional metadata - can be an object with key-value pairs (e.g. {\"project\": \"onboarding\", \"originalFilename\": \"sample.pdf\", \"batchId\": \"batch_2025-07-08_21-19-44\"}) or a simple string (e.g. \"Document uploaded from automation\"). If no metadata requested by user, add a description of the process that created this file. If a string is provided, it will be wrapped as {\"description\": \"your string\"}."
},
"fileLinksExpireInDays": {
"oneOf": [
{
"type": "number"
},
{
"type": "string",
"const": "never"
}
],
"default": 1,
"description": "File link expiration: 1-7 days or \"never\" to make file public."
},
"fileLinksExpireInMinutes": {
"type": "number",
"description": "Minute-level precision for file link expiration. Can be combined with days (max 7 days total)."
},
"returnFileUrl": {
"type": "boolean",
"default": false,
"description": "Whether to include the file_url (signed storage URL) in the response. Agents should generally leave this false and use filestorage_create_sharelink instead. Workflows should set true when the URL is needed by downstream steps."
},
"replaceExisting": {
"type": "boolean",
"default": true,
"description": "Whether to replace existing files with same filename. If false, adds timestamp to filename to avoid overwriting."
},
"queryParams": {
"type": "object",
"additionalProperties": true,
"description": "Optional key-value pairs to include as query parameters in the signed URL. Useful for passing contextual data (e.g. {\"id\": \"123\"}) that JavaScript in HTML files can read via URLSearchParams."
},
"proxyId": {
"type": "string",
"description": "Proxy ID to access a shared filestorage collection. Requires X-API-Key header."
}
},
"required": [
"collectionId",
"filename",
"content"
]
}
```
***
## filestorage\_get\_item
Retrieve file metadata and optionally content from file storage. IMPORTANT: When a user asks to 'get a file', 'share a file', or 'send me a file', do NOT use this tool — use filestorage\_create\_sharelink instead, which returns a clean shareable URL (works for both public and private files). Only use this tool when you need to: (1) read the actual file contents for processing/analysis (set getFileContents=true), or (2) check file metadata (size, type, dates). Agents: avoid requesting the signedUrl as it is very long and bloats context — use filestorage\_create\_sharelink instead. Workflows: set returnSignedUrl=true when the URL is needed by downstream steps.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| -------------------------- | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `collectionId` | string | Yes | — | Collection ID the file belongs to - e.g. "KCny7nGXpBzWNYpJzC0b" |
| `filename` | string | Yes | — | Name of the file to retrieve (required) - e.g. "example.json". Use this for filename-based access. |
| `getFileContents` | boolean | No | `false` | Whether to include file contents in response. Works for text files (JSON, TXT, HTML, CSV) and extracts text from binary documents (PDF, DOCX, XLSX, PPTX). |
| `fileLinksExpireInDays` | string | No | `1` | File link expiration for returned signedUrl: 1-7 days or "never" for public access. |
| `fileLinksExpireInMinutes` | number | No | — | Minute-level precision for signedUrl expiration. Can be combined with days (max 7 days total). |
| `queryParams` | object | No | — | Optional key-value pairs to include as query parameters in the signed URL. Useful for passing contextual data (e.g. \{"id": "123"}) that JavaScript in HTML files can read via URLSearchParams. |
| `returnSignedUrl` | boolean | No | `false` | Whether to include the signedUrl in the response. Agents should generally leave this false and use filestorage\_create\_sharelink instead. Workflows should set true when the URL is needed by downstream steps. |
| `proxyId` | string | No | — | Proxy ID to access a shared filestorage collection. Requires X-API-Key header. |
```json theme={null}
{
"type": "object",
"properties": {
"collectionId": {
"type": "string",
"description": "Collection ID the file belongs to - e.g. \"KCny7nGXpBzWNYpJzC0b\""
},
"filename": {
"type": "string",
"description": "Name of the file to retrieve (required) - e.g. \"example.json\". Use this for filename-based access."
},
"getFileContents": {
"type": "boolean",
"default": false,
"description": "Whether to include file contents in response. Works for text files (JSON, TXT, HTML, CSV) and extracts text from binary documents (PDF, DOCX, XLSX, PPTX)."
},
"fileLinksExpireInDays": {
"oneOf": [
{
"type": "number"
},
{
"type": "string",
"const": "never"
}
],
"default": 1,
"description": "File link expiration for returned signedUrl: 1-7 days or \"never\" for public access."
},
"fileLinksExpireInMinutes": {
"type": "number",
"description": "Minute-level precision for signedUrl expiration. Can be combined with days (max 7 days total)."
},
"queryParams": {
"type": "object",
"additionalProperties": true,
"description": "Optional key-value pairs to include as query parameters in the signed URL. Useful for passing contextual data (e.g. {\"id\": \"123\"}) that JavaScript in HTML files can read via URLSearchParams."
},
"returnSignedUrl": {
"type": "boolean",
"default": false,
"description": "Whether to include the signedUrl in the response. Agents should generally leave this false and use filestorage_create_sharelink instead. Workflows should set true when the URL is needed by downstream steps."
},
"proxyId": {
"type": "string",
"description": "Proxy ID to access a shared filestorage collection. Requires X-API-Key header."
}
},
"required": [
"collectionId",
"filename"
]
}
```
***
## filestorage\_update\_item
Append content to existing text files or update metadata and link expiration settings. For text files (JSON, TXT, HTML, CSV): provide content to append. For binary files (PNG, JPG, PDF, etc.): omit content and only update metadata/expiration settings without resending file content. Can also be used to make files public or update link expiry. Agents: to share a file after update, use filestorage\_create\_sharelink. Workflows: set returnFileUrl=true to include the file\_url in the response.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| -------------------------- | ------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `collectionId` | string | Yes | — | Collection ID the file belongs to - e.g. "KCny7nGXpBzWNYpJzC0b" |
| `filename` | string | Yes | — | Name of file to update (required) - e.g. "example.txt" |
| `content` | string | No | — | Content to append to text files (TEXT FILES ONLY). Must be string. Omit for binary files when only updating metadata/expiration. |
| `metadata` | string | No | — | Optional metadata - can be an object with key-value pairs (e.g. \{"project": "onboarding", "originalFilename": "sample.pdf"}) or a simple string (e.g. "File updated from automation"). If a string is provided, it will be wrapped as \{"description": "your string"}. Additional fields will be stored as metadata. |
| `fileLinksExpireInDays` | string | No | — | Update file link expiration: 1-7 days or "never" to make file public. Use "never" to make files publicly accessible. |
| `fileLinksExpireInMinutes` | number | No | — | Minute-level precision for link expiration. Can be combined with days (max 7 days total). |
| `returnFileUrl` | boolean | No | `false` | Whether to include the file\_url (signed storage URL) in the response. Agents should generally leave this false and use filestorage\_create\_sharelink instead. Workflows should set true when the URL is needed by downstream steps. |
| `proxyId` | string | No | — | Proxy ID to access a shared filestorage collection. Requires X-API-Key header. |
```json theme={null}
{
"type": "object",
"properties": {
"collectionId": {
"type": "string",
"description": "Collection ID the file belongs to - e.g. \"KCny7nGXpBzWNYpJzC0b\""
},
"filename": {
"type": "string",
"description": "Name of file to update (required) - e.g. \"example.txt\""
},
"content": {
"type": "string",
"description": "Content to append to text files (TEXT FILES ONLY). Must be string. Omit for binary files when only updating metadata/expiration."
},
"metadata": {
"oneOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "string"
}
],
"description": "Optional metadata - can be an object with key-value pairs (e.g. {\"project\": \"onboarding\", \"originalFilename\": \"sample.pdf\"}) or a simple string (e.g. \"File updated from automation\"). If a string is provided, it will be wrapped as {\"description\": \"your string\"}. Additional fields will be stored as metadata."
},
"fileLinksExpireInDays": {
"oneOf": [
{
"type": "number"
},
{
"type": "string",
"const": "never"
}
],
"description": "Update file link expiration: 1-7 days or \"never\" to make file public. Use \"never\" to make files publicly accessible."
},
"fileLinksExpireInMinutes": {
"type": "number",
"description": "Minute-level precision for link expiration. Can be combined with days (max 7 days total)."
},
"returnFileUrl": {
"type": "boolean",
"default": false,
"description": "Whether to include the file_url (signed storage URL) in the response. Agents should generally leave this false and use filestorage_create_sharelink instead. Workflows should set true when the URL is needed by downstream steps."
},
"proxyId": {
"type": "string",
"description": "Proxy ID to access a shared filestorage collection. Requires X-API-Key header."
}
},
"required": [
"collectionId",
"filename"
]
}
```
***
## filestorage\_delete\_item
Delete a file from file storage. Permanently removes the file and all associated metadata. This operation cannot be undone. Supports both filename-based deletion and itemId-based deletion. Needs an EXISTING collection ID (not a name).
**Parameters:**
| Parameter | Type | Required | Default | Description |
| -------------- | ------ | -------- | ------- | ----------------------------------------------------------------------------------------------------- |
| `collectionId` | string | Yes | — | Collection ID the file belongs to - e.g. "KCny7nGXpBzWNYpJzC0b" |
| `filename` | string | Yes | — | Name of file to delete (required) - e.g. "example.json". File must exist in the specified collection. |
| `proxyId` | string | No | — | Proxy ID to access a shared filestorage collection. Requires X-API-Key header. |
```json theme={null}
{
"type": "object",
"properties": {
"collectionId": {
"type": "string",
"description": "Collection ID the file belongs to - e.g. \"KCny7nGXpBzWNYpJzC0b\""
},
"filename": {
"type": "string",
"description": "Name of file to delete (required) - e.g. \"example.json\". File must exist in the specified collection."
},
"proxyId": {
"type": "string",
"description": "Proxy ID to access a shared filestorage collection. Requires X-API-Key header."
}
},
"required": [
"collectionId",
"filename"
]
}
```
***
## filestorage\_list\_items
List files in a file storage collection. Returns file metadata for browsing — no signed URLs or storage credentials are included. Recommended workflow: (1) list files to browse available files, (2) to read a specific file's content use filestorage\_get\_item with getFileContents=true, (3) to share a file with a user or third party use filestorage\_create\_sharelink which returns a clean short URL.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| -------------------------- | ------ | -------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `collectionId` | string | Yes | — | Collection ID to list files from - e.g. "KCny7nGXpBzWNYpJzC0b". Always an ID that can be obtained from filestorage\_list\_collections, never a name. |
| `format` | string | No | `"light"` | Response format: "light" (default, recommended) or "full". Light returns file metadata without signed URLs. Full includes signedUrl per file but is rarely needed — use filestorage\_get\_item for individual file access instead. |
| `fileLinksExpireInDays` | string | No | `1` | File link expiration for returned signedUrls: 1-7 days or "never" for public access. |
| `fileLinksExpireInMinutes` | number | No | — | Minute-level precision for signedUrl expiration. Can be combined with days (max 7 days total). |
| `queryParams` | object | No | — | Optional key-value pairs to include as query parameters in the signed URLs. Useful for passing contextual data (e.g. \{"id": "123"}) that JavaScript in HTML files can read via URLSearchParams. |
| `proxyId` | string | No | — | Proxy ID to access a shared filestorage collection. Requires X-API-Key header. |
```json theme={null}
{
"type": "object",
"properties": {
"collectionId": {
"type": "string",
"description": "Collection ID to list files from - e.g. \"KCny7nGXpBzWNYpJzC0b\". Always an ID that can be obtained from filestorage_list_collections, never a name."
},
"format": {
"type": "string",
"enum": [
"light",
"full"
],
"default": "light",
"description": "Response format: \"light\" (default, recommended) or \"full\". Light returns file metadata without signed URLs. Full includes signedUrl per file but is rarely needed — use filestorage_get_item for individual file access instead."
},
"fileLinksExpireInDays": {
"oneOf": [
{
"type": "number"
},
{
"type": "string",
"const": "never"
}
],
"default": 1,
"description": "File link expiration for returned signedUrls: 1-7 days or \"never\" for public access."
},
"fileLinksExpireInMinutes": {
"type": "number",
"description": "Minute-level precision for signedUrl expiration. Can be combined with days (max 7 days total)."
},
"queryParams": {
"type": "object",
"additionalProperties": true,
"description": "Optional key-value pairs to include as query parameters in the signed URLs. Useful for passing contextual data (e.g. {\"id\": \"123\"}) that JavaScript in HTML files can read via URLSearchParams."
},
"proxyId": {
"type": "string",
"description": "Proxy ID to access a shared filestorage collection. Requires X-API-Key header."
}
},
"required": [
"collectionId"
]
}
```
***
## filestorage\_create\_file\_from\_file\_url
Upload a file to file storage from a URL source. Downloads the file from the provided URL and stores it in the collection. By default, uploading with the same filename will overwrite existing files. Returns file metadata including id, file\_size, mime\_type, and metadata. Agents: to share the uploaded file, call filestorage\_create\_sharelink afterward — avoid requesting file\_url as it bloats context with storage credentials. Workflows: set returnFileUrl=true to include the file\_url in the response for convenient downstream use. Supports all file types (documents, images, audio, video, etc.).
**Parameters:**
| Parameter | Type | Required | Default | Description |
| -------------------------- | ------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `collectionId` | string | Yes | — | Collection ID to add the file to - e.g. "KCny7nGXpBzWNYpJzC0b" |
| `fileUrl` | string | Yes | — | URL of file to download and upload to storage (required). Must be accessible via HTTP/HTTPS. |
| `metadata` | string | No | — | Optional metadata - can be an object with key-value pairs (e.g. \{"project": "onboarding", "originalFilename": "sample.pdf"}) or a simple string (e.g. "File uploaded from URL"). If a string is provided, it will be wrapped as \{"description": "your string"}. Additional attributes for file organization. |
| `fileLinksExpireInDays` | string | No | `1` | File link expiration: 1-7 days or "never" to make file public. |
| `fileLinksExpireInMinutes` | number | No | — | Minute-level precision for file link expiration. Can be combined with days (max 7 days total). |
| `returnFileUrl` | boolean | No | `false` | Whether to include the file\_url (signed storage URL) in the response. Agents should generally leave this false and use filestorage\_create\_sharelink instead. Workflows should set true when the URL is needed by downstream steps. |
| `replaceExisting` | boolean | No | `true` | Whether to replace existing files with same filename. If false, adds timestamp to filename to avoid overwriting. |
| `queryParams` | object | No | — | Optional key-value pairs to include as query parameters in the signed URL. Useful for passing contextual data (e.g. \{"id": "123"}) that JavaScript in HTML files can read via URLSearchParams. |
| `proxyId` | string | No | — | Proxy ID to access a shared filestorage collection. Requires X-API-Key header. |
```json theme={null}
{
"type": "object",
"properties": {
"collectionId": {
"type": "string",
"description": "Collection ID to add the file to - e.g. \"KCny7nGXpBzWNYpJzC0b\""
},
"fileUrl": {
"type": "string",
"description": "URL of file to download and upload to storage (required). Must be accessible via HTTP/HTTPS."
},
"metadata": {
"oneOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "string"
}
],
"description": "Optional metadata - can be an object with key-value pairs (e.g. {\"project\": \"onboarding\", \"originalFilename\": \"sample.pdf\"}) or a simple string (e.g. \"File uploaded from URL\"). If a string is provided, it will be wrapped as {\"description\": \"your string\"}. Additional attributes for file organization."
},
"fileLinksExpireInDays": {
"oneOf": [
{
"type": "number"
},
{
"type": "string",
"const": "never"
}
],
"default": 1,
"description": "File link expiration: 1-7 days or \"never\" to make file public."
},
"fileLinksExpireInMinutes": {
"type": "number",
"description": "Minute-level precision for file link expiration. Can be combined with days (max 7 days total)."
},
"returnFileUrl": {
"type": "boolean",
"default": false,
"description": "Whether to include the file_url (signed storage URL) in the response. Agents should generally leave this false and use filestorage_create_sharelink instead. Workflows should set true when the URL is needed by downstream steps."
},
"replaceExisting": {
"type": "boolean",
"default": true,
"description": "Whether to replace existing files with same filename. If false, adds timestamp to filename to avoid overwriting."
},
"queryParams": {
"type": "object",
"additionalProperties": true,
"description": "Optional key-value pairs to include as query parameters in the signed URL. Useful for passing contextual data (e.g. {\"id\": \"123\"}) that JavaScript in HTML files can read via URLSearchParams."
},
"proxyId": {
"type": "string",
"description": "Proxy ID to access a shared filestorage collection. Requires X-API-Key header."
}
},
"required": [
"collectionId",
"fileUrl"
]
}
```
***
## filestorage\_create\_sharelink
DEFAULT TOOL when a user asks to 'get', 'share', or 'send' a file. Works for both public and private files. Creates a clean, shareable URL that serves the file directly in the browser. For private files, returns a short URL that does not expose storage signatures. For public files, returns the public URL directly. When the user says 'get me file X' or 'can I have file X', use this tool — do NOT use filestorage\_get\_item unless the user explicitly wants the file contents for processing. Each call generates a unique short URL with its own independent expiration. Optionally store query parameters that will be appended to the URL when the link is accessed.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| -------------------------- | ------ | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `collectionId` | string | Yes | — | Collection ID the file belongs to - e.g. "KCny7nGXpBzWNYpJzC0b" |
| `filename` | string | Yes | — | Name of the file to create a share link for (required) - e.g. "example.json" |
| `fileLinksExpireInDays` | number | No | — | Share link expiration in days (1-7). At least one of fileLinksExpireInDays or fileLinksExpireInMinutes is required. |
| `fileLinksExpireInMinutes` | number | No | — | Share link expiration in minutes. Can be combined with days (max 7 days total). At least one of fileLinksExpireInDays or fileLinksExpireInMinutes is required. |
| `queryParams` | object | No | — | Optional key-value pairs to store with the link. When the short URL is accessed, these params are appended to the URL via redirect so client-side JavaScript can read them via URLSearchParams. |
| `proxyId` | string | No | — | Proxy ID to access a shared filestorage collection. Requires X-API-Key header. |
```json theme={null}
{
"type": "object",
"properties": {
"collectionId": {
"type": "string",
"description": "Collection ID the file belongs to - e.g. \"KCny7nGXpBzWNYpJzC0b\""
},
"filename": {
"type": "string",
"description": "Name of the file to create a share link for (required) - e.g. \"example.json\""
},
"fileLinksExpireInDays": {
"type": "number",
"description": "Share link expiration in days (1-7). At least one of fileLinksExpireInDays or fileLinksExpireInMinutes is required."
},
"fileLinksExpireInMinutes": {
"type": "number",
"description": "Share link expiration in minutes. Can be combined with days (max 7 days total). At least one of fileLinksExpireInDays or fileLinksExpireInMinutes is required."
},
"queryParams": {
"type": "object",
"additionalProperties": true,
"description": "Optional key-value pairs to store with the link. When the short URL is accessed, these params are appended to the URL via redirect so client-side JavaScript can read them via URLSearchParams."
},
"proxyId": {
"type": "string",
"description": "Proxy ID to access a shared filestorage collection. Requires X-API-Key header."
}
},
"required": [
"collectionId",
"filename"
]
}
```
***
## filestorage\_make\_file\_public
Make a file public so anyone with the URL can access it. WARNING: This action makes the file accessible to anyone on the internet — confirm with the user before proceeding. Once public, the file will not expire and can be accessed without authentication. Returns the public URL. This is reversible — to make the file private again, use filestorage\_update\_item with a fileLinksExpireInDays value (1-7).
**Parameters:**
| Parameter | Type | Required | Default | Description |
| -------------- | ------ | -------- | ------- | ------------------------------------------------------------------------------ |
| `collectionId` | string | Yes | — | Collection ID the file belongs to - e.g. "KCny7nGXpBzWNYpJzC0b" |
| `filename` | string | Yes | — | Name of the file to make public (required) - e.g. "report.html" |
| `proxyId` | string | No | — | Proxy ID to access a shared filestorage collection. Requires X-API-Key header. |
```json theme={null}
{
"type": "object",
"properties": {
"collectionId": {
"type": "string",
"description": "Collection ID the file belongs to - e.g. \"KCny7nGXpBzWNYpJzC0b\""
},
"filename": {
"type": "string",
"description": "Name of the file to make public (required) - e.g. \"report.html\""
},
"proxyId": {
"type": "string",
"description": "Proxy ID to access a shared filestorage collection. Requires X-API-Key header."
}
},
"required": [
"collectionId",
"filename"
]
}
```