Operator evidence attachments
Operator-supplied supporting documents attached to a single DDS record โ land titles, certificates, third-party audit reports, correspondence, maps, and any other evidence that backs the due-diligence statement but is not itself submitted to EU TRACES. The audit trail is the single home for this evidence: it is timestamped, linked to the record (and optionally to the plots it justifies), retained for the full Article 12 period, and exportable on a competent-authority request.
All routes live under
/regulations/eudr/audit-trail/:recordId/attachments and are org-scoped โ
an attachment on a record the caller can't see returns 404.
โถWhat you can do here
| Action | Endpoint | Scope |
|---|---|---|
| Mint Attachment | POST โฆ/attachments โ mint a signed upload URL + pending row | eudr:write |
| List Attachments | GET โฆ/attachments โ keyset list, with filter + sort | eudr:read |
| Get Attachment | GET โฆ/attachments/:id โ one attachment + a signed download URL | eudr:read |
| Update Attachment | PATCH โฆ/attachments/:id โ edit the free-text description | eudr:write |
| Delete Attachment | DELETE โฆ/attachments/:id โ soft-delete (idempotent) | eudr:write |
| Link Plot | PUT โฆ/attachments/:id/plots/:plotId โ cover another of the record's plots | eudr:write |
| Unlink Plot | DELETE โฆ/attachments/:id/plots/:plotId โ drop a plot link | eudr:write |
โถUpload is a two-step signed-URL flow
The bytes never transit the API. Uploading is mint โ PUT โ auto-confirm:
- Mint โ
POST โฆ/attachmentswith the file's metadata (category,source,filename). The response (201) carries a short-livedupload_url(withapplication/octet-streamand a max-size ceiling pinned into the signature) andexpires_at. The row starts instatus: "pending". - Upload โ
PUTthe raw bytes toupload_urlwithContent-Type: application/octet-stream. Exceeding the pinned size is rejected by storage. - Auto-confirm โ when the object finalizes, storage fires an
OBJECT_FINALIZEevent to an internal webhook that flips the row tostatus: "stored"and stampsconfirmed_at. There is no client confirm call โ poll the list / single GET untilstatusisstored.
โถThe attachment resource
| Field | Type | Notes |
|---|---|---|
subject_type | "dds_record" | Polymorphic subject; only dds_record today |
subject_id | uuid | The record this evidence backs |
category | enum | supporting_document, certificate, due_diligence_statement, legality_evidence, geolocation_evidence, correspondence, map, other |
source | enum | operator, supplier, third_party, verifier |
filename | string | Sanitised; extension must be allowlisted |
description | string | null | Operator free-text (what the evidence is); set at mint or via PATCH; โค 2000 chars |
content_type | string | null | MIME type; not a mint input โ resolved from the filename extension at finalize (null while pending) |
size_bytes | int | null | 1 โฆ 52428800 (50 MB); not a mint input โ resolved from the stored object at finalize (null while pending) |
status | enum | pending โ stored |
verification_status | enum | approved (default), awaiting_verification, rejected โ an unresolved awaiting_verification blocks DDS submission |
plot_ids | uuid[] | Record plots this document justifies (may be empty) |
checksum_sha256 | string | null | Optional client-supplied hash |
locked | boolean | true once the DDS version is submitted (immutable thereafter) |
metadata | object | null | Optional free-form; __proto__ rejected |
created_at / confirmed_at / archived_at | timestamp | null | Lifecycle timestamps |
The mint response additionally carries upload_url + expires_at; the
single-GET carries download_url + expires_at.
โถImmutability, soft-delete & carry-forward
- Lock-on-submit. When a DDS version is submitted, its attachments
become immutable (
locked: true); aDELETEagainst a locked attachment returns409 Conflict, so the evidence backing a filing can't be altered after the fact. - Soft-delete. Before submission,
DELETEtombstones the row โ it drops from listings, but its bytes stay resolvable so an already-filed reference still downloads. Idempotent. - Plot links can only target plots in the record's current-version plot set. Cutting a new DDS version carries the previous version's live (unlocked) attachments forward (addition-only โ it never removes existing links, and already-frozen version rows are left untouched).
โถSecurity notes
- Documents live in an isolated storage bucket; downloads are served through short-lived signed URLs that force an attachment disposition (never rendered inline).
- The upload allowlist rejects active-content types
(
.html,.svg,.js, executables) โ only the document/image/archive extensions above are accepted.
Every mutation is recorded on the Audit Log as
attachment.uploaded, attachment.archived, and
attachment.locked_on_submit events.
Required scope:
eudr:readfor reads,eudr:writefor mutations. Records are org-scoped โ another org's record returns404.