Trigger firing
triggers
JSON:API type: trigger_firing.
The v2 OpenAPI document declares this resource's schema; the resource-field coverage gate holds this page to it.
A firing is the outcome of one trigger matching one stored event — the join record between the two, so both ends stay addressable as relationships.
Deduplication
The (trigger_id, event_id) pair is unique: one trigger fires at most once
per event. There is no re-fire; a retried action is a new chain member, not a
new firing.
Endpoints
| Verb | Path | Behaviour |
|---|---|---|
GET | /api/projects/{project_code}/triggers/{id}/firings | The trigger's firings, newest first (created_at DESC, id DESC), gated by read on the trigger's rule path (…/triggers/<code>). meta.authorisations reports update/delete on that path. |
GET | /api/maintenance/{window_id}/deferred_firings | A maintenance window's parked firings (status deferred, parked by that window), in original event order. Visibility rides read on the window node's …/maintenance rule path; an unknown window and a read denial both answer 404. |
POST | /api/projects/{project_code}/triggers/{id}/firings/{firing_id}/discard | Selective discard of one parked firing before release. Only a deferred firing discards — otherwise the named 422 "Firing <id> is not deferred — only a deferred firing can be discarded". A discarded firing settles suppressed, keeps its deferring window as history, and emits the settled hop. Authorisation: read on the trigger's rule path plus update on the deferring window node's …/maintenance rule path (the same right that starts and ends the window), 404-on-deny. The race twin — a discard losing the status compare-and-set to a concurrent release — answers a validation error from the writer ("no longer deferred"). |
Attributes
| Attribute | Type | Meaning |
|---|---|---|
status | string | The firing outcome. Vocabulary, verbatim: created | suppressed | failed | deferred. deferred is the one non-terminal status — a firing parked by an active maintenance window, re-evaluated when the window ends (or settled suppressed by a discard). |
created_type | string, nullable | The created object's type on the created arm; null otherwise. |
created_id | string, nullable | The created object's id on the created arm; null otherwise. |
error | string, nullable | The failure text on the failed arm; a deferred firing carries its deferral reason here. Null on created. |
correlation_id | string, nullable | The chain key the firing's created work carries — follow it with GET /api/chains/{correlation_id}. |
executed_as | string, nullable | The identity the firing executed as (the trigger's run_as resolution); null when the trigger ran as its author/the system default. |
created_at | string (ISO8601, 6 fractional digits) | When the firing was recorded. |
The deferring maintenance window itself (deferred_window_id in the row) is
not serialized as an attribute — it is kept as history after the firing
settles and drives the discard endpoint's authorisation.
Relationships
| Name | Kind | Meaning |
|---|---|---|
trigger | to-one trigger | The rule that fired. |
event | to-one event | The matched stored event. |
No links object is emitted on this resource.
The v2 reads — TriggerService
ListTriggerFirings lists a trigger's firings newest first with typed
status/since filters; DiscardTriggerFiring settles one deferred
firing (read on the trigger plus update on the deferring window's node
/maintenance path). See opschain docs api-v2.
Related pages
opschain docs resources/trigger— the owning rule.opschain docs maintenance-windows— deferral and release.opschain docs events— the matched-event side.