{"id":"0831c455-2f3e-4a96-907d-798aed5efd60","entityType":"agent","slug":"clawhub-dbalve-fast-io","name":"Fast.io","canonicalUrl":"https://www.xpersona.co/agent/clawhub-dbalve-fast-io","canonicalPath":"/agent/clawhub-dbalve-fast-io","generatedAt":"2026-10-09T17:15:43.540Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":null},"description":"Workspaces for agentic teams. Complete agent guide with all 19 consolidated tools using action-based routing — parameters, workflows, ID formats, and constra...","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 3K downloads reported by the source. Last updated 4/15/2026.","installCommand":"clawhub skill install kn74d15nyw6rzrc3fekbs5333d80ha0y:fast-io","sourceUrl":"https://clawhub.ai/dbalve/fast-io","homepage":"https://clawhub.ai/dbalve/fast-io","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/dbalve/fast-io","kind":"source"}],"safetyScore":84,"overallRank":62,"popularityScore":63,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Fast.io technical dossier on Xpersona with source links, trust signals, and execution metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":"No protocol or capability metadata is available."},"protocols":[],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":0,"capabilityMatrix":{"rows":[],"flattenedTokens":""}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":null},"stars":null,"forks":null,"downloads":3012,"packageName":null,"latestVersion":"1.105.0","tractionLabel":"3K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-02-28T18:04:01.890Z","emptyReason":null},"lastUpdatedAt":"2026-04-15T00:45:39.800Z","lastCrawledAt":"2026-02-28T18:04:01.890Z","lastIndexedAt":null,"nextCrawlAt":"2026-03-01T18:04:01.890Z","lastVerifiedAt":null,"highlights":[{"version":"1.105.0","createdAt":"2026-02-26T23:38:17.549Z","changelog":"fast-io v1.94.2 → v1.105.0 - Updated version metadata in the manifest and agent guide to 1.105.0/1.104. - Refreshed the \"Last Updated\" date in documentation (now 2026-02-26). - No other user-visible changes noted.","fileCount":3,"zipByteSize":91517},{"version":"1.94.1","createdAt":"2026-02-23T20:43:31.090Z","changelog":"**Summary:** Major update introducing widget support, new resource types, and workflow changes. - Added support for interactive HTML5 app widgets, now discoverable and launchable via a new `widget://*` resource namespace and the `apps` tool. - MCP resources expanded to include app widget resources (5 widgets available). - MCP prompts added for app launching (Workspace Picker, File Picker, Workflow Manager, Exchange Setup, Quickshare). - Number of end-to-end workflows consolidated from 13 to 12. - Cloud import support removed from description and documentation. - Metadata version bumped from 1.84.0 to 1.94.0; guide, endpoints, and lists updated accordingly.","fileCount":3,"zipByteSize":88250},{"version":"1.84.0","createdAt":"2026-02-19T22:50:02.772Z","changelog":"- Added support for a new (19th) consolidated tool, expanding the API surface. - Introduced cloud import from external storage providers as a core platform feature. - Resource listing improvements: increased workspace/share coverage to 10 each and now list up to 25 recent root files per workspace/share. - Revised documentation to cover 13 end-to-end workflows (up from 12), cloud import, and refined tool/action details. - Description and guide updated to reflect new features, including real-time collaboration and expanded workflow primitives.","fileCount":null,"zipByteSize":null},{"version":"1.80.0","createdAt":"2026-02-18T23:30:24.955Z","changelog":"- Updated version from 1.73.0 to 1.80.0. - Added dynamic resource listing for workspace and share files; authenticated users can browse and discover files via resources/list, with results cached for 1 minute. - Clarified that only root-level files are listed via resources/list; subdirectory browsing requires the storage tool. - Resource list entries now include file name, workspace/share name, file size, and MIME type. - Improved SKILL.md version metadata and documentation to reflect new features.","fileCount":null,"zipByteSize":null},{"version":"1.73.0","createdAt":"2026-02-18T14:43:57.078Z","changelog":"**Fast-io 1.73.0 — Major update with expanded tools and workflow capabilities** - Increased number of consolidated tools from 14 to 18, covering the full Fast.io API surface. - Expanded the guide's coverage: now includes 12 end-to-end workflows (up from 10), with additional focus on workflow and collaboration primitives. - Added detailed support for workflow primitives: tasks, worklogs, approvals, and todos. - Increased the number of guided prompts for multi-step operations from 6 to 9. - Documentation and guide now reflect new capabilities, feature set, and tool parameters. - Updated agent plan, API, and workflow documentation for greater clarity and operational completeness.","fileCount":null,"zipByteSize":null},{"version":"1.68.0","createdAt":"2026-02-16T20:53:15.927Z","changelog":"## fast-io 1.68.0 Changelog - Updated the skill version and documentation from 1.64.x to 1.68.x. - Minor documentation update: clarified the \"Finding the right file in a large collection\" row to say \"Semantic search finds documents by meaning, not just filename.\" - Guide \"Last Updated\" and version number reflect new release date (2026-02-16). - No changes to code or functionality were detected.","fileCount":null,"zipByteSize":null},{"version":"1.64.0","createdAt":"2026-02-14T20:50:16.637Z","changelog":"fast-io 1.54.1 Changelog - No file changes detected in this release. - Only the version metadata was updated (from 1.54.0 to 1.64.0) in SKILL.md. - Documentation has been brought up to date to reflect the latest platform version.","fileCount":null,"zipByteSize":null},{"version":"1.54.0","createdAt":"2026-02-13T19:09:51.944Z","changelog":"- Expanded positioning from a cloud file management platform to \"workspaces for agentic teams,\" supporting collaboration between agents and humans. - Guide and platform documentation updated to version 1.54, with detailed coverage of team workspaces, agent collaboration, and activity feeds. - MCP resources now include session scopes and agent names in status, enabling richer authentication and agent identification. - New guided prompt for structured metadata workflows, including template creation, value setting, AI extraction, and metadata-based queries. - Description, overview, and problem/solution sections revised to emphasize real-time collaboration, shared workspaces, and agent-to-agent coordination. - All 14 consolidated tools, workflows, and platform documentation remain available under a free agent plan with 50 GB storage and 5,000 monthly credits.","fileCount":null,"zipByteSize":null}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install kn74d15nyw6rzrc3fekbs5333d80ha0y:fast-io","setupComplexity":"low","setupSteps":["Install using `clawhub skill install kn74d15nyw6rzrc3fekbs5333d80ha0y:fast-io` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/dbalve/fast-io before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-dbalve-fast-io/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-dbalve-fast-io/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-dbalve-fast-io/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-dbalve-fast-io/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-dbalve-fast-io/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-dbalve-fast-io/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":[]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-09T17:15:43.535Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-dbalve-fast-io/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-dbalve-fast-io/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-dbalve-fast-io/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-dbalve-fast-io/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":null},"readme":"Skill: Fast.io\n\nOwner: dbalve\n\nSummary: Workspaces for agentic teams. Complete agent guide with all 19 consolidated tools using action-based routing — parameters, workflows, ID formats, and constra...\n\nTags: ai-chat:1.15.0, collaboration:1.15.0, file-sharing:1.15.0, latest:1.105.0, latest cloud-storage:1.15.0, mcp:1.15.0, productivity:1.15.0, rag:1.15.0\n\nVersion history:\n\nv1.105.0 | 2026-02-26T23:38:17.549Z | user\n\nfast-io v1.94.2 → v1.105.0\n\n- Updated version metadata in the manifest and agent guide to 1.105.0/1.104.\n- Refreshed the \"Last Updated\" date in documentation (now 2026-02-26).\n- No other user-visible changes noted.\n\nv1.94.1 | 2026-02-23T20:43:31.090Z | user\n\n**Summary:** \nMajor update introducing widget support, new resource types, and workflow changes.\n\n- Added support for interactive HTML5 app widgets, now discoverable and launchable via a new `widget://*` resource namespace and the `apps` tool.\n- MCP resources expanded to include app widget resources (5 widgets available).\n- MCP prompts added for app launching (Workspace Picker, File Picker, Workflow Manager, Exchange Setup, Quickshare).\n- Number of end-to-end workflows consolidated from 13 to 12.\n- Cloud import support removed from description and documentation.\n- Metadata version bumped from 1.84.0 to 1.94.0; guide, endpoints, and lists updated accordingly.\n\nv1.84.0 | 2026-02-19T22:50:02.772Z | user\n\n- Added support for a new (19th) consolidated tool, expanding the API surface.\n- Introduced cloud import from external storage providers as a core platform feature.\n- Resource listing improvements: increased workspace/share coverage to 10 each and now list up to 25 recent root files per workspace/share.\n- Revised documentation to cover 13 end-to-end workflows (up from 12), cloud import, and refined tool/action details.\n- Description and guide updated to reflect new features, including real-time collaboration and expanded workflow primitives.\n\nv1.80.0 | 2026-02-18T23:30:24.955Z | user\n\n- Updated version from 1.73.0 to 1.80.0.\n- Added dynamic resource listing for workspace and share files; authenticated users can browse and discover files via resources/list, with results cached for 1 minute.\n- Clarified that only root-level files are listed via resources/list; subdirectory browsing requires the storage tool.\n- Resource list entries now include file name, workspace/share name, file size, and MIME type.\n- Improved SKILL.md version metadata and documentation to reflect new features.\n\nv1.73.0 | 2026-02-18T14:43:57.078Z | user\n\n**Fast-io 1.73.0 — Major update with expanded tools and workflow capabilities**\n\n- Increased number of consolidated tools from 14 to 18, covering the full Fast.io API surface.\n- Expanded the guide's coverage: now includes 12 end-to-end workflows (up from 10), with additional focus on workflow and collaboration primitives.\n- Added detailed support for workflow primitives: tasks, worklogs, approvals, and todos.\n- Increased the number of guided prompts for multi-step operations from 6 to 9.\n- Documentation and guide now reflect new capabilities, feature set, and tool parameters.\n- Updated agent plan, API, and workflow documentation for greater clarity and operational completeness.\n\nv1.68.0 | 2026-02-16T20:53:15.927Z | user\n\n## fast-io 1.68.0 Changelog\n\n- Updated the skill version and documentation from 1.64.x to 1.68.x.\n- Minor documentation update: clarified the \"Finding the right file in a large collection\" row to say \"Semantic search finds documents by meaning, not just filename.\"\n- Guide \"Last Updated\" and version number reflect new release date (2026-02-16).\n- No changes to code or functionality were detected.\n\nv1.64.0 | 2026-02-14T20:50:16.637Z | user\n\nfast-io 1.54.1 Changelog\n\n- No file changes detected in this release.\n- Only the version metadata was updated (from 1.54.0 to 1.64.0) in SKILL.md.\n- Documentation has been brought up to date to reflect the latest platform version.\n\nv1.54.0 | 2026-02-13T19:09:51.944Z | user\n\n- Expanded positioning from a cloud file management platform to \"workspaces for agentic teams,\" supporting collaboration between agents and humans.\n- Guide and platform documentation updated to version 1.54, with detailed coverage of team workspaces, agent collaboration, and activity feeds.\n- MCP resources now include session scopes and agent names in status, enabling richer authentication and agent identification.\n- New guided prompt for structured metadata workflows, including template creation, value setting, AI extraction, and metadata-based queries.\n- Description, overview, and problem/solution sections revised to emphasize real-time collaboration, shared workspaces, and agent-to-agent coordination.\n- All 14 consolidated tools, workflows, and platform documentation remain available under a free agent plan with 50 GB storage and 5,000 monthly credits.\n\nv1.43.0 | 2026-02-09T19:07:51.058Z | user\n\nNo user-facing changes in this release.\n\n- Version bumped from 1.41.0 to 1.43.0 in documentation only.\n- No file or functionality changes detected.\n\nv1.41.0 | 2026-02-08T19:21:25.503Z | user\n\n- Version updated to 1.41.0 with comprehensive guide refresh.\n- Agent guide now versioned \"1.41\", dated 2026-02-08.\n- Updated prompt list: prompts reduced from 8 to 5, focusing on onboarding, file addition, AI chat, agent-human comments, and activity catch-up.\n- Prompt descriptions revised for improved clarity and coverage of new authentication and collaboration workflows.\n- Metadata updated to reflect the new version.\n- No code or functional changes detected; documentation only.\n\nv1.39.1 | 2026-02-07T16:07:49.231Z | user\n\n**Major update: Migrated to consolidated toolset (action-based routing) and overhauled documentation.**\n\n- Reduced tool count from 258 to 14 by consolidating actions in each tool (action-based routing).\n- Updated documentation and workflows to reference the new consolidated actions instead of separate tools for each endpoint.\n- Improved descriptions of tool parameters, workflows, and authentication flows for clarity with the new architecture.\n- Updated versioning and resource references to track and document breaking changes moving forward.\n- Cleaned up obsolete, split tool references and detailed migration advice for developers.\n\nv1.39.0 | 2026-02-07T16:05:13.894Z | user\n\nfast-io 1.35.1\n\n- No file changes were detected in this version.\n- No user-facing updates or bug fixes are included.\n- Version bump only; functionality remains unchanged.\n\nv1.35.0 | 2026-02-06T17:37:06.618Z | user\n\nfast-io 1.31.1\n\n- Documentation updated to skill version 1.35.0 and platform capabilities as of 2026-02-06.\n- Clarified description and free agent plan: storage reduced to 50 GB (was 100 GB); number of tools adjusted to 258 (was 266).\n- Expanded and reorganized documentation: clearer guide to agent and human account options, key workflows, and how to use the platform.\n- Updated references to tool endpoints, authentication methods, and available features.\n- No code or logic changes; update is documentation only.\n\nv1.31.0 | 2026-02-06T14:01:56.267Z | user\n\nVersion 1.31.0 of fast-io\n\n- No file changes detected in this release.\n- Skill definition, description, features, and workflows remain unchanged from previous version.\n\nv1.30.1 | 2026-02-06T13:26:32.244Z | user\n\nfast-io 1.30.1\n\n- Updated agent guide reference: The complete guide (now covering 266 tools) is served directly by the MCP server at the /skill.md endpoint.\n- Toolset expanded from 257 to 266 available tools.\n- Enhanced file upload: Added native binary upload via blob references (`blob_ref`), reducing base64 overhead for binary files.\n- Updated documentation to clarify chunk upload options: support for `content` (text), `blob_ref` (preferred binary), and `data` (legacy base64).\n- Minor documentation adjustments for versioning clarity and structure.\n\nv1.30.0 | 2026-02-06T13:19:37.458Z | user\n\nfast-io 1.25.1 → 1.27.0\n\n- Updated skill version from 1.25.0 to 1.27.0 in metadata.\n- Clarified file upload instructions: use the data parameter only for base64-encoded binary files, not for plain text.\n- Improved upload-chunk documentation to distinguish between text (content) and binary (data) handling.\n- No changes to files; updates reflect improved documentation and workflow guidance.\n\nv1.25.0 | 2026-02-05T18:48:06.569Z | user\n\nfast-io 1.20.1 Changelog\n\n- Added MCP resource endpoints for agent guide and session authentication state.\n- Introduced 8 guided MCP prompts for onboarding, file upload, AI chat, branding, and more.\n- Updated binary file upload flow: `upload-chunk` now accepts optional base64 data.\n- Documentation improvements and clearer workflow summaries.\n- Version metadata updated to 1.25.0.\n\nv1.20.0 | 2026-02-04T22:38:20.813Z | user\n\n**AI chat is now read-only, and file upload tools have been updated for more flexible handling.**\n\n- AI chat can only read and analyze file content; it cannot modify files, settings, members, or events. All non-read actions require MCP tools.\n- Added a dedicated tool for single-step uploads of text files (`upload-text-file`), streamlining creation of code, markdown, CSV, and similar documents.\n- Updated chunked file upload workflow for binary and large files, now requiring explicit session creation and chunk management.\n- Tool count increased from 256 to 257.\n- Documentation and capability descriptions clarified, especially concerning AI chat limitations and file upload recommendations.\n- Version updated to 1.20.0.\n\nv1.18.0 | 2026-02-04T21:36:37.730Z | user\n\nfast-io 1.18.0\n\n- Added clear instructions to always use both `list-orgs` (internal orgs) and `orgs-external` (external orgs via workspace membership) for comprehensive organization discovery.\n- Updated documentation to highlight org discovery patterns and prevent agents from missing external orgs.\n- Metadata version bumped to 1.18.0.\n- Removed outdated reference file and added new documentation references.\n\nv1.17.0 | 2026-02-04T20:23:16.770Z | user\n\nVersion 1.17.0 highlights:\n\n- Added a prominent link and directive to fetch the full agent guide from https://mcp.fast.io/skill.md at the start of every session.\n- Clarified that the included documentation is only a summary, not a complete reference.\n- No other content or workflow changes detected.\n\nv1.16.0 | 2026-02-04T20:18:16.722Z | user\n\nfast-io 1.16.0 is a version bump with no file changes from 1.15.1.\n\n- Version updated from 1.15.0 to 1.16.0 in metadata.\n- No functional or documentation changes detected.\n\nv1.15.0 | 2026-02-04T20:10:28.506Z | user\n\nfast-io 1.15.0\n\n- Expanded documentation in SKILL.md, detailing platform features and capabilities.\n- Clarified account creation and authentication workflows for agent and human users.\n- Outlined advanced file management, sharing options, and AI chat/query tools.\n- Listed free agent plan limits, credit usage, and supported tool categories.\n- Provided clear integration details for endpoints, storage, and collaboration features.\n\nArchive index:\n\nArchive v1.105.0: 3 files, 91517 bytes\n\nFiles: references/REFERENCE.md (115552b), SKILL.md (166593b), _meta.json (128b)\n\nFile v1.105.0:SKILL.md\n\n---\nname: fast-io\ndescription: >-\n Workspaces for agentic teams. Complete agent guide with all 19 consolidated\n tools using action-based routing — parameters, workflows, ID formats, and\n constraints. Use this skill when agents need shared workspaces to collaborate\n with other agents and humans, create branded shares (Send/Receive/Exchange),\n or query documents using built-in AI. Supports ownership transfer to humans,\n workspace management, workflow primitives (tasks, worklogs, approvals, todos),\n and real-time collaboration.\n Free agent plan with 50 GB storage and 5,000 monthly credits.\nlicense: Proprietary\ncompatibility: >-\n Requires network access. Connects to the Fast.io MCP server at mcp.fast.io\n via Streamable HTTP (/mcp) or SSE (/sse).\nmetadata:\n author: fast-io\n version: \"1.105.0\"\nhomepage: \"https://fast.io\"\n---\n\n# Fast.io MCP Server -- AI Agent Guide\n\n**Version:** 1.104\n**Last Updated:** 2026-02-26\n\nThe 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.\n\n> **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.\n\n> **Platform reference.** For a comprehensive overview of Fast.io's capabilities, the agent plan, key workflows, and upgrade paths, see [references/REFERENCE.md](references/REFERENCE.md).\n\n---\n\n## 1. Overview\n\n**Workspaces for Agentic Teams. Collaborate, share, and query with AI -- all through one API, free.**\n\nFast.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.\n\n### The Problem Fast.io Solves\n\nAgentic 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.\n\nWhen 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?\"\n\n| Problem | Fast.io Solution |\n|---------|-----------------|\n| No shared workspace for agentic teams | Workspaces where agents and humans collaborate with file preview, versioning, and AI |\n| Agent-to-agent coordination lacks structure | Shared workspaces with activity feeds, comments, and real-time sync across team members |\n| Sharing outputs with humans is awkward | Purpose-built shares (Send, Receive, Exchange) with link sharing, passwords, expiration |\n| Collecting files from humans is harder | Receive shares let humans upload directly to your workspace -- no email attachments |\n| Understanding document contents | Built-in AI reads, summarizes, and answers questions about your files |\n| Building a RAG pipeline from scratch | Enable intelligence on a workspace and documents are automatically indexed, summarized, and queryable |\n| Finding the right file in a large collection | Semantic search finds documents by meaning, not just filename |\n| Handing a project off to a human | One-click ownership transfer -- human gets the org, agent keeps admin access |\n| Tracking what happened | Full audit trail with AI-powered activity summaries |\n| Cost | Free. 50 GB storage, 5,000 monthly credits, no credit card |\n\n### MCP Server\n\nThis 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.\n\nOnce 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.\n\n### Server Endpoints\n\n- **Production:** `mcp.fast.io`\n- **Development:** `mcp.fastdev1.com`\n\nTwo transports are available on each:\n\n- **Streamable HTTP at `/mcp`** -- the preferred transport for new integrations.\n- **SSE at `/sse`** -- a legacy transport maintained for backward compatibility.\n\n### MCP Resources\n\nThe server exposes static MCP resources, widget resources, and file download resource templates. Clients can read them via `resources/list` and `resources/read`:\n\n| URI | Name | Description | MIME Type |\n|-----|------|-------------|-----------|\n| `skill://guide` | skill-guide | Full agent guide (this document) with all 19 tools, workflows, and platform documentation | `text/markdown` |\n| `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` |\n| `widget://*` | Widget HTML | Interactive HTML5 widgets (5 total) -- use the `apps` tool to discover and launch | `text/html` |\n\n**File download resource templates** -- read file content directly through MCP without needing external HTTP access:\n\n| URI Template | Name | Auth | Dynamic Listing | Description |\n|---|---|---|---|---|\n| `download://workspace/{workspace_id}/{node_id}` | download-workspace-file | Session token | Yes | Download a file from a workspace |\n| `download://share/{share_id}/{node_id}` | download-share-file | Session token | Yes | Download a file from a share |\n| `download://quickshare/{quickshare_id}` | download-quickshare-file | None (public) | No | Download a quickshare file |\n\nFiles 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.\n\n**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.\n\n### MCP Prompts\n\nThe 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.\n\n| Prompt Name | Description |\n|---|---|\n| `App: Choose Workspace or Org` | Launch the Workspace Picker to browse orgs, select workspaces, and manage shares |\n| `App: Pick a File` | Launch the File Picker with built-in workspace navigator for browsing, searching, and selecting files |\n| `App: Open Workflow` | Launch the Workflow Manager (auto-selects workspace if only one, otherwise opens Workspace Picker first) |\n| `App: Available Apps` | List all available MCP App widgets with descriptions and launch instructions |\n\n### HTTP File Pass-Through\n\nFor 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:\n\n| Endpoint | Auth | Description |\n|---|---|---|\n| `GET /file/workspace/{workspace_id}/{node_id}` | `Mcp-Session-Id` header | Stream a workspace file |\n| `GET /file/share/{share_id}/{node_id}` | `Mcp-Session-Id` header | Stream a share file |\n| `GET /file/quickshare/{quickshare_id}` | None (public) | Stream a quickshare file |\n\nThe 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.\n\n### Workflow Overview\n\nThe 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.\n\n**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.\n\n### Additional References\n\n- **Agent guide (this file):** `/skill.md` on the MCP server -- tool documentation, workflows, and constraints.\n- **REST API reference:** `https://api.fast.io/llms.txt` -- endpoint documentation for the underlying Fast.io API.\n- **Platform guide:** [references/REFERENCE.md](references/REFERENCE.md) -- capabilities, agent plan details, key workflows, and upgrade paths.\n\n---\n\n## 2. Authentication (Critical First Step)\n\nAuthentication is required before calling any tool except these unauthenticated tools:\n\n- `auth` with actions: `signin`, `signup`, `set-api-key`, `pkce-login`, `email-check`, `password-reset-request`, `password-reset`\n- `download` with action: `quickshare-details`\n\n### Choosing the Right Approach\n\nThere are three ways to use Fast.io as an agent, depending on whether you are operating autonomously or assisting an existing human user.\n\n**Option 1: Autonomous Agent -- Create an Agent Account**\n\nIf 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.\n\n**Option 2: Assisting a Human -- Use Their API Key**\n\nIf 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 work as Bearer tokens and by default have the same permissions as the account owner. Keys can optionally be scoped to specific organizations, workspaces, or shares (using the same scope system as OAuth tokens), tagged with an `agent_name` for tracking, and given an expiration date. Unscoped keys do not expire unless revoked. Agents can also manage API keys programmatically with `auth` actions `api-key-create`, `api-key-update`, `api-key-list`, `api-key-get`, and `api-key-delete`.\n\n**Option 3: Agent Account Invited to a Human's Org**\n\nIf 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.\n\n**Option 4: Browser Login (PKCE)**\n\nIf 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.\n\nPKCE 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:\n\n| scope_type | Access granted |\n|------------|---------------|\n| `user` | Full account access (default) |\n| `org` | User selects specific organizations |\n| `workspace` | User selects specific workspaces |\n| `all_orgs` | All organizations the user belongs to |\n| `all_workspaces` | All workspaces the user has access to |\n| `all_shares` | All shares the user is a member of (`share:*:`) |\n\n**Scope inheritance:** Broader scopes include access to child entities automatically:\n\n- `all_orgs` includes all orgs + all workspaces + all shares within those orgs\n- `all_workspaces` includes all workspaces + all shares within those workspaces\n- `org` scope on a specific org includes access to all workspaces and shares within that org\n- `workspace` scope on a specific workspace includes access to shares within that workspace\n- `all_shares` grants direct access to all shares the user has membership in, bypassing workspace/org inheritance\n\nThe `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.\n\n**Approval flow by scope_type:**\n\n- **`user`** (default): Full account access. The user sees a simple approve/decline prompt with no entity picker.\n- **`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.\n- **`all_orgs`**, **`all_workspaces`**, **`all_shares`**: The user sees a summary of the wildcard access being requested (no entity picker), then approves or declines.\n\nThe MCP server defaults to `scope_type=\"user\"` for backward compatibility.\n\n| Scenario | Recommended Approach |\n|----------|---------------------|\n| Operating autonomously, storing files, building for users | Create an agent account with your own org (Option 1) |\n| Helping a human manage their existing account | Ask the human to create an API key for you (Option 2) |\n| Working within a human's org with your own identity | Create an agent account, have the human invite you (Option 3) |\n| Building something to hand off to a human | Create an agent account, build it, then transfer the org (Option 1) |\n| Signing in without sending a password through the agent | Browser-based PKCE login (Option 4) |\n\n**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`.\n\n### Standard Sign-In Flow\n\n1. Call `auth` with action `signin`, `email` and `password`.\n2. The server returns a JWT `auth_token` and stores it in the session automatically.\n3. All subsequent tool calls use this token without any manual passing.\n\n### Agent Account Creation\n\nWhen 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:\n\n- `account_type` set to `\"agent\"`\n- Free agent plan assigned automatically\n- Transfer/claim workflow enabled for handing orgs off to humans\n\n**Steps:**\n\n1. Optionally call `auth` action `email-check` with the desired `email` to verify it is available for registration before attempting signup.\n2. Call `auth` action `signup` with `first_name`, `last_name`, `email`, and `password`. The `agent=true` flag is sent automatically by the MCP server.\n3. The account is created and a session is established automatically -- the agent is signed in immediately.\n4. **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.\n5. No credit card is required. No trial period. No expiration. The account persists indefinitely.\n\n### Two-Factor Authentication Flow\n\n1. Call `auth` action `signin` with `email` and `password`.\n2. If the response includes `two_factor_required: true`, the returned token has limited scope.\n3. Call `auth` action `2fa-verify` with the 2FA `code` (TOTP, SMS, or WhatsApp).\n4. The server replaces the limited-scope token with a full-scope token automatically.\n\n### Browser Login (PKCE) Flow\n\n1. 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).\n2. The tool returns a `login_url` -- present it to the user to open in a browser.\n3. The user signs in (email/password or SSO).\n4. 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.\n5. The user clicks Approve. The browser displays an authorization code. The user copies it.\n6. Call `auth` action `pkce-complete` with the `code` to exchange it for an access token.\n7. 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.\n\n### Checking Session Status\n\n- `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.\n- `auth` action `check` -- validates the token against the Fast.io API. Returns the user ID if the token is still valid.\n\n### Session Expiry\n\nJWT tokens last **1 hour**. API keys do not expire by default, but can optionally have an expiration set via `api-key-create` or `api-key-update` with the `key_expires` parameter. When a JWT session expires or a time-limited API key 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.\n\n**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.\n\n### Signing Out\n\nCall `auth` action `signout` to clear the stored session from the Durable Object.\n\n---\n\n## 3. Core Concepts\n\n### Organizations\n\nOrganizations 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:\n\n- **Workspaces** — the file storage containers that belong to the organization.\n- **Members** with roles: owner, admin, member, guest, view.\n- **Billing and subscriptions** managed through Stripe integration.\n- **Plan limits** that govern storage, transfer, AI tokens, and member counts.\n\nOrganizations are identified by a 19-digit numeric profile ID or a domain string.\n\n**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.\n\n#### Org Discovery (IMPORTANT)\n\nTo discover all available orgs, agents **must call both actions**:\n\n1. `org` action `list` -- returns internal orgs where you are a direct member (`member: true`)\n2. `org` action `discover-external` -- returns external orgs you access via workspace membership only (`member: false`)\n\n**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.\n\n#### Internal vs External Orgs\n\n**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.\n\n**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.\n\n**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.\n\n### Workspaces\n\nWorkspaces are file storage containers within organizations. Each workspace has:\n\n- Its own set of **members** with roles (owner, admin, member, guest).\n- A **storage tree** of files and folders (storage nodes).\n- Optional **AI features** for RAG-powered chat.\n- **Shares** that can be created within the workspace.\n- **Archive/unarchive** lifecycle management.\n- **50 GB included storage** on the free agent plan, with files up to 1 GB per upload.\n- **File versioning** -- every edit creates a new version, old versions are recoverable.\n- **Full-text and semantic search** -- find files by name or content, and documents by meaning.\n\nWorkspaces are identified by a 19-digit numeric profile ID.\n\n#### Intelligence: On or Off\n\nWorkspaces have an **intelligence** toggle that controls whether AI features are active:\n\n**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.\n\n**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:\n\n- **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.\n- **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.\n- **Auto-summarization** -- short and long summaries generated for every indexed document and code file, searchable and visible in the UI.\n- **Metadata extraction** -- AI pulls key metadata from documents automatically.\n\n> **Coming soon:** RAG indexing support for images, video, and audio files. Currently only documents and code are indexed.\n\nIntelligence 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.\n\n**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.\n\nFor full details on AI chat types, file context modes, AI state, and how intelligence affects them, see the **AI Chat** section below.\n\n### Shares\n\nShares are purpose-built spaces for exchanging files with people outside your workspace. They can exist within workspaces and have three types:\n\n| Mode | What It Does | Agent Use Case |\n|------|-------------|----------------|\n| **Send** | Recipients can download files | Deliver reports, exports, generated content |\n| **Receive** | Recipients can upload files | Collect documents, datasets, user submissions |\n| **Exchange** | Both upload and download | Collaborative workflows, review cycles |\n\n#### Share Features\n\n- **Password protection** -- require a password for link access\n- **Expiration dates** -- shares auto-expire after a set period\n- **Download controls** -- enable or disable file downloads\n- **Access levels** -- Members Only, Org Members, Registered Users, or Public (anyone with the link)\n- **Custom branding** -- background images, gradient colors, accent colors, logos\n- **Post-download messaging** -- show custom messages and links after download\n- **Up to 3 custom links** per share for context or calls-to-action\n- **Guest chat** -- let share recipients ask questions in real-time\n- **AI-powered auto-titling** -- shares automatically generate smart titles from their contents\n- **Activity notifications** -- get notified when files are sent or received\n- **Comment controls** -- configure who can see and post comments (owners, guests, or both)\n\n#### Two Storage Modes\n\nWhen creating a share with `share` action `create`, the `storage_mode` parameter determines how files are stored:\n\n- **`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.\n\n- **`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.\n\nBoth 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).\n\nShares are identified by a 19-digit numeric profile ID.\n\n**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.\n\n### Storage Nodes\n\nFiles 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.\n\nKey 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).\n\nNodes have versions. Each file modification creates a new version. Version history can be listed and files can be restored to previous versions.\n\n**Conflict resolution (REPLACE by default):** When a file operation encounters an existing file with the same name in the target folder, the default behavior is to **replace** (overwrite) the existing file:\n\n- **Upload (addfile)** -- silently overwrites the existing file. The previous content is preserved as a version entry, recoverable via `storage` action `version-list` / `version-restore`.\n- **Move / Copy** -- trashes the existing conflicting file, then completes the operation. The old file is recoverable from trash.\n- **Restore from trash** -- trashes the existing conflicting file, then restores.\n- **Folder conflicts and type mismatches** (file vs folder) still fall back to rename (e.g. `folder (2)`).\n\nThis means uploading a file with the same name as an existing file will **overwrite it**, not create a renamed copy like `report (2).pdf`. If you need multiple files with the same name to coexist, rename them before uploading.\n\n### Notes\n\nNotes 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\"`.\n\n#### Creating and Updating Notes\n\nCreate notes with `workspace` action `create-note`, read with `workspace` action `read-note`, and update with `workspace` action `update-note`.\n\n**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).\n\n**Reading:** Provide `workspace_id` and `node_id`. Returns the note's markdown content and metadata.\n\n**Updating:** Provide `workspace_id`, `node_id`, and at least one of `name` (must end in `.md`) or `content` (max 100 KB).\n\n| Constraint | Limit |\n|------------|-------|\n| Content encoding | Valid UTF-8 (UTF8MB4). Invalid byte sequences and control characters (`\\p{C}` except `\\t`, `\\n`, `\\r`) are stripped. |\n| Content size | 100 KB max |\n| Filename | 1-100 characters, must end in `.md` |\n| Markdown validation | Code blocks and emphasis markers must be balanced |\n| Rate limit | 2 per 10s, 5 per 60s |\n\n#### Notes as Long-Term Knowledge Grounding\n\nIn 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.\n\nWhen 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.\n\nKey behaviors:\n\n- Notes are ingested for RAG when workspace intelligence is enabled\n- Notes within a folder scope are included in scoped queries\n- Notes with `ai_state: ready` are searchable via RAG\n- Notes can also be attached directly to a chat via `files_attach` (check `ai.attach` is `true` in storage details)\n\n**Use cases:**\n\n- Store project context, decisions, and rationale. Months later, ask \"Why did we choose vendor X?\" and the AI retrieves the note.\n- Save research findings in a note. Future AI chats automatically use those findings as grounding.\n- Create reference documents (style guides, naming conventions) that inform all future AI queries in the workspace.\n\n#### Other Note Operations\n\nNotes 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`).\n\n#### Linking Users to Notes\n\n- **Note in workspace context** (opens workspace with note panel): `https://{domain}.fast.io/workspace/{folder_name}/storage/root?note={note_id}`\n- **Note preview** (standalone view): `https://{domain}.fast.io/workspace/{folder_name}/preview/{note_id}`\n\n### AI Chat\n\nAI chat lets agents ask questions about files stored in workspaces and shares. Two chat types are available, each with different file context options.\n\n**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.\n\n#### Two Chat Types\n\n- **`chat`** — Basic AI conversation with no file context from the workspace index. Use for general questions only.\n- **`chat_with_files`** — AI grounded in your files. Two mutually exclusive modes for providing file context:\n - **Folder/file scope (RAG)** — limits the retrieval search space. Requires intelligence enabled; files must be in `ready` AI state.\n - **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.\n\n**Auto-promotion:** If you create a chat with `type=chat` but include `files_scope`, `folders_scope`, or `files_attach`, the system automatically promotes the type to `chat_with_files`. You don't need to worry about setting the type exactly right — the intent is unambiguous when file parameters are present.\n\nBoth types augment answers with web knowledge when relevant.\n\n#### File Context: Scope vs Attachments\n\nFor `chat_with_files`, choose one of these mutually exclusive approaches:\n\n| Feature | Folder/File Scope (RAG) | File Attachments |\n|---------|------------------------|------------------|\n| How it works | Limits RAG search space | Files read directly by AI |\n| Requires intelligence | Yes | No |\n| File readiness requirement | `ai_state: ready` | `ai.attach: true` |\n| Best for | Many files, knowledge retrieval | Specific files, direct analysis |\n| Max references | 100 folder refs (subfolder tree expansion) or 100 file refs | 20 files / 200 MB |\n| Default (no scope given) | Entire workspace | N/A |\n\n**Scope parameters** (REQUIRES intelligence — will error if intelligence is off):\n\n- `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.\n- `files_scope` — comma-separated `nodeId:versionId` pairs (max 100). Limits RAG to specific indexed files. nodeId is required; versionId is required in the pair format but will be **auto-resolved to the node's current version** if left empty (e.g., `nodeId:` with nothing after the colon). Get `versionId` from the file's `version` field in `storage` action `list` or `details` responses.\n- **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.\n\n**Attachment parameter** (no intelligence required):\n\n- `files_attach` — comma-separated `nodeId:versionId` pairs (max 20, 200 MB total). nodeId is required; versionId will be **auto-resolved to the current version** if left 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.\n\n**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.\n\n**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).\n\n`files_scope`/`folders_scope` and `files_attach` are mutually exclusive — sending both will error.\n\n#### Intelligence and AI State\n\nThe 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:\n\n| State | Meaning |\n|-------|---------|\n| `disabled` | AI processing disabled for this file |\n| `pending` | Queued for processing |\n| `in_progress` | Currently being ingested and indexed |\n| `ready` | Complete — available for folder/file scope queries |\n| `failed` | Processing failed |\n\nOnly files with `ai_state: ready` are included in folder/file scope searches. Check file state via `storage` action `details` with `context_type: \"workspace\"`.\n\n#### Attachability — the `ai.attach` Flag\n\nFile nodes in storage list/details responses include an `ai` object with three fields:\n\n| Field | Type | Meaning |\n|-------|------|---------|\n| `ai.state` | string | AI indexing state (`disabled`, `pending`, `inprogress`, `ready`, `failed`) |\n| `ai.attach` | boolean | Whether the file can be used with `files_attach` |\n| `ai.summary` | boolean | Whether the file already has an AI-generated summary |\n\n**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.\n\nThis flag is independent of the workspace intelligence setting — a file can have `ai.attach: true` even when intelligence is off.\n\n**When to enable intelligence:** You need scoped RAG queries, cross-file search, auto-summarization, or a persistent knowledge base.\n\n**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).\n\nEven with intelligence off, `chat_with_files` with file attachments still works for files with `ai.attach: true`.\n\n#### How to Phrase Questions\n\n**With folder/file scope (RAG):** Write questions likely to match content in indexed files. The AI searches the scope, retrieves passages, and cites them.\n\n- Good: \"What are the payment terms in the vendor contracts?\"\n- Good: \"Summarize the key findings from the Q3 analysis reports\"\n- Bad: \"Tell me about these files\" — too vague, no specific content to match\n- Bad: \"What's in this workspace?\" — cannot meaningfully search for \"everything\"\n\n**With file attachments:** Be direct — the AI reads the full file content. No retrieval step.\n\n- \"Describe this image in detail\"\n- \"Extract all dates and amounts from this invoice\"\n- \"Convert this CSV data into a summary table\"\n\n**Personality:** The `personality` parameter controls the tone and length of AI responses. Pass it when creating a chat or sending a message:\n\n- `concise` — short, brief answers\n- `detailed` — comprehensive answers with context and evidence (default)\n\nUse `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.\n\n**Controlling verbosity in questions:** You can also guide verbosity through how you phrase the question itself:\n\n- \"In one sentence, what is the main conclusion of this report?\"\n- \"List only the file names that mention GDPR compliance, no explanations\"\n- \"Give me a brief summary — 2-3 bullet points max\"\n\nCombining `personality: \"concise\"` with a direct question produces the shortest answers and uses the fewest AI credits.\n\n#### Chat Parameters\n\nCreate a chat with `ai` action `chat-create` (with `context_type: \"workspace\"`) or `ai` action `chat-create` (with `context_type: \"share\"`):\n\n- `type` (required) — `chat` or `chat_with_files`\n- `query_text` (required for workspace, optional for share) — initial message, 2-12,768 characters\n- `personality` (optional) — `concise` or `detailed` (default: `detailed`)\n- `privacy` (optional) — `private` or `public` (default: `public`)\n- `files_scope` (optional) — `nodeId:versionId,...` (max 100, requires `chat_with_files` + intelligence). nodeId required; versionId auto-resolved if empty. **Omit to search all indexed documents (recommended default).**\n- `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).**\n- `files_attach` (optional) — `nodeId:versionId,...` (max 20 / 200 MB, nodeId required, versionId auto-resolved if empty, mutually exclusive with scope params)\n\n#### Follow-up Messages\n\nSend 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.\n\n#### Waiting for AI Responses\n\nAfter creating a chat or sending a message, the AI response is asynchronous. Message states progress: `ready` → `in_progress` → `complete` (or `errored`).\n\n**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.\n\n#### Response Citations\n\nCompleted AI responses include citations pointing to source files:\n\n- `nodeId` — storage node opaque ID\n- `versionId` — file version opaque ID\n- `entries[].page` — page number\n- `entries[].snippet` — text excerpt\n- `entries[].timestamp` — audio/video timestamp\n\n#### Linking Users to AI Chats\n\nAppend `?chat={chat_opaque_id}` to the workspace storage URL:\n\n`https://{domain}.fast.io/workspace/{folder_name}/storage/root?chat={chat_id}`\n\n#### Share AI Chats\n\nShares support AI chat with identical capabilities. All workspace AI endpoints have share equivalents accessible via `ai` actions with `context_type: \"share\"`.\n\n### AI Share / Export\n\nGenerate 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.\n\n### Profile IDs\n\nOrganizations, 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`.\n\nMost endpoints also accept custom names as identifiers:\n| Profile Type | Numeric ID | Custom Name |\n|-------------|-----------|-------------|\n| Workspace | 19-digit ID | Folder name (e.g., `my-project`) |\n| Share | 19-digit ID | URL name (e.g., `q4-financials`) |\n| Organization | 19-digit ID | Domain name (e.g., `acme`) |\n| User | 19-digit ID | Email address (e.g., `user@example.com`) |\n\n### QuickShares\n\nQuickShares 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.\n\n### File Preview\n\nFiles 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.\n\nSupported preview formats:\n\n- **Images** -- full-resolution with auto-rotation and zoom\n- **Video** -- HLS adaptive streaming (50--60% faster load than raw video)\n- **Audio** -- interactive waveform visualization\n- **PDF** -- page navigation, zoom, text selection\n- **Spreadsheets** -- grid navigation with multi-sheet support\n- **Code and text** -- syntax highlighting, markdown rendering\n\nUse `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.\n\n**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.\n\n### Comments and Annotations\n\nHumans and agents can leave feedback directly on files, anchored to specific content using the `reference` parameter:\n\n- **Image comments** -- anchored to spatial regions (normalized x/y/width/height coordinates)\n- **Video comments** -- anchored to timestamps with spatial region selection\n- **Audio comments** -- anchored to timestamps or time ranges\n- **PDF comments** -- anchored to specific pages with optional text snippet selection\n- **Threaded replies** -- single-level threading only; replies to replies are auto-flattened to the parent\n- **Emoji reactions** -- one reaction per user per comment; adding a new reaction replaces the previous one\n- **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\n\nComments use JSON request bodies (`Content-Type: application/json`), unlike most other endpoints which use form-encoded data.\n\n**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`.\n\n**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. Optionally include `linked_entity_type` and `linked_entity_id` to link the comment to a task or approval at creation time.\n\n**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.\n\n**Comment Linking:** Comments can be linked to workflow entities (tasks or approvals). Each comment supports one link at a time (nullable). Use `comment` action `link` to associate an existing comment with a task or approval, `comment` action `unlink` to remove the association, and `comment` action `linked` to reverse-lookup all comments linked to a given entity. You can also link at creation time by passing `linked_entity_type` and `linked_entity_id` to the `add` action. Comment responses include `linked_entity_type` and `linked_entity_id` fields (null when unlinked).\n\n**Linking users to comments:** The preview URL opens the comments sidebar automatically. Deep link query parameters let you target a specific comment or position:\n\n| Parameter | Format | Purpose |\n|-----------|--------|---------|\n| `?comment={id}` | Comment opaque ID | Scrolls to and highlights a specific comment for 2 seconds |\n| `?t={seconds}` | e.g. `?t=45.5` | Seeks to timestamp for audio/video comments |\n| `?p={pageNum}` | e.g. `?p=3` | Navigates to page for PDF comments |\n\nWorkspace: `https://{org.domain}.fast.io/workspace/{folder_name}/preview/{file_opaque_id}?comment={comment_id}`\n\nShare: `https://go.fast.io/shared/{custom_name}/{title-slug}/preview/{file_opaque_id}?comment={comment_id}`\n\nParameters 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 enable\n\nFile v1.105.0:_meta.json\n\n{\n \"ownerId\": \"kn74d15nyw6rzrc3fekbs5333d80ha0y\",\n \"slug\": \"fast-io\",\n \"version\": \"1.105.0\",\n \"publishedAt\": 1772149097549\n}\n\nFile v1.105.0:references/REFERENCE.md\n\n# Fast.io for AI Agents\n\n> **Version:** 1.25.0 | **Last updated:** 2026-02-21\n>\n> This guide is available at the `/current/agents/` endpoint on the connected API server.\n\n**Workspaces for Agentic Teams. Collaborate, share, and query with AI — all through one API, free.**\n\nFast.io provides workspaces for agentic teams — where agents collaborate with other agents and with humans. Upload\noutputs, create branded data rooms, ask questions about documents using built-in AI, and hand everything off to a human\nwhen the job is done. No infrastructure to manage, no subscriptions to set up, no credit card required.\n\n**MCP-enabled agents** should connect via the Model Context Protocol for the simplest integration — no raw HTTP calls\nneeded.\n\n**Connection endpoints:**\n- **Streamable HTTP (recommended):** `https://mcp.fast.io/mcp`\n- **Legacy SSE:** `https://mcp.fast.io/sse`\n\nThe MCP server exposes **19 consolidated tools** using action-based routing — each tool covers a domain (e.g., `auth`,\n`storage`, `upload`) and uses an `action` parameter to select the operation. See the \"MCP Tool Architecture\" section\nbelow for the full tool list.\n\nMCP-connected agents receive comprehensive workflow guidance through SERVER_INSTRUCTIONS at connection time, and can\nread resources (`resources/read`) including `skill://guide` for full tool documentation, `session://status` for current\nauthentication state, and `download://` resource templates for direct file content retrieval.\n\nThis guide covers platform concepts and capabilities; the MCP server provides tool-level details through its standard\nprotocol interface. The API endpoints referenced below are what the MCP server calls under the hood, and are available\nfor agents that need direct HTTP access or capabilities not yet covered by the MCP tools.\n\n---\n\n## Why Agents Use Fast.io\n\n### The Problem\n\nAgentic teams — groups of agents working together and with humans — need a shared place to work. Today, agents cobble\ntogether S3 buckets, presigned URLs, email attachments, and custom download pages. Every agent reinvents collaboration,\nand there's no shared workspace where agents and humans can see the same files, track activity, and hand off work.\n\nMeanwhile, when agents need to *understand* documents — not just store them — they have to download files, parse dozens\nof formats, build search indexes, and manage their own RAG pipeline. That's a lot of infrastructure for what should be a\nsimple question: \"What does this document say?\"\n\n### What Fast.io Solves\n\n| Problem | Fast.io Solution |\n|----------------------------------------------|---------------------------------------------------------------------------------------------------|\n| No shared workspace for agentic teams | Workspaces where agents and humans collaborate with file preview, versioning, and AI |\n| Agent-to-agent coordination lacks structure | Shared workspaces with activity feeds, comments, and real-time sync across team members |\n| Sharing outputs with humans is awkward | Purpose-built shares (Send, Receive, Exchange) with link sharing, passwords, expiration |\n| Collecting files from humans is harder | Receive shares let humans upload directly to your workspace — no email attachments |\n| Understanding document contents | Built-in AI reads, summarizes, and answers questions about your documents and code |\n| Building a RAG pipeline from scratch | Enable intelligence on a workspace and documents are automatically indexed, summarized, and queryable |\n| Finding the right file in a large collection | Semantic search finds documents by meaning, not just filename |\n| Handing a project off to a human | One-click ownership transfer — human gets the org, agent keeps admin access |\n| Tracking what happened | Full audit trail with AI-powered activity summaries |\n| Cost | Free. 50 GB storage, 5,000 monthly credits, no credit card |\n\n---\n\n## Getting Started — Choosing the Right Account Type\n\nThere are two ways to use Fast.io as an agent, depending on whether you're operating autonomously or assisting an\nexisting human user.\n\n### Option 1: Autonomous Agent — Create an Agent Account\n\nIf you're operating as part of an agentic team (collaborating with other agents, sharing outputs with humans, running\nworkflows), create your own agent account:\n\n1. `POST /current/user/` with `email_address`, `password`, `tos_agree=true`, `agent=true`\n2. Authenticate with Basic Auth → get JWT\n3. Verify your email address (required before using most endpoints):\n - `POST /current/user/email/validate/` with `email` — sends a verification code to your email\n - `POST /current/user/email/validate/` with `email` and `email_token` — validates the code and marks your account as verified\n4. `POST /current/org/create/` with `domain` (required, 2-80 chars lowercase alphanumeric + hyphens) — an org is a collector of workspaces that can represent a company, team, business unit, or personal collection\n5. `POST /current/org/{org_id}/create/workspace/` with `folder_name`, `name`, `perm_join`, `perm_member_manage` (all required — see Permission Values below)\n\nAgent accounts get the free agent plan (50 GB, 5,000 monthly credits) and can transfer orgs to humans when ready. This\nis the recommended path for autonomous agents.\n\n#### Permission Values\n\nWorkspace and share creation require human-readable permission strings:\n\n**Workspace `perm_join`** (who can auto-join from the org):\n- `'Member or above'` (default) — any org member can join\n- `'Admin or above'` — only org admins and owners\n- `'Only Org Owners'` — only org owners\n\n**Workspace `perm_member_manage`** (who can manage workspace members):\n- `'Member or above'` (default) — any workspace member can manage\n- `'Admin or above'` — only workspace admins and owners\n\n**Share `access_options`** (who can access the share):\n- `'Only members of the Share or Workspace'` (default)\n- `'Members of the Share, Workspace or Org'`\n- `'Anyone with a registered account'`\n- `'Anyone with the link'` (allows password protection)\n\n### Option 2: Assisting a Human — Use Their API Key\n\nIf a human already has a Fast.io account and wants your help managing their files, workspaces, or shares, they can\ncreate an API key for you to use. No separate agent account is needed — you operate as the human user.\n\n**How the human creates an API key:**\n\nGo to **Settings → Devices & Agents → API Keys** and click **Create API Key**. Optionally enter a memo to label the\nkey (e.g., \"CI pipeline\" or \"Agent access\"), then click **Create**. Copy the key immediately — it is only displayed\nonce and cannot be retrieved later. Direct link: `https://go.fast.io/settings/api-keys`\n\nUse the API key as a Bearer token: `Authorization: Bearer {api_key}`\n\nThe API key has the same permissions as the human user, so you can manage their workspaces, shares, and files directly.\n\n### Option 3: Agent Account Invited to a Human's Org\n\nIf you want your own agent identity but need to work within a human's existing organization (their company, team, or personal collection), you can create an agent account and have the human invite you as a member. This gives you access to their workspaces and shares while keeping your own account separate.\n\n**How the human invites the agent to their org:**\n\nGo to **Settings → Your Organization → [Org Name] → Manage People** and click **Invite People**. Enter the agent's\nemail address, choose a permission level (Member or Admin), and click **Send Invites**. The agent account will receive\nthe invitation and can accept it via `POST /current/user/invitations/acceptall/`.\n\n**How the human invites the agent to a workspace:**\n\nOpen the workspace, click the member avatars in the toolbar, then click **Manage Members**. Enter the agent's email\naddress, choose a permission level, and optionally check **Invite to org** to add them to the organization at the same\ntime. Click **Send Invites** — if the agent isn't already an org member and the toggle is off, they'll need an org\ninvite separately.\n\nAlternatively, the human can invite the agent programmatically:\n- **Org:** `POST /current/org/{org_id}/members/{agent_email}/` with `permission` level\n- **Workspace:** `POST /current/workspace/{workspace_id}/members/{agent_email}/` with `permission` level\n\n### Option 4: PKCE Browser Login — Secure Authentication Without Sharing Passwords\n\nFor the most secure authentication flow — especially when a human wants to authorize an agent without sharing their\npassword — use the PKCE (Proof Key for Code Exchange) browser login. No credentials pass through the agent at any point.\n\nThe `client_id` can be a pre-registered ID, a dynamically registered ID (via DCR), or an **HTTPS URL pointing to a\nClient ID Metadata Document (CIMD)**. CIMD is the MCP specification's preferred registration method — the server\nfetches client metadata from the URL on-the-fly, so no pre-registration is needed.\n\n1. Agent calls `POST /current/oauth/authorize/` with PKCE parameters (`code_challenge`, `code_challenge_method=S256`,\n `client_id`, `redirect_uri`, `response_type=code`) — gets back an authorization URL\n2. The user opens the URL in their browser, signs in (supports SSO), and approves access\n3. The browser displays an authorization code that the user copies back to the agent\n4. Agent calls `POST /current/oauth/token/` with `grant_type=authorization_code`, the authorization `code`, and the\n PKCE `code_verifier` — receives an access token and refresh token\n5. The agent is now authenticated. Access tokens last **1 hour**, refresh tokens last **30 days**. Use\n `POST /current/oauth/token/` with `grant_type=refresh_token` to get new access tokens without repeating the flow.\n\nThis is the recommended approach when:\n- A human wants to grant agent access without sharing their password\n- The organization uses SSO and password-based auth isn't available\n- You need the strongest security guarantees (no credentials stored by the agent)\n\n### Recommendations\n\n| Scenario | Recommended Approach |\n|----------|---------------------|\n| Operating autonomously, storing files, building for users | Create an agent account with your own org (your personal collection of workspaces) |\n| Helping a human manage their existing account | Ask the human to create an API key for you |\n| Working within a human's org with your own identity | Create an agent account, have the human invite you |\n| Building something to hand off to a human | Create an agent account, build it, then transfer the org |\n| Human wants to authorize an agent without sharing credentials | Use PKCE browser login (Option 4) |\n\n### Authentication & Token Lifecycle\n\nAll API requests require `Authorization: Bearer {token}` in the header. How you get that token depends on your access\npattern:\n\n**JWT tokens (agent accounts):** Authenticate with `GET /current/user/auth/` using HTTP Basic Auth (email:password). The\nresponse includes an `auth_token` (JWT). OAuth access tokens last **1 hour** and refresh tokens last **30 days**. When\nyour token expires, re-authenticate to get a new one. If the account has 2FA enabled, the initial token has limited\nscope until 2FA verification is completed via `/current/user/auth/2factor/auth/{token}/`.\n\n**API keys (human accounts):** API keys are long-lived and do not expire unless the human revokes them. No refresh flow\nneeded.\n\n**Verify your token:** Call `GET /current/user/auth/check/` at any time to validate your current token and get the\nauthenticated user's ID. This is useful at startup to confirm your credentials are valid before beginning work, or to\ndetect an expired token without waiting for a 401 error on a real request.\n\n### OAuth Scopes — Controlling Access\n\nWhen using PKCE browser login, you can request scoped access tokens that limit what the agent can do. Scopes follow\nan inheritance model — broader scopes automatically include access to their children.\n\n**Scope types:**\n\n| Scope Type | Description |\n|------------------|-----------------------------------------------------------------------------|\n| `all_orgs` | Access to all organizations the user owns or is a member of |\n| `all_workspaces` | Access to all workspaces across accessible organizations |\n| `all_shares` | Access to all shares across accessible organizations and workspaces |\n\n**Inheritance:** `all_orgs` includes `all_workspaces`, which includes `all_shares`. Requesting `all_orgs` grants full\naccess to all orgs, workspaces, and shares the user has access to.\n\nPass the desired `scope_type` when initiating the PKCE authorization flow (`POST /current/oauth/authorize/`). If\nomitted, the token defaults to full access (equivalent to `all_orgs`).\n\n### Organizations — Collectors of Workspaces\n\nAn organization (org) is a collector of workspaces. It can represent a company, a business unit, a team, or simply your own personal collection. Every workspace and share lives under an org, and orgs are the billable entity — storage, credits, and member limits are tracked at the org level.\n\n### Internal vs External Orgs\n\nWhen working with Fast.io, an agent may interact with orgs in two different ways:\n\n**Internal orgs** — orgs you created or were invited to join as a member. You have org-level access: you can see all\nworkspaces (subject to permissions), manage settings if you're an admin, and appear in the org's member list. Your own\norgs always show `member: true` in API responses.\n\n**External orgs** — orgs you can access only through workspace membership. If a human invites you to their workspace\nbut does not invite you to their org, the org appears as external. You can see the org's name and basic public info, but\nyou cannot manage org settings, see other workspaces, or add members at the org level. External orgs show\n`member: false` in API responses.\n\nThis distinction matters because an agent invited to a single workspace cannot assume it has access to the rest of that\norg. It can only work within the workspaces it was explicitly invited to.\n\n**Full org discovery requires both endpoints:**\n\n- `GET /current/orgs/list/` — returns orgs you are a member of (`member: true`)\n- `GET /current/orgs/list/external/` — returns orgs you access via workspace membership only (`member: false`)\n\n**Always call both.** An agent that only calls `/orgs/list/` will miss every org where it was invited to a workspace but\nnot to the org itself — which is the most common pattern when a human adds an agent to help with a specific project. If\nyou skip `/orgs/list/external/`, you won't discover those workspaces at all.\n\n**Example:** A human invites your agent to their \"Q4 Reports\" workspace. You can upload files, run AI queries, and\ncollaborate in that workspace. But you cannot create new workspaces in their org, view their billing, or access their\nother workspaces. The org shows up in `/orgs/list/external/` — not `/orgs/list/`.\n\nIf the human later invites you to the org itself (via org member invitation), the org moves from external to internal and\nyou gain org-level access based on your permission level.\n\n### Pagination\n\nAll list endpoints support offset-based pagination via query parameters. Use pagination to keep responses within token\nlimits and iterate through large collections.\n\n**Query parameters:**\n\n| Parameter | Type | Default | Max | Description |\n|-----------|------|---------|-----|----------------------------|\n| `limit` | int | 100 | 500 | Number of items to return |\n| `offset` | int | 0 | — | Number of items to skip |\n\n**Response metadata:** Every paginated response includes a `pagination` object:\n\n```json\n{\n \"pagination\": {\n \"total\": 42,\n \"limit\": 100,\n \"offset\": 0,\n \"has_more\": false\n }\n}\n```\n\n**Paginating through results:**\n\n```\n# First page\nGET /current/orgs/list/?limit=10&offset=0\n# → pagination.has_more = true, pagination.total = 42\n\n# Second page\nGET /current/orgs/list/?limit=10&offset=10\n# → pagination.has_more = true\n\n# Continue until has_more = false\n```\n\n**Endpoints supporting pagination:**\n\n| Endpoint | Collection Key |\n|------------------------------------------------------|--------------------|\n| `GET /current/orgs/all/` | `orgs` |\n| `GET /current/orgs/list/` | `orgs` |\n| `GET /current/orgs/list/external/` | `orgs` |\n| `GET /current/shares/all/` | `shares` |\n| `GET /current/workspace/{id}/members/list/` | `users` |\n| `GET /current/org/{id}/billing/usage/members/list/` | `billable_members` |\n| `GET /current/workspace/{id}/list/shares/` | `shares` |\n| `GET /current/user/me/list/shares/` | `shares` |\n| `GET /current/org/{id}/list/workspaces/` | `workspaces` |\n| `GET /current/org/{id}/members/list/` | `users` |\n| `GET /current/workspace/{id}/storage/search/` | `files` |\n| `GET /current/share/{id}/storage/search/` | `files` |\n| `GET /current/share/{id}/members/list/` | `users` |\n\n---\n\n## Core Capabilities\n\n### 1. Workspaces — Shared Spaces for Agentic Teams\n\nWorkspaces are where agentic teams do their work. Each workspace has its own storage, member list, AI chat, and\nactivity feed — a shared environment where agents collaborate with other agents and with humans.\n\n- **50 GB included storage** on the free agent plan\n- **Files up to 1 GB** per upload\n- **File versioning** — every edit creates a new version, old versions are recoverable\n- **Folder hierarchy** — organize files however you want\n- **Full-text and semantic search** — find files by name or content, and documents by meaning\n- **Member roles** — Owner, Admin, Editor, Viewer with granular permissions\n- **Real-time sync** — changes appear instantly for all members via WebSockets\n\n#### Intelligence: On or Off\n\nWorkspaces have an **intelligence** toggle that controls whether AI features are active. This is a critical decision:\n\n**Intelligence OFF** — the workspace stores files without AI indexing. You can still attach files directly to an AI chat\nconversation (up to 20 files), but files are not persistently indexed. This is fine for coordination workflows where\nyou don't need to query your content.\n\n**Intelligence ON** — the workspace becomes an AI-powered knowledge base. Every document and code file uploaded is automatically ingested,\nsummarized, and indexed for RAG. This enables:\n\n- **RAG (retrieval-augmented generation)** — scope AI chat to entire folders or the full workspace and ask questions\n across your indexed documents and code. The AI retrieves relevant passages and answers with citations.\n- **Semantic search** — find files by meaning, not just keywords. \"Show me contracts with indemnity clauses\" works even\n if those exact words don't appear in the filename.\n- **Auto-summarization** — short and long summaries generated for every indexed document and code file, searchable and visible in the UI.\n- **Metadata extraction** — AI pulls structured metadata from documents, code, and images automatically using templates.\n Assign a template to a workspace, and every document uploaded is automatically extracted against that schema during\n ingestion. You can also trigger extraction manually or in batch. See section 14 (Metadata) for the full API.\n\n> **Coming soon:** RAG indexing support for images, video, and audio files. Currently only documents and code are indexed.\n\nIntelligence is enabled by default when creating workspaces via the API for agent accounts. If your team only needs a\nshared workspace for coordination, you can disable it to conserve credits. If you want to query your content — enable it.\n\n**Agent use case:** Create a workspace per project or client. Enable intelligence if agents or humans need to query the\ncontent. Upload reports, datasets, and deliverables. Invite other agents and human stakeholders. Everything is organized,\nsearchable, and versioned — and the whole team can see it.\n\n### 2. Shares — Structured Agent-Human Exchange\n\nShares are purpose-built spaces for exchanging files between your agentic team and external humans. Three modes cover\nevery exchange pattern:\n\n| Mode | What It Does | Agent Use Case |\n|--------------|-------------------------------|-----------------------------------------------|\n| **Send** | Recipients can download files | Deliver reports, exports, generated content |\n| **Receive** | Recipients can upload files | Collect documents, datasets, user submissions |\n| **Exchange** | Both upload and download | Collaborative workflows, review cycles |\n\n#### Share Features\n\n- **Password protection** — require a password for link access\n- **Expiration dates** — shares auto-expire after a set period\n- **Download controls** — enable or disable file downloads\n- **Access levels** — `'Only members of the Share or Workspace'`, `'Members of the Share, Workspace or Org'`, `'Anyone with a registered account'`, or `'Anyone with the link'`\n- **Custom branding** — background images, gradient colors, accent colors, logos\n- **Post-download messaging** — show custom messages and links after download\n- **Up to 3 custom links** per share for context or calls-to-action\n- **Guest chat** — let share recipients ask questions in real-time\n- **AI-powered auto-titling** — shares automatically generate smart titles from their contents\n- **Activity notifications** — get notified when files are sent or received\n- **Comment controls** — configure who can see and post comments (owners, guests, or both)\n\n#### Two Storage Modes\n\nWhen creating a share, you choose a `storage_mode` that determines how the share's files are managed:\n\n- **`room`** (independent storage, default) — the share has its own isolated storage. Files are added directly to the\n share and are independent of any workspace. This creates a self-contained data room — changes to workspace files don't\n affect the room, and vice versa. Perfect for final deliverables, compliance packages, archived reports, or any\n scenario where you want an immutable snapshot.\n\n- **`shared_folder`** (workspace-backed) — the share is backed by a specific folder in a workspace. The share displays\n the live contents of that folder — any files added, updated, or removed in the workspace folder are immediately\n reflected in the share. No file duplication, so no extra storage cost. To create a shared folder, pass\n `storage_mode=shared_folder` and `folder_node_id={folder_opaque_id}` when creating the share. Note: expiration dates\n are not allowed on shared folder shares since the content is live.\n\nBoth modes look the same to share recipients — a branded data room with file preview, download controls, and all share\nfeatures. The difference is whether the content is a snapshot (room) or a live view (shared folder).\n\n**Agent use case:** Generate a quarterly report, create a Send share with your client's branding, set a 30-day\nexpiration, and share the link. The client sees a branded page with instant file preview — not a raw download link.\n\n### 3. QuickShare — Instant File Handoff\n\nNeed to toss a file to someone right now? QuickShare creates a share from a single file with zero configuration.\nAutomatic 30-day expiration. No setup, no decisions.\n\n**Agent use case:** Debug log, sample output, or quick artifact? QuickShare it and send the link. Done.\n\n### 4. Built-In AI — Ask Questions About Your Files\n\nFast.io's AI is a **read-only tool** — it can read and analyze file contents, but it cannot modify files, change\nworkspace settings, manage members, or read events. It answers questions about your documents, nothing more. For any\naction beyond reading file content, your agent must use the API or MCP server directly.\n\nFast.io's AI lets agents query documents through two chat types, with or without persistent indexing. Both types\naugment file knowledge with information from the web when relevant.\n\n#### Chat Types\n\n**`chat`** — Basic AI conversation. Does not use file context from the workspace index. Use this for general questions\nor when you don't need to reference stored files.\n\n**`chat_with_files`** — AI conversation grounded in your files. This is the type you use when you want the AI to read,\nanalyze, and cite your documents. Requires the workspace to have **intelligence enabled** if using folder/file scope\n(RAG). Supports two mutually exclusive modes for providing file context:\n\n1. **Folder/file scope** (RAG) — limits the search space for retrieval. The AI searches the indexed content of files\n within the specified scope, retrieves relevant passages, and answers with citations. Requires intelligence enabled\n and files in `ready` AI state.\n\n2. **File attachments** — files are directly attached to the conversation. The AI reads the full content of the attached\n files. Does not require intelligence — any file with a ready preview can be attached. Max 20 files, 200MB total.\n\nThese two modes cannot be combined in a single chat — use scope OR attachments, not both.\n\n**Auto-promotion:** If you create a chat with `type=chat` but include `files_scope`, `folders_scope`, or `files_attach`,\nthe system automatically promotes the type to `chat_with_files`. You don't need to worry about setting the type exactly\nright — the intent is unambiguous when file parameters are present.\n\n#### Intelligence Setting — When to Enable It\n\nThe `intelligence` toggle on a workspace controls whether uploaded documents and code files are automatically ingested, summarized, and\nindexed for RAG.\n\n**Enable intelligence when:**\n- You have many files and need to search across them to answer questions\n- You want scoped RAG queries against folders or the entire workspace\n- You need auto-summarization and metadata extraction\n- You're building a persistent knowledge base\n\n**Disable intelligence when:**\n- You're using the workspace purely for team coordination and file exchange\n- You only need to analyze specific files (use file attachments instead)\n- You want to conserve credits (ingestion costs 10 credits/page)\n\nEven with intelligence disabled, you can still use `chat_with_files` with **file attachments** — any file that has a\nready preview can be attached directly to a chat for one-off analysis.\n\n#### AI State — File Readiness for RAG\n\nEvery document and code file in an intelligent workspace has an `ai_state` field that tracks its ingestion progress:\n\n| State | Meaning |\n|---------------|---------------------------------------------------|\n| `disabled` | AI processing disabled for this file |\n| `pending` | Queued for processing |\n| `in_progress` | Currently being ingested and indexed |\n| `ready` | Processing complete — file is available for RAG |\n| `failed` | Processing failed |\n\n**Only documents and code files with `ai_state: ready` are included in folder/file scope searches.** If you upload files and immediately\ncreate a scoped chat, recently uploaded files may not yet be indexed. Use the activity polling endpoint to wait for\n`ai_state` changes before querying.\n\n#### Folder Scope vs File Attachments\n\n| Feature | Folder/File Scope (RAG) | File Attachments |\n|----------------------|--------------------------------------------|------------------------------------------|\n| How it works | Limits RAG search space | Files read directly by AI |\n| Requires intelligence| Yes | No |\n| Requires `ai_state` | Files must be `ready` | Files must have a ready preview |\n| Best for | Many files, knowledge retrieval | Specific files, direct analysis |\n| Max references | 100 folder refs (subfolder tree expansion) | 20 files, 200MB total |\n| Default behavior | No scope = entire workspace | N/A |\n\n**Folder scope parameters:**\n- `folders_scope` — comma-separated `nodeId:depth` pairs (depth 1-10, max 100 subfolder refs). The depth controls how\n many levels of subfolders are expanded — only subfolder references count toward the 100 limit, not individual files\n within those folders. The RAG backend automatically searches all indexed documents inside the scoped folders.\n- `files_scope` — comma-separated `nodeId:versionId` pairs (max 100 refs). nodeId is required; versionId is required\n in the pair format but will be **auto-resolved to the node's current version** if left empty (e.g., `nodeId:` with\n nothing after the colon). Get the versionId from the file's `version` field in storage list/details responses.\n Limits RAG retrieval to specific file versions.\n- **Default scope is the entire workspace** — if you omit both `files_scope` and `folders_scope`, the AI searches\n all indexed documents. This is the recommended approach when you want to query across everything. Only provide scope\n parameters when you need to narrow the search to specific files or folders.\n\n**Important — how folder scope works internally:**\nFolder scope defines a search boundary, not a file list. When you pass `folders_scope`, the system expands the specified\nfolders into a set of subfolder references up to the given depth. The RAG backend then searches all indexed documents within\nthose folders automatically. You do **not** need to enumerate or list individual files — just provide the top-level\nfolder ID and the desired depth. A folder containing thousands of files with only a few subfolders will work fine,\nbecause only the subfolder references (not file references) count toward the 100 limit. If you need to query the\nentire workspace, omit `folders_scope` entirely — the default scope is already the full workspace.\n\n**File attachment parameter:**\n- `files_attach` — comma-separated `nodeId:versionId` pairs (max 20 files, 200MB total). nodeId is required;\n versionId will be **auto-resolved to the current version** if left empty. **Only file nodes are accepted — passing\n a folder nodeId will be rejected.** Files are read directly, not searched via RAG. To include folder contents, use\n `folders_scope` instead.\n\n#### Notes as Knowledge Grounding\n\nNotes are markdown documents created directly in workspace storage via the API\n(`POST /current/workspace/{id}/storage/{folder}/createnote/`). In an intelligent workspace, notes are ingested and\nindexed just like uploaded files. This makes notes a way to store long-term knowledge that becomes grounding material\nfor future AI queries.\n\n**Agent use case:** Store project context, decision logs, or reference material as notes. When you later ask the AI\n\"What was the rationale for choosing vendor X?\", the note containing that decision is retrieved and cited — even months\nlater.\n\nNotes within a folder scope are included in RAG queries when intelligence is enabled.\n\n#### How to Write Effective Questions\n\nThe way you phrase questions depends on whether you're using folder scope (RAG) or file attachments.\n\n**With folder/file scope (RAG):**\n\nWrite questions that are likely to match content in your indexed files. The AI searches the scope for relevant passages,\nretrieves them, and uses them as citations to answer your question. Think of it as a search query that returns context\nfor an answer.\n\n- Good: \"What are the payment terms in the vendor contracts?\" — matches specific content in files\n- Good: \"Summarize the key findings from the Q3 analysis reports\" — retrieves relevant sections\n- Good: \"What risks were identified in the security audit?\" — finds specific content to cite\n- Bad: \"Tell me about these files\" — too vague for retrieval, no specific content to match\n- Bad: \"What's in this workspace?\" — the AI can't meaningfully search for \"everything\"\n\nIf no folder scope is specified, the search defaults to all indexed documents in the workspace. For large workspaces, narrowing the\nscope to specific folders improves relevance and reduces token usage.\n\n**With file attachments:**\n\nYou can be more direct and simplistic since the AI reads the full file content. No retrieval step — the AI has the\ncomplete file in context.\n\n- \"Describe this image in detail\"\n- \"Extract all dates and amounts from this invoice\"\n- \"Convert this CSV data into a summary table\"\n- \"What programming language is this code written in and what does it do?\"\n\n**Personality:** The `personality` parameter controls the tone and length of AI responses. Pass it when creating a chat\nor sending a message:\n\n- `concise` — short, direct answers with minimal explanation\n- `detailed` — comprehensive answers with context and evidence (default)\n\nThis makes a significant difference in response quality for your use case. Agents that need to extract data or get quick\nanswers should use `concise` to avoid wasting tokens on lengthy explanations. Use `detailed` when you need thorough\nanalysis with supporting evidence.\n\nYou can also control verbosity in the question itself — for example, \"In one sentence, summarize this report\" or \"List\nonly the file names, no explanations.\" Combining `concise` personality with direct questions produces the shortest\nresponses.\n\n#### Waiting for AI Responses\n\nAfter sending a message, the AI processes it asynchronously. You need to wait for the response to be ready.\n\n**Message states:**\n\n| State | Meaning |\n|-------------------|--------------------------------------|\n| `ready` | Queued for processing |\n| `in_progress` | AI is generating the response |\n| `complete` | Response finished |\n| `errored` | Processing failed |\n| `post_processing` | Finalizing (citations, formatting) |\n\n**Option 1: SSE streaming (recommended for real-time display)**\n\n`GET /current/workspace/{id}/ai/chat/{chat_id}/message/{message_id}/read/`\n\nReturns a `text/event-stream` with response chunks as they're generated. The stream ends with a `done` event when the\nresponse is complete. Response chunks include the AI's text, citations pointing to specific files/pages/snippets, and\nany structured data (tables, analysis).\n\n**Option 2: Activity polling (recommended for background processing)**\n\nDon't poll the message endpoint in a loop. Instead, use the activity long-poll:\n\n`GET /current/activity/poll/{workspace_id}?wait=95&lastactivity={timestamp}`\n\nWhen `ai_chat:{chatId}` appears in the activity response, the chat has been updated — fetch the message details to get\nthe completed response. This is the most efficient approach when you don't need to stream the response in real-time.\n\n**Option 3: Fetch completed response**\n\n`GET /current/workspace/{id}/ai/chat/{chat_id}/message/{message_id}/details/`\n\nCheck the `state` field. If `complete`, the `response.text` contains the full answer and `response.citations` contains\nthe file references.\n\n#### Linking Users to AI Chats\n\nTo send a user directly to an AI chat in the workspace UI, append a `chat` query parameter to the workspace storage\nURL:\n\n`https://{org.domain}.fast.io/workspace/{workspace.folder_name}/storage/root?chat={chat_opaque_id}`\n\nThis opens the workspace with the specified chat visible in the AI panel.\n\n#### Supported Content Types\n\n**Indexed for RAG** (requires Intelligence ON):\n- Documents (PDF, Word, text, markdown)\n- Code files (all common languages)\n\n**File attachments only** (no RAG indexing):\n- Spreadsheets (Excel, CSV)\n- Images (all common formats) — *RAG indexing coming soon*\n- Video (all common formats) — *RAG indexing coming soon*\n- Audio (all common formats) — *RAG indexing coming soon*\n\n#### AI Share — Export to External AI Tools\n\nGenerate temporary download URLs for your files, formatted as markdown, for pasting into external AI assistants like\nChatGPT or Claude. Up to 25 files, 50MB per file, 100MB total. Links expire after 5 minutes. This is separate from the\nbuilt-in AI chat — use it when you want to analyze files with a different model or tool.\n\n**Agent use case:** A user asks \"What were Q3 margins?\" You have 50 financial documents in an intelligent workspace.\nInstead of downloading and parsing all 50, create a `chat_with_files` scoped to the finance folder and ask. The AI\nsearches the indexed content, retrieves relevant passages, and answers with citations. Pass the cited answer — with\nsource references — back to the user.\n\n### 5. File Preview — No Download Required\n\nFiles uploaded to Fast.io get automatic preview generation. When humans open a share or workspace, they see the content\nimmediately — no \"download and open in another app\" friction.\n\n**Supported preview formats:**\n\n- **Images** — full-resolution with auto-rotation and zoom\n- **Video** — HLS adaptive streaming (50-60% faster load than raw video)\n- **Audio** — interactive waveform visualization\n- **PDF** — page navigation, zoom, text selection\n- **Spreadsheets** — grid navigation with multi-sheet support\n- **Code & text** — syntax highlighting, markdown rendering\n\n**Agent use case:** Your generated PDF report doesn't just appear as a download link. The human sees it rendered inline,\ncan flip through pages, zoom in, and comment on specific sections — all without leaving the browser.\n\n### 6. Notes — Markdown Documents as Knowledge\n\nNotes are a storage node type (alongside files and folders) that store markdown content directly on the server. They\nlive in the same folder hierarchy as files, are versioned like any other node, and appear in storage listings with\n`type: \"note\"`.\n\n#### Creating and Updating Notes\n\n**Create:** `POST /current/workspace/{id}/storage/{parent_id}/createnote/`\n\n- `name` (required) — filename, must end in `.md`, max 100 characters (e.g., `\"project-context.md\"`)\n- `content` (required) — markdown text, max 100 KB. Must be valid UTF-8 (UTF8MB4). Control characters (`\\p{C}` except `\\t`, `\\n`, `\\r`) are stripped.\n\n**Update:** `POST /current/workspace/{id}/storage/{node_id}/updatenote/`\n\n- `name` (optional) — rename the note (must end in `.md`)\n- `content` (optional) — replace the markdown content (max 100 KB). Must be valid UTF-8 (UTF8MB4). Control characters (`\\p{C}` except `\\t`, `\\n`, `\\r`) are stripped.\n- At least one of `name` or `content` must be provided\n\nNotes can also be moved, copied, deleted, and restored using the same storage endpoints as files and folders.\n\n#### Notes as Long-Term Knowledge Grounding\n\nIn an intelligent workspace, notes are automatically ingested and indexed just like uploaded documents. This makes notes a\npowerful way to **bank knowledge over time** — any facts, context, or decisions stored in notes become grounding\nmaterial for future AI queries.\n\nWhen an AI chat uses folder scope (or defaults to the entire workspace), notes within that scope are searched alongside\nfiles. The AI retrieves relevant passages from notes and cites them in its answers.\n\n**Use cases:**\n- Store project context, decisions, and rationale as notes. Months later, ask \"Why did we choose vendor X?\" and the AI\n retrieves the note with that decision.\n- After researching a topic, save key findings in a note. Future AI chats automatically use those findings as grounding.\n- Create reference documents (style guides, naming conventions, process docs) that inform all future AI queries in the\n workspace.\n\n#### Linking Users to Notes\n\n**Open a note in the workspace UI** — append `?note={opaque_id}` to the workspace storage URL:\n\n`https://{org.domain}.fast.io/workspace/{folder_name}/storage/root?note={note_opaque_id}`\n\n**Link directly to the note preview** — use the standard file preview URL:\n\n`https://{org.domain}.fast.io/workspace/{folder_name}/preview/{note_opaque_id}`\n\nThe preview link is more effective if you want the user to focus on reading just that note, while the `?note=` link\nopens the note within the full workspace context.\n\n### 7. Comments & Annotations\n\nHumans can leave feedback directly on files, anchored to specific content:\n\n- **Image comments** — anchored to regions of the image\n- **Video comments** — anchored to timestamps with frame-stepping and spatial region selection\n- **Audio comments** — anchored to timestamps or time ranges\n- **PDF comments** — anchored to specific pages with optional text selection\n- **Threaded replies** — single-level threads under each comment (replies to replies are auto-flattened)\n- **Emoji reactions** — one reaction per user per comment, new replaces previous\n- **Mentions** — tag users with `@[user:USER_ID:Display Name]` syntax in the comment body\n\n**Character limits:** The comment `body` field has a hard maximum of **8,192 characters** — this includes the full mention tag markup. When you convert a short `@name` reference into the bracket syntax (e.g., `@[user:abc123:Jane Smith]`), the expanded string is what counts toward the limit. The display text (everything except mention markup) is separately capped at **500 characters**. Build your comment body with the expanded tags first, then verify the total length before submitting.\n\n**Linking users to comments:** Link users to the file preview URL. The comments sidebar opens automatically in workspace\npreviews, and in share previews when comments are enabled on the share.\n\nBase preview URL:\n\n`https://{org.domain}.fast.io/workspace/{folder_name}/preview/{file_opaque_id}`\n\nFor shares: `https://go.fast.io/shared/{custom_name}/{title-slug}/preview/{file_opaque_id}`\n\n**Deep linking to a specific comment:** Append `?comment={comment_id}` to the preview URL. The UI scrolls to and\nhighlights the comment automatically:\n\n`https://{org.domain}.fast.io/workspace/{folder_name}/preview/{file_opaque_id}?comment={comment_id}`\n\n**Deep linking to media/document positions:** For comments anchored to specific locations, combine with position\nparameters:\n\n- `?t={seconds}` — seeks to a timestamp in audio/video (e.g., `?comment={id}&t=45.5`)\n- `?p={pageNum}` — navigates to a page in PDFs (e.g., `?comment={id}&p=3`)\n\n**Agent use case:** You generate a design mockup. The human comments \"Change the header color\" on a specific region of\nthe image. You read the comment, see exactly what region they're referring to, and regenerate.\n\n### 8. File Uploads — Getting Files Into Fast.io\n\nAgents upload files through a session-based API. There are two paths depending on file size:\n\n#### Small Files (Under 4 MB)\n\nFor files under 4 MB, upload in a single request. Send the file as `multipart/form-data` with the `chunk` field\ncontaining the file data, plus `org` (your org domain), `name`, `size`, and `action=create`.\n\nTo have the file automatically added to a workspace or share, include `instance_id` (the workspace or share ID) and\noptionally `folder_id` (the target folder's OpaqueId, or omit for root). The response includes `new_file_id` — the\npermanent OpaqueId of the file in storage. No further steps needed.\n\n```\nPOST /current/upload/\nContent-Type: multipart/form-data\n\nFields: org, name, size, action=create, instance_id, folder_id, chunk (file)\n→ Response: { \"result\": true, \"id\": \"session-id\", \"new_file_id\": \"2abc...\" }\n```\n\n#### Large Files (4 MB and Above)\n\nLarge files use chunked uploads. The flow has five steps:\n\n1. **Create a session** — `POST /current/upload/` with `org`, `name`, `size`, `action=create`, `instance_id`, and\n optionally `folder_id`. Returns a session `id`.\n\n2. **Upload chunks** — Split the file into **5 MB chunks** (last chunk may be smaller). For each chunk, send\n `POST /current/upload/{session_id}/chunk/` as `multipart/form-data` with the `chunk` field (binary data), `order`\n (1-based — first chunk is `order=1`), and `size`. You can upload up to **3 chunks in parallel** per session.\n\n3. **Trigger assembly** — Once all chunks are uploaded, call `POST /current/upload/{session_id}/complete/`. The server\n verifies chunks and combines them into a single file.\n\n4. **Poll for completion** — The upload progresses through states asynchronously. Poll the session details with the\n built-in long-poll:\n\n `GET /current/upload/{session_id}/details/?wait=60`\n\n The server holds the connection for up to 60 seconds and returns immediately when the status changes:\n\n | Status | Meaning | What to Do |\n |--------|---------|------------|\n | `ready` | Awaiting chunks | Upload chunks |\n | `uploading` | Receiving chunks | Continue uploading |\n | `assembling` | Combining chunks | Keep polling |\n | `complete` | Assembled, awaiting storage | Keep polling |\n | `storing` | Being added to storage | Keep polling |\n | **`stored`** | **Done** — file is in storage | Read `new_file_id`, clean up |\n | `assembly_failed` | Assembly error (terminal) | Check `status_message` |\n | `store_failed` | Storage error (retryable) | Keep polling, server retries |\n\n Stop polling when status is `stored`, `assembly_failed`, or `store_failed`.\n\n5. **Clean up** — Delete the session after completion: `DELETE /current/upload/{session_id}/`.\n\n#### Optional Integrity Hashing\n\nInclude `hash` (SHA-256 hex digest) and `hash_algo=sha256` on each chunk for server-side integrity verification. You can\nalso provide a full-file hash in the session creation request instead.\n\n#### Resuming Interrupted Uploads\n\nIf a connection drops mid-upload, the session persists on the server. To resume:\n\n1. Fetch the session: `GET /current/upload/{session_id}/details/`\n2. Read the `chunks` map — keys are chunk numbers already uploaded, values are byte sizes\n3. Upload only the missing chunks\n4. Trigger assembly and continue as normal\n\n#### Manual Storage Placement\n\nIf you omit `instance_id` when creating the session, the file is uploaded but not placed in any workspace or share. You\ncan add it to storage manually afterward:\n\n```\nPOST /current/workspace/{id}/storage/{folder}/addfile/\nBody: from={\"type\":\"upload\",\"upload\":{\"id\":\"{session_id}\"}}\n```\n\nThis is useful when you need to upload first and decide where to place the file later.\n\n#### MCP Binary Upload — Three Approaches\n\nMCP agents have three ways to pass binary data when uploading chunks. Each uses the `upload` tool's `chunk` action\nwith exactly one of `data`, `blob_ref`, or `content` (for text):\n\n**1. `data` parameter (base64) — simplest for MCP agents**\n\nPass base64-encoded binary directly in the `data` parameter of the `chunk` action. No extra steps required. Works\nwith any MCP client. Adds ~33% size overhead from base64 encoding.\n\n**2. `stage-blob` action — MCP tool-based blob staging**\n\nUse the `upload` tool's `stage-blob` action with `data` (base64) to pre-stage binary data as a blob. Returns a\n`blob_id` that you pass as `blob_ref` in the `chunk` call. Useful when decoupling staging from uploading or preparing\nmultiple chunks in advance.\n\n1. `upload` action `stage-blob` with `data` (base64-encoded binary) → returns `{ blob_id, size }`\n2. `upload` action `chunk` with `blob_ref` set to the `blob_id`\n\n**3. `POST /blob` endpoint — HTTP blob staging for non-MCP clients**\n\nA sidecar HTTP endpoint that accepts raw binary data outside the JSON-RPC pipe, avoiding base64 encoding entirely.\nUseful for clients that can make direct HTTP requests alongside MCP tool calls.\n\n1. `POST /blob` with `Mcp-Session-Id` header and raw bytes as the request body → returns `{ blob_id, size }`\n2. `upload` action `chunk` with `blob_ref` set to the `blob_id`\n\n**Blob constraints (apply to both staging methods):**\n- Blobs expire after **5 minutes** — stage and consume them promptly\n- Each blob is consumed (deleted) on first use and cannot be reused\n- Maximum blob size: **100 MB**\n\n**Agent use case:** You're generating a 200 MB report. Create an upload session targeting the client's workspace, split\nthe file into 5 MB chunks, upload 3 at a time, trigger assembly, and poll until `stored`. The file appears in the\nworkspace with previews generated automatically. Use the activity polling endpoint (section 13) to know when AI indexing\ncompletes if intelligence is enabled.\n\n### 9. URL Import — Pull Files From Anywhere\n\nWhen you need to add a file from the web, use `POST /current/web_upload/` with `source_url` instead of downloading it\nlocally and re-uploading. This is faster because the file transfers server-to-server — your agent never touches the\nbytes.\n\n- Supports any HTTP/HTTPS URL\n- Supports OAuth-protected sources: **Google Drive, OneDrive, Dropbox**\n- Files go through the same processing pipeline (preview generation, AI indexing if intelligence is enabled, virus\n scanning)\n\n**Check progress after submitting.** Web uploads are processed asynchronously by Fast.io's server-side fetch agent,\nwhich may be blocked or rate-limited by the source. The import can fail silently if the source rejects the request, times\nout, or returns an error. Monitor the upload status to confirm the file was actually retrieved and stored before\nreporting success to the user.\n\n**Security note:** The `web_upload` endpoint instructs the Fast.io cloud server to fetch the URL — not the agent's\nlocal environment. The Fast.io server is a public cloud service with no access to the agent's local network, internal\nsystems, or private infrastructure. It can only reach publicly accessible URLs and supported OAuth-authentica\n\nArchive v1.94.1: 3 files, 88250 bytes\n\nFiles: references/REFERENCE.md (114827b), SKILL.md (157564b), _meta.json (127b)\n\nFile v1.94.1:SKILL.md\n\n---\nname: fast-io\ndescription: >-\n Workspaces for agentic teams. Complete agent guide with all 19 consolidated\n tools using action-based routing — parameters, workflows, ID formats, and\n constraints. Use this skill when agents need shared workspaces to collaborate\n with other agents and humans, create branded shares (Send/Receive/Exchange),\n or query documents using built-in AI. Supports ownership transfer to humans,\n workspace management, workflow primitives (tasks, worklogs, approvals, todos),\n and real-time collaboration.\n Free agent plan with 50 GB storage and 5,000 monthly credits.\nlicense: Proprietary\ncompatibility: >-\n Requires network access. Connects to the Fast.io MCP server at mcp.fast.io\n via Streamable HTTP (/mcp) or SSE (/sse).\nmetadata:\n author: fast-io\n version: \"1.94.0\"\nhomepage: \"https://fast.io\"\n---\n\n# Fast.io MCP Server -- AI Agent Guide\n\n**Version:** 1.94\n**Last Updated:** 2026-02-22\n\nThe 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.\n\n> **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.\n\n> **Platform reference.** For a comprehensive overview of Fast.io's capabilities, the agent plan, key workflows, and upgrade paths, see [references/REFERENCE.md](references/REFERENCE.md).\n\n---\n\n## 1. Overview\n\n**Workspaces for Agentic Teams. Collaborate, share, and query with AI -- all through one API, free.**\n\nFast.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.\n\n### The Problem Fast.io Solves\n\nAgentic 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.\n\nWhen 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?\"\n\n| Problem | Fast.io Solution |\n|---------|-----------------|\n| No shared workspace for agentic teams | Workspaces where agents and humans collaborate with file preview, versioning, and AI |\n| Agent-to-agent coordination lacks structure | Shared workspaces with activity feeds, comments, and real-time sync across team members |\n| Sharing outputs with humans is awkward | Purpose-built shares (Send, Receive, Exchange) with link sharing, passwords, expiration |\n| Collecting files from humans is harder | Receive shares let humans upload directly to your workspace -- no email attachments |\n| Understanding document contents | Built-in AI reads, summarizes, and answers questions about your files |\n| Building a RAG pipeline from scratch | Enable intelligence on a workspace and documents are automatically indexed, summarized, and queryable |\n| Finding the right file in a large collection | Semantic search finds documents by meaning, not just filename |\n| Handing a project off to a human | One-click ownership transfer -- human gets the org, agent keeps admin access |\n| Tracking what happened | Full audit trail with AI-powered activity summaries |\n| Cost | Free. 50 GB storage, 5,000 monthly credits, no credit card |\n\n### MCP Server\n\nThis 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.\n\nOnce 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.\n\n### Server Endpoints\n\n- **Production:** `mcp.fast.io`\n- **Development:** `mcp.fastdev1.com`\n\nTwo transports are available on each:\n\n- **Streamable HTTP at `/mcp`** -- the preferred transport for new integrations.\n- **SSE at `/sse`** -- a legacy transport maintained for backward compatibility.\n\n### MCP Resources\n\nThe server exposes static MCP resources, widget resources, and file download resource templates. Clients can read them via `resources/list` and `resources/read`:\n\n| URI | Name | Description | MIME Type |\n|-----|------|-------------|-----------|\n| `skill://guide` | skill-guide | Full agent guide (this document) with all 19 tools, workflows, and platform documentation | `text/markdown` |\n| `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` |\n| `widget://*` | Widget HTML | Interactive HTML5 widgets (5 total) -- use the `apps` tool to discover and launch | `text/html` |\n\n**File download resource templates** -- read file content directly through MCP without needing external HTTP access:\n\n| URI Template | Name | Auth | Dynamic Listing | Description |\n|---|---|---|---|---|\n| `download://workspace/{workspace_id}/{node_id}` | download-workspace-file | Session token | Yes | Download a file from a workspace |\n| `download://share/{share_id}/{node_id}` | download-share-file | Session token | Yes | Download a file from a share |\n| `download://quickshare/{quickshare_id}` | download-quickshare-file | None (public) | No | Download a quickshare file |\n\nFiles 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.\n\n**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.\n\n### MCP Prompts\n\nThe 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.\n\n| Prompt Name | Description |\n|---|---|\n| `App: Choose Workspace or Org` | Launch the Workspace Picker to browse orgs, select workspaces, and manage shares |\n| `App: Pick a File` | Launch the File Picker with built-in workspace navigator for browsing, searching, and selecting files |\n| `App: Open Workflow` | Launch the Workflow Manager (auto-selects workspace if only one, otherwise opens Workspace Picker first) |\n| `App: Available Apps` | List all available MCP App widgets with descriptions and launch instructions |\n\n### HTTP File Pass-Through\n\nFor 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:\n\n| Endpoint | Auth | Description |\n|---|---|---|\n| `GET /file/workspace/{workspace_id}/{node_id}` | `Mcp-Session-Id` header | Stream a workspace file |\n| `GET /file/share/{share_id}/{node_id}` | `Mcp-Session-Id` header | Stream a share file |\n| `GET /file/quickshare/{quickshare_id}` | None (public) | Stream a quickshare file |\n\nThe 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.\n\n### Workflow Overview\n\nThe 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.\n\n**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.\n\n### Additional References\n\n- **Agent guide (this file):** `/skill.md` on the MCP server -- tool documentation, workflows, and constraints.\n- **REST API reference:** `https://api.fast.io/llms.txt` -- endpoint documentation for the underlying Fast.io API.\n- **Platform guide:** [references/REFERENCE.md](references/REFERENCE.md) -- capabilities, agent plan details, key workflows, and upgrade paths.\n\n---\n\n## 2. Authentication (Critical First Step)\n\nAuthentication is required before calling any tool except these unauthenticated tools:\n\n- `auth` with actions: `signin`, `signup`, `set-api-key`, `pkce-login`, `email-check`, `password-reset-request`, `password-reset`\n- `download` with action: `quickshare-details`\n\n### Choosing the Right Approach\n\nThere are three ways to use Fast.io as an agent, depending on whether you are operating autonomously or assisting an existing human user.\n\n**Option 1: Autonomous Agent -- Create an Agent Account**\n\nIf 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.\n\n**Option 2: Assisting a Human -- Use Their API Key**\n\nIf 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`.\n\n**Option 3: Agent Account Invited to a Human's Org**\n\nIf 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.\n\n**Option 4: Browser Login (PKCE)**\n\nIf 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.\n\nPKCE 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:\n\n| scope_type | Access granted |\n|------------|---------------|\n| `user` | Full account access (default) |\n| `org` | User selects specific organizations |\n| `workspace` | User selects specific workspaces |\n| `all_orgs` | All organizations the user belongs to |\n| `all_workspaces` | All workspaces the user has access to |\n| `all_shares` | All shares the user is a member of (`share:*:`) |\n\n**Scope inheritance:** Broader scopes include access to child entities automatically:\n\n- `all_orgs` includes all orgs + all workspaces + all shares within those orgs\n- `all_workspaces` includes all workspaces + all shares within those workspaces\n- `org` scope on a specific org includes access to all workspaces and shares within that org\n- `workspace` scope on a specific workspace includes access to shares within that workspace\n- `all_shares` grants direct access to all shares the user has membership in, bypassing workspace/org inheritance\n\nThe `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.\n\n**Approval flow by scope_type:**\n\n- **`user`** (default): Full account access. The user sees a simple approve/decline prompt with no entity picker.\n- **`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.\n- **`all_orgs`**, **`all_workspaces`**, **`all_shares`**: The user sees a summary of the wildcard access being requested (no entity picker), then approves or declines.\n\nThe MCP server defaults to `scope_type=\"user\"` for backward compatibility.\n\n| Scenario | Recommended Approach |\n|----------|---------------------|\n| Operating autonomously, storing files, building for users | Create an agent account with your own org (Option 1) |\n| Helping a human manage their existing account | Ask the human to create an API key for you (Option 2) |\n| Working within a human's org with your own identity | Create an agent account, have the human invite you (Option 3) |\n| Building something to hand off to a human | Create an agent account, build it, then transfer the org (Option 1) |\n| Signing in without sending a password through the agent | Browser-based PKCE login (Option 4) |\n\n**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`.\n\n### Standard Sign-In Flow\n\n1. Call `auth` with action `signin`, `email` and `password`.\n2. The server returns a JWT `auth_token` and stores it in the session automatically.\n3. All subsequent tool calls use this token without any manual passing.\n\n### Agent Account Creation\n\nWhen 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:\n\n- `account_type` set to `\"agent\"`\n- Free agent plan assigned automatically\n- Transfer/claim workflow enabled for handing orgs off to humans\n\n**Steps:**\n\n1. Optionally call `auth` action `email-check` with the desired `email` to verify it is available for registration before attempting signup.\n2. Call `auth` action `signup` with `first_name`, `last_name`, `email`, and `password`. The `agent=true` flag is sent automatically by the MCP server.\n3. The account is created and a session is established automatically -- the agent is signed in immediately.\n4. **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.\n5. No credit card is required. No trial period. No expiration. The account persists indefinitely.\n\n### Two-Factor Authentication Flow\n\n1. Call `auth` action `signin` with `email` and `password`.\n2. If the response includes `two_factor_required: true`, the returned token has limited scope.\n3. Call `auth` action `2fa-verify` with the 2FA `code` (TOTP, SMS, or WhatsApp).\n4. The server replaces the limited-scope token with a full-scope token automatically.\n\n### Browser Login (PKCE) Flow\n\n1. 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).\n2. The tool returns a `login_url` -- present it to the user to open in a browser.\n3. The user signs in (email/password or SSO).\n4. 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.\n5. The user clicks Approve. The browser displays an authorization code. The user copies it.\n6. Call `auth` action `pkce-complete` with the `code` to exchange it for an access token.\n7. 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.\n\n### Checking Session Status\n\n- `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.\n- `auth` action `check` -- validates the token against the Fast.io API. Returns the user ID if the token is still valid.\n\n### Session Expiry\n\nJWT 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.\n\n**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.\n\n### Signing Out\n\nCall `auth` action `signout` to clear the stored session from the Durable Object.\n\n---\n\n## 3. Core Concepts\n\n### Organizations\n\nOrganizations 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:\n\n- **Workspaces** — the file storage containers that belong to the organization.\n- **Members** with roles: owner, admin, member, guest, view.\n- **Billing and subscriptions** managed through Stripe integration.\n- **Plan limits** that govern storage, transfer, AI tokens, and member counts.\n\nOrganizations are identified by a 19-digit numeric profile ID or a domain string.\n\n**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.\n\n#### Org Discovery (IMPORTANT)\n\nTo discover all available orgs, agents **must call both actions**:\n\n1. `org` action `list` -- returns internal orgs where you are a direct member (`member: true`)\n2. `org` action `discover-external` -- returns external orgs you access via workspace membership only (`member: false`)\n\n**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.\n\n#### Internal vs External Orgs\n\n**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.\n\n**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.\n\n**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.\n\n### Workspaces\n\nWorkspaces are file storage containers within organizations. Each workspace has:\n\n- Its own set of **members** with roles (owner, admin, member, guest).\n- A **storage tree** of files and folders (storage nodes).\n- Optional **AI features** for RAG-powered chat.\n- **Shares** that can be created within the workspace.\n- **Archive/unarchive** lifecycle management.\n- **50 GB included storage** on the free agent plan, with files up to 1 GB per upload.\n- **File versioning** -- every edit creates a new version, old versions are recoverable.\n- **Full-text and semantic search** -- find files by name or content, and documents by meaning.\n\nWorkspaces are identified by a 19-digit numeric profile ID.\n\n#### Intelligence: On or Off\n\nWorkspaces have an **intelligence** toggle that controls whether AI features are active:\n\n**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.\n\n**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:\n\n- **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.\n- **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.\n- **Auto-summarization** -- short and long summaries generated for every indexed document and code file, searchable and visible in the UI.\n- **Metadata extraction** -- AI pulls key metadata from documents automatically.\n\n> **Coming soon:** RAG indexing support for images, video, and audio files. Currently only documents and code are indexed.\n\nIntelligence 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.\n\n**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.\n\nFor full details on AI chat types, file context modes, AI state, and how intelligence affects them, see the **AI Chat** section below.\n\n### Shares\n\nShares are purpose-built spaces for exchanging files with people outside your workspace. They can exist within workspaces and have three types:\n\n| Mode | What It Does | Agent Use Case |\n|------|-------------|----------------|\n| **Send** | Recipients can download files | Deliver reports, exports, generated content |\n| **Receive** | Recipients can upload files | Collect documents, datasets, user submissions |\n| **Exchange** | Both upload and download | Collaborative workflows, review cycles |\n\n#### Share Features\n\n- **Password protection** -- require a password for link access\n- **Expiration dates** -- shares auto-expire after a set period\n- **Download controls** -- enable or disable file downloads\n- **Access levels** -- Members Only, Org Members, Registered Users, or Public (anyone with the link)\n- **Custom branding** -- background images, gradient colors, accent colors, logos\n- **Post-download messaging** -- show custom messages and links after download\n- **Up to 3 custom links** per share for context or calls-to-action\n- **Guest chat** -- let share recipients ask questions in real-time\n- **AI-powered auto-titling** -- shares automatically generate smart titles from their contents\n- **Activity notifications** -- get notified when files are sent or received\n- **Comment controls** -- configure who can see and post comments (owners, guests, or both)\n\n#### Two Storage Modes\n\nWhen creating a share with `share` action `create`, the `storage_mode` parameter determines how files are stored:\n\n- **`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.\n\n- **`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.\n\nBoth 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).\n\nShares are identified by a 19-digit numeric profile ID.\n\n**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.\n\n### Storage Nodes\n\nFiles 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.\n\nKey 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).\n\nNodes have versions. Each file modification creates a new version. Version history can be listed and files can be restored to previous versions.\n\n### Notes\n\nNotes 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\"`.\n\n#### Creating and Updating Notes\n\nCreate notes with `workspace` action `create-note` and update with `workspace` action `update-note`.\n\n**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).\n\n**Updating:** Provide `workspace_id`, `node_id`, and at least one of `name` (must end in `.md`) or `content` (max 100 KB).\n\n| Constraint | Limit |\n|------------|-------|\n| Content encoding | Valid UTF-8 (UTF8MB4). Invalid byte sequences and control characters (`\\p{C}` except `\\t`, `\\n`, `\\r`) are stripped. |\n| Content size | 100 KB max |\n| Filename | 1-100 characters, must end in `.md` |\n| Markdown validation | Code blocks and emphasis markers must be balanced |\n| Rate limit | 2 per 10s, 5 per 60s |\n\n#### Notes as Long-Term Knowledge Grounding\n\nIn 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.\n\nWhen 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.\n\nKey behaviors:\n\n- Notes are ingested for RAG when workspace intelligence is enabled\n- Notes within a folder scope are included in scoped queries\n- Notes with `ai_state: ready` are searchable via RAG\n- Notes can also be attached directly to a chat via `files_attach` (check `ai.attach` is `true` in storage details)\n\n**Use cases:**\n\n- Store project context, decisions, and rationale. Months later, ask \"Why did we choose vendor X?\" and the AI retrieves the note.\n- Save research findings in a note. Future AI chats automatically use those findings as grounding.\n- Create reference documents (style guides, naming conventions) that inform all future AI queries in the workspace.\n\n#### Other Note Operations\n\nNotes 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`).\n\n#### Linking Users to Notes\n\n- **Note in workspace context** (opens workspace with note panel): `https://{domain}.fast.io/workspace/{folder_name}/storage/root?note={note_id}`\n- **Note preview** (standalone view): `https://{domain}.fast.io/workspace/{folder_name}/preview/{note_id}`\n\n### AI Chat\n\nAI chat lets agents ask questions about files stored in workspaces and shares. Two chat types are available, each with different file context options.\n\n**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.\n\n#### Two Chat Types\n\n- **`chat`** — Basic AI conversation with no file context from the workspace index. Use for general questions only.\n- **`chat_with_files`** — AI grounded in your files. Two mutually exclusive modes for providing file context:\n - **Folder/file scope (RAG)** — limits the retrieval search space. Requires intelligence enabled; files must be in `ready` AI state.\n - **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.\n\nBoth types augment answers with web knowledge when relevant.\n\n#### File Context: Scope vs Attachments\n\nFor `chat_with_files`, choose one of these mutually exclusive approaches:\n\n| Feature | Folder/File Scope (RAG) | File Attachments |\n|---------|------------------------|------------------|\n| How it works | Limits RAG search space | Files read directly by AI |\n| Requires intelligence | Yes | No |\n| File readiness requirement | `ai_state: ready` | `ai.attach: true` |\n| Best for | Many files, knowledge retrieval | Specific files, direct analysis |\n| Max references | 100 folder refs (subfolder tree expansion) or 100 file refs | 20 files / 200 MB |\n| Default (no scope given) | Entire workspace | N/A |\n\n**Scope parameters** (REQUIRES intelligence — will error if intelligence is off):\n\n- `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.\n- `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.\n- **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.\n\n**Attachment parameter** (no intelligence required):\n\n- `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.\n\n**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.\n\n**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).\n\n`files_scope`/`folders_scope` and `files_attach` are mutually exclusive — sending both will error.\n\n#### Intelligence and AI State\n\nThe 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:\n\n| State | Meaning |\n|-------|---------|\n| `disabled` | AI processing disabled for this file |\n| `pending` | Queued for processing |\n| `in_progress` | Currently being ingested and indexed |\n| `ready` | Complete — available for folder/file scope queries |\n| `failed` | Processing failed |\n\nOnly files with `ai_state: ready` are included in folder/file scope searches. Check file state via `storage` action `details` with `context_type: \"workspace\"`.\n\n#### Attachability — the `ai.attach` Flag\n\nFile nodes in storage list/details responses include an `ai` object with three fields:\n\n| Field | Type | Meaning |\n|-------|------|---------|\n| `ai.state` | string | AI indexing state (`disabled`, `pending`, `inprogress`, `ready`, `failed`) |\n| `ai.attach` | boolean | Whether the file can be used with `files_attach` |\n| `ai.summary` | boolean | Whether the file already has an AI-generated summary |\n\n**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.\n\nThis flag is independent of the workspace intelligence setting — a file can have `ai.attach: true` even when intelligence is off.\n\n**When to enable intelligence:** You need scoped RAG queries, cross-file search, auto-summarization, or a persistent knowledge base.\n\n**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).\n\nEven with intelligence off, `chat_with_files` with file attachments still works for files with `ai.attach: true`.\n\n#### How to Phrase Questions\n\n**With folder/file scope (RAG):** Write questions likely to match content in indexed files. The AI searches the scope, retrieves passages, and cites them.\n\n- Good: \"What are the payment terms in the vendor contracts?\"\n- Good: \"Summarize the key findings from the Q3 analysis reports\"\n- Bad: \"Tell me about these files\" — too vague, no specific content to match\n- Bad: \"What's in this workspace?\" — cannot meaningfully search for \"everything\"\n\n**With file attachments:** Be direct — the AI reads the full file content. No retrieval step.\n\n- \"Describe this image in detail\"\n- \"Extract all dates and amounts from this invoice\"\n- \"Convert this CSV data into a summary table\"\n\n**Personality:** The `personality` parameter controls the tone and length of AI responses. Pass it when creating a chat or sending a message:\n\n- `concise` — short, brief answers\n- `detailed` — comprehensive answers with context and evidence (default)\n\nUse `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.\n\n**Controlling verbosity in questions:** You can also guide verbosity through how you phrase the question itself:\n\n- \"In one sentence, what is the main conclusion of this report?\"\n- \"List only the file names that mention GDPR compliance, no explanations\"\n- \"Give me a brief summary — 2-3 bullet points max\"\n\nCombining `personality: \"concise\"` with a direct question produces the shortest answers and uses the fewest AI credits.\n\n#### Chat Parameters\n\nCreate a chat with `ai` action `chat-create` (with `context_type: \"workspace\"`) or `ai` action `chat-create` (with `context_type: \"share\"`):\n\n- `type` (required) — `chat` or `chat_with_files`\n- `query_text` (required for workspace, optional","readmeExcerpt":"Skill: Fast.io Owner: dbalve Summary: Workspaces for agentic teams. Complete agent guide with all 19 consolidated tools using action-based routing — parameters, workflows, ID formats, and constra... Tags: ai-chat:1.15.0, collaboration:1.15.0, file-sharing:1.15.0, latest:1.105.0, latest cloud-storage:1.15.0, mcp:1.15.0, productivity:1.15.0, rag:1.15.0 Version history: v1.105.0 | 2026-02-26T23:38:17.549Z | user fast-io","codeSnippets":[],"executableExamples":[{"language":"json","snippet":"{\n \"pagination\": {\n \"total\": 42,\n \"limit\": 100,\n \"offset\": 0,\n \"has_more\": false\n }\n}"},{"language":"text","snippet":"# First page\nGET /current/orgs/list/?limit=10&offset=0\n# → pagination.has_more = true, pagination.total = 42\n\n# Second page\nGET /current/orgs/list/?limit=10&offset=10\n# → pagination.has_more = true\n\n# Continue until has_more = false"},{"language":"text","snippet":"POST /current/upload/\nContent-Type: multipart/form-data\n\nFields: org, name, size, action=create, instance_id, folder_id, chunk (file)\n→ Response: { \"result\": true, \"id\": \"session-id\", \"new_file_id\": \"2abc...\" }"},{"language":"text","snippet":"POST /current/workspace/{id}/storage/{folder}/addfile/\nBody: from={\"type\":\"upload\",\"upload\":{\"id\":\"{session_id}\"}}"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: fast-io\ndescription: >-\n Workspaces for agentic teams. Complete agent guide with all 19 consolidated\n tools using action-based routing — parameters, workflows, ID formats, and\n constraints. Use this skill when agents need shared workspaces to collaborate\n with other agents and humans, create branded shares (Send/Receive/Exchange),\n or query documents using built-in AI. Supports ownership transfer to humans,\n workspace management, workflow primitives (tasks, worklogs, approvals, todos),\n and real-time collaboration.\n Free agent plan with 50 GB storage and 5,000 monthly credits.\nlicense: Proprietary\ncompatibility: >-\n Requires network access. Connects to the Fast.io MCP server at mcp.fast.io\n via Streamable HTTP (/mcp) or SSE (/sse).\nmetadata:\n author: fast-io\n version: \"1.105.0\"\nhomepage: \"https://fast.io\"\n---\n\n# Fast.io MCP Server -- AI Agent Guide\n\n**Version:** 1.104\n**Last Updated:** 2026-02-26\n\nThe 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.\n\n> **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.\n\n> **Platform reference.** For a comprehensive overview of Fast.io's capabilities, the agent plan, key workflows, and upgrade paths, see [references/REFERENCE.md](references/REFERENCE.md).\n\n---\n\n## 1. Overview\n\n**Workspaces for Agentic Teams. Collaborate, share, and query with AI -- all through one API, free.**\n\nFast.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.\n\n### The Problem Fast.io Solves\n\nAgentic 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.\n\nWhen 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?\"\n\n| Problem | Fast.io Solution |\n|---------|------------"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn74d15nyw6rzrc3fekbs5333d80ha0y\",\n \"slug\": \"fast-io\",\n \"version\": \"1.105.0\",\n \"publishedAt\": 1772149097549\n}"},{"path":"references/REFERENCE.md","content":"# Fast.io for AI Agents\n\n> **Version:** 1.25.0 | **Last updated:** 2026-02-21\n>\n> This guide is available at the `/current/agents/` endpoint on the connected API server.\n\n**Workspaces for Agentic Teams. Collaborate, share, and query with AI — all through one API, free.**\n\nFast.io provides workspaces for agentic teams — where agents collaborate with other agents and with humans. Upload\noutputs, create branded data rooms, ask questions about documents using built-in AI, and hand everything off to a human\nwhen the job is done. No infrastructure to manage, no subscriptions to set up, no credit card required.\n\n**MCP-enabled agents** should connect via the Model Context Protocol for the simplest integration — no raw HTTP calls\nneeded.\n\n**Connection endpoints:**\n- **Streamable HTTP (recommended):** `https://mcp.fast.io/mcp`\n- **Legacy SSE:** `https://mcp.fast.io/sse`\n\nThe MCP server exposes **19 consolidated tools** using action-based routing — each tool covers a domain (e.g., `auth`,\n`storage`, `upload`) and uses an `action` parameter to select the operation. See the \"MCP Tool Architecture\" section\nbelow for the full tool list.\n\nMCP-connected agents receive comprehensive workflow guidance through SERVER_INSTRUCTIONS at connection time, and can\nread resources (`resources/read`) including `skill://guide` for full tool documentation, `session://status` for current\nauthentication state, and `download://` resource templates for direct file content retrieval.\n\nThis guide covers platform concepts and capabilities; the MCP server provides tool-level details through its standard\nprotocol interface. The API endpoints referenced below are what the MCP server calls under the hood, and are available\nfor agents that need direct HTTP access or capabilities not yet covered by the MCP tools.\n\n---\n\n## Why Agents Use Fast.io\n\n### The Problem\n\nAgentic teams — groups of agents working together and with humans — need a shared place to work. Today, agents cobble\ntogether S3 buckets, presigned URLs, email attachments, and custom download pages. Every agent reinvents collaboration,\nand there's no shared workspace where agents and humans can see the same files, track activity, and hand off work.\n\nMeanwhile, when agents need to *understand* documents — not just store them — they have to download files, parse dozens\nof formats, build search indexes, and manage their own RAG pipeline. That's a lot of infrastructure for what should be a\nsimple question: \"What does this document say?\"\n\n### What Fast.io Solves\n\n| Problem | Fast.io Solution |\n|----------------------------------------------|---------------------------------------------------------------------------------------------------|\n| No shared workspace for agentic teams | Workspaces where agents and humans collaborate with file preview, versioning, and AI |\n| Agent-to-agent coordination lack"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1831,"uniquenessScore":37,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"agent-directory","verified":false,"confidence":"low","updatedAt":"2026-10-09T17:15:43.540Z","emptyReason":"No close protocol neighbors were found."},"items":[],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[]}}}