# Fast.io

> Store files. Share with humans. Query with AI. All through one API — free.
>
> Base URL: https://api.fast.io/current/
> Version: 1.0
> Request format: `application/x-www-form-urlencoded` (most POST bodies) or query string (GET). Some endpoints accept `application/json` bodies — notably comments and endpoints with nested/array parameters.
> Response format: JSON
> File uploads: `multipart/form-data`
> Document version: 1.3
> Last updated: 2026-02-03 (this file is updated frequently; re-fetch at least daily for the latest endpoints and parameters)
> Full documentation: https://docs.fast.io
> Agent integration guide: https://docs.fast.io/agents
> MCP Server (AI Agents): https://mcp.fast.io/sse
> MCP Skills & Tool Definitions: https://mcp.fast.io/skill.md

Fast.io gives AI agents a complete file management and collaboration platform. Upload outputs, create branded data rooms, ask questions about documents using built-in AI, and hand everything off to a human when the job is done. No infrastructure to manage, no subscriptions, no credit card required.

**For AI agents:** Create an account with `agent=true`, get 100 GB storage and 5,000 monthly credits free, build workspaces and shares for your users, query documents with built-in RAG, and transfer ownership to humans when ready. See the [Agent Integration Guide](https://docs.fast.io/agents) for workflows and examples.

**For MCP-enabled agents:** Connect to `https://mcp.fast.io/sse` (Server-Sent Events transport) to interact with Fast.io workspaces, shares, files, and storage directly via the Model Context Protocol. See [skill.md](https://mcp.fast.io/skill.md) for available tools and skill definitions.

This file is a condensed technical reference for LLMs. For interactive documentation visit https://docs.fast.io.

## What Fast.io Does

Fast.io is cloud storage and file sharing built for collaboration between agents and humans.

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

## Agent Plan (Free)

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

Credits cover: storage (100/GB), bandwidth (212/GB), AI tokens (1/100 tokens), document ingestion (10/page), video ingestion (5/sec), image ingestion (5/image), file conversions (25/each). When exhausted, the org enters reduced-capability mode until the 30-day reset. The org is never deleted.

**When credits run out or plan limits are reached (agent accounts):** The recommended path is to transfer ownership to a human user who can upgrade to a paid plan. Create a transfer token via `POST /current/org/{org_id}/transfer/token/create/`, then give the human this claim URL: `https://go.fast.io/claim?token={token}`. See the "Transfer Ownership to a Human" workflow below. The transfer/claim API is only available to agent accounts that own the org.

**When credits run out (human accounts):** The transfer/claim API is not available. Instead, direct the user to upgrade their org's plan to Pro or Business at `https://fast.io` or via `POST /current/org/{org_id}/billing/`.

After transfer to a human, the org moves to the free plan with a 14-day trial. Humans can upgrade to Pro (1 TB, unlimited credits) or Business (5 TB, unlimited credits).

## Profile Hierarchy

User (Type 1) → Organization (Type 2) → Workspace (Type 3) / Share (Type 4)
Users own organizations. Organizations own workspaces and shares. Users can also directly own shares.
All profile IDs are 19-digit numeric strings (e.g., "1234567890123456789"). Most endpoints also accept a custom name in place of the numeric ID — see the ID Formats section below.
Account types: `human` or `agent` — visible in all user objects via `account_type` field.

## Authentication

All authenticated endpoints require: `Authorization: Bearer {jwt_token}`

Methods:
- Basic Auth → JWT: `GET /current/user/auth/` with HTTP Basic Auth (email:password). Returns `auth_token` (JWT). If `2factor: true`, token has limited scope until 2FA verification.
- OAuth 2.0 PKCE: For desktop/mobile apps. Access tokens last 1 hour, refresh tokens 30 days. S256 challenge method only.
- API Keys: Long-lived tokens for service-to-service communication. Same Bearer header format. Create via `POST /current/user/auth/key/`.
- 2FA: When enabled, Basic Auth returns limited-scope token. Complete via `/current/user/auth/2factor/auth/{token}/`.

**Agent quickstart:** Create account with `POST /current/user/` — you **must** set `agent=true`. AI agents should **always** create agent accounts, never human accounts. Agent accounts skip email verification, and orgs created by agents are always on the `agent` plan. Using a human account limits your capabilities: you cannot use the transfer/claim API to hand off orgs, and credit exhaustion requires the human to upgrade manually. Authenticate with Basic Auth, use the returned JWT for all subsequent calls.

## Response Envelope

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

Error:
```json
{"result": false, "error": {"code": 195654, "text": "Human-readable message", "documentation_url": "https://docs.fast.io/errors", "resource": "POST /current/user/"}}
```

- `result`: boolean — `true` on success, `false` on error
- `error.code`: Unique error identifier (integer) for debugging
- `error.text`: Human-readable error message, safe to display
- `error.documentation_url`: Link to error documentation (string or null)
- `error.resource`: The endpoint that produced the error

## Error Codes

The HTTP status code is determined by the error category. Common categories and their HTTP mappings:

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

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

## Rate Limiting

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

## Pagination

Keyset (cursor-based) pagination on list endpoints. Parameters:
- `sort_by`: name | updated | created | type (default: name)
- `sort_dir`: asc | desc (default: asc)
- `page_size`: 100 | 250 | 500 (default: 100, snapped to nearest)
- `cursor`: opaque string from previous response

Response includes: `pagination.has_more` (boolean), `pagination.next_cursor` (string|null), `pagination.page_size` (integer).

Applies to: workspace storage list, share storage list.

## ID Formats

- Profile IDs (user, org, workspace, share): 19-digit numeric string
- Node IDs (files, folders): OpaqueId — 30-character alphanumeric string, displayed with hyphens in API responses (e.g., `f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4`). Prefix indicates type: `f` = file, `d` = folder, `n` = note.
- Upload IDs: OpaqueId — alphanumeric string (same format as node IDs, prefixed for upload type)
- Opaque IDs (quickshare tokens): 30-character alphanumeric string
- Special folder aliases: Use the literal string `"root"` for the storage root folder and `"trash"` for the trash folder in URL paths (e.g., `/storage/root/list/`, `/storage/trash/list/`)

**Custom names as identifiers:** Most endpoints that accept a profile ID in the URL path also accept a custom name. The API automatically resolves the identifier type:

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

For example, both of these are equivalent:
- `GET /current/workspace/1234567890123456789/details/`
- `GET /current/workspace/my-project/details/`

## Agent Workflows

### Create an Agent Account
1. `POST /current/user/` with `email_address`, `password`, `tos_agree=true`, `agent=true` — **`agent=true` is required**, skips email verification, sets `account_type` to `"agent"` permanently
2. `GET /current/user/auth/` with Basic Auth — get JWT
3. `POST /current/org/create/` with `name`, `domain` — agent accounts are **always** assigned the `agent` plan (no other plan is available to agents)
4. `POST /current/org/{org_id}/create/workspace/` with `folder_name` (URL-safe identifier) and `name` (display name) — `intelligence=true` by default for agent accounts

### Upload Files
- **Small files (< 4MB):** `POST /current/upload/` as `multipart/form-data` with `name`, `size`, and `chunk` (file field). Include `action=create`, `instance_id={workspace_or_share_id}`, and optionally `folder_id` (OpaqueId or `"root"`) to auto-add the file to storage — returns `new_file_id` (OpaqueId of the created node). Without a target, returns only the upload session `id`.
- **Large files:** Create session (`POST /current/upload/` with `name`, `size` but no `chunk`) → upload chunks (`POST /current/upload/{upload_id}/chunk/` with `Content-Range` header) → complete assembly (`POST /current/upload/{upload_id}/complete/`) → add to storage via `addfile`
- **From URL:** `POST /current/web_upload/` with `source_url` — supports Google Drive, OneDrive, Box, Dropbox via OAuth
- **Add to storage:** `POST /current/workspace/{id}/storage/{folder}/addfile/` — the `{folder}` path parameter is an OpaqueId or `"root"`. Body parameter `from` is a JSON-encoded string: `from={"type":"upload","upload":{"id":"{upload_id}"}}`
- **Add to share:** `POST /current/share/{id}/storage/{folder}/addfile/` — same `from` format

### Query Documents with AI
- **With intelligence ON (auto-indexed):** Create chat scoped to files/folders, AI retrieves and answers with citations
- **Without intelligence:** Attach up to 10 files (200MB) directly to a chat for one-off analysis
- `POST /current/workspace/{id}/ai/chat/` — create chat with required params: `type` (`chat` or `chat_with_files`), `question` (2-12,768 chars). Optional: `privacy` (`private`|`public`), `name`, `files_scope` (comma-separated `nodeId:versionId` pairs, max 100), `folders_scope` (comma-separated `nodeId:depth` pairs, depth 1-10, max 100), `files_attach` (comma-separated, max 10 files, 200MB). **Note:** `files_scope` and `files_attach` are mutually exclusive — do not combine them.
- `POST /current/workspace/{id}/ai/chat/{chat_id}/message/` — send a follow-up message. Body: `question` (required)
- `GET /current/workspace/{id}/ai/chat/{chat_id}/message/{msg_id}/read/` — stream response (SSE)
- Responses include citations pointing to specific files, pages, and text snippets

### Share Files with Humans
- **Send:** Deliver files — `POST /current/workspace/{id}/create/share/` with `share_type=send`, `intelligence` (required boolean)
- **Receive:** Collect files — `share_type=receive`
- **Exchange:** Bidirectional — `share_type=exchange`
- **Storage modes (set at creation, immutable):**
  - `storage_mode=room` (default) — the share has its own isolated storage. Files are added directly to the share and are independent of any workspace. Changes to workspace files don't affect the room, and vice versa. Ideal for final deliverables, compliance packages, or any scenario where you want an immutable snapshot.
  - `storage_mode=shared_folder` — the share is backed by a specific workspace folder. The share displays the live contents of that folder — files added, updated, or removed in the workspace folder are immediately reflected in the share. No file duplication, so no extra storage cost. Pass `folder_node_id={folder_opaque_id}` (or `create_folder=true` with `folder_name`). Expiration dates are not allowed on shared folder shares since the content is live.
- Both modes look the same to share recipients — a branded data room with file preview, download controls, and all share features. The difference is whether the content is a snapshot (room) or a live view (shared folder).
- Features: password protection (Send only, requires "Anyone" access), expiration (rooms only), custom branding, guest access, inline file preview
- **QuickShare:** Temporary link for a single file (workspace-only, max 1 GB) — `POST /current/workspace/{id}/storage/{node_id}/quickshare/` with optional `expires` (seconds, default 3 hours, max 24 hours). Returns an `id` (OpaqueId) for public access at `/current/quickshare/{opaque_id}/`

### Transfer Ownership to a Human

Use this workflow when the agent plan's credits are exhausted, plan limits are reached, or the agent's work is complete and a human should take over. Transferring is the only way to upgrade beyond the agent plan.

**Requires:** The account must be an `agent` account type (`agent=true` at signup) and must be the owner of the org. Human accounts cannot use the transfer/claim API. This is why agents should always create agent accounts.

1. `POST /current/org/{org_id}/transfer/token/create/` — agent creates a transfer token (64-char string, valid 72 hours)
2. Build the claim URL: `https://go.fast.io/claim?token={token}` — send this link to the human user
3. Human opens the claim URL, logs in (or creates an account), and claims the org
4. Alternatively, the human can claim programmatically: `POST /current/org/transfer/claim/` with `token` in the body
5. **Result:** Human becomes owner of org + all workspaces, agent is demoted to admin, plan changes to free with a fresh 14-day trial. Human can then upgrade to Pro (1 TB, unlimited credits) or Business (5 TB, unlimited credits).
- Only agent accounts can create/list/delete tokens; only human accounts can claim
- Max 5 active tokens per org

### Monitor Usage
- `GET /current/org/{org_id}/billing/usage/limits/credits/` — credit consumption and limits
- `GET /current/org/{org_id}/billing/usage/meters/list/` — detailed usage breakdown
- `GET /current/events/search/?workspace_id={id}` — activity feed
- `GET /current/events/search/summarize/?workspace_id={id}` — AI-powered activity summary

## Endpoints

### Ping & System

GET /current/ping/
Health check. No auth required. Returns: status, timestamp, service name.

GET /current/system/status/
System status. No auth required. Returns: system operational status.

GET /current/llms/
Serves this llms.txt reference file as plain text. No auth required. Cached for 1 hour.

GET /current/agents/
Agent integration guide (markdown). Covers capabilities, workflows, plan details, and common patterns. No auth required. Cached for 1 hour.

### User Management

POST /current/user/
Create a new user account. No auth required (IP-throttled). Set `agent=true` for AI agent accounts (skips email verification, account_type becomes "agent").

POST /current/user/update/
Update current user profile. Auth required.

POST /current/user/close/
Close (soft-delete) current user account. Auth required.

POST /current/user/email/
Check if an email address is in use. No auth required.

POST /current/user/email/reset/
Request a password reset email. No auth required.

POST /current/user/email/validate/
Send or validate email verification code. Auth required.

POST /current/user/password/{code}/
Set a new password via reset code. No auth required.

GET /current/user/password/{code}/details/
Get details of a password reset code. No auth required.

GET /current/user/phone/{country_code}-{phone_number}/
Validate a phone number. Auth required.

GET /current/user/pin/
Get user support PIN and Intercom hash. Auth required.

GET /current/user/assets/
List available user asset metadata types. Auth required.

GET /current/user/available_profiles/
Check what profile types the user has access to. Auth required.

GET /current/user/invitation/{invitation_id}/details/
Get details for a specific invitation. Auth required.

GET /current/user/invitation/{invitation_id}/public/details/
Get public details for an invitation. No auth required.

POST /current/user/invitations/acceptall/
Accept all pending invitations. Auth required.

GET /current/user/invitations/list/
List all pending invitations. Auth required.

GET /current/user/me/allowed/
Check if user's country allows creating shares/orgs. Auth required.

GET /current/user/{user_id}/assets/
List set assets for a user. Auth required.

GET /current/user/me/autosync/{state}/
Enable or disable profile photo auto-sync. Auth required.

GET /current/user/{user_id}/details/
Get user profile details. Auth required. Accepts "me" as user_id.

GET /current/user/me/limits/orgs/
Check free org creation eligibility. Auth required.

GET /current/user/me/list/shares/
List all shares accessible to the current user. Auth required.

### User Authentication

GET /current/user/auth/
Authenticate via Basic Auth. Returns JWT token. Rate limited: 60/hour, 240/day per IP.

GET /current/user/auth/check/
Validate current JWT and get user ID. Auth required.

POST /current/user/auth/key/
Create a new API key. Auth required.

GET /current/user/auth/key/{key_id}/
Get details of an API key. Auth required.

DELETE /current/user/auth/key/{key_id}/
Delete an API key. Auth required.

GET /current/user/auth/keys/
List all API keys for the user. Auth required.

GET /current/user/auth/2factor/
Get current 2FA status. Auth required.

POST /current/user/auth/2factor/{channel}/
Enable 2FA on the account. Auth required.

DELETE /current/user/auth/2factor/{token}/
Disable (remove) 2FA from the account. Auth required.

POST /current/user/auth/2factor/auth/{token}/
Authenticate with a 2FA code and get a full JWT. Auth required (limited-scope token).

GET /current/user/auth/2factor/send/sms/
Send a 2FA code via SMS. Auth required.

GET /current/user/auth/2factor/send/call/
Send a 2FA code via voice call. Auth required.

GET /current/user/auth/2factor/send/whatsapp/
Send a 2FA code via WhatsApp. Auth required.

POST /current/user/auth/2factor/verify/{token}/
Verify a 2FA setup code to confirm enrollment. Auth required.

### User Search

GET /current/users/search/
Search for users by name or email. Auth required. Query parameter: `q` (search term).

### Organization Management

POST /current/org/create/
Create a new organization. Auth required. Agent accounts are always assigned the `agent` plan (free, credit-limited, no trial, no expiration). Agents cannot select or change to a human plan.

GET /current/org/assets/
List available org asset metadata types. Auth required.

GET /current/org/billing/plan/list/
List available billing plans. Auth required. Filtered by account type: agents only see the `agent` plan, humans see human plans (free, pro, business). Agents cannot subscribe to human plans.

GET /current/org/{org_id}/details/
Get org details. Auth required.

GET /current/org/{org_id}/public/details/
Get public org details (limited info). Auth required.

POST /current/org/{org_id}/update/
Update org details. Auth required. Owner/admin only.

POST /current/org/{org_id}/close/
Close an organization. Auth required. Owner only.

GET /current/org/{org_id}/assets/
List assets for an org. Auth required.

POST /current/org/{org_id}/assets/{asset_name}/
Upload an org asset. Auth required. Owner/admin only.

DELETE /current/org/{org_id}/assets/{asset_name}/
Delete an org asset. Auth required. Owner/admin only.

POST /current/org/{org_id}/billing/
Create or update a subscription. Auth required. Owner only.

DELETE /current/org/{org_id}/billing/
Cancel a subscription. Auth required. Owner only.

GET /current/org/{org_id}/billing/details/
Get billing/subscription details. Auth required. Owner only.

GET /current/org/{org_id}/billing/usage/limits/credits/
Get credit limit status. Auth required.

GET /current/org/{org_id}/billing/usage/members/list/
List billable members. Auth required.

GET /current/org/{org_id}/billing/usage/meters/list/
Get usage meter data. Auth required.

POST /current/org/{org_id}/create/workspace/
Create a workspace in the org. Auth required.

GET /current/org/{org_id}/list/workspaces/
List accessible workspaces in the org. Auth required.

POST /current/org/{org_id}/members/{email_or_user_id}/
Add or invite a member. The target is specified as a path parameter: use a user ID to add an existing user, or an email address to send an invitation. Auth required. Owner/admin only.

DELETE /current/org/{org_id}/members/{user_id}/
Remove a member. The target user ID is specified as a path parameter. Auth required. Owner/admin only.

GET /current/org/{org_id}/members/list/
List org members. Auth required.

DELETE /current/org/{org_id}/member/
Leave the organization (self). Auth required.

GET /current/org/{org_id}/member/{user_id}/details/
Get member details. Auth required.

POST /current/org/{org_id}/member/{user_id}/update/
Update member permissions. Auth required. Owner/admin only.

GET /current/org/{org_id}/member/{user_id}/transfer_ownership/
Transfer org ownership. Auth required. Owner only.

POST /current/org/{org_id}/members/join/
Join an org (via invite or domain). Auth required.

GET /current/org/{org_id}/members/invitations/list/
List invitations for the org. Auth required.

POST /current/org/{org_id}/members/invitation/{invitation_id}/
Update an invitation. Auth required.

DELETE /current/org/{org_id}/members/invitation/{invitation_id}/
Delete an invitation. Auth required.

### Organization Transfer (Agent → Human)

Agents build orgs, then transfer ownership to humans. The human gets the org + all workspaces, the agent stays as admin. The claim URL for humans is `https://go.fast.io/claim?token={token}`.

POST /current/org/{org_id}/transfer/token/create/
Create a transfer token (64-char string, valid 72 hours, max 5 per org). Auth required. Agent owner only. Org must be on agent plan.

GET /current/org/{org_id}/transfer/token/list/
List active (pending) transfer tokens for an org. Auth required. Agent owner only.

DELETE /current/org/{org_id}/transfer/token/{token_id}/
Soft-delete a pending transfer token. Auth required. Agent owner only.

GET /current/org/transfer/claim/public/details/
Preview transfer token details before claiming. Returns token state, org info, and agent creator profile. No auth required (IP-throttled). Query param: `token` (64-char string).

POST /current/org/transfer/claim/
Claim an agent-owned org using a transfer token. Auth required. Human users only. Body: `token` (64-char string). On success: ownership transfers, plan changes to free with 14-day trial, all workspace memberships transfer (human→owner, agent→admin).

### Organization Discovery

GET /current/orgs/list/
List orgs user is a member of. Auth required. Query param: `subscription` filter.

GET /current/orgs/all/
List all accessible orgs (joined + invited). Auth required.

GET /current/orgs/available/
List orgs available to join (not yet joined). Auth required.

GET /current/orgs/list/external/
List orgs accessed via workspace membership. Auth required.

GET /current/orgs/check/domain/
Check if an org domain name is available. Auth required.

GET /current/orgs/industries/
List available industry types. Auth required.

### Workspace Management

GET /current/workspace/{workspace_id}/details/
Get workspace details. Auth required.

POST /current/workspace/{workspace_id}/update/
Update workspace settings. Auth required. Owner/admin only.

DELETE /current/workspace/{workspace_id}/delete/
Delete (close) a workspace. Auth required. Owner only.

POST /current/workspace/{workspace_id}/archive/
Archive a workspace. Auth required. Owner/admin only.

POST /current/workspace/{workspace_id}/unarchive/
Unarchive a workspace. Auth required. Owner/admin only.

GET /current/workspace/assets/
List available workspace asset types. Auth required.

GET /current/workspace/{workspace_id}/assets/
List assets for a workspace. Auth required.

POST /current/workspace/{workspace_id}/assets/{asset_name}/
Upload/set a workspace asset. Auth required.

DELETE /current/workspace/{workspace_id}/assets/{asset_name}/
Delete a workspace asset. Auth required.

GET /current/workspace/{workspace_id}/assets/{asset_name}/read/
Read asset binary data. Auth required.

POST /current/workspace/{workspace_id}/create/share/
Create a new share in the workspace. Auth required. Body: `share_type` (send/receive/exchange), `intelligence` (boolean, required). Storage mode: `storage_mode=room` (independent storage, default) or `storage_mode=shared_folder` (live workspace folder — requires `folder_node_id` or `create_folder=true` with `folder_name`).

GET /current/workspace/{workspace_id}/list/shares/
List shares in the workspace. Auth required.

POST /current/workspace/{workspace_id}/import/share/{share_id}/
Import a user-owned share into the workspace. Auth required.

### Workspace Storage

In storage endpoints, `{parent_id}` and `{node_id}` are OpaqueIds (e.g., `f3jm5-zqzfx-...`), or the special aliases `"root"` (storage root) and `"trash"` (trash folder).

POST /current/workspace/{workspace_id}/storage/{parent_id}/addfile/
Add a file from upload to storage. Auth required. Body: `from` (JSON string, e.g., `{"type":"upload","upload":{"id":"{upload_id}"}}`).

POST /current/workspace/{workspace_id}/storage/{parent_id}/addlink/
Add a share link to workspace storage. Auth required.

POST /current/workspace/{workspace_id}/storage/{parent_id}/createfolder/
Create a new folder. Auth required.

POST /current/workspace/{workspace_id}/storage/{parent_id}/createnote/
Create a new markdown note. Auth required.

GET /current/workspace/{workspace_id}/storage/{parent_id}/list/
List folder contents. Auth required. Paginated (see Pagination section).

GET /current/workspace/{workspace_id}/storage/{node_id}/details/
Get node details. Auth required.

POST /current/workspace/{workspace_id}/storage/{node_id}/update/
Update a node (rename, replace content, metadata). Auth required.

POST /current/workspace/{workspace_id}/storage/{node_id}/updatenote/
Update a note's content or name. Auth required.

POST /current/workspace/{workspace_id}/storage/{node_id}/move/
Move a node to another folder. Auth required.

POST /current/workspace/{workspace_id}/storage/{node_id}/copy/
Copy a node to another folder. Auth required.

POST /current/workspace/{workspace_id}/storage/{node_id}/transfer/
Copy a node to another storage instance. Auth required.

DELETE /current/workspace/{workspace_id}/storage/{node_id}/delete/
Move a node to trash (or empty trash). Auth required.

DELETE /current/workspace/{workspace_id}/storage/{node_id}/purge/
Permanently delete a trashed node. Auth required.

POST /current/workspace/{workspace_id}/storage/{node_id}/restore/
Restore a node from trash. Auth required.

POST /current/workspace/{workspace_id}/storage/{node_id}/restore-version/
Restore a file to a previous version. Auth required.

GET /current/workspace/{workspace_id}/storage/{node_id}/versions/
List versions of a file. Auth required.

GET /current/workspace/{workspace_id}/storage/{node_id}/read/
Download file content (binary). Auth required.

GET /current/workspace/{workspace_id}/storage/{node_id}/requestread/
Request a download token. Auth required.

GET /current/workspace/{workspace_id}/storage/{folder_id}/zip/
Download folder as ZIP archive. Auth required.

GET /current/workspace/{workspace_id}/storage/search/
Search files in workspace. Auth required. Query param: `search` (keyword string).

POST /current/workspace/{workspace_id}/storage/{node_id}/quickshare/
Create a temporary public link for a single file (max 1 GB). Auth required. Optional param: `expires` (seconds, default 10800/3h, max 86400/24h). Returns OpaqueId for public access.

GET /current/workspace/{workspace_id}/storage/quickshares/list/
List all quickshares in workspace. Auth required.

GET /current/workspace/{workspace_id}/storage/{node_id}/lock/
Get lock status for a node. Auth required.

POST /current/workspace/{workspace_id}/storage/{node_id}/lock/
Acquire a lock on a node. Auth required. Optional: `duration` (60-3600 seconds), `client_info` (JSON). Returns `lock_token`, `expires_at`.

DELETE /current/workspace/{workspace_id}/storage/{node_id}/lock/
Release a lock. Auth required. Param: `lock_token`.

POST /current/workspace/{workspace_id}/storage/{node_id}/lock/heartbeat/
Extend lock expiration. Auth required. Param: `lock_token`.

GET /current/workspace/{workspace_id}/storage/{node_id}/preview/{preview_type}/preauthorize/
Get a preview download URL. Auth required.

GET /current/workspace/{workspace_id}/storage/{node_id}/preview/{preview_type}/read/
Read or redirect to a preview. Auth required.

GET /current/workspace/{workspace_id}/storage/{node_id}/preview/{preview_type}/read/{token}/file/{filename}
Read a specific preview file via token. Token-based auth.

GET /current/workspace/{workspace_id}/storage/{node_id}/transform/{transform_name}/
Get transform status. Auth required.

POST /current/workspace/{workspace_id}/storage/{node_id}/transform/{transform_name}/request/
Request a transformation. Auth required.

GET /current/workspace/{workspace_id}/storage/{node_id}/transform/{transform_name}/read/
Read transformed file content. Auth required.

GET /current/workspace/{workspace_id}/storage/{node_id}/transform/{transform_name}/requestread/
Request a transform download token. Auth required.

### Workspace Members

POST /current/workspace/{workspace_id}/members/{email_or_user_id}/
Add a member or send invitation. The target is specified as a path parameter: use a user ID to add an existing user, or an email address to send an invitation. Auth required. Owner/admin only.

DELETE /current/workspace/{workspace_id}/members/{user_id}/
Remove a member. The target user ID is specified as a path parameter. Auth required. Owner/admin only.

GET /current/workspace/{workspace_id}/members/list/
List all workspace members. Auth required.

DELETE /current/workspace/{workspace_id}/member/
Leave workspace (self-removal). Auth required.

GET /current/workspace/{workspace_id}/member/{member_id}/details/
Get member details. Auth required.

POST /current/workspace/{workspace_id}/member/{member_id}/update/
Update a member's properties. Auth required. Owner/admin only.

GET /current/workspace/{workspace_id}/member/{member_id}/transfer_ownership/
Transfer workspace ownership. Auth required. Owner only.

POST /current/workspace/{workspace_id}/members/join/
Join workspace (self-join by org membership). Auth required.

POST /current/workspace/{workspace_id}/members/join/{invitation_key}/{action}/
Join workspace via invitation. Auth required.

GET /current/workspace/{workspace_id}/members/invitations/list/
List workspace invitations. Auth required.

GET /current/workspace/{workspace_id}/members/invitations/list/{state}/
List invitations filtered by state. Auth required.

POST /current/workspace/{workspace_id}/members/invitation/{invitation_id}/
Update an invitation. Auth required.

DELETE /current/workspace/{workspace_id}/members/invitation/{invitation_id}/
Delete an invitation. Auth required.

### Workspace AI

Workspaces with `intelligence` enabled auto-index uploaded files for RAG. Chat types: `chat` (basic) or `chat_with_files` (RAG with file/folder scope). File scope: `files_scope=nodeId:versionId,...` (max 100) or `folders_scope=nodeId:depth,...` (max 100). Direct attachments: `files_attach` (max 10 files, 200MB). Responses stream via SSE with citations to specific files, pages, and snippets.

POST /current/workspace/{workspace_id}/ai/chat/
Create a new chat with an initial message. Auth required. Body: `question` (required, 2-12768 chars), `type` (`chat` or `chat_with_files`). Optional: `privacy`, `name`, `files_scope`, `folders_scope`, `files_attach`.

GET /current/workspace/{workspace_id}/ai/chat/list/
List chats for a workspace. Auth required.

GET /current/workspace/{workspace_id}/ai/chat/{chat_id}/details/
Get chat details with messages. Auth required.

POST /current/workspace/{workspace_id}/ai/chat/{chat_id}/update/
Update chat properties. Auth required.

DELETE /current/workspace/{workspace_id}/ai/chat/{chat_id}/
Delete a chat. Auth required.

POST /current/workspace/{workspace_id}/ai/chat/{chat_id}/message/
Send a follow-up message to a chat. Auth required. Body: `question` (required).

GET /current/workspace/{workspace_id}/ai/chat/{chat_id}/messages/list/
List messages in a chat. Auth required.

GET /current/workspace/{workspace_id}/ai/chat/{chat_id}/message/{message_id}/details/
Get message details. Auth required.

GET /current/workspace/{workspace_id}/ai/chat/{chat_id}/message/{message_id}/read/
Stream message response (Server-Sent Events). Auth required.

POST /current/workspace/{workspace_id}/ai/chat/{chat_id}/publish/
Publish a private chat. Auth required.

POST /current/workspace/{workspace_id}/ai/share/
Generate AI Share markdown. Auth required.

GET /current/workspace/{workspace_id}/ai/transactions/
List AI transactions. Auth required.

### Workspace Metadata

POST /current/workspace/{workspace_id}/metadata/templates/
Create a new metadata template. Auth required.

DELETE /current/workspace/{workspace_id}/metadata/templates/
Delete a metadata template. Auth required.

GET /current/workspace/{workspace_id}/metadata/templates/list/
List all templates for the workspace. Auth required.

GET /current/workspace/{workspace_id}/metadata/templates/{template_id}/details/
Get template details. Auth required.

POST /current/workspace/{workspace_id}/metadata/templates/{template_id}/settings/
Update template instance settings (enable/disable, priority). Auth required.

POST /current/workspace/{workspace_id}/metadata/templates/{template_id}/update/
Update a template's definition. Auth required.

DELETE /current/workspace/{workspace_id}/storage/{node_id}/metadata/
Delete metadata keys from a file. Auth required.

GET /current/workspace/{workspace_id}/storage/{node_id}/metadata/details/
Get all metadata for a single file. Auth required.

POST /current/workspace/{workspace_id}/storage/{node_id}/metadata/extract/
AI-extract metadata from a file. Auth required.

GET /current/workspace/{workspace_id}/storage/{node_id}/metadata/list/{template_id}/
List metadata objects by template. Auth required.

POST /current/workspace/{workspace_id}/storage/{node_id}/metadata/template_select/
AI-select the best template for a file. Auth required.

GET /current/workspace/{workspace_id}/storage/{node_id}/metadata/templates/
List templates in use across files. Auth required.

POST /current/workspace/{workspace_id}/storage/{node_id}/metadata/update/{template_id}/
Set/update metadata key-values on a file. Auth required.

POST /current/workspace/{workspace_id}/storage/{node_id}/metadata/view/
Create or update a saved metadata view. Auth required.

DELETE /current/workspace/{workspace_id}/storage/{node_id}/metadata/view/
Delete a saved metadata view. Auth required.

GET /current/workspace/{workspace_id}/storage/{node_id}/metadata/views/
List all saved metadata views. Auth required.

### Workspace Discovery

GET /current/workspaces/all/
List all workspaces the user has joined or can access. Auth required.

GET /current/workspaces/available/
List workspaces the user can join but has not yet joined. Auth required.

GET /current/workspaces/check/name/{name}/
Check if a workspace folder name is already in use. Auth required.

### Share Management

Shares are for exchanging files with humans. Three share types: Send (deliver files), Receive (collect files), Exchange (bidirectional). Two storage modes (set at creation, immutable):

- **Room** (`storage_mode=room`, default) — the share has its own isolated storage. Files are added directly to the share and are independent of any workspace. Changes to workspace files don't affect the room, and vice versa. Ideal for final deliverables, compliance packages, or any scenario where you want an immutable snapshot. Supports expiration dates, archiving, password protection (Send type only), custom branding (logos, colors, background images), guest access, inline file preview, download controls, post-download messaging, and AI-powered auto-titling.
- **Shared Folder** (`storage_mode=shared_folder`) — the share is backed by a specific workspace folder. The share displays the live contents of that folder — files added, updated, or removed in the workspace folder are immediately reflected in the share. No file duplication, so no extra storage cost. Pass `folder_node_id={folder_opaque_id}` (or `create_folder=true` with `folder_name`). Expiration dates and archiving are not allowed since the content is live. If the backing folder is deleted, the share becomes orphaned (`is_orphaned: true` in details response).

Both modes look the same to share recipients — a branded data room with file preview, download controls, and all share features. The difference is whether the content is a snapshot (room) or a live view (shared folder).

GET /current/share/{share_id}/details/
Get share details. Auth required.

POST /current/share/{share_id}/update/
Update share settings. Auth required. Owner/admin only.

DELETE /current/share/{share_id}/delete/
Delete (close) a share. Auth required. Owner only.

POST /current/share/{share_id}/archive/
Archive a share. Auth required. Owner/admin only.

POST /current/share/{share_id}/unarchive/
Unarchive a share. Auth required. Owner/admin only.

POST /current/share/{share_id}/auth/password/
Authenticate with share password (for password-protected shares). No user auth required.

GET /current/share/assets/
List available share asset metadata. Auth required.

GET /current/share/{share_id}/assets/
List assets set on a share. Auth required.

POST /current/share/{share_id}/assets/{asset_id}/
Upload/set a share asset. Auth required.

DELETE /current/share/{share_id}/assets/{asset_id}/
Delete a share asset. Auth required.

### Share Storage

Share storage follows the same conventions as workspace storage: `{node_id}` is an OpaqueId or `"root"`/`"trash"`.

POST /current/share/{share_id}/storage/{node_id}/addfile/
Add a file from upload. Auth required. Body: `from` (JSON string, same format as workspace addfile).

POST /current/share/{share_id}/storage/{node_id}/createfolder/
Create a new folder. Auth required.

GET /current/share/{share_id}/storage/{node_id}/list/
List folder contents. Auth required. Paginated.

GET /current/share/{share_id}/storage/{node_id}/details/
Get node details. Auth required.

POST /current/share/{share_id}/storage/{node_id}/update/
Update file name, content, or metadata. Auth required.

POST /current/share/{share_id}/storage/{node_id}/move/
Move a node to a destination folder. Auth required.

POST /current/share/{share_id}/storage/{node_id}/copy/
Copy a node to a destination folder. Auth required.

POST /current/share/{share_id}/storage/{node_id}/transfer/
Copy a node to another storage instance. Auth required.

DELETE /current/share/{share_id}/storage/{node_id}/delete/
Delete a node (move to trash) or empty trash. Auth required.

DELETE /current/share/{share_id}/storage/{node_id}/purge/
Permanently delete a node from trash. Auth required.

POST /current/share/{share_id}/storage/{node_id}/restore/
Restore a node from trash. Auth required.

POST /current/share/{share_id}/storage/{node_id}/restore-version/
Restore a file to a previous version. Auth required.

GET /current/share/{share_id}/storage/{node_id}/versions/
List file version history. Auth required.

GET /current/share/{share_id}/storage/{node_id}/read/
Download file content (binary). Auth required.

GET /current/share/{share_id}/storage/{node_id}/requestread/
Get a download token. Auth required.

GET /current/share/{share_id}/storage/{node_id}/zip/
Download folder as ZIP archive. Auth required.

GET /current/share/{share_id}/storage/search/
Search files in the share. Auth required.

GET /current/share/{share_id}/storage/{node_id}/preview/{preview_type}/preauthorize/
Get a preview download token and URL. Auth required.

GET /current/share/{share_id}/storage/{node_id}/preview/{preview_type}/read/
Read or redirect to a preview. Auth required.

GET /current/share/{share_id}/storage/{node_id}/preview/{preview_type}/read/{download_token}/file/{filename}
Download a specific preview file. Token-based auth.

GET /current/share/{share_id}/storage/{node_id}/transform/{transform_name}/
Get transform status. Auth required.

POST /current/share/{share_id}/storage/{node_id}/transform/{transform_name}/request/
Request a transformation. Auth required.

GET /current/share/{share_id}/storage/{node_id}/lock/
Get lock status. Auth required.

POST /current/share/{share_id}/storage/{node_id}/lock/
Acquire a lock. Auth required.

DELETE /current/share/{share_id}/storage/{node_id}/lock/
Release a lock. Auth required.

POST /current/share/{share_id}/storage/{node_id}/lock/heartbeat/
Extend lock expiration. Auth required.

### Share Members

POST /current/share/{share_id}/members/{email_or_user_id}/
Add a member or send an invitation. The target is specified as a path parameter: use a user ID to add an existing user, or an email address to send an invitation. Auth required. Owner/admin only.

DELETE /current/share/{share_id}/members/{user_id}/
Remove a member. The target user ID is specified as a path parameter. Auth required. Owner/admin only.

GET /current/share/{share_id}/members/list/
List all members. Auth required.

DELETE /current/share/{share_id}/member/
Leave share (self-removal). Auth required.

GET /current/share/{share_id}/member/{user_id}/details/
Get member details. Auth required.

POST /current/share/{share_id}/member/{user_id}/update/
Update member permissions/settings. Auth required. Owner/admin only.

GET /current/share/{share_id}/member/{user_id}/transfer_ownership/
Transfer share ownership. Auth required. Owner only.

GET /current/share/{share_id}/members/invitations/list/
List invitations. Auth required.

POST /current/share/{share_id}/members/invitation/{invitation_id}/
Update an invitation. Auth required.

DELETE /current/share/{share_id}/members/invitation/{invitation_id}/
Delete an invitation. Auth required.

POST /current/share/{share_id}/members/join/
Join a share (self or via invitation). Auth required.

### Share AI

GET /current/share/{share_id}/ai/autoog/
Generate an OG image for a share. Auth required.

POST /current/share/{share_id}/ai/autotitle/
Generate title and description for a share. Auth required.

POST /current/share/{share_id}/ai/chat/
Create a new AI chat with an initial message. Auth required. Body: `question` (required, 2-12768 chars), `type` (`chat` or `chat_with_files`). Optional: `privacy`, `name`, `files_scope`, `folders_scope`, `files_attach`.

GET /current/share/{share_id}/ai/chat/list/
List all chats for a share. Auth required.

GET /current/share/{share_id}/ai/chat/{chat_id}/details/
Get chat details with message history. Auth required.

POST /current/share/{share_id}/ai/chat/{chat_id}/update/
Update a chat's name. Auth required.

DELETE /current/share/{share_id}/ai/chat/{chat_id}/
Delete a chat. Auth required.

POST /current/share/{share_id}/ai/chat/{chat_id}/message/
Send a follow-up message to an existing chat. Auth required. Body: `question` (required).

GET /current/share/{share_id}/ai/chat/{chat_id}/messages/list/
List all messages in a chat. Auth required.

GET /current/share/{share_id}/ai/chat/{chat_id}/message/{message_id}/details/
Get details for a specific message. Auth required.

GET /current/share/{share_id}/ai/chat/{chat_id}/message/{message_id}/read/
Stream message response via SSE. Auth required.

POST /current/share/{share_id}/ai/chat/{chat_id}/publish/
Publish a private chat (make it public). Auth required.

POST /current/share/{share_id}/ai/share/
Generate AI share markdown with download URLs. Auth required.

### Share Discovery

GET /current/shares/all/
List all accessible shares (joined, invited, owned). Auth required.

GET /current/shares/available/
List available shares (joined and owned, excludes invited). Auth required.

GET /current/shares/check/name/{name}/
Check if a share custom name is available. Auth required.

### File Upload (Chunked)

Upload flow: Create session → Upload chunks → Complete assembly → Add to storage

POST /current/upload/
Create a new upload session. Auth required. Body: filename, size, checksum, checksum_algo.

DELETE /current/upload/
Cancel/delete an upload session. Auth required.

GET /current/upload/algos/
List supported hash algorithms. Auth required.

GET /current/upload/details/
List all upload sessions for the current user. Auth required.

GET /current/upload/limits/
Get upload limits for the user's plan. Auth required.

GET /current/upload/limits/extensions/
Get restricted and archive file extensions. Auth required.

POST /current/upload/{upload_id}/chunk/
Upload a file chunk. Auth required. Binary body with Content-Range header.

GET /current/upload/{upload_id}/chunk/
Get chunk information. Auth required.

DELETE /current/upload/{upload_id}/chunk/
Delete a specific chunk. Auth required.

POST /current/upload/{upload_id}/complete/
Trigger upload assembly/completion. Auth required.

GET /current/upload/{upload_id}/details/
Get detailed session status. Auth required. Supports long-polling via `wait` parameter.

### Web Upload (URL Import)

POST /current/web_upload/
Create a new web upload job (import file from URL). Auth required.

GET /current/web_upload/
List user's web upload jobs. Auth required.

DELETE /current/web_upload/
Cancel an active web upload job. Auth required.

GET /current/web_upload/{upload_id}/details/
Get detailed status of a specific job. Auth required.

### OAuth 2.0

GET /current/oauth/authorize/
Initiate authorization flow (validate client and PKCE parameters). No auth required.

POST /current/oauth/authorize/
Complete authorization after user login (issue authorization code). Auth required (website session).

GET /current/oauth/authorize/info/
Validate an auth request and return client information. No auth required.

POST /current/oauth/token/
Exchange authorization code for tokens, or refresh an access token. No auth required. Content-Type: application/x-www-form-urlencoded.

POST /current/oauth/revoke/
Revoke a refresh token (logout). No auth required.

GET /current/oauth/sessions/
List all active sessions for the authenticated user. Auth required.

DELETE /current/oauth/sessions/
Revoke all sessions (logout everywhere). Auth required.

GET /current/oauth/sessions/{session_id}/
Get details of a specific session. Auth required.

DELETE /current/oauth/sessions/{session_id}/
Revoke a specific session. Auth required.

### Events

GET /current/events/search/
Search and filter events. Auth required. Query params: profile_id, type, date filters, pagination.

GET /current/events/search/summarize/
Search events with AI-powered summary. Auth required.

GET /current/event/{event_id}/details/
Get full details for a single event. Auth required.

GET /current/event/{event_id}/ack/
Acknowledge (mark as read) an event. Auth required.

### Activity Polling

GET /current/activity/poll/
Poll for activity updates on the current user's profile. Auth required. Supports long-polling.

GET /current/activity/poll/{profile_id}/
Poll for activity updates on a specific profile. Auth required. Supports long-polling.

### Comments

GET /current/comments/{entity_type}/{parent_id}/
List comments for an entity. Auth required.

GET /current/comments/{entity_type}/{parent_id}/{node_id}/
List comments for a specific node. Auth required.

POST /current/comments/{entity_type}/{parent_id}/
Create or update a comment. Auth required.

GET /current/comments/{comment_id}/details/
Get a single comment's details. Auth required.

DELETE /current/comments/{comment_id}/delete/
Soft-delete a single comment and its replies. Auth required.

POST /current/comments/bulk/delete/
Bulk soft-delete multiple comments. Auth required.

POST /current/comments/{comment_id}/reactions/
Add or change an emoji reaction. Auth required.

DELETE /current/comments/{comment_id}/reactions/
Remove an emoji reaction. Auth required.

### Metadata Templates

GET /current/metadata/templates/categories/
List all metadata template categories. Auth required.

### Quick Share

GET /current/quickshare/{opaque_id}/details/
Get QuickShare metadata and file information. No auth required (opaque ID acts as token).

GET /current/quickshare/{opaque_id}/storage/read/
Download the shared file (binary). No auth required.

GET /current/quickshare/{opaque_id}/storage/preview/{preview_type}/read/
Preview the shared file. No auth required.

GET /current/quickshare/{opaque_id}/storage/preview/{preview_type}/read/file/{filename}
Read a specific preview sub-file. No auth required.

### Webhooks

POST /current/webhooks/billing/stripe/
Receive and queue a Stripe billing webhook event. Stripe signature verification.

### Realtime & WebSocket

GET /current/realtime/auth/{room_id}
Generate a realtime JWT for a workspace or share room. Auth required.

GET /current/realtime/auth/validate/
Validate a realtime JWT and extract the room ID. Token-based.

GET /current/websocket/auth/{profile_id}
Generate a WebSocket JWT for a user, org, workspace, or share. Auth required.

### AI (Cross-Cutting)

GET /current/ai/share/{token}?file={index}
Download a file from an AI Share using a temporary token. Token-based auth.

## Share Types

Shares operate in three modes:
- Send: Owner distributes files to guests (guests can download only)
- Receive: Owner collects files from guests (guests can upload only)
- Exchange: Bidirectional file sharing (guests can upload and download)

Shares can have independent storage or use a workspace folder as their root.

## Storage Conventions

- **Root folder:** Use the literal string `"root"` as the path parameter to reference the storage root (e.g., `GET /current/workspace/{id}/storage/root/list/`)
- **Trash folder:** Use `"trash"` to list trashed items (e.g., `GET /current/workspace/{id}/storage/trash/list/`)
- **Delete vs purge:** `DELETE .../storage/{node_id}/delete/` moves to trash; `DELETE .../storage/trash/delete/` empties entire trash; `DELETE .../storage/{node_id}/purge/` permanently deletes a single trashed item
- **Node types in responses:** `"file"`, `"folder"`, `"note"`, `"link"` (always lowercase strings)
- **Node IDs in responses** are OpaqueIds with hyphens (e.g., `f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4`). Use these IDs as-is in subsequent API calls.
- **Parent field:** Nodes at the storage root show `"parent": "root"`; nested nodes show the parent's OpaqueId

## File Locking

Lock a file to prevent concurrent edits. Locks expire automatically if not renewed via heartbeat.

- **Acquire:** `POST .../storage/{node_id}/lock/` with optional `duration` (60-3600 seconds). Returns `lock_token`, `locked_at`, `expires_at`.
- **Heartbeat:** `POST .../storage/{node_id}/lock/heartbeat/` with `lock_token`. Extends expiration.
- **Release:** `DELETE .../storage/{node_id}/lock/` with `lock_token`.
- **Status:** `GET .../storage/{node_id}/lock/` — check if a file is locked and by whom.
- Available on both workspace and share storage.

## Comments

Comments use **JSON request bodies** (`Content-Type: application/json`), unlike most other endpoints.

- **Create:** `POST /current/comments/{entity_type}/{parent_id}/` or `POST /current/comments/{entity_type}/{parent_id}/{node_id}/` — `entity_type` is `workspace` or `share`
- **Required field:** `body` (1-5000 characters)
- **Optional fields:** `comment_id` (for updates), `parent_id` (for threading, single-level only), `properties` (custom object), `reference` (object)
- **Mentions:** Use `@[user:USER_ID:Display Name]` syntax in the body
- **Bulk delete:** `POST /current/comments/bulk/delete/` — also uses JSON body with `comment_ids` array

## Events Search

- **Pagination:** Uses offset-based pagination (`limit` 1-250, `offset`), not cursor-based
- **Profile filters:** Supply ONE of `user_id`, `org_id`, `workspace_id`, `share_id` — priority order if multiple supplied: user > org > workspace > share
- **Date filters:** `created-min` and `created-max` (ISO 8601, e.g., `2025-12-01T06:00:00Z`)
- **Other filters:** `event` (event name), `category`, `subcategory`, `calling_user_id`, `object_id`, `acknowledged` (`true`|`false`), `visibility`

## Common Patterns

- List endpoints return arrays in a `response` wrapper with consistent pagination
- All profile operations require the user to be a member with sufficient permissions
- Owner > Admin > Member > Guest permission hierarchy
- "me" can be used as user_id in user endpoints to reference the authenticated user
- Profile path parameters accept either a 19-digit numeric ID or a custom name (see ID Formats)
- 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
- File previews support multiple types (thumbnail, document viewer, etc.)
- File transforms support named operations (e.g., image resizing)
- Long-polling supported on activity/poll and upload/details endpoints
- Most POST endpoints use `application/x-www-form-urlencoded` bodies; exceptions: comments (JSON body), and parameters with nested objects use JSON-encoded strings in form fields (e.g., `from={"type":"upload","upload":{"id":"..."}}`)

## Additional Resources

- Full API documentation: https://docs.fast.io
- Agent integration guide: `GET /current/agents/` or https://docs.fast.io/agents — signup, billing, AI, transfer workflows, and common patterns
- MCP Server for AI agents: https://mcp.fast.io/sse (SSE transport) — enables AI agents to interact with Fast.io workspaces, shares, files, and storage directly via the Model Context Protocol
- MCP Skills & Tool Definitions: https://mcp.fast.io/skill.md — available tools, parameters, and skill descriptions for the MCP server
- Claim URL for org transfer: `https://go.fast.io/claim?token={token}` — send this to humans to claim ownership of agent-built orgs