Fastio API Documentation Put your files to work — workspaces for agentic teams. Answer across your files, automate the busywork, and keep work secure and on the record. Storage is step zero.

Fastio 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.

For AI agents: Create an account (optionally with agent=true), choose a paid plan (Starter, Business, or Growth), build workspaces for your team (agents and humans), and query documents with built-in RAG. All paid plans include the AI Agent plan feature for agentic chat, RAG, and intelligence.

For MCP-enabled agents: Connect via the Model Context Protocol to interact with Fastio 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 multiple domain-specific tools with action-based routing.

Detailed API References

What Fastio Does

Storage is step zero. Fastio is organized around three things you do with your files — Intelligence, Automation, and Secure collaboration:

Building blocks:

Plans

New organizations choose one of three paid plans. All three include the content_ai and ai_agent plan features, and signing is universal across every plan.

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), workflow steps (5/completed step).

A newly created organization must select a paid plan before it can be used; until then it is in an upgrade-only state (the same state as an org that has exhausted its credits) and gated endpoints return HTTP 402.

When credits run out: Solo plans hard-stop on overage until the monthly credit reset; Business and Growth meter overage. Direct the user to upgrade or adjust the plan at https://fast.io or via POST /current/org/{org_id}/billing/.

Profile Hierarchy

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

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., "2234567890123456789"). The leading digit encodes the profile type — 2 = user, 3 = org, 4 = workspace, 5 = share. 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, ...}

Error:

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

Validation error (HTTP 406) with structured per-parameter detail:

{
  "result": false,
  "error": {
    "code": 10022,
    "text": "email: This value should not be blank.",
    "documentation_url": "https://api.fast.io/llms.txt",
    "resource": "POST /current/user/email/",
    "params": [
      {
        "name": "email",
        "kind": "missing",
        "message": "This value should not be blank.",
        "code": 10022
      }
    ]
  }
}

• result: boolean — true on success, false on error
• error.code: Unique error identifier (integer) for debugging
• error.text: Human-readable error message. Advisory; clients should prefer params for programmatic handling. Retained byte-identically for compatibility.
• error.documentation_url: Link to error documentation (string or null)
• error.resource: The endpoint that produced the error
• error.params: Array of {name, kind, message, code, expected_type?, received_alias?}. Present on validation errors (HTTP 406). Aggregates every failed parameter so callers see all problems in one round trip. kind is one of missing (required parameter omitted), invalid (value failed a constraint), or type_mismatch (value could not be decoded into the expected type). Omitted when empty.

OAuth (/current/oauth/token/, /current/oauth/revoke/, /current/oauth/register/) and the cloud-storage / billing webhook receivers retain RFC-compliant bare-JSON error envelopes (RFC 6749 §5.2 / RFC 7591). The params field is not emitted by those endpoints.

OPTIONS Introspection

OPTIONS introspection is currently supported on roughly 40% of public endpoints. Supported endpoints respond with a JSON description of their accepted parameters — source (query / body / path / header), required vs optional flag, expected type, and a summary of declared constraints (length bounds, choice set, range, equality). Use this to fetch parameter requirements before issuing a call rather than learning them from a validation-error round trip.

curl -X OPTIONS "https://api.fast.io/current/{endpoint}/" -H "Authorization: Bearer {jwt_token}"

Unsupported endpoints (OAuth, webhook receivers, and a substantial set of legacy endpoints not yet migrated) return 405 Method Not Allowed for OPTIONS. Coverage is being expanded incrementally — check via OPTIONS first; fall back to the documented schema when you receive a 405.

Error Codes

Client Errors

Billing & Credit Errors

Server Errors

Retired Per-Field Codes

As of 2026-05-05, error codes 136957, 249170, 279705, 295625 are retired. The equivalent field-level failures now surface inside error.params[] with kind: 'invalid' (and a per-field code and message describing the specific violation). Clients that previously switched on those exact integers should switch on params[].name + params[].kind instead.

Rate Limiting

Headers: x-ve-limit-avail (requests remaining), x-ve-limit-max (window cap), x-ve-limit-expires (Unix-time the window resets).

When exceeded: HTTP 429 with error code 1671 (Rate Limited). Back off until x-ve-limit-expires.

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 + Workflow Run List)

Two list endpoints support cursor-based (keyset) pagination. Storage listing always uses the cursor path; the workflow run list uses it opt-in — activate by passing any of page_size, cursor, or bucket (a bare request or limit/offset returns the legacy offset shape). A page may contain fewer than page_size items even when has_more is true — rely on has_more / next_cursor, not page fullness, to decide whether to continue.

Storage listing (GET /current/workspace/{id}/storage/):

• 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

Workflow run list (GET /current/workspace/{id}/workflows/):

• page_size: 1–100 (default: 50)
• cursor: opaque string from previous response; discard and restart whenever any filter changes
• bucket: in_flight | completed | paused | failed — filter by execution status
• Response: pagination.has_more, pagination.next_cursor, pagination.page_size; first page also returns best-effort counts

Compact Responses (output=)

Most list and detail endpoints accept an optional output query parameter that selects a response shape tuned to how much detail the caller actually needs. This is useful for agents and clients that want to minimize payload size and token usage.

• Syntax: ?output=<token> or ?output=<token>,<token> — comma-separated list of tokens.
• Detail-level tokens (mutually exclusive — pick at most one per request):
  • terse — the smallest useful shape: identifiers, primary labels, and the handful of fields needed to navigate between resources. Best for tree traversal, picker UIs, autocomplete, and any workflow that will follow up with a detail call only on user interest.
  • standard — terse plus the operational context most list and detail views actually render: timestamps, lifecycle flags, short descriptions, plan/status fields, creator/owner refs, member status, and short summaries. Recommended default for most agent list/detail workflows.
  • full — the complete resource shape; equivalent to omitting ?output= entirely. Use when you need branding, capability matrices, permission blocks, long-form AI summaries, metadata, or other rarely-read detail.
• Modifier tokens (orthogonal — may be combined with any detail level):
  • markdown — switches the response encoding from JSON to GitHub-flavored Markdown. Response Content-Type becomes text/markdown; charset=UTF-8. Works on every endpoint that returns a JSON envelope, including error responses. Arrays of same-shaped records become GFM pipe tables; associative maps become bullet lists; error envelopes are promoted to a leading # Error section. Consumers that render markdown as HTML MUST sanitize the output.
• Default behavior: When output= is absent, responses are full JSON and byte-for-byte unchanged from previous API versions — existing clients require no changes.
• Combining level tokens: Specifying more than one detail level in the same request (e.g. ?output=terse,standard) is an error and returns HTTP 406. Combine a level with modifiers only (e.g. ?output=standard,markdown).
• Unknown tokens: Silently ignored for forward compatibility. New tokens may be added without bumping the API version.
• Cumulative fields: standard is a superset of terse, and full is a superset of standard. Nothing disappears as you move up a tier.
• Scope: Applies transparently to nodes (files/folders/notes/links), events, users, workspaces, orgs, and shares wherever they appear — including when nested inside other resources.

Per-category field lists for terse and standard are documented in the relevant category reference (storage, events, orgs, workspaces, shares, auth/users).

ID Formats

• Profile IDs (user, org, workspace, share, file share): 19-digit numeric string
• Node IDs (files, folders, notes): OpaqueId — 29 alphanumeric characters, displayed in a 34-character hyphenated form (5 groups of 5 plus a final group of 4) (e.g., f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjf). Node IDs are fully opaque — clients MUST NOT parse a resource type from any part of the id, including the leading character; files, folders, and notes are not distinguishable by their id. API input accepts either the hyphenated or un-hyphenated form.
• Upload IDs / Web Upload IDs / Quickshare tokens / Chat IDs: OpaqueId — same canonical format as node IDs.
• 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

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