# 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-07
> 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 |
| **Workflow** | https://api.fast.io/current/llms/workflow/ | Task lists & tasks; workflow feature toggle |
| **Workflow Orchestration** | https://api.fast.io/current/llms/workflows/ | Durable workflow runtime, templates, triggers, obligations, signed audit export, dual-control redaction, inbound/outbound webhooks, pools, realtime channel (WebSocket invalidation nudges), workflow-native content review (approval surface), human-gate `task` / `todo` steps (blocking/non-blocking, with task reassignment), mid-run modifications (propose/apply changes to a running workflow), agent step commentary trace, agent step activity feed, natural-language edge gates (fail-closed) & structured agent verdicts (`verdict_schema` branching), storage side-effect steps (`share.create` / `share.delete` / `file.copy` / `file.delete`, run-provenance-guarded so a delete only ever touches what the run created) |
| **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 — and `signing.envelope` step `sign_template_id` integration) |
| **Dashboard** | https://api.fast.io/current/llms/dashboard/ | Per-workspace actionable card feed (obligations, mentions, file activity, signatures) with optional AI overlay (urgency, summaries, synthesis), dismiss/snooze, and Ripley Agent seed handoff |
| **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** | Describe a workflow in plain English and an agent (Ripley or your own, over MCP) runs it on your files — event/schedule triggers, approvals, tasks, and native e-signature, charged a flat credit per completed step |
| **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), workflow steps (5/completed step).

**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 + 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 `{ total, limit, offset, has_more }` instead. 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`

**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 (cursor path): `pagination.has_more`, `pagination.next_cursor`, `pagination.page_size`; first page also returns best-effort `counts: { in_flight, completed, paused, failed }` (omitted on cursor pages)

## 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 (tasks, imports) additionally support an endpoint-specific `?format=md` parameter that renders domain-shaped markdown (checkbox lists, 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, comments & workflow items in one call, grouped into per-type buckets with independent pagination
- `GET /current/share/{id}/search/` — Unified search across a share (files, comments & workflow 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. Tasks have a dedicated private comment thread (see Workflow / Task Management).
- `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

### Workflow (Task Management) → [Workflow reference](https://api.fast.io/current/llms/workflow/)

Workflow features enable structured task management within workspaces and shares. All workflow endpoints require the `workflow` feature to be enabled on the target workspace or share. On shares, task access requires Member-level access or higher — guests and public guests are denied. Toggle endpoints (enable/disable) remain Admin-only. Tasks can carry **attachments** (references to files, notes, workflows, sign-envelopes, shares, or other tasks; up to 100 per task) and a private **comment thread** (see the Workflow reference for full shapes).

**Task Lists & Tasks:**
- `GET /current/workspace/{workspace_id}/tasks/` - List task lists
- `GET /current/share/{share_id}/tasks/` - List task lists
- `POST /current/workspace/{workspace_id}/tasks/create/` - Create task list
- `POST /current/share/{share_id}/tasks/create/` - Create task list
- `GET /current/tasks/{list_id}/details/` - Task list details
- `POST /current/tasks/{list_id}/update/` - Update task list
- `POST /current/tasks/{list_id}/delete/` - Delete task list
- `POST /current/tasks/{list_id}/restore/` - Restore a trashed task list
- `GET /current/tasks/{list_id}/items/` - List tasks
- `POST /current/tasks/{list_id}/items/create/` - Create task
- `GET /current/tasks/{list_id}/items/{task_id}/` - Task details
- `POST /current/tasks/{list_id}/items/{task_id}/update/` - Update task
- `POST /current/tasks/{list_id}/items/{task_id}/delete/` - Delete task
- `POST /current/tasks/{list_id}/items/{task_id}/restore/` - Restore a trashed task (restore its list first if the list is trashed)
- `POST /current/tasks/{list_id}/items/{task_id}/status/` - Change status
- `POST /current/tasks/{list_id}/items/{task_id}/assign/` - Assign task
- `POST /current/tasks/{list_id}/items/{task_id}/move/` - Move task to another list
- `GET /current/tasks/{list_id}/items/{task_id}/attachments/` - List task attachments
- `POST /current/tasks/{list_id}/items/{task_id}/attachments/` - Attach objects to a task (single or bulk; cap 100)
- `POST /current/tasks/{list_id}/items/{task_id}/attachments/detach/` - Detach an object from a task
- `GET /current/tasks/{list_id}/items/{task_id}/comments/` - List a task's comments
- `POST /current/tasks/{list_id}/items/{task_id}/comments/` - Post a comment on a task
- `POST /current/tasks/{list_id}/items/bulk-status/` - Bulk status change
- `POST /current/tasks/{list_id}/items/reorder/` - Bulk reorder tasks
- `POST /current/workspace/{workspace_id}/tasks/reorder/` - Bulk reorder task lists
- `POST /current/share/{share_id}/tasks/reorder/` - Bulk reorder task lists

**Workflow Toggle:**
- `POST /current/workspace/{workspace_id}/workflow/enable/` - Enable workflow
- `POST /current/workspace/{workspace_id}/workflow/disable/` - Disable workflow
- `POST /current/share/{share_id}/workflow/enable/` - Enable workflow
- `POST /current/share/{share_id}/workflow/disable/` - Disable workflow

**Workflow Content Review (Orchestration):**
- `POST /current/workflow-review/send-for-review/` - Send a workflow asset out for review (opens a review surface)
- `POST /current/workflow-review/surface/{surface_id}/reviewer/add-member/` - Add a workspace member as a reviewer; `POST /current/workflow-review/surface/{surface_id}/reviewer/add-external/` - Add an external (email) reviewer; `POST /current/workflow-review/surface/{surface_id}/reviewer/{reviewer_id}/remove/` - Remove a reviewer
- `POST /current/workflow-review/surface/{surface_id}/asset/{asset_id}/bind-node/` - Bind a storage node to a review asset
- `GET /current/workflow-review/preview/read/` - Read a review asset preview

Workflow and import GET endpoints support `format=md` for Markdown output. Most list endpoints support `limit` and `offset` pagination; the workflow run list (`GET /current/workspace/{id}/workflows/`) supports opt-in cursor pagination (see *Keyset Pagination* above; bare and `?limit=`/`?offset=` requests return the legacy offset shape). All workflow endpoints (except toggle) require the `workflow` feature enabled on the target profile. Share workflow access requires Member-level or higher.

### 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 is a universal feature — available to every organization on every plan, with no plan gating or feature flag.

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`. A workflow step of type `wait_for_signing` parks on the envelope and resumes when it reaches a terminal state.

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

Per-workspace, per-member feed of ranked, paginated actionable cards. Cards are drawn from workflow obligations (approvals, tasks, reviews, confirmations), @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)

### 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. Requires `cloud_import` feature enabled on the workspace.

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

**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 identity (admin)
- `GET /current/imports/workspace/{workspace_id}/identities/{identity_id}/` - Identity details
- `POST /current/imports/workspace/{workspace_id}/identities/{identity_id}/revoke/` - Revoke identity (admin)

**Import Sources:**
- `GET /current/imports/workspace/{workspace_id}/sources/` - List import sources
- `POST /current/imports/workspace/{workspace_id}/sources/discover/` - Discover remote folders (admin)
- `POST /current/imports/workspace/{workspace_id}/sources/create/` - Create import source (admin)

**Source Details:**
- `GET /current/imports/details/{source_id}/` - Source details
- `POST /current/imports/details/{source_id}/update/` - Update settings (admin)
- `POST /current/imports/details/{source_id}/delete/` - Soft-delete source (admin)
- `POST /current/imports/details/{source_id}/disconnect/` - Disconnect (keep/delete files, admin)
- `POST /current/imports/details/{source_id}/refresh/` - Trigger immediate sync

**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 (admin)

**Write-back (Read-Write Sources):**
- `GET /current/imports/details/{source_id}/writebacks/` - List write-back jobs
- `POST /current/imports/details/{source_id}/writebacks/push/{node_id}/` - Force push file (admin)
- `GET /current/imports/details/{source_id}/writebacks/{writeback_id}/` - Write-back details
- `POST /current/imports/details/{source_id}/writebacks/{writeback_id}/retry/` - Retry failed (admin)
- `POST /current/imports/details/{source_id}/writebacks/{writeback_id}/resolve/` - Resolve conflict (admin)
- `POST /current/imports/details/{source_id}/writebacks/{writeback_id}/cancel/` - Cancel write-back (admin)

Providers: `google_drive`, `dropbox`, `box`, `onedrive_business`. Source statuses: pending, discovering, syncing, synced, error, paused, disconnected, disconnecting. 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