Share Management Purpose-built portals for exchanging files with internal teams and external guests.

Shares are purpose-built portals for exchanging files with internal teams and external guests. They support branded file preview, download controls, guest access, password protection, expiration, AI-powered features, and real-time collaboration.

Share Types

Default share type is exchange.

Storage Modes (Immutable at Creation)

Portal (storage_mode=independent, default)

The share has its own isolated storage. Files added to the portal are independent of any workspace. Changes to workspace files do not affect the portal, and vice versa.

Features: Expiration dates, archiving, password protection (Send type only), custom branding, guest access, inline file preview, download controls, post-download messaging, AI auto-titling.

Shared Folder (storage_mode=workspace_folder)

The share is backed by a specific workspace folder. The share displays the live contents of that folder — files added, updated, or removed in the workspace folder are immediately reflected in the share. No file duplication, so no extra storage cost.

Creation: Pass folder_node_id={folder_opaque_id} to link an existing folder, or create_folder=true with folder_name to create a new one.

Restrictions: Expiration dates and archiving are not allowed since the content is live. Each workspace folder can only be shared once. If the backing folder is deleted, the share becomes orphaned (is_orphaned: true in details response).

Both modes look the same to share recipients — a branded portal with file preview, download controls, and all share features.

Response Field: share_category

API responses include a share_category field alongside storage_mode. The storage_mode field is the input parameter used when creating shares; share_category is response-only.

Access Options

The access_options parameter controls who can access the share:

Restrictions:

• Receive and Exchange shares cannot use 'Anyone with the link' unless anonymous_uploads_enabled is true (requires premium plan). Without anonymous uploads, file uploads require user identity.
• Enabling comments or certain notification settings on a share with 'Anyone with the link' access automatically upgrades access to 'Anyone with a registered account' because those features require user identity.
• Changing share type to receive or exchange while access is 'Anyone with the link' automatically upgrades access to 'Anyone with a registered account' (unless anonymous_uploads_enabled is true).
• Changing access away from 'Anyone with the link' or changing type away from Receive/Exchange automatically disables anonymous_uploads_enabled.

Compact Responses (output=)

Every endpoint that returns one or more share objects (details, list, discovery) accepts an optional output query parameter that selects the response shape. A single detail-level token may be combined with modifier tokens; specifying two detail levels (e.g. ?output=terse,standard) returns HTTP 400. When output= is omitted, responses are full and byte-for-byte unchanged.

Use terse for share pickers, share-link previews, and navigation sidebars — it carries the ID, title, type (Send/Receive/Exchange), access level, the share's root node id as a top-level share_root_id scalar (what layouts and transfer pages need to scope navigation), and a creator user id so "Shared by {creator}" rows can resolve via the user cache without pulling the full share-link object. Use standard for share list views and the summary card on share detail pages — it adds storage mode, folder binding, the full share_link object, timestamps, expiration, the caller's membership status, the locked lifecycle chip (admin-only), and the download_security badge (high/medium/off) that share-list rows render. Use full (or omit the parameter) for the share settings screen, branding editors, password configuration, invite link management, and any workflow that reads capability or permission matrices. 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.

Create Share

Path Parameters

Required Parameters

Optional Parameters

Request Example

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/create/share/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "share_type=send&intelligence=true&access_options=Anyone+with+the+link&title=Client+Deliverables"

Response

Status: 200 OK

{
  "result": true,
  "share": {
    "id": "9876543210987654321",
    "custom_name": "aB3cD4eF5g",
    "storage_mode": "independent",
    "share_category": "portal"
  }
}

For workspace folder shares, the response also includes folder_node_id.

Response Fields

Error Responses

Share Details

Path Parameters

Request Example

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

Response

Status: 200 OK

{
  "result": true,
  "share": {
    "id": "1234567890123456789",
    "title": "Q4 Financial Reports",
    "description": "Quarterly financial documents",
    "share_type": "exchange",
    "custom_name": "q4-reports",
    "storage_mode": "independent",
    "share_category": "portal",
    "closed": false,
    "archived": false,
    "share_level": "owner",
    "share_root_id": "node_abc123def456",
    "download_security": "off",
    "activity_tracking": {
      "enabled": true,
      "owner_activity": true,
      "guest_activity": true,
      "own_activity": true,
      "all_upload_activity": false
    },
    "comments": {
      "enabled": true,
      "owner_comments_visible": true,
      "guest_comments_visible": true,
      "personal_replies_visible": true,
      "owner_replies_visible": true
    },
    "filesystem": {
      "file_creation": true,
      "file_modification": "owned",
      "file_download": "all",
      "file_view": "all",
      "folder_creation": true,
      "folder_modification": "owned"
    },
    "event_flow": {
      "enabled": true,
      "can_see_own_events": true,
      "can_see_owner_events": true,
      "can_see_guest_events": false
    },
    "multiplayer": {
      "enabled_for_user": true,
      "enabled_for_owners": true,
      "enabled_for_guests": true,
      "owners_can_see_guests": true,
      "guests_can_see_owners": false
    },
    "member_visibility": {
      "user_can_see_members": true,
      "owners_can_see_members": true,
      "guests_can_see_members": false
    },
    "invite": {
      "setting": "owners_only",
      "can_invite": true
    },
    "capabilities": {
      "can_archive": true,
      "can_set_expiration": true
    },
    "parent_type": "workspace",
    "parent_workspace": "9876543210987654321",
    "parent_org": "1122334455667788990",
    "created": "2024-01-01 10:00:00 UTC",
    "expires": "2024-12-31 23:59:59 UTC"
  }
}

Response Fields

Error Responses

Public Share Details

For password-protected shares, pass the password JWT in the x-ve-password header (obtained from the password auth endpoint).

Request Example

# Public access (no auth)
curl -X GET "https://api.fast.io/current/share/1234567890123456789/public/details/"

# Password-protected share
curl -X GET "https://api.fast.io/current/share/1234567890123456789/public/details/" \
  -H "x-ve-password: {password_jwt_token}"

# Authenticated user
curl -X GET "https://api.fast.io/current/share/1234567890123456789/public/details/" \
  -H "Authorization: Bearer {jwt_token}"

Response

Status: 200 OK

{
  "result": true,
  "share": {
    "id": "1234567890123456789",
    "title": "Q4 Financial Reports",
    "share_type": "exchange",
    "storage_mode": "independent",
    "share_category": "portal"
  },
  "owner": {
    "id": "9988776655443322110",
    "display_name": "Jane Smith",
    "avatar": "https://..."
  },
  "nodes": [
    {
      "id": "aB3cD4eF5g",
      "name": "report.pdf",
      "type": "file",
      "size": 1048576,
      "parent": "root"
    }
  ],
  "users": [
    {
      "id": "1122334455667788990",
      "display_name": "John Doe",
      "role": "guest"
    }
  ],
  "comments": [],
  "org": {
    "id": "5566778899001122334",
    "name": "Acme Corp"
  }
}

Response Fields

Error Responses

Update Share

Request Body (All Fields Optional)

Request Example

curl -X POST "https://api.fast.io/current/share/1234567890123456789/update/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "title=Updated+Title&description=New+description&share_type=exchange"

Response

Status: 200 OK

{
  "result": true
}

Important Behaviors

• Password auto-clear: Changing access away from 'Anyone with the link' automatically clears the password.
• Access auto-upgrade: Enabling comments or notification settings that require user identity automatically upgrades access from 'Anyone with the link' to 'Anyone with a registered account'.
• Share type auto-upgrade: Changing to receive or exchange while access is 'Anyone with the link' upgrades access to 'Anyone with a registered account'.
• Intelligence: Can be enabled and disabled. Enabling requires both the content_ai and ai_agent plan features — plans that lack either are rejected with 1605 (Invalid Input). Disabling destroys indexed embeddings (vector index is flushed). Re-enabling incurs re-indexing costs (AI credits consumed to re-index all files).
• Expiration: Workspace folder shares cannot have expiration dates. Expiration is validated against the billing plan.
• Share link sync: Updating the share name automatically renames any associated workspace share link node.

Error Responses

Delete Share

Request Body

Request Example

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

Response

Status: 202 Accepted

{
  "result": true
}

Error Responses

Notes

• Soft delete with retention period before permanent removal.
• For workspace folder shares, the share reference in the backing folder is cleaned up.
• Share link nodes in the parent workspace are also removed.

Archive / Unarchive

No request body required.

Request Example

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

Response

Status: 202 Accepted

{
  "result": true
}

Error Responses

Notes

• Archived shares block guest access.
• Unarchiving requires that the billing plan supports this feature.

Password Protection

Available only on Send shares with 'Anyone with the link' access.

Set/Update Password

Set via password parameter on create or update (4-128 chars). Send "null" or "" to clear.

Authenticate with Password

Request Body

Request Example

curl -X POST "https://api.fast.io/current/share/1234567890123456789/auth/password/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "password=mysecretpassword"

Response

Status: 200 OK

{
  "result": true,
  "expires_in": 86400,
  "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response Fields

Error Responses

Notes

• Token expires after 24 hours.
• If the share's password is changed, all previously issued tokens become invalid.
• Use the returned token in the x-ve-password header for subsequent share requests.

Anonymous File Drop (Guest Auth)

Enables anonymous file uploads on public Receive and Exchange shares without requiring account registration. Visitors obtain a scoped JWT via the guest auth endpoint, then use it as a Bearer token for subsequent upload requests.

Requirements:

• Share must have 'Anyone with the link' access
• Share must be Receive or Exchange type
• anonymous_uploads_enabled must be true on the share
• Premium plan required

Authenticate as Guest

Request

No body required. POST request only.

Request Example

curl -X POST "https://api.fast.io/current/share/1234567890123456789/auth/guest/"

Response

Status: 200 OK

{
  "result": true,
  "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600
}

Response Fields

Error Responses

Notes

• The returned auth_token should be used as a Bearer token in the Authorization header for subsequent upload requests.
• Each guest auth call creates a new ephemeral user account scoped to the share.
• Tokens are short-lived; obtain a new token if the previous one expires.

Anonymous Upload Workflow

1. Check share eligibility: GET /current/share/{share_id}/public/details/ — verify anonymous_uploads_enabled: true in the response.
2. Obtain guest token: POST /current/share/{share_id}/auth/guest/ — returns a scoped auth_token.
3. Upload files: Use the standard upload flow (POST /current/upload/init/, chunk upload, POST /current/upload/complete/) with Authorization: Bearer {auth_token}.
4. Add to share: POST /current/share/{share_id}/storage/addfile/ with the upload key, using the same Bearer token.

Expiration

Available only on portal shares (not workspace folder).

Set the expires parameter (datetime format: YYYY-MM-DD HH:MM:SS) on create or update. Send "null" to clear. When the share expires, access is revoked. Expiration is validated against the billing plan.

Branding & Styling

Shares support custom branding through the update endpoint:

Send "null" for any JSON field to clear it.

Share Assets

List Available Asset Types

List Share Assets

Upload/Set Asset

Request Example

curl -X POST "https://api.fast.io/current/share/1234567890123456789/assets/logo/" \
  -H "Authorization: Bearer {jwt_token}" \
  -F "file=@logo.png" \
  -F 'metadata={"crop_x": 0, "crop_y": 0}'

Delete Asset

Read Asset Binary

Share Members

Permission Levels

Notification Options

Add Member or Send Invitation

Request Body (Adding Existing User)

Request Body (Inviting by Email)

Request Example

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

# Invite by email
curl -X POST "https://api.fast.io/current/share/1234567890123456789/members/newuser@example.com/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d '{"permissions": "guest", "message": "Join our shared files!"}'

Response (Invitation Created)

{
  "result": true,
  "invitation": {
    "id": "5566778899001122334",
    "inviter": "Jane Smith",
    "invitee_email": "newuser@example.com",
    "invitee_uid": null,
    "accepted_uid": null,
    "entity_type": "share",
    "share": {
      "id": "1234567890123456789",
      "name": "Project Files"
    },
    "state": "pending",
    "consumed": false,
    "created": "2025-01-15 10:30:00 UTC",
    "updated": "2025-01-15 10:30:00 UTC",
    "expires": "2025-02-15 10:30:00 UTC"
  }
}

Error Responses

Remove Member

Leave Share (Self-Removal)

Member Details

Response

{
  "result": true,
  "user": {
    "id": "9876543210987654321",
    "account_type": "human",
    "email_address": "member@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "permissions": "admin",
    "status": "active",
    "invite": null,
    "notify": "Notify me in app",
    "expires": null
  }
}

Update Member

Transfer Ownership

List Members

Response

{
  "result": true,
  "users": [
    {
      "id": "1111111111111111111",
      "account_type": "human",
      "email_address": "owner@example.com",
      "first_name": "Jane",
      "last_name": "Smith",
      "permissions": "owner",
      "status": "active",
      "invite": null,
      "notify": "Notify me in app",
      "expires": null
    },
    {
      "id": "5566778899001122334",
      "account_type": "human",
      "email_address": "invited@example.com",
      "first_name": "invited@example.com",
      "last_name": "",
      "permissions": "guest",
      "status": "pending",
      "invite": {
        "id": "5566778899001122334",
        "created": "2025-01-15 10:30:00 UTC",
        "expires": "2025-02-15 10:30:00 UTC"
      },
      "notify": "Notify me in app",
      "expires": null
    }
  ]
}

Pending Members

When a user is invited to a share by email but does not yet have a Fastio account, they appear as a pending member in the member list. Pending members are placeholders that allow teams to pre-assign workflow items before the invitee signs up.

How pending members appear in responses:

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

Workflow assignments: On a share, guests (including still-pending invitees) have no workflow access — they cannot be assigned to an approval, task, or todo step, and share guests cannot use the Tasks API. Workflow approval reviewers must be workspace members; external non-member reviewers require the workspace's native-review tier to be extended. Newly created workspaces default to the extended tier (external reviewers available out of the box); a workspace that predates that default, or whose tier was explicitly set to mvs or cleared, supports external reviewers only after a workspace admin sets the extended tier via the workspace update endpoint.

Account claim: When the invited user signs up or accepts the invitation with an existing account, their status transitions from "pending" to "active". Their share access is preserved across the transition.

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

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

Join Share

Self-join rules (without invitation key):

Self-joined members receive member permission with no expiration. Only notify_options is respected from input.

List Invitations

Update Invitation

Delete Invitation

Share Discovery

List All Shares

Response Fields

Each share in the shares array includes the same fields as the details endpoint, plus:

List Available Shares

Check Share Name Availability

Status 202 Accepted = name available.

List Shares in Workspace

List User's Shares

Import Share into Workspace

Error Responses

Share AI

Shares support AI features when intelligence is enabled. Enabling intelligence and creating or sending chat messages require plan features (content_ai plus ai_agent for write/agentic flows). See the AI reference for the full plan matrix.

Auto-Generate OG Image

Auto-Generate Title & Description

AI Chat

Share AI chat follows the same patterns as workspace AI chat. Replace /workspace/{id} with /share/{id} in all chat endpoints. For full AI chat documentation, see AI & Chat reference.

Endpoints

QuickShare (Workspace Feature)

QuickShare creates a temporary public link for a single file. This is a workspace storage feature, not a share management feature, but is related to sharing.

Create QuickShare (deprecated → 403)

QuickShare Details (Public)

Response

{
  "result": true,
  "quickshare": {
    "id": "aBcDeFgHiJ",
    "node": {
      "id": "1234567890123456789",
      "type": "file",
      "name": "presentation.pdf",
      "size": 5242880,
      "mimetype": "application/pdf",
      "mimecategory": "document"
    },
    "creator_uid": {
      "id": "9876543210987654321",
      "account_type": "human",
      "first_name": "Jane",
      "last_name": "Doe"
    },
    "limit_exceeded": false,
    "expires": "2024-01-15 13:30:00 UTC",
    "created": "2024-01-15 10:30:00 UTC"
  }
}

Download File (Public)

Transfer Limits:

• Max total bytes: 10 GB
• Max multiplier: 100x file size
• Once either limit is reached, limit_exceeded is set permanently.

Read Note Content (Public)

Response

{
  "result": true,
  "content": "# Note content here\n\nMarkdown text...",
  "note": {
    "id": "{opaque_note_id}",
    "type": "note",
    "name": "my-note.md",
    "size": 1024,
    "mimetype": "text/markdown",
    "mimecategory": "document"
  }
}

Error responses: Returns 1605 (Invalid Input) (400) if the node is not a note, 1609 (Not Found) (404) if the quickshare is not found or the note is in trash, 1656 (Bandwidth Limit) (429) if the transfer limit is reached, or 1680 (Access Denied) (403) if the file is inaccessible (virus/DMCA/locked).

Preview File (Public)

Preview Limits: Max 20x file size for total preview bytes.

Multi-file previews (e.g., HLS) return a 307 Temporary Redirect to a sub-file endpoint.

QuickShare Error Responses

File Share (Durable Single-File Share)

A File Share is the durable successor to QuickShare: a long-lived, link-shareable view of one file from a workspace. Unlike QuickShare it is durable by default (expiry is optional, never forced) and has no per-link transfer cap — bandwidth is metered to the owning organization. A File Share is bound to a single workspace file node at creation; the binding is immutable (rebinding means creating a new File Share).

Addressing — opaque id. A File Share is addressed by an opaque public id (the id_alt field): an unguessable, non-enumerable handle (the same id shape used for nodes and uploads), which appears in its share links. Every File Share route — public read and management alike — accepts this opaque id; the legacy numeric profile id is also accepted during the transition, so existing links keep working. Build links from id_alt.

Access Tiers

Set with access_option at create/update time:

On top of the tier, per-user grants raise an individual user's capability — view, download, or edit. An optional link password can gate any tier; it is supplied on the public read endpoints via the x-ve-password request header, never in the URL.

Workspace members (implicit access). The shared file lives in the File Share's parent workspace, so an authenticated member of that workspace reaches it through the File Share exactly as they would through the workspace itself — admitted regardless of tier or named grant, at the capability their workspace role confers on the file (a workspace editor gets edit, a view-only member gets view). This is why the owner/creator and other workspace members can view — and collaboratively edit notes on — their own named_people share without granting themselves. A set link password still applies to members. Anonymous callers and non-members are governed solely by the tier + grant rules above.

Public Read Endpoints

These serve the link viewer. They are anonymous-allowed where the access tier permits (e.g. anyone_with_link); for any_registered / named_people the caller must present a bearer token and have sufficient access.

The effective_capability field is the single highest capability the calling identity actually holds on this File Share — view, download, or edit — resolved after the access tier, any per-user grant, and the link password are all applied. Use it to render the right controls up front (show the Download button only at download or higher; show “Upload new version” only at edit) instead of attempting an action and handling a later denial. Because the details response is only returned once the caller has passed the read gate, the value is present and at least view on the normal path; it is omitted only in the rare case the capability probe itself faults — treat an absent value as “unknown” and fall back to attempting the action.

Manage context (authenticated callers only). The details response additionally carries an optional manage block so an owner’s UI can decide whether to surface in-place management controls without a separate lookup:

• can_manage (boolean) — true when the authenticated caller may manage this File Share (a member of its parent workspace, the same requirement the management endpoints enforce), false when authenticated but not a manager. Omitted entirely for anonymous callers, so the public link stays anonymous.
• workspace_id (string) — the owning workspace id, returned only when can_manage is true. Pass it to the workspace-scoped management endpoints (list / update / grants / delete). A non-manager never receives it.
• creator_uid (string) — the File Share creator’s user id, returned only when can_manage is true.

These fields are additive — anonymous viewers and clients that ignore them are unaffected.

Details Response (authenticated manager)

{
  "result": true,
  "fileshare": {
    "fileshare": "1234567890123456789",
    "id_alt": "a2bk7yqe9z3w8h5n6m4xp1c0tv7rs",
    "title": "Quarterly Presentation",
    "access_option": "anyone_with_link",
    "has_password": false,
    "effective_capability": "download",
    "can_manage": true,
    "workspace_id": "9876543210987654321",
    "creator_uid": "1122334455667788990",
    "file": {
      "id": "f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjf",
      "type": "file",
      "name": "presentation.pdf",
      "size": 5242880,
      "mimetype": "application/pdf"
    }
  }
}

For an anonymous viewer the three manage fields are absent; for an authenticated non-manager only can_manage: false is present (no workspace_id / creator_uid).

Management Endpoints (Authenticated Workspace Member)

Creating, listing, updating, deleting, and managing grants are documented in the Workspaces reference (POST /current/workspace/{workspace_id}/create/fileshare/, GET /current/workspace/{workspace_id}/list/fileshares/, and the POST|PATCH /current/fileshare/{id}/update/, DELETE /current/fileshare/{id}/delete/, GET|POST|DELETE /current/fileshare/{id}/grants/ endpoints). All require the caller to be an authenticated member of the File Share's parent workspace.

External Edit (Write-Back)

A holder of an edit grant can replace the shared file's content without being a workspace member, by targeting the File Share id as the update target of a normal upload session. This is covered in the Upload reference (action=update, instance_id={fileshare_id}, file_id={bound_node_id}), including the optional if_version_id compare-and-swap precondition and how a version conflict is surfaced.

Collaborative Notes (Realtime)

When the bound file is a note (a .md text document), an authorized recipient can read and collaboratively edit it in real time rather than downloading and re-uploading binary content. Real-time edits from a File Share recipient and from members of the owning workspace converge on the same live document — there is no forking or separate copy. A note bound to a File Share cannot be replaced by a binary upload; its content changes only through the endpoints below or the real-time collaboration session.

The flow is: mint a short-lived collaboration token with the note-auth endpoint, then use that token (not your session bearer token) to read the note's text and, if you hold an edit grant, to push updates. The same token is what a client presents to join the real-time collaboration session.

Note-Auth Response

{
  "expires_in": 900,
  "auth_token": "..."
}

Owner-Side Visibility (Comments)

A File Share is a view of a file that also lives in the owning workspace, so comments left by File Share recipients are visible to workspace members on that same file — it's the same node, so the comments appear in both places. For a workspace member:

• Activity feed — File Share comment activity surfaces on the owning workspace's realtime / activity feed, so workspace members see when a recipient comments (the nudge carries no comment text).
• File comments — the workspace node comment list for the bound file includes the File Share's comments alongside the workspace's own. They appear read-only in the workspace view (can_reply / can_edit / can_delete are false) — replies and edits to a File Share comment go through the File Share's own surface.
• Workspace search — the workspace comments search bucket includes comments left through the workspace's live (active, non-expired, non-revoked) File Shares.

This visibility is one-directional: workspace ⊇ File Share. Workspace members see File Share comments, but File Share recipients never see the workspace's internal comments — a recipient's view stays isolated to their own File Share's comment thread.

File Share Error Responses

Share Workflow

Shares support the Tasks feature (task lists) when workflow is enabled. Workflow requires the workflow billing plan feature, which is also required for workflow orchestration.

Enable Workflow

Response

Status: 200 OK

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

Disable Workflow

Response

Status: 200 OK

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

List Task Lists

Response

Status: 200 OK

{
  "result": true,
  "task_lists": [
    {
      "id": "aBcDeFgHiJ",
      "profile_id": "1234567890123456789",
      "name": "Sprint 1",
      "description": "First sprint tasks",
      "created_by": "9876543210987654321",
      "properties": {},
      "sort_order": 0,
      "created": "2026-01-15 10:30:00 UTC",
      "updated": "2026-01-15 10:30:00 UTC",
      "deleted": null
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 1
  }
}

Create Task List

Request Body

Request Example

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

Response

Status: 200 OK

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

Error Responses

Reorder Task Lists

Request Body

Each entry in order:

Request Example

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

Response

Status: 200 OK

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

Error Responses

Workflow-Native Sign-off & Checklists

For human sign-off on a share's files use workflow review via either approval step type — both produce a reviewer roster, version-pinned assets, a per-reviewer per-asset decision matrix, and a resolution policy. The lock-based approval step pulls the reviewed files into workspace storage and write-locks them while the review is pending, releasing them on resolution. The in-place approval_in_place step instead reviews the files where they already live in the share/portal/file share with no move/copy/lock — the approved version is version-stamped and content-hashed for durable audit and later changes surface as drift. The fastest way to start an in-place review on a single file is the "Request approval" quick path (POST /current/workflow-review/quick-approval/), which provisions a private file share for the chosen reviewers and starts a one-step in-place approval run in a single call (single file, members-only roster in v1; for multi-file or external reviewers, author an approval_in_place step in a workflow). For checklist items use the workflow todo step (both step types in the workflow orchestration tool). The Tasks API (task lists & tasks) is the supported task-tracking surface. See the Workflow reference for these surfaces.

Workflow Error Responses (Shared)

All workflow endpoints (tasks, enable/disable) share these common errors:

Share Storage

Share storage follows the same API patterns as workspace storage. See Storage reference for full endpoint documentation.

Replace /workspace/{workspace_id} with /share/{share_id} in all storage paths. Available operations:

• addfile — add file from upload
• createfolder — create folder
• list — list folder contents (keyset pagination)
• details — node details
• update — rename, replace content
• move — move within share
• copy — copy within share
• transfer — copy to another storage instance
• delete — move to trash
• purge — permanently delete from trash
• restore — restore from trash
• restore-version — restore previous version
• versions — list version history
• read — download file
• requestread — get download token
• zip — download folder as ZIP
• search — keyword search
• preview — file previews (preauthorize, read, token-based read)
• transform — image transforms (status, request, read, requestread)
• requestpreview — one-time preview nonce (shares with download_security=medium only)
• readnote — read note content as JSON (token-based access supported)
• lock — file locking (acquire, heartbeat, release, status)

Not available in shares: addlink, createnote, updatenote, quickshare