Organization Management Org CRUD, members, billing, discovery

An organization (org) is a collector of workspaces. It can represent a company, a business unit, a team, or simply a personal collection. Orgs are the billable entity — storage, credits, and member limits are tracked at the org level. Every workspace and share lives under an org.

Profile IDs are 19-digit numeric strings. Most endpoints also accept the org's domain name (e.g., acme) in place of the numeric ID.

Internal vs External Orgs

Agents must call both GET /current/orgs/list/ and GET /current/orgs/list/external/ to discover all orgs they can access.

• Internal orgs (member: true) — orgs you created or were invited to join as a member. You have org-level access: see all workspaces (subject to permissions), manage settings if admin, appear in the member list. Listed via GET /current/orgs/list/.
• External orgs (member: false) — orgs you access only through workspace membership. A human invited you to their workspace but not to the org itself. You can see the org's name and basic public info, but cannot manage org settings, see other workspaces, or add org members. Listed via GET /current/orgs/list/external/.

External orgs are the most common pattern when a human invites an agent to help with a specific project — they add the agent to a workspace but not to the org itself.

If the human later invites the agent to the org itself, it moves from external to internal and gains org-level access.

Org Field Constraints

Member Roles and Permissions

The perm_member_manage org setting controls the minimum role required to add, remove, or update members.

Organization Security Controls

Organizations on the Enterprise plan can restrict what their members may create. All four settings are read and written on the org (see Org Field Constraints above); they are returned to admins on GET /current/org/{org_id}/details/ and written with POST /current/org/{org_id}/update/.

Both sharing settings also exist on each workspace. The effective answer is the org setting AND the workspace setting, so the org acts as a ceiling: a workspace can switch sharing off for itself, but cannot switch it back on when the org has switched it off.

Turning a sharing setting off blocks new creation only. Shares and links that already exist keep working, and remain editable and deletable.

Reading the effective answer. Do not infer these from the raw settings — a member cannot read them. Read capabilities on GET /current/org/{org_id}/details/ (for workspace creation) and on GET /current/workspace/{workspace_id}/details/ (for sharing), which already combine the role, the plan, and both policy levels for the calling user.

Refusals. A create request that policy forbids returns HTTP 403 with a reason in params: policy_workspace_create_denied or policy_sharing_disabled. These are distinct from a plan-limit refusal, which keeps reporting its own error.

The Enterprise gate is directional. Only a write that tightens one of these four settings needs the Enterprise plan: switching a sharing setting off, raising the role required to create a workspace, or taking a user off the allowlist. Such a write from an organization without the plan returns HTTP 403 with params.reason = plan_required. Resubmitting a setting at the value it already holds, or relaxing one — switching sharing back on, lowering the role, adding a user to the allowlist — returns 200 on any plan, so an organization that changes plan can always unwind what it configured. Reading is never gated.

Audit. A write that changes one of these four settings adds a policy_changes map to the org_updated event: policy_changes.<key> = { before, after } for perm_workspace_create, sharing_shares and sharing_file_links (before is the value that was in force, so a setting never configured reports its default), and policy_changes.workspace_create_allowlist = { added, removed } — counts, not user IDs, because the event is visible to every member while the list itself is admin-only. policy_changes is absent when no setting changed.

Organizations that have never configured these settings behave exactly as they did before they existed: workspace creation is open to members and above, and both sharing settings are on.

Collaboration Policies (External Invites)

Organizations on the Enterprise plan can restrict which members may bring outside people onto Portals, Shared Folders, File Shares and Workspaces. Three org-level settings share one policy envelope shape:

The envelope. Each setting is a JSON object with two role baselines and an optional per-member exception list:

{ "admin": "allowed", "member": "denied", "overrides": { "9876543210987654321": "allowed" } }

• admin and member are each "allowed" or "denied", applying to owners/admins and to ordinary members respectively (an owner reads the admin baseline).
• overrides maps a user ID to "allowed" or "denied", naming an exception to that user's role baseline. Every key must be a current member of the org — a workspace or share participant who is not an org member always reads the member baseline instead and can never be named here. Maximum 100 overrides per policy.
• Unconfigured is permissive. An org that has never set one of these three keys behaves exactly as it did before the policy existed — nobody is restricted.
• An unreadable stored value is the one exception to "permissive is the default." It resolves to "denied" for every caller until an admin resaves it, and it is echoed back as the raw stored string (not an object), so a client can detect and repair it rather than silently showing it as unset.

Reading and writing.

• Write: POST /current/org/{org_id}/update/ — send the whole envelope as a JSON string in the field named after the setting (see Update Organization below). Sending "" or "null" clears the policy back to unconfigured; the server also accepts a literal null. An omitted field leaves the stored value unchanged. Every write replaces the whole value — sending overrides as {} clears every existing exception while leaving both baselines untouched; there is no partial merge of overrides.
• Read: GET /current/org/{org_id}/details/ echoes all three envelopes raw, admin-only — the stored setting the shared policy editor round-trips.
• Effective answer: capabilities.external_invites_shares / _portals / _workspaces on the same response report the calling user's own resolved answer (their role, or their override) as booleans. These are member-visible, and a client should read them to decide whether to show an invite control rather than recomputing the effective answer from the raw envelope.

Enforcement. The org policy is the first half of the answer; each Portal, Shared Folder and Workspace also carries its own external_invites flag (allowed / denied, absent = inherit the org policy — see the Shares and Workspaces references); a File Share has no flag of its own and follows the org policy only. An object can only ever tighten below the org result, never loosen it. Refusals are HTTP 403 with a params.reason distinguishing which layer denied, so the client can route the user to the right admin:

The check looks only at whether the invitee is external — a current org member, or someone on one of this org's verified SSO domains, is never refused regardless of the policy. It applies wherever external access is created or widened: sending or resending a share, portal, workspace or File Share invitation; adding an outside user directly; accepting a pending invitation (a refusal at acceptance leaves the invitation pending rather than failing it, since the policy or the inviter's own standing can change between issuance and acceptance); and creating a Portal, Shared Folder or File Share with public access, or widening an existing one's public-access setting, including 'Anyone with a registered account' to 'Anyone with the link'. Inviting a member to the org itself is never gated — an org invite is definitionally of a non-member.

POST /current/user/invitations/acceptall/ is partial-success under this policy: a policy-refused invitation is skipped (left pending, no access granted) while every other pending invitation in the batch is still processed — see that endpoint in the Auth reference for the response shape.

Audit. org_updated carries the three keys inside its existing policy_changes map: policy_changes.<key> = { before: {admin, member}, after: {admin, member}, overrides: {added, removed, changed} }. The override numbers are counts, not user IDs — policy_changes renders for every member, while the exception list itself stays admin-only.

Credential Policy

Organizations on the Enterprise plan can cap what an API key or an OAuth grant issued inside the org may hold, and constrain it on every later request, not only at the moment it is issued. One org-level setting, credential_policy, governs two credential families independently:

The envelope, twice. credential_policy wraps one ordinary policy envelope (see Collaboration Policies above for the {admin, member, overrides} shape) per family — but here each role's value is itself an object, not a bare string:

{
  "api_keys": {
    "admin": { "max_mode": "rwa", "scope_types": ["org", "workspace", "share", "fileshare"] },
    "member": { "max_mode": "rw", "scope_types": ["workspace", "share"] },
    "overrides": { "9876543210987654321": { "max_mode": "r", "scope_types": ["share"] } }
  },
  "oauth": {
    "admin": { "max_mode": "rwa", "scope_types": ["org", "workspace", "share", "fileshare"] },
    "member": { "max_mode": "rw", "scope_types": ["workspace", "share"] },
    "overrides": {}
  }
}

• Each role's value is {"max_mode": "r"|"rw"|"rwa", "scope_types": [...]}.
• max_mode is a ceiling: the highest access mode a credential in that family may hold for any one entity governed by this org. It reads the opposite way from an ordinary scope check — a credential is refused here for holding too much, not too little.
• scope_types is the subset of entity types a credential in that family may hold a grant for against this org — org, workspace, share, fileshare. (The retired workflow type and the sign_envelope type are not selectable here. A sign_envelope grant is never refused by scope_types, but it is still bounded by max_mode.) Account-only authority (user:*, memory:*, userdetails:*) is never refused by scope_types — an account-wide key is used against every org its holder can reach, so refusing it by type here would disable it everywhere else — but it is still bounded by max_mode, evaluated locally against whichever org a given request actually touches.
• overrides maps a user ID to its own {max_mode, scope_types} value, naming an exception to that user's role baseline. Every key must be a current member of the org. Maximum 100 overrides per family.
• Unconfigured is permissive — an org that has never set credential_policy, or has cleared a family, behaves exactly as it did before the policy existed: every mode, every attributable type.
• An unreadable stored value is the one exception to "permissive is the default." It resolves to the restrictive pole — every credential in that family refused — until an admin resaves it, and it is echoed back as the raw stored string so a client can detect and repair it.

Reading and writing.

• Write: POST /current/org/{org_id}/update/ — send the whole credential_policy object as a JSON string in the credential_policy field (see Update Organization below). An omitted family is left unchanged; a family set to null is cleared back to unconfigured. Enterprise plan only to tighten — a write that lowers a max_mode or removes a scope_types entry, for either family, for anyone (admin, member, or an override), is refused with HTTP 403 and params.reason = plan_required on an org without the plan.
• Read: GET /current/org/{org_id}/details/ echoes credential_policy raw, admin-only, plus capabilities.credential_policy_api_keys and capabilities.credential_policy_oauth — the calling user's own effective {max_mode, scope_types} for each family, so a key-creation form can pre-filter its scope and mode pickers without recomputing the resolution itself.

Enforcement.

• At issuance — creating or updating an API key (see API Keys in the Auth reference), and at OAuth consent (see the OAuth 2.0 reference), the requested (or, on an update, the effective) scopes are checked against the policy of each grant's own owning org.
• At every later request — unlike the org security controls above, which are read-time or create-time only, credential_policy is re-checked on every authenticated request an API key or OAuth token makes that resolves to a governing org. Tightening the policy can make an already-issued, already-working credential start failing on its very next call, with no revocation event and no grace period.

Refusals are 403 with params.reason:

• A signed-in browser session is never subject to credential_policy — it carries no scopes claim, exactly as it is exempt from the ordinary scope checks in the Auth reference.
• A public File Share single-file link carries no API key and no account session; it is not an org-governed credential and is never checked, at issuance or at request time.
• Three collection endpoints that list an account's own orgs and shares in bulk (orgs/list, orgs/all, shares/all) resolve no single governing org per row and are permanently outside the request-time check — a stated limit, not an oversight.
• A lookup failure — the policy could not be read, or the owning org could not be resolved — is 503 (temporarily unavailable), never a silent pass and never a 401.
• Only the authority actually used for a request is checked — the concrete or wildcard grant that satisfied that request's entity, never the credential's whole scope set and never an inherited parent grant. A key holding org:A:rwa and org:B:r is checked against org A's policy only while it is acting in org A.

Audit. org_updated carries credential_policy inside its existing policy_changes map, one entry per family: policy_changes.credential_policy = { api_keys: {before, after, overrides: {added, removed, changed}}, oauth: {before, after, overrides: {added, removed, changed}} }.

Cloud Sync Policy

Organizations on the Enterprise plan can restrict whether cloud-sync import runs at all, and whether it may write local changes back to the connected provider. One org-level setting, cloud_sync, is a policy envelope (see Collaboration Policies above for the {admin, member, overrides} frame) whose value is:

{ "enabled": true, "mode": "read_write" }

• enabled (bool) — whether cloud sync runs at all for the caller this value resolves to. false stops sync in both directions; a source parks at status: "suspended_policy" and resumes on its own once the policy re-enables it.
• mode ("read" or "read_write") — whether local edits are pushed back to the provider. "read" stops only the outbound half; inbound sync continues. A mode-only flip changes no source status.
• Unconfigured is permissive — {enabled: true, mode: "read_write"}. An unreadable stored value is the one exception: it resolves to the restrictive pole (enabled: false) for every caller until an admin resaves it, echoed back raw so a client can detect and repair it.
• This is the org half only. The effective answer for a workspace is the org value resolved first, then met with that workspace's own cloud_sync_mode ceiling — see Cloud Sync Policy in the Workspaces reference for the full resolution order, the per-source effective_access_mode fields, and how a queued write-back behaves under a read policy (deferred, not failed, with a bounded ~5-day hold).

Reading and writing.

• Write: POST /current/org/{org_id}/update/ — send the whole envelope as a JSON string in the cloud_sync field (see Update Organization below). Sending ""/"null"/null clears the policy back to unconfigured. An omitted field leaves the stored value unchanged.
• Read: GET /current/org/{org_id}/details/ echoes cloud_sync raw, admin-only. There is no org-level effective-answer field: the effective answer is the workspace's effective_cloud_sync, because cloud sync is a per-workspace feature and the org value alone cannot say whether a given workspace's own setting narrows it further.

Refusals are 403 with params.reason:

mode never gates opening a new connection or inspecting/disconnecting an existing one — only enabled does, and only write-back actions consult mode. When the policy cannot be read at all, the same endpoints answer 1693 (Temporarily Unavailable) → 503 instead — retryable, never a denial.

Audit. org_updated carries cloud_sync inside its existing policy_changes map: policy_changes.cloud_sync = { before: {admin, member}, after: {admin, member}, overrides: {added, removed, changed} } — each baseline is its {enabled, mode} value (null when unconfigured), and overrides are only counted, never named.

Require-2FA Policy

Organizations on the Enterprise plan can require a second factor to sign in. One org-level setting, auth_require_2fa, is a policy envelope (see Collaboration Policies above for the {admin, member, overrides} frame) whose per-role value is one of two words:

{ "admin": "required", "member": "optional", "overrides": { "9876543210987654321": "required" } }

• admin and member are each "required" or "optional", applying to owners/admins and to ordinary members respectively (an owner reads the admin baseline).
• overrides maps a user ID to "required" or "optional", naming an exception to that user's role baseline. Every key must be a current member of the org. Maximum 100 overrides.
• Unconfigured is permissive — an org that has never set this key behaves exactly as it did before the policy existed: optional for everyone.
• An unreadable stored value is the one exception to “permissive is the default.” It resolves to the restrictive pole, "required", for every caller until an admin resaves it, and it is echoed back as the raw stored string so a client can detect and repair it.

Scope — password and social login only. This policy governs the moment a session is minted by those two flows, because they are the only ones where a factor can be demanded at that moment. It has no effect on API keys, OAuth grants, or MCP tokens — none of them is challenged for a factor at request time, regardless of what this policy says. An SSO-minted session is compliant regardless of this or any other org's requirement — the identity provider owns that factor, and the enterprise SSO exchange response never carries a 2factor or enrol_required field. See Interactive Login & Enrolment in the Auth reference for the enrolment flow this policy drives.

Reading and writing.

• Write: POST /current/org/{org_id}/update/ — send the whole envelope as a JSON string in the auth_require_2fa field (see Update Organization below). Sending "" or "null" clears the policy back to unconfigured; the server also accepts a literal null. An omitted field leaves the stored value unchanged. Enterprise plan only to tighten — a write moving optional/unconfigured to required, for admin, member, or an override.
• Read: GET /current/org/{org_id}/details/ echoes auth_require_2fa raw, admin-only — the stored setting the shared policy editor round-trips. There is no capabilities twin. Every other envelope policy on this page also reports the calling user's own resolved answer under capabilities; this one does not, because the effective answer is about a person signing in, not a place being viewed, and it is already delivered where it is actionable — enrol_required on the login response — rather than by walking every org the reader belongs to on an ordinary org read.

Refusal on write — HTTP 403 with params.reason = two_factor_admin_unenrolled: the endpoint refuses ONLY when the writer's own effective requirement goes optional/unconfigured → required and the writer holds no factor themselves (self-lockout). Tightening the member baseline, or setting an override for someone else, always succeeds even from an unenrolled admin — there is no blanket “enrol before you may require it” rule, and no SSO escape hatch; enrolling is the only remedy for the writer's own lockout.

Two transient refusals, and on both of them NOTHING WAS SAVED. Beside the 403 above, a write of this key can answer 503 twice over, and both are retryable:

• "This policy could not be checked against your own account. Please try again." — the self-lockout test could not be evaluated, so the endpoint established neither a refusal nor a pass and declined to guess.
• "This policy change could not be scheduled. Please try again." — the write tightened the policy, but the session revocation that tightening requires could not be scheduled. The write is then deliberately abandoned: the policy is NOT stored. A tightening that committed with no revocation behind it would leave every newly-required user holding the session they already had, with nothing scheduled to end it and nothing saying so — so the endpoint refuses rather than storing half the change. Do not treat this as “probably applied, refresh later”; re-send the same request.

Side effects of flipping this policy on. The sessions of users who become required and hold no factor are revoked, but asynchronously — there is a window between the policy write returning success and the sweep reaching that user's sessions. Two populations are deliberately left alone by this cut, and are instead challenged at their next login rather than swept immediately:

• A user who is already enrolled is untouched — enrollment already satisfies the new requirement, so revoking them would cost a re-login with no purchase. This also means a session minted before its holder enrolled survives the flip; there is no claim on the token itself that distinguishes it.
• A user who becomes required by joining the org, or by being promoted into a role whose baseline requires it, is not swept — neither is a policy write, so there is nothing for the sweep to hang off; they are challenged at their next login instead.

Removing an optional override is NOT in that group — it IS swept. Dropping an exception that leaves the user under a required baseline is a direct tightening write, and it queues a sweep targeted at exactly that one user rather than the whole org. The rule is: a write that tightens a baseline sweeps org-wide; a write that newly requires a factor of exactly one named user sweeps only them; anything ambiguous falls back to the org-wide sweep.

Audit. org_updated carries auth_require_2fa inside its existing policy_changes map: policy_changes.auth_require_2fa = { before: {admin, member}, after: {admin, member}, overrides: {added, removed, changed} } — the same shape as the collaboration policies above.

Access Policy (Geo / IP Restrictions)

Enterprise plan. An org can restrict which countries and/or IP ranges may reach its content at all — every workspace, share, upload, and read, across every credential type (browser session, API key, OAuth, MCP). Read and write it through the access_policy field on GET /current/org/{org_id}/details/ (admin-only, raw) and POST /current/org/{org_id}/update/ — see the field description under Update Organization above.

Value shape, evaluated separately per role:

{"admin":  {"countries": {"mode": "allow", "codes": ["US", "CA"]}, "ips": ["203.0.113.0/24"]},
 "member": {"countries": {"mode": "allow", "codes": ["US"]}, "ips": null},
 "overrides": {"9876543210987654321": {"countries": null, "ips": null}}}

• Each of admin and member (and each entry in overrides, keyed by a current member's user id, at most 100 entries) is {"countries": null | {"mode": "allow"|"deny", "codes": [...]}, "ips": null | [cidr, ...]}.
• countries.codes — 1 to 250 entries, any 2-letter code (including XK), plus the special codes XX (unknown location) and T1 (Tor). The server upper-cases and dedupes them.
• ips — 1 to 100 IPv4/IPv6 addresses or CIDR ranges. A bare address means /32 (IPv4) or /128 (IPv6). Any prefix length is accepted except /0, which is refused — clear the rule instead of writing it as “unrestricted”. The echo is always canonical CIDR (host bits masked).
• {"countries": null, "ips": null} (or the whole field ""/"null") means unrestricted.
• The whole value is replaced on every write — send the complete envelope; overrides are not merged with a prior write.

Who is evaluated: owners and admins read the admin value; members and guests (non-org participants) read member; a per-user entry in overrides wins over either baseline. API keys, OAuth grants and MCP tokens resolve as the user they belong to. A storage download token or preview link resolves as the user who requested it (an older token predating this field reads the member baseline).

Evaluation, for the caller's IP and country:

1. Pass if ips is set and the IP falls inside any listed range — this bypasses the country rule entirely.
2. Otherwise pass if countries is set and the country passes it: in allow mode the country (or XX/T1) must be listed; in deny mode any country not listed passes, and an unknown/Tor caller passes unless XX/T1 is explicitly listed.
3. Otherwise pass if both countries and ips are null (unrestricted).
4. Otherwise blocked. An ips-only rule therefore blocks every IP not on the list, regardless of country. A request with no resolvable IP is always blocked by any restricting rule.

Tightening gate. A write that tightens access_policy — the new value blocks some IP or country the old value allowed — needs the Enterprise plan and is refused with 403 plan_required on a lower plan. Relaxing is always allowed, so a downgraded org can still undo its own restriction.

Self-lockout guard. A write that would take the caller's own current IP/country from pass to block is refused with 403 access_policy_self_lockout (params.ip / params.country). There is no override flag — add your own IP, or an override naming yourself, in the same write. If the result cannot be resolved, the write is refused with 503 access_policy_unavailable (retryable; nothing was saved).

Enforcement. Every org-content request from a blocked caller — any credential type — is refused with 403 geo_restricted (never 401, so a client must never treat this as a sign-out): params: {reason: "geo_restricted", rule: "country"|"ip", org_id, domain} (rule is "ip" for an IP-only rule, or for a missing/unresolvable client IP). The restriction list itself is never echoed to a blocked caller. Suggested copy: “Access to this organization is not permitted from your current location or network.” This includes upload endpoints for an org-governed target — create, chunk, stream, complete, and both upload/{id}/details and web_upload/{id}/details — which refuse a blocked caller with geo_restricted, never a 404; a 404 from a details read still means the session itself is gone, not that it was hidden by this policy. If an upload session's own target cannot itself be read to determine the policy, the call fails 503 access_policy_unavailable (retryable) rather than passing through unchecked. websocket/auth and activity/poll for an org-owned profile (see Activity Polling / WebSocket in the Events reference) return this same structured geo_restricted refusal ahead of any generic invalid-input error, and an MCP-classified request reaching any of these gets 403 mcp_access_denied instead — see AI, Intelligence & MCP Access Policy below. A missing owning org (rare) reports 403 access_policy_org; an unreadable stored policy or membership reports 503 access_policy_unavailable (retryable) — except that an unreadable stored access_policy resolves to blocked for everyone but the owner, so a corrupted policy fails closed rather than open.

Exemptions. Anonymous public access, and a signed-in user reading a share or file link whose access is set to “Anyone with the link” (public means public), are not geo-checked. Anything on that same share that needs actual membership — a write, or any member-only action — is checked. Internal pipeline and platform-agent (Ripley) tokens are also exempt.

Owner break-glass. The org owner always reaches GET org/{org_id}/details/ and POST org/{org_id}/update/, even from a blocked location — otherwise a misconfigured policy could lock an owner out of fixing it. Every other org call the owner makes is geo-checked the same as anyone else; a client can infer “recovery mode” when other org calls return geo_restricted while details keeps succeeding. An event is recorded only when that access actually bypassed a block, and is rate-limited.

Cross-org lists. A row belonging to an org that blocks the caller — by this policy, or by the MCP access policy on an MCP request (see below) — is dropped before paging from orgs/list (including the org's own row), orgs/all, orgs/list/external, workspace and share list/available endpoints, the caller's own share list (GET user/me/list/shares/ — see the Shares reference), upload lists, and events/search without a workspace_id filter. Most of these are dropped before paging so pages and totals stay exact; the one exception is the web_upload list, which is paged in SQL, so a page can come back short of limit while total still counts every row. user/available_profiles is not filtered — it reports booleans about the caller's own relationships, with no org rows to drop.

Known limits. An already-open WebSocket connection is not forcibly closed when a policy changes — it is re-checked the next time its token is minted (on reconnect). A storage download token issued before this feature shipped is checked against the member rule for the remainder of its (short) life. Access through the Fastio MCP is evaluated at the MCP worker's own network egress, which does not necessarily reflect the end user's real location.

AI, Intelligence & MCP Access Policy

Enterprise plan. Alongside access_policy above, an org can independently gate five AI/MCP surfaces and one workspace allowlist, all written through POST /current/org/{org_id}/update/ — see the ai_agent / ai_intelligence / ai_metadata / ai_summaries / mcp_access / ai_workspaces field descriptions under Update Organization above, and the raw/capabilities echo fields under Get Org Details. Unconfigured means allowed for every one of these keys.

• Each of ai_agent / ai_intelligence / ai_metadata / ai_summaries / mcp_access is the same envelope shape as the other policy families above: {"admin":"allowed"|"denied","member":..., "overrides":{}}. ai_summaries has no per-user override controls in the editor (background-only).
• Tightening — allowed → denied, adding a denied override, or narrowing ai_workspaces — needs the Enterprise plan (403 plan_required). Relaxing is always allowed.
• Background vs. interactive. Background processing — indexing, automatic metadata extraction on ingest, and per-file summaries — is paused only when the feature is denied for both the admin and member baselines, or when the workspace is off the ai_workspaces list. A single-baseline denial or a per-user denied override only refuses that caller's interactive use (so for ai_summaries, which has no interactive surface, it has no effect).
• Turning a feature off does not delete anything. Existing index data, summaries and metadata stay stored and readable, and existing Ripley Agent threads stay readable (list/details/messages). Re-allowing catches up files added or changed during that specific pause, per workspace, from that workspace's own pause window — the catch-up is retried automatically until it completes. A workspace that is merely suspended or locked while paused keeps its owed catch-up rather than losing it, and receives it once the workspace is re-enabled and the policy allows it again; only a closed or deleted workspace's owed catch-up is dropped. Metadata is only re-extracted for files whose extraction the pause actually withheld (a copy or move made during the pause is not re-extracted); a file whose preview was already billed is not billed again. A plan that always generates summaries still catches those up even in a workspace with Intelligence off. While a workspace's indexing is paused, or while its summaries are paused, the background reconciler does not re-ingest its paused files — both must be allowed to run in the background before the reconciler acts on that workspace again. A templated extract-all sweep or a queued template extraction stops rather than running — its progress reports stop_reason: "paused_policy" (see Jobs Status (Unified Async Processing) in the AI reference) — and picks back up once the metadata policy allows it again. A sweep that briefly cannot read the org's policy partway through pauses at that point and resumes on its own retry, rather than failing outright; if the policy still can't be confirmed, the sweep stops with stop_reason: "policy_unreadable" — resubmit once the policy is readable again.
• The org is a ceiling. These policies never rewrite a workspace's own intelligence / metadata_extraction switch; they only gate whether turning either on, or using it, succeeds.

Refusals (branch on params.reason, never on error.code or HTTP status alone):

See the AI reference for exactly which endpoints return these (chat create/send/publish/rename, AI share, share auto-title/OG, metadata extraction, and the search endpoints' semantic leg), and Workspaces (ai_policy_state, can_use_ai_agent) for how a workspace's own details surface the effective, policy-aware answer per feature.

Compact Responses (output=)

Every endpoint that returns one or more org objects (details, list, discovery) accepts an optional output query parameter that selects the response shape. A single detail-level token may be combined with modifier tokens; specifying two detail levels (e.g. ?output=terse,standard) returns HTTP 406. When output= is omitted, responses are full and byte-for-byte unchanged.

Use terse for org switchers and billing-entity pickers — it includes the ID, URL domain, display name, and logo so the org-switcher sidebar can render entries without falling back to initials. Use standard for org list views, most member-facing dashboards, and branding-aware surfaces — it adds plan, description, lifecycle flags (including the locked and suspended lifecycle/billing chips, emitted to members only), the caller's permission and status, timestamps, hierarchy pointer, plan-gated capabilities, the visual-identity bundle (accent color, background, homepage), and the subscription state fields (subscriber, subscriber_cancel, subscriber_trial_until, payment_state, payment_failed_at, access_ends_at) that list-view subscription chips render. Note that subscriber reports entitlement, not payment health — it stays true while a payment is failing — so read payment_state when you need to know whether billing is actually current. Use full (or omit the parameter) for the org settings screen, billing portal, auth-domain configuration, and any workflow that reads remaining trial credit, permission blocks, social links, or encryption metadata. Unknown tokens are silently ignored. Add the markdown modifier (e.g. ?output=standard,markdown) to receive the response as GitHub-flavored Markdown (Content-Type: text/markdown; charset=UTF-8) instead of JSON — see the cross-cutting ?output= reference for the full contract.

The capabilities object (member-visible) reports plan-gated features the org currently has access to, as booleans. It includes capabilities.signing — whether the org's plan and feature flags currently grant the e-signature surface (e-signature is enabled on every plan, so this is normally true). Read it to decide whether to surface signing UI rather than inferring availability from a denied request.

On GET /current/org/{org_id}/details/ only, capabilities additionally carries can_create_workspace (the effective answer for the calling user, combining their role, the plan, and the org's workspace-create policy), sso, org_controls, and external_invites_shares / external_invites_portals / external_invites_workspaces (see Collaboration Policies). Those are deliberately absent from org list responses, where the answer is not caller-specific enough to be useful; request the org's details when you need them.

Organization CRUD

Create Organization

Request parameters

A newly created organization must select a paid plan (Starter, Business, or Enterprise) 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. This applies to agent and human accounts alike: agent accounts are ordinary accounts tagged account_type=agent and follow the same paid-plan flow. The legacy free plan is no longer available for new organizations.

New orgs on a monthly plan begin a free trial of up to 30 days, or until the included trial credits are used. Annual plans have no trial — an annual subscription is billed for the full term at signup. A trial also carries a credit allowance (trial_credit_limit), which differs by plan — read each plan's own trial_credit_limit. Reaching it ends the trial early and starts the subscription — so the trial is bounded by usage as well as by time, and a customer who consumes their allowance in three days is billed on day three. The exception is a trial with a cancellation scheduled: it never converts and is never charged; usage is held at the trial's credit allowance instead. Show both limits at checkout. A trial is only available on a user's first organization — if the user owns, or has ever owned, any other organization (including one they later closed), no trial is offered on a later org, no matter how much time has passed. A user is also only ever offered one free trial, ever — once a user has started a free trial on any organization, no later organization is offered another one, no matter how much time has passed. When blocked by either rule, a new org subscribes with immediate payment instead of a trial.

Read the trial length from the plan itself rather than assuming a fixed number of days: each plan reports free_days in its pricing, and free_days: 0 means the plan has no trial and payment is due at checkout.

curl example

curl -X POST "https://api.fast.io/current/org/create/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "domain=acme-corp" \
  -d "name=Acme Corporation" \
  -d "industry=technology"

Response (200 OK) — trial available

{
  "result": true,
  "org": {
    "id": "1234567890123456789",
    "domain": "acme-corp",
    "name": "Acme Corporation",
    "description": null,
    "logo": null,
    "accent_color": null,
    "closed": false,
    "suspended": false
  },
  "has_free_trial": true,
  "requires_payment": true,
  "is_agent": false
}

When the owner already owns, or has ever owned, another organization, no trial is offered — the org still subscribes but bills immediately. This block is permanent:

{
  "result": true,
  "org": { "...": "..." },
  "has_free_trial": false,
  "requires_payment": true,
  "is_agent": false,
  "no_trial_reason": "Free trials are only available on your first organization."
}

A trial is also blocked once the owner has ever started a free trial on any organization — this is also permanent, no matter how much time has passed:

{
  "result": true,
  "org": { "...": "..." },
  "has_free_trial": false,
  "requires_payment": true,
  "is_agent": false,
  "no_trial_reason": "A free trial has already been used on this account."
}

Both blocks are permanent, so trial_available_at is never returned in any case.

requires_payment is always true for new orgs (there is no free plan). Until a paid plan is selected the org is in an upgrade-only state (gated endpoints return 402). This applies to all accounts, including agent accounts (is_agent: true).

Response fields

Error responses

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

Get Org Details

{org_id} accepts a 19-digit numeric ID or the org's domain name.

Access levels

curl example

curl -X GET "https://api.fast.io/current/org/1234567890123456789/details/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "org": {
    "id": "1234567890123456789",
    "domain": "acme-corp",
    "name": "Acme Corporation",
    "description": "Leading provider of innovation",
    "logo": "https://assets.fast.io/org/logo.png",
    "accent_color": {"color": "#0066CC", "opacity": 100},
    "closed": false,
    "locked": false,
    "suspended": false,
    "created": "2024-01-15 10:30:00 UTC",
    "updated": "2024-06-20 14:45:00 UTC"
  }
}

Response fields

Error responses

Get Onboarding Checklist

{org_id} accepts a 19-digit numeric ID or the org's domain name.

Access

curl example

curl -X GET "https://api.fast.io/current/org/1234567890123456789/onboarding/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "onboarding": {
    "eligible": true,
    "visible": true,
    "next": "invite_teammate",
    "items": [
      {"id": "add_files",       "status": "done",    "completed_at": null},
      {"id": "install_desktop", "status": "todo",    "completed_at": null},
      {"id": "connect_cloud",   "status": "started", "completed_at": null},
      {"id": "connect_agent",   "status": "done",    "completed_at": "2026-10-03 14:02:11 UTC"},
      {"id": "invite_teammate", "status": "todo",    "completed_at": null},
      {"id": "create_portal",   "status": "todo",    "completed_at": null},
      {"id": "ask_ripley",      "status": "todo",    "completed_at": null}
    ]
  }
}

Response fields

While visible is true, item statuses can take up to a minute to reflect a change.

Each item, when done: add_files — the org has at least one file; install_desktop — a member has signed in to the Fastio Desktop app; connect_cloud — a cloud import (Dropbox/Google Drive/Box/OneDrive) has completed a sync at least once; connect_agent — a member has connected an AI agent to the org; invite_teammate — someone other than the owner has joined the org; create_portal — the org has created a portal; ask_ripley — Ripley has answered a question in one of the org's workspaces.

Error responses

Get Public Org Details

{org_id} accepts a 19-digit numeric ID or the org's domain name.

curl example

curl -X GET "https://api.fast.io/current/org/1234567890123456789/public/details/"

Response (200 OK)

{
  "result": true,
  "org": {
    "id": "1234567890123456789",
    "domain": "acme-corp",
    "name": "Acme Corporation",
    "description": "Leading provider of innovation",
    "logo": "https://assets.fast.io/org/logo.png",
    "accent_color": {"color": "#0066CC", "opacity": 100}
  }
}

Response fields

Update Organization

Access levels

Request parameters (all optional)

curl example

curl -X POST "https://api.fast.io/current/org/1234567890123456789/update/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "name=Acme Corp Updated" \
  -d "description=Updated description" \
  -d "industry=technology"

Response (200 OK)

{
  "result": true
}

If no actual changes are detected, returns success immediately.

Error responses

Close Organization

Request parameters

curl example

curl -X POST "https://api.fast.io/current/org/1234567890123456789/close/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "confirm=acme-corp"

Response (202 Accepted)

{
  "result": true
}

Error responses

Storage deletion is deferred to the deletion system after a retention period.

Organization Assets

List Available Asset Types

curl example

curl -X GET "https://api.fast.io/current/org/assets/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "names": ["logo", "background"],
  "metadata_scheme": {
    "logo": {
      "width": {"name": "Image Width", "description": "Image width", "required": true, "type": "int", "min": 1},
      "height": {"name": "Image Height", "description": "Image height", "required": true, "type": "int", "min": 1},
      "mime": {"name": "Mimetype", "description": "Image mimetype", "required": true, "type": "string"},
      "megapixels": {"name": "Image Megapixels", "description": "Image megapixels", "required": true, "type": "int", "min": 0, "max": 48},
      "transform": {"name": "transform", "description": "Transform image", "required": false, "type": "image_transformer"}
    }
  },
  "file_types": {"logo": "image", "background": "image"}
}

names lists the asset names the org accepts; file_types maps each to its file kind; metadata_scheme maps each to the metadata properties validated on upload (shown for logo only — background carries the same keys, with width/height capped at 4096 and megapixels at 33).

List Org Assets

curl example

curl -X GET "https://api.fast.io/current/org/1234567890123456789/assets/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "assets": {
    "logo": {
      "metadata": {"width": 512, "height": 512, "megapixels": 0, "mime": "image/png"}
    }
  }
}

Keyed by asset name; each entry carries the stored metadata (image width, height, megapixels, mime). An org with no assets returns "assets": []. Fetch the bytes with Read Org Asset (Raw) below.

Upload Org Asset

Request parameters

curl example

curl -X POST "https://api.fast.io/current/org/1234567890123456789/assets/logo/" \
  -H "Authorization: Bearer {jwt_token}" \
  -F "file=@logo.png"

Error responses

Delete Org Asset

curl example

curl -X DELETE "https://api.fast.io/current/org/1234567890123456789/assets/logo/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true
}

Read Org Asset (Raw)

HEAD requests return headers only.

Organization Members

Add or Invite a Member

The target is specified as a path parameter:

• Use a user ID (19-digit numeric) to add an existing user directly
• Use an email address to send an invitation

If you pass an email address that belongs to an account which has not verified that address, an invitation is sent to it instead of adding the account directly.

Request parameters (adding existing user by ID)

Request parameters (inviting by email)

curl example (add existing user)

curl -X POST "https://api.fast.io/current/org/1234567890123456789/members/9876543210987654321/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "permissions=member"

curl example (invite by email)

curl -X POST "https://api.fast.io/current/org/1234567890123456789/members/jane@example.com/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "permissions=member" \
  -d "message=Welcome to the team!"

Response (200 OK) — direct add

{
  "result": true
}

Response (200 OK) — invitation created

{
  "result": true,
  "invitation": {
    "id": "a53no-nj43t-cwoju-ldoi6-nxql4-hm5q",
    "invitee_email": "jane@example.com",
    "entity_type": "org",
    "state": "pending",
    "created": "2024-01-15 10:30:00 UTC"
  }
}

Abbreviated: the invitation object carries every field of a List Org Invitations entry, plus an org object.

Error responses

Remove a Member

The target user ID (19-digit numeric) is a path parameter.

curl example

curl -X DELETE "https://api.fast.io/current/org/1234567890123456789/members/9876543210987654321/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true
}

List Org Members

Query parameters

curl example

curl -X GET "https://api.fast.io/current/org/1234567890123456789/members/list/?limit=50&offset=0" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "users": [
    {
      "id": "1234567890123456789",
      "account_type": "human",
      "email_address": "owner@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "permissions": "owner",
      "auth": {
        "password": true,
        "social": [
          {"provider": "google", "last_login": "2026-09-15 10:22:31 UTC"}
        ],
        "sso": [],
        "two_factor": {"enabled": true, "method": "totp"}
      },
      "compliance_auditor": false
    },
    {
      "id": "1234567890123456780",
      "account_type": "agent",
      "email_address": "bot@example.com",
      "first_name": "Service",
      "last_name": "Bot",
      "permissions": "admin",
      "auth": {
        "password": false,
        "social": [],
        "sso": [],
        "two_factor": {"enabled": false, "method": null}
      },
      "compliance_auditor": false
    }
  ],
  "pagination": {
    "total": 2,
    "limit": 50,
    "offset": 0,
    "has_more": false
  }
}

Response fields

Leave Organization (Self)

curl example

curl -X DELETE "https://api.fast.io/current/org/1234567890123456789/member/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true
}

Error responses

Get Member Details

curl example

curl -X GET "https://api.fast.io/current/org/1234567890123456789/member/9876543210987654321/details/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "user": {
    "id": "9876543210987654321",
    "account_type": "human",
    "email_address": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Smith",
    "permissions": "admin",
    "notify": "Notify me in app",
    "member_added_at": "2026-08-29 15:48:29 UTC"
  }
}

Response fields

Error responses

Update Member Permissions

Request parameters (all optional)

curl example

curl -X POST "https://api.fast.io/current/org/1234567890123456789/member/9876543210987654321/update/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "permissions=admin"

Response (200 OK)

{
  "result": true
}

Error responses

Transfer Org Ownership

Fixed behaviour:

• The successor is promoted before the current owner is demoted, under a per-org lock — the org is never left without an owner.
• Retry completes a partial transfer. If a previous call stopped midway (both users end up owners), calling again with the same target finishes it and returns 200.
• A concurrent call on the same org returns 409 transfer_in_progress.
• Owned-org lists refresh immediately for both users.
• Transferring a free/unpaid org is refused when the receiver is already at the free-org limit. Paid orgs are unrestricted.
• Billing stays on the org: subscription, Stripe customer and payment method are untouched. If no billing email is set, it follows the new owner.
• SSO: the old owner stays an admin, and admins are exempt from SSO enforcement, so the transfer alone signs no one out. Only a later loss of that admin role can end their sessions if SSO is enforced.
• No email is sent — this is recorded as an event only.

curl example

curl -X POST "https://api.fast.io/current/org/1234567890123456789/member/9876543210987654321/transfer_ownership/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "ownership": {
    "profile_id": "1234567890123456789", "profile_type": "org",
    "previous_owner": "1111111111111111111", "new_owner": "9876543210987654321",
    "transferred_at": "2026-09-23 16:37:29 UTC"
  }
}

Error responses (error.params.reason)

Event: ownership_transferred (audit log; profile_type, from_user, to_user). The two existing membership_updated events (promotion and demotion) still fire.

Bulk Access Transfer (Org)

Move a departing or off-boarding member's entire access footprint in one org to another member — every workspace and share membership, plus the ownerships on them — in one guided flow: preview, execute, poll status.

Scope: org O only — A's org row, A's rows on O's workspaces, and A's rows on shares inside O's workspaces. Personal shares and A's memberships in other orgs are untouched.

Rules:

• For each item, B ends at max(B_current, A_role) — B is never downgraded.
• Workspace/share ownerships A holds move to B; A is demoted to admin on those items.
• Refused when A is the org owner (use Transfer Org Ownership above first), when B is not already an org member, when B is A, or when B is unavailable.
• Who: org admin+ with an admin-scope credential. An admin may not target an A whose role is admin or above — only the owner can.
• A's pending invites are counted, not changed.
• Optional offboard: removes A from the org once every item is done or skipped. It can be blocked by a retention or compliance restriction on A in this org (one in another org does not block it) — the transfer itself still completes either way.

Preview (dry run)

curl example

curl -X POST "https://api.fast.io/current/org/1234567890123456789/member/9876543210987654321/transfer_access/preview/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "to_user_id=1111111111111111111"

Response (200 OK)

{
  "result": true,
  "preview": {
    "from_user": "9876543210987654321", "to_user": "1111111111111111111",
    "plan_hash": "sha256:9f2c…",
    "complete": true,
    "org": {"from_role": "member", "to_role_before": "guest", "to_role_after": "member", "action": "raise"},
    "counts": {"workspaces": 12, "shares": 40, "ownerships": 3, "raise": 30, "add": 20, "skipped_b_higher": 2, "invites_sent_by_from": 4},
    "items": [
      {"type": "workspace", "id": "4123456789012345678", "name": "Legal", "from_role": "owner",
       "to_role_before": null, "to_role_after": "owner", "action": "transfer_ownership"}
    ],
    "items_truncated": false,
    "blocking": [],
    "warnings": ["billable_users_may_increase"],
    "offboard_allowed": true, "offboard_blocked_reason": null
  }
}

Response fields

Errors: 403 insufficient_permission (caller is not admin+, or an admin targeting an admin — this refuses the preview outright); 406 successor_not_org_member (malformed to_user_id); 406 from_user_not_member (malformed {user_id} path segment); 406 field validation. Every other refusal (from_user_not_member, from_user_is_org_owner, successor_is_source, successor_not_org_member, successor_unavailable, nothing_to_transfer) appears in blocking with HTTP 200 instead of failing the call.

Execute

The server recomputes the plan and compares hashes — a mismatch means something changed since the preview.

curl example

curl -X POST "https://api.fast.io/current/org/1234567890123456789/member/9876543210987654321/transfer_access/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "to_user_id=1111111111111111111" -d "plan_hash=sha256:9f2c…" -d "offboard=true"

Response: HTTP 202

{"result": true, "transfer": {"id": "mt7q…", "status": "queued", "created_at": "2026-09-23 16:40:00 UTC"}}

Errors (error.params.reason), checked in this order: 403 insufficient_permission; the first applicable blocking reason (406); 409 plan_incomplete (preview could not enumerate everything); 409 plan_changed (re-preview); 409 transfer_in_progress (params.transfer_id names the active transfer — show it); 503 (store/queue unavailable, retry); 429 throttled.

Events: org_member_transfer_started (plan counts). Per item, the existing added-member events / membership_updated, plus ownership_transferred, each carrying transfer_id. At the end, org_member_transfer_completed (report counts, complete, offboard_status).

Status + report

curl example

curl -X GET "https://api.fast.io/current/org/1234567890123456789/transfers/mt7q…/?limit=100&offset=0" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "transfer": {
    "id": "mt7q…", "status": "running", "from_user": "9876543210987654321", "to_user": "1111111111111111111",
    "calling_user": "1234567890123456780",
    "offboard": true, "offboard_status": "not_requested", "offboard_blocked_reason": null, "reason": null,
    "counts": {"total": 55, "done": 30, "skipped": 2, "failed": 0},
    "items": [{"type": "share", "id": "5123…", "action": "add", "outcome": "done", "reason": null}],
    "created_at": "… UTC", "updated_at": "… UTC", "completed_at": null
  },
  "pagination": {"total": 55, "limit": 100, "offset": 0, "has_more": false}
}

Response fields

Kept for 30 days; after that, 404 transfer_not_found — the audit log remains the record.

Join Organization

Join methods

1. Via invitation: Append the invitation key to the URL path: .../join/{invitation_key}/ optionally followed by accept or decline. Default is accept.
2. Via authorized domain: The org must have perm_authorized_domains set, the user's email address must be verified (agent accounts included), and the user's email domain must match. A new user is added as a Member; a current (unexpired) member keeps their role; an expired membership is restored as Member. Only notify_options is read from input; permissions is ignored.

curl example (invitation)

curl -X POST "https://api.fast.io/current/org/1234567890123456789/members/join/abc123def456/accept/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true
}

Error responses

List Org Invitations

curl example

curl -X GET "https://api.fast.io/current/org/1234567890123456789/members/invitations/list/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "invitations": [
    {
      "id": "a53no-nj43t-cwoju-ldoi6-nxql4-hm5q",
      "inviter": "John Doe",
      "inviter_actor": {
        "user_id": "1234567890123456789",
        "kind": "human",
        "agent_name": null,
        "name_source": null,
        "credential_type": "session",
        "verified": false
      },
      "invitee_email": "jane@example.com",
      "invitee_uid": "5566778899001122334",
      "accepted_uid": null,
      "entity_type": "org",
      "state": "pending",
      "consumed": false,
      "created": "2024-01-15 10:30:00 UTC",
      "updated": "2024-01-15 10:30:00 UTC",
      "expires": "2024-01-18 10:30:00 UTC"
    }
  ]
}

Response fields

Error responses

Update an Invitation

{invitation_id} can be the invitation ID or the invitee email address. The invitation must belong to this org; otherwise the request fails with 406 exactly as an unknown invitation does ("Invalid invitation id or Invitation not found." for an ID). Parameters are form fields; a JSON request body is refused with a 406 error.

Request parameters (all optional)

curl example

curl -X POST "https://api.fast.io/current/org/1234567890123456789/members/invitation/a53no-nj43t-cwoju-ldoi6-nxql4-hm5q/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "permissions=admin"

Response (200 OK)

{
  "result": true
}

Error responses

Delete an Invitation

{invitation_id} can be the invitation ID or the invitee email address. The invitation must belong to this org; otherwise the request fails with 406 exactly as an unknown invitation does ("Invalid invitation id or Invitation not found." for an ID).

curl example

curl -X DELETE "https://api.fast.io/current/org/1234567890123456789/members/invitation/a53no-nj43t-cwoju-ldoi6-nxql4-hm5q/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true
}

Error responses

Compliance & Audit

Enterprise plan. These endpoints give an org owner or admin, or a member holding the compliance_auditor flag (“auditor”), read access to the org’s credential inventory, per-user and sharing-exposure reports, and a streaming audit-log export — plus the two write actions (credential revoke, force sign-out) that stay admin-only. See org.capabilities.can_view_compliance / can_manage_legal_holds above to decide whether to show this UI without guessing from role alone.

The auditor flag adds no write power. It is a boolean on a normal org membership (member.compliance_auditor, granted only by the owner — see Grant/Revoke the Auditor Flag below). An auditor keeps their existing role and workspaces; the flag only opens the read-only surfaces on this page plus legal-hold management. It is inert while the org lacks the Enterprise plan.

Credential rule for these reads. A signed-in browser session always passes. An API key needs an admin-scope (rwa) grant on the org.

Common refusals across this whole section — branch on error.params.reason, never on error.code or on HTTP status alone:

Credential Reach Classification

Every API key and OAuth grant is classified relative to the org being viewed:

Revoke eligibility (who may act, and on what):

• org_only credentials are always revocable by an eligible actor.
• user_wide and mixed credentials are revocable only when the credential owner's email is on one of this org's verified SSO domains — otherwise 409 credential_spans_other_orgs (remedy copy: “Remove this member from the organization, or tighten the credential policy”).
• An eligible actor is an org admin+ whose role is strictly above the target's. The owner can never be a target. Auditors never revoke, regardless of the flag.
• Revoking an OAuth session stops refreshes immediately, but an already-issued access token keeps working for up to 1 hour. Say so in any revoke/sign-out confirmation copy.

List Org Credentials

Query parameters

curl example

curl -X GET "https://api.fast.io/current/org/1234567890123456789/credentials/?type=oauth&reach=mixed" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "credentials": [
    {
      "type": "api_key", "id": "k8x2mq4rt7", "user_id": "9876543210987654321",
      "label": "CI deploy", "agent_name": null, "client_id": null, "device_name": null,
      "token_chars": "x9Qz", "scopes": ["workspace:4123456789012345678:rw"], "other_scopes": 0,
      "access_mode": "rw", "admin": false, "legacy": false, "mcp": false,
      "reach": "org_only", "created": "2026-09-01 10:00:00 UTC", "expires": null,
      "last_used": "2026-09-23 07:10:00 UTC", "last_ip": "203.0.113.7", "last_country": "US",
      "revocable": true, "revocable_reason": null
    },
    {
      "type": "oauth", "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4", "user_id": "9876543210987654321",
      "label": null, "agent_name": "Claude", "client_id": "cimd:https://claude.ai/…",
      "device_name": "MacBook", "token_chars": null, "scopes": ["workspace:4123456789012345679:rw"], "other_scopes": 2,
      "access_mode": "rw", "admin": false, "legacy": false, "mcp": true, "reach": "mixed",
      "created": "2026-09-10 12:00:00 UTC", "expires": "2026-10-10 12:00:00 UTC",
      "last_used": "2026-09-22 18:00:00 UTC", "last_ip": "198.51.100.4", "last_country": "DE",
      "revocable": false, "revocable_reason": "credential_spans_other_orgs"
    }
  ],
  "pagination": {"has_more": true, "next_cursor": "…", "page_size": 50, "credentials_capped": false}
}

Response fields

Token secrets and hashes are never returned. Expired API keys and revoked/expired OAuth sessions are not listed.

Error responses

Revoke a Credential

{user_id} = the credential's owner (a live org member); {type} = api_key | oauth. No body.

curl example

curl -X DELETE "https://api.fast.io/current/org/1234567890123456789/member/9876543210987654321/credentials/api_key/k8x2mq4rt7/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{"result": true, "revoked": {"type": "api_key", "id": "k8x2mq4rt7", "user_id": "9876543210987654321"}}

Error responses

Events: org_credential_revoked (audit log). The existing api_key_deleted also fires on the member's own trail, with the calling user as the admin.

Force Sign-Out a Member

curl example

curl -X POST "https://api.fast.io/current/org/1234567890123456789/member/9876543210987654321/sign-out/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true, "sessions_invalidated": true,
  "revoked": [{"type": "api_key", "id": "k8x2mq4rt7"}, {"type": "oauth", "id": "a1b2…"}],
  "skipped": [{"type": "oauth", "id": "c3d4…", "reason": "credential_spans_other_orgs"}]
}

Error responses

A 500 does not by itself tell you whether sessions were invalidated: it can occur before invalidation (retry) or after invalidation when one or more credential revokes then failed. Retrying is always safe (idempotent): the session bump repeats harmlessly and already-revoked credentials are unaffected.

Event: org_member_signed_out.

Confirmation copy must say: this signs the person out of every Fastio org and personal use, not only this one, and OAuth apps may keep working for up to 1 hour.

Get Member Compliance Report

Target must be a live org member (404 member_not_found). Each section is independently best-effort — see partial/truncated.

curl example

curl -X GET "https://api.fast.io/current/org/1234567890123456789/member/9876543210987654321/report/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "report": {
    "user": {
      "id": "9876543210987654321", "email_address": "a@example.com", "first_name": "A", "last_name": "B",
      "created": "2025-01-15 10:30:00 UTC", "two_factor": true, "password_set": true,
      "sso": {"enforced": true, "exempt": false, "org_domain": "example.com"},
      "managed_account": true, "locked": false, "suspended": false
    },
    "org_membership": {"permission": "admin", "compliance_auditor": false, "member_added_at": "2026-01-02 09:00:00 UTC"},
    "workspaces": [{"id": "4123456789012345678", "name": "Legal", "permission": "member", "member_added_at": "2026-01-03 09:00:00 UTC"}],
    "credentials": {"api_keys": 3, "oauth_sessions": 2},
    "logins": {
      "last_login": "2026-09-23 07:10:00 UTC", "window_days": 90, "count": 41,
      "recent": [{"created": "2026-09-23 07:10:00 UTC", "method": "sso", "ip": "203.0.113.7", "country": "US", "user_agent": "Mozilla/5.0 ..."}]
    },
    "last_activity": "2026-09-23 07:12:00 UTC"
  },
  "partial": [], "truncated": []
}

Response fields

Error responses

Get Sharing Exposure Report

Query parameters

counts=false (list mode only). Returns workspace rows only (the same workspace block — id, name) with no summary block and no per-workspace exposure walk; only_exposed is ignored. Same auth, and the same limit/cursor paging, as the default. This is meant for building an admin-wide workspace picker — for example the ai_workspaces allowlist editor above — cheaply at org scale (a large org can have on the order of a thousand workspaces).

{"result": true,
 "workspaces": [{"workspace": {"id": "4123456789012345678", "name": "Legal"}}],
 "pagination": {"has_more": true, "next_cursor": "…", "page_size": 20}}

Response (200 OK) — list mode, default counts=true

{
  "result": true,
  "workspaces": [{
    "workspace": {"id": "4123456789012345678", "name": "Legal"},
    "summary": {"public_shares": 2, "public_file_links": 5, "external_members": 7, "pending_external_invites": 1}
  }],
  "pagination": {"has_more": true, "next_cursor": "…", "page_size": 20}
}

List mode returns counts only (no per-share/link/member rows). It also enforces an internal per-page read budget, so a page can come back shorter than limit — or even with a single workspace — while pagination.has_more is still true; keep paging on has_more rather than assuming a short page means the org is exhausted.

Detail mode (?workspace_id=…) adds shares[], file_links[], external_members[], pending_external_invites[] to the one workspace row:

{
  "workspace": {"id": "4123456789012345678", "name": "Legal"},
  "summary": {"public_shares": 1, "public_file_links": 1, "external_members": 1, "pending_external_invites": 2},
  "shares": [{
    "id": "5123456789012345678", "name": "Q3 data room", "category": "portal", "share_type": "send",
    "access_options": "Anyone with the link", "password_set": true, "expires": null,
    "creator": {"id": "9876543210987654321", "email_address": "creator@example.com"},
    "owner": {"id": "9876543210987654322", "email_address": "owner@example.com"},
    "member_count": 12,
    "external_members": [{"user_id": "9876543210987654323", "email_address": "vendor@example.com", "permission": "guest", "added_at": "2026-08-01 09:00:00 UTC"}],
    "pending_external_invites": [{"email_address": "invitee@example.com", "permission": "guest", "created": "2026-09-01 09:00:00 UTC"}]
  }],
  "file_links": [{
    "id": "6123456789012345678", "access_option": "anyone_with_link", "password_set": false,
    "expires": null, "creator": {"id": "9876543210987654321", "email_address": "creator@example.com"},
    "node_id": "2ltsuq4mjacuv7pgc5ydlxnsjwee4"
  }],
  "external_members": [{"user_id": "9876543210987654323", "email_address": "vendor@example.com", "permission": "member", "added_at": "2026-08-01 09:00:00 UTC"}],
  "pending_external_invites": [{"email_address": "invitee2@example.com", "permission": "member", "created": "2026-09-02 09:00:00 UTC"}]
}

Error responses

Export the Audit Log

Replaces any client-side paging loop over events/search. Not a 5,000-row export: it streams until the range is exhausted or a per-request row cap is hit (then hands back a cursor to continue).

Query parameters

curl example

curl -X GET "https://api.fast.io/current/org/1234567890123456789/audit/export/?from=2026-08-01&to=2026-08-31&format=csv" \
  -H "Authorization: Bearer {jwt_token}" -o audit.csv

Response: a streamed file, not a JSON envelope. Content-Type: text/csv; charset=UTF-8 or application/x-ndjson. Content-Disposition: attachment; filename="audit-<org>-<from>-<to>.<ext>".

Columns / JSONL keys: event_id, created, event, category, sub_category, calling_user_id, calling_user_email, event_user_id, workspace_id, share_id, object_id, ip, country, severity, metadata (metadata is a JSON string; every id is a string). CSV cells starting with = + - @ are prefixed with ' (formula-injection guard). Row visibility follows the caller's own audit-log rules (hold events owner/auditor only).

Stream end markers — the last line is always one of:

• Complete: CSV # complete; rows=12345 / JSONL {"_complete":true,"rows":12345}.
• Truncated (per-request row cap): CSV # truncated; next_cursor=… / JSONL {"_truncated":true,"next_cursor":"…"}. Re-request with cursor= to continue — a continuation response's CSV has no header row (concatenate parts as-is); JSONL has no header either way.
• Neither marker — the stream was cut (network/timeout); the file is incomplete. Retry from the last next_cursor you have, or from scratch.

Error responses (before the stream starts, normal JSON envelope)

Event: org_audit_exported.

Grant/Revoke the Auditor Flag

Request parameters

curl example

curl -X POST "https://api.fast.io/current/org/1234567890123456789/member/9876543210987654321/compliance-auditor/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "enabled=true"

Response (200 OK)

{"result": true, "user_id": "9876543210987654321", "compliance_auditor": true}

Enabling needs the Enterprise plan (on a current subscription); disabling always works, on any plan and on a lapsed subscription. Setting the current value, or targeting the owner (who already has every auditor power), is an idempotent 200 with no change. Removing the member from the org clears the flag; a plan lapse leaves it stored but inert; reviving an expired membership also clears it, so the flag never returns without the owner re-granting it.

Error responses (checked in this order)

Events: org_compliance_auditor_changed, plus the existing membership_updated.

Legal Holds (Enterprise plan)

A legal hold preserves a workspace's or a member's content against destruction while litigation, an investigation, or another compliance need is active. Holds are managed by the org owner (any plan) or by an auditor (Enterprise) — org admins cannot manage holds, even though they can manage everything else (403 legal_hold_access_required). Placing a hold needs the Enterprise plan; listing, viewing and releasing an existing hold work on any plan, so a lapsed org can still lift its own holds. All four endpoints also need an admin-capable credential — a login session, or an API key/OAuth token with rwa scope on the org; any other credential gets 403 scope_admin_required.

What a hold does. A hold preserves, not freezes — members keep working normally. Deleting, moving, emptying trash, and closing a workspace or share all keep working exactly as before. What changes is permanent destruction: purge of trashed content, version pruning, automatic share expiry, and profile/account deletion are all held back for anything the hold covers, and quietly resume once the hold is released. A user never sees an error because of a hold — purging held content still reports success; the content is retained instead of destroyed. Held content, including deleted-but-retained bytes, keeps counting toward the org's billed storage.

Scope. A workspace hold covers the workspace itself, every one of its shares, and its e-sign envelopes — including ones created after the hold is placed. A person hold covers content the member authored across the org's workspaces, plus their own account. Person-hold coverage has two limits: files a cloud-sync import brought in with no resolvable owner, and copies of the person's files made by someone else, are attributed to the importer/copier and are not covered by a person hold — a workspace hold covers both of those regardless of who authored them.

Confidentiality. The legal_hold_created / legal_hold_released audit events never carry the hold's reason, and — unlike the rest of the audit log — they are visible only to the org owner or an entitled auditor, even in export and summarize, and only when the request itself carries a login session or an API key/OAuth token with an org admin-capable (rwa) scope on that same org — a user:*:rw-scoped key, or a key scoped to a different org, never sees them, whoever owns it. A search filtered to one of these two event types by a caller who does not qualify comes back as an empty page rather than an error — event names are matched exactly, so filtering on a case, whitespace, or accent variant of a hold-event name, or on any event value that is not itself a plain lowercase name, also returns an empty page rather than a broader match. They are never sent to a configured SIEM stream.

Hold object

{
  "id": "sabdqahjioknnh36puhwmjy5nluifp",
  "org_id": "1234567890123456789",
  "status": "active",
  "target_type": "workspace",
  "target": {"id": "4123456789012345678", "name": "Legal", "closed": false},
  "name": "Matter 2026-114",
  "reason": "Litigation hold per counsel",
  "created_by": {"id": "9876543210987654321", "email_address": "owner@example.com"},
  "created": "2026-09-23 16:37:29 UTC",
  "released_by": null,
  "released": null
}

For a person hold, target is {"id": "…", "email_address": "…", "first_name": "…", "last_name": "…"}. A target / created_by / released_by profile that no longer loads keeps its id with the display fields null (a workspace's closed reads true in that case) — a hold outlives the workspace it covers, since it can be placed on one that is already closed.

Place a Hold

Request parameters

A workspace target may already be closed, as long as it has not been purged. A person target must be a current org member. Several holds may target the same workspace or person at once.

curl example

curl -X POST "https://api.fast.io/current/org/1234567890123456789/legal-holds/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "target_type=workspace" -d "target_id=4123456789012345678" \
  -d "name=Matter 2026-114" -d "reason=Litigation hold per counsel"

Response (200 OK)

result: true and legal_hold — the new hold, in the hold object shape shown above.

Error responses

Event: legal_hold_created (never carries reason; visible only to the owner/auditors).

List Holds

Query parameters

Response (200 OK)

{
  "result": true,
  "legal_holds": [
    {
      "id": "sabdqahjioknnh36puhwmjy5nluifp",
      "org_id": "1234567890123456789",
      "status": "active",
      "target_type": "workspace",
      "target": {"id": "4123456789012345678", "name": "Legal", "closed": false},
      "name": "Matter 2026-114",
      "reason": "Litigation hold per counsel",
      "created_by": {"id": "9876543210987654321", "email_address": "owner@example.com"},
      "created": "2026-09-23 16:37:29 UTC",
      "released_by": null,
      "released": null
    }
  ],
  "pagination": {"total": 3, "limit": 100, "offset": 0, "has_more": false}
}

Errors: legal_hold_access_required (403).

Hold Detail + Impact

Adds impact to the hold object. For a workspace hold: {"bytes": …, "files": …, "folders": …, "shares": …}, totalled across the workspace, its shares (a folder share that shares the workspace's own storage is not double-counted), and its e-sign envelopes — trashed and pending-deletion content included, the same figures billing uses. impact_available is true only when every part of the count succeeded; otherwise impact is null (retry later). A person hold always reports "impact": null, "impact_available": false. There is no separate preview endpoint — this is also where to check a hold's footprint right after placing it.

Response (200 OK)

{
  "result": true,
  "legal_hold": {
    "id": "sabdqahjioknnh36puhwmjy5nluifp",
    "org_id": "1234567890123456789",
    "status": "active",
    "target_type": "workspace",
    "target": {"id": "4123456789012345678", "name": "Legal", "closed": false},
    "name": "Matter 2026-114",
    "reason": "Litigation hold per counsel",
    "created_by": {"id": "9876543210987654321", "email_address": "owner@example.com"},
    "created": "2026-09-23 16:37:29 UTC",
    "released_by": null,
    "released": null,
    "impact": {"bytes": 123456789, "files": 1200, "folders": 80, "shares": 4},
    "impact_available": true
  }
}

Errors: legal_hold_not_found (404 — an unknown id and another org's id answer identically); legal_hold_access_required (403).

Release a Hold

curl example

curl -X POST "https://api.fast.io/current/org/1234567890123456789/legal-holds/sabdqahjioknnh36puhwmjy5nluifp/release/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "legal_hold": {
    "id": "sabdqahjioknnh36puhwmjy5nluifp",
    "org_id": "1234567890123456789",
    "status": "released",
    "target_type": "workspace",
    "target": {"id": "4123456789012345678", "name": "Legal", "closed": false},
    "name": "Matter 2026-114",
    "reason": "Litigation hold per counsel",
    "created_by": {"id": "9876543210987654321", "email_address": "owner@example.com"},
    "created": "2026-09-23 16:37:29 UTC",
    "released_by": {"id": "9876543210987654321", "email_address": "owner@example.com"},
    "released": "2026-09-24 10:02:00 UTC"
  }
}

Releasing an already-released hold returns the same 200 idempotently and emits nothing further.

Errors: legal_hold_not_found (404); legal_hold_access_required (403).

Event: legal_hold_released (only on the release that actually changes the hold's status).

The hold is lifted lazily, not instantly — deferred destruction of the content it covered resumes automatically on its own schedule. There is nothing else to call; do not treat a hold that still shows released items pending cleanup as a bug.

Refusals Elsewhere Caused by a Hold

• POST /current/org/{org_id}/close/ while any hold on the org is active refuses 409 legal_hold_active — "This organization cannot be closed while a legal hold is active. Release all legal holds first." Release every hold, then retry. See Close Organization above.
• POST /current/user/close/ for an account covered by a person hold in any org refuses 409 account_close_blocked — "This account cannot be closed right now. Please contact your organization." This wording is deliberately generic: it never confirms or names a legal hold, since the account holder may not be entitled to know one exists. See Auth & Users.
• Deleting, trashing, moving a workspace or share, and removing a member, are never refused by a hold — only permanent destruction is held back.

Read org.capabilities.can_manage_legal_holds (see Get Org Details above) to decide whether to show this UI at all, rather than guessing from role alone.

SIEM Audit Stream (Enterprise plan)

One generic HMAC-signed HTTPS webhook per org, streaming the org's audit-log event set (the same events visible through Compliance & Audit above) to your own SIEM (Splunk, Datadog, or any HTTPS receiver). At-least-once delivery, batched, approximately ordered. Legal-hold events are never streamed — they stay owner/auditor-only in the audit log, the same restriction as everywhere else.

Semantics:

• Delivery is at-least-once, in batches of up to 500 events (fewer when the batch would exceed about 900 KB of JSON; a single larger event is sent on its own). Ordering is approximate (by event time); a late-recorded event can arrive in a later batch. Dedupe on event_id on your side.
• Each delivery attempt has its own delivery_id; a retry may regroup events differently.
• Latency is at least a couple of minutes. An event recorded well after its own timestamp may not make it into the stream at all — it still appears in the audit log and in Audit Export above.
• The stream starts at “now” when created — there is no backfill. Use Audit Export for history.
• A stream that fails continuously for a sustained period auto-pauses (state: "paused_failing") and raises an audit_stream_paused security alert (see Security Alerts below); re-enable it to retry.
• If the org itself is later deleted, its stream configuration is removed automatically — there is nothing to clean up on your side.
• If the signing secret is briefly unreadable on our side, delivery pauses and retries automatically; a secret rotation issued during that window takes effect on the next retry, not immediately.
• Splunk/Datadog presets are a future release; this is a generic webhook today.

Who:

• GET: admin+, or an entitled compliance auditor.
• Writes: admin+ with an admin-scope credential.
• Enterprise is required for every call except GET, disabling (enabled=false), and DELETE, which work on any plan. On a non-Enterprise org, GET returns the stored config with state: "paused_plan" instead of refusing. Creating, enabling, rotating the secret, and testing still need Enterprise.

Get Audit Stream

curl example

curl -X GET "https://api.fast.io/current/org/1234567890123456789/audit/stream/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "stream": {
    "enabled": true, "state": "active",
    "url": "https://siem.example.com/fastio", "secret_masked": "****a1b2",
    "created": "… UTC", "updated": "… UTC", "updated_by": "…",
    "delivered_through": "2026-09-23 16:30:00 UTC", "events_delivered": 120394,
    "last_attempt_at": "… UTC", "last_success_at": "… UTC", "last_status_code": 200,
    "last_error_class": null, "consecutive_failures": 0, "gap_from": null, "gap_to": null
  }
}

Response fields

Errors: 404 stream_not_configured (show the “Set up” state); 403 compliance_access_required.

Create or Update Audit Stream

Request parameters

Create: returns the config plus "secret": "whsec_…" — shown once. Store it immediately; it cannot be retrieved again (only rotated). The stream starts delivering from “now”.

Update: secret is absent from the response. Re-enabling a paused or disabled stream resets the failure count and retries immediately.

curl example

curl -X POST "https://api.fast.io/current/org/1234567890123456789/audit/stream/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "url=https://siem.example.com/fastio" -d "enabled=true"

Error responses

Event: org_audit_stream_updated.

Delete Audit Stream

Response (200 OK)

{"result": true}

Errors: 404 stream_not_configured. Event: org_audit_stream_deleted.

Rotate Signing Secret

Response (200 OK)

{"result": true, "secret": "whsec_…"}

Errors: same as Create or Update Audit Stream above. Event: org_audit_stream_updated with change: "secret_rotated".

Send a Test Delivery

Response (200 OK)

{"result": true, "delivered": false, "status_code": 502, "error_class": "http_5xx", "latency_ms": 840}

— a failed delivery is a result, not an error; check delivered. Throttled to a small number of calls per org — 429 with Retry-After when you call it too soon after the last one.

The test delivery uses the same wire format and signature as a real one (below) and carries one synthetic record with event: "audit_stream_test". It is never stored as an event and never moves the stream's delivery position — have your receiver accept it (2xx) and otherwise ignore it.

Wire Format

POST <your url>
Content-Type: application/json

{"stream": "fastio.audit", "org_id": "…", "delivery_id": "…", "sent_at": "… UTC", "events": [ … ]}

Headers: X-Fastio-Delivery-Id; X-Fastio-Timestamp (unix seconds); X-Fastio-Signature: v1=<hex HMAC-SHA256(secret, "<timestamp>.<raw request body>")>.

Verifying the signature: recompute HMAC-SHA256(your_secret, timestamp + "." + raw_body) over the raw (unparsed) request body, hex-encode it, and compare to the value after v1= using a constant-time comparison. Reject the request if the timestamp is more than 5 minutes old (also guards against replay). Do not trust an unsigned or mis-signed delivery.

Event record fields: event_id, event, category, sub_category, severity, created, org_id, workspace_id, share_id, actor_user_id, subject_user_id, object_id, description, metadata, ip, country (every id is a string). An org_security_alert record carries no event user and no actor, so its top-level subject_user_id and actor_user_id are both null — read the alert's subject from metadata.subject_user_id instead.

Your receiver should: verify the signature over the raw body; reject stale timestamps; dedupe on event_id (delivery is at-least-once and a retry can regroup events); treat ordering as approximate; respond with any 2xx to acknowledge (redirects are not followed — respond directly).

Security Alerts (Enterprise plan)

Proactive notification — an audit-log event plus an email — when one of a handful of security-shaped patterns happens in the org: a new-country sign-in, a geo/IP policy block, an unusually large burst of deletions or downloads by one person, a new credential that can reach the org, or the audit stream above pausing itself. Enterprise plan only.

Setting: the security_alerts field on Update Organization above (admin+). Unset means every alert is on and compliance auditors are included as recipients — the default for an Enterprise org that has never configured this. enabled: [] turns every alert off; clear with "" to return to the default.

Alert types:

Repeated alerts of the same kind are throttled so a single ongoing pattern does not flood you with duplicates, and each alert type is capped per org per day — once the cap is hit, further alerts of that kind are suppressed for the rest of the day and the next alert's notification says so.

Output:

• An org_security_alert audit-log event (severity high) — visible the same way as the rest of Compliance & Audit, through events/search. It carries no event user — the subject of the alert (if any) rides only in subject_user_id, so a member is never shown an alert about themselves in their own personal activity. It also carries no calling_user and no actor: the alert is raised by the platform, not by the request that tripped it — render its actor as “System”.
• An email to the org owner and admins, plus compliance auditors when include_auditors is on (default). Each recipient gets at most one email per alert, capped per day so a burst cannot flood an inbox.

In-app: GET /current/events/search/?org_id=…&visibility=external_audit_log&event=org_security_alert (add &acknowledged=false for an unread badge). Acknowledge with POST /current/event/{event_id}/ack/. Acknowledgement is per viewer — one admin acknowledging an alert does not clear it for other admins or auditors. A compliance auditor who is not an admin may open event/{event_id}/details/ and acknowledge an org_security_alert row the same as an admin can.

Errors: 406 params[] {name: "security_alerts"} for an unknown alert name in the setting write; 403 plan_required when the write would turn an alert on, or turn auditors on, on a non-Enterprise org (turning alerts off, removing auditors, or clearing is allowed on any plan).

Event: org_security_alert per alert. org_updated's policy_changes also gains security_alerts ({before, after}) when the setting itself changes.

Organization Discovery

List Internal Orgs

Non-admin/non-owner members only see orgs with active subscriptions; admins and owners always see their orgs.

curl example

curl -X GET "https://api.fast.io/current/orgs/list/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "orgs": [
    {
      "id": "1234567890123456789",
      "domain": "acme-corp",
      "name": "Acme Corporation",
      "description": "Leading provider of innovation",
      "logo": "https://assets.fast.io/org/logo.png",
      "accent_color": {"color": "#0066CC", "opacity": 100},
      "closed": false,
      "suspended": false,
      "subscriber": true,
      "user_status": "joined",
      "member": true
    }
  ],
  "pagination": {"total": 1, "limit": 100, "offset": 0, "has_more": false}
}

Response fields

Subscription filtering

List External Orgs

curl example

curl -X GET "https://api.fast.io/current/orgs/list/external/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "orgs": [
    {
      "id": "1234567890123456780",
      "domain": "partner-corp",
      "name": "Partner Corporation",
      "description": "External partner organization",
      "logo": null,
      "accent_color": {"color": "#FF6600", "opacity": 100},
      "closed": false,
      "suspended": false,
      "subscriber": true,
      "user_status": "available",
      "member": false
    }
  ],
  "pagination": {"total": 1, "limit": 100, "offset": 0, "has_more": false}
}

Response fields

List All Orgs

curl example

curl -X GET "https://api.fast.io/current/orgs/all/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "orgs": [
    {
      "id": "1234567890123456789",
      "domain": "acme-corp",
      "name": "Acme Corporation",
      "description": "Leading provider of innovation",
      "logo": "https://assets.fast.io/org/logo.png",
      "accent_color": {"color": "#0066CC", "opacity": 100},
      "closed": false,
      "suspended": false,
      "user_status": "joined"
    }
  ],
  "pagination": {"total": 1, "limit": 100, "offset": 0, "has_more": false}
}

Response fields

List Available Orgs

curl example

curl -X GET "https://api.fast.io/current/orgs/available/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "orgs": [
    {
      "id": "1234567890123456782",
      "domain": "new-company",
      "name": "New Company",
      "description": "An org you can join",
      "logo": null,
      "accent_color": {"color": "#FF6600", "opacity": 100},
      "closed": false,
      "suspended": false
    }
  ]
}

Check Domain Availability

Path parameters

curl example

curl -X GET "https://api.fast.io/current/orgs/check/domain/acme-corp" \
  -H "Authorization: Bearer {jwt_token}"

Response (202 Accepted) — domain available

{
  "result": true
}

Error responses

List Industries

curl example

curl -X GET "https://api.fast.io/current/orgs/industries/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "unspecified": {
    "title": "Unspecified",
    "description": "No specific industry or sector."
  },
  "technology": {
    "title": "Technology",
    "description": "Companies that develop or provide software, hardware, and IT services."
  },
  "healthcare": {
    "title": "Healthcare",
    "description": "Organizations providing medical services, healthcare management, and patient care."
  },
  "financial": {
    "title": "Financial Services",
    "description": "Businesses offering banking, investment, and financial management services."
  }
}

Response fields

Billing

The unsubscribed tier is identified as unpaid. It was previously reported as free; clients should accept both for now and treat them as the same tier. Where a plan identifier is accepted as INPUT, free is still accepted and resolves to unpaid. unpaid is not a purchasable plan: it never appears in GET /current/org/billing/plan/list/, and subscribing to it is refused.

Where the identifier appears for an org with no active subscription, and where it does not:

Do not read an empty current_plan as "no plan" or as an error. On GET .../billing/details/ it is the normal shape for an org that is not a current subscriber. To learn which tier such an org is on, read the org's plan field rather than this object.

Preview a Plan Change

Use this before POST /current/org/{org_id}/billing/ whenever the org already has a subscription. A change that increases committed spend — a higher tier, or monthly to annual on the same tier — is invoiced immediately rather than at the next cycle, so the card is charged in the same interaction the customer confirms. Show them this figure first.

Request parameters

curl example

curl -X GET "https://api.fast.io/current/org/1234567890123456789/billing/preview/?billing_plan=enterprise_v2_monthly" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "preview": {
    "amount_due_cents": 20132,
    "currency": "usd",
    "proration_date": 1756670400,
    "source_plan": "business_v3_monthly",
    "target_plan": "enterprise_v2_monthly",
    "spend_increasing": true,
    "ends_trial": false
  }
}

Errors

Create or Update Subscription

Request parameters

curl example

curl -X POST "https://api.fast.io/current/org/1234567890123456789/billing/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "billing_plan=business_v3_monthly"

Response (201 Created) — new subscription

{
  "result": true,
  "billing_status": {
    "active": false,
    "free_trial_eligible": true,
    "current_plan": { "...": "..." },
    "customer": { "...": "..." },
    "subscription": { "...": "..." },
    "setup_intent": {
      "id": "{setup_id}",
      "client_secret": "{setup_id}_secret",
      "status": "requires_payment_method"
    },
    "payment_intent": [],
    "payment_recovery": [],
    "public_key": "{public_key}"
  }
}

Every field on this response is nested under billing_status — there is no root-level subscription, is_active, or is_trial_eligible.

This response shape is the same whether or not a trial applies. Confirm the billing_status.setup_intent.client_secret with the customer's card. No money moves at that moment — the SetupIntent is a $0 card capture that also performs any 3-D Secure authentication up front.

• Trial applies — the subscription starts in trialing and the card is charged when the trial ends.
• No trial (all annual plans, and any org that has subscribed before) — the subscription is created and charged immediately once the card is captured.

The card is inspected before any charge: a card refused by the funding rules (see payment-method/precheck/) does not produce a subscription, and the customer's billing address is taken from the card, so the first invoice is taxed correctly.

Hosted checkout (checkout=true) — Response (201 Created)

Send checkout=true with success_url and cancel_url to let a Stripe-hosted page take the card instead of your own form:

curl -X POST "https://api.fast.io/current/org/1234567890123456789/billing/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "billing_plan=business_v3_monthly" \
  -d "checkout=true" \
  -d "success_url=https://fast.io/billing/done" \
  -d "cancel_url=https://fast.io/billing"

{
  "result": true,
  "billing_status": {
    "active": false,
    "free_trial_eligible": true,
    "current_plan": { "...": "..." },
    "customer": { "...": "..." },
    "subscription": { "...": "..." },
    "setup_intent": [],
    "payment_intent": [],
    "payment_recovery": [],
    "public_key": "{public_key}",
    "checkout": {
      "id": "{checkout_session_id}",
      "url": "https://{payment_provider_checkout_host}/...",
      "expires_at": "2026-10-01 14:03:22 UTC",
      "trial": true,
      "trial_days": 30
    }
  }
}

setup_intent is empty in this response — there is nothing to confirm in your own page. checkout.trial and checkout.trial_days state whether this checkout grants a free trial (an annual plan, for example, has none even when free_trial_eligible is true); when the org owner's trial eligibility cannot be verified, no trial is offered.

The hosted page accepts cards only and requires a billing address. Beside the submit button it states either the free trial (up to the plan's trial days, or until the included trial credits are used; nothing is charged to start it; then the plan price per month plus usage and applicable tax, unless cancelled) or the amount charged today (the plan price plus applicable tax, billed monthly or annually, with usage billed monthly). No fixed trial end date is promised.

Starting checkout again for the same plan, trial and return URLs while the open page still has at least 10 minutes left returns that same session, so a double-submit is safe. Any other start replaces it: earlier open checkout pages are closed and a new one is created. Starting the card-form flow (without checkout) also closes any open checkout page, so an old checkout tab cannot complete.

Neither this request nor the redirect back creates the subscription. It is created shortly afterwards, once the card is confirmed — exactly as in the card-form flow, including the trial/no-trial charging rules and the card funding rules. After the browser returns to success_url, poll GET /current/org/{org_id}/billing/details/:

1. billing_status.current_plan.name equals the plan you started → done.
2. billing_status.payment_recovery is non-empty → send the customer to payment_recovery.invoice.hosted_invoice_url to complete payment.
3. billing_status.refusal_reason is non-null → the card was refused and no subscription was created; let the customer start checkout again with a different card.
4. Otherwise keep polling, up to your own timeout.

Response (202 Accepted) — subscription updated. A change that settles right away (a downgrade, or an upgrade that needs no additional authentication) returns 202 with no body.

Response (202 Accepted) — payment action required. When a plan change may raise a charge and the card needs additional authentication (3-D Secure), the org's subscription stays on its current plan and the response carries a payment_recovery descriptor for the pending change:

{
  "result": true,
  "billing_status": {
    "current_plan": { "name": "business_v3_monthly", "...": "..." },
    "payment_recovery": {
      "recoverable": true,
      "status": "active",
      "plan": "enterprise_v2_monthly",
      "invoice": {
        "id": "{invoice_id}",
        "status": "open",
        "amount_due": 20132,
        "currency": "usd",
        "hosted_invoice_url": "https://{payment_provider_host}/i/.../{invoice_id}"
      },
      "payment_intent": {
        "id": "{payment_intent_id}",
        "client_secret": "{payment_intent_id}_secret",
        "status": "requires_action",
        "requires_action": true
      }
    },
    "payment_intent": { "...": "same object as billing_status.payment_recovery.payment_intent" }
  }
}

billing_status.current_plan still names the plan the org is on today; payment_recovery.plan is the target of the pending change. payment_recovery.status here reports the subscription's own live status (active or trialing, not a fixed “pending” value) — recognize a pending upgrade as payment_recovery whose status is active or trialing, together with plan (the target). An unpaid subscription's recovery instead carries incomplete, past_due or unpaid. Confirm payment_recovery.payment_intent.client_secret with Stripe.js (a new card may be used) — the plan itself changes only once payment settles, moments later and asynchronously. payment_recovery disappearing on a later read is NOT itself a success or failure signal — it clears the instant the charge succeeds, before the plan changes. After a successful confirm, poll GET .../billing/details/ until billing_status.current_plan.name equals the plan you confirmed; that is the actual promotion. If the challenge is abandoned, the pending change expires after up to about 23 hours (sooner if the current billing period ends first). On an account that is current on its billing, abandoning the challenge simply leaves the org on its existing plan — no past-due status, no dunning. An account that is already behind on payment, or on an older subscription still on the prior billing mechanics, may still become past-due if the authentication is abandoned.

Re-posting the same target plan while a change is pending returns the same payment_intent rather than starting a new one — get a fresh GET .../billing/preview/ quote first (or omit proration_date), since a stale quote is refused. Posting a different plan, a downgrade, or the org's current plan first cancels the pending change; posting the current plan on its own just cancels it and leaves the subscription as it was.

Response (200 OK) — payment recovery: if the org already has an UNPAID subscription (status incomplete, past_due, or unpaid — e.g. a prior card was declined), no new subscription or setup intent is created. The response instead carries a non-empty billing_status.payment_recovery object (see Get Billing Details below for its shape); confirm its nested payment_intent.client_secret with a (new) card to pay the existing open invoice. While a subscription is in this state a plan switch is not applied — the outstanding invoice must be settled first, after which the plan can be changed once the subscription is active. (This is a genuinely unpaid subscription, distinct from the pending-upgrade case above — a pending upgrade's own invoice does not block a further plan change; posting a different plan simply cancels it, per the previous paragraph.)

Error responses

Schedule Subscription Cancellation

One exception: a trial whose trial period has already ended but that has not yet been billed is cancelled immediately instead of at period end. Nothing is charged and nothing is prorated, access ends at once, and the response is already_cancelled with no cancel_at. It cannot be reversed with PUT; a new subscription is required.

Request Parameters

curl example

curl -X DELETE "https://api.fast.io/current/org/1234567890123456789/billing/" \
  -H "Authorization: Bearer {jwt_token}"

Optionally include reason to tell us why:

curl -X DELETE "https://api.fast.io/current/org/1234567890123456789/billing/?reason=price" \
  -H "Authorization: Bearer {jwt_token}"

Response (202 Accepted)

{
  "result": true,
  "status": "scheduled_cancellation",
  "message": "Your subscription is scheduled to end at the close of the current billing period.",
  "cancel_at": 1735689600,
  "cancel_at_period_end": true,
  "closed": false
}

If a cancellation has already been scheduled (or already executed), or a trial whose trial period had already ended was just cancelled immediately:

{
  "result": true,
  "status": "already_cancelled",
  "message": "Subscription is already cancelled"
}

Response fields

Notes

• The customer retains full subscriber access (and continues to count against billing) until cancel_at. A trial cancelled after its trial period has already ended is the exception: it ends immediately, with no charge.
• current_period_end and cancel_at are also reflected on GET /current/org/{org_id}/billing/details/ so UIs can render an "ends on YYYY-MM-DD" affordance.

Error responses

Reactivate Subscription

curl example

curl -X PUT "https://api.fast.io/current/org/1234567890123456789/billing/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "status": "reactivated",
  "message": "Your subscription has been reactivated and will renew at the end of the current billing period.",
  "current_period_end": 1735689600,
  "cancel_at_period_end": false
}

Response fields

Notes

• Calling PUT on a subscription that is not currently scheduled to cancel is a successful no-op.
• Once cancel_at has passed and the subscription has terminated, the org is no longer a subscriber and PUT returns 404. Use POST /current/org/{org_id}/billing/ to start a new subscription instead.

Error responses

Get Billing Details

curl example

curl -X GET "https://api.fast.io/current/org/1234567890123456789/billing/details/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "billing_status": {
    "active": true,
    "free_trial_eligible": false,
    "current_plan": { "...": "..." },
    "customer": { "...": "..." },
    "subscription": { "...": "..." },
    "setup_intent": { "...": "..." },
    "payment_intent": { "...": "..." },
    "payment_recovery": { "...": "..." },
    "public_key": "{public_key}",
    "refusal_reason": null
  }
}

Every field on this response is nested under billing_status — there is no root-level subscription, is_active, or is_trial_eligible. billing_status.previous_plan is present only when the subscription is cancelled (see below).

Response fields

Get Credit Usage

curl example

curl -X GET "https://api.fast.io/current/org/1234567890123456789/billing/usage/limits/credits/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "credit_limits_enabled": false,
  "in_trial": false,
  "trial_auto_convert_at": 0,
  "free_credits_tracking": true,
  "free_org_mode": false,
  "org_id": "1234567890123456789",
  "plan": "starter_monthly",
  "over_free_allowance": false,
  "usage": {
    "credits_used": 1200,
    "free_credit_allowance": 100000,
    "credits_remaining": 98800,
    "usage_percentage": 1.2
  },
  "period": {
    "start": "2025-01-15 10:00:00 UTC",
    "end": "2025-02-14 10:00:00 UTC",
    "days_total": 30,
    "days_elapsed": 5,
    "days_remaining": 25
  },
  "renewal": {
    "interval_days": 30,
    "next_renewal": "2025-02-14 10:00:00 UTC"
  },
  "run_rate": null
}

The example is a paid plan outside its trial. Paid plans bill usage beyond the monthly allowance as overage, so credit_limits_enabled is false and credits_remaining tracks the included allowance rather than a ceiling. During a trial, or on a legacy plan that stops at its allowance, credit_limits_enabled is true and usage is held at the monthly allowance. A trial with a cancellation scheduled never converts to paid: usage is held at the trial's own credit allowance instead (reported as usage.free_credit_allowance), trial_auto_convert_at is 0, and in_trial stays true past the trial's end until the plan ends (unless the trial was already billed for its first term). Orgs without a paid plan, and legacy plans with a fixed credit cap, receive a capped shape instead: over_limit, usage.credit_limit and trial in place of the allowance fields.

Response fields

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

List Billable Members

Query parameters

curl example

curl -X GET "https://api.fast.io/current/org/1234567890123456789/billing/usage/members/list/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "billable_members": {
    "1234567890123456789": {
      "id": "1234567890123456789",
      "account_type": "human",
      "email_address": "user@example.com",
      "parents": {
        "9876543210987654321": {
          "permission": "member",
          "date_joined": "2024-01-15 10:30:00 UTC"
        }
      }
    }
  },
  "pagination": {"total": 1, "limit": 100, "offset": 0, "has_more": false}
}

Response fields

Get Usage Meters

Query parameters

Only one of workspace_id or share_id can be specified at a time.

Usage history retention. Usage history is kept at three resolutions, decided by each reading's own timestamp: a reading less than 45 days old is kept hour by hour; from 45 days to one year old it is kept as one point per UTC day; older than one year, as one point per calendar month, kept indefinitely. A total is identical at every resolution when the range is aligned to the resolution kept for that age: whole UTC days for readings 45 days to a year old, whole calendar months for readings older than a year. Ask for whole days over a range that reaches past a year and the month-resolution part of it still contributes whole months, because there is no finer detail left to divide — and the same is true of a range starting mid-day more than 45 days ago, which includes that entire UTC day.

Reading times are the exception, and they stay exact: the timestamp and value of the latest reading in each kept period are preserved, so a "last value" answer is always a real reading rather than the start or end of a day or a month.

Resolution of a long range. A range that reaches into a coarser resolution is answered at that resolution, and interval_hours reports the width the points are actually at — which can be wider than the range alone implies. Calendar-month points have no fixed width, so interval_hours is negative for them and counts months per point: -1 is one month, -3 a quarter. Several months are grouped into one point when a range is long enough that one point per month would exceed the point ceiling. Every point carries its own start_time and end_time, so read a point's span from those rather than assuming a fixed width.

History before the policy. This policy took effect on 2026-09-19 and did not recreate history that had already been discarded: nothing older than 120 days existed at that point. A range reaching further back returns zeros for the part with no history rather than an error, so a flat or empty early portion of a long range means there is no detail to show, not that there was no usage. Invoices and billed totals for closed periods are unaffected — they are kept independently of this detail. Pull and store anything you need at a finer resolution than the policy keeps.

curl example

curl -X GET "https://api.fast.io/current/org/1234567890123456789/billing/usage/meters/list/?meter=storage&start_time=2026-08-01+00:00:00&end_time=2026-08-31+23:59:59" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "usage": {
    "meter": "storage",
    "total": 1073741824,
    "cost": 0.50,
    "credits": 500,
    "start_time": "2026-08-01 00:00:00 UTC",
    "end_time": "2026-08-31 23:59:59 UTC",
    "interval_hours": 24,
    "workspace_id": null,
    "share_id": null,
    "data_points": [
      {
        "start_time": "2026-08-01 00:00:00 UTC",
        "end_time": "2026-08-02 00:00:00 UTC",
        "value": 536870912,
        "cost": 0.25,
        "credits": 250
      }
    ]
  }
}

Response fields

Error responses

List Available Plans

• All accounts (agent and human) see the same paid plans, whether activating a new organization or switching an existing one: Starter, Business, and Enterprise. Each plan is offered in a monthly and an annual interval (e.g., starter_monthly / starter_annual, business_v3_monthly / business_v3_annual, enterprise_v2_monthly / enterprise_v2_annual).
• The free plan and legacy plans are not offered to new organizations; existing organizations on those plans keep their current plan.

New organizations choose a paid plan to activate; until then the org is in an upgrade-only state.

curl example

curl -X GET "https://api.fast.io/current/org/billing/plan/list/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

Each entry in plans is the full plan definition. The example below is abbreviated: it shows one of the six entries, trims its meters, features and limits objects, and omits a few presentation fields. The real response lists every meter, feature flag and limit.

{
  "result": true,
  "results": 6,
  "defaults": {
    "pro": "starter_monthly",
    "business": "business_v3_monthly"
  },
  "plans": [
    {
      "name": "enterprise_v2_monthly",
      "title": "Enterprise",
      "desc": "For scaling teams that need room to grow",
      "category": "business",
      "pricing": {
        "price_base": 199.99,
        "coupon": null,
        "meters": {
          "credits": {
            "price_per_unit": 0.01,
            "unit": 100,
            "free_units": 3000000,
            "unit_desc": "credit",
            "meter_type": "direct",
            "aggregation_type": "last"
          },
          "users": {
            "price_per_unit": 1,
            "unit": 1,
            "unit_desc": "seats",
            "free_units": 30,
            "meter_type": "direct",
            "aggregation_type": "average"
          }
        },
        "billing_threshold": 450,
        "billed": "monthly",
        "free": false,
        "free_days": 30,
        "free_cooldown": 5184000,
        "discount": null
      },
      "legacy_billing": false,
      "credit_overage_behavior": "metered_overage",
      "trial_credit_limit": 150000,
      "seat_limit": 200,
      "available": true,
      "show_upgrade_msg": true,
      "features": {
        "sso": true,
        "org_controls": true,
        "content_ai": true,
        "ai_agent": true
      },
      "limits": {
        "event_retention_days": 365,
        "workspaces": { "limit": 200, "members": 30 }
      }
    }
  ]
}

Response fields

List Invoices

Query parameters

curl example

curl -X GET "https://api.fast.io/current/org/1234567890123456789/billing/invoices/?limit=10" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "invoices": [
    {
      "id": "in_1234567890",
      "status": "paid",
      "currency": "usd",
      "amount_due": 2900,
      "amount_paid": 2900,
      "subtotal": 2900,
      "total": 2900,
      "paid": true,
      "description": "Subscription creation",
      "hosted_invoice_url": "https://{payment_provider_host}/i/.../{invoice_id}",
      "invoice_pdf": "https://{payment_provider_host}/invoice/.../{invoice_id}.pdf",
      "period_start": "2026-03-01 00:00:00 UTC",
      "period_end": "2026-04-01 00:00:00 UTC",
      "created": "2026-03-01 00:00:00 UTC"
    }
  ],
  "has_more": false
}

Response fields

Amounts are in the smallest currency unit (cents for USD). Use hosted_invoice_url to link users to their invoices. Use starting_after with the last invoice id for pagination.

Create Workspace (from Org)

Request parameters

curl example

curl -X POST "https://api.fast.io/current/org/1234567890123456789/create/workspace/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "folder_name=project-alpha" \
  -d "name=Project Alpha" \
  -d "perm_join=Member or above" \
  -d "perm_member_manage=Admin or above"

Response (200 OK)

{
  "result": true,
  "workspace": {
    "id": "1234567890123456780",
    "folder_name": "project-alpha",
    "intelligence": true
  }
}

Response fields

Error responses

List Workspaces in Org

Query parameters

Access levels

curl example

curl -X GET "https://api.fast.io/current/org/1234567890123456789/list/workspaces/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "workspaces": [
    {
      "id": "1234567890123456780",
      "folder_name": "project-alpha",
      "name": "Project Alpha",
      "description": "Main project workspace"
    }
  ],
  "pagination": {"total": 1, "limit": 100, "offset": 0, "has_more": false}
}

Response fields