Intake API

Durable single-file and batch intake

📄️Validate an immutable original and enqueue its core processing

The Idempotency-Key is scoped to the authenticated household member. Repeating the same key and semantic request returns the original documentId and taskId; reusing it for different content returns 409. By default, an already-ingested checksum returns 409 unless allowDuplicate is true. A 202 response means durable acceptance only; poll the returned taskId.

📄️Validate two to one hundred originals as a durable intake batch

Files are processed and returned in request order. The batch envelope and item identities are durable, so repeating an identical ordered request with the same Idempotency-Key resumes or replays it. A changed filename, order, or content under that key returns 409. An intake rejection has null documentId/taskId plus a bounded error. A durable acceptance always preserves non-null documentId/taskId; while processing is active its error is null, and if processing later exhausts retries the replay preserves both IDs alongside the bounded error so clients recover the existing document rather than uploading it again.

📄️Discover the TUS 1.0 resumable-upload capabilities

Unauthenticated constant TUS discovery response advertising creation, termination, expiration, and SHA-1 or SHA-256 checksum support; it does not access upload storage.

📄️Create or recover a durable resumable-upload session

Implements TUS 1.0 creation. Upload-Length is a declared original length, not a Jiandu product limit. Upload-Metadata carries base64 filename, optional conventional filetype (or Jiandu contentType), and allowDuplicate fields. Retrying an identical Idempotency-Key returns the original session Location. Replaying an accepted session requires current documents.read permission and access to its document; an unreadable accepted session returns 404.

📄️Terminate one independently resumable upload

Requires documents.create, Tus-Resumable 1.0.0, and an exact same-origin proof for cookie requests. Only an active unexpired session in the authenticated intake scope can be terminated; cancellation records private spool cleanup, while terminal and expired sessions return 404.

📄️Read transfer, finalization, and durable acceptance status

Requires documents.create, Tus-Resumable 1.0.0, and the authenticated intake scope that owns the upload. Returns source-neutral transfer and finalization state plus any durable document, task, or bounded failure outcome. Accepted sessions also require current documents.read permission and access to their document; an unreadable accepted session returns 404.

📄️Recover the authoritative durable upload offset

Requires documents.create, Tus-Resumable 1.0.0, and the authenticated intake scope that owns the upload. An accepted session also requires current documents.read permission and access to its document. Returns durable offset, declared length, and expiry; unknown, cross-scope, canceled, expired, and unreadable accepted sessions return 404.

📄️Append one checksummed bounded transfer chunk

The per-request chunk budget bounds memory and retry cost; it is not a whole-document limit. A successful response advances Upload-Offset only after the chunk is durable.