Fast.io API Documentation Workspaces for Agentic Teams. Collaborate, share, and query with AI — all through one API, free.

Fast.io provides workspaces for agentic teams — where agents collaborate with other agents and with humans. Upload outputs, create branded portals, 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, no credit card required.

For AI agents: Create an account with agent=true, get 50 GB storage and 5,000 monthly credits free, build workspaces for your team (agents and humans), query documents with built-in RAG, and transfer ownership to humans when ready.

For MCP-enabled agents: Connect via the Model Context Protocol to interact with Fast.io workspaces, shares, files, and storage directly. Connect to https://mcp.fast.io/mcp (Streamable HTTP) or https://mcp.fast.io/sse (legacy SSE). The server exposes 19 consolidated tools with action-based routing.

Detailed API References

What Fast.io Does

Agent Plan (Free)

Credits cover: storage (100/GB), bandwidth (212/GB), AI tokens (1/100 tokens), document ingestion (10/page), video ingestion (5/sec), image ingestion (5/image), file conversions (25/each). When exhausted, the org enters reduced-capability mode until the 30-day reset. The org is never deleted.

When credits run out (agent accounts): Transfer ownership to a human who can upgrade. Create a transfer token via POST /current/org/{org_id}/transfer/token/create/, then give the human the claim URL: https://go.fast.io/claim?token={token}. See Organizations reference for details.

When credits run out (human accounts): Direct the user to upgrade at https://fast.io or via POST /current/org/{org_id}/billing/.

Profile Hierarchy

User (Type 1) → Organization (Type 2) → Workspace (Type 3) / Share (Type 4)

Users own organizations. An organization is a collector of workspaces — it can represent a company, a business unit, a team, or simply a personal collection. Organizations own workspaces and shares. Users can also directly own shares.

All profile IDs are 19-digit numeric strings (e.g., "1234567890123456789"). Most endpoints also accept a custom name in place of the numeric ID.

Account types: human or agent — visible in all user objects via account_type field.

Authentication

All authenticated endpoints require: Authorization: Bearer {jwt_token}

Four methods:

• Basic Auth → JWT: GET /current/user/auth/ with HTTP Basic Auth. Returns JWT. If 2FA enabled, token has limited scope until verified.
• OAuth 2.0 PKCE: For desktop/mobile apps and MCP agents. S256 only. Supports Dynamic Client Registration (RFC 7591), CIMD for URL-based client_id, and Resource Indicators (RFC 8707). See OAuth reference.
• API Keys: Long-lived tokens. Same Bearer header. Create via POST /current/user/auth/key/. Optionally supports scoped permissions, agent names, and expiration. Update via POST /current/user/auth/key/{id}/.
• 2FA: Limited-scope token → full token after POST /current/user/auth/2factor/auth/{token}/.

Choose your access pattern

1. Human's account — Human creates API key, gives it to you. You operate as them. → Auth reference
2. Autonomous agent — Create agent account (agent=true), create org, work independently. → Auth reference
3. Collaboration — Create agent account, human invites you to their org/workspace. → Auth reference
4. PKCE browser login — Secure, no password sharing, supports SSO. → OAuth reference

Response Envelope

Success (data fields at root level):

{"result": true, "status": "ok", ...}

Error:

{
  "result": false,
  "error": {
    "code": 195654,
    "text": "Human-readable message",
    "documentation_url": "https://api.fast.io/llms.txt",
    "resource": "POST /current/user/"
  }
}

• result: boolean — true on success, false on error
• error.code: Unique error identifier (integer) for debugging
• error.text: Human-readable error message, safe to display
• error.documentation_url: Link to error documentation (string or null)
• error.resource: The endpoint that produced the error

Error Codes

Client Errors

Billing & Credit Errors

Server Errors

Rate Limiting

Headers: X-Rate-Limit-Available, X-Rate-Limit-Expiry, X-Rate-Limit-Max

When exceeded: HTTP 429 with error code 1671 (1671 (Rate Limited)).

Pagination

Offset Pagination (List Endpoints)

Most list endpoints support offset-based pagination:

• limit: 1–500 (default: 100) — number of items to return
• offset: 0+ (default: 0) — number of items to skip
• Response: pagination.total, pagination.limit, pagination.offset, pagination.has_more

Keyset Pagination (Storage List Endpoints)

Storage listing uses cursor-based pagination:

• sort_by: name | updated | created | type (default: name)
• sort_dir: asc | desc (default: asc)
• page_size: 100 | 250 | 500 (default: 100)
• cursor: opaque string from previous response
• Response: pagination.has_more, pagination.next_cursor, pagination.page_size

ID Formats

• Profile IDs (user, org, workspace, share): 19-digit numeric string
• Node IDs (files, folders): OpaqueId — 30-character alphanumeric with hyphens (e.g., f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4). Prefix: f = file, d = folder, n = note.
• Upload IDs: OpaqueId — alphanumeric string
• Opaque IDs (quickshare tokens): 30-character alphanumeric string
• Special folder aliases: "root" for storage root, "trash" for trash folder

Custom names as identifiers

Field Constraints

Profile fields (org, workspace, share) have validation rules enforced server-side.

Agent Workflows

Upload Files

Small files (< 4MB): single-request upload. Large files: chunked upload with parallel chunks.

→ Full details: Upload reference

Query Documents with AI

Create chats with chat (general) or chat_with_files (RAG with citations). Stream responses via SSE.

→ Full details: AI reference

Share Files with Humans

Create Send/Receive/Exchange shares with Portal or Shared Folder storage modes.

→ Full details: Shares reference

Transfer Ownership to a Human

Agent creates transfer token → build claim URL https://go.fast.io/claim?token={token} → human claims org.

→ Full details: Organizations reference

Monitor Usage

• GET /current/org/{org_id}/billing/usage/limits/credits/ — credit consumption
• GET /current/org/{org_id}/billing/usage/meters/list/ — detailed breakdown
• GET /current/events/search/ — activity feed

→ Full details: Events reference

Activity Polling

Long-poll for changes instead of looping on individual endpoints:

GET /current/activity/poll/{entityId}?wait=95&lastactivity={timestamp}

→ Full details: Events reference

Endpoint Summary

System

Category References

Common Patterns

• List endpoints return arrays in a response wrapper with consistent pagination
• All profile operations require membership with sufficient permissions
• Owner > Admin > Member > Guest permission hierarchy
• "me" can be used as user_id to reference the authenticated user
• Profile path parameters accept either a 19-digit numeric ID or a custom name
• Storage operations (workspace and share) follow identical patterns
• AI chat endpoints (workspace and share) follow identical patterns
• Member management endpoints (org, workspace, share) follow identical patterns
• Long-polling supported on activity/poll and upload/details endpoints
• Most POST endpoints use application/x-www-form-urlencoded bodies; comments use application/json

Additional Resources

• Full single-file reference: https://api.fast.io/current/llms/full/
• Agent integration guide: available at /current/agents/
• MCP Server: https://mcp.fast.io/mcp (Streamable HTTP) or https://mcp.fast.io/sse (legacy SSE)
• MCP Skills: available at /skill.md on the MCP server
• Claim URL for org transfer: https://go.fast.io/claim?token={token}