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

Workflow

Task Lists (Workflow)

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 400. 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/workflow 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, workflow_permissions). 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.

Summary Enrichment Setting

Workflow obligations carry a deterministic, no-AI display_summary. A workspace can additionally opt in to AI summary enrichment, which augments an obligation's display with an LLM-derived structured-extraction object (nl_enrichment) when an extraction schema is configured on the workflow. The enrichment is off by default and is governed by two workspace settings:

• nl_summaries_enabled (boolean, default true) — the master switch. When false, no AI enrichment runs and obligations expose only the deterministic display_summary. Setting it to true requires the plan's AI features (content_ai).
• nl_summaries_daily_cap (integer, default 100, range 0–100000) — a per-workspace ceiling on the number of AI enrichment operations per day. 0 disables enrichment without flipping the master switch.

Both settings are Admin-or-Owner only. They are returned on GET /current/workspace/{id}/details/ and set on POST /current/workspace/{id}/update/. The enrichment itself is surfaced on the obligation read surface as a separate top-level nl_enrichment object — see the Workflow reference for its shape and trust class.

Workspace CRUD

Create Workspace

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

Path Parameters

Request Parameters

Implicit defaults on create: A new workspace comes with workflow_approval_native_enabled = "extended" by default (in-place approval + external reviewers available out of the box). This is not a create parameter — you cannot set it on this endpoint. To change the tier after creation, use the update endpoint (POST /current/workspace/{workspace_id}/update/); see the Update Workspace section.

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_enabled": true,
    "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. Pending members are placeholders that allow teams to pre-assign workflow items before the invitee signs up.

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
}

Workflow assignments: Pending members can be assigned to tasks before they create an account. Their user ID is valid and works with all assignment endpoints.

Account claim: When the invited user signs up or accepts the invitation with an existing account, their status transitions from "pending" to "active". All existing workflow assignments (such as tasks) are preserved and transfer automatically.

Removal: To remove a pending member, delete their invitation using the invitation endpoints (see Workspace Invitations below). Deleting the invitation removes the pending member and unassigns any workflow items associated with them.

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

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

Workflow

Enable Workflow

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

Path Parameters

Example

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

Response (200 OK)

{
  "result": true,
  "message": "Workflow features enabled",
  "workflow": true
}

Error Responses

Disable Workflow

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

Path Parameters

Example

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

Response (200 OK)

{
  "result": true,
  "message": "Workflow features disabled",
  "workflow": false
}

Error Responses

Task Lists

Task lists are a workflow feature. Workflow must be enabled on the workspace before using these endpoints. All task list endpoints support Accept: text/markdown for markdown-formatted output.

List Task Lists

Auth: JWT required. View or above. Requires the workflow billing feature.

Path Parameters

Query Parameters

Headers

Example

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

Response (200 OK)

{
  "result": true,
  "task_lists": [
    {
      "id": "abc123opaque",
      "profile_id": "1234567890123456789",
      "name": "Sprint Backlog",
      "description": "Current sprint items",
      "created_by": "9876543210987654321",
      "properties": {},
      "sort_order": 0,
      "created": "2026-01-15 10:30:00 UTC",
      "updated": "2026-01-20 14:45:00 UTC",
      "deleted": null
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 1
  }
}

Response Fields

Error Responses

Create Task List

Auth: JWT required. View or above. Requires the workflow billing feature.

Path Parameters

Request Body (JSON)

Example

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/tasks/create/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sprint Backlog", "description": "Current sprint items"}'

Response (200 OK)

{
  "result": true,
  "task_list": {
    "id": "abc123opaque",
    "profile_id": "1234567890123456789",
    "name": "Sprint Backlog",
    "description": "Current sprint items",
    "created_by": "9876543210987654321",
    "properties": {},
    "sort_order": 0,
    "created": "2026-01-15 10:30:00 UTC",
    "updated": "2026-01-15 10:30:00 UTC",
    "deleted": null
  }
}

Error Responses

Reorder Task Lists

Auth: JWT required. View or above. Requires the workflow billing feature.

Path Parameters

Request Body (JSON)

Example

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/tasks/reorder/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{"order": [{"id": "abc123", "sort_order": 0}, {"id": "def456", "sort_order": 1}]}'

Response (200 OK)

{
  "result": true,
  "reordered": 2,
  "profile_id": "1234567890123456789"
}

Error Responses

Workflow-Native Sign-off & Checklists

For human sign-off use the workflow approval step and the native review surface; for checklist items use the workflow todo step (both in the workflow orchestration tool). The Tasks API (task lists & tasks) is the supported task-tracking surface. See the Workflow reference for these surfaces.