fast-io

name	fast-io
description	Workspaces for agentic teams. Complete agent guide with all 19 consolidated tools using action-based routing — parameters, workflows, ID formats, and constraints. Use this skill when agents need shared workspaces to collaborate with other agents and humans, create branded shares (Send/Receive/Exchange), or query documents using built-in AI. Supports ownership transfer to humans, workspace management, workflow primitives (tasks, worklogs, approvals, todos), and real-time collaboration. Free agent plan with 50 GB storage and 5,000 monthly credits.
license	Proprietary
compatibility	Requires network access. Connects to the Fast.io MCP server at mcp.fast.io via Streamable HTTP (/mcp) or SSE (/sse).
metadata	{"author":"fast-io","version":"1.94.0"}
homepage	https://fast.io

Fast.io MCP Server -- AI Agent Guide

Version: 1.94 Last Updated: 2026-02-22

The definitive guide for AI agents using the Fast.io MCP server. Covers why and how to use the platform: product capabilities, the free agent plan, authentication, core concepts (workspaces, shares, intelligence, previews, comments, URL import, metadata, workflow, ownership transfer), 12 end-to-end workflows, interactive MCP App widgets, and all 19 consolidated tools with action-based routing.

Versioned guide. This guide is versioned and updated with each server release. The version number at the top of this document tracks tool parameters, ID formats, and API behavior changes. If you encounter unexpected errors, the guide version may have changed since you last read it.

Platform reference. For a comprehensive overview of Fast.io's capabilities, the agent plan, key workflows, and upgrade paths, see references/REFERENCE.md.

---

1. Overview

Workspaces for Agentic Teams. Collaborate, share, and query with AI -- all through one API, free.

Fast.io provides workspaces for agentic teams -- where agents collaborate with other agents and with humans. Upload outputs, create branded data rooms, ask questions about documents using built-in AI, and hand everything off to a human when the job is done. No infrastructure to manage, no subscriptions to set up, no credit card required.

The Problem Fast.io Solves

Agentic teams -- groups of agents working together and with humans -- need a shared place to work. Today, agents cobble together S3 buckets, presigned URLs, email attachments, and custom download pages. Every agent reinvents collaboration, and there is no shared workspace where agents and humans can see the same files, track activity, and hand off work.

When agents need to understand documents -- not just store them -- they have to download files, parse dozens of formats, build search indexes, and manage their own RAG pipeline. That is a lot of infrastructure for what should be a simple question: "What does this document say?"

Problem	Fast.io Solution
No shared workspace for agentic teams	Workspaces where agents and humans collaborate with file preview, versioning, and AI
Agent-to-agent coordination lacks structure	Shared workspaces with activity feeds, comments, and real-time sync across team members
Sharing outputs with humans is awkward	Purpose-built shares (Send, Receive, Exchange) with link sharing, passwords, expiration
Collecting files from humans is harder	Receive shares let humans upload directly to your workspace -- no email attachments
Understanding document contents	Built-in AI reads, summarizes, and answers questions about your files
Building a RAG pipeline from scratch	Enable intelligence on a workspace and documents are automatically indexed, summarized, and queryable
Finding the right file in a large collection	Semantic search finds documents by meaning, not just filename
Handing a project off to a human	One-click ownership transfer -- human gets the org, agent keeps admin access
Tracking what happened	Full audit trail with AI-powered activity summaries
Cost	Free. 50 GB storage, 5,000 monthly credits, no credit card

MCP Server

This MCP server exposes 19 consolidated tools that cover the full Fast.io REST API surface. Every authenticated API endpoint has a corresponding tool action, and the server handles session management automatically.

Once a user authenticates, the auth token is stored in the server session and automatically attached to all subsequent API calls. There is no need to pass tokens between tool invocations.

Server Endpoints

• Production: mcp.fast.io
• Development: mcp.fastdev1.com

Two transports are available on each:

• Streamable HTTP at /mcp -- the preferred transport for new integrations.
• SSE at /sse -- a legacy transport maintained for backward compatibility.

MCP Resources

The server exposes static MCP resources, widget resources, and file download resource templates. Clients can read them via resources/list and resources/read:

URI	Name	Description	MIME Type
skill://guide	skill-guide	Full agent guide (this document) with all 19 tools, workflows, and platform documentation	text/markdown
session://status	session-status	Current authentication state: authenticated boolean, user_id, user_email, token_expires_at (Unix epoch), token_expires_at_iso (ISO 8601), scopes (raw scope string or null), scopes_detail (array of hydrated scope objects with entity names/domains/parents, or null), agent_name (string or null)	application/json
widget://*	Widget HTML	Interactive HTML5 widgets (5 total) -- use the apps tool to discover and launch	text/html

File download resource templates -- read file content directly through MCP without needing external HTTP access:

URI Template	Name	Auth	Dynamic Listing	Description
download://workspace/{workspace_id}/{node_id}	download-workspace-file	Session token	Yes	Download a file from a workspace
download://share/{share_id}/{node_id}	download-share-file	Session token	Yes	Download a file from a share
download://quickshare/{quickshare_id}	download-quickshare-file	None (public)	No	Download a quickshare file

Files up to 50 MB are returned inline as base64-encoded blob content. Larger files return a text fallback with a URL to the HTTP pass-through endpoint (see below). The download tool responses include a resource_uri field with the appropriate URI for each file.

Dynamic resource listing: When authenticated, workspace and share file resources are dynamically listed via resources/list. MCP clients (such as Claude Desktop's @ mention picker) can discover available files without any tool calls. Up to 10 workspaces and 10 shares are enumerated, with up to 25 most recently updated root-level files from each. Resources appear as "WorkspaceName / filename.ext" or "ShareTitle / filename.ext". Results are cached for 1 minute per session. Only root-level files are listed -- subdirectories are not recursively enumerated. Use the storage tool with action list to browse deeper. The quickshare template remains template-only and is not dynamically enumerable.

MCP Prompts

The server registers MCP prompts that appear in the client's "Add From" / "+" menu as user-clickable app launchers. These are primarily for desktop MCP clients (e.g., Claude Desktop); code-mode clients (Claude Code, Cursor) do not surface prompts.

Prompt Name	Description
App: Choose Workspace or Org	Launch the Workspace Picker to browse orgs, select workspaces, and manage shares
App: Pick a File	Launch the File Picker with built-in workspace navigator for browsing, searching, and selecting files
App: Open Workflow	Launch the Workflow Manager (auto-selects workspace if only one, otherwise opens Workspace Picker first)
App: Available Apps	List all available MCP App widgets with descriptions and launch instructions

HTTP File Pass-Through

For files larger than 50 MB or when raw binary streaming is needed, the server provides an HTTP pass-through endpoint that streams file content directly from the API:

Endpoint	Auth	Description
GET /file/workspace/{workspace_id}/{node_id}	Mcp-Session-Id header	Stream a workspace file
GET /file/share/{share_id}/{node_id}	Mcp-Session-Id header	Stream a share file
GET /file/quickshare/{quickshare_id}	None (public)	Stream a quickshare file

The response includes proper Content-Type, Content-Length, and Content-Disposition headers from the upstream API. Errors are returned as HTML pages. The Mcp-Session-Id header is the same session identifier used for MCP protocol communication.

Workflow Overview

The server includes workflow features for project tracking: tasks (structured work items with priorities and assignees), worklogs (append-only activity logs), approvals (formal sign-off requests), and todos (simple checklists). Enable workflow on a workspace with workspace action enable-workflow before using these tools. See the Full Agent Workflow recipe in section 6 for the complete pattern.

Best practice (IMPORTANT): After state-changing actions (uploading files, creating shares, changing task status, member changes, file moves/deletes), append a worklog entry describing what you did and why. Without worklog entries, agent work is invisible to humans reviewing the workspace. For multiple related actions (e.g., uploading several files), you may log once after the batch completes rather than after each individual action. Worklog entries are append-only and permanent.

Additional References

• Agent guide (this file): /skill.md on the MCP server -- tool documentation, workflows, and constraints.
• REST API reference: https://api.fast.io/llms.txt -- endpoint documentation for the underlying Fast.io API.
• Platform guide: references/REFERENCE.md -- capabilities, agent plan details, key workflows, and upgrade paths.

---

2. Authentication (Critical First Step)

Authentication is required before calling any tool except these unauthenticated tools:

• auth with actions: signin, signup, set-api-key, pkce-login, email-check, password-reset-request, password-reset
• download with action: quickshare-details

Choosing the Right Approach

There are three ways to use Fast.io as an agent, depending on whether you are operating autonomously or assisting an existing human user.

Option 1: Autonomous Agent -- Create an Agent Account

If you are operating independently (storing files, running workflows, building workspaces for users), create your own agent account with auth action signup. Agent accounts get the free agent plan (50 GB, 5,000 monthly credits) and can transfer orgs to humans when ready. This is the recommended path for autonomous agents. See Agent Account Creation below for steps.

Option 2: Assisting a Human -- Use Their API Key

If a human already has a Fast.io account and wants your help managing their files, workspaces, or shares, they can create an API key for you to use. No separate agent account is needed -- you operate as the human user. The human creates a key at Settings -> Devices & Agents -> API Keys (direct link: https://go.fast.io/settings/api-keys). Call auth with action set-api-key and the key to authenticate -- the key is validated and stored in the session automatically. API keys are a 1:1 replacement for JWT tokens: they work as Bearer tokens with the same permissions as the account owner and do not expire unless revoked. Agents can also manage API keys programmatically with auth actions api-key-create, api-key-list, and api-key-delete.

Option 3: Agent Account Invited to a Human's Org

If you want your own agent identity but need to work within a human's existing organization, create an agent account with auth action signup, then have the human invite you to their org with member action add (entity_type org) or to a workspace with member action add (entity_type workspace). Alternatively the human can invite via the UI: Settings -> Your Organization -> Manage People. This gives you access to their workspaces and shares while keeping your own account separate. After accepting invitations with user action accept-all-invitations, use auth action signin to authenticate normally. Note: If the human only invites you to a workspace (not the org), the org will appear as external -- see Internal vs External Orgs in the Organizations section.

Option 4: Browser Login (PKCE)

If you prefer not to send a password through the agent, use browser-based PKCE login. Call auth action pkce-login (optionally with an email hint) to get a login URL. The user opens the URL in a browser, signs in (email/password or SSO like Google/Microsoft), and approves access. The browser displays an authorization code which the user copies back to the agent. Call auth action pkce-complete with the code to finish signing in. This is the most secure option -- no credentials pass through the agent.

PKCE login supports optional scoped access via the scope_type parameter. By default, scope_type is "user" (full account access). Other scope types restrict the token to specific entity types:

scope_type	Access granted
user	Full account access (default)
org	User selects specific organizations
workspace	User selects specific workspaces
all_orgs	All organizations the user belongs to
all_workspaces	All workspaces the user has access to
all_shares	All shares the user is a member of (share:*:<mode>)

Scope inheritance: Broader scopes include access to child entities automatically:

• all_orgs includes all orgs + all workspaces + all shares within those orgs
• all_workspaces includes all workspaces + all shares within those workspaces
• org scope on a specific org includes access to all workspaces and shares within that org
• workspace scope on a specific workspace includes access to shares within that workspace
• all_shares grants direct access to all shares the user has membership in, bypassing workspace/org inheritance

The agent_name parameter controls what the user sees on the approval screen -- the screen displays "[agent_name] will act on your behalf". If omitted, only the client name is shown. Use a descriptive name so the user knows which agent is requesting access.

Approval flow by scope_type:

• user (default): Full account access. The user sees a simple approve/decline prompt with no entity picker.
• org, workspace: The user sees an entity selection screen listing their accessible entities with checkboxes, plus a read-only / read-write toggle. The user picks which entities to grant, then approves or declines.
• all_orgs, all_workspaces, all_shares: The user sees a summary of the wildcard access being requested (no entity picker), then approves or declines.

The MCP server defaults to scope_type="user" for backward compatibility.

Scenario	Recommended Approach
Operating autonomously, storing files, building for users	Create an agent account with your own org (Option 1)
Helping a human manage their existing account	Ask the human to create an API key for you (Option 2)
Working within a human's org with your own identity	Create an agent account, have the human invite you (Option 3)
Building something to hand off to a human	Create an agent account, build it, then transfer the org (Option 1)
Signing in without sending a password through the agent	Browser-based PKCE login (Option 4)

Credit limits by account type: Agent accounts (Options 1, 3) can transfer orgs to humans when credits run out -- see Ownership Transfer in section 3. Human accounts (Option 2) cannot use the transfer/claim API; direct the human to upgrade their plan at https://go.fast.io/settings/billing or via org action billing-create.

Standard Sign-In Flow

1. Call auth with action signin, email and password.
2. The server returns a JWT auth_token and stores it in the session automatically.
3. All subsequent tool calls use this token without any manual passing.

Agent Account Creation

When creating a new account (Options 1 and 3 above), agents MUST use auth action signup which automatically registers with agent=true. Never sign up as a human account. Agent accounts provide:

• account_type set to "agent"
• Free agent plan assigned automatically
• Transfer/claim workflow enabled for handing orgs off to humans

Steps:

1. Optionally call auth action email-check with the desired email to verify it is available for registration before attempting signup.
2. Call auth action signup with first_name, last_name, email, and password. The agent=true flag is sent automatically by the MCP server.
3. The account is created and a session is established automatically -- the agent is signed in immediately.
4. Verify your email (required before using most endpoints): Call auth action email-verify with email to send a verification code, then call auth action email-verify again with email and email_token to validate the code.
5. No credit card is required. No trial period. No expiration. The account persists indefinitely.

Two-Factor Authentication Flow

1. Call auth action signin with email and password.
2. If the response includes two_factor_required: true, the returned token has limited scope.
3. Call auth action 2fa-verify with the 2FA code (TOTP, SMS, or WhatsApp).
4. The server replaces the limited-scope token with a full-scope token automatically.

Browser Login (PKCE) Flow

1. Call auth action pkce-login (optionally with email to pre-fill the sign-in form, scope_type to request scoped access, and agent_name to identify the agent).
2. The tool returns a login_url -- present it to the user to open in a browser.
3. The user signs in (email/password or SSO).
4. The user sees the approval screen showing the agent_name (or client name if not provided). Depending on scope_type: for user they simply approve; for org/workspace they select specific entities and read-only/read-write access; for all_orgs/all_workspaces/all_shares they review the wildcard access summary.
5. The user clicks Approve. The browser displays an authorization code. The user copies it.
6. Call auth action pkce-complete with the code to exchange it for an access token.
7. The session is established automatically -- all subsequent tool calls are authenticated. If scoped access was granted, scopes and agent_name are included in the response and stored in the session.

Checking Session Status

• auth action status -- checks the local Durable Object session. No API call is made. Returns authentication state, user ID, email, token expiry, scopes, and agent_name.
• auth action check -- validates the token against the Fast.io API. Returns the user ID if the token is still valid.

Session Expiry

JWT tokens last 1 hour. API keys (used when assisting a human) do not expire unless revoked. When a JWT session expires, tool calls return a clear error indicating that re-authentication is needed. Call auth action signin again to establish a new session. The MCP server does not auto-refresh tokens.

Tip: For long-running sessions, use auth action status to check remaining token lifetime before starting a multi-step workflow. If the token is close to expiring, re-authenticate first to avoid mid-workflow interruptions.

Signing Out

Call auth action signout to clear the stored session from the Durable Object.

---

3. Core Concepts

Organizations

Organizations are top-level containers that collect workspaces. An organization can represent a company, a business unit, a team, or simply your own personal collection. Every user belongs to one or more organizations. Organizations have:

• Workspaces — the file storage containers that belong to the organization.
• Members with roles: owner, admin, member, guest, view.
• Billing and subscriptions managed through Stripe integration.
• Plan limits that govern storage, transfer, AI tokens, and member counts.

Organizations are identified by a 19-digit numeric profile ID or a domain string.

IMPORTANT: When creating orgs, agents MUST use org action create which automatically assigns billing_plan: "agent". This ensures the org gets the free agent plan (50 GB, 5,000 credits/month). Do not use any other billing plan for agent-created organizations.

Org Discovery (IMPORTANT)

To discover all available orgs, agents must call both actions:

1. org action list -- returns internal orgs where you are a direct member (member: true)
2. org action discover-external -- returns external orgs you access via workspace membership only (member: false)

An agent that only checks org action list will miss external orgs entirely and won't discover the workspaces it's been invited to. External orgs are the most common pattern when a human invites an agent to help with a specific project -- they add the agent to a workspace but not to the org itself.

Internal vs External Orgs

Internal orgs (member: true) -- orgs you created or were invited to join as a member. You have org-level access: you can see all workspaces (subject to permissions), manage settings if you're an admin, and appear in the org's member list.

External orgs (member: false) -- orgs you can access only through workspace membership. You can see the org's name and basic public info, but you cannot manage org settings, see other workspaces, or add members at the org level. Your access is limited to the specific workspaces you were explicitly invited to.

Example: A human invites your agent to their "Q4 Reports" workspace. You can upload files, run AI queries, and collaborate in that workspace. But you cannot create new workspaces in their org, view their billing, or access their other workspaces. The org shows up via org action discover-external -- not org action list. If the human later invites you to the org itself, the org moves from external to internal.

Workspaces

Workspaces are file storage containers within organizations. Each workspace has:

• Its own set of members with roles (owner, admin, member, guest).
• A storage tree of files and folders (storage nodes).
• Optional AI features for RAG-powered chat.
• Shares that can be created within the workspace.
• Archive/unarchive lifecycle management.
• 50 GB included storage on the free agent plan, with files up to 1 GB per upload.
• File versioning -- every edit creates a new version, old versions are recoverable.
• Full-text and semantic search -- find files by name or content, and documents by meaning.

Workspaces are identified by a 19-digit numeric profile ID.

Intelligence: On or Off

Workspaces have an intelligence toggle that controls whether AI features are active:

Intelligence OFF -- the workspace is pure file storage. You can still attach files directly to an AI chat conversation (up to 20 files, 200 MB total), but files are not persistently indexed. This is fine for simple storage and sharing where you do not need to query your content.

Intelligence ON -- the workspace becomes an AI-powered knowledge base. Every document and code file uploaded is automatically ingested, summarized, and indexed for RAG. This enables:

• RAG (retrieval-augmented generation) -- scope AI chat to entire folders or the full workspace and ask questions across your indexed documents and code. The AI retrieves relevant passages and answers with citations.
• Semantic search -- find files by meaning, not just keywords. "Show me contracts with indemnity clauses" works even if those exact words do not appear in the filename.
• Auto-summarization -- short and long summaries generated for every indexed document and code file, searchable and visible in the UI.
• Metadata extraction -- AI pulls key metadata from documents automatically.

Coming soon: RAG indexing support for images, video, and audio files. Currently only documents and code are indexed.

Intelligence defaults to ON for workspaces created via the API by agent accounts. If the workspace is only used for file storage and sharing, disable it to conserve credits. If you need to query your content, leave it enabled.

Agent use case: Create a workspace per project or client. Enable intelligence if you need to query the content later. Upload reports, datasets, and deliverables. Invite other agents and human stakeholders. Everything is organized, searchable, and versioned.

For full details on AI chat types, file context modes, AI state, and how intelligence affects them, see the AI Chat section below.

Shares

Shares are purpose-built spaces for exchanging files with people outside your workspace. They can exist within workspaces and have three types:

Mode	What It Does	Agent Use Case
Send	Recipients can download files	Deliver reports, exports, generated content
Receive	Recipients can upload files	Collect documents, datasets, user submissions
Exchange	Both upload and download	Collaborative workflows, review cycles

Share Features

• Password protection -- require a password for link access
• Expiration dates -- shares auto-expire after a set period
• Download controls -- enable or disable file downloads
• Access levels -- Members Only, Org Members, Registered Users, or Public (anyone with the link)
• Custom branding -- background images, gradient colors, accent colors, logos
• Post-download messaging -- show custom messages and links after download
• Up to 3 custom links per share for context or calls-to-action
• Guest chat -- let share recipients ask questions in real-time
• AI-powered auto-titling -- shares automatically generate smart titles from their contents
• Activity notifications -- get notified when files are sent or received
• Comment controls -- configure who can see and post comments (owners, guests, or both)

Two Storage Modes

When creating a share with share action create, the storage_mode parameter determines how files are stored:

• room (independent storage, default) -- The share has its own isolated storage. Files are added directly to the share and are independent of any workspace. This creates a self-contained data room -- changes to workspace files do not affect the room, and vice versa. Use for final deliverables, compliance packages, archived reports, or any scenario where you want an immutable snapshot.

• shared_folder (workspace-backed) -- The share is backed by a specific folder in a workspace. The share displays the live contents of that folder -- any files added, updated, or removed in the workspace folder are immediately reflected in the share. No file duplication, so no extra storage cost. To create a shared folder, pass storage_mode=shared_folder and folder_node_id={folder_opaque_id} when creating the share. Note: Expiration dates are not allowed on shared folder shares since the content is live.

Both modes look the same to share recipients -- a branded data room with file preview, download controls, and all share features. The difference is whether the content is a snapshot (room) or a live view (shared folder).

Shares are identified by a 19-digit numeric profile ID.

Agent use case: Generate a quarterly report, create a Send share with your client's branding, set a 30-day expiration, and share the link. The client sees a professional, branded page with instant file preview -- not a raw download link.

Storage Nodes

Files and folders are represented as storage nodes. Each node has an opaque ID (a 30-character alphanumeric string, displayed with hyphens, e.g. f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4). The special value root refers to the root folder of a workspace or share, and trash refers to the trash folder.

Key operations on storage nodes: list, create-folder, move, copy, rename, delete (moves to trash), purge (permanently deletes), restore (recovers from trash), search, add-file (link an upload), and add-link (create a share reference).

Nodes have versions. Each file modification creates a new version. Version history can be listed and files can be restored to previous versions.

Notes

Notes are a storage node type (alongside files and folders) that store markdown content directly on the server. They live in the same folder hierarchy as files, are versioned like any other node, and appear in storage listings with type: "note".

Creating and Updating Notes

Create notes with workspace action create-note and update with workspace action update-note.

Creating: Provide workspace_id, parent_id (folder opaque ID or "root"), name (must end in .md, max 100 characters), and content (markdown text, max 100 KB).

Updating: Provide workspace_id, node_id, and at least one of name (must end in .md) or content (max 100 KB).

Constraint	Limit
Content encoding	Valid UTF-8 (UTF8MB4). Invalid byte sequences and control characters (\p{C} except \t, \n, \r) are stripped.
Content size	100 KB max
Filename	1-100 characters, must end in .md
Markdown validation	Code blocks and emphasis markers must be balanced
Rate limit	2 per 10s, 5 per 60s

Notes as Long-Term Knowledge Grounding

In an intelligent workspace, notes are automatically ingested and indexed just like uploaded documents. This makes notes a way to bank knowledge over time -- any facts, context, or decisions stored in notes become grounding material for future AI queries.

When an AI chat uses folder scope (or defaults to the entire workspace), notes within that scope are searched alongside files. The AI retrieves relevant passages from notes and cites them in answers.

Key behaviors:

• Notes are ingested for RAG when workspace intelligence is enabled
• Notes within a folder scope are included in scoped queries
• Notes with ai_state: ready are searchable via RAG
• Notes can also be attached directly to a chat via files_attach (check ai.attach is true in storage details)

Use cases:

• Store project context, decisions, and rationale. Months later, ask "Why did we choose vendor X?" and the AI retrieves the note.
• Save research findings in a note. Future AI chats automatically use those findings as grounding.
• Create reference documents (style guides, naming conventions) that inform all future AI queries in the workspace.

Other Note Operations

Notes support the same storage operations as files and folders: move (via storage action move), copy (storage action copy), delete/trash (storage action delete), restore (storage action restore), version history (storage action version-list), and details (storage action details).

Linking Users to Notes

• Note in workspace context (opens workspace with note panel): https://{domain}.fast.io/workspace/{folder_name}/storage/root?note={note_id}
• Note preview (standalone view): https://{domain}.fast.io/workspace/{folder_name}/preview/{note_id}

AI Chat

AI chat lets agents ask questions about files stored in workspaces and shares. Two chat types are available, each with different file context options.

AI chat is read-only. It can read, analyze, search, and answer questions about file contents, but it cannot modify files, change workspace settings, manage members, or access events. Any action beyond reading file content — uploading, deleting, moving files, changing settings, managing shares, reading events — must be done through the MCP tools directly. Do not attempt to use AI chat as a general-purpose tool for workspace management.

Two Chat Types

• chat — Basic AI conversation with no file context from the workspace index. Use for general questions only.
• chat_with_files — AI grounded in your files. Two mutually exclusive modes for providing file context:
  • Folder/file scope (RAG) — limits the retrieval search space. Requires intelligence enabled; files must be in ready AI state.
  • File attachments — files read directly by the AI. No intelligence required; files must have ai.attach: true in storage details (the file must be a supported type for AI analysis). Max 20 files, 200 MB total.

Both types augment answers with web knowledge when relevant.

File Context: Scope vs Attachments

For chat_with_files, choose one of these mutually exclusive approaches:

Feature	Folder/File Scope (RAG)	File Attachments
How it works	Limits RAG search space	Files read directly by AI
Requires intelligence	Yes	No
File readiness requirement	ai_state: ready	ai.attach: true
Best for	Many files, knowledge retrieval	Specific files, direct analysis
Max references	100 folder refs (subfolder tree expansion) or 100 file refs	20 files / 200 MB
Default (no scope given)	Entire workspace	N/A

Scope parameters (REQUIRES intelligence — will error if intelligence is off):

• folders_scope — comma-separated nodeId:depth pairs (depth 1-10, max 100 subfolder refs). Defines a search boundary — the RAG backend finds documents within scoped folders automatically. Just pass folder IDs with depth; do not enumerate individual files. A folder with thousands of files and few subfolders works fine.
• files_scope — comma-separated nodeId:versionId pairs (max 100). Limits RAG to specific indexed files. Both nodeId AND versionId are required and must be non-empty — get versionId from the file's version field in storage action list or details responses.
• If neither is specified, the default scope is the entire workspace (all indexed documents). This is the recommended default — omit scope parameters unless you specifically need to narrow the search.

Attachment parameter (no intelligence required):

• files_attach — comma-separated nodeId:versionId pairs (max 20, 200 MB total). Both nodeId AND versionId are required and must be non-empty. Files are read directly, not via RAG. FILES ONLY: passing a folder nodeId returns a 406 error. To include folder contents in AI context, use folders_scope instead (requires intelligence). Only files with ai.attach: true in storage details can be attached — check before using.

Do not list folder contents and pass individual file IDs as files_scope when you mean to search a folder — use folders_scope with the folder's nodeId instead. files_scope is only for targeting specific known file versions.

Scope vs attach: files_scope and folders_scope narrow the RAG search boundary and require workspace intelligence to be enabled — they will error on non-intelligent workspaces. files_attach sends files directly to the AI without indexing and works regardless of intelligence setting, but accepts only file nodeIds (not folders).

files_scope/folders_scope and files_attach are mutually exclusive — sending both will error.

Intelligence and AI State

The workspace intelligence toggle (see Workspaces above) controls whether uploaded documents and code files are auto-ingested, summarized, and indexed for RAG. When intelligence is enabled, each file has an ai_state indicating its readiness:

State	Meaning
disabled	AI processing disabled for this file
pending	Queued for processing
in_progress	Currently being ingested and indexed
ready	Complete — available for folder/file scope queries
failed	Processing failed

Only files with ai_state: ready are included in folder/file scope searches. Check file state via storage action details with context_type: "workspace".

Attachability — the ai.attach Flag

File nodes in storage list/details responses include an ai object with three fields:

Field	Type	Meaning
ai.state	string	AI indexing state (disabled, pending, inprogress, ready, failed)
ai.attach	boolean	Whether the file can be used with files_attach
ai.summary	boolean	Whether the file already has an AI-generated summary

Before using files_attach, check that ai.attach is true. A file is attachable when its type supports AI analysis (documents, code, images, PDFs, spreadsheets, etc.) or when it already has a summary from prior processing. Files with ai.attach: false (unsupported formats, corrupt files, or files still processing) will be rejected by the API.

This flag is independent of the workspace intelligence setting — a file can have ai.attach: true even when intelligence is off.

When to enable intelligence: You need scoped RAG queries, cross-file search, auto-summarization, or a persistent knowledge base.

When to disable intelligence: The workspace is for storage/sharing only, or you only need to analyze specific files via attachments. Saves credits (ingestion costs 10 credits/page).

Even with intelligence off, chat_with_files with file attachments still works for files with ai.attach: true.

How to Phrase Questions

With folder/file scope (RAG): Write questions likely to match content in indexed files. The AI searches the scope, retrieves passages, and cites them.

• Good: "What are the payment terms in the vendor contracts?"
• Good: "Summarize the key findings from the Q3 analysis reports"
• Bad: "Tell me about these files" — too vague, no specific content to match
• Bad: "What's in this workspace?" — cannot meaningfully search for "everything"

With file attachments: Be direct — the AI reads the full file content. No retrieval step.

• "Describe this image in detail"
• "Extract all dates and amounts from this invoice"
• "Convert this CSV data into a summary table"

Personality: The personality parameter controls the tone and length of AI responses. Pass it when creating a chat or sending a message:

• concise — short, brief answers
• detailed — comprehensive answers with context and evidence (default)

Use concise when you need a quick fact, a yes/no answer, or a brief summary. Use detailed (or omit the parameter) when you need thorough analysis with supporting evidence and citations. The personality can also be overridden per follow-up message.

Controlling verbosity in questions: You can also guide verbosity through how you phrase the question itself:

• "In one sentence, what is the main conclusion of this report?"
• "List only the file names that mention GDPR compliance, no explanations"
• "Give me a brief summary — 2-3 bullet points max"

Combining personality: "concise" with a direct question produces the shortest answers and uses the fewest AI credits.

Chat Parameters

Create a chat with ai action chat-create (with context_type: "workspace") or ai action chat-create (with context_type: "share"):

• type (required) — chat or chat_with_files
• query_text (required for workspace, optional for share) — initial message, 2-12,768 characters
• personality (optional) — concise or detailed (default: detailed)
• privacy (optional) — private or public (default: public)
• files_scope (optional) — nodeId:versionId,... (max 100, requires chat_with_files + intelligence). Both parts required and non-empty. Omit to search all indexed documents (recommended default).
• folders_scope (optional) — nodeId:depth,... (depth 1-10, max 100 subfolder refs, requires chat_with_files + intelligence). Folder scope = search boundary, not file enumeration. Omit to search all indexed documents (recommended default).
• files_attach (optional) — nodeId:versionId,... (max 20 / 200 MB, both parts required and non-empty, mutually exclusive with scope params)

Follow-up Messages

Send follow-ups with ai action message-send (with context_type: "workspace" or "share"). The chat type is inherited from the parent chat. Each follow-up can update the scope, attachment, and personality parameters.

Waiting for AI Responses

After creating a chat or sending a message, the AI response is asynchronous. Message states progress: ready → in_progress → complete (or errored).

Recommended: Call ai action message-read (with context_type: "workspace" or "share") with the returned message_id. The tool polls automatically (up to 15 attempts, 2-second intervals, ~30 seconds). If the response is still processing after that window, use event action activity-poll with the workspace/share ID instead of calling the read action in a loop — see Activity Polling in section 7.

Response Citations

Completed AI responses include citations pointing to source files:

• nodeId — storage node opaque ID
• versionId — file version opaque ID
• entries[].page — page number
• entries[].snippet — text excerpt
• entries[].timestamp — audio/video timestamp

Linking Users to AI Chats

Append ?chat={chat_opaque_id} to the workspace storage URL:

https://{domain}.fast.io/workspace/{folder_name}/storage/root?chat={chat_id}

Share AI Chats

Shares support AI chat with identical capabilities. All workspace AI endpoints have share equivalents accessible via ai actions with context_type: "share".

AI Share / Export

Generate temporary markdown-formatted download URLs for files that can be pasted into external AI tools (ChatGPT, Claude, etc.). Use ai action share-generate (with context_type: "workspace" or "share"). URLs expire after 5 minutes. Limits: 25 files maximum, 50 MB per file, 100 MB total.

Profile IDs

Organizations, workspaces, and shares are all identified by 19-digit numeric profile IDs. These appear throughout the tool parameters as workspace_id, share_id, org_id, profile_id, and member_id.

Most endpoints also accept custom names as identifiers:

Profile Type	Numeric ID	Custom Name
Workspace	19-digit ID	Folder name (e.g., my-project)
Share	19-digit ID	URL name (e.g., q4-financials)
Organization	19-digit ID	Domain name (e.g., acme)
User	19-digit ID	Email address (e.g., [e-mail])

QuickShares

QuickShares are temporary public download links for individual files in workspaces (not available for shares). They can be accessed without authentication. Expires in seconds from creation (default 10,800 = 3 hours, max 86,400 = 24 hours). Max file size: 1 GB. Each quickshare has an opaque identifier used to retrieve metadata and download the file.

File Preview

Files uploaded to Fast.io get automatic preview generation. When humans open a share or workspace, they see the content immediately -- no "download and open in another app" friction.

Supported preview formats:

• Images -- full-resolution with auto-rotation and zoom
• Video -- HLS adaptive streaming (50--60% faster load than raw video)
• Audio -- interactive waveform visualization
• PDF -- page navigation, zoom, text selection
• Spreadsheets -- grid navigation with multi-sheet support
• Code and text -- syntax highlighting, markdown rendering

Use storage action preview-url (with context_type: "workspace" or "share") to generate preview URLs. Use storage action preview-transform (with context_type: "workspace" or "share") for image resize, crop, and format conversion.

Agent use case: Your generated PDF report does not just appear as a download link. The human sees it rendered inline, can flip through pages, zoom in, and comment on specific sections -- all without leaving the browser.

Comments and Annotations

Humans and agents can leave feedback directly on files, anchored to specific content using the reference parameter:

• Image comments -- anchored to spatial regions (normalized x/y/width/height coordinates)
• Video comments -- anchored to timestamps with spatial region selection
• Audio comments -- anchored to timestamps or time ranges
• PDF comments -- anchored to specific pages with optional text snippet selection
• Threaded replies -- single-level threading only; replies to replies are auto-flattened to the parent
• Emoji reactions -- one reaction per user per comment; adding a new reaction replaces the previous one
• Mention tags -- reference users and files inline using bracket syntax: @[profile:id], @[user:opaqueId:Display Name], @[file:fileId:filename.ext]. Get IDs from member lists, user details, or storage listings. The display name segment is optional for profile tags but recommended for user and file tags

Comments use JSON request bodies (Content-Type: application/json), unlike most other endpoints which use form-encoded data.

Listing comments: Use comment action list for per-file comments and comment action list-all for all comments across a workspace or share. Both support sort, limit (2-200), offset, include_deleted, reference_type filter, and include_total.

Adding comments: Use comment action add with profile_type, profile_id, node_id, and text. Optionally include parent_comment_id for replies and reference to anchor to a specific position. Supports mention tags in the body. Two character limits apply: total body including tags max 8,192 chars, display text (body with @[...] tags stripped) max 2,048 chars.

Deleting comments: comment action delete is recursive -- deleting a parent also removes all replies. comment action bulk-delete is NOT recursive -- replies to deleted comments are preserved.

Linking users to comments: The preview URL opens the comments sidebar automatically. Deep link query parameters let you target a specific comment or position:

Parameter	Format	Purpose
?comment={id}	Comment opaque ID	Scrolls to and highlights a specific comment for 2 seconds
?t={seconds}	e.g. ?t=45.5	Seeks to timestamp for audio/video comments
?p={pageNum}	e.g. ?p=3	Navigates to page for PDF comments

Workspace: https://{org.domain}.fast.io/workspace/{folder_name}/preview/{file_opaque_id}?comment={comment_id}

Share: https://go.fast.io/shared/{custom_name}/{title-slug}/preview/{file_opaque_id}?comment={comment_id}

Parameters can be combined -- e.g. ?comment={id}&t=45.5 to deep link to a video comment at a specific timestamp. In shares, the comments sidebar only opens if the share has comments enabled.

Agent use case: You generate a design mockup. The human comments "Change the header color" on a specific region of the image. You read the comment, see exactly what region they are referring to via the reference.region coordinates, and regenerate.

URL Import

Agents can import files directly from URLs without downloading them locally first. Fast.io's server fetches the file, processes it, and adds it to your workspace or share.

• Supports any HTTP/HTTPS URL
• Supports OAuth-protected sources: Google Drive, OneDrive, Dropbox
• Files go through the same processing pipeline (preview generation, AI indexing if intelligence is enabled, virus scanning)

Use upload action web-import with the source URL, target profile, and parent node ID. Use upload action web-status to check progress and upload action web-list to list active import jobs.

Agent use case: A user says "Add this Google Doc to the project." You call upload action web-import with the URL. Fast.io downloads it server-side, generates previews, indexes it for AI, and it appears in the workspace. No local I/O.

Metadata

Metadata enables structured data annotation on files within workspaces. The system uses a template-based approach: administrators create templates that define the fields (name, type, constraints), then assign a template to the workspace. Files can then have metadata values set against the template fields.

Key points:

• One template per workspace -- each workspace supports at most one assigned metadata template at a time.
• Template categories -- legal, financial, business, medical, technical, engineering, insurance, educational, multimedia, hr.
• Field types -- string, int, float, bool, json, url, datetime -- each with optional constraints (min, max, default, fixed_list, can_be_null).
• Two metadata types -- template metadata conforms to template field definitions; custom metadata is freeform key-value pairs not tied to any template.
• System templates -- pre-built templates that are automatically cloned when assigned to a workspace, so customizations do not affect the global definition.
• AI extraction -- the extract action uses AI to analyze file content and automatically populate metadata fields. Extracted values are flagged with is_auto: true. Consumes AI credits.
• Version history -- metadata changes are tracked with version snapshots, accessible via the versions action.
• Requires billing feature -- the organization must have the metadata billing feature enabled.
• Template IDs are alphanumeric strings prefixed with mt_ (e.g. mt_abc123def456).

Ownership Transfer

The primary way agents deliver value: build something, then give it to a human. Also the recommended action when the agent plan runs out of credits and API calls start returning 402 Payment Required -- transfer the org to a human who can upgrade to a paid plan.

IMPORTANT: Account type restriction. The transfer/claim workflow (org actions transfer-token-create, transfer-token-list, transfer-token-delete, transfer-claim) is only available when the agent created an agent account (via auth action signup) and that agent account owns the org. If the agent is signed in with a human account (via auth action signin), the transfer/claim API cannot be used. Human-owned orgs must be upgraded directly by the human through the Fast.io dashboard.

The flow:

1. Agent creates an agent account with auth action signup and an org with org action create, sets up workspaces with org action create-workspace, uploads files, configures shares
2. Agent generates a transfer token (valid 72 hours) with org action transfer-token-create
3. Agent sends the claim URL to the human: https://go.fast.io/claim?token=<token>
4. Human clicks the link and claims the org with their account

When to transfer:

• The org is ready for human use (workspaces configured, files uploaded, shares set up)
• The agent plan runs out of credits (402 Payment Required) -- transfer so the human can upgrade
• The human explicitly asks to take over the org

Managing transfer tokens:

• org action transfer-token-list -- check for existing pending tokens before creating new ones
• org action transfer-token-delete -- revoke a token if the transfer is no longer needed
• org action transfer-claim -- claim an org using a token (used by the receiving human's agent)

What happens after transfer:

• Human becomes the owner of the org and all workspaces
• Agent retains admin access (can still manage files and shares)
• Human gets a free plan (credit-based, no trial period)
• Human can upgrade to Pro or Business at any time

Agent use case: A user says "Set up a project workspace for my team." You create the org, build out the workspace structure, upload templates, configure shares for client deliverables, invite team members -- then transfer ownership. The human walks into a fully configured platform. You stay on as admin to keep managing things.

402 Payment Required use case (agent account): While working, the agent hits credit limits. Call org action transfer-token-create, send the claim URL to the human, and explain they can upgrade to continue. The agent keeps admin access and resumes work once the human upgrades.

402 Payment Required use case (human account): The agent cannot transfer the org. Instead, inform the user that their org has run out of credits and they need to upgrade their billing plan. Direct them to the Fast.io dashboard or use org action billing-create to update to a paid plan.

Workflow (Tasks, Worklogs, Approvals, Todos)

Workspaces and shares support an optional workflow layer that adds structured task management, activity logging, approval gates, and simple checklists. Workflow features are controlled by a toggle -- they must be explicitly enabled before use.

Enabling Workflow

• Workspaces: workspace action enable-workflow with workspace_id
• Shares: share action enable-workflow with share_id

Check whether workflow is enabled via workspace action details or share action details -- look for workflow: true in the response.

Disabling workflow (workspace action disable-workflow or share action disable-workflow) makes all workflow data inaccessible but preserves it. Re-enabling restores access.

Task Lists and Tasks

Tasks are organized into lists. Each workspace or share can have multiple task lists, and each list contains individual tasks.

• Task lists have a name and optional description. Create with task action create-list, list with task action list-lists.
• Tasks have a title, description, status, priority, assignee, dependencies, and optional node link. Create with task action create-task, list with task action list-tasks.
• Statuses: pending, in_progress, complete, blocked
• Priorities: 0 = none, 1 = low, 2 = medium, 3 = high, 4 = critical
• Assignees are profile IDs (workspace or share members). Use task action assign-task to assign or unassign.
• Bulk operations: task action bulk-status changes status on up to 100 tasks at once.
• Markdown output: Pass format: "md" to get human-readable markdown instead of JSON.

Worklogs

Worklogs are append-only chronological activity logs scoped to tasks, task lists, storage nodes, or profiles. Entries cannot be edited or deleted after creation.

• Entries: Regular log entries appended with worklog action append. Use for progress updates, decisions, reasoning, and status changes.
• Interjections: Priority corrections created with worklog action interject. Interjections are always urgent and require acknowledgement from other participants.
• Acknowledgement: worklog action acknowledge marks an interjection as seen. worklog action unacknowledged lists interjections that still need acknowledgement.
• Markdown output: Pass format: "md" for human-readable output.

Approvals

Formal approval requests scoped to tasks, storage nodes, or worklog entries. Use when a decision requires explicit sign-off.

• Create: approval action create with profile_id, description (1-5000 chars), entity_type ("task", "node", or "worklog_entry"), and optionally approver_id (a single profile ID, must be an entity member).
• Resolve: approval action resolve with resolve_action: "approve" or "reject" and an optional comment. Only designated approvers can resolve.
• Statuses: pending, approved, rejected
• Markdown output: Pass format: "md" for human-readable output.

Todos

Simple flat checklists scoped to workspaces and shares. No nesting -- just a list of items that can be checked off.

• Create: todo action create with a title.
• Toggle: todo action toggle flips the done state of a single todo. todo action bulk-toggle sets done state on up to 100 todos at once.
• Update/Delete: todo action update changes title. todo action delete soft-deletes a todo.
• Markdown output: Pass format: "md" for human-readable output.

Notes as Agent Knowledge Layer

Notes (type: "note") are markdown files stored in workspace storage (see Notes above). When combined with workflow features, notes become a knowledge layer:

• Automatic AI indexing: When workspace intelligence is enabled, notes are ingested and indexed for RAG just like uploaded files.
• Link tasks to notes: Tasks can reference storage nodes, including notes. Create context notes for project background, requirements, or reference material, then create tasks that link to those notes for full context.
• Worklogs for reasoning: Use worklog entries to record decisions, progress, and reasoning over time. The chronological log builds a narrative that complements the structured task list.
• AI can search all context: With intelligence enabled, AI chat can search across notes, worklogs, task descriptions, and uploaded files -- giving comprehensive answers grounded in the project's full history.

Recommended pattern: Create notes for project context and requirements. Create task lists for work phases. Link tasks to relevant notes. Log progress with worklogs. Request approvals for decisions. The AI can then answer questions like "Why did we choose this approach?" by searching across all of these artifacts.

Permission Parameter Values

Several tools use permission parameters with specific allowed values. Use these exact strings when calling the tools.

Organization Creation (org action create)

Parameter	Allowed Values	Default
perm_member_manage	Owner only, Admin or above, Member or above	Member or above
industry	unspecified, technology, healthcare, financial, education, manufacturing, construction, professional, media, retail, real_estate, logistics, energy, automotive, agriculture, pharmaceutical, legal, government, non_profit, insurance, telecommunications, research, entertainment, architecture, consulting, marketing	unspecified
background_mode	stretched, fixed	stretched

Workspace Creation (org action create-workspace) and Update (workspace action update)

Parameter	Allowed Values	Default
perm_join	Only Org Owners, Admin or above, Member or above	Member or above
perm_member_manage	Admin or above, Member or above	Member or above

Share Creation (share action create)

Parameter	Allowed Values	Default
type	send, receive, exchange	exchange
storage_mode	independent, workspace_folder	independent
access_options	Only members of the Share or Workspace, Members of the Share, Workspace or Org, Anyone with a registered account, Anyone with the link	Only members of the Share or Workspace
invite	owners, guests	owners
notify	never, notify_on_file_received, notify_on_file_sent_or_received	never
display_type	list, grid	grid
intelligence	true, false	false
comments_enabled	true, false	true
download_enabled	true, false	true
guest_chat_enabled	true, false	false
workspace_style	true, false	true
background_image	-

Share constraints:

• Receive and Exchange shares cannot use Anyone with the link access -- this option is only available for Send shares.
• Password protection (password parameter) is only allowed when access_options is Anyone with the link.
• Expiration (expires parameter in MySQL format YYYY-MM-DD HH:MM:SS) is not allowed on workspace_folder shares.
• Field length and format constraints for custom_name, title, and description are documented in the Profile Field Constraints table below.
• Color parameters (accent_color, background_color1, background_color2) accept JSON strings.
• create_folder creates a new workspace folder for the share when used with storage_mode='workspace_folder'.

Profile Field Constraints

All profile fields are validated server-side. Requests that violate these constraints are rejected with a 400 error.

Entity	Field	API Key	Min	Max	Pattern	Required	Nullable
Org	domain	domain	2	80	^[a-z0-9]([-a-z0-9]{0,61}[a-z0-9])?$	Yes (create)	No
Org	name	name	3	100	No control chars	Yes	No
Org	description	description	10	1000	No control chars	No	Yes
Workspace	folder_name	folder_name	4	80	^[\p{L}\p{N}-]+$ (letters, digits, hyphens)	Yes (create)	No
Workspace	name	name	2	100	No control chars	Yes	No
Workspace	description	description	10	1000	No control chars	No	Yes
Share	custom_name	custom_name	4	80	^[\p{L}\p{N}]+$ (letters, digits only)	Yes (create)	No
Share	custom_url	custom_url	10	100	—	Yes	Yes
Share	title	title	2	80	No control chars	Yes	Yes
Share	description	description	10	500	No control chars	No	Yes

• "No control chars" = rejects Unicode control characters (\p{C})
• Org domain: lowercase ASCII alphanumeric + hyphens; cannot start/end with hyphen
• Workspace folder_name: Unicode letters, digits, and hyphens
• Share custom_name: Unicode letters and digits only (no hyphens or special chars)
• Share description max is 500 (org/workspace is 1000)

---

4. Agent Plan -- Free Tier

The agent plan is a free tier designed for AI agents. No credit card, no trial period, no expiration. Enough resources to build and demonstrate value, with room to grow when the org transfers to a human on a paid plan.

Resource Limits

Resource	Included
Price	$0 -- no credit card, no trial period, no expiration
Storage	50 GB
Max file size	1 GB
Monthly credits	5,000 (resets every 30 days)
Workspaces	5
Shares	50
Members per workspace	5
Share invitations	10 per share
Account auto-deletion	Never

Credit Costs

All platform activity consumes credits from the monthly 5,000 allowance:

Resource	Cost
Storage	100 credits/GB
Bandwidth	212 credits/GB
AI chat tokens	1 credit per 100 tokens
Document pages ingested	10 credits/page
Video ingested	5 credits/second
Audio ingested	0.5 credits/second
Images ingested	5 credits/image
File conversions	25 credits/conversion

When credits run out, the org enters a reduced-capability state and API calls return 402 Payment Required. The org is never deleted. Use org action limits to check current credit usage and remaining balance.

When you hit 402 or run low on credits:

• Agent account (created via auth action signup): Transfer the org to the human. Call org action transfer-token-create to generate a transfer token, then send the human the claim URL: https://go.fast.io/claim?token=<token>. Once they claim the org they can upgrade to a paid plan with unlimited credits. You retain admin access and can resume work immediately after the upgrade. This is the expected workflow -- agents build on the free plan, then hand off to humans who pay when they are ready.
• Human account (signed in via auth action signin): You cannot use the transfer/claim API. Tell the user they need to upgrade the org's billing plan directly. They can do this from the Fast.io dashboard or by calling org action billing-create to update their subscription to a paid plan.

After Transfer -- Human Plan Options

Once an agent transfers an org to a human, the human gets a free plan (credit-based, no trial period) and can upgrade:

Feature	Agent (Free)	Free (Human)	Pro	Business
Monthly credits	5,000	5,000	Unlimited	Unlimited
Storage	50 GB	50 GB	1 TB	5 TB
Max file size	1 GB	1 GB	25 GB	50 GB
Workspaces	5	5	10	1,000
Shares	50	50	1,000	50,000

The transfer flow is the primary way agents deliver value: set everything up on the free agent plan, then hand it off. The human upgrades when they are ready, and the agent retains admin access to keep managing things.

---

5. Tool Categories

The 19 tools use action-based routing. Each tool covers a specific area of the Fast.io platform and exposes multiple actions.

auth

Authentication, sign-in/sign-up, two-factor authentication, API key management, and OAuth session management. This is always the starting point for any agent interaction.

Actions: signin, signout, signup, check, session, status, set-api-key, email-check, email-verify, password-reset-request, password-reset, 2fa-verify, 2fa-status, 2fa-enable, 2fa-disable, 2fa-send, 2fa-verify-setup, pkce-login, pkce-complete, api-key-create, api-key-list, api-key-get, api-key-delete, oauth-list, oauth-details, oauth-revoke, oauth-revoke-all

user

Retrieve and update the current user profile, search for other users, manage invitations, upload and delete user assets (profile photos), check account eligibility, and list shares the user belongs to.

Actions: me, update, search, close, details-by-id, profiles, allowed, org-limits, list-shares, invitation-list, invitation-details, accept-all-invitations, asset-upload, asset-delete, asset-types, asset-list

org

Organization CRUD, member management, billing and subscription operations, workspace creation, invitation workflows, asset management (upload, delete), organization discovery, and ownership transfer.

Actions: list, details, create, update, close, public-details, limits, list-workspaces, list-shares, create-workspace, billing-plans, billing-create, billing-cancel, billing-details, billing-activate, billing-reset, billing-members, billing-meters, members, invite-member, remove-member, update-member-role, member-details, leave, transfer-ownership, join, invitations-list, invitation-update, invitation-delete, transfer-token-create, transfer-token-list, transfer-token-delete, transfer-claim, discover-all, discover-available, discover-check-domain, discover-external, asset-upload, asset-delete, asset-types, asset-list

workspace

Workspace-level settings, lifecycle operations (update, delete, archive, unarchive), listing and importing shares, managing workspace assets, workspace discovery, notes (create, update), quickshare management, metadata operations (template CRUD, assignment, file metadata get/set/delete, AI extraction), and workflow toggle (enable/disable tasks, worklogs, approvals, and todos).

Actions: list, details, update, delete, archive, unarchive, members, list-shares, import-share, available, check-name, create-note, update-note, quickshare-get, quickshare-delete, quickshares-list, metadata-template-create, metadata-template-delete, metadata-template-list, metadata-template-details, metadata-template-update, metadata-template-clone, metadata-template-assign, metadata-template-unassign, metadata-template-resolve, metadata-template-assignments, metadata-get, metadata-set, metadata-delete, metadata-extract, metadata-list-files, metadata-list-templates-in-use, metadata-versions, enable-workflow, disable-workflow

share

Share CRUD, public details, archiving, password authentication, asset management, share name availability checks, and workflow toggle (enable/disable tasks, worklogs, approvals, and todos).

Actions: list, details, create, update, delete, public-details, archive, unarchive, password-auth, members, available, check-name, quickshare-create, enable-workflow, disable-workflow

storage

File and folder operations within workspaces and shares. List, list recently modified files across all folders, create folders, move, copy, delete, rename, purge, restore, search, add files from uploads, add share links, transfer nodes, manage trash, version operations, file locking, and preview/transform URL generation. Requires context_type parameter (workspace or share).

Actions: list, recent, details, search, trash-list, create-folder, copy, move, delete, rename, purge, restore, add-file, add-link, transfer, version-list, version-restore, lock-acquire, lock-status, lock-release, preview-url, preview-transform

upload

File upload operations. Single-step text file upload, chunked upload lifecycle (create session, stage binary blobs, upload chunks as plain text / base64 / blob reference, finalize, check status, cancel), web imports from external URLs, upload limits and file extension restrictions, and session management.

Actions: create-session, chunk, finalize, status, cancel, list-sessions, cancel-all, chunk-status, chunk-delete, stage-blob, text-file, web-import, web-list, web-cancel, web-status, limits, extensions

download

Generate download URLs and ZIP archive URLs for workspace files, share files, and quickshare links. MCP tools cannot stream binary data -- these actions return URLs that can be opened in a browser or passed to download utilities. Requires context_type parameter (workspace or share) for file-url and zip-url actions. Responses include a resource_uri field (e.g. download://workspace/{id}/{node_id}) that MCP clients can use to read file content directly via MCP resources. Direct download URLs include ?error=html so errors render as human-readable HTML in browsers.

Actions: file-url, zip-url, quickshare-details

ai

AI-powered chat with RAG, semantic search, and document analysis in workspaces and shares. Create chats, send messages, read AI responses (with polling), list and manage chats, search indexed documents and code by meaning with relevance scores, publish private chats, generate AI share markdown, track AI token usage, and auto-title generation. Requires context_type parameter (workspace or share).

Actions: chat-create, chat-list, chat-details, chat-update, chat-delete, chat-publish, message-send, message-list, message-details, message-read, search, share-generate, transactions, autotitle

comment

Comments are scoped to {entity_type}/{parent_id}/{node_id} where entity_type is workspace or share, parent_id is the 19-digit profile ID, and node_id is the storage node opaque ID. List comments on files (per-node and profile-wide with sort/limit/offset/filter params), add comments with optional reference anchoring (image regions, video/audio timestamps, PDF pages with text selection), single-level threaded replies, recursive single delete, non-recursive bulk delete, get comment details, and emoji reactions (one per user per comment). Comments use JSON request bodies.

Actions: list, list-all, add, delete, bulk-delete, details, reaction-add, reaction-remove

event

Search the audit/event log with rich filtering by category, subcategory, and event name (see Event Filtering Reference in section 7 for the full taxonomy). Get AI-powered summaries of activity, retrieve full details for individual events, list recent activity, and long-poll for activity changes.

Actions: search, summarize, details, activity-list, activity-poll

member

Member management for organizations, workspaces, and shares. Add, remove, update roles, transfer ownership, leave, join, and join via invitation. Requires entity_type parameter (workspace or share).

Actions: add, remove, details, update, transfer-ownership, leave, join, join-invitation

invitation

Invitation management for organizations, workspaces, and shares. List invitations, list by state, update, and delete. Requires entity_type parameter (workspace or share).

Actions: list, list-by-state, update, delete

asset

Asset management (upload, delete, list, read) for organizations, workspaces, shares, and users. Requires entity_type parameter (org, workspace, share, or user).

Actions: upload, delete, types, list, read

task

Task list and task management for workspaces and shares. Create and manage task lists, then create tasks within them with statuses, priorities, assignees, and dependencies. Supports bulk status changes and markdown output. Requires workflow to be enabled on the target entity.

Actions: list-lists, create-list, list-details, update-list, delete-list, list-tasks, create-task, task-details, update-task, delete-task, change-status, assign-task, bulk-status

worklog

Activity log for tracking agent work. After uploads, task changes, share creation, or any significant action, log what you did and why — builds a searchable audit trail for humans and AI. Also create urgent interjections that require acknowledgement. Entries are append-only and permanent. Requires workflow to be enabled on the target entity.

Actions: append, list, interject, details, acknowledge, unacknowledged

approval

Formal approval requests scoped to tasks, storage nodes, or worklog entries. Create approval requests with designated approvers, then resolve them with approve or reject decisions. Requires workflow to be enabled on the target entity.

Actions: list, create, details, resolve

todo

Simple flat checklists scoped to workspaces and shares. Create, update, delete, and toggle completion state on individual todos or in bulk. No nesting. Requires workflow to be enabled on the target entity.

Actions: list, create, details, update, delete, toggle, bulk-toggle

apps

Interactive MCP App widget discovery and launching. List available widgets, get details for a specific widget, launch a widget with workspace or share context, and find widgets associated with a specific tool domain.

Actions: list, details, launch, get-tool-apps

---

6. Common Workflows

1. Create an Account and Sign In

See Choosing the Right Approach in section 2 for which option fits your scenario.

Option 1 -- Autonomous agent (new account):

1. Optionally call auth action email-check with the desired email to verify availability.
2. auth action signup with first_name, last_name, email, and password -- registers as an agent account (agent=true is sent automatically) and signs in immediately.
3. auth action email-verify with email -- sends a verification code. Then auth action email-verify with email and email_token -- validates the code. Required before using most endpoints.
4. org action create to create a new org on the agent plan, or org action list to check existing orgs.

Option 2 -- Assisting a human (API key):

1. The human creates an API key at https://go.fast.io/settings/api-keys and provides it to the agent.
2. Call auth action set-api-key with the API key. The key is validated against the API and stored in the session -- all subsequent tool calls are authenticated automatically. No account creation needed.
3. org action list and org action discover-external to discover all available organizations (see Org Discovery).

Option 3 -- Agent invited to a human's org:

1. Create an agent account with auth action signup (same as Option 1).
2. Have the human invite you via org action invite-member or member action add (with entity_type: "workspace").
3. Accept invitations with user action accept-all-invitations.
4. org action list and org action discover-external to discover all available orgs (see Org Discovery). If the human only invited you to a workspace (not the org), it will only appear via discover-external.

Returning users:

1. auth action signin with email and password.
2. If two_factor_required: true, call auth action 2fa-verify with the 2FA code.
3. org action list and org action discover-external to discover all available organizations (see Org Discovery).

2. Browse and Download a File

1. org action list and org action discover-external -- discover all available organizations (see Org Discovery). Note the org_id values.
2. org action list-workspaces with org_id -- get workspaces in the organization. Note the workspace_id values.
3. storage action list with context_type: "workspace", context_id (workspace ID), and node_id: "root" -- browse the root folder. Note the node_id values for files and subfolders.
4. storage action details with context_type: "workspace", context_id, and node_id -- get full details for a specific file (name, size, type, versions).
5. download action file-url with context_type: "workspace", context_id, and node_id -- get a temporary download URL with an embedded token. The response also includes a resource_uri (e.g. download://workspace/{id}/{node_id}) that MCP clients can use to read file content directly. Return the download URL to the user, or use the resource URI to read the file through MCP.

3. Upload a File to a Workspace

Text files (recommended): Use upload action text-file with profile_type: "workspace", profile_id, parent_node_id, filename, and content (plain text). This single action creates the session, uploads, finalizes, and polls until stored — returns new_file_id on success. Use this for code, markdown, CSV, JSON, config files, and any other text content.

Binary or large files (chunked flow):

1. upload action create-session with profile_type: "workspace", profile_id (the workspace ID), parent_node_id (target folder or "root"), filename, and filesize in bytes. Returns an upload_id, recommended_mcp_chunk_bytes (default 24576), and total_chunks — use these to split the file.
2. upload action chunk with upload_id, chunk_number (1-indexed), and chunk data. Split files into pieces of recommended_mcp_chunk_bytes (24 KB binary / ~32 KB base64) — even small files. Three options for passing data (provide exactly one):
   • content — for text (strings, code, JSON, etc.). Do NOT use data for text.
   • data — base64-encoded binary (≤32 KB per call). The simplest approach for binary uploads through MCP tool calls. Split the file and send each piece as a separate chunk.
   • blob_ref — blob ID from upload action stage-blob or POST /blob. Useful when pre-staging data or when using the HTTP blob endpoint from non-MCP clients. Blobs expire after 5 minutes and are consumed (deleted) on use. Repeat for each chunk. Wait for each chunk to return success before sending the next.
3. upload action finalize with upload_id -- triggers file assembly and polls until stored. Returns the final session state with status: "stored" or "complete" on success (including new_file_id), or throws on assembly failure. The file is automatically added to the target workspace and folder specified in step 1 -- no separate add-file call is needed.

Note: storage action add-file is only needed if you want to link the upload to a different location than the one specified during session creation.

4. Import a File from URL

Use this when you have a file URL (HTTP/HTTPS, Google Drive, OneDrive, Box, Dropbox) and want to add it to a workspace without downloading locally.

1. upload action web-import with url (the source URL), profile_type: "workspace", profile_id (the workspace ID), and parent_node_id (target folder or "root"). Returns an upload_id.
2. upload action web-status with upload_id -- check import progress. The server downloads the file, scans it, generates previews, and indexes it for AI (if intelligence is enabled).
3. The file appears in the workspace storage tree once the job completes.

5. Deliver Files to a Client

Create a branded, professional data room for outbound file delivery. This replaces raw download links, email attachments, and S3 presigned URLs.

1. Upload files to the workspace (see workflow 3 or 4).