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.
• Compact responses: Every storage endpoint that returns nodes (list, details, search, metadata, trash, quickshares) accepts an optional ?output=<token> query parameter with three detail levels: terse, standard, or full. See the "Compact Responses" section below for the full contract, field lists, and the HTTP 400 rule for multi-level combinations.

Compact Responses (output=)

Every storage endpoint that returns node objects — folder listings, node details, search hits, metadata endpoints, trash listings, and quickshares — accepts an optional output query parameter that selects the shape of each node in the response. 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 list rows, tree rendering, pickers, breadcrumb navigation, and drag-and-drop targets — it carries modified (so list rows can render the date column and "sort by modified" without a follow-up fetch), a per-type previews readiness map (so the thumbnail selector can pick the best available source), and the summary title. Use standard for most detail views, file-browser main lists, and any UI that shows AI-processing state, lock/restricted chips, DMCA chips, import-provider chips, or trash state — it adds the ai.state that drives the "summarizing…" spinner, timestamps, origin creator plus type, the dmca flag for DMCA chip rendering, is_imported for import-provider chips, link-node target_type/target_id discriminators, and the metadata.title/metadata.short user overrides that list rows render when a custom title is set. Use full (or omit the parameter) for the node detail pane, virus/AI inspection, version history, and any workflow that reads long-form summaries, EXIF, import provider metadata, or content hashes. 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.

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.
• Conflict resolution: If a file with the same name exists, the default behavior is to replace (overwrite) the existing file, creating a version for rollback. Folder or type-mismatch conflicts fall back to renaming.

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

Read Note

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

Path Parameters

Query Parameters

curl Example

# Workspace
curl -X GET "https://api.fast.io/current/workspace/12345678901234567890/storage/n5mno-pqrst-uvwxy-z1234-abcde-fghij6/readnote/" \
  -H "Authorization: Bearer {jwt_token}"

# Share
curl -X GET "https://api.fast.io/current/share/12345678901234567890/storage/n5mno-pqrst-uvwxy-z1234-abcde-fghij6/readnote/" \
  -H "Authorization: Bearer {jwt_token}"

# Share with download token (no JWT needed)
curl -X GET "https://api.fast.io/current/share/12345678901234567890/storage/n5mno-pqrst-uvwxy-z1234-abcde-fghij6/readnote/?token={download_token}"

Response

{
  "result": "yes",
  "response": {
    "content": "# Meeting Notes\n\nDiscussed project timeline.",
    "note": {
      "id": "n5mno-pqrst-uvwxy-z1234-abcde-fghij6",
      "type": "note",
      "name": "meeting-notes.md",
      "parent": "root",
      "mimetype": "text/markdown",
      "version": "v1",
      "created": "2025-01-15T10:30:00Z",
      "modified": "2025-01-15T10:30:00Z"
    }
  }
}

Response Fields

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

Notes:

• Conflict resolution: If a file with the same name exists in the destination, the existing file is replaced (moved to trash for rollback). Folder or type-mismatch conflicts fall back to renaming.

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.
• Conflict resolution: If a file with the same name exists in the destination, the existing file is replaced (moved to trash for rollback). Folder or type-mismatch conflicts fall back to renaming.

Transfer Node

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

Path Parameters

Request Body (form-encoded)

curl Example (copy, default)

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'

curl Example (move)

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' \
  -d 'mode=move'

Response (copy)

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

Response (move)

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

Error Responses

Notes:

• Folder transfers are recursive.
• The user must have write access to both source and destination.
• When mode=move, the source node is trashed in the source storage instance after the copy completes. The response includes "source_trashed": true on success.

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:

• Uses ZIP64 format — supports archives up to 50GB (plan-dependent limits may be lower).
• Compatible with all modern extraction tools (WinRAR, 7-Zip, macOS Archive Utility, Windows Explorer).
• The archive is streamed; it is not buffered in memory.
• Files are stored without compression for immediate streaming.
• Maximum 10,000 files per archive.
• 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 1609 (Not Found) (404) if no quickshare exists.

DELETE — Delete QuickShare

Returns {"result": "yes"}. Returns 1609 (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.

In medium security mode, file previews are available for guests but direct downloads are restricted. Owners and admins can still download normally.

Metadata Saved Views

Each user can persist per-template column order, column visibility, and sort preferences. Saved views are private to the user — two users can independently customize the same template. Identity is the tuple (workspace, user, template); there is at most one saved view per user per template per workspace.

Auth required. Permission: Member. Metadata billing feature required.

GET — Retrieve Saved View

Returns the caller's saved view for the supplied template. Responds 1609 (Not Found) (404) when the caller has no view saved for that template.

Query Parameters

POST — Create or Update Saved View

Upserts the caller's saved view. If a view already exists for this template, the row is replaced in place (its id and created timestamp are preserved; updated is refreshed). Otherwise a new row is created.

Send as application/x-www-form-urlencoded. The config field holds a JSON-encoded string (not a nested JSON body) — sending Content-Type: application/json is rejected with 406 (This field is missing).

Request Body

Example

curl -X POST "https://api.fast.io/current/workspace/{workspace_id}/metadata/view/" \
  -H "Authorization: Bearer {jwt_token}" \
  --data-urlencode "template_id={template_id}" \
  --data-urlencode 'config={"version":1,"columns":[{"field":"title","visible":true,"width":180}],"sort":{"field":"updated","dir":"desc"},"filters":[]}'

DELETE — Remove Saved View

Deletes only the caller's own view; other users' views are untouched. Responds 1609 (Not Found) (404) when the caller has no view saved for that template.

Query Parameters

GET Views — List Saved Views

Lists every saved view the caller owns in this workspace (one entry per template the caller has customized). Views belonging to other users are never returned.

Config Schema

{
  "version": 1,
  "columns": [
    { "field": "title",  "visible": true,  "width": 180 },
    { "field": "status", "visible": true,  "width": 120 }
  ],
  "sort": { "field": "updated", "dir": "desc" },
  "filters": [
    { "field": "status",   "operator": "=",  "value_type": "string", "value": "active" },
    { "field": "priority", "operator": ">=", "value_type": "int",    "value": 3 }
  ]
}

Unknown top-level keys, unknown columns[] keys, unknown sort keys, or unknown filters[] keys cause the request to be rejected with 1605 (Invalid Input).

Filters

Filter entries in a saved view use {field, operator, value_type, value} — the per-entry field name matches the naming used by columns[].field and sort.field for a uniform identifier across the config.

• Max 5 filter entries per view.
• AND-chained; insertion order is preserved round-trip.
• Numeric value types (int, float) accept the stringy form ("42") via numeric validation.
• For relational operators (<, <=, >, >=) with value_type: string, the server performs lexical comparison. Numeric value types use numeric comparison.

Value coercion. Values follow standard scalar coercion — strings like "true", "1", "yes", "on" (and their falsy counterparts) are accepted when value_type is bool; numeric-form strings like "42" or "1.5" are accepted when value_type is int or float. Sending the typed value directly (e.g. 3 instead of "3") is preferred and round-trips unchanged.

Stateless filters query parameter shape. The template nodes listing endpoint accepts a stateless filters query parameter whose per-entry identifier is still key (not field); that pre-existing query-layer contract is unchanged. Saved View configs use field for internal consistency with columns[].field and sort.field. When the server auto-applies a saved view on the nodes endpoint, it handles the translation internally. Use field when writing a Saved View; use key only when passing a stateless filters query parameter directly on the nodes endpoint.

Response Shape

{
  "result": "yes",
  "response": {
    "id": "{view_id}",
    "user_id": "{user_id}",
    "template_id": "{template_id}",
    "config": { "version": 1, "columns": [], "sort": { "field": "updated", "dir": "desc" }, "filters": [] },
    "created": "2026-04-23T11:02:00+00:00",
    "updated": "2026-04-23T11:02:00+00:00"
  }
}

The list endpoint wraps rows under response.items[] and adds a response.count field.

Auto-Apply on Template Nodes Listing

GET /current/workspace/{workspace_id}/metadata/templates/{template_id}/nodes inspects the caller's saved view for the given template.

• Sort. When the request does not include an explicit sort_field and the caller has a saved view whose config carries a sort.field, the server applies sort.field + sort.dir to the listing automatically. Passing sort_field in the query always wins.
• Filters. When the request does not include a filters query parameter and the caller's saved view carries a non-empty filters array, the server applies those filters to the listing automatically. Passing filters explicitly (including an empty string or empty array) always wins and bypasses the saved view — no server-side merge is performed.
• Partial override. sort_field and filters fall back independently. A request that supplies sort_field but omits filters uses the caller's sort with the saved view's filters (and vice versa). Callers that want a stateless listing with neither the saved sort nor the saved filters must supply both explicitly.

Column order and visibility are not applied server-side — clients use the saved view's columns array to decide which columns to render.

Error Responses

Workspace-Only Features

These endpoints are only available on workspaces, not shares:

• addlink — add a share link to storage
• createnote / readnote / 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