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.

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.

Organization CRUD

Create Organization

Request parameters

A newly created organization must select a paid plan (Starter, Business, or Growth) 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 14-day free trial. Annual plans have no trial — 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

Ownership Transfer / Claim (Agent-Owned Orgs)

When an agent account creates and owns an org, this flow lets a human user take over ownership. The agent (owner of an org on the agent plan) mints a short-lived transfer token, shares it with the human, and the human claims the org with that token. On a successful claim the human becomes the new owner of the org and every workspace under it, and the agent that created the org is demoted to admin (on the org and on each workspace). The org is also moved off the agent plan onto the transfer target plan.

This is distinct from Transfer Org Ownership (above), which reassigns ownership between two existing members of the same org. The token flow crosses the agent-to-human boundary and does not require the human to already be a member.

Token lifecycle: tokens are pending when created, become claimed once a human claims them, expired after their expiry (default 72 hours from creation), or deleted if revoked. Only a pending, non-expired token is claimable. An org may have at most 5 active (pending) tokens at a time. The raw 64-character token secret is returned by the create, list, and revoke endpoints (so the agent can share it); the public details endpoint deliberately omits it.

Create Transfer Token

curl example

curl -X POST "https://api.fast.io/current/org/1234567890123456789/transfer/token/create/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "transfer_token": {
    "id": "eA1B2C3D4E5F6G7H8J9K0L1M2N3O4",
    "token": "a1b2c3d4e5f6...{64-char secret}",
    "org_id": 1234567890123456789,
    "state": "pending",
    "expires": "2026-07-10 16:37:29 UTC",
    "created": "2026-07-07 16:37:29 UTC"
  }
}

Response fields

Error responses

List Transfer Tokens

curl example

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

Response (200 OK)

{
  "result": true,
  "results": 1,
  "transfer_tokens": [
    {
      "id": "eA1B2C3D4E5F6G7H8J9K0L1M2N3O4",
      "token": "a1b2c3d4e5f6...{64-char secret}",
      "org_id": 1234567890123456789,
      "state": "pending",
      "expires": "2026-07-10 16:37:29 UTC",
      "created": "2026-07-07 16:37:29 UTC"
    }
  ]
}

Each token object has the same shape as Create Transfer Token; results is the number of active tokens returned. Returns 1680 (Access Denied) (401) if the caller is not an agent account.

Revoke Transfer Token

curl example

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

Response (200 OK)

{
  "result": true,
  "transfer_token": {
    "id": "eA1B2C3D4E5F6G7H8J9K0L1M2N3O4",
    "token": "a1b2c3d4e5f6...{64-char secret}",
    "org_id": 1234567890123456789,
    "state": "deleted",
    "expires": "2026-07-10 16:37:29 UTC",
    "created": "2026-07-07 16:37:29 UTC"
  }
}

Error responses

Get Public Token Details

Query parameters

curl example

curl -X GET "https://api.fast.io/current/org/transfer/claim/public/details/?token=a1b2c3d4e5f6...{64-char secret}"

Response (200 OK)

{
  "result": true,
  "transfer_token": {
    "id": "eA1B2C3D4E5F6G7H8J9K0L1M2N3O4",
    "state": "pending",
    "is_claimable": true,
    "expires": "2026-07-10 16:37:29 UTC",
    "created": "2026-07-07 16:37:29 UTC"
  },
  "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",
    "plan": "agent"
  },
  "created_by": {
    "id": "1234567890123456780",
    "account_type": "agent",
    "first_name": "Service",
    "last_name": "Bot",
    "email_address": "bot@example.com",
    "profile_pic": null
  }
}

The transfer_token.is_claimable boolean reports whether the token can currently be claimed (pending and not expired). The org and created_by objects are omitted if the org or its agent creator can no longer be loaded.

Error responses

Claim Org (Human User)

On success: the human becomes owner of the org and of every workspace under it; the agent that created the org is demoted to admin on the org and on each workspace; the org is moved off the agent plan onto its transfer target plan; and the token is marked claimed.

Request parameters

curl example

curl -X POST "https://api.fast.io/current/org/transfer/claim/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "token=a1b2c3d4e5f6...{64-char secret}"

Response (200 OK)

{
  "result": true,
  "org": {
    "id": "1234567890123456789",
    "domain": "acme-corp",
    "plan": "solo_monthly"
  },
  "previous_owner": {
    "id": "1234567890123456780",
    "account_type": "agent"
  },
  "workspaces_transferred": 3
}

Response fields

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