Create Event

Append a user-authored entry to the audit log. The operator's reason is recorded under payload.note with payload.source = "user" so readers can distinguish operator notes from system-emitted events.

Path params

ParamDescription
recordIdDDS record id

Request body

{
  "action":         "<DdsMitigationAction>", // required, see action vocabulary below
  "target_plot_id": "<uuid> | null",         // optional; required for plot-targeted actions
  "reason":         "max 2000 chars"         // required, 1..2000 chars
}

Action vocabulary

action is picked from the closed DDS_MITIGATION_ACTION enum. See the Audit Log folder docs for the full list and which actions require target_plot_id.

  • Plot-targeted (must set target_plot_id): config.exclusion_added, config.exclusion_removed, config.justification_set, config.justification_removed, plot.attached.
  • Global (must omit target_plot_id or send null): every other action โ€” record.create, record.update, version.*, config.replace, config.patch.

Sending a mismatched combination returns 400 with the message prefixed dds_mitigation_event_log:.

Validation rules

  • Visibility: 404 when the record's organization_id isn't in the caller's effectiveOrgIds.
  • Plot membership: when target_plot_id is set, the plot must appear in the record's current version snapshot.
  • Reason required: empty or missing reason โ†’ 400.
  • Append-only: events cannot be edited or deleted after creation.

Response (201)

Returns the inserted event in the same envelope shape as the list endpoint. The actor_* fields are populated from the calling API key (member key โ†’ actor_user_id set, org key โ†’ null).

Errors

StatusCodeWhen
400BAD_REQUESTBad body, unknown action, action/plot contract mismatch, or plot outside the current version
401UNAUTHORIZEDMissing/invalid API key
404NOT_FOUNDRecord isn't visible to the caller
409CONFLICTRecord has no current version yet (cannot anchor an event)

Required scope: ingestions:write