Storage Operations File and folder operations, locking, previews, and transforms

Storage endpoints are available on both workspaces and shares. The API patterns are identical — replace workspace/{workspace_id} with share/{share_id} in any path below unless noted as workspace-only or share-only.

All endpoints require JWT authentication unless otherwise noted. Include the header Authorization: Bearer {jwt_token} with every request.

Conventions

• Root folder: Use the literal string "root" as the path parameter (e.g., /storage/root/list/)
• Trash folder: Use "trash" to list trashed items (e.g., /storage/trash/list/)
• Node IDs: OpaqueIds — 30-character alphanumeric strings displayed with hyphens (e.g., f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4). Use as-is in API calls.
• Node ID prefixes: f = file, d = folder, n = note
• Node types in responses: "file", "folder", "note", "link" (lowercase strings)
• Parent field: Nodes at the storage root have "parent": "root"; nested nodes show the parent's OpaqueId
• Delete vs purge: DELETE .../storage/{node_id}/delete/ moves to trash. DELETE .../storage/trash/delete/ empties the entire trash. DELETE .../storage/{node_id}/purge/ permanently deletes a single trashed item.
• Workspace folder shares: Shares that reference a workspace folder have their root mapped to the designated folder. All operations are scoped to that subtree.

Node Object Schema

All endpoints that return node data use this format. Fields vary by node type.

AI States

Keyset Pagination (Storage List)

Storage listing endpoints (list and recent) use cursor-based pagination, not offset-based.

Request Parameters

Response Pagination Fields

Notes:

• Cursors are HMAC-signed; tampered cursors are rejected with an error.
• When using a cursor, the page size from the cursor takes precedence over the request parameter.
• Only the first page of each sort configuration is cached (30-second TTL).
• The recent endpoint ignores sort_by and sort_dir (always sorted by updated descending).

List Folder Contents

Auth required. Permission: View (workspace), Guest+ (share). Share list on public shares may not require JWT.

Path Parameters

Query parameters: See Keyset Pagination section above.

curl Example

curl -X GET "https://api.fast.io/current/workspace/12345678901234567890/storage/root/list/?sort_by=name&sort_dir=asc&page_size=100" \
  -H "Authorization: Bearer {jwt_token}"

Response

{
  "result": "yes",
  "response": {
    "nodes": {
      "items": [
        {
          "id": "d1abc-defgh-ijklm-nopqr-stuvw-xyz123",
          "type": "folder",
          "name": "Documents",
          "parent": "root",
          "created": "2025-01-01T00:00:00Z",
          "modified": "2025-01-20T14:45:00Z"
        },
        {
          "id": "f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4",
          "type": "file",
          "name": "photo.jpg",
          "parent": "root",
          "size": 2048000,
          "mimetype": "image/jpeg",
          "created": "2025-01-10T09:00:00Z",
          "modified": "2025-01-10T09:00:00Z"
        }
      ],
      "path": "/",
      "parent": null
    },
    "pagination": {
      "has_more": true,
      "next_cursor": "eyJwIjoiMmFiYzEyMy4uLiIsInMi...",
      "page_size": 100
    }
  }
}

Response Fields

Error Responses

Node Details

Auth required. Permission: View (workspace), View (share).

Path Parameters

curl Example

curl -X GET "https://api.fast.io/current/workspace/12345678901234567890/storage/f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4/details/" \
  -H "Authorization: Bearer {jwt_token}"

Response

{
  "result": "yes",
  "response": {
    "node": {
      "id": "f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4",
      "type": "file",
      "name": "document.pdf",
      "parent": "d1abc-defgh-ijklm-nopqr-stuvw-xyz123",
      "size": 5242880,
      "hash": "d41d8cd98f00b204e9800998ecf8427e",
      "hash_algo": "md5",
      "mimetype": "application/pdf",
      "mimecategory": "document",
      "version": "v1",
      "created": "2025-01-15T10:30:00Z",
      "modified": "2025-01-20T14:45:00Z",
      "restricted": false,
      "dmca": false,
      "locked": false,
      "lock_info": null,
      "virus": { "status": "scanned", "infected": false },
      "file_attributes": { "width": null, "height": null, "duration": null },
      "summary": {
        "title": "Quarterly Report",
        "short": "Q4 financial summary",
        "long": "Comprehensive financial report covering revenue and expenses."
      },
      "metadata": null,
      "previews": {
        "thumbnail": { "state": "ready" },
        "pdf": { "state": "ready" }
      },
      "ai": { "state": "indexed", "attach": true },
      "origin": { "type": "upload", "creator": "98765432109876543210" }
    }
  }
}

Response fields: See Node Object Schema above for complete field reference.

Error Responses

Add File from Upload

Auth required. Permission: Guest (workspace), file creation permission (share).

Path Parameters

Request Body (form-encoded)

from format (workspace):

{"type": "upload", "upload": {"id": "{upload_id}"}}

from format (share — also supports hash source):

{"from_type": "upload", "upload": {"upload_id": "{upload_id}"}}

{"from_type": "hash", "hash": {"hash": "{file_hash}", "hash_type": "sha256"}}

curl Example

curl -X POST "https://api.fast.io/current/workspace/12345678901234567890/storage/root/addfile/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d 'name=document.pdf' \
  -d 'from={"type":"upload","upload":{"id":"abc123opaqueid"}}'

Response

{
  "result": "yes",
  "response": {
    "node": {
      "id": "f4kn6-arybw-qxes3-ey9z6-cwoc4-sglhn5",
      "type": "file",
      "name": "document.pdf",
      "parent": "root",
      "size": 5242880,
      "hash": "d41d8cd98f00b204e9800998ecf8427e",
      "hash_algo": "md5",
      "mimetype": "application/pdf",
      "mimecategory": "document",
      "version": "v1",
      "created": "2025-01-15T10:30:00Z",
      "modified": "2025-01-15T10:30:00Z",
      "restricted": false,
      "dmca": false,
      "locked": false
    }
  }
}

Error Responses

Notes:

• The upload session must be in COMPLETE status before adding the file.
• Virus scanning occurs during upload assembly, not at this stage.

Add Link (Workspace Only)

Auth required. Permission: Guest.

Path Parameters

Request Body (form-encoded)

curl Example

curl -X POST "https://api.fast.io/current/workspace/12345678901234567890/storage/root/addlink/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d 'link_target_type=share' \
  -d 'share=my-share-name'

Response

{"result": "yes"}

Error Responses

Create Folder

Auth required. Permission: Guest (workspace), folder creation permission (share).

Path Parameters

Request Body (form-encoded)

curl Example

curl -X POST "https://api.fast.io/current/workspace/12345678901234567890/storage/root/createfolder/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d 'name=Documents'

Response

{
  "result": "yes",
  "response": {
    "node": {
      "id": "d2bcd-efghi-jklmn-opqrs-tuvwx-yz1234",
      "type": "folder",
      "name": "Documents",
      "parent": "root",
      "created": "2025-01-15T10:30:00Z",
      "modified": "2025-01-15T10:30:00Z",
      "restricted": false,
      "dmca": false,
      "locked": false
    }
  }
}

Error Responses

Create Note (Workspace Only)

Auth required. Permission: Guest.

Path Parameters

Request Body (form-encoded)

curl Example

curl -X POST "https://api.fast.io/current/workspace/12345678901234567890/storage/root/createnote/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d 'name=meeting-notes.md' \
  -d 'content=# Meeting Notes\n\nDiscussed project timeline.'

Response

{
  "result": "yes",
  "response": {
    "note": {
      "id": "n5mno-pqrst-uvwxy-z1234-abcde-fghij6",
      "type": "note",
      "name": "meeting-notes.md",
      "parent": "root",
      "mimetype": "text/markdown",
      "created": "2025-01-15T10:30:00Z",
      "modified": "2025-01-15T10:30:00Z"
    }
  }
}

Error Responses

Update Note (Workspace Only)

Auth required. Permission: Guest.

Path Parameters

Request Body (form-encoded)

At least one of name or content is required.

curl Example

curl -X POST "https://api.fast.io/current/workspace/12345678901234567890/storage/n5mno-pqrst-uvwxy-z1234-abcde-fghij6/updatenote/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d 'content=# Updated Notes\n\nRevised content here.'

Response

{
  "result": "yes",
  "response": {
    "note": {
      "id": "n5mno-pqrst-uvwxy-z1234-abcde-fghij6",
      "type": "note",
      "name": "meeting-notes.md",
      "parent": "root",
      "mimetype": "text/markdown",
      "created": "2025-01-15T10:30:00Z",
      "modified": "2025-01-20T14:45:00Z"
    }
  }
}

Error Responses

Update Node

Auth required. Permission: Guest (workspace), file modification permission (share).

Path Parameters

Request Body (form-encoded)

At least one field should be provided.

curl Example (rename)

curl -X POST "https://api.fast.io/current/workspace/12345678901234567890/storage/f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4/update/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d 'name=new-document-name.pdf'

curl Example (replace content and update metadata)

curl -X POST "https://api.fast.io/current/workspace/12345678901234567890/storage/f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4/update/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d 'from={"type":"upload","upload":{"id":"upload_opaque_id"}}' \
  -d 'metadata_title=Updated Report' \
  -d 'metadata_short=Q1 2025 revision'

Response

{
  "result": "yes",
  "response": {
    "node": {
      "id": "f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4",
      "type": "file",
      "name": "new-document-name.pdf",
      "parent": "root",
      "size": 5242880,
      "version": "v2",
      "modified": "2025-01-22T11:00:00Z"
    }
  }
}

Error Responses

Notes:

• Replacing content creates a new version.
• Renaming a link node propagates the rename to the linked share.
• Custom metadata overrides AI-generated summary values for display.

Move Node

Auth required. Permission: Guest (workspace), file modification permission (share).

Path Parameters

Request Body (form-encoded)

curl Example

curl -X POST "https://api.fast.io/current/workspace/12345678901234567890/storage/f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4/move/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d 'parent=d1abc-defgh-ijklm-nopqr-stuvw-xyz123'

Response

{"result": "yes"}

Error Responses

Copy Node

Auth required. Permission: Guest (workspace), file/folder creation permission (share).

Path Parameters

Request Body (form-encoded)

curl Example

curl -X POST "https://api.fast.io/current/workspace/12345678901234567890/storage/f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4/copy/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d 'parent=d1abc-defgh-ijklm-nopqr-stuvw-xyz123'

Response

{
  "result": "yes",
  "response": {
    "node": {
      "id": "f6qrs-tuvwx-yz123-abcde-fghij-klmno7",
      "type": "file",
      "name": "document.pdf",
      "parent": "d1abc-defgh-ijklm-nopqr-stuvw-xyz123"
    },
    "job": null
  }
}

Error Responses

Notes:

• Creates a deep copy for folders (all children are copied recursively).
• The copied node gets a new OpaqueId.

Transfer Node

Auth required. Permission: Guest on source + write access on destination.

Path Parameters

Request Body (form-encoded)

curl Example

curl -X POST "https://api.fast.io/current/workspace/12345678901234567890/storage/f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4/transfer/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d 'instance=98765432109876543210' \
  -d 'parent=root'

Response

{
  "result": "yes",
  "response": {
    "node": {
      "id": "f7stu-vwxyz-12345-abcde-fghij-klmno8",
      "type": "file",
      "name": "document.pdf",
      "parent": "root"
    },
    "job": null
  }
}

Error Responses

Notes:

• Folder transfers are recursive.
• The user must have write access to both source and destination.

Delete Node (Move to Trash)

Auth required. Permission: Guest (workspace), file modification permission (share). Emptying trash on shares requires admin permission.

Path Parameters

curl Examples

# Delete a specific node
curl -X DELETE "https://api.fast.io/current/workspace/12345678901234567890/storage/f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4/delete/" \
  -H "Authorization: Bearer {jwt_token}"

# Empty the trash
curl -X DELETE "https://api.fast.io/current/workspace/12345678901234567890/storage/trash/delete/" \
  -H "Authorization: Bearer {jwt_token}"

Response

{
  "result": "yes",
  "response": {
    "job": null
  }
}

Error Responses

Notes:

• Deleting a folder moves it and all children to trash recursively.
• Share delete permissions may be restricted to files the user created.

Purge Node (Permanent Delete)

Auth required. Permission: Member (workspace), admin (share).

Path Parameters

curl Example

curl -X DELETE "https://api.fast.io/current/workspace/12345678901234567890/storage/f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4/purge/" \
  -H "Authorization: Bearer {jwt_token}"

Response

{
  "result": "yes",
  "response": {
    "job": null
  }
}

Error Responses

Restore from Trash

Auth required. Permission: Guest (workspace), file modification + admin (share).

Path Parameters

curl Example

curl -X POST "https://api.fast.io/current/workspace/12345678901234567890/storage/f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4/restore/" \
  -H "Authorization: Bearer {jwt_token}"

Response

{
  "result": "yes",
  "response": {
    "job": null
  }
}

Error Responses

List Versions

Auth required. Permission: View (workspace), file view permission (share).

Path Parameters

curl Example

curl -X GET "https://api.fast.io/current/workspace/12345678901234567890/storage/f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4/versions/" \
  -H "Authorization: Bearer {jwt_token}"

Response

{
  "result": "yes",
  "response": {
    "versions": [
      {
        "id": "v8abc-defgh-ijklm-nopqr-stuvw-xyz901",
        "version_number": 2,
        "created": "2025-01-20T14:45:00Z",
        "operation": "update",
        "size": 5242880,
        "hash": "abc123def456789..."
      },
      {
        "id": "v9bcd-efghi-jklmn-opqrs-tuvwx-yz0123",
        "version_number": 1,
        "created": "2025-01-15T10:30:00Z",
        "operation": "create",
        "size": 4194304,
        "hash": "def456abc789012..."
      }
    ]
  }
}

Response Fields (per version)

Error Responses

Restore Version

Auth required. Permission: Guest (workspace), file modification permission (share).

Path Parameters

Request Body (form-encoded)

curl Example

curl -X POST "https://api.fast.io/current/workspace/12345678901234567890/storage/f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4/restore-version/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d 'version_id=v9bcd-efghi-jklmn-opqrs-tuvwx-yz0123'

Response

{
  "result": "yes",
  "response": {
    "new_version": {
      "id": "v0cde-fghij-klmno-pqrst-uvwxy-z12345",
      "version_number": 3,
      "created": "2025-01-25T09:00:00Z",
      "operation": "restore"
    },
    "node": {
      "id": "f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4",
      "type": "file",
      "name": "original-name.pdf",
      "version": "v3"
    }
  }
}

Error Responses

Notes:

• Original versions are preserved; a new version with operation type "restore" is created.
• Both filename and content are restored to the historical version's state.

Download File (Read)

Auth: JWT or download token. Permission: View (workspace), download permission (share). With a valid token query parameter, no JWT is required.

Path Parameters

Query Parameters

curl Examples

# Download with JWT auth
curl -X GET "https://api.fast.io/current/workspace/12345678901234567890/storage/f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4/read/" \
  -H "Authorization: Bearer {jwt_token}" \
  -o output.pdf

# Download with token (no JWT needed)
curl -X GET "https://api.fast.io/current/workspace/12345678901234567890/storage/f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4/read/?token={download_token}" \
  -o output.pdf

# Download specific version
curl -X GET "https://api.fast.io/current/workspace/12345678901234567890/storage/f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4/read/?version_id=v9bcd-efghi-jklmn-opqrs-tuvwx-yz0123" \
  -H "Authorization: Bearer {jwt_token}" \
  -o output_v1.pdf

# Byte-range request (streaming)
curl -X GET "https://api.fast.io/current/workspace/12345678901234567890/storage/f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4/read/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Range: bytes=0-1023"

Response: Binary file content streamed directly.

• Status 200 OK for full file, 206 Partial Content for range requests.
• Headers: Content-Type, Content-Length, Content-Disposition, Accept-Ranges: bytes.

Error Responses

Request Download Token

Auth required. Permission: View (workspace), download permission (share).

Path Parameters

curl Example

curl -X GET "https://api.fast.io/current/workspace/12345678901234567890/storage/f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4/requestread/" \
  -H "Authorization: Bearer {jwt_token}"

Response

{
  "result": "yes",
  "response": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Usage: Append ?token={token} to the read endpoint to download without an Authorization header. Useful for opening files in browser tabs.

Error Responses

Download Folder as ZIP

Auth required. Permission: View (workspace), download permission (share).

Path Parameters

curl Example

curl -X GET "https://api.fast.io/current/workspace/12345678901234567890/storage/root/zip/" \
  -H "Authorization: Bearer {jwt_token}" \
  -o workspace.zip

Response: Binary ZIP archive streamed directly with Content-Type and Content-Disposition headers.

Notes:

• The archive is streamed; it is not buffered in memory.
• Rate limited more aggressively than other endpoints due to resource cost.

Recent Files

Auth required. Permission: View (workspace), Guest+ (share). Public shares may allow password-only access.

Query Parameters

curl Example

curl -X GET "https://api.fast.io/current/workspace/12345678901234567890/storage/recent/?type=file&page_size=250" \
  -H "Authorization: Bearer {jwt_token}"

Response

{
  "result": "yes",
  "nodes": {
    "count": 3,
    "items": [
      {
        "id": "f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4",
        "name": "report.pdf",
        "type": "file",
        "parent": "d1abc-defgh-ijklm-nopqr-stuvw-xyz123",
        "size": 2048576,
        "updated": "2025-02-18T14:30:00Z",
        "created": "2025-02-17T10:00:00Z"
      }
    ]
  },
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJsYXN0X3VwZGF0ZWQiOiIyMDI1LTAyLTE4...",
    "page_size": 100
  }
}

Response Fields

Error Responses

Notes:

• Sort order is always updated DESC and is not configurable.
• Uses cursor-based (keyset) pagination, same as the list endpoint.
• For workspace folder shares, results are post-filtered to the share's subtree.

Search

Auth required. Permission: View (workspace), search + file view permissions (share).

Query Parameters

curl Example

curl -X GET "https://api.fast.io/current/workspace/12345678901234567890/storage/search/?search=quarterly+report" \
  -H "Authorization: Bearer {jwt_token}"

Response

{
  "result": "yes",
  "response": {
    "files": {
      "f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4": {
        "name": "Q4 Report.pdf",
        "parent_id": "d1abc-defgh-ijklm-nopqr-stuvw-xyz123",
        "type": "file"
      },
      "f6qrs-tuvwx-yz123-abcde-fghij-klmno7": {
        "name": "Quarterly Summary.docx",
        "parent_id": "root",
        "type": "file"
      }
    }
  }
}

Response Fields

Error Responses

Notes:

• Share search is not available for workspace-backed shares (shared folders).
• Search results are filtered by the user's file view permissions.

QuickShare (Workspace Only)

Auth required. Permission: Member.

Path Parameters

POST — Create or Update QuickShare

Request Body (form-encoded)

curl Example

curl -X POST "https://api.fast.io/current/workspace/12345678901234567890/storage/f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4/quickshare/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d 'expires=604800'

Response

{
  "result": "yes",
  "response": {
    "quickshare": {
      "id": "qs_abc123def456",
      "node": {
        "id": "f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4",
        "type": "file",
        "name": "presentation.pdf",
        "size": 5242880,
        "mimetype": "application/pdf"
      },
      "creator_uid": {
        "id": "12345678901234567890",
        "email_address": "john@example.com",
        "first_name": "John",
        "last_name": "Doe"
      },
      "limit_exceeded": false,
      "expires": "2025-01-22 10:30:00",
      "created": "2025-01-15 10:30:00"
    }
  }
}

Error Responses (POST)

GET — Get QuickShare Details

Returns the same format as POST. Returns APP_ERROR_NOT_FOUND (404) if no quickshare exists.

DELETE — Delete QuickShare

Returns {"result": "yes"}. Returns APP_ERROR_NOT_FOUND (404) if no quickshare exists.

Public Access Endpoints (No Auth Required)

Once a quickshare is created, these endpoints are accessible without authentication:

GET /current/quickshare/{quickshare_id}/details/                                    -- metadata and file info
GET /current/quickshare/{quickshare_id}/storage/read/                               -- download the file
GET /current/quickshare/{quickshare_id}/storage/preview/{preview_type}/read/        -- preview
GET /current/quickshare/{quickshare_id}/storage/preview/{preview_type}/read/file/{filename}  -- preview sub-file

List QuickShares in Workspace

Auth required. Permission: Member.

curl Example

curl -X GET "https://api.fast.io/current/workspace/12345678901234567890/storage/quickshares/list/" \
  -H "Authorization: Bearer {jwt_token}"

Response

{
  "result": "yes",
  "response": {
    "quickshares": [
      {
        "id": "qs_abc123def456",
        "node": { "id": "...", "type": "file", "name": "presentation.pdf" },
        "creator_uid": { "id": "...", "email_address": "john@example.com" },
        "limit_exceeded": false,
        "expires": "2025-01-22 10:30:00",
        "created": "2025-01-15 10:30:00"
      }
    ]
  }
}

File Locking

Lock a file to prevent concurrent edits. Locks expire automatically if not renewed via heartbeat. Available on both workspace and share storage.

Acquire Lock

Auth required. Permission: Guest (workspace), file modification permission (share).

Request Body (form-encoded)

curl Example

curl -X POST "https://api.fast.io/current/workspace/12345678901234567890/storage/f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4/lock/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d 'duration=300' \
  -d 'client_info={"device_name":"My Laptop","client_version":"2.1.0"}'

Response

{
  "result": "yes",
  "response": {
    "lock_token": "unique_lock_token_string",
    "locked_at": "2025-01-28T10:00:00+00:00",
    "expires_at": "2025-01-28T10:05:00+00:00",
    "node_id": "f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4"
  }
}

Response Fields

Error Responses

Heartbeat (Extend Lock)

Auth required.

Request Body (form-encoded)

curl Example

curl -X POST "https://api.fast.io/current/workspace/12345678901234567890/storage/f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4/lock/heartbeat/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d 'lock_token=unique_lock_token_string'

Response

{
  "result": "yes",
  "response": {
    "expires_at": "2025-01-28T10:10:00+00:00",
    "time_remaining": 300
  }
}

Error Responses

Notes:

• Send heartbeats well before the lock expires (e.g., at 50% of lock duration).
• Heartbeats can recreate an expired lock if the token and user match.

Release Lock

Auth required.

Request Body/Query

Response

{
  "result": "yes",
  "response": {
    "released": true
  }
}

Error Responses

Lock Status

Auth required.

Response (locked)

{
  "result": "yes",
  "response": {
    "locked": true,
    "locked_at": "2025-01-28T10:00:00+00:00",
    "expires_at": "2025-01-28T10:05:00+00:00",
    "node_id": "f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4",
    "time_remaining": 245,
    "locker_uid": "12345678901234567890"
  }
}

Response (unlocked)

{
  "result": "yes",
  "response": {
    "locked": false
  }
}

Previews

File previews provide rendered views of documents, images, video, and other content without downloading the original file.

Preview Types

Preview States

Returned in node details responses under previews.{type}.state:

Preauthorize Preview

Auth required. Permission: View (workspace), file view permission (share).

Path Parameters

curl Example

curl -X GET "https://api.fast.io/current/workspace/12345678901234567890/storage/f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4/preview/thumbnail/preauthorize/" \
  -H "Authorization: Bearer {jwt_token}"

Response

{
  "result": "yes",
  "response": {
    "downloadToken": "eyJhbGciOiJIUzI1NiJ9...",
    "path": "/current/workspace/.../preview/thumbnail/read/eyJhbGci.../file/preview.png",
    "primaryFilename": "preview.png"
  }
}

Response Fields

Error Responses

Read Preview

Auth required.

Token-Based Preview Read

Path Parameters

Transforms

Image transforms allow on-the-fly resizing, cropping, rotating, and format conversion.

Get Transform Status

Auth required. Currently the supported {transform_name} is image.

curl Example

curl -X GET "https://api.fast.io/current/workspace/12345678901234567890/storage/f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4/transform/image/" \
  -H "Authorization: Bearer {jwt_token}"

Response

{
  "result": "yes",
  "response": {
    "state": "rendered"
  }
}

Transformation States

Request Transform

Auth required.

Response

{
  "result": "yes",
  "response": {
    "state": "rendered"
  }
}

Error Responses

Read Transformed File

Auth: JWT or download token.

Image Transform Parameters

Pass as query parameters on transform read endpoints:

curl Example

curl -X GET "https://api.fast.io/current/workspace/12345678901234567890/storage/f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4/transform/image/read/?width=200&height=200&output-format=jpg" \
  -H "Authorization: Bearer {jwt_token}" \
  -o thumbnail.jpg

Request Transform Download Token (Workspace Only)

Auth required.

Response

{
  "result": "yes",
  "response": {
    "token": "eyJhbGciOiJIUzI1NiJ9..."
  }
}

Download Tokens Pattern

The requestread endpoint generates temporary, auth-free download tokens for files, previews, and transforms.

Flow:

1. GET .../storage/{node_id}/requestread/ — returns {"token": "..."}
2. GET .../storage/{node_id}/read/?token={token} — download without Authorization header

Useful for opening files in browser tabs or embedding in pages without exposing auth headers.

Workspace-Only Features

These endpoints are only available on workspaces, not shares:

• addlink — add a share link to storage
• createnote / updatenote — markdown notes
• quickshare — temporary public file links
• quickshares/list — list all quickshares
• transform/.../requestread/ — transform download tokens

Share-Specific Notes

• Share storage follows identical patterns to workspace storage for all common operations
• Shares support file locking (acquire, heartbeat, release, status)
• Shares support previews and transforms (status, request, read)
• Share permissions are granular: separate permissions for file view, download, creation, modification, and administration
• Shares may restrict operations to files the user created (creator-only restrictions)
• Workspace folder shares map root to the designated folder and scope all operations to that subtree
• Search is not available for workspace folder shares (files are indexed by workspace, not share)
• Public shares may allow listing and downloading without JWT authentication