damOne ingest path
Interactive uploads, direct-to-S3 uploads and migrations converge before an asset exists.
- 01
Stage
Create a resumable session and stream chunks, or request a presigned PUT. Bytes remain under the tenant staging prefix.
- 02
Finalise
Assemble the object, hash with BLAKE3, sniff the real media type, scan when clamd is configured, then promote by content address.
- 03
Derive
Render the thumbnail, preview and web derivative while the original is hot. Preserve colour and provenance evidence.
- 04
Index and enrich
Index only after previews exist, then run similarity, colour and any enabled assisted-enrichment jobs.
Choose an upload protocol
| Path | Use it when | Required contract |
|---|---|---|
| POST /uploads | The client needs resumability or deferred length | TUS 1.0.0 headers |
| PATCH /uploads/{id} | Sending the next TUS chunk | Offset and TUS version |
| POST /uploads/presign | The browser can send one direct S3 PUT | Known length and TUS version |
| damctl import transfer | Moving a library through a connector | JSONL import plan |
curl -i -X POST 'http://127.0.0.1:8080/uploads' \
-H 'Authorization: Bearer $DAMRS_API_KEY' \
-H 'Tus-Resumable: 1.0.0' \
-H 'Upload-Length: 7340032' \
-H 'Upload-Metadata: filename Y2FtcGFpZ24uanBn'The delivery decision
A delivery token binds the tenant, asset or derivative, intended purpose and expiry. Its signature proves the request was minted by dam.rs; it does not freeze the rights verdict.
When GET /d/{token} is redeemed, the server resolves the tenant, checks the caller-independent token constraints, evaluates current rights for the intended use, appends the decision and only then redirects to a short-lived object-store URL.
- Internal preview deliberately remains visible while rights paperwork is unknown.
- Distribution fails closed when evidence is absent, expired or incompatible with the requested use.
- Archive state returns a restore estimate instead of minting a URL that object storage will reject.
- Revocation takes effect on the next fetch because no earlier badge or signature promised future delivery.
Storage tiers
| Tier | Search and preview | Original download |
|---|---|---|
| STANDARD | Immediate | Immediate |
| STANDARD_IA / GLACIER_IR | Immediate | Immediate with retrieval fee |
| GLACIER / DEEP_ARCHIVE | Immediate | Asynchronous restore |