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 400. 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) that list-view subscription chips render. 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 begin a 14-day free trial of a paid plan. A user may start only one free trial every 60 days across all orgs they own; within that window a new org subscribes with immediate payment instead of a trial.

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 is within the per-user 60-day trial cooldown, no free trial is offered — the org still subscribes but bills immediately:

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

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"

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

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

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,
  "subscription": { "...": "..." },
  "customer": { "...": "..." },
  "setup_intent": {
    "id": "{setup_id}",
    "client_secret": "{setup_id}_secret",
    "status": "requires_payment_method"
  },
  "is_active": false,
  "is_trial_eligible": true,
  "public_key": "{public_key}"
}

Response (202 Accepted) — subscription updated.

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,
  "subscription": { "...": "..." },
  "customer": { "...": "..." },
  "setup_intent": { "...": "..." },
  "payment_intent": { "...": "..." },
  "is_active": true,
  "is_trial_eligible": false,
  "is_cancelled": false,
  "current_plan": "business_v2_monthly",
  "previous_plan": null,
  "public_key": "{public_key}"
}

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 (100/GB), bandwidth (212/GB), AI tokens (1/100 tokens), document ingestion (10/page), video ingestion (5/sec), image ingestion (5/image), file conversions (25/each).

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.

curl example

curl -X GET "https://api.fast.io/current/org/1234567890123456789/billing/usage/meters/list/?meter=storage_bytes&start_time=2024-01-01+00:00:00&end_time=2024-01-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": "2024-01-01 00:00:00 UTC",
    "end_time": "2024-01-31 23:59:59 UTC",
    "interval_hours": 24,
    "workspace_id": null,
    "share_id": null,
    "data_points": [
      {
        "start_time": "2024-01-01 00:00:00 UTC",
        "end_time": "2024-01-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 paid plans available for new organizations: 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",
    "growth": "growth_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": "growth",
      "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" \
  -d "intelligence=true"

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