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

ActionEndpointScope
Mint AttachmentPOST โ€ฆ/attachments โ€” mint a signed upload URL + pending roweudr:write
List AttachmentsGET โ€ฆ/attachments โ€” keyset list, with filter + sorteudr:read
Get AttachmentGET โ€ฆ/attachments/:id โ€” one attachment + a signed download URLeudr:read
Update AttachmentPATCH โ€ฆ/attachments/:id โ€” edit the free-text descriptioneudr:write
Delete AttachmentDELETE โ€ฆ/attachments/:id โ€” soft-delete (idempotent)eudr:write
Link PlotPUT โ€ฆ/attachments/:id/plots/:plotId โ€” cover another of the record's plotseudr:write
Unlink PlotDELETE โ€ฆ/attachments/:id/plots/:plotId โ€” drop a plot linkeudr:write

Upload is a two-step signed-URL flow

The bytes never transit the API. Uploading is mint โ†’ PUT โ†’ auto-confirm:

  1. Mint โ€” POST โ€ฆ/attachments with the file's metadata (category, source, filename). The response (201) carries a short-lived upload_url (with application/octet-stream and a max-size ceiling pinned into the signature) and expires_at. The row starts in status: "pending".
  2. Upload โ€” PUT the raw bytes to upload_url with Content-Type: application/octet-stream. Exceeding the pinned size is rejected by storage.
  3. Auto-confirm โ€” when the object finalizes, storage fires an OBJECT_FINALIZE event to an internal webhook that flips the row to status: "stored" and stamps confirmed_at. There is no client confirm call โ€” poll the list / single GET until status is stored.

The attachment resource

FieldTypeNotes
subject_type"dds_record"Polymorphic subject; only dds_record today
subject_iduuidThe record this evidence backs
categoryenumsupporting_document, certificate, due_diligence_statement, legality_evidence, geolocation_evidence, correspondence, map, other
sourceenumoperator, supplier, third_party, verifier
filenamestringSanitised; extension must be allowlisted
descriptionstring | nullOperator free-text (what the evidence is); set at mint or via PATCH; โ‰ค 2000 chars
content_typestring | nullMIME type; not a mint input โ€” resolved from the filename extension at finalize (null while pending)
size_bytesint | null1 โ€ฆ 52428800 (50 MB); not a mint input โ€” resolved from the stored object at finalize (null while pending)
statusenumpending โ†’ stored
verification_statusenumapproved (default), awaiting_verification, rejected โ€” an unresolved awaiting_verification blocks DDS submission
plot_idsuuid[]Record plots this document justifies (may be empty)
checksum_sha256string | nullOptional client-supplied hash
lockedbooleantrue once the DDS version is submitted (immutable thereafter)
metadataobject | nullOptional free-form; __proto__ rejected
created_at / confirmed_at / archived_attimestamp | nullLifecycle 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); a DELETE against a locked attachment returns 409 Conflict, so the evidence backing a filing can't be altered after the fact.
  • Soft-delete. Before submission, DELETE tombstones 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:read for reads, eudr:write for mutations. Records are org-scoped โ€” another org's record returns 404.