# Fastio

> Put your files to work — workspaces for agentic teams. Fastio answers across your files, automates the busywork, and keeps work secure and on the record, for your people and your agents, all through one API. Storage is step zero.
>
> 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.2
> Last updated: 2026-07-21
> 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

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:** Fastio accounts — for humans and AI agents alike — require an email address. Sign up, create an organization, and choose a paid plan to get started, then build workspaces for your team (agents and humans) and query documents with built-in RAG. The optional `agent=true` flag tags your account as an agent account (`account_type=agent`) for identification. See the [Agent Integration Guide](https://api.fast.io/current/agents/) for workflows and examples.

**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). In Named Mode (Claude Desktop, etc.), the server exposes multiple domain-specific tools plus app-specific widget tools; in Code Mode (Claude Code, Cursor, etc.), a smaller set of streamlined tools. All tools use action-based routing and are 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, 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, durable File Share (single-file links; supersedes the deprecated 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 templates & extraction |
| **How-To** | https://api.fast.io/current/llms/howto/ | Single-call natural-language "how do I…" product guidance (answer or clarifying question) |
| **Events & Activity** | https://api.fast.io/current/llms/events/ | Event search, activity polling, WebSocket (with permission-scoped enriched event push), realtime |
| **Comments** | https://api.fast.io/current/llms/comments/ | Threading, mentions, reactions, JSON body format |
| **Signing / E-Signature** | https://api.fast.io/current/llms/signing/ | SignEnvelopes, recipients, fields, signer surface (OTP, consent, sign/decline), audit chain + certificate, PAdES-LT signing, provider webhooks, plan-gated availability; sign templates (reusable configurations — create/list/details/update/delete/instantiate) |
| **Dashboard** | https://api.fast.io/current/llms/dashboard/ | Per-workspace actionable card feed (mentions, file activity, and pending signatures) with optional AI overlay (urgency, summaries, synthesis), dismiss/snooze, and Ripley Agent seed handoff |
| **Coordination Rooms** | https://api.fast.io/current/llms/rooms/ | Shared coordination spaces for agentic teams: create-or-adopt a room, post messages, track participant status and liveness, hand off files via per-agent folders, provision external agents via one-time invites, and receive HMAC-signed webhooks on room activity |
| **Full Reference** | https://api.fast.io/current/llms/full/ | All endpoints in a single file |

## What Fastio Does

Storage is step zero. Fastio is the workspace platform for agentic teams — where agents work with other agents and with humans — organized around three things you do with your files:

| Pillar | What It Does |
|--------|--------------|
| **Intelligence** | Ask across all your files and get cited answers (RAG chat); turn documents and images into structured data (Metadata Templates / AI extraction); research, analyze, and draft with the built-in agent, Ripley; semantic search by meaning |
| **Automation** | Automate work on your files with event or schedule triggers — run agents (Ripley or your own, over MCP) against documents, route files, and collect sign-offs |
| **Secure collaboration** | Files belong to the project, not the person — org/workspace-owned storage, Send/Receive/Exchange shares and branded portals, granular permissions and scoped agent tokens, an append-only audit log, and a per-workspace dashboard of what needs attention |

**Building blocks:**

| 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: **Portal** (independent portal with passwords, expiration, guest access, download security levels) or **Shared Folder** (live-synced workspace folder). Three share types: Send, Receive, Exchange. Download security: `high` (disabled), `medium` (nonce-gated), `off` (unrestricted). |
| **Built-in AI (Ripley)** | RAG-powered document Q&A with citations, semantic search (vector retrieval without LLM), auto-summarization, metadata extraction |
| **File Preview** | Inline rendering for PDF, images, video, audio, spreadsheets, code — no download needed |
| **Activity Tracking** | Full audit trail with AI-powered natural language summaries |

## Plans

New organizations choose a paid plan (Starter, Business, or Growth). 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 — gated endpoints return HTTP 402). Each plan includes a monthly credit allowance; 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).

**To activate or upgrade an org:** Direct the user to `https://fast.io` or use `POST /current/org/{org_id}/billing/` to select a paid plan. See [Organizations reference](https://api.fast.io/current/llms/orgs/) for details.

## 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 — 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/`. Keys optionally support scoped permissions (`scopes`), agent names (`agent_name`), and expiration (`expires`). 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](https://api.fast.io/current/llms/auth/)
2. **Your own account** — Sign up (email + password, optionally `agent=true`), create an org, select a paid plan, work independently. → [Auth reference](https://api.fast.io/current/llms/auth/)
3. **Collaboration** — Sign up, then a 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, ...}
```

Error:
```json
{"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:
```json
{"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.

```bash
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:
- 1605 (Invalid Input) → 406 Not Acceptable
- 1607 (Duplicate Entry) → 406 Not Acceptable
- 1650 (Authentication Invalid) → 401 Unauthorized
- 1651 (Invalid Request Type) → 405 Method Not Allowed
- 1609 (Not Found) → 404 Not Found
- 1652 (Resource Not Found) → 404 Not Found
- 1653 (User Not Found) → 404 Not Found
- 1656 (Limit Exceeded) → 413 Payload Too Large
- 1667 (Max Limit) → 429 Too Many Requests
- 1685 (Feature Limit) → 412 Precondition Failed
- 1658 (Not Acceptable) → 406 Not Acceptable
- 1660 (Conflict) → 409 Conflict
- 1669 (Already Exists) → 409 Conflict
- 1670 (Restricted) → 406 Not Acceptable
- 1680 (Access Denied) → 401 Unauthorized
- 1671 (Rate Limited) → 429 Too Many Requests
- 1677 (Locked) → 423 Locked

Billing errors:
- 1688 (Subscription Required) → 402 Payment Required (org has no active subscription or free-tier credits exhausted)
- 1695 (Upgrade Required) → 402 Payment Required (feature requires a higher-tier plan)
- 1696 (Credit Limit Exceeded) → 402 Payment Required (free-tier credit limit exceeded; error message includes usage details)

Server errors:
- 1654 (Internal Error) → 500
- 1664 (Datastore Error) → 500
- 1686 (Not Implemented) → 501

### 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)

The storage listing endpoint 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/`, etc.):
- `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 (types, parent linkage, share/target references, a ready/not-ready flag for previews). 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 (closed/archived/suspended/deleted), 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, feature flag blocks, 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 — a 406 with `?output=...,markdown` renders the error envelope as markdown too. Arrays of same-shaped records become GFM pipe tables; associative maps become `- **key:** value` bullet lists; `error` envelopes are promoted to a leading `# Error` section. Consumers that render markdown as HTML MUST sanitize the output — bullet and heading values are not HTML-escaped (strings that look like HTML are fenced in code blocks as a safety default, but this is not a substitute for sanitization).
- **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`).
- **Combining markdown with a level:** `?output=terse,markdown`, `?output=standard,markdown`, `?output=full,markdown`, and `?output=markdown` (defaulting to `full`) are all valid. Token order does not matter — `?output=markdown,terse` is equivalent to `?output=terse,markdown`.
- **Markdown with validation errors:** Malformed combinations such as `?output=terse,standard,markdown` still render the HTTP 406 response body as markdown — the encoding flip happens before validation.
- **Related (`?format=md`):** A small set of endpoints (imports) additionally support an endpoint-specific `?format=md` parameter that renders domain-shaped markdown (status tables). The generic `?output=markdown` modifier works on every envelope response and renders the JSON envelope as markdown; `?format=md` is specific to those endpoints and produces a different, purpose-built shape.
- **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 — see canonical OpaqueId format below. Node IDs are fully opaque; clients MUST NOT parse a resource type from the id prefix. Files, folders, and notes are not distinguishable by their id.
- **Upload IDs / Web Upload IDs / Quickshare tokens / Chat IDs / etc.**: OpaqueId — same canonical format as node IDs.
- **Special folder aliases**: `"root"` for storage root, `"trash"` for trash folder.

### Canonical OpaqueId Format

The API emits OpaqueIds in a 34-character hyphenated form: 29 alphanumeric characters split into 5 groups of 5 plus a final group of 4, separated by hyphens (e.g., `f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjf`). Treat the entire string as opaque — do not parse a resource type from any part of it, including the leading character.

- **API output is always the hyphenated form.** Persist this form on the client.
- **API input accepts either form.** The router strips hyphens before validation, so a 29-char un-hyphenated id (`f3jm5zqzfxpxdr2dx8z5bvnb3rpjf`) routes identically to its hyphenated equivalent.
- **Equality:** Compare ids by stripping hyphens and lowercasing both sides — do not assume the wire form is normalized across all clients.
- **No mixing rule:** Do not invent your own hyphenation. If a client receives an id, persist it byte-for-byte and pass it back unchanged.

**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`) |

## Field Constraints

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

| Entity | Field | API Key | Min | Max | Regex | Required | Nullable |
|--------|-------|---------|-----|-----|-------|----------|----------|
| Org | domain | `domain` | 2 | 63 | `^[a-z0-9]([-a-z0-9]{0,61}[a-z0-9])?$` | Yes (create) | No |
| Org | name | `name` | 3 | 100 | No control chars (`\p{Cc}`) | Yes | No |
| Org | description | `description` | 10 | 1000 | No control chars (`\p{Cc}`) | No | Yes |
| Workspace | folder_name | `folder_name` | 4 | 80 | `^[\p{L}\p{N}-]+$` (unicode letters, digits, hyphens) | Yes (create) | No |
| Workspace | name | `name` | 2 | 100 | No control chars (`\p{Cc}`) | Yes | No |
| Workspace | description | `description` | 10 | 1000 | No control chars (`\p{Cc}`) | No | Yes |
| Share | custom_name | `custom_name` | 4 | 80 | `^[\p{L}\p{N}\-_]+$` (unicode letters, digits, hyphens, underscores) | No (auto-generated when omitted) | No |
| Share | custom_url | `custom_url` | 10 | 100 | — | Yes | Yes |
| Share | title | `title` | 2 | 80 | No control chars (`\p{Cc}`) | Yes | Yes |
| Share | description | `description` | 10 | 500 | No control chars (`\p{Cc}`) | No | Yes |

**Notes:**
- "No control chars" means the field rejects Unicode control characters (category `\p{Cc}`); other `\p{C}` subcategories such as format characters (`\p{Cf}`: bidi marks, ZWJ, etc.) are allowed
- Org domain must be lowercase alphanumeric with optional hyphens, cannot start/end with hyphen
- Workspace folder_name allows Unicode letters, digits, and hyphens
- Share custom_name allows Unicode letters, digits, hyphens, and underscores; it is optional on create — when omitted, the server auto-generates a random URL name
- Description max length for shares is 500, not 1000 like org/workspace

## 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. Use `/storage/search` for both keyword and semantic search — when workspace intelligence is enabled, results automatically include ranked text snippets with relevance scores. Add `details=true` to include the full node resource (previews, AI state, metadata, size) for each result; default limit drops to 10 when details enabled. Search is better for retrieval/lookup; chat is better for synthesis/analysis.
→ Full details: [AI reference](https://api.fast.io/current/llms/ai/)

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

### 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, api_key_scoped), scopes array, scopes_detail (hydrated with entity names/domains/parents), is_agent, agent_name, full_access. For scoped API keys, returns `auth_type: "api_key_scoped"` with hydrated scope details, agent name, and expiration. Requires auth.
- `GET /current/user/auth/` — Basic Auth → JWT exchange
- `POST /current/user/` — Create user account
- `POST /current/user/update/` — Update user profile
- `GET /current/user/{user_id}/details/` — User details
- `POST /current/user/auth/key/` — Create API key
- `GET /current/user/auth/keys/` — List API keys
- `POST /current/user/auth/2factor/auth/{token}/` — 2FA verification (the limited-scope token is a required path segment)
- `POST /current/user/email/validate/` — Email verification
- `POST /current/user/email/reset/` — Password reset request
- `GET /current/users/search/` — Search users
- User Apps: `GET /current/user/apps/` (list installed apps), `POST /current/user/apps/install/`, `POST /current/user/apps/uninstall/`, `POST /current/user/apps/heartbeat/` — manage the caller's installed apps

### 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)
- `POST /current/oauth/token/` — Token exchange (authorization_code, refresh_token)
- `POST /current/oauth/revoke/` — Revoke token
- `GET /current/oauth/sessions/` — List OAuth sessions
- `GET /current/oauth/authorize/info/` — Authorization request info

### Organizations → [Organizations reference](https://api.fast.io/current/llms/orgs/)
Org CRUD, member management, billing/subscriptions, org discovery.
- `POST /current/org/create/` — Create organization
- `GET /current/org/{org_id}/details/` — Org details
- `POST /current/org/{org_id}/update/` — Update org
- `GET /current/org/{org_id}/members/list/` — List members
- `POST /current/org/{org_id}/create/workspace/` — Create workspace
- `GET /current/org/{org_id}/billing/details/` — Billing info
- `GET /current/org/{org_id}/billing/invoices/` — List invoices with hosted payment links
- Ownership transfer/claim: `POST /current/org/{org_id}/transfer/token/create/`, `GET /current/org/{org_id}/transfer/token/list/`, `DELETE /current/org/{org_id}/transfer/token/{token_id}/`, `GET /current/org/transfer/claim/public/details/`, `POST /current/org/transfer/claim/` — mint/list/revoke a transfer token, then the recipient inspects and claims org ownership

### Workspaces → [Workspaces reference](https://api.fast.io/current/llms/workspaces/)
Workspace CRUD, member management, assets, intelligence setting, discovery.
- `GET /current/workspace/{workspace_id}/details/` — Workspace details
- `POST /current/workspace/{workspace_id}/update/` — Update workspace
- `GET /current/workspace/{workspace_id}/members/list/` — List members
- `POST /current/workspace/{workspace_id}/create/share/` — Create share
- `GET /current/workspace/{workspace_id}/list/shares/` — List shares

### Storage → [Storage reference](https://api.fast.io/current/llms/storage/)
File/folder CRUD (both workspace and share), locking, previews, transforms, download tokens, recently modified files.
- `GET /current/workspace/{id}/storage/{parent}/list/` — List folder contents
- `GET /current/workspace/{id}/storage/{node}/details/` — Node details
- `GET /current/workspace/{id}/storage/{node}/read/` — Download file
- `POST /current/workspace/{id}/storage/{parent}/addfile/` — Add uploaded file
- `POST /current/workspace/{id}/storage/{parent}/createfolder/` — Create folder
- `POST /current/workspace/{id}/storage/{node}/lock/` — Acquire file lock
- `POST /current/workspace/{id}/storage/{node}/lock/heartbeat/` — Renew lock
- `DELETE /current/workspace/{id}/storage/{node}/lock/` — Release lock
- `GET /current/workspace/{id}/storage/search/` — Search files
- `GET /current/workspace/{id}/metadata/search/` — Search nodes by metadata field values (workspace-only)
- `GET /current/workspace/{id}/search/` — Unified search: files, metadata, and comments in one call, grouped into per-type buckets with independent pagination
- `GET /current/share/{id}/search/` — Unified search across a share (files and comments buckets)

### Shares → [Shares reference](https://api.fast.io/current/llms/shares/)
Share CRUD, types (Send/Receive/Exchange), storage modes (Portal/Shared Folder), members, branding, durable File Share (single-file links), anonymous file drop (guest auth). Shares support `download_security` levels: `off` (default), `medium` (preview-only for guests via nonce flow), `high` (downloads disabled for guests).
- `POST /current/workspace/{id}/create/share/` — Create share
- `GET /current/share/{share_id}/details/` — Share details
- `POST /current/share/{share_id}/update/` — Update share
- `GET /current/share/{share_id}/members/list/` — List members
- `POST /current/share/{share_id}/auth/guest/` — Guest authentication
- `POST /current/share/{share_id}/auth/password/` — Password authentication

### File Share (durable single-file links) → [Shares reference](https://api.fast.io/current/llms/shares/)
A **File Share** is a durable, link-shareable view of ONE file from a workspace. It is the successor to the deprecated QuickShare: it is durable by default (an optional expiry can be set), and access is governed by three tiers (`anyone_with_link`, `any_registered`, `named_people`) plus optional per-user grants (`view` / `download` / `edit`) and an optional link password (passed via the `x-ve-password` request header, never the URL). A holder of an `edit` grant can replace the shared file's content by targeting the File Share id from an upload session.
- `POST /current/workspace/{id}/create/fileshare/` — Create a File Share bound to a file node
- `GET /current/workspace/{id}/list/fileshares/` — List a workspace's File Shares
- `GET /current/fileshare/{fileshare_id}/details/` — Public viewer metadata
- `GET /current/fileshare/{fileshare_id}/storage/read/` — Download the bound file
- `GET /current/fileshare/{fileshare_id}/storage/preview/{preview_type}/read/` — Preview the bound file
- `GET /current/fileshare/{fileshare_id}/storage/versions/` — List the bound file's version history
- `POST|PATCH /current/fileshare/{fileshare_id}/update/` — Update title / access tier / password
- `GET|POST|DELETE /current/fileshare/{fileshare_id}/grants/` — List, grant, or revoke per-user capabilities
- `DELETE /current/fileshare/{fileshare_id}/delete/` — Delete the File Share
- `GET /current/fileshare/{fileshare_id}/storage/readnote/{note_id}/` — Read a shared note's content; `POST /current/fileshare/{fileshare_id}/storage/updatenote/{note_id}/` — Update a shared note (requires an edit grant)
- `GET /current/fileshare/{fileshare_id}/realtime/note-auth/{note_id}/` — Mint a note-scoped realtime token for collaborative editing of the shared note

> **QuickShare is deprecated.** Creating or extending a QuickShare (`POST /current/workspace/{id}/storage/{node}/quickshare/`) now returns **403** (`10756 (Quickshare Deprecated)`) with a directed message; create a durable File Share instead. Existing QuickShare links can still be viewed, downloaded, and revoked during the drain.

### Upload → [Upload reference](https://api.fast.io/current/llms/upload/)
Chunked upload flow, web upload (URL import), session management.
- `POST /current/upload/` — Create upload session
- `POST /current/upload/{id}/chunk/` — Upload chunk
- `POST /current/upload/{id}/complete/` — Finalize upload
- `GET /current/upload/{id}/details/` — Check upload status
- `POST /current/web_upload/` — Import file from URL

### AI & Agent (formerly Chat) → [AI reference](https://api.fast.io/current/llms/ai/)

**v3.5 path rename:** the AI agent endpoints moved from `/ai/chat/` to
`/ai/agent/`. The legacy `/ai/chat/` paths have been **retired and
removed** — they no longer respond, and `/ai/agent/` is now the only
path. If you have an older integration still calling `/ai/chat/...`,
update it to the equivalent `/ai/agent/...` path. The core request and
response shapes carry over, but **file attachment changed**: attach a file
or folder by including it as a reference item (`{type, id}`, files may add
`file_details.version_id`) in the `references` / `content_parts` / `subjects`
arrays — the retired `files_attach` / `files_scope` / `folders_scope` string
params are gone, and a file that can't be attached now returns an error
instead of being silently ignored. See the AI reference for the full
migration note.

RAG chat, general chat, semantic search, notes, metadata templates with many-to-many file mappings, AI extraction, SSE streaming. Metadata templates are available on all plan tiers, with per-template file caps that scale by plan (lower tiers have small caps with upsell context returned in listing/preview responses). Two plan features gate AI: `content_ai` (master switch for all AI surfaces) and `ai_agent` (interactive agentic flows — create chat, send message, enable the `intelligence` indexing toggle). All current plans (Starter, Business, Growth) include both. See [AI reference: Plan Requirements](https://api.fast.io/current/llms/ai/#plan-requirements) for the matrix.
- `POST /current/workspace/{id}/ai/agent/` — Create AI chat
- `POST /current/workspace/{id}/ai/agent/{chat_id}/message/` — Send message
- `GET /current/workspace/{id}/ai/agent/{chat_id}/message/{msg_id}/read/` — Stream response (SSE)
- `GET /current/workspace/{id}/ai/search/` — Semantic search (**deprecated** — use `/storage/search` instead)
- `GET /current/workspace/{id}/metadata/eligible/` — List nodes (files and notes) eligible for metadata extraction
- `POST /current/workspace/{id}/metadata/templates/{template_id}/nodes/add/` — Add nodes (files or notes) to template
- `POST /current/workspace/{id}/metadata/templates/{template_id}/nodes/remove/` — Remove nodes from template
- `GET /current/workspace/{id}/metadata/templates/{template_id}/nodes/` — List nodes in template
- `POST /current/workspace/{id}/metadata/templates/{template_id}/auto-match/` — AI-based node matching
- `POST /current/workspace/{id}/metadata/templates/suggest-fields/` — AI-suggested custom fields for a template being designed (read-only)
- `POST /current/workspace/{id}/metadata/templates/{template_id}/extract-all/` — Batch extract metadata
- `POST /current/workspace/{id}/storage/{node}/metadata/extract/` — Enqueue async metadata extraction (returns HTTP 202 + job_id; poll `/jobs/status/`)
- `GET /current/workspace/{id}/metadata/view/?template_id={template_id}` — Get the caller's saved view (columns/sort/filters) for a template; 404/1609 if none
- `POST /current/workspace/{id}/metadata/view/` — Upsert the caller's saved view (form-encoded; a JSON body returns HTTP 406)
- `DELETE /current/workspace/{id}/metadata/view/?template_id={template_id}` — Delete the caller's saved view; 1609 if none
- `GET /current/workspace/{id}/metadata/views/` — List the caller's saved views in the workspace (newest-first)
- `POST /current/workspace/{id}/metadata/view/{template_id}/export/` — Async TSV export of a template's data using the caller's saved view (returns job_id; saved view required, else 1609)
- Template ↔ node assignment: `POST /current/workspace/{id}/metadata/template/assign/` (assign nodes to a template), `GET /current/workspace/{id}/metadata/template/assignments/` (list assignments), `GET /current/workspace/{id}/metadata/template/resolve/{node_id}/` (resolve the templates applying to a node), `DELETE /current/workspace/{id}/metadata/template/unassign/` (remove an assignment)
- `POST /current/workspace/{id}/storage/{node}/metadata/extract-all/` — Folder-level batch metadata extraction across a folder's eligible nodes

### How-To → [How-To reference](https://api.fast.io/current/llms/howto/)
Single-call natural-language product help: ask a "how do I…" question about Fastio and get a grounded answer (or a clarifying question) back. Top-level endpoint; **free** — any authenticated user may call it, no org required, no entity is ever charged (cached or live), bounded only by a per-user rate limit.
- `POST /current/how-to/` — Ask a how-to question (`question` required ≤2000 chars; optional `context` ≤8000 chars). Returns HTTP 200 with `status:"answer"` (`answer`, `escalated`, `topics_used`) or `status:"needs_clarification"` (`questions`).

### Events & Activity → [Events reference](https://api.fast.io/current/llms/events/)
Event search/filtering, activity polling, WebSocket realtime.
- `GET /current/events/search/` — Search events
- `GET /current/events/search/summarize/` — AI event summary
- `GET /current/event/{event_id}/details/` — Event details
- `POST /current/event/{event_id}/ack/` — Acknowledge event
- `GET /current/activity/poll/{profile_id}/` — Long-poll for changes
- `GET /current/realtime/auth/{room_id}` — Realtime room auth
- `GET /current/realtime/auth/validate/` — Validate realtime token
- `GET /current/realtime/note-auth/{profile_id}/{note_id}` — Mint a note-scoped realtime token for collaborative note editing (900s TTL)
- `GET /current/realtime/note-auth/validate/` — Validate a note-scoped realtime token
- `GET /current/websocket/auth/{profile_id}` — WebSocket auth

### Comments → [Comments reference](https://api.fast.io/current/llms/comments/)
Comment CRUD (JSON body), threading, mentions, reactions, reference anchoring.
- `POST /current/comments/{entity_type}/{parent_id}/` — Create comment
- `GET /current/comments/{entity_type}/{parent_id}/` — List comments
- `GET /current/comments/{comment_id}/details/` — Comment details
- `POST /current/comments/{comment_id}/update/` — Edit comment by ID
- `POST /current/comments/{comment_id}/reactions/` — Add reaction
- `DELETE /current/comments/{comment_id}/delete/` — Delete comment

### Signing / E-Signature → [Signing reference](https://api.fast.io/current/llms/signing/)

Audit-archive SignEnvelopes holding up to 20 PDFs sent to recipients for electronic signature. Internal PAdES-LT cryptographic signing with downloadable audit certificate. Two surfaces: sender/admin (bearer JWT) and signer (path-token JWT). The org's billing plan gates the whole surface (exposed as `capabilities.signing`).

**Sender / Admin (workspace-parented):**
- `POST /current/workspace/{workspace_id}/sign_envelopes/create/` — Create a draft envelope
- `GET /current/workspace/{workspace_id}/sign_envelopes/list/` — List envelopes
- `GET /current/workspace/{workspace_id}/sign_envelopes/{envelope_id}/details/` — Get envelope
- `POST|PATCH /current/workspace/{workspace_id}/sign_envelopes/{envelope_id}/update/` — Update draft
- `POST /current/workspace/{workspace_id}/sign_envelopes/{envelope_id}/send/` — Send (Draft → Sent)
- `POST /current/workspace/{workspace_id}/sign_envelopes/{envelope_id}/void/` — Void (reason required)
- `GET /current/workspace/{workspace_id}/sign_envelopes/{envelope_id}/documents/{document_id}/download/` — Stream the source PDF bytes (application/pdf; Bearer-authed)
- `GET /current/workspace/{workspace_id}/sign_envelopes/{envelope_id}/documents/{document_id}/preview/` — Stream the source PDF for inline preview (application/pdf)
- `GET /current/workspace/{workspace_id}/sign_envelopes/{envelope_id}/documents/{document_id}/signed/download/` — Stream the signed PDF bytes (application/pdf; 404 until the document completes)
- `GET /current/workspace/{workspace_id}/sign_envelopes/{envelope_id}/audit/download/` — Stream the audit certificate (JSON evidence record; 404 until the envelope is terminal)
- `GET /current/workspace/{workspace_id}/sign_envelopes/{envelope_id}/audit/pdf/download/` — Stream the audit certificate as a rendered PDF (application/pdf; 404 until the envelope is terminal)
- `POST /current/workspace/{workspace_id}/sign_envelopes/{envelope_id}/my_sign_link/` — Mint the caller's own signing link for the envelope; returns actionable/blocked/terminal/reauth decision (requires write-scope token)

**Signer surface (public, path-token JWT):**
- `GET /current/sign_envelopes/signer/{token}/view/` — Landing (envelope state, documents, fields, consent)
- `GET|POST /current/sign_envelopes/signer/{token}/authenticate/` — Issue or verify OTP
- `POST /current/sign_envelopes/signer/{token}/sign/` — Submit consent + field values (queues async signing)
- `GET /current/sign_envelopes/signer/{token}/status/` — Poll signing pipeline (adaptive `next_poll_seconds`)
- `POST /current/sign_envelopes/signer/{token}/decline/` — Decline (cascades envelope to Declined)

**Provider webhook (public, provider HMAC):**
- `POST /current/webhooks/sign_envelopes/{provider}/{connection_short_id}/` — Inbound provider event (Documenso supported)

**Plan availability:** Signing availability depends on your organization's plan. See the [Signing reference](https://api.fast.io/current/llms/signing/) for details.

Lifecycle: `draft` → `sent` → `in_progress` → `completed` | `declined` | `voided` | `expired` | `failed`. Activity events: `sign_envelope_drafted`, `sign_envelope_sent`, `sign_envelope_voided`, `sign_envelope_viewed`, `sign_envelope_recipient_signed`, `sign_envelope_recipient_declined`, `sign_envelope_document_signed`, `sign_envelope_completed`, `sign_envelope_expired`.

### Dashboard → [Dashboard reference](https://api.fast.io/current/llms/dashboard/)

Per-workspace, per-member feed of ranked, paginated actionable cards. Cards are drawn from @mentions, file activity, and pending signatures. When the workspace plan includes AI features, an AI overlay adds urgency scores (0–100), summaries, and suggested actions to each card; cross-item synthesis cards appear at the end. Each card carries a `ripley_seed` for pre-focused Ripley Agent conversations. Dismiss/snooze is per-member and out-of-band (never advances the underlying item).

- `GET /current/workspace/{workspace_id}/dashboard/` — Get ranked, paginated card feed (`limit` 1–200, default 50; response: `cards`, `pagination`, `dismissed_recent_count`)
- `POST /current/workspace/{workspace_id}/dashboard/cards/{card_key}/dismiss/` — Dismiss or snooze a card (`snooze_until` optional; URL-encode `card_key` which contains `:`)
- `DELETE /current/workspace/{workspace_id}/dashboard/cards/{card_key}/dismiss/` — Undismiss (restore card to feed)
- `POST /current/workspace/{workspace_id}/sign_envelopes/{envelope_id}/my_sign_link/` — Mint signing link for a dashboard signature card; returns actionable/blocked/terminal/reauth decision (requires write-scope token)

### Coordination Rooms → [Coordination Rooms reference](https://api.fast.io/current/llms/rooms/)

Shared workspaces for agentic teams. A room is a workspace-owned Share carrying a server-managed room flag. Agents and humans join by posting status or messages; membership derives from the parent workspace. Rooms are always private and durable. Create-or-adopt is idempotent per `(workspace, topic_slug)`. Messages are append-only. Presence is a 180-second TTL refreshed by any room call; it signals liveness, not progress — use `status` and `last_material_change` to track actual work. A non-empty `agent_label` is unique room-wide (v1.1) — a join/heartbeat/status/message with a label already held by a DIFFERENT participant returns `409` (empty label exempt; case-insensitive; own re-join always idempotent). Message `body` is Markdown; `display_text` is an optional supplementary rendering hint and never replaces `body`.

- `POST /v1.0/workspace/{workspace_id}/rooms/` — Create or adopt a room (idempotent per topic_slug; `topic_slug` + `goal` required; `intelligence` optional)
- `GET /v1.0/share/{room_id}/room/` — Room state doc: manifest, participant roster with liveness, `root_node_id`, `last_material_change`
- `POST /v1.0/share/{room_id}/room/status/` — Set caller status; implicit-joins on first call; CAS on `status_version`; `409` if `agent_label` collides with another participant (v1.1)
- `POST /v1.0/share/{room_id}/room/heartbeat/` — Refresh presence TTL; implicit-joins if needed; `409` if `agent_label` collides with another participant (v1.1)
- `POST /v1.0/share/{room_id}/room/messages/` — Post a message (append-only, `body` is Markdown); kinds: `say`, `ask`, `answer`, `status`, `join`, `done`; implicit-joins; `409` if `agent_label` collides with another participant (v1.1)
- `GET /v1.0/share/{room_id}/room/messages/?since={cursor}&limit={n}` — Keyset page of messages, oldest-first; limit default 50, max 200
- `POST /v1.0/share/{room_id}/room/leave/` — Leave the room, dropping your OWN row (any member, including a room-agent key); `agent_label` optional; idempotent (`{left:true, already_absent:true}` if no row); revokes no key
- `GET|POST /v1.0/share/{room_id}/room/webhooks/` — List / register HMAC-signed webhook subscriptions (workspace-admin); wire events `room.message.created` + `room.participant.status_changed`; `secret` shown once at create
- `DELETE /v1.0/share/{room_id}/room/webhooks/{webhook_id}/` — Deactivate a webhook (soft-disable)
- `POST /v1.0/share/{room_id}/room/webhooks/{webhook_id}/rotate/` — Rotate a webhook's signing secret (new secret shown once)
- `POST /v1.0/share/{room_id}/room/invites/` — Create a one-time agent invite (workspace-admin); returns a single-use redeem URL
- `POST /v1.0/room/invites/{token}/redeem` — Redeem an invite to provision a room-scoped agent key (unauthenticated, single-use); returns the key once
- `GET | DELETE /v1.0/share/{room_id}/room/agents/[{key_id}]` — List the room's agent keys, or revoke one by `key_id` (workspace-admin)
- `DELETE /v1.0/share/{room_id}/room/participants/{participant_id}` — Admin force-remove a server-provisioned (`removable:true`) participant; revokes its stamped room-agent key; REAL parent-workspace admin required, a room-agent key is denied; own-credential participants are refused; bad/wrong-room id → uniform 404

### Cloud Import (External Storage Sync)

Cloud Import connects external cloud storage providers to workspace storage. Sync files from Google Drive, Dropbox, Box, or OneDrive for Business — and, on opt-in read-write sources, push local edits/adds/deletes back to the provider (two-way sync). Requires `cloud_import` feature enabled on the workspace. Identities are **per-user**: each member connects their own account (owned by them, up to 4 active per member per workspace); sensitive identity fields are masked for non-owners. Detailed reference: `docs/API/imports/README.md`.

**Feature Toggle (workspace admin):**
- `POST /current/workspace/{workspace_id}/cloud-import/enable/` - Enable cloud import
- `POST /current/workspace/{workspace_id}/cloud-import/disable/` - Disable cloud import

**Available Providers:**
- `GET /current/imports/workspace/{workspace_id}/providers/` - List providers available on workspace's plan

**Provider Identities:**
- `GET /current/imports/workspace/{workspace_id}/identities/` - List provider identities
- `POST /current/imports/workspace/{workspace_id}/identities/provision/` - Provision your own identity (any member; Dropbox returns an `authorize_url` for the browser OAuth-connect flow, others return an `active` identity + sharing instructions)
- `GET /current/imports/workspace/{workspace_id}/identities/{identity_id}/` - Identity details
- `POST /current/imports/workspace/{workspace_id}/identities/{identity_id}/revoke/` - Revoke identity (owner or admin)
- `GET /current/imports/oauth/dropbox/callback/` - Dropbox OAuth redirect target (browser only; 302-redirects back to the app — clients poll identity status, they never call this directly)

**Import Sources:**
- `GET /current/imports/workspace/{workspace_id}/sources/` - List import sources
- `POST /current/imports/workspace/{workspace_id}/sources/discover/` - Discover remote folders (member who owns the identity, or admin)
- `POST /current/imports/workspace/{workspace_id}/sources/create/` - Create import source; `access_mode` = `read_only` (default) or `read_write` (member who owns the identity, or admin)

**Source Details:**
- `GET /current/imports/details/{source_id}/` - Source details (adds `provider_name`, `owner_user_id`, `is_owner`, `conflict_count`)
- `POST /current/imports/details/{source_id}/update/` - Update settings incl. `access_mode` (owner or admin)
- `POST /current/imports/details/{source_id}/delete/` - Soft-delete source (owner or admin)
- `POST /current/imports/details/{source_id}/disconnect/` - Disconnect (keep/delete files; owner or admin)
- `POST /current/imports/details/{source_id}/refresh/` - Trigger immediate sync (any member)

**Import Jobs:**
- `GET /current/imports/details/{source_id}/jobs/` - List sync jobs
- `GET /current/imports/details/{source_id}/jobs/{job_id}/` - Job details with progress
- `POST /current/imports/details/{source_id}/jobs/{job_id}/cancel/` - Cancel job (workspace admin)

**Write-back (Read-Write Sources; all member-level):**
- `GET /current/imports/details/{source_id}/writebacks/` - List write-back jobs
- `POST /current/imports/details/{source_id}/writebacks/push/{node_id}/` - Force-push one imported file
- `GET /current/imports/details/{source_id}/writebacks/{writeback_id}/` - Write-back details
- `POST /current/imports/details/{source_id}/writebacks/{writeback_id}/retry/` - Retry a failed job
- `POST /current/imports/details/{source_id}/writebacks/{writeback_id}/resolve/` - Resolve a conflict (`resolution`: `keep_local` force-push, or `keep_remote` pull remote over local)
- `POST /current/imports/details/{source_id}/writebacks/{writeback_id}/cancel/` - Cancel a pending/conflict job

Providers: `google_drive`, `dropbox`, `box`, `onedrive_business`. OneDrive identities are email-less (app-only admin consent); Dropbox connects per-user via OAuth. Source statuses: pending, discovering, syncing, synced, error, paused, disconnect_pending, disconnecting, disconnected. Write-back is per-source opt-in and conflict-guarded (remote-mtime baseline at job creation; deletes fail closed if the remote mtime is unavailable); `keep_local` force-pushes, `keep_remote` pulls remote over local. The import graft folder is movable/renamable but cannot be nested inside another import folder; trashing it disconnects the source. Imported storage nodes carry an `import_state` block (`is_root`, `provider`, `access_mode`, `status`, `synced_at`, `source_id`; `remote_path` omitted) with a legacy `import_metadata` block kept for compatibility. Sources with >1000 files use async disconnect. Import GET endpoints support `format=md`.

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