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.

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, Workspace and File Share also carries its own external_invites flag (allowed / denied, absent = inherit the org policy — see the Shares and Workspaces references). 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 widening an object's own public-access setting, including 'Registered users with an 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 and sign_envelope entity types are not offered; they are not selectable here.) 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.

Audit. org_updated carries cloud_sync inside its existing policy_changes map: policy_changes.cloud_sync = { before: {enabled, mode}, after: {enabled, mode}, overrides: {added, removed, changed} }.

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.

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.

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, Growth, 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 other than Enterprise begin a 14-day free trial. Enterprise and all annual plans have no trial — Enterprise is billed at signup, and an annual subscription is billed for the full term at signup. A free 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 free trial is offered on a later org, no matter how much time has passed. A secondary per-user cooldown (60 days on modern plans, anchored at trial start) also applies on top of this, though in practice it only matters on the first org itself. 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 14: 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) — free 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 free trial is offered — the org still subscribes but bills immediately. This is the primary block and is permanent, so there is no trial_available_at:

{
  "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 free trial can also be blocked by the secondary per-user cooldown (60 days on modern plans, anchored at trial start) — in practice this only matters on the first org itself. That case does include trial_available_at:

{
  "result": true,
  "org": { "...": "..." },
  "has_free_trial": false,
  "requires_payment": true,
  "is_agent": false,
  "no_trial_reason": "A free trial was started recently. A new free trial is available in 43 days.",
  "trial_available_at": "2026-08-05 12:00:00 UTC"
}

requires_payment is always true for new orgs (the legacy free tier is closed). 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": "#0066CC",
    "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 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": "#0066CC"
  }
}

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"

This response shape is the same whether or not a free trial applies. Confirm the 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 does not produce a subscription, and the customer's billing address is taken from the card, so the first invoice is taxed correctly.

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,
  "assets": [
    {
      "name": "logo",
      "mime_types": ["image/png", "image/jpeg"],
      "max_size": 5242880
    }
  ]
}

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": {
      "url": "https://assets.fast.io/org/logo.png",
      "mime_type": "image/png",
      "size": 45678
    }
  }
}

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

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": "eA1B2C3D4E5F6G7H8J9K0L1M2N3O4",
    "invitee_email": "jane@example.com",
    "entity_type": "org",
    "state": "pending",
    "created": "2024-01-15 10:30:00 UTC"
  }
}

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"
    },
    {
      "id": "1234567890123456780",
      "account_type": "agent",
      "email_address": "bot@example.com",
      "first_name": "Service",
      "last_name": "Bot",
      "permissions": "admin"
    }
  ],
  "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,
  "member": {
    "id": "9876543210987654321",
    "account_type": "human",
    "email_address": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Smith",
    "permissions": "admin",
    "invite": "accepted",
    "notify": "Email me",
    "expires": null,
    "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

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
}

Error responses

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 and the user's email domain must match. User is added as a Member.

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": "eA1B2C3D4E5F6G7H8J9K0L1M2N3O4",
      "inviter": "John Doe",
      "invitee_email": "jane@example.com",
      "entity_type": "org",
      "state": "pending",
      "created": "2024-01-15 10:30:00 UTC",
      "expires": "2024-02-15 10:30:00 UTC"
    }
  ]
}

Response fields

Error responses

Update an Invitation

{invitation_id} can be the invitation ID or the invitee email address.

Request parameters (all optional)

curl example

curl -X POST "https://api.fast.io/current/org/1234567890123456789/members/invitation/eA1B2C3D4E5F6G7H8J9K0L1M2N3O4/" \
  -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.

curl example

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

Response (200 OK)

{
  "result": true
}

Error responses

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": "#0066CC",
      "closed": false,
      "suspended": false,
      "subscriber": true,
      "user_status": "joined",
      "member": true
    }
  ]
}

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": "#FF6600",
      "closed": false,
      "suspended": false,
      "subscriber": true,
      "user_status": "available",
      "member": 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": "#0066CC",
      "closed": false,
      "suspended": false,
      "user_status": "joined"
    }
  ]
}

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": "#FF6600",
      "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,
  "technology": {
    "title": "Technology",
    "description": "Software, hardware, and IT services"
  },
  "healthcare": {
    "title": "Healthcare",
    "description": "Medical, pharmaceutical, and health services"
  },
  "finance": {
    "title": "Finance",
    "description": "Banking, investment, and financial services"
  },
  "education": {
    "title": "Education",
    "description": "Schools, universities, and training providers"
  }
}

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=growth_monthly" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "preview": {
    "amount_due_cents": 20132,
    "currency": "usd",
    "proration_date": 1756670400,
    "source_plan": "business_v2_monthly",
    "target_plan": "growth_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_v2_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": null,
    "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.

Response (202 Accepted) — subscription updated.

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.

Error responses

Schedule Subscription Cancellation

curl example

curl -X DELETE "https://api.fast.io/current/org/1234567890123456789/billing/" \
  -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):

{
  "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.
• 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}"
  }
}

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": true,
  "free_org_mode": false,
  "org_id": "1234567890123456789",
  "plan": "solo_monthly",
  "over_limit": false,
  "usage": {
    "credits_used": 1200,
    "credit_limit": 300000,
    "credits_remaining": 298800,
    "usage_percentage": 0.4
  },
  "period": {
    "start": "2025-01-15 10:00:00 UTC",
    "end": "2025-02-14 10:00:00 UTC",
    "days_total": 30,
    "days_elapsed": 10,
    "days_remaining": 20
  },
  "renewal": {
    "interval_days": 30,
    "next_renewal": "2025-02-14 10:00:00 UTC"
  },
  "trial": null
}

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

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": [
    {
      "id": "1234567890123456789",
      "account_type": "human",
      "email_address": "user@example.com",
      "parents": {
        "9876543210987654321": {
          "permission": "member",
          "date_joined": "2024-01-15 10:30:00 UTC"
        }
      }
    }
  ]
}

Response fields

Get Usage Meters

Query parameters

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

Usage history retention. Detailed usage history is kept for a bounded window; detail older than that window is removed automatically. A request whose range reaches past the window returns zeros for the part that is no longer retained rather than an error, so a flat or empty early portion of a long range means the detail has aged out, 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 to keep for longer.

curl example

curl -X GET "https://api.fast.io/current/org/1234567890123456789/billing/usage/meters/list/?meter=storage_bytes&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_bytes",
    "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 Growth. Each plan is offered in a monthly and an annual interval (e.g., solo_monthly / solo_annual, business_v2_monthly / business_v2_annual, growth_monthly / growth_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)

{
  "result": true,
  "results": 3,
  "defaults": {
    "pro": "solo_monthly",
    "business": "business_v2_monthly"
  },
  "plans": [
    {
      "id": "solo_monthly",
      "name": "Starter",
      "category": "pro",
      "amount": 2900
    },
    {
      "id": "business_v2_monthly",
      "name": "Business",
      "category": "business",
      "amount": 9900
    },
    {
      "id": "growth_monthly",
      "name": "Growth",
      "category": "business",
      "amount": 29900
    }
  ]
}

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"
  }
}

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"
    }
  ]
}

Response fields