Overview

What you get

• File + upload data model: Separate file and upload records with statuses, metadata, and lifecycle timestamps. Uploads are sessions; a file exists once its content is published.
• Content in your database: File content lives in the fragment's own table. A write stores the content and publishes the file in one transaction. See Storage.
• Batch publication: Prepare several uploads, then publish, delete, and check files together in one atomic commit with revision preconditions.
• Search and edits: An optional text index, server-side text edits, and signed file links.
• Hooks for lifecycle events: onFileReady, onUploadFailed, and onFileDeleted.
• Client helpers: Upload with progress reporting, download, edit, and search.

Typical flow

1. Create an upload with POST /uploads.
2. Send its content with PUT /uploads/:uploadId/content, which publishes the file, or prepares it when the upload belongs to a batch.
3. Fetch metadata or download the file when needed.

POST /files does both steps in one multipart request.

Retry + idempotency

• POST /uploads is idempotent only when a checksum is provided. If a matching, unfinished upload already exists, the server returns it so clients can resume.
• Without a checksum, a second upload of the same fileKey is rejected with UPLOAD_ALREADY_ACTIVE, unless it sets replaceActiveUpload.
• Sending content to a prepared batch upload again returns the same prepared write.

Retention

• Completed uploads are retained for auditing and retries.
• Uploads that expire before their content arrives, or prepared uploads whose batch never commits, are marked expired and lose any content they held.