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.
POST /uploads and GET /uploads/:uploadId return the resolved provider plus canonical provider-sticky follow-up URLs (statusEndpoint, progressEndpoint, completeEndpoint, abortEndpoint, and the strategy-specific upload endpoints).
If a file already exists for the key, POST /uploads and POST /uploads/:uploadId/complete return FILE_ALREADY_EXISTS.
Storage-touching follow-up routes return PROVIDER_MISMATCH before storage I/O if a request lands on the wrong provider fragment.

GET /files — list files with cursor pagination and optional provider + prefix filters.
GET /files/by-key?provider=<provider>&key=<fileKey> — fetch file metadata.
PATCH /files/by-key?provider=<provider>&key=<fileKey> — update file metadata.
DELETE /files/by-key?provider=<provider>&key=<fileKey> — delete a file (idempotent).
GET /files/by-key/download-url?provider=<provider>&key=<fileKey> — signed download URL (if supported).
GET /files/by-key/content?provider=<provider>&key=<fileKey> — 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.