Audit Trail

Each event is returned as a dds_mitigation_event resource:

{
  "type": "dds_mitigation_event",
  "id": "<uuid>",
  "attributes": {
    "dds_id": "<uuid>",
    "dds_version_id": "<uuid>",
    "occurred_at": "2026-05-09T12:05:00Z",
    "actor_user_id": "<uuid|null>",
    "actor_organization_id": "<uuid>",
    "action": "<action>",
    "target_plot_id": "<uuid|null>",
    "payload": { },
    "attachments": [ ]
  }
}

• action is one of the closed vocabulary catalogued below.
• target_plot_id is set only for plot-scoped actions (see Plot-scoped actions), and null otherwise.
• payload is an action-specific JSON object. The per-action shapes are documented below; consumers should read only the fields documented for the action they are rendering, as payloads may carry additional keys.
• actor_user_id is null for system-emitted events (worker jobs, async flows) that have no interactive user.

---

Action	Meaning
record.create	Record created
record.update	Record operator / commodity attributes updated

A PATCH of commodity.hs_code writes record.update. For the codes TRACES accepts, the blockers a code can raise and how to clear them, see HS codes TRACES accepts.

Action	Meaning
version.create	A new version was cut
version.task_create	Version-cut task started (async)
version.task_completed	Version-cut task succeeded
version.task_failed	Version-cut task failed

Action	Meaning
config.replace	Full replacement of exclusions + justifications
config.patch	Incremental update of exclusions + justifications
config.finding_set	A finding was written or replaced on any axis (payload.axis says which)
config.finding_removed	A finding was removed
config.finding_batch_set	Many findings were written on one axis in one batch call (payload.subject_ids names them)
config.exclusion_added	A plot was excluded from the record — system-only since EPO-1983
config.exclusion_removed	A plot was re-included — system-only since EPO-1983
config.justification_set	A justification was set on a plot
config.justification_removed	A justification was removed from a plot

Which action records an exclusion. An operator excluding a plot writes config.finding_set with payload.axis: "exclusion", via PUT /verdict-overrides. The config.exclusion_added / config.exclusion_removed pair is now emitted only by the submit-time auto-exclude and its re-include, with payload.source: "system" and systemAuthored: true.

That split is deliberate, not cosmetic: config.finding_set invalidates the authorisation grant a submit files under, so emitting one during the submit itself would 409 every record holding a non-compliant plot. Filter on payload.source to separate operator decisions from system ones.

Action	Meaning
plot.attached	A plot was attached to a version
plot.metric_updated	A plot's deforestation metrics changed between versions (carries a { previous, next } diff of only the changed attributes)
plot.assessment_updated	One or more of a plot's validation assessments (core / art9 / art10 / hazard / infrastructure) changed between versions

Action	Meaning
version.submit_started	Submission task initiated
version.submitted	Filed with EU TRACES by Epoch on the operator's behalf
version.submit_failed	Submission failed
version.marked_submitted	Operator filed externally via the EU portal and recorded the result manually
version.authorization_granted	Operator acknowledged the §9 step-3 "authorize Epoch to submit" consent text

Action	Meaning
version.assessments_refreshed	The reprocess / version-cut flow ran a fresh sco2api pass for at least one staged location
underlying_assessment_refreshed	An out-of-band /refresh of the /assessments/* write surface overwrote validation data that an open version pins (see below)

Action	Meaning
supplier.overridden	A per-record supplier snapshot override was written
supplier.propagated	A supplier edit propagated into a pending version via live-link
supplier.forked	A multi-org supplier edit repointed this org's pivot to a new global row
supplier.merged	A supplier was repointed onto a colliding row (fingerprint dedup)
supplier.frozen_on_submit	Supplier snapshots frozen before building the TRACES envelope
supplier.frozen_on_version_cut	Prior version's supplier snapshots frozen during a version cut

Action	Meaning
operator.defaults_changed	The org's operator defaults changed while this version was still open
operator.frozen_on_submit	The version's operator block was snapshotted from org defaults at submit time

Only this subset may be appended by callers via POST /regulations/eudr/audit-trail/:recordId/events; everything else is emitted exclusively by the fm-api code paths that own the underlying state transition, so the trail cannot be forged:

• config.patch
• config.exclusion_added
• config.exclusion_removed
• config.justification_set
• config.justification_removed

Amendment: config.finding_set and config.finding_removed are not caller-appendable; they are written by fm-api code that owns the finding. config.finding_set is written by PUT /regulations/eudr/audit-trail/:recordId/verdict-overrides. config.finding_removed is written by DELETE /regulations/eudr/audit-trail/:recordId/verdict-overrides.

These actions always carry a non-null target_plot_id; all others carry null:

config.exclusion_added, config.exclusion_removed, config.justification_set, config.justification_removed, plot.attached, plot.metric_updated, plot.assessment_updated, underlying_assessment_refreshed.

config.finding_set and config.finding_removed are the exception: they carry target_plot_id when the finding's subject_type is plot, and null on a record-grain finding such as a legality clearance. Read payload.subject_type and payload.subject_id to address the subject on any axis.

config.finding_batch_set is the exception among finding actions: it covers many plots, so it carries a null target_plot_id and names the plots in payload.subject_ids instead.

---

Field	Type	Notes
assessment_slug	string	Human slug for the refreshed assessment
assessment_type	string	Assessment type enum value
staged_location_id	uuid	The staged location whose validation was overwritten
previous_sco2_run_at	ISO-8601 string | null	The sco2_run_at the version pinned before the refresh; null when the overwrite created the row where none existed
new_sco2_run_at	ISO-8601 string	The sco2_run_at after the refresh
assessment_task_id	uuid	The originating refresh task — shared by every row from the same refresh
selection_kind	"single" | "list" | "filter"	How the refresh selected its locations
trigger	"refresh"	Constant — distinguishes this from version-cut refreshes

target_plot_id on the event is the affected plot.

A single refresh can touch many plots across many open versions. The emitter writes one event per (open version, plot) affected — not one per plot and not one per refresh — and every row produced by the same refresh shares one assessment_task_id.

A renderer that wants a single human line per refresh — e.g.

Underlying {assessment_slug} assessment refreshed on N plot(s) — {previous_sco2_run_at} → {new_sco2_run_at}

should roll up at render time, grouping the rows within a version by assessment_task_id:

• N = count of distinct target_plot_id in the group
• the old → new window = the earliest previous_sco2_run_at → the new_sco2_run_at in the group (they share one refresh, so new_sco2_run_at is uniform)

The API intentionally does not pre-aggregate: it preserves per-plot granularity so a consumer can render either the rolled-up summary or the individual plot rows. The rollup is a presentation concern.

---

Two different reasons keep a plot out of a filing, and the audit trail states which one applies.

Judged non-compliant. The effective verdict is non_compliant — either alert-derived, or an operator override to non_compliant. Auto-excluded at submit, narrated as "non-compliant plot (not filed to TRACES)".

Awaiting human review. The plot carries plot_resolution: pending_review: the automated adjudicator proposed a verdict and nobody has confirmed it yet. Also auto-excluded at submit, but narrated as "plot awaiting human review (not filed to TRACES)" — it is not an assertion that the plot is non-compliant, and an inspector reading the trail can tell the two apart.

The distinction matters because the review state is independent of the alert. A plot can be awaiting review while its alert reads sub-threshold, so withholding is decided on the review state itself rather than inferred from the verdict. Without that, an unadjudicated plot whose alert happened to clear the threshold would file as compliant.

An operator override on the plot_compliance axis retires the pending state and returns the plot to the filing if it resolves compliant. Adding exemption_driver to a compliant override records a non-agricultural cause, and the plot then reads exempt with that cause. List the outstanding queue with GET /regulations/eudr/audit-trail/:recordId/plots?filter[plot_resolution]=eq:pending_review.

Two caveats on that queue. An active override removes a plot from the filter whatever value you ask for — the filter answers "which plots still need a decision", and a decided plot is out of scope. And the endpoint lists only plots still in the filing: a submit attempt withholds every pending-review plot, so after a failed submit they appear on /plots/excluded instead and the queue answers zero. Read both surfaces for the full outstanding set.

For the wider worklist, every plot an operator may still act on rather than only those awaiting review, send filter[needs_resolution]=true. It drops plots that are compliant with no justification and keeps everything else, including plots already overridden, so a progress count does not shrink as plots are resolved. It has no effect on /plots/excluded.

To read one plot's row on either list, send filter[plot_id]=eq:<uuid>.

---

Method	Path	Description
POST	/regulations/eudr/audit-trail/:recordId/attachments	Mint a signed upload URL and a pending attachment row
GET	/regulations/eudr/audit-trail/:recordId/attachments	Keyset-paginated list of the record's attachments
GET	/regulations/eudr/audit-trail/:recordId/attachments/:id	Fetch one attachment with a signed download URL
DELETE	/regulations/eudr/audit-trail/:recordId/attachments/:id	Soft-delete (idempotent); drops from listings, bytes stay resolvable
PUT	/regulations/eudr/audit-trail/:recordId/attachments/:id/plots/:plotId	Link an existing attachment to one of the record's plots (idempotent)
DELETE	/regulations/eudr/audit-trail/:recordId/attachments/:id/plots/:plotId	Unlink a plot (idempotent)

Reads require the eudr:read scope; mutations require eudr:write. Every route is org-scoped — an attachment on a record your key cannot see returns 404.

The bytes never transit the API. Uploading is a mint → PUT → auto-confirm sequence:

1. Mint. POST …/attachments with the file's metadata. The response is a 201 carrying an upload_url (a short-lived signed URL with application/octet-stream and a maxBytes ceiling pinned into the signature) and expires_at. The attachment row is created in status: "pending". content_type and size_bytes are not accepted as inputs — the same as Ingest Assets, the finalize step resolves them from the stored object (size) and the filename extension (content type).

   {
     "data": {
       "type": "attachment",
       "attributes": {
         "category": "certificate",
         "source": "operator",
         "filename": "harvest-permit.pdf",
         "plot_ids": ["<plot-uuid>"]
       }
     }
   }
   

2. Upload. PUT the raw bytes to upload_url with Content-Type: application/octet-stream (the pinned type). Exceeding the pinned size is rejected by storage.

3. Auto-confirm. When the object finalizes, GCS fires an OBJECT_FINALIZE event to an internal webhook (POST /_internal/attachment-finalize), which 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.

{
  "type": "attachment",
  "id": "<uuid>",
  "attributes": {
    "subject_type": "dds_record",
    "subject_id": "<record-uuid>",
    "category": "certificate",
    "source": "operator",
    "filename": "harvest-permit.pdf",
    "content_type": "application/pdf",
    "size_bytes": 48213,
    "status": "stored",
    "verification_status": "approved",
    "plot_ids": ["<plot-uuid>"],
    "checksum_sha256": "<hex|null>",
    "locked": false,
    "metadata": null,
    "created_at": "2026-07-16T09:00:00Z",
    "confirmed_at": "2026-07-16T09:00:04Z",
    "archived_at": null
  },
  "links": { "self": "/regulations/eudr/audit-trail/<record>/attachments/<id>" }
}

• category — one of supporting_document, certificate, due_diligence_statement, legality_evidence, geolocation_evidence, correspondence, map, other.
• source — one of operator, supplier, third_party, or verifier (the last for accredited third-party verifier reports).
• status — pending until the bytes finalize, then stored.
• verification_status — approved (default), awaiting_verification, or rejected. An attachment left awaiting_verification blocks submission of the DDS version.
• plot_ids — the record plots this document justifies (may be empty; one attachment can cover many plots via the attachment_plot pivot).
• locked — true once the DDS version is submitted (see below).
• The mint response additionally carries upload_url + expires_at; the single-GET carries download_url + expires_at (pass ?ttl=<seconds> to shorten the download URL lifetime).

The list endpoint pages via keyset cursor (page[size], default 50, max 200) and supports the standard four Accept formats. Filters:

• filter[category][eq|in]
• filter[source][eq|in]
• filter[status][eq|in] — pending | stored
• filter[verification_status][eq|in] — approved | awaiting_verification | rejected
• filter[filename][eq|in|contains|startsWith]
• filter[plot_id][eq] — attachments covering a given plot (via the pivot)

Sort with ?sort= (prefix - for descending) on created_at (default -created_at), confirmed_at, size_bytes, filename, category, source, status, or verification_status.

• 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 cannot be altered after the fact.
• Soft-delete. Before submission, DELETE …/attachments/:id tombstones the row (archived_at set) — it drops out of listings, but its bytes remain resolvable so any already-filed reference still downloads. The call is idempotent.
• Plot links. A plot can only be linked if it belongs to the record's current-version plot set (otherwise 422).
• Carry-forward. Cutting a new DDS version carries the previous version's live (unlocked) attachments forward, re-keyed onto the new version's plots, so the current version always shows the operator's active evidence. This is addition-only — it never removes existing plot links, and already-frozen version rows are left untouched.

The upload / lock / archive lifecycle is recorded on the audit trail via the attachment.uploaded, attachment.locked_on_submit, and attachment.archived events (see the event vocabulary above).

---

See EUDR Compliance for the end-to-end compliance workflow.