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

Every /current/cloudsync/details/{source_id}/... endpoint above enforces a scoped credential's workspace scope, the same way the /current/cloudsync/workspace/{workspace_id}/... endpoints already do. The source id resolves to a workspace, and a credential whose scope does not cover that workspace is refused with 10560 (Access Denied) → 403, “Your token does not have sufficient scope for this Workspace.” — read endpoints (details, jobs, jobs/{job_id}, writebacks, writebacks/{id}) need read scope on the workspace, mutations (update, refresh, delete, disconnect, jobs/{job_id}/cancel, and every writebacks/... write action) need write scope.

Several of those mutations are also gated on who is acting, not only on scope. jobs/{job_id}/cancel always requires an admin-capable credential. refresh, update, delete, disconnect, writebacks/push/{node_id} and writebacks/{writeback_id}/cancel|resolve|retry require one only when the caller is acting as a workspace admin rather than as the member who connected the source — that connector/identity owner still only needs the write scope above. Admin-capable means a sign-in session, or a token holding rwa on the workspace or its org (see scope_admin_required under Transfer Workspace Ownership above). A legacy unscoped API key passes the write-scope check above but is never admin-capable, so it cannot take these actions as an admin.

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.
• An Enterprise org can additionally gate this with an AI policy. Turning intelligence=true ON can be refused (ai_policy_denied / ai_policy_workspace_not_allowed) independently of the plan check above, and even with the switch already on, background indexing and interactive use can be paused by the org. Read capabilities.can_use_intelligence and capabilities.ai_policy_state on workspace details for the effective, policy-aware answer rather than inferring it from the raw intelligence switch — see AI, Intelligence & MCP Access Policy in Organizations.

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).
• An Enterprise org can additionally gate this with an AI policy. Turning metadata_extraction=true ON can be refused the same way as intelligence=true above, and the explicit per-file/per-folder extraction endpoints and automatic on-ingest extraction alike can be paused org-wide or narrowed to specific workspaces. Read capabilities.can_use_metadata and capabilities.ai_policy_state.metadata on workspace details for the effective answer — see AI, Intelligence & MCP Access Policy in Organizations.

Sharing Policy

Two booleans on a workspace control whether new sharing may be created in it:

The organization carries a twin of each. The effective answer is the org setting AND the workspace setting, so the org is a ceiling: a workspace may switch sharing off for itself, but cannot switch it back on once the org has switched it off. Switching either level off requires the Enterprise plan; switching one back on, resubmitting it unchanged, and reading them do not.

• On by default. A workspace that has never configured these reports both as true, including every workspace created before the settings existed.
• Change them: POST /current/workspace/{workspace_id}/update/ with sharing_shares and/or sharing_file_links. Workspace Admin or above. Send both form-encoded or as query parameters, with the string "true" or "false" — a JSON request body is not read by this endpoint.
• Switching one off blocks NEW creation only. Shares and links that already exist keep working and remain editable and deletable. Nothing is revoked, expired or deleted.
• Read the effective answer, not the settings. capabilities.can_create_share, capabilities.can_create_folder_share and capabilities.can_create_fileshare on the workspace already combine the calling user's role with both policy levels. The raw sharing_* booleans report this workspace's own setting only, which is not the whole answer when the org has switched sharing off.
• The org half of the rule is readable on the workspace. capabilities.org_sharing_shares and capabilities.org_sharing_file_links report the parent organization's ceiling for each switch, and capabilities.org_controls reports whether that organization's plan allows configuring these controls at all; all three are returned to workspace members at the full output level, so a settings screen can distinguish "switched off here" from "switched off for the whole organization" without a second request.
• Refusals from the create endpoints are HTTP 403 with params.reason = policy_sharing_disabled. A refusal never leaves a partially created share behind — for a shared folder in particular, the folder is not created.
• Audit. A write that changes either switch adds policy_changes.<key> = { before, after } to the workspace_updated event (before is the value in force, so a switch never configured reports true). policy_changes is absent when neither switch changed.

Collaboration Policy (External Invites)

A separate org-level setting, external_invites_workspaces, governs whether a member may bring an outside person onto a workspace — distinct from the sharing policy above, which governs creating shares at all. See Collaboration Policies in the Organizations reference for the full envelope shape, the override rules, and the org-level request/response fields.

• This workspace's own switch: external_invites (allowed / denied, or absent to inherit the org policy) — a raw setting, readable by any member at the full output level and writable only by a workspace admin, and gated by nothing itself. It can only ever tighten below the org's result, never loosen it, and there is currently no way to reset it back to "inherit" once set.
• Read the effective answer: capabilities.can_invite_external on the workspace's details response combines the org policy, the calling user's role/override, and this workspace's own switch for the calling user. Do not recompute it client-side from external_invites.
• Refusals are HTTP 403 with params.reason = external_invites_denied (the org policy) or external_invites_object_denied (this workspace's own switch), raised at member invitation (fresh, resend, and any broadening edit — a permission reduction is never gated) and at invitation acceptance, re-checked against the live policy at redemption time. A redemption refusal leaves the invitation pending, never failed; decline is never gated.
• Inviting a member to the org itself is a different action and is never gated by this policy.

Cloud Sync Policy

Distinct from the cloud_import on/off switch (which the Cloud Sync endpoints below still use to gate the feature entirely), an Enterprise-plan org can restrict the direction cloud sync is allowed to run in, and a workspace can tighten that further for itself.

• enabled = false stops sync in both directions: every import source in the workspace parks at status: "suspended_policy". mode = "read" stops only the outbound half — inbound sync continues, and the source keeps its live status.
• Effective access is always the org-then-workspace meet, resolved in that order: a member override that would widen access still loses to a workspace stored at read.
• cloud_sync_mode absent on a workspace reads as read_write (the permissive default), never read.
• The workspace value is a preference: POST workspace/{workspace_id}/update/ accepts either value from an authorised workspace admin, including widening read back to read_write — the runtime meet already prevents a stored read_write from beating an org read.
• Read the effective answer: GET workspace/{workspace_id}/details/ (full output tier only) returns the raw cloud_sync_mode plus effective_cloud_sync: {enabled, mode, reason} for the calling user. reason is null, cloud_sync_disabled, or cloud_sync_read_only. null is never permissive.
• Every cloud-sync source object also carries effective_access_mode / effective_access_mode_reason beside access_mode / enforced_access_mode — see When the Org or Workspace Policy Restricts Cloud Sync below.
• The list response (GET .../sources/) additionally carries pending_removal, describing a sync that stopped rather than remove an unusually large share of a connected folder — see Confirming a Large Deletion below. Not present on GET .../details/{source_id}/.
• A write-back queued before a flip to read is deferred, not failed — no write_back_failed event, and it resumes if the policy widens. The hold is bounded (~5 days); a row still held at the ceiling retires as terminal failed with properties.terminal_reason: "policy_hold_expired". The local edit is never touched.
• Manual write-back actions (push, retry, a keep_local resolve) refuse immediately with 403 and params.reason = cloud_sync_read_only (or cloud_sync_disabled) instead of accepting and quietly deferring.
• Opening a new connection (identity provision, source create, each provider's OAuth-complete) is refused with 403 / cloud_sync_disabled when enabled = false; on OAuth-complete it is raised before the authorization code is redeemed. mode never gates a connection. Inspecting or disconnecting an existing connection is never blocked by this policy.
• How a policy refusal reads. A refusal is 1700 (Forbidden) → 403 carrying params.reason (cloud_sync_disabled or cloud_sync_read_only) — settled until an admin changes the policy, so do not retry it. When the policy could not be read at all, the same endpoints answer 1693 (Temporarily Unavailable) → 503 "Cloud sync policy is temporarily unavailable. Please try again shortly." — transient; send the same request again shortly and never render it as a denial. Branch on the HTTP status and params.reason, never on the numeric error.code.
• A policy-parked source can still be paused. POST cloudsync/details/{source_id}/update/ with action: pause is accepted on a suspended_policy source (as well as synced / error), so a user can keep it held when the policy re-enables sync; it then stays paused until they resume it. A source that is already paused is never moved to suspended_policy.

Both halves are wired. The org-level write (cloud_sync on POST org/{org_id}/update/) and its raw, admin-only echo on GET org/{org_id}/details/ use the same shared policy spine as Collaboration Policies and Credential Policy — see Cloud Sync Policy in the Organizations reference for the org-side shape.

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",
    "intelligence": true
  }
}

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": {"color": "#0066CC", "opacity": 100},
    "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",
    "org_domain": "acme-corp"
  }
}

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,
  "names": ["logo"],
  "metadata_scheme": {
    "logo": {
      "width": {"name": "Image Width", "description": "Image width", "required": true, "type": "int", "min": 1},
      "height": {"name": "Image Height", "description": "Image height", "required": true, "type": "int", "min": 1},
      "mime": {"name": "Mimetype", "description": "Image mimetype", "required": true, "type": "string"},
      "megapixels": {"name": "Image Megapixels", "description": "Image megapixels", "required": true, "type": "int", "min": 0, "max": 48},
      "transform": {"name": "transform", "description": "Transform image", "required": false, "type": "image_transformer"}
    }
  },
  "file_types": {"logo": "image"}
}

names lists the asset names a workspace accepts (only logo); file_types maps each to its file kind; metadata_scheme maps each to the metadata properties validated on upload.

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": {
      "metadata": {"width": 512, "height": 512, "megapixels": 0, "mime": "image/png"}
    }
  }
}

Keyed by asset name; each entry carries the stored metadata. A workspace with no assets returns "assets": []. Fetch the bytes with Read Asset Binary below.

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
}

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 signed-in user; workspace membership is not required. 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. You cannot add or invite someone at a role above your own — the ceiling applies to invitations as well as direct adds.

Send the parameters as form fields (application/x-www-form-urlencoded or multipart/form-data); a JSON request body is refused with a 406 error.

If you pass an email address that belongs to an account which has not verified that address, an invitation is sent to it instead of adding the account directly.

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": "aea3w-cuan6-edcu5-vkaex-g52gm-dacr",
    "inviter": "John Doe",
    "invitee_email": "newuser@example.com",
    "entity_type": "workspace",
    "state": "pending",
    "created": "2025-01-15 10:30:00 UTC",
    "expires": "2025-01-18 10:30:00 UTC"
  }
}

Abbreviated: the invitation object carries every field of a List Workspace Invitations entry, plus a workspace object.

Error Responses

Direct-add and invitation both count as "adding a member" for the collaboration policy above; an org invite (adding someone to the org itself, not to this workspace) is a separate action and is never gated by it.

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.

Query Parameters: limit (default 100, max 500) and offset (default 0). The response carries a pagination object (total, limit, offset, has_more).

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",
      "notify": "Notify me in app"
    },
    {
      "id": "9876543210987654321",
      "account_type": "agent",
      "email_address": "bot@example.com",
      "first_name": "Sync",
      "last_name": "Bot",
      "permissions": "member",
      "status": "active",
      "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": "aea3wcuan6edcu5vkaexg52gmdacr",
        "created": "2025-01-15 10:30:00",
        "expires": "2025-01-18 10:30:00"
      }
    }
  ],
  "pagination": {
    "total": 3,
    "limit": 100,
    "offset": 0,
    "has_more": false
  }
}

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,
  "user": {
    "id": "9876543210987654321",
    "account_type": "human",
    "email_address": "user@example.com",
    "first_name": "Jane",
    "last_name": "Smith",
    "permissions": "member"
  }
}

Response Fields

Error Responses

Update a Member

Auth: JWT required. Permission depends on perm_member_manage; you may always update your own membership. Either way you cannot set a role above your own.

Send the parameters as form fields; a JSON request body is refused with a 406 error.

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

Transfer Workspace Ownership

Auth: JWT required. Owner only.

Fixed behaviour:

• The successor is promoted before the current owner is demoted, under a per-workspace lock.
• Retry completes a partial transfer. If a previous call stopped midway (both users end up owners), calling again with the same target finishes it and returns 200.
• A concurrent call on the same workspace returns 409 transfer_in_progress.
• No email is sent — this is recorded as an event 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,
  "ownership": {
    "profile_id": "1234567890123456789", "profile_type": "workspace",
    "previous_owner": "1111111111111111111", "new_owner": "9876543210987654321",
    "transferred_at": "2026-09-23 16:37:29 UTC"
  }
}

Error Responses (error.params.reason)

Event: ownership_transferred (audit log; profile_type, from_user, to_user). The two existing membership_updated events (promotion and demotion) still fire.

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

A new self-joined member gets the member role; a current (unexpired) member who self-joins keeps their role; an expired membership is restored as member. Only notify_options is read; permissions is ignored. A self-join never sets a membership expiry.

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.

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": "aea3wcuan6edcu5vkaexg52gmdacr",
    "created": "2025-01-15 10:30:00",
    "expires": "2025-01-18 10:30:00"
  }
}

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": "aea3w-cuan6-edcu5-vkaex-g52gm-dacr",
      "inviter": "Alice Johnson",
      "inviter_actor": {
        "user_id": "1234567890123456789",
        "kind": "human",
        "agent_name": null,
        "name_source": null,
        "credential_type": "session",
        "verified": false
      },
      "invitee_email": "newuser@example.com",
      "invitee_uid": "5566778899001122334",
      "accepted_uid": null,
      "entity_type": "workspace",
      "state": "pending",
      "consumed": false,
      "created": "2025-01-15 10:30:00 UTC",
      "updated": "2025-01-15 10:30:00 UTC",
      "expires": "2025-01-18 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.

Send the parameters as form fields; a JSON request body is refused with a 406 error.

Request Parameters (all optional)

Examples

# Decline by ID
curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/members/invitation/aea3w-cuan6-edcu5-vkaex-g52gm-dacr/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "state=declined"

# 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/aea3w-cuan6-edcu5-vkaex-g52gm-dacr/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true
}

Error Responses

Creating Shares from Workspaces

Create Share

Auth: JWT required. Workspace Guest or above, subject to the Sharing Policy — read capabilities.can_create_share for the effective answer.

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
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 100,
    "offset": 0,
    "has_more": false
  }
}

Import Share into Workspace

Auth: JWT required. Workspace Member or above AND owner of the share.

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",
    "id_alt": "adheih5r326qjiqvk4wfamvt4rqeh",
    "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,
    "comments_enabled": false
  }
}

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",
      "id_alt": "adheih5r326qjiqvk4wfamvt4rqeh",
      "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,
      "comments_enabled": false,
      "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"
        }
      ]
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 100,
    "offset": 0,
    "has_more": false
  }
}

Update a File Share

Request Body (form-encoded)

Widening access_option (named_people → any_registered or anyone_with_link, or any_registered → anyone_with_link) is governed by the org's collaboration policy exactly like the grants endpoint below — narrowing and every other field are unaffected.

Error Responses

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

Collaboration policy. A grant to an external person (not a current member of the File Share's owning org, and not on one of that org's verified SSO domains) is governed by the org's external_invites_shares policy — see Collaboration Policy above. A File Share has no external-invite switch of its own; it follows the org policy only. A new grant or any broadening edit — raising the capability, extending an expiry, or widening access_option — is gated; a pure reduction is always available. This applies to POST (both the email and numeric-user arms) and to a resend that raises the capability, but never to DELETE.

Granting by Email

• If the email belongs to an existing account that has verified that address, it is granted directly — the response carries the resolved user, and the grant appears in the list as state: active. A new grant sends that person an email with a direct link to the File Share (granting by user does the same); changing the capability of an existing grant sends nothing.
• If the email has no account yet, or belongs to an account that has not verified it, a pending invitation to that address 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, verified 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.

Query Parameters

Pagination is opt-in: it activates only when the request includes limit and/or offset (an explicit offset=0 counts as a request). When neither parameter is present, the response is unchanged from before — every accessible workspace, and no pagination key.

Example

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

Example (paginated)

curl -X GET "https://api.fast.io/current/workspaces/all/?limit=50&offset=0" \
  -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": {"color": "#0066CC", "opacity": 100},
      "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. Pagination uses the same limit/offset parameters and pagination object as the shares listing but, unlike it, applies only when requested. An out-of-range or non-numeric limit (valid 1-500), or a negative or non-numeric offset, is rejected with an invalid-input error (1605).

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 (without user_status or pagination), but only includes un-joined workspaces.

Check Workspace Name

Auth: JWT required. Membership (Member or above) of the org in the path required. 2FA required.

Path Parameters

Example

curl -X GET "https://api.fast.io/current/workspaces/check/name/1234567890123456789/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.

When the Workspace Is Deleted

Deleting a workspace — or closing the org that owns it — does not disconnect its cloud-sync sources, because a deleted workspace can be restored for a while. Instead each source moves to suspended_workspace at its 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. The check that found the workspace deleted is recorded once as a failed job; no further jobs run for the source while it is suspended.

If the workspace is restored, the source resumes on its own within about a day: it goes back to synced and syncs at the next opportunity, with the same files and the same connection — nothing is re-imported. There is no call to make and no reconnect to redo. If the workspace is never restored, its sources are removed together with the rest of the workspace when the deletion becomes permanent.

A source in suspended_workspace cannot be resumed or refreshed by hand (update/ with action: resume and refresh/ both answer 409); it can still be paused, or disconnected.

When the Org or Workspace Policy Restricts Cloud Sync

See Cloud Sync Policy above for the org cloud_sync envelope and the workspace cloud_sync_mode ceiling. Two outcomes, driven by the two halves of that policy:

• enabled = false parks every source in the workspace at status: "suspended_policy" — a new value alongside suspended_plan, with the same "nothing to repair" behavior: files, the graft and the remote link are all kept, and the source resumes on its own once the policy re-enables sync. The policy is resolved for the member who owns each source's connected account, so a per-member override parks only that member's sources.
• mode = "read" changes no source status. Inbound sync continues; only outbound write-back is affected.

Every cloud-sync source object (list, details, and the sources/create/ and details/{source_id}/update/ responses) carries effective_access_mode and effective_access_mode_reason beside access_mode / enforced_access_mode: the actual behavior for the calling principal once the policy is applied, in the source's own read_only / read_write vocabulary (not the policy's read / read_write vocabulary — the two are never conflated). It is the caller's own resolved policy met with the policy of the member who owns the source's connected account (the write-back runs under that account), then capped by the source's own access_mode — so a read_only source is never reported read_write, and a permissive caller still sees read_only when the owner's policy is read. effective_access_mode_reason is null, cloud_sync_disabled or cloud_sync_read_only. Both fields are null when the answer could not be determined (the policy could not be read, or the caller or the account's owner could not be resolved); null is never permissive.

Timestamp format change. The cloud-sync source object's last_sync_at, next_sync_at, created and updated are now emitted as YYYY-MM-DD HH:MM:SS UTC — the canonical API datetime format. They previously omitted the UTC suffix. A client that parses these fields with a fixed pattern must accept the suffix.

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.

Estimating Folders Before Connecting Them

POST /current/cloudsync/workspace/{workspace_id}/sources/estimate/ counts how many files and how many bytes up to 10 remote folders hold, so a picker can show whether each one fits the workspace plan before a source is created. It runs as a job, like discovery. It is not metered: no credits are charged for an estimate.

Auth: JWT required. The same rules as sources/discover/: the caller must be a member of the workspace and the owner of the chosen identity — there is no workspace-admin override. The identity must be active, cloud sync must be enabled for the workspace, and the endpoint is rate limited.

Response (200):

{
  "result": true,
  "job_id": "{job_id}",
  "status": "estimating",
  "message": "Estimate job created. Poll for results: GET /cloudsync/details/estimate/jobs/{job_id}/",
  "drive_id": null,
  "drive_type": null,
  "drive_name": null,
  "site_name": null
}

The drive fields are filled in for OneDrive for Business. Sending the same request again (same identity, same drive, same folders in the same order) while an estimate is still running returns that same job, in the same shape, with the message "An estimate for these folders is already running. Poll for results: GET /cloudsync/details/estimate/jobs/{job_id}/". A different order is a different request.

Polling. GET /current/cloudsync/details/estimate/jobs/{job_id}/ — the job endpoint with the fixed segment estimate where a source id would go, exactly as discovery uses discovery. Owner-only, like discovery polling. A discovery job id asked for under estimate, or an estimate job under discovery, answers not found. The response is { "result": true, "job": { ... } } with the standard job object: job_type is discovery with properties.discovery_kind set to estimate (that is how an estimate is told apart from a folder discovery), status is pending · running · completed · failed · canceled, and import_source_id is null. job.properties also carries provider, identity_id, drive_id (OneDrive for Business), estimate_paths (the folders asked about) and, once the job has completed, estimate_results and estimate_completed_at (YYYY-MM-DD HH:MM:SS UTC).

If the job as a whole cannot run — the identity was revoked, the workspace was closed, the organization's policy turned cloud sync off, or the plan could not be determined — it ends failed with the reason in error_message. Estimate jobs cannot be canceled, and they never appear in the workspace-wide jobs view.

estimate_results holds one row per folder, in the order requested:

{
  "remote_path": "/Clients",
  "file_count": 1250,
  "total_size": 734003200,
  "complete": true,
  "stopped": null,
  "counted_at": "2026-10-04 12:00:00 UTC",
  "error": null
}

Files and bytes are counted the same way the first sync counts a newly connected folder against the plan. The folder can change at the provider between the estimate and that sync.

• complete: true — exact numbers; stopped and error are null.
• stopped: "limit" — the count passed the plan's per-folder file cap or size cap, and counting stopped there. file_count and total_size are the values reached, already over the cap. This folder will not fit the plan; connecting it would be refused at its first sync.
• stopped: "timeout" — the folder took longer than about two minutes to count. The numbers are partial and are a lower bound.
• error set — the folder could not be counted; file_count and total_size are 0, complete is false and stopped is null. The other folders in the same request are still counted. The message is one of: "folder not found at the cloud provider", "provider rate limited, try again shortly", "the cloud provider refused to list this folder", "the cloud provider refused access for the connected account", "this folder path cannot be read", "the folder listing could not be read completely, try again shortly", "the folder could not be counted, try again shortly".

drive_id errors are the same as on discover (see Selecting a Drive on a Source), and so are the owner-only refusal and the cloud-sync-disabled refusals.

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. Send root to place the import directly at the top level of the workspace instead, with no Imports folder. 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.

A folder that contains, or sits inside, a connected folder is refused too. Connecting /Clients while /Clients/Northwind is already connected — or the other way round — would sync the same files into two places, and on a two-way source each would write back into the other's folder. The candidates are the same as for the duplicate check above: sources in this workspace on the same connected cloud account (and, for OneDrive for Business, the same library) that still hold their folder; a disconnected source does not count. Paths are compared ignoring letter case and leading or trailing slashes, one whole folder name at a time — /Foo does not overlap /Foobar. A source connected at the account root overlaps every folder. An exact match keeps the duplicate refusal (268832); only a strict ancestor or descendant gets 165964. Discovery flags these folders in advance with overlaps_graft.

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 (a workspace admin needs a sign-in session or an rwa credential on the workspace or its org — an unscoped API key does not qualify). The permission check runs before the “already disconnected” check below, so a caller without access learns nothing about the source's status from the answer.

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 pauses for confirmation — instead of being applied — when it would remove an unusually large share of the connected folder: at least 10 files, and more than a quarter of the files the folder holds; or 1,000 files or more, regardless of the folder's size. A provider listing that comes back completely empty for a folder that previously held files always pauses, whatever the count. When a run pauses: 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, ending with “The person who connected this account can confirm the removal to let it proceed.” 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.

Removed files land in the workspace trash, not gone for good. A removal that proceeds — whether it was below the pause threshold or went through after confirmation — moves the files to the workspace's trash like any other delete, so they can be restored from there. Restoring a file that was removed from a read_write connected folder uploads it back to the cloud provider, the same as creating a new file in that folder would.

Read pending_removal on the list response, not error_message. GET .../workspace/{workspace_id}/sources/ carries a structured pending_removal field on each source — error_message is advisory text for a human and is not part of the contract. pending_removal is null when nothing is waiting for confirmation (the normal case), while a sync is queued or running, and for a stop that cannot be confirmed at all (see the fourth point below); otherwise:

"pending_removal": {
  "remove_count": 6,
  "folder_file_count": 16,
  "files": ["Reports/q3.xlsx", "Old Drafts/"],
  "files_truncated": false,
  "detected_at": "2026-10-02 16:58:14 UTC",
  "connector_owner": { "user_id": "2477739036763523387", "name": "Jane Doe" },
  "can_confirm": true
}

This field is not present on GET .../details/{source_id}/ — read it from the list.

To let the removal 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. A plain refresh (no acknowledge_large_delete) stays owner-or-admin, like the rest of refresh/. Confirming the removal itself is the connector owner’s alone — there is no workspace-admin override. A caller who passes the usual refresh access check (owner or workspace admin) but is not the person who connected the account gets the first error below; a caller who fails that access check gets the endpoint’s ordinary access errors instead:

After a confirmed refresh, pending_removal becomes null immediately. status stays error for a few seconds until the sync starts, then moves syncing → synced — or back to error with a new pending_removal if more files vanished in the meantime. The response shape of refresh/ itself does not change.

Five things about acknowledge_large_delete 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 the connector owner (pending_removal.connector_owner) before sending it, and never wire it into a retry loop.

Reading a Source Against Its Plan Limits

Each connected folder is limited by the workspace plan in two ways: how many files it may hold and how many bytes. Every source object from the list, details and sources/create/ responses carries both caps and where the source stands against them:

The two caps and the two states are null on a response that carries no plan context (the update/ response); limit_exceeded is present everywhere.

limit_exceeded is the refusal itself, not arithmetic. When a sync is refused because the folder is over a cap, the source goes to status: "error" with an error_message, and limit_exceeded names the cap. The matching object_limit_state or size_limit_state then reads exceeded even if file_count or total_size is still 0 — which is the normal case for a newly connected folder refused before anything was imported. limit_exceeded is set only while the source is still in that error: it is null again as soon as the source leaves status: "error" or its error_message changes to a different reason — when the next sync starts, succeeds, fails for another reason, or the source is suspended, paused or disconnected. Upgrading the plan does not clear it by itself: limit_exceeded and the matching exceeded state remain until the source leaves the refusal state — normally when the next sync of that source starts — even though the new plan's caps are already reported in object_limit / size_limit.

size_limit_state can read lower than what the next sync compares. total_size includes a file with no provider-declared size (a Google Docs, Sheets or Slides file) only once it has actually been imported, while the sync's own check counts each such file it has never imported as 10 MiB. Use the estimate endpoint (see Estimating Folders Before Connecting Them) to check a folder before connecting it.

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. The exception is the two update/ busy refusals, which answer 406 and are retryable (see below). 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. Some 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. The cloud-sync policy rows split the same way: 105962 → 403 is settled until an admin changes the policy, while 178341 / 178934 → 503 means the policy could not be read and is worth sending 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 — but a write-back it already queued is held, not discarded; see below.

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). The identity owner needs only the write scope documented above; a workspace admin additionally needs an admin-capable credential — a sign-in session, or a token holding rwa on the workspace or its org — and is otherwise refused scope_admin_required (see Transfer Workspace Ownership above). 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 canonical API datetime format. 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 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.

Flipping a source to read_only HOLDS its queued write-backs instead of cancelling them. A pending job stays pending; the route resumes automatically, with no re-queue needed, as soon as the source is switched back to read_write. The hold is bounded: a write-back still held after about 5 days ends failed instead of waiting indefinitely, with properties.terminal_reason: "policy_hold_expired" — retry-writeback accepts it from there, so the edit is never silently lost. This is a reversible policy choice, not a loss of the route: disconnecting the source, deleting it, a member removal, or a revoked connection still cancel outright, exactly as above.

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 (a workspace admin needs a sign-in session or an rwa credential on the workspace or its org; the identity owner needs only write scope). 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 permission check runs before the access-mode check. A member who is neither owner nor admin, pushing to a read_only source, is told about their permissions rather than about the access mode — so a caller without access, or one whose credential's scope doesn't cover the workspace, learns nothing about the source's mode from the answer.

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 (a workspace admin needs a sign-in session or an rwa credential on the workspace or its org; the identity owner needs only write scope).

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 (a workspace admin needs a sign-in session or an rwa credential on the workspace or its org; the identity owner needs only write scope).

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 (a workspace admin needs a sign-in session or an rwa credential on the workspace or its org; the identity owner needs only write scope). 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.

A cloud-sync policy refusal is a separate answer again. Push, retry and a keep_local resolve refuse with 1700 (Forbidden) → 403 and params.reason = cloud_sync_read_only or cloud_sync_disabled when the org or workspace policy does not allow write-back — settled until an admin widens the policy, so do not retry it. A "Cloud sync policy is temporarily unavailable" 1693 → 503 is retryable like the other 503s. Cancel and a keep_remote resolve are never refused by policy. See Cloud Sync Policy.

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.