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.

Create Share

Path Parameters

Required Parameters

Optional Parameters

Request Example

curl -X POST "https://api.fast.io/current/workspace/12345678901234567890/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": "yes",
  "response": {
    "share": {
      "id": "98765432109876543210",
      "custom_name": "aB3cD4eF5g",
      "storage_mode": "independent",
      "share_category": "portal"
    }
  },
  "current_api_version": "1.0"
}

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/12345678901234567890/details/" \
  -H "Authorization: Bearer {jwt_token}"

Response

Status: 200 OK

{
  "result": "yes",
  "response": {
    "share": {
      "id": "12345678901234567890",
      "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",
      "download_enabled": true,
      "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": "98765432109876543210",
      "parent_org": "11223344556677889900",
      "created": "2024-01-01 10:00:00",
      "expires": "2024-12-31 23:59:59"
    }
  },
  "current_api_version": "1.0"
}

Response Fields

Error Responses

Public Share Details

Rate Limits: 3/3s, 15/10s, 20/60s, 50/hour, 200/day (per IP).

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/12345678901234567890/public/details/"

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

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

Response

Status: 200 OK

{
  "result": "yes",
  "response": {
    "share": {
      "id": "12345678901234567890",
      "title": "Q4 Financial Reports",
      "share_type": "exchange",
      "storage_mode": "independent",
      "share_category": "portal"
    },
    "owner": {
      "id": "99887766554433221100",
      "display_name": "Jane Smith",
      "avatar": "https://..."
    },
    "nodes": [
      {
        "id": "aB3cD4eF5g",
        "name": "report.pdf",
        "type": "file",
        "size": 1048576,
        "parent": "root"
      }
    ],
    "users": [
      {
        "id": "11223344556677889900",
        "display_name": "John Doe",
        "role": "guest"
      }
    ],
    "comments": [],
    "org": {
      "id": "55667788990011223344",
      "name": "Acme Corp"
    }
  },
  "current_api_version": "1.0"
}

Response Fields

Error Responses

Update Share

Rate Limits: 5/3s, 20/30s, 50/5min, 300/hour, 500/day (per share + user).

Request Body (All Fields Optional)

Request Example

curl -X POST "https://api.fast.io/current/share/12345678901234567890/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": "yes",
  "current_api_version": "1.0"
}

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: Once disabled, intelligence cannot be re-enabled.
• 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

Rate Limits: 100/5min, 3000/hour, 5000/day (per workspace).

Request Body

Request Example

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

Response

Status: 202 Accepted

{
  "result": "yes",
  "current_api_version": "1.0"
}

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

Rate Limits (archive): 100/5min, 3000/hour, 5000/day (per workspace).

Rate Limits (unarchive): 50/5min, 300/hour, 500/day (per share).

No request body required.

Request Example

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

Response

Status: 202 Accepted

{
  "result": "yes",
  "current_api_version": "1.0"
}

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

Rate Limits: 3/3s, 10/10s, 15/60s, 30/hour, 100/day (per IP). Heavily rate-limited to prevent brute force.

Request Body

Request Example

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

Response

Status: 200 OK

{
  "result": "yes",
  "response": {
    "expires_in": 86400,
    "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "current_api_version": "1.0"
}

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

Rate Limits: 3/3s, 10/10s, 15/60s, 30/hour, 100/day (per IP).

Request

No body required. POST request only.

Request Example

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

Response

Status: 200 OK

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

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/12345678901234567890/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

Rate Limits: 15/3s, 25/10s, 50/60s, 100/hour, 1000/day.

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/12345678901234567890/members/98765432109876543210/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d '{"permissions": "member"}'

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

Response (Invitation Created)

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

Error Responses

Remove Member

Rate Limits: 15/3s, 25/10s, 50/60s, 100/hour, 1000/day.

Leave Share (Self-Removal)

Member Details

Rate Limits: 200/3s, 500/10s, 750/60s, 1000/hour, 2500/day.

Response

{
  "result": "yes",
  "response": {
    "user": {
      "id": "98765432109876543210",
      "account_type": "human",
      "email_address": "member@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "permissions": "admin",
      "invite": null,
      "notify": "Notify me in app",
      "expires": null
    }
  },
  "current_api_version": "1.0"
}

Update Member

Rate Limits: 10/3s, 25/10s, 50/60s, 100/hour, 1000/day.

Transfer Ownership

Rate Limits: 10/3s, 25/10s, 50/60s, 100/hour, 1000/day.

List Members

Rate Limits: 20/3s, 50/10s, 200/60s, 500/hour, 10000/day.

Response

{
  "result": "yes",
  "response": {
    "users": [
      {
        "id": "11111111111111111111",
        "account_type": "human",
        "email_address": "owner@example.com",
        "first_name": "Jane",
        "last_name": "Smith",
        "permissions": "owner",
        "invite": null,
        "notify": "Notify me in app",
        "expires": null
      }
    ]
  },
  "current_api_version": "1.0"
}

Join Share

Rate Limits: 10/3s, 25/10s, 50/60s, 100/hour, 1000/day.

Self-join rules (without invitation key):

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

List Invitations

Rate Limits: 10/3s, 25/10s, 50/60s, 100/hour, 1000/day.

Update Invitation

Rate Limits: 10/60s, 20/600s, 30/hour.

Delete Invitation

Rate Limits: 10/60s, 20/600s, 30/hour.

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

Rate Limits: 5/3s, 30/10s, 60/60s, 250/hour, 1000/day (per user).

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.

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

QuickShare Details (Public)

Rate Limits: 3/3s, 15/10s, 20/60s, 50/hour, 200/day (per IP).

Response

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

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": "yes",
  "response": {
    "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 APP_ERROR_INPUT_INVALID (400) if the node is not a note, APP_ERROR_NOT_FOUND (404) if the quickshare is not found or the note is in trash, APP_BANDWIDTH_LIMIT (429) if the transfer limit is reached, or APP_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

Share Workflow

Shares support workflow features (task lists, todo items, and approvals) when enabled. Workflow requires the workflow billing plan feature.

Enable Workflow

Rate Limits: 1/3s, 5/10s, 20/60s, 100/hour (per share + user).

Response

Status: 200 OK

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

Disable Workflow

Rate Limits: 1/3s, 5/10s, 20/60s, 100/hour (per share + user).

Response

Status: 200 OK

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

List Task Lists

Response

Status: 200 OK

{
  "result": true,
  "response": {
    "task_lists": [
      {
        "id": "aBcDeFgHiJ",
        "profile_id": "12345678901234567890",
        "name": "Sprint 1",
        "description": "First sprint tasks",
        "created_by": "98765432109876543210",
        "properties": {},
        "sort_order": 0,
        "created": "2026-01-15T10:30:00+00:00",
        "updated": "2026-01-15T10:30:00+00:00",
        "deleted": null
      }
    ],
    "pagination": {
      "limit": 50,
      "offset": 0,
      "total": 1
    }
  },
  "current_api_version": "1.0"
}

Create Task List

Request Body

Request Example

curl -X POST "https://api.fast.io/current/share/12345678901234567890/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,
  "response": {
    "task_list": {
      "id": "aBcDeFgHiJ",
      "profile_id": "12345678901234567890",
      "name": "Sprint 1",
      "description": "First sprint tasks",
      "created_by": "98765432109876543210",
      "properties": {},
      "sort_order": 0,
      "created": "2026-01-15T10:30:00+00:00",
      "updated": "2026-01-15T10:30:00+00:00",
      "deleted": null
    }
  },
  "current_api_version": "1.0"
}

Error Responses

Reorder Task Lists

Request Body

Each entry in order:

Request Example

curl -X POST "https://api.fast.io/current/share/12345678901234567890/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,
  "response": {
    "reordered": 2,
    "profile_id": "12345678901234567890"
  },
  "current_api_version": "1.0"
}

Error Responses

List Todo Items

Response

Status: 200 OK

{
  "result": true,
  "response": {
    "todos": [
      {
        "id": "aBcDeFgHiJ",
        "profile_id": "12345678901234567890",
        "title": "Review document",
        "done": 0,
        "assignee_id": "98765432109876543210",
        "sort_order": 0,
        "created_by": "98765432109876543210",
        "properties": null,
        "created": "2026-01-15T10:30:00+00:00",
        "updated": "2026-01-15T10:30:00+00:00",
        "deleted": null
      }
    ],
    "pagination": {
      "limit": 50,
      "offset": 0,
      "total": 1
    }
  },
  "current_api_version": "1.0"
}

Create Todo Item

Request Body

Request Example

curl -X POST "https://api.fast.io/current/share/12345678901234567890/todos/create/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{"title": "Review document", "assignee_id": "98765432109876543210"}'

Response

Status: 200 OK

{
  "result": true,
  "response": {
    "todo": {
      "id": "aBcDeFgHiJ",
      "profile_id": "12345678901234567890",
      "title": "Review document",
      "done": 0,
      "assignee_id": "98765432109876543210",
      "sort_order": 0,
      "created_by": "98765432109876543210",
      "properties": null,
      "created": "2026-01-15T10:30:00+00:00",
      "updated": "2026-01-15T10:30:00+00:00",
      "deleted": null
    }
  },
  "current_api_version": "1.0"
}

Error Responses

Bulk Toggle Todos

Request Body

Request Example

curl -X POST "https://api.fast.io/current/share/12345678901234567890/todos/bulk-toggle/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{"todo_ids": ["aBcDeFgHiJ", "kLmNoPqRsT"], "done": true}'

Response

Status: 200 OK

{
  "result": true,
  "response": {
    "toggled": 2,
    "done": true
  },
  "current_api_version": "1.0"
}

Error Responses

List Approvals

Query Parameters

Response

Status: 200 OK

{
  "result": true,
  "response": {
    "approvals": [
      {
        "id": "aBcDeFgHiJ",
        "entity_type": "task",
        "entity_id": "kLmNoPqRsT",
        "profile_id": "12345678901234567890",
        "requested_by": "98765432109876543210",
        "description": "Please review this task",
        "status": "pending",
        "approver_id": "11223344556677889900",
        "resolved_by": null,
        "resolved_at": null,
        "comment": null,
        "deadline": "2026-02-01T00:00:00+00:00",
        "node_id": null,
        "properties": {},
        "created": "2026-01-15T10:30:00+00:00",
        "updated": "2026-01-15T10:30:00+00:00"
      }
    ],
    "pagination": {
      "limit": 50,
      "offset": 0,
      "total": 1
    }
  },
  "current_api_version": "1.0"
}

Response Fields

Error Responses

Workflow Error Responses (Shared)

All workflow endpoints (tasks, todos, approvals, 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)
• lock — file locking (acquire, heartbeat, release, status)

Not available in shares: addlink, createnote, updatenote, quickshare, transform/requestread