Uploads and Recovery

Four stages of an upload

1. Core creates an Upload Intent, reserves quota and returns the intent, objectKey and uploadGrant.
2. The browser transfers sequential 5 MiB parts (5 × 1024 × 1024 bytes) to Storage.
3. The browser submits the part count. Storage queues assembly and finalization for its Worker.
4. The Worker checks the object and calls Core. Core commits the version and quota accounting; a usable version then appears in the list.

The progress bar measures transferred parts, not background finalization. The page polls at most 20 times with roughly 500 ms between attempts. Exceeding that observation window produces a processing message, not proof of final failure. Polling checks only the first 100 files and matches by filename. For strict verification, inspect the version and size and compare downloaded contents.

File and authorization limits

Use a nonempty file. Its trimmed name must contain 1–255 characters and no slash, backslash or control characters. MIME type must also be nonempty. API sizeBytes is a positive decimal integer string, not a floating-point number or a value with units.

An Upload Intent lasts 15 minutes; uploadGrant lasts at most 300 seconds. They are different deadlines. A slow large transfer can lose authorization before the intent expires. The current browser offers no transparent grant renewal or resume-across-refresh guarantee. 5 MiB is the part size, not a whole-file limit. Available quota, authorization lifetime and deployment boundaries also constrain uploads.

API sequence and retries

Create with POST /api/v1/upload-intents and Idempotency-Key. The JSON contains fileName, string sizeBytes, mimeType and optional parentId. Send parts with PUT /api/v1/storage/uploads/{objectKey}/parts/{partNumber}, starting at 1. Storage requests use uploadGrant, not the login access token. Complete with POST /api/v1/storage/uploads/{objectKey}/complete and a JSON object whose numeric parts field is the total part count.

Retry the same logical request with the same key and identical parameters. Reusing a key for different data conflicts; generating a new key for every uncertain retry can reserve space repeatedly. Never call /api/v1/internal/* finalization callbacks from a client: they are private service protocols.

Identify the failed stage

| State | Next step | | --- | --- | | Intent creation failed | Check parameters, identity and quota; no transfer authorization exists yet | | Part transfer failed before completion submission | The page attempts cancellation and reports a cancellation failure separately | | Completion submitted but file absent | Wait, refresh and inspect file/version state before submitting again | | 409 | Check name, idempotency key, target file and intent state | | 413 | Check declared size and allowed byte boundaries; repeated retries alone will not help | | 401 | Check grant type and lifetime; signing in again does not renew an old grant |

POST /api/v1/upload-intents/{id}/cancel cancels an active intent, returning 204. An intent that can no longer be cancelled may return 409. Cancellation does not delete a completed file.

Replace an existing file

POST /api/v1/files/{fileId}/upload-intents creates a replacement intent. Transfer and finalization follow the same sequence. The current upload panel only creates new uploads; it has no replacement selector. A new-upload name conflict is not automatic overwrite. Replacement retains the logical file and adds a version; see Quota for its accounting.