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
| Param | Description |
|---|---|
recordId | DDS 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_idor sendnull): 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_idisn't in the caller'seffectiveOrgIds. - Plot membership: when
target_plot_idis 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
| Status | Code | When |
|---|---|---|
| 400 | BAD_REQUEST | Bad body, unknown action, action/plot contract mismatch, or plot outside the current version |
| 401 | UNAUTHORIZED | Missing/invalid API key |
| 404 | NOT_FOUND | Record isn't visible to the caller |
| 409 | CONFLICT | Record has no current version yet (cannot anchor an event) |
Required scope:
ingestions:write