Events API

GET/api/events

request access

The operational domain-event feed (#11).

Newest first, with optional event_type / aggregate_id filters. Distinct from the audit feed: this is the operational stream other subsystems consume (alert generation, dashboards). Request-tier read, site/environment-scoped (#2): a scoped principal sees only its own scope's events plus events that are platform-wide (NULL) on BOTH axes. The cross-scope rule is SYMMETRIC: a SITE-ONLY event (concrete site, NULL environment — e.g. a decommission) is NOT visible to an environment-scoped principal, and an ENV-ONLY event (NULL site, concrete environment) is NOT visible to a site-scoped one — in each case the mutating handlers fail closed for that principal, so the feed must not be more permissive. Empty + durable:false when no DB is configured.

Permissions

HTTP request

GET https://<your-host>/api/events

Path parameters

This operation has no path parameters.

Query parameters

Request headers

Request body

This operation does not accept a request body.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  'https://<your-host>/api/events'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "events": null,
  "durable": false
}

GET/api/events/alerts

monitoring.alert.read access

The alert-worthy slice of the domain-event stream (#11 slice 2a).

Reuses the scoped feed but keeps only events the pure event_alerts classifier flags — currently a request reaching a NEGATIVE terminal state: failed=critical, rejected=warning, cancelled=info — annotating each with its severity. The status filter is pushed into SQL (via the engine's authoritative status list) so the page is not short-counted when alerts are rare. The dedicated monitoring-alert read capability is checked before database access; site/environment scope is then applied in SQL. Empty + durable:false no DB.

Permissions

HTTP request

GET https://<your-host>/api/events/alerts

Path parameters

This operation has no path parameters.

Query parameters

Request headers

Request body

This operation does not accept a request body.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  'https://<your-host>/api/events/alerts'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "alerts": null,
  "durable": false
}

POST/api/events/alerts/batch/ack

monitoring.alert.acknowledge access

Acknowledge up to 100 alerts in one call (#19).

Mirrors the requests_batch_* (#17) shape: the dedicated acknowledgement capability is checked up front, ids are deduped + capped at 100, then each id runs the SAME per-item scope/ack core (ack_alert_one) as the single endpoint — so a batch can NEVER ack an out-of-scope alert, and one bad id never aborts the rest. Per-item independent; partial success; HTTP 200 always with {results, succeeded, failed}.

Permissions

HTTP request

POST https://<your-host>/api/events/alerts/batch/ack

Path parameters

This operation has no path parameters.

Query parameters

This operation has no query parameters.

Request headers

Request body

JSON structure: BatchAlertAckBody.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request POST \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '{"event_ids":[]}' \
  'https://<your-host>/api/events/alerts/batch/ack'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "results": null,
  "succeeded": null,
  "failed": null
}

POST/api/events/alerts/{event_id}/ack

monitoring.alert.acknowledge access

Acknowledge an alert (#11 slice 2e).

Marks the alert (a domain_events row) as seen by the acting principal; the feed then shows acknowledged + who/when. Re-acking updates in place. Requires the dedicated monitoring-alert acknowledgement capability. 404 when the event id is unknown, 400 on a control-character note, 503 with no DB.

Permissions

HTTP request

POST https://<your-host>/api/events/alerts/{event_id}/ack

Path parameters

Query parameters

This operation has no query parameters.

Request headers

Request body

JSON structure: AlertAckBody.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request POST \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '{}' \
  'https://<your-host>/api/events/alerts/<event_id>/ack'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "acknowledged": false,
  "event_id": null,
  "acknowledged_by": null
}