Files and Versions

Find a file

Open /account on the instance. The file list loads 20 records at a time. "加载更多" (load more) follows nextCursor; "刷新" (refresh) replaces the list with the first page. A failed request and an empty list are different things—an unavailable service doesn't mean your files were erased.

Each entry shows its name, update time, and current version's size, number, and MIME type. currentVersion: null means no usable version is available yet, so the version and download buttons are disabled. Wait for finalization and refresh instead of assuming that a filename proves successful storage.

Inspect versions

"版本" (versions) opens a list of version numbers, sizes, and creation times. A File is the logical record, a File Version is an immutable content version, and a Storage Object is the stored object. Their identifiers aren't interchangeable.

The versions API defaults to 20 records and allows at most 100 per cursor page. The current dialog requests only the first 100 and has no further-page control. This doesn't mean older versions disappear—the API's nextCursor tells you whether more remain. Replacement uploads can create another version, but the dialog has no restore or specific-historical-version download button.

Download the current version

When you download, the client first uses your signed-in identity to request a private Download Ticket, then sends the returned downloadGrant to Storage. A ticket lasts 60 seconds and can be consumed once. Request it at download time; the object address isn't a permanent public link.

The browser reads the complete response into a Blob before saving, so large downloads can need substantial browser memory. The source doesn't promise resumable downloads, parallel downloading, or arbitrary Range requests. If a ticket expires, was consumed, or the transfer fails, start a new download to get a new ticket rather than endlessly replaying the old one.

Listing API boundaries

GET /api/v1/files defaults to 50 records, with a maximum of 100. Omitting parentId adds no parent filter; parentId=null selects the root. A cursor is signed and bound to the user, endpoint, and filter context. Pass it unchanged and restart pagination when filters change. Don't manufacture cursors or transfer them between accounts.

The active public file routes provide queries, not general folder creation, rename, move, delete, or recycle-bin recovery. A folder type or deletedAt field in the data model doesn't expose those operations. Don't use archived instructions or edit the database as a substitute for normal file management.

See Uploads for replacement and name conflicts, and Quota for storage accounting.