# Fast.io

> Workspaces for Agentic Teams. Collaborate, share, and query with AI — all through one API, free.
>
> Base URL: https://api.fast.io/current/
> Version: 1.0
> Request format: `application/x-www-form-urlencoded` (most POST bodies) or query string (GET). Some endpoints accept `application/json` bodies — notably comments and endpoints with nested/array parameters.
> Response format: JSON
> File uploads: `multipart/form-data`
> Document version: 2.0
> Last updated: 2026-02-12
> Full reference (single file): https://api.fast.io/current/llms/full/
> Agent integration guide: available at the `/current/agents/` endpoint on the connected API server
> MCP Server (AI Agents): connect via the Model Context Protocol for tool access
> MCP Streamable HTTP endpoint: https://mcp.fast.io/mcp
> MCP Legacy SSE endpoint: https://mcp.fast.io/sse
> MCP Skills & Tool Definitions: available at the `/skill.md` endpoint on the connected MCP server

Fast.io provides workspaces for agentic teams — where agents collaborate with other agents and with humans. Upload outputs, create branded data rooms, ask questions about documents using built-in AI, and hand everything off to a human when the job is done. No infrastructure to manage, no subscriptions, 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. See the [Agent Integration Guide](https://fast.io/agents.md) for workflows and examples.

**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 14 consolidated tools with action-based routing (e.g., `auth`, `storage`, `upload`), each annotated with MCP hints (`title`, `readOnlyHint`, `destructiveHint`). Resources (`skill://guide`, `session://status`) and guided prompts for common workflows are also available. The MCP server provides a `/skill.md` endpoint with available tools and skill definitions.

## Detailed API References

This file is a concise overview. For complete endpoint documentation with parameters, response fields, and examples, see the category-specific references:

| Category | URL | What It Covers |
|----------|-----|----------------|
| **Auth & Users** | https://api.fast.io/current/llms/auth/ | Authentication methods, user CRUD, getting started patterns |
| **OAuth 2.0** | https://api.fast.io/current/llms/oauth/ | PKCE flow, token exchange, session management, DCR, resource indicators |
| **Organizations** | https://api.fast.io/current/llms/orgs/ | Org CRUD, members, billing, transfer (agent→human), discovery |
| **Workspaces** | https://api.fast.io/current/llms/workspaces/ | Workspace CRUD, members, assets, discovery |
| **Storage** | https://api.fast.io/current/llms/storage/ | File/folder operations, locking, previews, transforms |
| **Shares** | https://api.fast.io/current/llms/shares/ | Share types, storage modes, members, branding, quickshare |
| **Upload** | https://api.fast.io/current/llms/upload/ | Chunked upload flow, web upload, status polling |
| **AI & Chat** | https://api.fast.io/current/llms/ai/ | RAG chat, intelligence, notes, metadata extraction |
| **Events & Activity** | https://api.fast.io/current/llms/events/ | Event search, activity polling, WebSocket, realtime |
| **Comments** | https://api.fast.io/current/llms/comments/ | Threading, mentions, reactions, JSON body format |
| **Full Reference** | https://api.fast.io/current/llms/full/ | All endpoints in a single file |

## What Fast.io Does

Fast.io is the workspace platform for agentic teams — where agents work with other agents and with humans.

| Capability | What It Does |
|-----------|-------------|
| **Workspaces** | Shared workspaces for agentic teams with file versioning, search, and AI chat |
| **Shares** | Purpose-built spaces for agent-human exchange with two storage modes: **Room** (independent data room with passwords, expiration, guest access) or **Shared Folder** (live-synced workspace folder). Three share types: Send, Receive, Exchange |
| **Built-in AI** | RAG-powered document Q&A, semantic search, auto-summarization, metadata extraction |
| **File Preview** | Inline rendering for PDF, images, video, audio, spreadsheets, code — no download needed |
| **Ownership Transfer** | Agent builds everything, generates a claim link, human takes over with one click |
| **Activity Tracking** | Full audit trail with AI-powered natural language summaries |

## Agent Plan (Free)

| Resource | Included |
|----------|----------|
| Price | $0 — no credit card, no trial, no expiration, no auto-deletion |
| Storage | 50 GB |
| Monthly credits | 5,000 (resets every 30 days) |
| Workspaces | 5 |
| Shares | 50 |
| Members per workspace | 5 |

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](https://api.fast.io/current/llms/orgs/) 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 — see ID Formats below.
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), Client ID Metadata Document (CIMD) for URL-based client_id, and Resource Indicators (RFC 8707). See [OAuth reference](https://api.fast.io/current/llms/oauth/).
- **API Keys:** Long-lived tokens. Same Bearer header. Create via `POST /current/user/auth/key/`.
- **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](https://api.fast.io/current/llms/auth/)
2. **Autonomous agent** — Create agent account (`agent=true`), create org, work independently. → [Auth reference](https://api.fast.io/current/llms/auth/)
3. **Collaboration** — Create agent account, human invites you to their org/workspace. → [Auth reference](https://api.fast.io/current/llms/auth/)
4. **PKCE browser login** — Secure, no password sharing, supports SSO. → [OAuth reference](https://api.fast.io/current/llms/oauth/)

## Response Envelope

Success (data fields at root level):
```json
{"result": true, "status": "ok", ...}
```

Error:
```json
{"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:
- 1605 APP_ERROR_INPUT_INVALID → 406 Not Acceptable
- 1607 APP_ERROR_INPUT_DUPLICATE → 406 Not Acceptable
- 1650 APP_AUTH_INVALID → 401 Unauthorized
- 1651 APP_REQUEST_TYPE → 405 Method Not Allowed
- 1609 APP_ERROR_NOT_FOUND → 404 Not Found
- 1652 APP_RESOURCE_NOT_FOUND → 404 Not Found
- 1653 APP_USER_NOT_FOUND → 404 Not Found
- 1656 APP_EXCEEDED_LIMIT → 413 Payload Too Large
- 1667 APP_MAX_LIMIT → 429 Too Many Requests
- 1685 APP_FEATURE_LIMIT → 412 Precondition Failed
- 1658 APP_NOT_ACCEPTABLE → 406 Not Acceptable
- 1660 APP_CONFLICT → 409 Conflict
- 1669 APP_EXISTS → 409 Conflict
- 1670 APP_RESTRICTED → 406 Not Acceptable
- 1680 APP_DENIED → 401 Unauthorized
- 1671 APP_ENHANCE_CALM → 429 Too Many Requests
- 1677 APP_LOCKED → 423 Locked

Server errors:
- 1654 APP_INTERNAL_ERROR → 500
- 1664 APP_ERROR_DATASTORE → 500
- 1686 APP_ERROR_NOT_IMPLEMENTED → 501

## Rate Limiting

Headers: `X-Rate-Limit-Available`, `X-Rate-Limit-Expiry`, `X-Rate-Limit-Max`
When exceeded: HTTP 429 with error code 1671 (APP_ENHANCE_CALM).

## 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:** Most endpoints that accept a profile ID also accept a custom name:

| Profile Type | Custom Name |
|-------------|-------------|
| Workspace | Folder name (e.g., `my-project`) |
| Share | URL name (e.g., `q4-financials`) |
| Organization | Domain name (e.g., `acme`) |
| User | Email address (e.g., `user@example.com`) |

## Agent Workflows

### Upload Files
Small files (< 4MB): single-request upload. Large files: chunked upload with parallel chunks.
→ Full details: [Upload reference](https://api.fast.io/current/llms/upload/)

### Query Documents with AI
Create chats with `chat` (general) or `chat_with_files` (RAG with citations). Stream responses via SSE.
→ Full details: [AI reference](https://api.fast.io/current/llms/ai/)

### Share Files with Humans
Create Send/Receive/Exchange shares with Room or Shared Folder storage modes.
→ Full details: [Shares reference](https://api.fast.io/current/llms/shares/)

### 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](https://api.fast.io/current/llms/orgs/)

### 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](https://api.fast.io/current/llms/events/)

### 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](https://api.fast.io/current/llms/events/)

## Endpoint Summary

### System
- `GET /current/ping/` — Health check (no auth)
- `GET /current/system/status/` — System status (no auth)
- `GET /current/llms/` — This reference file (no auth)
- `GET /current/agents/` — Agent integration guide (no auth)
- `GET /.well-known/oauth-authorization-server/` — OAuth authorization server metadata (RFC 8414, no auth)
- `GET /.well-known/oauth-protected-resource/` — OAuth protected resource metadata (RFC 9728, no auth)

### Users & Auth → [Auth reference](https://api.fast.io/current/llms/auth/)
User CRUD, authentication (Basic Auth, API keys, 2FA), email validation, password reset, user search.
- `GET /current/auth/scopes/` — Token scope introspection. Returns auth_type (jwt_v2, jwt_v1, api_key), scopes array, scopes_detail (hydrated with entity names/domains/parents), is_agent, agent_name, full_access. Requires auth.

### OAuth 2.0 → [OAuth reference](https://api.fast.io/current/llms/oauth/)
PKCE authorization flow, token exchange/refresh, session management, Dynamic Client Registration (RFC 7591/7592), Client ID Metadata Document (CIMD), Resource Indicators (RFC 8707), scoped access tokens (JWT v2.0).
- `GET /.well-known/oauth-authorization-server/` — Authorization server metadata (RFC 8414, no auth)
- `GET /.well-known/oauth-protected-resource/` — Protected resource metadata (RFC 9728, no auth)
- `POST /current/oauth/register/` — Dynamic client registration (no auth, rate limited)
- `PUT /current/oauth/register/` — Update client registration (localhost-only clients)

### Organizations → [Organizations reference](https://api.fast.io/current/llms/orgs/)
Org CRUD, member management, billing/subscriptions, agent→human transfer, org discovery.

### Workspaces → [Workspaces reference](https://api.fast.io/current/llms/workspaces/)
Workspace CRUD, member management, assets, intelligence setting, discovery.

### Storage → [Storage reference](https://api.fast.io/current/llms/storage/)
File/folder CRUD (both workspace and share), locking, previews, transforms, download tokens.

### Shares → [Shares reference](https://api.fast.io/current/llms/shares/)
Share CRUD, types (Send/Receive/Exchange), storage modes (Room/Shared Folder), members, branding, quickshare.

### Upload → [Upload reference](https://api.fast.io/current/llms/upload/)
Chunked upload flow, web upload (URL import), session management.

### AI & Chat → [AI reference](https://api.fast.io/current/llms/ai/)
RAG chat, general chat, notes, metadata templates, metadata extraction, SSE streaming.

### Events & Activity → [Events reference](https://api.fast.io/current/llms/events/)
Event search/filtering, activity polling, WebSocket realtime, webhooks.

### Comments → [Comments reference](https://api.fast.io/current/llms/comments/)
Comment CRUD (JSON body), threading, mentions, reactions, reference anchoring.

## 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}`