Files and Versions

Find a file

Open /account on the instance. The file list requests 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 states; an unavailable service does not mean 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 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 are not 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 does not mean older versions disappear: the API's nextCursor determines 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

On download, the client first uses the 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 is not a permanent public link.

The browser reads the complete response into a Blob before saving, so large downloads can require substantial browser memory. The source does not 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. Do not 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 does not expose those operations. Do not 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.