Routes

Uploads

• POST /uploads — create an upload session and receive strategy details.
• GET /uploads/:uploadId — read upload status and progress.
• POST /uploads/:uploadId/progress — record client-side progress (direct uploads).
• POST /uploads/:uploadId/parts — get signed URLs for multipart uploads.
• POST /uploads/:uploadId/parts/complete — record uploaded parts.
• POST /uploads/:uploadId/complete — finalize upload and mark file ready.
• POST /uploads/:uploadId/abort — abort an upload.
• PUT /uploads/:uploadId/content — server-stream (proxy) bytes to storage.

Notes:

• POST /uploads is idempotent only when a checksum is provided; if metadata matches, the existing upload is returned to support resume without creating a new storage session.
• If a file already exists for the key, POST /uploads and POST /uploads/:uploadId/complete return FILE_ALREADY_EXISTS.

Files

• GET /files — list files with cursor pagination and optional prefix filtering.
• GET /files/:fileKey — fetch file metadata.
• PATCH /files/:fileKey — update file metadata.
• DELETE /files/:fileKey — delete a file (idempotent).
• GET /files/:fileKey/download-url — signed download URL (if supported).
• GET /files/:fileKey/content — server-stream (proxy) downloads (if supported).

Notes:

• POST /files does not implement idempotent matching; active uploads and existing files return UPLOAD_ALREADY_ACTIVE or FILE_ALREADY_EXISTS.

Error codes

• UPLOAD_NOT_FOUND
• UPLOAD_ALREADY_ACTIVE
• UPLOAD_METADATA_MISMATCH
• FILE_NOT_FOUND
• FILE_ALREADY_EXISTS
• UPLOAD_EXPIRED
• UPLOAD_INVALID_STATE
• SIGNED_URL_UNSUPPORTED
• STORAGE_ERROR
• INVALID_FILE_KEY
• INVALID_CHECKSUM