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 Enterprise), 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.

Credits cover: storage (150/GB), bandwidth (400/GB), AI tokens (1/100 tokens), document ingestion (10/page), video ingestion (5/sec), audio ingestion (1 per 2 sec), image ingestion (5/image), file conversions (25/each), e-signatures (100 per billable recipient, at send), cloud sync (1 per 1,000 objects scanned per sync, minimum 1 per sync), AI index (100 per 1,000 indexed vectors, sampled daily and charged on the period average, so a corpus you keep for a month costs 100 per 1,000 vectors for that month, not per day).

Plans offered before these remain in place for their existing subscribers as legacy plans (titled with a "(legacy)" suffix, for example "Starter (legacy)"); they keep their prices and allowances but can no longer be selected. A subscriber on a legacy plan can move to any current plan.

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: all current plans meter overage beyond the monthly allowance (the legacy Starter plan hard-stops until the monthly credit reset instead). 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}

Ways to get a token:

• Browser sign-in (email + password, recommended): the Fastio web app calls POST /current/user/auth/login/start/, sends the browser to the returned login_url (the Fastio sign-in page, which handles password and 2FA), and exchanges the one-time callback code with PKCE at POST /current/user/auth/login/exchange/ for a session. Returns only to Fastio’s own web origins. See Auth reference.
• Signup: POST /current/user/ returns a session (auth_token) when it creates a new account; an already-registered email gets result: true with no auth_token (check your email).
• Basic Auth → JWT (deprecated, will be retired): GET /current/user/auth/ with HTTP Basic Auth still returns a JWT today. Use browser sign-in, OAuth PKCE, or API keys instead.
• OAuth 2.0 PKCE: For desktop/mobile apps, CLIs and MCP agents — the recommended way for anything but the Fastio web app to act for a password user. 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}/. A key created without scopes stores ["user:*:rw"] — whole-account read and write, but no administration and no account settings (those need rwa scopes and the userdetails:*:rw scope respectively).
• 2FA: Handled on the sign-in page for browser sign-in and OAuth. On the deprecated Basic Auth login: 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. Your own account — Sign up (email + password, optionally agent=true) — the signup response carries your session — then use that session to create an org and select a paid plan (a default API key cannot do admin billing operations); create an API key afterwards for ongoing access. → Auth reference
3. Collaboration — Sign up, then a 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) from endpoints that use structured parameter validation, and on some conflicts (HTTP 409). Not every 406 carries it, so always fall back to error.text. On some refusals — certain 406s, and the 403 / 503 refusals described under Error Codes — params is instead an object carrying reason; check Array.isArray(params) before reading it. 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), type_mismatch (value could not be decoded into the expected type), unknown_parameter (the parameter is not part of the accepted set for this request — stop sending it rather than correcting its value), or conflict (the value was well formed, but the state it referred to has since changed). Omitted when empty. Treat kind as open-ended: handle an unrecognised value as a generic failure rather than rejecting the response.
• Conflict entries (HTTP 409). A conflict entry names the parameter whose precondition no longer holds and carries a reason naming the cause — currently conflict_version_mismatch, meaning the resource changed since the version you supplied. Branch on params[].reason — the only field that names the cause. params[].name + params[].kind is a fallback for clients receiving only the four standard fields: it identifies a failed precondition on that parameter, not which one, so treat it as a generic conflict. Do not branch on the HTTP status (409 reports several unrelated conditions) or on the numeric code (assigned per call site, so it differs between endpoints reporting the same cause). Re-read the resource and re-apply your change against the current state; resending the same request unchanged cannot succeed. That last point is about conflict entries, not about 409 in general — a 409 carrying no params[] can report a condition that clears on its own, and the cloud-sync write-back queue has one (see Write-Back Queue).

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 (most OAuth endpoints, webhook receivers, and a substantial set of legacy endpoints not yet migrated) return 405 Method Not Allowed for OPTIONS. OAuth authorization-server discovery (/.well-known/oauth-authorization-server/) does support it. Coverage is being expanded incrementally — check via OPTIONS first; fall back to the documented schema when you receive a 405.

Error Codes

Reading this list: the four-digit 16xx/17xx values below are HTTP-status classes, not error.code. The error.code a client actually receives is assigned per endpoint, so use the HTTP status as the gate and a documented error.code — five or six digits, plus the 9661-9669 family — only as a refinement. A 16xx value identifies the status class — useful for telling which kind of failure occurred — but comparing one against error.code will never match. Five- and six-digit codes (and the 9661-9669 family) are real error.code values. If you widen a check from a specific code to a status, widen what you assert with it — a status covers failures the narrower code did not, so a message written for that one code becomes a confident falsehood on the rest.

Client Errors

Billing & Credit Errors

Server Errors

1693 means something the request needs is briefly busy or out of reach, so the request was not carried out at all. Unlike the client errors above it is retryable, and a retry is the correct response: wait a moment and send the same request again, unchanged. Do not rewrite the request, do not vary its inputs, and do not report it as a settled refusal.

1701 means the endpoint was retired by decision. Distinct from 404 on purpose: 404 means “no such thing” and is answered by re-checking the id or your access, whereas 410 means the path itself is finished. Do not retry it, do not vary the id, and do not treat it as an outage — remove the call and use the replacement named in the error message.

1700 means the credential is valid but this request is not permitted — never a reason to sign out. 1697 is returned by account signup or org creation from a geo-restricted location (see Authentication).

Credential Scope Errors

Four codes report a credential that was verified and is too narrow for what it attempted. All four are HTTP 403, never 401, and on them error.params is an object (not the validation array) carrying reason, entity_type, entity_id, required_access_mode, current_access_mode and credential_type, plus credential_id and credential_label for an API-key caller. Branch on params.reason, not the number.

• 10767 (scope_admin_required) — an administrative operation with a credential that is not admin-capable. Administrative reads count: org billing details, invoices, usage, credits, plan preview, payment method, and the events audit log all require an admin-capable credential.
• 10768 (scope_exceeds_issuer, or access_mode_exceeds_initiate on an OAuth consent) — the requested scopes or access mode are broader than the credential making the request, or broader than the authorization was initiated with.
• 10769 (userdetails_scope_required) — an account-settings operation (changing password or email_address, 2FA enrolment and its verification, invalidate-all) without the userdetails:*:rw scope.
• 10770 (scope_write_required) — a non-GET method on an account-anchored route, attempted by a credential that holds no write-capable grant anywhere. A user:*:r credential reads the whole account and writes nothing: no exempt route, sign-out/ included, so such a client ends its session by discarding the credential locally or calling POST /current/oauth/revoke/.

Full detail: Auth & Users.

Organization Access Policy Refusals

An organization on the Enterprise plan can restrict access to its content by country and IP range, and can switch AI features and MCP access off per member and per workspace. These refusals can come from any endpoint that reaches that org's content — org, workspace, share, storage, upload, events, and realtime — for every credential type. They are HTTP 403, never 401 (the credential is still valid, so never sign out or discard it on them), error.params is an object, and you branch on params.reason:

• geo_restricted — the caller's network location is blocked by the owning org's access policy. params also carries rule ("country" or "ip"), org_id and domain. Retrying from the same location will not succeed.
• mcp_access_denied — the request came through the Fastio MCP and the org does not allow MCP access for this user. params.org = {id, domain}. Account-level (user/*) endpoints are never blocked.
• ai_policy_denied / ai_policy_workspace_not_allowed — the org has turned off the AI feature named in params.feature for this caller, or for this workspace.

A 503 (1693) with params.reason = access_policy_unavailable means the policy could not be evaluated — retry it unchanged. List endpoints that span several orgs omit the rows of an org that blocks the caller rather than failing. Full detail: Access Policy (Geo / IP Restrictions) and AI, Intelligence & MCP Access Policy in Organizations.

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 10368. Back off until x-ve-limit-expires.

Some endpoints also apply their own throttle on top of this and may return a 429 with a Retry-After header giving a number of seconds — wait at least that long before retrying; when the header is absent, back off using the x-ve-limit-* headers instead.

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)

Storage listing uses cursor-based (keyset) pagination. 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/{parent_id}/list/):

• 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

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., 2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4). 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. Some id families (for example comment and sign-template ids) are 30 characters, rendered as 6 groups of 5 (35 characters). Id fields use the hyphenated form, but a few values carry the raw id (for example the id inside an upload session’s status_message) — persist whatever you receive.
• 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 an agent chat with POST /current/workspace/{id}/ai/agent/, send messages, and 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 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
• Attributable records (storage nodes, versions, locks, intents, events, comments, invitations, metadata facts) carry one actor object — user_id, kind (human/agent/api_key/app/system/unknown), agent_name, name_source, credential_type, verified. Only Fastio’s own built-in agent is verified: true; every other agent_name is self-declared. See Actor Attribution in the Storage reference

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