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

Shares are purpose-built data rooms 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)

Room (storage_mode=independent, default)

The share has its own isolated storage. Files added to the room are independent of any workspace. Changes to workspace files do not affect the room, 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 data room with file preview, download controls, and all share features.

Access Options

The access_options parameter controls who can access the share:

Restrictions:

• Receive and Exchange shares cannot use 'Anyone with the link' because 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'.

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"
    }
  },
  "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",
      "closed": false,
      "archived": false,
      "share_level": "owner",
      "download_enabled": true,
      "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"
    },
    "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 the KEY_SHARE_UNARCHIVE_ALLOWED billing plan feature flag.

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.

Expiration

Available only on room shares (not workspace folder).

Set the expires parameter (MySQL 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.

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