Workspace Management Create, configure, and manage workspaces within organizations. Control members, assets, shares, and AI intelligence settings.

Workspaces are shared project spaces within an organization. They support file versioning, search, AI chat, and member management. Most workspace endpoints also accept the workspace's folder_name (e.g., my-project) in place of the numeric ID.

Endpoint Summary

Workspace CRUD

Assets

Members

Invitations

Shares (in workspace context)

File Shares (durable single-file links)

Cloud Import

Discovery

Compact Responses (output=)

Every endpoint that returns one or more workspace 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 workspace switchers, autocomplete, and org-scoped navigation — it carries the identifier, display name, folder slug, parent org domain, and user_status so the two-column "Joined vs. Available" workspace list can render and the join button can enable/disable without a follow-up fetch. Use standard for workspace list views and the summary area of workspace detail pages — it adds lifecycle flags (including the locked admin-only chip), storage usage, timestamps, description, the workspace's visual identity (logo, accent_color), plus the intelligence feature toggles and the plan-gate capabilities bundle so list rows can differentiate "enabled but plan-locked" from "usable." Use full (or omit the parameter) for the workspace settings screen, branding editors, and any workflow that reads permission matrices or remaining feature blocks (comments, chat, search, assets). 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.

Field Constraints

Permission Values

perm_join — who can self-join from the parent org

perm_member_manage — who can manage workspace members

Permission Levels (numeric hierarchy)

Intelligence Setting

The intelligence boolean on a workspace controls whether uploaded files are automatically indexed for RAG (retrieval-augmented generation).

• Enable (intelligence=true) — files are auto-indexed for semantic search, summarization, and citation. Required for chat_with_files AI chat type. Requires both the content_ai and ai_agent plan features. Plans that lack either feature cannot set intelligence=true; the API rejects the create/update request with 1605 (Invalid Input).
• Disable (intelligence=false) — files are stored/shared without RAG indexing. You can still attach files directly to a chat type conversation for one-off analysis on plans that support chat.
• Set at creation: POST /current/org/{org_id}/create/workspace/ with intelligence=true|false
• Update later: POST /current/workspace/{id}/update/ with intelligence=true|false
• Can be enabled and disabled within time restrictions. Disabling intelligence destroys indexed embeddings (the vector index is flushed). Re-enabling intelligence incurs re-indexing costs as AI credits are consumed to re-index all files.
• Agent-account default: On plans that include ai_agent, new workspaces created by agent accounts default intelligence=true if the parameter is omitted. On plans without ai_agent (including the legacy agent plan), the default is false because the indexing pipeline has no consumer. See the AI reference for the full plan matrix.

Workspace CRUD

Create Workspace

Auth: JWT required. Org membership (Member or above) required.

Path Parameters

Request Parameters

Example

curl -X POST "https://api.fast.io/current/org/1000000000000000001/create/workspace/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "folder_name=engineering" \
  -d "name=Engineering Team" \
  -d "description=Main engineering workspace for the team" \
  -d "perm_join=Member or above" \
  -d "perm_member_manage=Admin or above" \
  -d "intelligence=true"

Response (200 OK)

{
  "result": true,
  "workspace": {
    "id": "1234567890123456789",
    "folder_name": "engineering"
  }
}

Response Fields

Access Levels

Error Responses

Get Workspace Details

Auth: JWT required. Workspace membership required (View or above).

Path Parameters

Example

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

Response (200 OK)

{
  "result": true,
  "workspace": {
    "id": "1234567890123456789",
    "name": "Engineering Team",
    "folder_name": "engineering",
    "description": "Main engineering workspace",
    "accent_color": "#0066CC",
    "logo": "https://assets.fast.io/1234567890123456789/logo.png",
    "closed": false,
    "archived": false,
    "perm_join": "Member or above",
    "perm_member_manage": "Admin or above",
    "created": "2023-01-15 10:30:00 UTC",
    "updated": "2024-01-20 14:45:00 UTC",
    "user_status": "joined",
    "org_domain": "acme-corp",
    "nl_summaries_daily_cap": 100
  }
}

Response Fields

Access Levels

Error Responses

Update Workspace

Auth: JWT required. Admin or Owner required.

Path Parameters

Request Parameters (all optional)

Example

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/update/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "name=Updated Workspace Name" \
  -d "description=New description for the workspace" \
  -d "perm_join=Admin or above"

Response (200 OK)

{
  "result": true
}

Error Responses

If no fields have changed, returns 200 OK without making changes. JSON fields are decoded server-side; send valid JSON strings.

Delete Workspace

Auth: JWT required. Owner only. 2FA required.

Path Parameters

Query Parameters

Example

curl -X DELETE "https://api.fast.io/current/workspace/1234567890123456789/delete/?confirm=engineering" \
  -H "Authorization: Bearer {jwt_token}"

Response (202 Accepted)

{
  "result": true
}

Error Responses

Archive Workspace

Auth: JWT required. Admin or Owner required. 2FA required.

Example

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/archive/" \
  -H "Authorization: Bearer {jwt_token}"

Response (202 Accepted)

{
  "result": true
}

Error Responses

Unarchive Workspace

Auth: JWT required. Admin or Owner required. 2FA required.

Example

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/unarchive/" \
  -H "Authorization: Bearer {jwt_token}"

Response (202 Accepted)

{
  "result": true
}

Error Responses

Workspace Assets

List Available Asset Types

Auth: JWT required.

Example

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

Response (200 OK)

{
  "result": true,
  "assets": [
    {
      "name": "logo",
      "type": "image",
      "max_size": 5242880,
      "accepted_formats": ["image/png", "image/jpeg", "image/svg+xml"]
    }
  ]
}

List Workspace Assets

Auth: JWT required. Owner only. 2FA required.

Example

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

Response (200 OK)

{
  "result": true,
  "assets": {
    "logo": {
      "url": "https://assets.fast.io/1234567890123456789/logo.png",
      "size": 102400,
      "content_type": "image/png"
    }
  }
}

Upload/Set Workspace Asset

Auth: JWT required. Admin or Owner required.

Path Parameters

Request Body (multipart/form-data)

Example

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

Response (200 OK)

{
  "result": true,
  "asset": {
    "name": "logo",
    "url": "https://assets.fast.io/1234567890123456789/logo.png"
  }
}

Error Responses

Delete Workspace Asset

Auth: JWT required. Admin or Owner required.

Example

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

Response (200 OK)

{
  "result": true
}

Read Asset Binary

Auth: JWT required. Any workspace member. 2FA required.

Example

# Download asset
curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/assets/logo/read/" \
  -H "Authorization: Bearer {jwt_token}" \
  --output logo.png

# Get metadata headers only
curl -I "https://api.fast.io/current/workspace/1234567890123456789/assets/logo/read/" \
  -H "Authorization: Bearer {jwt_token}"

Response: Raw binary content with appropriate Content-Type header (not JSON).

Workspace Members

Add or Invite a Member

Auth: JWT required. Permission depends on workspace perm_member_manage setting.

Path Parameters

Request Parameters (adding by user ID)

Request Parameters (inviting by email)

Examples

# Add existing user by ID
curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/members/9876543210987654321/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "permissions=member"

# Invite by email
curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/members/newuser@example.com/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "permissions=member" \
  -d "message=Welcome to the project!"

Response — Direct Add (200 OK)

{
  "result": true
}

Response — Invitation Sent (200 OK)

{
  "result": true,
  "invitation": {
    "id": "1234567890123456789",
    "inviter": "John Doe",
    "invitee_email": "newuser@example.com",
    "entity_type": "workspace",
    "state": "pending",
    "created": "2025-01-15 10:30:00 UTC",
    "expires": "2025-02-15 10:30:00 UTC"
  }
}

Error Responses

Adding a user to a workspace may also auto-add them to the parent organization if the workspace is configured for automatic org membership.

Remove a Member

Auth: JWT required. Permission depends on perm_member_manage.

Example

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

Response (200 OK)

{
  "result": true
}

Error Responses

Removing a member cascades removal into all shares within the workspace.

List Workspace Members

Auth: JWT required. Any workspace member.

Example

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

Response (200 OK)

{
  "result": true,
  "users": [
    {
      "id": "1234567890123456789",
      "account_type": "human",
      "email_address": "owner@example.com",
      "first_name": "Alice",
      "last_name": "Johnson",
      "permissions": "owner",
      "status": "active",
      "invite": "accepted",
      "notify": "Email me",
      "expires": null
    },
    {
      "id": "9876543210987654321",
      "account_type": "agent",
      "email_address": "bot@example.com",
      "first_name": "Sync",
      "last_name": "Bot",
      "permissions": "member",
      "status": "active",
      "invite": "accepted",
      "notify": "Notify me in app",
      "expires": "2025-12-31 23:59:59 UTC"
    },
    {
      "id": "5566778899001122334",
      "account_type": "human",
      "email_address": "invited@example.com",
      "first_name": "invited@example.com",
      "last_name": "",
      "permissions": "member",
      "status": "pending",
      "invite": {
        "id": "5566778899001122334",
        "created": "2025-01-15 10:30:00 UTC",
        "expires": "2025-02-15 10:30:00 UTC"
      },
      "notify": "Notify me in app",
      "expires": null
    }
  ]
}

Response Fields

Leave Workspace (Self)

Auth: JWT required.

Example

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

Response (200 OK)

{
  "result": true
}

Error Responses

Get Member Details

Auth: JWT required. Any workspace member.

Example

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

Response (200 OK)

{
  "result": true,
  "member": {
    "id": "9876543210987654321",
    "account_type": "human",
    "email_address": "user@example.com",
    "first_name": "Jane",
    "last_name": "Smith",
    "permissions": "member",
    "invite": "accepted",
    "notify": "Notify me in app",
    "expires": null
  }
}

Response Fields

Error Responses

Update a Member

Auth: JWT required. Permission depends on perm_member_manage.

Request Parameters (all optional)

Example

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

Response (200 OK)

{
  "result": true
}

Error Responses

Users cannot escalate permissions beyond their own level.

Transfer Workspace Ownership

Auth: JWT required. Owner only.

Example

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

Response (200 OK)

{
  "result": true
}

Error Responses

Join Workspace

Auth: JWT required.

Request Parameters

Example

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

Response (200 OK)

{
  "result": true
}

Error Responses

Self-joining members are assigned the member role. Only notification preferences are accepted. Self-joined memberships do not expire.

Join Workspace via Invitation

Auth: JWT required.

Path Parameters

Example

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

Response (200 OK)

{
  "result": true
}

Error Responses

The system validates the inviter still has sufficient permissions at acceptance time. Accepting may also auto-add the user to the parent organization.

Pending Members

When a user is invited to a workspace by email but does not yet have a Fastio account, they appear as a pending member in the member list.

How pending members appear in responses:

• The status field is "pending" (vs "active" for registered users).
• An invite object is included with basic invitation details (id, created, expires).
• email_address shows the invited email address.
• first_name is set to the invited email address; last_name is empty.

Example Member List Entry (Pending)

{
  "id": "5566778899001122334",
  "account_type": "human",
  "email_address": "newuser@example.com",
  "first_name": "newuser@example.com",
  "last_name": "",
  "permissions": "member",
  "status": "pending",
  "invite": {
    "id": "5566778899001122334",
    "created": "2025-01-15 10:30:00 UTC",
    "expires": "2025-02-15 10:30:00 UTC"
  },
  "notify": "Notify me in app",
  "expires": null
}

Account claim: When the invited user signs up or accepts the invitation with an existing account, their status transitions from "pending" to "active".

Removal: To remove a pending member, delete their invitation using the invitation endpoints (see Workspace Invitations below). Deleting the invitation removes the pending member.

Notifications: Pending members do not receive in-app or email notifications until they claim their account.

Workspace Invitations

List Workspace Invitations

Auth: JWT required. Any workspace member.

Example

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

Response (200 OK)

{
  "result": true,
  "invitations": [
    {
      "id": "1234567890123456789",
      "inviter": "Alice Johnson",
      "invitee_email": "newuser@example.com",
      "invitee_uid": null,
      "accepted_uid": null,
      "entity_type": "workspace",
      "workspace": {
        "id": "9876543210987654321",
        "name": "Project Alpha"
      },
      "state": "pending",
      "created": "2025-01-15 10:30:00 UTC",
      "updated": "2025-01-15 10:30:00 UTC",
      "expires": "2025-02-15 10:30:00 UTC"
    }
  ]
}

Response Fields

List Invitations by State

Auth: JWT required. Any workspace member.

Path Parameters

Example

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

Response: Same format as List Workspace Invitations, filtered by state.

Error Responses

Update an Invitation

Auth: JWT required. Permission depends on perm_member_manage.

Request Parameters (all optional)

Examples

# Revoke by ID
curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/members/invitation/1111111111111111111/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "state=revoked"

# Update by email
curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/members/invitation/user@example.com/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "permissions=admin"

Response (200 OK)

{
  "result": true
}

Error Responses

Delete an Invitation

Auth: JWT required. Permission depends on perm_member_manage.

Example

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

Response (200 OK)

{
  "result": true
}

Error Responses

Creating Shares from Workspaces

Create Share

Auth: JWT required. Admin or Owner required.

For full share management documentation, see Shares reference.

Required Parameters

Optional Parameters

Access Options (access_options)

Example

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/create/share/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "title=Client Deliverables" \
  -d "share_type=send" \
  -d "intelligence=true" \
  -d "access_options=Anyone with a registered account" \
  -d "invite=owners"

Response (200 OK)

{
  "result": true,
  "share": {
    "id": "9876543210987654321",
    "custom_name": "abc123opaque",
    "storage_mode": "independent"
  }
}

Response — Workspace Folder Share

{
  "result": true,
  "share": {
    "id": "9876543210987654321",
    "custom_name": "def456opaque",
    "storage_mode": "workspace_folder",
    "folder_node_id": "abc123def456"
  }
}

Response Fields

Error Responses

List Shares in Workspace

Auth: JWT required. View or above.

Query Parameters

Example

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

Response (200 OK)

{
  "result": true,
  "shares": [
    {
      "id": "9876543210987654321",
      "title": "Client Deliverables",
      "share_type": "send",
      "custom_name": "client-deliverables",
      "archived": false,
      "closed": false
    }
  ]
}

Import Share into Workspace

Auth: JWT required. Must be workspace member AND share owner.

Path Parameters

Example

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/import/share/9876543210987654321/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "share": {
    "id": "9876543210987654321",
    "parent_type": "workspace",
    "parent_workspace": "1234567890123456789"
  }
}

Error Responses

Share must be user-owned (not already in another workspace). User must be the sole owner. Multiple owners must be removed first. Archived shares are auto-unarchived during import.

File Shares (Durable Single-File Links)

A File Share is a durable, link-shareable view of one workspace file — the successor to the deprecated QuickShare. It is durable by default (an optional expiry can be set on create/update) and has no per-link transfer cap (bandwidth is metered to the owning organization). A File Share is bound to a single file node at creation and the binding is immutable. The public read endpoints (details, download, preview, versions) are documented in the Shares and Storage references; the management endpoints below require the caller to be an authenticated member of the workspace.

Comment visibility is one-directional (workspace ⊇ File Share). Because a File Share is just a view of a workspace file, comments left by File Share recipients also surface to workspace members — read-only on the workspace file's comment thread and in workspace comment search. The reverse is never true: a File Share recipient sees only the comments made under that File Share and never the workspace's internal comments.

Create a File Share

Request Body (form-encoded)

curl Example

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/create/fileshare/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "node=f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjf" \
  -d "title=Quarterly Presentation" \
  -d "access_option=anyone_with_link"

Response (200 OK)

{
  "result": true,
  "fileshare": {
    "fileshare": "1234567890123456789",
    "title": "Quarterly Presentation",
    "access_option": "anyone_with_link",
    "has_password": false,
    "bound_node_id": "f3jm5zqzfxpxdr2dx8z5bvnb3rpjf",
    "creator_uid": "9876543210987654321",
    "created": "2026-04-27 16:37:29 UTC",
    "updated": "2026-04-27 16:37:29 UTC",
    "expires": null
  }
}

Error Responses

List File Shares in Workspace

Each item additionally carries grant_count (the number of live named-people grants on the File Share — revoked / expired grants excluded) and grants_preview (the first few grants, in the same shape as the grants list endpoint, for rendering an avatar stack without a second call). Both are best-effort: if the grant read faults for an item, the two fields are omitted for that item (the rest of the list still returns). The full access list is the GET .../grants/ endpoint below.

Response (200 OK)

{
  "result": true,
  "fileshares": [
    {
      "fileshare": "1234567890123456789",
      "title": "Quarterly Presentation",
      "access_option": "anyone_with_link",
      "has_password": false,
      "bound_node_id": "f3jm5zqzfxpxdr2dx8z5bvnb3rpjf",
      "creator_uid": "9876543210987654321",
      "created": "2026-04-27 16:37:29 UTC",
      "updated": "2026-04-27 16:37:29 UTC",
      "expires": null,
      "grant_count": 2,
      "grants_preview": [
        {
          "user": "9876543210987654321",
          "name": "Ada Lovelace",
          "email": "ada@example.com",
          "capability": "edit",
          "state": "active",
          "created": "2026-04-27 16:37:29 UTC",
          "expires": null
        },
        {
          "user": null,
          "name": null,
          "email": "pending.invitee@example.com",
          "capability": "view",
          "state": "pending",
          "created": "2026-04-27 16:40:00 UTC",
          "expires": "2026-05-27 16:40:00 UTC"
        }
      ]
    }
  ]
}

Update a File Share

Request Body (form-encoded)

Returns the updated File Share in the same shape as create.

Delete a File Share

List / Manage Per-User Grants

List (GET) Response (200 OK)

Returns the File Share's live named-people grants — revoked and expired grants are excluded. There are no pagination parameters (the access list is small; the first 1000 grants are returned).

{
  "result": true,
  "grants": [
    {
      "user": "9876543210987654321",
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "capability": "edit",
      "state": "active",
      "created": "2026-04-27 16:37:29 UTC",
      "expires": null
    },
    {
      "user": null,
      "name": null,
      "email": "pending.invitee@example.com",
      "capability": "view",
      "state": "pending",
      "created": "2026-04-27 16:40:00 UTC",
      "expires": "2026-05-27 16:40:00 UTC"
    }
  ]
}

Grant Fields

Grant / Revoke (POST / DELETE) Request Body (form-encoded)

Supply exactly one of user or email (supplying both, or neither, is rejected as invalid input — 1605, HTTP 406).

A view grant can open the link and preview; download can also download the bytes (and historical versions); edit can additionally replace the file's content via an upload session (see the Upload reference). Re-granting the same capability, or revoking a non-existent grant, is a silent no-op. Response (POST by user, or DELETE): {"result": true}.

Granting by Email

• If the email belongs to an existing account, it is granted directly — the response carries the resolved user, and the grant appears in the list as state: active.
• If the email has no account yet, a pending invitation is created and an invite email is sent. The grant appears in the list as state: pending (with user: null) and activates automatically when that person signs up with the invited address — they then hold exactly the capability you granted. The response carries the new pending grant in the same shape as a grants-list row (so it folds straight into the rendered access list).
• Re-granting a pending email at a different capability updates the pending invitation to the new capability.
• Granting a now-registered email directly supersedes any pending invitation for that address (the pending entry is replaced by the active grant).

Revoking by Email (DELETE)

Revokes an active grant for that address, and/or cancels a still-pending invitation for it. Cancelling a pending invitation confers nothing, so it does not emit an access-revoked event. A DELETE that matches neither is an idempotent success.

Response (POST by registered email): { "result": true, "user": { "id": "9876543210987654321" } }

Response (POST by unregistered email — invitation created). The pending grant is returned in the same shape as a grants-list row (user is null for an unclaimed invitee; the internal invitation/account id is never exposed):

{
  "result": true,
  "grant": {
    "user": null,
    "name": null,
    "email": "newperson@example.com",
    "capability": "view",
    "state": "pending",
    "created": "2026-04-27 16:37:29 UTC",
    "expires": "2026-05-27 16:37:29 UTC"
  }
}

Error Responses

Workspace Discovery

List All Workspaces

Auth: JWT required.

Example

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

Response (200 OK)

{
  "result": true,
  "workspaces": [
    {
      "id": "1234567890123456789",
      "name": "Engineering Team",
      "folder_name": "engineering",
      "description": "Main engineering workspace",
      "accent_color": "#0066CC",
      "logo": "https://assets.fast.io/1234567890123456789/logo.png",
      "closed": false,
      "archived": false,
      "perm_join": "Member or above",
      "perm_member_manage": "Admin or above",
      "created": "2023-01-15 10:30:00 UTC",
      "updated": "2024-01-20 14:45:00 UTC",
      "user_status": "joined",
      "org_domain": "acme-corp"
    }
  ]
}

Response Fields

Spans all organizations the user belongs to. Workspaces from orgs without active subscriptions are filtered out.

List Available Workspaces

Auth: JWT required.

Example

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

Response: Same structure as List All Workspaces, but only includes un-joined workspaces.

Check Workspace Name

Auth: JWT required. Org membership (Member or above) required. 2FA required.

Path Parameters

Example

curl -X GET "https://api.fast.io/current/workspaces/check/name/engineering/" \
  -H "Authorization: Bearer {jwt_token}"

Response — Name Available (202 Accepted)

{
  "result": true
}

Error Responses

Checks globally across all workspaces, not just the current org. Returns 202 Accepted (not 200 OK) when the name is available.

List Workspaces in Org

Auth: JWT required.

Path Parameters

Query Parameters

Example

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

Response (200 OK)

{
  "result": true,
  "workspaces": [
    {
      "id": "1234567890123456789",
      "folder_name": "engineering",
      "name": "Engineering Team",
      "description": "Main project workspace"
    }
  ],
  "pagination": {
    "total": 5,
    "limit": 50,
    "offset": 0,
    "has_more": false
  }
}

Access Levels

Cloud Import

Enable Cloud Import

Auth: JWT required. Admin or Owner required. Requires the cloud import billing feature.

Path Parameters

Example

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/cloud-import/enable/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "message": "Cloud import features enabled",
  "cloud_import": true
}

Error Responses

Disable Cloud Import

Auth: JWT required. Admin or Owner required. Requires the cloud import billing feature.

Path Parameters

Example

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/cloud-import/disable/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "message": "Cloud import features disabled",
  "cloud_import": false
}

Error Responses

Provision Provider Identity

Google Drive and Box — provisioned in the background. The endpoint returns immediately with status: "provisioning". Poll the identity detail or list endpoint until status is "active" (success) or "error" (failure). The identity_email field is "provisioning-pending" while provisioning is in progress, and the instructions returned at provision time say so rather than naming an address that does not exist yet. Re-fetch the identity after it activates to get the real identity_email; the sharing instruction text is a provision-time field and is not repeated on the identity response. When you share the remote folder with that address, grant a level that can WRITE if the source will be read_write — for Box that is Editor, not Viewer. Nothing verifies the granted level at connect time: the provider is the only thing that ever checks it, and it does so at transfer time, so a read-only grant connects, activates and syncs normally and then fails the source's first write-back permanently.

Dropbox and OneDrive for Business — connected by the user, in a browser. Nothing is provisioned in the background for these. The response carries status: "provisioning" plus an authorize_url, and the identity becomes "active" only once the user completes the consent screen and your app posts the result back — see Complete a Browser OAuth Connect below. There is no address to share a folder with, because the connected account IS the access: identity_email holds a placeholder (dropbox-oauth-pending / onedrive-oauth-pending) until the connect finishes, and is then the real account address. Each user connects their own account, so one workspace can hold several independent connections to the same provider.

An identity in error or revoked state can be re-provisioned. A provisioning OAuth identity is returned as-is, without a fresh authorize_url, while its consent could still be live — so a user who abandoned the browser tab cannot immediately retry. That row is reclaimable: provision it again after about 30 minutes and a new authorize_url is issued, or revoke it and provision to recover sooner.

Auth: JWT required. The identity is owned by the caller, and the floor depends on the provider: OneDrive for Business requires Member, because the resulting delegated grant is only ever useful for creating a source, which itself requires Member. Google Drive, Box and Dropbox accept any workspace member with view access.

Request Body (form-encoded)

Response (200 OK)

{
  "result": true,
  "identity": {
    "id": "abc123...",
    "profile_id": "1234567890123456789",
    "provider": "google_drive",
    "identity_email": "provisioning-pending",
    "status": "provisioning",
    "created": "2026-07-23 16:37:29 UTC",
    "updated": "2026-07-23 16:37:29 UTC"
  },
  "instructions": "This connection is still being set up. Once it reports as active, read the connection to get the address to share your folder with."
}

Error Responses

Complete a Browser OAuth Connect

After the user consents, the provider redirects the browser to a route on the app origin — https://go.{host}/imports/oauth/{provider}/callback — which is a front-end route, not an API one. That route reads code and state out of its own URL and posts them here, on the signed-in user's session. Both providers work exactly this way; there is deliberately no public callback endpoint for either, and the previous Dropbox one (GET /current/imports/oauth/dropbox/callback/) has been removed.

The session is what binds the flow to a person. A state token identifies the connection, not the human holding it, so an authorize_url that gets forwarded to a colleague would otherwise attach their cloud account to your identity — whose owner could then read, and on a read_write source write, their files. Requiring the completion to arrive on the originating user's session closes that: anyone else gets 1680 (Access Denied).

Post the decline, too. When the user refuses consent the provider sends back an error instead of a code; post { "state": …, "error": … } so the identity is marked. Without it the identity sits provisioning with nothing coming to finish it.

Authentication is checked before the state is consumed, so a session that lapsed during a slow consent returns 401 with both the state and the code still redeemable — refresh the session and post the same pair once more. State tokens are single-use and short-lived (about ten minutes, matched to the provider's own code lifetime); a replayed, expired, tampered or unknown one is rejected.

Auth: JWT required. The caller must BE the user who started the connection.

Request Body (JSON)

Response (200 OK)

{
  "result": true,
  "identity": {
    "id": "abc123...",
    "profile_id": "1234567890123456789",
    "provider": "onedrive_business",
    "identity_email": "casey@contoso.com",
    "status": "active",
    "created": "2026-08-09 16:37:29 UTC",
    "updated": "2026-08-09 16:38:04 UTC"
  },
  "connected": true,
  "connect_error_code": null
}

connected and connect_error_code report the outcome directly, so the result does not have to be discovered by polling the identity afterwards.

Request faults — a bad state, the wrong caller, an unknown identity — are ordinary 4xx errors, not a connect_error_code.

Error Responses

A completion that arrives for an identity already active is treated as success and returns the identity rather than an error — a double-posted callback is safe.

Revoke Provider Identity

Auth: JWT required. Admin or Owner required.

Response (200 OK)

{
  "result": true,
  "identity": {
    "id": "abc123...",
    "profile_id": "1234567890123456789",
    "provider": "google_drive",
    "identity_email": "import-sa@project.iam.gserviceaccount.com",
    "status": "revoking",
    "created": "2026-07-23 12:00:00 UTC",
    "updated": "2026-07-23 16:37:29 UTC"
  }
}

Error Responses

Identity Statuses

List Identity Drives

A OneDrive for Business identity is one connected Microsoft work or school account, and that account can usually reach several libraries with no meaningful default among them. Which library an import uses is therefore a per-source choice, made from this catalog and fixed when the source is created.

This endpoint answers from stored rows and never contacts the provider. To rebuild the catalog, call the refresh endpoint below.

Auth: JWT required. The identity owner only — for OneDrive there is no workspace-admin override, because this catalog enumerates one person's own Microsoft content. Admins keep every removal power (revoke the identity, disconnect or delete a source); what they cannot do is browse it. The other three providers' catalogs are a workspace-level service account or a shared folder, so those stay owner-or-admin.

Query Parameters

Response (200 OK)

{
  "result": true,
  "identity_id": "abc123...",
  "provider": "onedrive_business",
  "drives": [
    {
      "drive_id": "b!X9tKqL3mEkO7nQfR2sVwYzA1bCdEfGhIjKlMnOpQrStUvWxYz0123456789AbCdEf",
      "drive_type": "documentLibrary",
      "name": "Documents",
      "site_name": "Marketing",
      "web_url": "https://contoso.sharepoint.com/sites/Marketing/Shared%20Documents",
      "is_default": false,
      "site_path": null
    }
  ],
  "drives_state": "ready",
  "drives_refreshed_at": "2026-08-03 16:42:11 UTC",
  "drives_error": null,
  "requires_site_path": false,
  "site_path": null,
  "pagination": { "limit": 50, "offset": 0, "total": 1 }
}

site_name is worth rendering: nearly every SharePoint site has a library called “Documents”, so the library name alone is often ambiguous.

Branch on drives_state, not on the length of drives. An empty catalog is the NORMAL state on a first connection — nothing is enumerated until a refresh is asked for — so drives: [] on its own cannot say whether nobody has looked yet, an enumeration is running, access was refused, or the account genuinely reaches no libraries.

requires_site_path is not a permission error. There is no Microsoft API that lists every site a signed-in user can reach — only a search that is permission-trimmed and not guaranteed exhaustive. The state means “we cannot prove this list is complete, and it is empty; name a site and we will look there”. It is raised only when nothing was refused, so it is genuinely distinct from permission_denied, which is always a refusal of something specific and is not fixed by supplying a path. A scoped refresh never produces it.

requires_site_path is a convenience alias of drives_state === "requires_site_path".

A partial consent is not an error. If the user grants access to their files but withholds the SharePoint permission, the connection succeeds and the identity becomes active — the catalog simply covers their own OneDrive and no site libraries. Treat that as a working connection with a smaller catalog, not a failed one.

drives_error is normally null on success, with ONE exception: a ready catalog that was cut off at an internal ceiling carries a truncation note. Those libraries are real and selectable — the list is merely incomplete — so show it as a warning beside a usable list rather than as a failure.

Note that ready and empty are derived from the rows returned in the same response, so the state and the list can never disagree. The other five describe how the last enumeration ENDED and are reported as recorded.

Error Responses

Refresh Identity Drives

Asynchronous, and it returns no job id. The response comes back immediately with drives_state: "refreshing"; poll GET .../drives/ until the state leaves refreshing. The state is recorded before the work is queued, so a client that reloads mid-refresh still sees refreshing on a cold read.

One refresh at a time per identity: a second call while one is genuinely in flight is rejected. That block expires on its own, so an interrupted refresh cannot lock the catalog permanently.

A refresh scoped with site_path replaces only the libraries belonging to that site and leaves the rest of the catalog alone, so an account whose sites have to be named one at a time can build its catalog across several calls. An unscoped refresh looks at the connected account's own OneDrive first, then the SharePoint sites it can find; it replaces only what it actually covered, so a run that found no sites does not delete the site libraries an earlier scoped refresh recorded.

An enumeration that fails part-way — a provider outage rather than a denial — leaves the previous catalog in place rather than replacing it with a partial one.

Auth: JWT required. The identity owner only — same rule as the list endpoint above, and for the same reason.

Request Body (optional)

{ "site_path": "contoso.sharepoint.com:/sites/Marketing" }

Response (200 OK)

{
  "result": true,
  "identity_id": "abc123...",
  "provider": "onedrive_business",
  "drives_state": "refreshing",
  "drives_refreshed_at": "2026-08-03 16:40:02 UTC",
  "requires_site_path": false,
  "site_path": null,
  "message": "Drive refresh started. Poll GET .../identities/param/abc123.../drives/ until drives_state leaves \"refreshing\"."
}

drives_refreshed_at is the PREVIOUS refresh's timestamp — this one has not finished — or null if none has ever completed. Use drives_state to detect a never-refreshed identity, not a null timestamp.

Error Responses

Selecting a Drive on a Source

drive_id is required when creating or discovering against a OneDrive for Business identity, and is not accepted for any other provider.

• Discover (POST .../sources/discover/) takes drive_id so the folders it returns come from the library the user actually chose.
• Create (POST .../sources/create/) takes the same drive_id. It is validated against that identity's own catalog, so a caller cannot reach a library it was never granted by supplying an arbitrary id. The library's type, name and site name are recorded from the stored row, never from the request.
• Update (POST /current/imports/details/{source_id}/update/) rejects drive_id. The library is part of what the source IS: repointing an existing source would make the recorded origin of every file it has already imported wrong. Create a second source instead.

Pass drive_id exactly as the drives endpoint returned it — it is an opaque provider string, not a Fastio id, and must not be reformatted or validated client-side.

Who may do this. Creating a source is restricted to the identity owner for every provider, with no workspace-admin override: only the person whose cloud account is connected may graft its folders into a workspace, and they must hold Member on that workspace. For OneDrive for Business, discovery is owner-only as well — it browses that person's own Microsoft content. Admins are refused here on purpose, and keep every removal power: revoking an identity, and disconnecting or deleting a source, remain owner-or-admin.

Browsing Below the Provider Root

POST .../sources/discover/ accepts an optional remote_path: the remote folder to enumerate. Omit it — or send an empty string, or null — to enumerate the provider root, which is the historical behaviour and stays the default.

Discovery returns folders only, one level down. It does not walk the tree: a client expands a level at a time, passing the folder it wants to open back as remote_path on the next call. The response shape, the job id, and the polling endpoint are unchanged.

Two paths are two different questions, and they do not collide. A discovery already in flight blocks only another discovery of the same workspace, provider, drive and path — so /Clients and /Clients/Northwind can be browsed at the same time, while asking the same question twice is still deduplicated into the first.

Only the length is checked when the call is accepted. A path the provider cannot resolve is reported by the discovery job, not by this endpoint: the call returns 200 with a job id, and that job finishes failed with the reason in its error_message. Check the job, not just the HTTP status.

remote_path is also an input on POST .../sources/create/, where it names the remote folder the source imports. On discover it names the folder to browse; the two are separate calls and neither implies the other.

Choosing Where an Import Lands

POST .../sources/create/ accepts an optional destination_node_id: the workspace storage folder the source's imported folder is created under. Omit it — or send an empty string, or null — and the import lands in the Imports system folder at the storage root, which is the historical placement and unchanged for every existing caller. A client that always sends the key can therefore leave it null here — but not on the update endpoint below, which rejects the key whatever its value.

Pass the node id exactly as a storage endpoint returned it; the formatted (dashed) form is accepted.

• The node must exist in this workspace and must be a folder. It is resolved against this workspace's own storage, so an id from another workspace is simply not found here.
• Create-time only. POST /current/imports/details/{source_id}/update/ rejects destination_node_id, on the key's presence rather than its value, and rejects it before applying any other field — a request carrying both a destination change and a legitimate one applies neither. Repointing a live source would leave every file it has already imported recorded against a location it is no longer in. The imported folder itself stays freely movable: move it in the workspace instead, and the sync follows it.
• The source object carries the choice and its outcome — see Reading the destination back below. root_node_id names the folder the import actually created, and is populated once the first sync has run.
• If the chosen folder has been trashed or deleted by the time the first sync runs, the import lands in the default Imports folder rather than failing, and the source records destination_fallback_at. A degraded placement is visible and fixable; a failed first sync looks like a broken import.
• An import's folder may not be created inside another import. A destination that is itself part of an import — an import's own folder, or anything beneath it — is rejected at create, with reason destination_nested, before any source exists. Choose a folder outside every existing import. (Relatedly, POST /current/workspace/{workspace_id}/storage/{node_id}/move/ refuses to move a cloud-import folder inside another one.)
• A destination the server could not verify is a retry, not a rejection. The nesting check walks the folder's ancestry; if that walk cannot complete, the call answers 1610 (Internal Error) with "Could not verify the chosen destination; please try again". That means undetermined, not nested — retry the same request rather than sending the user back to pick a different folder.

Reading the destination back. Every source object — from create, list, and details alike — carries two top-level fields, alongside drive_id. Both are also present inside properties.

Read them as a pair. destination_node_id on its own is the folder the user asked for, and it reads as a successful placement — which is exactly the wrong conclusion when the import actually fell back. A non-null destination_fallback_at beside it means "you asked for that folder, you got the default, at this time". A client that renders only the first will tell the user their choice was honoured when it was not.

destination_fallback_at describes placement at graft time, not current location. The imported folder is freely movable afterwards, so treat it as a record of what happened when the import landed, not as a live assertion about where it is now. It is written once and never cleared.

A destination that does not resolve is deliberately indistinguishable from one that is not yours. A malformed id, a node that does not exist, a trashed node, and a node in another workspace all answer with the same message, the same code and the same reason — "The chosen destination folder was not found in this workspace" — so the endpoint cannot be used to probe which node ids exist elsewhere. Only "the node is a file, not a folder" answers differently, and that branch is reachable only for a node the caller can already list.

Every 1605 rejection above is field-scoped: the response carries a detail naming destination_node_id, with kind: "invalid", the human message, a support code, and the stable reason. Branch on reason, never on the message text. The 1610 case is the one exception — it is a plain error with no field detail and no reason, because it reports that the destination could not be evaluated, not that it was bad. For that branch alone the numeric code 138825 is the discriminator, and it is contract-stable — it will not be merged into another call site. Treat it as retry the same request, never as pick a different folder.