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 Sync

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 and metadata_extraction 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 update endpoint rejects the 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.
• On by default at creation. POST /current/org/{org_id}/create/workspace/ enables intelligence unless you send intelligence=false; omitting the field means on, and is not an error. On a plan that lacks either content_ai or ai_agent the new workspace is created with intelligence off whatever you send, because the indexing pipeline has no consumer there — creation still succeeds rather than being rejected.
• Change it 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.

Automatic Metadata Extraction Setting

The metadata_extraction boolean on a workspace controls whether automatic metadata extraction runs for newly uploaded files. It is an opt-out layered under the intelligence setting and the plan: automatic extraction runs only when intelligence is on, the plan includes the metadata feature (capabilities.can_use_metadata), and metadata_extraction is not false. It can withhold extraction; it can never enable it where the intelligence setting or the plan does not allow it.

• On by default. Every workspace reports metadata_extraction: true unless it was explicitly switched off — including workspaces created before the setting existed. POST /current/org/{org_id}/create/workspace/ accepts metadata_extraction=false to create it off; omitting the field means on.
• Change it later: POST /current/workspace/{id}/update/ with metadata_extraction=true|false. No plan requirement: setting it on a plan without the metadata feature is accepted and has no effect. Unlike intelligence it is not rate-limited.
• Turning it off stops automatic extraction for files that reach processing from then on. The setting is read when a file is processed after upload, not at the moment the upload is accepted, so a file already being processed may still be extracted and an extraction already queued is not cancelled. Nothing is deleted: existing metadata values, fields, views and filters stay readable and editable, metadata search keeps working, and explicit per-file or per-folder extraction requests (POST .../storage/{node_id}/metadata/extract/, .../extract-all/) still run — the switch governs only what happens on its own at upload time.
• Turning it back on does not extract files uploaded while it was off; only new uploads are picked up. Use the explicit extraction endpoints to catch existing files up.
• Read it back as the boolean metadata_extraction on the workspace object at the standard output level and above (same level as intelligence).

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"

Response (200 OK)

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

Response Fields

Access Levels

Error Responses

Reading the error tables: the four-digit 16xx/17xx values below are HTTP-status classes, not error.code. The error.code a client actually receives is assigned per endpoint, so use the HTTP status as the gate and a documented error.code — five or six digits, plus the 9661-9669 family — only as a refinement. A 16xx value identifies the status class — useful for telling which kind of failure occurred — but comparing one against error.code will never match. Five- and six-digit codes (and the 9661-9669 family) are real error.code values. If you widen a check from a specific code to a status, widen what you assert with it — a status covers failures the narrower code did not, so a message written for that one code becomes a confident falsehood on the rest.

Get 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=2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4" \
  -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": "2ltsuq4mjacuv7pgc5ydlxnsjwee4",
    "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": "2ltsuq4mjacuv7pgc5ydlxnsjwee4",
      "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) Parameters

Where to send them differs by method. On POST, send them as a form-encoded request body (they are also accepted on the query string). On DELETE, send them as query-string parameters — a request body is not read on this DELETE, so a form-encoded DELETE body is silently ignored and the request fails as though you had supplied neither user nor email.

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

A workspace is listed when either the caller is a direct member of it, or the caller is an org member whose org permission level satisfies that workspace's join permission (perm_join). These are alternatives, not requirements, so the list contains both the workspaces the caller has joined and the ones they are entitled to join. Users who are not org members see only workspaces where they are a direct member.

Each row reports the caller's own standing in workspace_level (owner, admin, member, guest, viewer, none) at the standard and full output levels; ?output=terse omits it. A row the caller can see but has not joined reports none. Read this field to determine membership — do not infer it by subtracting /current/workspaces/available/ from this list. When the caller's level cannot be determined, workspace_level is omitted rather than reported as none, so none always means an authoritative "not a member".

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

No role sees a workspace set to No one can join automatically unless they are a direct member of it, and an admin does not see a Only Org Owners workspace unless they are a direct member. A removed or expired org membership confers no visibility.

Cloud Sync

Enable Cloud Sync

Auth: JWT required. Admin or Owner required. Requires the cloud sync 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 Sync

Auth: JWT required. Admin or Owner required. Requires the cloud sync 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

When the Plan Stops Including Cloud Sync

A workspace whose plan no longer includes cloud sync keeps everything it has already imported. Its sources move to suspended_plan at their next scheduled check: the imported files, the import folder and the link to the remote folder are all kept, and only scheduling stops — nothing syncs in and nothing writes back while a source sits there.

Nothing has to be repaired. A source in suspended_plan resumes on its own at the next check once the workspace is back on a plan that includes cloud sync; there is no call to make and no reconnect to redo.

Read it as its own state rather than as an idle healthy source: it is reported in the source's status like any other value, and a source that has stopped syncing because of the plan looks identical to a quiet one in every other field.

A Plan With No Cloud Connections Refuses at the Door

Some plans include cloud sync as a feature but allow no cloud connections at all. On those plans the whole connect flow is refused up front — the providers listing, identities/provision/, and the OAuth completion endpoint all answer:

This is a settled answer, and the fix is an upgrade rather than a retry. It is deliberately raised before an identity is created and before a consent screen is shown, so a user is never asked to hand a cloud credential to an account that could not use it. On the OAuth completion it is raised before the authorization code is redeemed, so a plan that lapsed while the consent screen was open leaves nothing stranded at the provider — start again from provision after upgrading.

Do not confuse it with 134248 → 503 on the same endpoints, which means the plan could not be determined right now and is worth retrying shortly. Gate on the HTTP status first: 412 is the plan answer, 503 is "ask again".

Provision Provider Identity

Every provider — connected by the user, in a browser. 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. Nothing is provisioned in the background and there is no address to share a folder with. Google Drive and Box previously created a robot account inside Fastio's own Google and Box tenants; that model has been removed entirely.

Provisioning requires workspace Member on every provider. A Viewer is refused: the resulting grant is only ever usable by someone who can create a source, so issuing one to a Viewer would mint a live credential its owner could never use.

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.

Such an identity carries properties.oauth_pending: true, and that marker is part of this contract — it is set by every provider, it is visible to non-owner callers, and it is cleared when the connect completes. It exists so a client can tell "waiting for a person to finish a consent screen" apart from "the server is still working", which otherwise look identical: both report status: "provisioning".

Read it together with authorize_url — authorize_url is issued only on the provision response and never appears when polling the identity afterwards. So provisioning + oauth_pending: true + no authorize_url is terminal by construction: no amount of polling will produce a link, and the connection must be restarted rather than waited on.

Auth: JWT required. The identity is owned by the caller, and the floor is Member on every one of the four providers — there is no per-provider carve-out, and a Viewer who could connect before is refused now. See Provisioning requires workspace Member above.

Request Body (JSON)

Send Content-Type: application/json. This endpoint parses a JSON body and rejects a form-encoded one with 127872 Invalid JSON in request body.

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"
  },
  "authorize_url": "https://accounts.google.com/o/oauth2/v2/auth?...",
  "instructions": "Open the authorization link to sign in and connect your own account."
}

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. All four providers work exactly this way; there is deliberately no public callback endpoint for any of them, and the previous Dropbox one (GET /current/cloudsync/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

Three outcomes, and the MESSAGE tells them apart — the numeric code alone does not. The 404 is settled: the identity is genuinely gone, and reposting the same code and state cannot bring it back — start again from provision. A 1664 reading “Failed to load the connection being completed.” happens before the authorization is redeemed: the grant is still good and the code is unspent, so post the same code and state again. A 1664 reading “The connection could not be verified after authorization; start a new connection.” happens after the authorization has already been redeemed — the code is spent and reposting it will fail, so start again from provision. Reposting a spent authorization does not just fail; it marks the pending connection as failed, which is worse than doing nothing.

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": "member@example.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 identity is one connected Microsoft account — work or school, or personal. A work or school account can usually reach several libraries with no meaningful default among them; a personal account has exactly one drive and no SharePoint. 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 — on every provider. Every catalog enumerates the connecting person's own cloud account, so a workspace admin browsing one would be reading that member's personal account; there is no admin override on any of the four. Admins keep every removal power (revoke the identity, disconnect or delete a source); what they cannot do is browse it. The same gate covers the discovery RESULT — polling a discovery job returns the folder listing, so it is owner-only too.

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/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/cloudsync/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.

Search indexing in that same view. The upsert_file entry of GET /current/workspace/{workspace_id}/jobs/status/ is an object (or null) carrying active, status (queued · processing · completed · failed), node_id, node_name, file_count, processed_count, failed_count, current_file, current_file_units_indexed, current_file_units_total, progress_percent, started_at, updated_at and completed_at. The two current_file_units_* fields are WITHIN-FILE progress in the units the indexer measured that file in (pages, for a document): a large document is ONE file indexed over several passes, so those two move while processed_count and progress_percent stand still. Both are always present and are null when nothing was measured and once the file is finished or failed. See the AI & Chat reference for the full field table and an example.

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 Dropbox and OneDrive for Business, discovery is owner-only as well — it browses that person's own cloud account. 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.

If the same scope was tried recently and failed, and is still within its short retry window, the call answers 503 ("A recent discovery for this folder has not finished retrying. Try again shortly.") rather than 200. This is distinct from the in-flight case above — no job is currently running to hand back — and it is a normal, expected retry signal: wait briefly and call discover again.

The shape of the path is checked before the call is accepted; whether the folder exists is not. Characters, directory traversal and the length limits below are all applied synchronously, so a malformed remote_path comes back as 1605 straight away. Only the provider-side question — does this folder exist, and can it be listed — is deferred: that is reported by the discovery job, not by this endpoint, so 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.

Some folders exist in a cloud account but cannot be listed at all. When discovery can confirm one of these on a root listing, it leaves it out of the results rather than offering a dead end — OneDrive's "Personal Vault" is the known case. That check is best-effort, so an unconfirmed unlistable folder can still be offered like any other. Either way — offered and then chosen, or named directly with remote_path — the discovery job for that folder fails immediately, without retrying, and its error_message says the provider refused to list it. Such a folder cannot be imported. On Google Drive, a shortcut whose target has since been deleted is omitted from listings the same way.

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.

What remote_path accepts, on BOTH calls. The two endpoints apply the same rule, so the picker can never offer a folder that create then refuses. A remote_path may be any name the provider can hold — Sales & Marketing, John's Files, Q3 Reports (Final), #general, 100% Done, emoji, and any script, in either Unicode normal form — except the characters providers themselves reject: *, ?, |, <, >, the null byte, and control characters. Directory traversal (.. as a whole component, in either slash direction) is refused. Length limits are 2048 characters overall, 4096 bytes overall, and 255 bytes for a single path component.

It is stored exactly as sent, including leading and trailing spaces. remote_path is an address, not a label: providers permit edge whitespace in a folder name, so trimming it would name a different folder than the one the listing offered. Post back the remote_path a discovery entry gave you, byte for byte. A value that is only whitespace counts as not given — on discover that enumerates the provider root, and on create it is refused as a missing field. remote_name, which is a display label rather than an address, is still trimmed.

Choosing Where an Import Lands

Two concurrent POST .../sources/create/ calls for the same workspace can briefly collide. If another source-creation request for this workspace is still in progress, the call answers 503 rather than creating a source or naming a field problem — wait briefly and send the same request again.

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/cloudsync/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-sync 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.

Linking to the Folder at the Provider

Every source object — from create, list, details and update alike — carries remote_folder_web_url: a browser link to the folder the source mirrors, at the provider.

Null means exactly one thing: no valid stored ID-to-URL mapping can be built. Treat it as do not render the affordance — never as a broken or unhealthy source. Several unrelated situations produce it, and the field deliberately does not distinguish them, because none of them is something a user can act on:

• no folder id is stored yet. A source acquires one on a sync, so this covers a source created before the field existed until a later sync records one — it is not limited to sources that have never synced, and an existing source can gain a link without anything being done to it;
• the provider was found to publish no id for the folder at all, and the source is recorded as such;
• the provider publishes an id but has no public URL form that addresses a folder by it. Dropbox and OneDrive for Business are both in this category today and always answer null. Google Drive and Box return a link;
• the stored id does not have the shape that provider's ids have, so no URL is built from it rather than one that would not resolve;
• the connected account behind the source could not be read, so the provider is unknown and the id cannot be attributed to any URL form.

The link is built from the folder's id, never from remote_path. That is what makes it survive the folder being renamed or moved at the provider — a path-derived link would quietly open the wrong folder afterwards, which is worse than opening none. For the same reason, do not build your own provider URL out of remote_path: if this field is null, there is no link to show.

Do not parse the URL, and do not assume its shape is stable per provider. It is for opening, not for extracting ids from.

Recognising a Folder That Was Renamed or Moved

POST .../sources/discover/ returns one entry per folder, and each entry carries an already_imported flag. Compute nothing yourself: the flag needs every source on the identity, which the discovery response does not carry and the caller may not be entitled to enumerate. An absent flag does not read as unknown, it reads as false, and the picker then offers a folder that is already connected.

already_imported follows the folder, not the path. Two keys are checked and a match on EITHER sets the flag — it is not an id check with a path check behind it. An entry is already imported when its remote_id matches the folder id of a source on the same drive, or when its remote_path matches a source's remote path. Both are proof, and neither absence disproves the other: a source that has an id can still be matched by path, and an entry whose remote_id is "" must still be matched by path. An empty value never matches an empty value on either key.

Renaming or moving a connected folder at the provider therefore keeps it marked as already imported, at its new path — which it previously did not, and a second source for the same folder could be created as a result.

The id key is scoped to the drive being listed; the path key is not. Provider item ids are unique within a drive rather than across drives, so an id is only compared against sources on the same drive — otherwise a folder in one library could be reported as already imported because an unrelated folder in another library happens to share its id, and you would be blocked from importing a folder you never imported. The path key is unscoped, which is long-standing behaviour: the same path on two libraries can mark each other as already imported even though sources/create would accept the second one.

Sources with no recorded id — everything created before the id existed, and everything on a provider that publishes none — are still matched by path exactly as before. Nothing that used to be recognised stopped being recognised.

Pass remote_id back when you create a source.

It is optional and advisory: it can only make POST .../sources/create/ refuse a duplicate it would otherwise have admitted, never the other way round. Sending it lets the duplicate check recognise a folder that has been renamed or moved since it was connected — the case a path comparison alone cannot see. Omitting it leaves the check exactly as strict as it was, and sending one that matches nothing does not weaken the path check: the two keys are OR-ed there too, so a wrong value cannot be used to slip a duplicate past the refusal. The id is only compared against sources on the same drive, as on discovery — but the two are not otherwise identical: this endpoint scopes its path key to the drive as well, while discovery's path key is unscoped. So the same path in two libraries can read as already imported in a discovery response and still be accepted here. This endpoint is the authority on what is actually refused.

The value is not stored on the source and is not what the source is identified by. The server records the folder's id itself, from the provider, on the first sync.

A folder this workspace has already connected is refused. Two sources for one remote folder would each mirror it and each write back into it. Disconnected sources do not reserve their folder, so reconnecting a folder you previously removed keeps working. The same folder connected on a different drive is a different folder and is not refused.

The refusal spans the whole workspace, scoped to the connected cloud account. Each workspace member who connects a provider gets their own connection, so two members can be looking at the same cloud account through two of them. A folder one member has already connected is refused for the other, because it is one folder and two sources would each mirror and write back into it. Two different cloud accounts are not compared: if two members connect two separate Dropbox accounts, each may connect its own /Photos — those are different folders that happen to share a name.

Disconnecting a Source

POST /current/cloudsync/details/{source_id}/disconnect/ ends a source's sync relationship permanently. Owner-or-admin: the member who owns the connected cloud account, or a workspace admin.

Neither action changes any FILE in the connected cloud account. Disconnecting ends the connection and delete trashes the workspace copies only. Nothing in the connected account's contents is added, changed or removed either way. Change notifications are registered per connected cloud ACCOUNT, not per folder — one registration serves every folder connected from that account, so disconnecting one folder does not tear it down, and the account's other connected folders keep receiving changes. The disconnected source simply stops: it reads disconnected, and nothing syncs or writes back for it again.

Response (200 OK)

A source of 1000 files or fewer is disconnected before the call returns:

{
  "result": true,
  "status": "disconnected",
  "message": "Source has been disconnected successfully.",
  "action": "delete",
  "data_deleted": true
}

data_deleted is null on keep and true on delete. It is never false. A delete that did not happen is an error response — the endpoint does not answer 200 and then report in a field that it changed nothing.

A source with more than 1000 files disconnects in the background instead, answering status: "disconnecting" with a message and no action or data_deleted. Poll the source until it leaves disconnecting.

delete is REFUSED rather than guessing. The imported folder is checked in full before anything moves, and the delete is refused unless every item in it is proven to be this source's own import. How that refusal reaches you depends on which path ran. On a source of 1000 files or fewer the request itself is refused with 403 — nothing changes and the source is left connected exactly as the call found it, so the cause can be fixed and the same request sent again. On a source of more than 1000 files the call has already answered 200 with disconnecting, so the same refusal surfaces on the source instead: it parks at disconnect_pending carrying the reason, as described below. That check is a snapshot taken before any trashing begins, so it cannot speak for content added or moved into the folder while the operation is already running; on a folder being changed concurrently, disconnect once the changes have settled.

A 403 here is settled: the same request refuses identically until the folder changes, so never put it in a retry loop. The message names the item that blocked it where it can, but the wording is advisory text for a person — branch on the status.

keep is not a universally safe fallback from a refusal. It releases every imported item in the folder, including items belonging to another connected folder — those stop being imported too, and the connection that owns them stops tracking them. It is clean for content the user added themselves, which carries no import state to release. Offer it knowing that, rather than as an automatic retry.

A disconnect that could not be carried out no longer reports success. Any unproven cleanup — a refusal, or storage that did not answer — ends the request with an error and leaves the source connected and retryable, instead of recording it as disconnected with its files still in place. Callers that treated a 200 as final can keep doing so; what changed is that the failure cases are no longer 200.

On the background path (>1000 files) the usual equivalent is disconnect_pending: the source leaves disconnecting, does not reach disconnected, carries the reason in its error_message, and neither syncs nor writes back while it sits there. Send the same disconnect again once the cause is fixed — disconnect_pending accepts a retry, and disconnected does not. That is the normal settling point rather than a guarantee: a background disconnect that cannot record its own outcome can be left in disconnecting instead, so read the source's current status rather than assuming which one it reached.

A source left in disconnecting is recoverable — send the same disconnect again. The status on its own is no longer a refusal. disconnect is accepted whenever nothing is actually working on the source, which is what an abandoned background disconnect looks like, and it starts a fresh one. It answers 503 only while a disconnect is genuinely in progress, and that answer means what it says: retry shortly. So a disconnecting source that stays that way is not stuck — retry the disconnect rather than waiting.

Confirming a Large Deletion

POST /current/cloudsync/details/{source_id}/refresh/

A sync mirrors deletions: files removed from the connected cloud folder are removed from the workspace too. A single run that would remove an unusually large share of the connected folder is stopped instead of applied — nothing is deleted, the source is left in error, and its error_message names how many files the run would have removed and how many the folder holds. Every later sync stops in the same place, because a provider that under-reports its own listing looks exactly like a folder somebody emptied, and guessing wrong destroys content.

To let it through, repeat the refresh with the confirmation:

{ "acknowledge_large_delete": true }

The field is optional and the endpoint still accepts a request with no body at all. It is owner-or-admin, like the rest of refresh/. The response shape does not change.

Five things about it are worth knowing before you build on it:

• It confirms the number the caller was shown, not "delete whatever you find". The confirmation is bound to the count recorded when the sync was stopped. If the folder has lost substantially more by the time the confirmed run measures it, that run stops again and reports the NEW count — send the refresh again to confirm that one. Small movement in between is tolerated.
• It is spent by one sync. Nothing is stored on the connection, so the next scheduled sync is bounded exactly as before. Re-send it if a later run stops again.
• It only applies to a folder that is still stopped. The confirmation is matched against the folder's most recent finished sync. If that sync completed normally, there is nothing left to confirm and the request is treated as an ordinary refresh — a folder that recovered on its own is not carrying an old confirmation forward, and a confirmation given for one stopped run can never be spent on a different one later.
• It cannot clear every stopped sync. When the run could not measure the folder completely, no exact count exists and the confirmation is ignored: the message says the deletion could not be judged rather than naming a number. Those clear when the underlying read succeeds, not by confirming.
• Confirm with a person, never automatically. This authorises deleting content from the workspace. Show the count and the folder to whoever is asking before sending it, and never wire it into a retry loop.

Source and Job Lifecycle Refusals

The source and job lifecycle endpoints — update/, refresh/, delete/ and jobs/{job_id}/cancel/ — each have a state precondition, and a request that violates one is answered 409 Conflict, never a 5xx. This is the same rule the write-back endpoints already follow, applied to the other half of the surface; these used to answer 500, which told clients to retry a request whose outcome had nothing to do with a server fault.

Gate on the HTTP status. The error.code values below are the ones actually serialized, and they identify the call site rather than the reason — several share a message, and the message is what tells the cases apart.

One row here is transient, not a refusal. sources/create/ answers 134248 → 503 when the workspace's plan could not be read at all. Nothing about the request is wrong and nothing is settled: send the same request again shortly. It is the same answer the connect endpoints give for the same condition, and it is deliberately distinct from the 412 plan limit above — gate on the HTTP status first, exactly as you would there.

update/ now refuses while a sync or disconnect owns the source, and this is a change to a shipped endpoint: pausing, resuming, renaming and changing the interval used to be accepted at any moment. They were not safe — a settings change made during a source's first sync overwrote the sync's own progress, leaving the connection wedged in a state nothing could move it out of. The two refusals answer 406, matching disconnect/, which has always refused the same way for the same reason. Both are transient: re-read the source with source-details, wait for the job to finish, and send the same request again.

None of these is answered by repeating the request immediately — but they are not all permanent. Two kinds are mixed together here, and the difference decides what a client should do:

• Settled for good. A disconnect job is never cancellable, at any status; a running job is never cancellable; a folder already connected stays connected until someone disconnects it; and a plan limit is lifted by an upgrade. Resending the same request unchanged cannot ever succeed — change the request, or change the account.
• Settled for now. delete/, refresh/ and update/ refuse because of the state the source is in at this moment — a source that is syncing or discovering will finish, and the same call is then valid. These clear on their own.

In both cases: do not tight-loop. Re-read the source with source-details (or the job) and act on the state it is actually in; where the state is one that transitions, wait for the transition rather than polling the refusing endpoint. Two rows are not a 409 at all: the plan limit answers 412, and its fix is an upgrade rather than a different request; the unreadable plan answers 503, and its fix is to send the same request again shortly.

A running sync job cannot be cancelled. Cancel applies only while the job is still pending, and it is applied as a compare-and-swap on that status — so a job that starts between reading it and cancelling it answers 409 rather than having its record rewritten. Once a sync is running it runs to completion; there is no way to stop a transfer in flight, and the previous behaviour only made the audit record say otherwise.

A disconnect job is never cancellable, at any status. Cancelling one does not stop the teardown — it removes the record that something owns it, and leaves the source stuck mid-disconnect. Wait for it to finish.

A 500 still appears on these endpoints and now means what it says: a datastore read or write failed, a profile could not be resolved, or a job could not be queued. Those are worth retrying. A state refusal is not.

Write-Back Queue

Write-back is the return direction of cloud sync. A change made to an imported file inside Fastio — an edit, a new version, a delete — is pushed back out to the folder at the provider, so the connected cloud account ends up holding the same content.

FOLDER changes propagate too, and the QUEUEING is all-or-nothing. Trashing a folder inside a read_write connected folder removes every file beneath it that this connection imported from the connected cloud account as well, not only from the workspace; restoring the folder re-uploads them, undoing the removals. Moving a folder OUT of the connected folder is treated the same way as trashing it, because those files have left the connection — the workspace keeps them as ordinary content, and the provider copies are removed. Each of these queues one write-back per imported file beneath the folder, created together: if the folder's contents cannot be listed completely, nothing at all is queued and the change stays local, which is the safe direction. That queueing pass performs no removals itself; rows it already queued carry their own jobs and complete on their own; a pass that could not queue every descendant is retried before it executes anything. What follows is not a transaction at the connected account. Once queued, each removal completes on its own and is retried until it lands, so a large folder can be briefly half-removed at the provider while the rest catch up. The folder CONVERGES rather than flipping in one step — read the write-back list if you need to know when it has settled. Files under a nested connected folder, files that were never imported, and files belonging to a different connection are left alone in every case. Restoring an earlier version of a file, and copying a file into a connected folder, also reach the provider. Tell a user this before they trash or move a folder inside a read_write connection: it reaches their own cloud account, not just this workspace.

Notes DO take part in cloud sync, in both directions. A note is Markdown — a .md node holding ordinary stored content — so it mirrors to the provider as its own .md object. A note you create or edit inside a read_write synced folder is pushed, queues a write-back like any file, and appears in the connected cloud account as a .md file; trashing one propagates the delete, and an edit made to that .md at the provider is pulled back into the note. The TYPE mapping, however, is one-way, and that is the part not to assume: a .md arriving from the provider with no matching note already in the workspace is imported as an ordinary file, never converted into a note — so the Markdown in a synced code or docs folder stays files rather than becoming collaborative notes.

A provider edit that is not valid note content is refused, and the sync stays healthy. Notes cap at 100 KB and must be markdown, so if the .md at the provider grows past that, or is replaced with something binary, the note keeps its previous content and the provider copy is left untouched. This is not a sync failure — the source does not go into error over it, and the rest of the folder keeps syncing — so a note that has quietly stopped tracking its provider file is something to look for rather than something you will be alerted to. Fix it at the provider and the next sync picks it up.

It is off by default and enabled per source: a source only writes back while its access_mode is read_write. A read_only source imports and never writes.

Most write-backs are created for you. Changing an imported file queues one automatically; there is no endpoint to call for the ordinary case. The endpoints in this section exist for the cases automation cannot settle by itself — forcing a push, retrying one that failed, deciding a conflict, and cancelling one that has not run yet.

Reading the queue is member-level; every write action is not. A push, a retry, a keep_local resolve — each of these runs the transfer under the cloud credential of the member who connected the source's identity, writing into that person's own cloud account. So the write actions require that identity's owner, or a workspace admin; anyone below that is refused with 1680 (Access Denied). Listing and reading a job need only ordinary view access to the workspace.

Timestamp format change. created, updated and remote_mtime_before are emitted as YYYY-MM-DD HH:MM:SS UTC — the same format every other datetime in this API uses. They previously omitted the  UTC suffix. A client that parses these fields with a fixed pattern must accept the suffix.

Status lifecycle

The lifecycle is pending → uploading → completed | failed | conflict | canceled.

Two of those are not the end of the story. failed returns to pending when you retry it, and conflict returns to pending when you resolve it. completed and canceled are final: no endpoint accepts a job in either state.

canceled does not only arrive from uploading. Cancelling acts directly on a pending or conflict job, and a job is also cancelled for you when the write-back route itself goes away for good — the source is flipped to read_only, disconnected or deleted, the connected identity is revoked, the member who owns it loses access to the workspace, or the workspace is closed. A canceled job you did not cancel means the route went away, not that the transfer failed.

A workspace on a temporary hold does NOT cancel its queued write-backs — they wait. A workspace or org that is locked, suspended or under review is on a hold that ends, so its queued jobs stay pending and the work is held rather than discarded. They are re-checked periodically and go out on their own once the hold is lifted; there is nothing to retry and nothing to re-queue. This is the difference between a hold and a closure: a closed workspace cancels, a suspended one waits. A job held this way can still reach its retry ceiling if the hold lasts long enough, and it then ends failed — which retry accepts, so the edit is never silently lost.

An edit made while a job is already uploading gets its own job. A queued pending job absorbs later edits to the same file, because it reads the file's current content when it runs. An uploading one cannot: the transfer has already read the content it is going to send, so a newer edit gets a fresh pending job queued behind it. Expect to see two jobs for one file in that window — one uploading and one pending — and expect the second to absorb any further edits rather than adding a third.

Do not treat conflict as an error state. It is a decision waiting on a person: both copies changed, and only the caller knows which one is right. Nothing has been overwritten at either end while a job sits there.

The write-back object

Every endpoint in this section returns this shape.

error_message is advisory text for a human. It is reduced to a safe summary before it leaves the API, its wording is not part of the contract, and it is not what a client should branch on — branch on status, and on the error responses documented below.

operation is part of a job's identity, not a detail of it. An upload and a delete for the same file are two independent jobs and neither blocks the other, so one file can legitimately have two live write-backs at once.

properties publishes only what a caller can act on. Internal transfer state is not included, so {} is the ordinary value for an automatically created job.

List Write-Back Jobs

Auth: JWT required. Any workspace member with view access; the source's owner is not required.

Path Parameters

Query Parameters

Both are clamped, never rejected: a limit above the maximum returns the maximum, and a limit of 0, a negative number, or a value that is not a number returns 1. A negative offset reads as 0. So a malformed page request returns a small page rather than an error, and a client that wants to validate its own paging must check what came back.

Response (200 OK)

{
  "result": true,
  "writebacks": [
    {
      "id": "al3eo-t5elp-ltput-g5a62-m3pmo-wian",
      "import_source_id": "axk7q-5ljws-dv2eb-z4aux-dsrpd-ki5u",
      "node_id": "2vqwd-zclih-azwk2-i6ay3-3bdrw-qa3p",
      "profile_id": "1234567890123456789",
      "remote_path": "/Marketing/Q3 Report.docx",
      "operation": "upload",
      "status": "conflict",
      "file_size": 184320,
      "bytes_uploaded": 0,
      "remote_mtime_before": "2026-04-27 16:37:29 UTC",
      "error_message": "The copy at the provider changed since this write-back was queued",
      "retry_count": 0,
      "properties": {},
      "created": "2026-04-27 16:38:02 UTC",
      "updated": "2026-04-27 16:41:15 UTC"
    }
  ],
  "pagination": { "limit": 50, "offset": 0, "total": 1 }
}

pagination.total is the number of items in writebacks, not the number of jobs the source has. It cannot be used to size a progress bar or to decide how many pages exist. Page until a page comes back shorter than limit.

Error Responses

Write-Back Job Details

Auth: JWT required. Any workspace member with view access.

Path Parameters

Response (200 OK)

{
  "result": true,
  "writeback": {
    "id": "al3eo-t5elp-ltput-g5a62-m3pmo-wian",
    "import_source_id": "axk7q-5ljws-dv2eb-z4aux-dsrpd-ki5u",
    "node_id": "2vqwd-zclih-azwk2-i6ay3-3bdrw-qa3p",
    "profile_id": "1234567890123456789",
    "remote_path": "/Marketing/Q3 Report.docx",
    "operation": "upload",
    "status": "completed",
    "file_size": 184320,
    "bytes_uploaded": 184320,
    "remote_mtime_before": "2026-04-27 16:37:29 UTC",
    "error_message": null,
    "retry_count": 0,
    "properties": { "triggered_by": "manual_push" },
    "created": "2026-04-27 16:38:02 UTC",
    "updated": "2026-04-27 16:39:44 UTC"
  }
}

A job belongs to exactly one source. Asking for a valid job id under the wrong source is refused rather than answered, so the pair must match.

Error Responses

Push a File Back to the Provider

The job is created pending, with operation: upload — a manual push is always an upload, never a delete — and properties.triggered_by set to manual_push. It returns as soon as the job is queued; it does not wait for the transfer.

Auth: JWT required. The owner of the source's connected identity, or a workspace admin. The transfer runs under the owner's cloud credential.

Path Parameters

No request body.

{node_id} must name an imported FILE or NOTE, never a folder. This is worth stating plainly because a folder inside a synced folder is an imported node just as much as a file is, so a folder's id is a perfectly plausible thing to send. It is refused at request time — 409 Conflict, error.code 166884, "Node is not an imported file or note" — rather than accepted with a 200 and a queued job that could only fail later. There is no "push this folder" operation; push each file. A note’s id is accepted. A note is Markdown — a .md node holding ordinary stored content — so it mirrors to the provider as its own .md object, and pushing one queues a write-back exactly as pushing a file does.

The node must also be under this source and still carry its import metadata. A node that belongs to another source, or that sits outside the folder this source imported, is refused 404 — the id is not addressable through this source.

Response (200 OK)

{
  "result": true,
  "writeback": {
    "id": "al3eo-t5elp-ltput-g5a62-m3pmo-wian",
    "import_source_id": "axk7q-5ljws-dv2eb-z4aux-dsrpd-ki5u",
    "node_id": "2vqwd-zclih-azwk2-i6ay3-3bdrw-qa3p",
    "profile_id": "1234567890123456789",
    "remote_path": "/Marketing/Q3 Report.docx",
    "operation": "upload",
    "status": "pending",
    "file_size": 184320,
    "bytes_uploaded": 0,
    "remote_mtime_before": null,
    "error_message": null,
    "retry_count": 0,
    "properties": { "triggered_by": "manual_push" },
    "created": "2026-04-27 16:38:02 UTC",
    "updated": "2026-04-27 16:38:02 UTC"
  }
}

The response is 200, not 201.

Error Responses

The access-mode check runs before the permission check. A member who is neither owner nor admin, pushing to a read_only source, is told about the access mode rather than about their permissions.

Three of the refusals above share one error.code — "Node is not an imported file or note", "Node does not belong to this import source" and "Node is not under this import source". They are distinguished by HTTP status (409 versus 404), never by the numeric code. This is the general rule for this API: numeric codes are assigned per call site and are for diagnostics, not for branching.

Retry a Failed Write-Back

Retrying does not change anything about the transfer. If the cause was a permission the connected account does not have, or a provider that rejects the file, the retry will fail the same way. Fix the cause first — a write-back that failed because the connected account lacks permission to write that folder is a permanent failure, and only granting the permission makes a retry worthwhile.

Auth: JWT required. The owner of the source's connected identity, or a workspace admin.

Path Parameters

No request body.

Precondition: status must be failed. Any other status is refused.

Response (200 OK)

The job, as re-queued — status: "pending", error_message: null, retry_count: 0, under the writeback key.

Error Responses

Resolve a Write-Back Conflict

Auth: JWT required. The owner of the source's connected identity, or a workspace admin.

Path Parameters

Request Body (JSON)

The value is case-sensitive, surrounding whitespace is ignored, and any other value is refused. keep_local discards the other side's change at the provider, and keep_remote discards the local one — put the choice in front of a person rather than defaulting it.

Precondition: status must be conflict.

Response (200 OK)

The job, as re-queued — status: "pending", properties.resolution set to the value you sent, under the writeback key.

Error Responses

The already-covered check on resolve excludes the job being resolved. A conflict job is itself live, so a check that counted it would refuse every resolve. Resolving is therefore never blocked by its own row — only by a different live write-back on the same file, for the same operation, which is what a later edit or a retry can put there while the conflict waits for a decision.

Cancel a Write-Back

Auth: JWT required. The owner of the source's connected identity, or a workspace admin. Cancelling runs no transfer and needs nobody's cloud credential — the same gate is applied to every write action on this queue so that one rule covers the whole surface.

Path Parameters

No request body.

Precondition: status must be pending or conflict. A job already uploading cannot be cancelled — the transfer is in flight, and there is no point at which it could be stopped cleanly. Wait for it to reach a terminal status.

Response (200 OK)

The job, with status: "canceled", under the writeback key.

Error Responses

Cancel has no already-covered check. It removes a live job rather than creating one, so whether the file is already covered is irrelevant to it — the two refusals about coverage that push, retry and resolve can return do not appear on this endpoint.

Reading a Write-Back Refusal

This is the part clients get wrong, so it is worth stating on its own. Refusals on the four write endpoints fall into three groups, and only two of the three are worth sending again.

Not every 409 on this surface is settled, which is the opposite of the general rule for conflicts elsewhere in this API. The already-covered refusal is the exception, and treating it as permanent means abandoning work that would have succeeded a moment later.

Why the 503s happen at all. Push, retry, resolve and cancel each take a short exclusive turn on the file they act on, so two write-back actions for one file can never interleave. Three distinct things can go wrong with that turn. All three answer 1693 → 503, and on all three nothing was written:

These are three different facts, not three phrasings of one: could not start, started but could not look, started and lost the turn before writing. Only the last one implies the request got as far as being ready to write — and it still wrote nothing, so re-sending it cannot queue, re-queue or cancel anything twice. All three are ordinary transient conditions that a plain retry fixes.

Cancel has no already-covered check — it removes a live job rather than creating one, so coverage is irrelevant to it and the middle row above cannot occur there.

Live means pending, uploading or conflict — those are the statuses that make a file "already covered". A completed, failed or canceled job does not block anything. And because operation is part of the match, a pending upload does not block a delete for the same file.

Telling the two 409s apart.

• On retry, re-read the job. If it is still failed — the status retry requires — the refusal was the transient one, and waiting will clear it. Any other status means the refusal was settled and the job has moved on without you.
• On resolve, re-read the job the same way. Still conflict means the refusal was the transient one; any other status means it was settled. The check excludes the job being resolved, so a resolve is never blocked by its own row — only by a different live write-back that appeared on the same file while the conflict was waiting for a decision.
• On push there is no job id to re-read, so the refusal itself is the discriminator. An access-mode refusal, or one saying the node is not an imported file or note, is settled. Only "This node already has a write-back in progress" clears as the queue drains — list the queue for that source and wait for the covering job to reach a terminal status.
• On cancel there is only one 409 to read — the state precondition — and it is settled.

In short: 1693 → 503, retry it; a 1660 saying the node is already covered, re-read and wait; a 1660 on a state precondition, settled — never retry.

Two outcomes worth planning for

A permission refusal from the provider is permanent. If the connected cloud account cannot write to the folder, every attempt fails identically. Retrying is wasted; the fix is to grant the account write access at the provider, and only then retry.

Renaming or moving an imported file inside Fastio leaves a duplicate at the provider. The write-back creates the file at its new remote path and deliberately does not delete the object at the old one — an unattended delete of a customer's cloud object is the more dangerous of the two failure modes. Expect the old copy to remain, and remove it at the provider if you do not want it.