Alarms

Required scopes: alarm.read

Required scopes: alarm.read

Get alarm history for all assets in an organization.

Returns a paginated list of alarm events across all assets belonging to the organization. Results are ordered by timestamp (most recent first).

Query Parameters:

• start_time: Start of the time range (required, ISO 8601 format)
• end_time: End of the time range (required, ISO 8601 format)
• organization_id: Target organization. Optional for users that map to exactly one organization — required for EBX admins and multi-org users.
• severity: Filter by severity levels (optional, can specify multiple)
• event_type: Filter by event types (optional, can specify multiple)
• limit: Maximum number of alarms to return (default: 100, max: 1000)
• offset: Offset for pagination (default: 0)

Event Types:

• alarm.opened: New alarm opened
• alarm.resolved: Alarm resolved (condition cleared)
• alarm.acknowledged: Alarm acknowledged by user
• alarm.muted: Alarm muted by user
• alarm.unmuted: Alarm unmuted by user

Performance Notes:

• Historical queries typically take 2-5 seconds
• Queries across many assets may take longer
• Use date ranges efficiently for better performance

Required scopes: alarm.write

Acknowledge an alarm.

Path Parameters:

• alarm_key: The alarm key in format asset_id:rule_id

Request Body:

• notes: Optional notes about the acknowledgment

Note: The acknowledge action is asynchronous. The state update will be reflected in subsequent queries and WebSocket updates.

Required scopes: alarm.write

Declare a clear asset/EMS fault for an open alarm.

An operator's notification is sent verbatim. The L0 agent's machine identity writes its own message, under four rules: emergency contacts only (403 not_emergency_contact), in the language each of them reads (422 language_mismatch), no links, IP addresses, domains or e-mail addresses in its subject or body, in any script (422 link_in_message), and the body goes out inside the automated-message frame (signature, operations contact, reference line, Control Center link). The checks run before anything is written.

A fault takes the asset out entirely, or — with power_limit — holds it to the power it can still deliver (a partial fault, e.g. one inverter lost).

The asset is held back with a power limit of reason fault before the response is returned: 0/0 makes it unavailable; otherwise the requested power_limit bounds apply. The window ends at notification.unavailability_end or, without a notification, unavailability_hours from now. The declaration is recorded in the audit history. When a notification is provided, delivery is requested for each selected contact's email and/or Slack channel, following the message rules above. Delivery happens asynchronously; acceptance does not confirm receipt by the contacts.

Callable by an EBX operator with alarm.write or the autonomous L0 agent (an EBX M2M integration granted alarm.write); EBX-internal because it notifies the asset's contact directory.

Notification: null declares the fault without notifying anyone. Otherwise recipient_contact_ids (at least one) must be contacts of the alarm's asset that have an email and/or Slack webhook, and unavailability_end must lie more than 30 min and at most unavailability_hours (+5 min) ahead — else 422 (detail stale_draft: draft the message again). Both are checked before anything is written.

Idempotency: when the asset is already under an active FAULT hold of the extent the request states (taken out entirely when power_limit is null, else the same bounds), already_declared=true is returned with that hold's real window and bounds and no second window is created. Notification delivery is requested again, with duplicate requests deduplicated, so delivery can be retried after a failed request. Any other extent is 409 fault_hold_differs — a full fault on a partially held asset included: a hold is never changed implicitly. A notification whose power_limit (the draft's) differs from the declaration's is 422 stale_draft.

Amend (a further loss): with amend: true the active FAULT hold is narrowed to power_limit from now on — it ends now and continues with the new bounds until its own end — and amended=true is returned with the continuation's window. Only narrowing is an amend (taking the asset out entirely narrows any partial hold): wider bounds in either direction are 409 fault_hold_widens (a recovery — lift or adjust the hold in the Availability tab), no active FAULT hold is 409 no_fault_hold, and the hold's own extent joins it (already_declared=true), so a retry is safe. A notification states the hold's deadline, as on a hand-off. The L0 agent amends like it declares. Another power limit overlapping the new window (maintenance, commercial) is 409 conflicting_limit.

Response notification_status: requested (all notification and audit requests accepted; notified lists the contacts with their channels), not_requested (no notification), or failed (at least one notification or audit request was not accepted — the fault hold still applies; retry, the declaration is idempotent).

Request Body:

• alarm_id: optional lifecycle id of the reviewed alarm. If it no longer matches the asset's current alarm for this rule, the request is rejected with 409 so a declaration is never applied to a different incident than the one reviewed.
• notes: optional operator notes recorded on the unavailability
• unavailability_hours: the hold's length, 1–720 h (720 = until further notice); default 8, the L0 agent's hold. Ignored when the asset is already under a FAULT unavailability.
• power_limit: {upper_limit_mw, lower_limit_mw} — declare a partial fault; null takes the asset out entirely
• amend: narrow the active FAULT hold to power_limit (a further loss); see Amend
• notification: {language, subject, body, recipient_contact_ids, unavailability_end} or null

Path Parameters:

• alarm_key: The alarm key in format asset_id:rule_id

Required scopes: alarm.write

Assemble the evidence for an open alarm without taking any action (never calls an LLM).

Returns the deterministic, evidence-backed facts (asset, rule and its catalog name, sustained duration, setpoint/return values, concurrent alarms), a Control Center deep link, the FAULT unavailability the asset is already under right now (active_fault_hold, null when none — a declaration then notifies against that hold instead of creating a new window), and the asset's contacts as selectable recipients (notifiable = has an email and/or Slack webhook; is_emergency contacts are pre-selected in the Control Center).

Used by the Control Center "Declare asset fault" modal and by the L0 agent to gather context; the message itself is drafted by POST .../fault-message-draft.

Path Parameters:

• alarm_key: The alarm key in format asset_id:rule_id

Required scopes: alarm.write

Draft the natural-language message (subject + plain-text body) a partner receives.

The facts are computed in code into a fact sheet; the ops-inbox narrator (an LLM under strict no-invention rules) writes the message from it in the requested language; the signature and reference footer are appended. The draft is a proposal: the operator reviews and edits it in the Control Center, and the declare endpoint sends exactly the reviewed text. The L0 agent does not draft here: it writes its own message and declares with it, inside the automated-message frame (see the declare endpoint).

The draft quotes the deadline of the hold that applies: the asset's active FAULT unavailability when it is already under one (the L0 agent or an earlier declaration), else now + unavailability_hours. A hold of 30 days is "until further notice": the text names no end time. The deadline is returned as unavailability_end and must be sent back as notification.unavailability_end — with the same unavailability_hours — so the declaration is checked against exactly the instant the draft was written for. An open-ended active hold has no deadline to quote: 422 open_ended_hold (adjust it in the Availability tab first). unverified_numbers lists the numbers in the draft that do not appear in the evidence — advisory, for the operator to check before sending; nothing is rejected on that basis.

Takes tens of seconds. 503 when the narrator is not configured, 502 when it fails or returns an unusable draft — there is no fallback text; the operator writes the message.

Request Body:

• language: de (default in the Control Center, formal "Sie") or en
• assessment: an existing hedged hypothesis to build on (the L0 judge's); null from the modal
• unavailability_hours: the hold's length, 1–720 h (720 = until further notice); default 8
• power_limit: {upper_limit_mw, lower_limit_mw} for a partial fault, so the draft states the power the asset keeps; null for a full unavailability. Under an active FAULT hold it must state that hold's extent, else 409 fault_hold_differs. The draft returns it as power_limit; send it back as notification.power_limit.
• amend: draft for an explicit amend of the active FAULT hold to power_limit (a further loss) — the draft states the narrowed bounds and the hold's deadline; same rules as amend on the declaration.

Path Parameters:

• alarm_key: The alarm key in format asset_id:rule_id

Required scopes: alarm.read

Return the BetterStack incident status for an alarm's current lifecycle.

Lets the Control Center show whether the on-call page is acknowledged — and whether a human or the L0 agent acknowledged it — reflecting acknowledgements made outside the portal too. Best-effort: returns found=False when the alarm has no live state, no incident was opened (not production-critical), or ops-inbox is unavailable, so the alarm view degrades instead of erroring.

Required scopes: alarm.write

Mute an alarm.

Muted alarms are still recorded in the event log but are filtered from notification channels (SNS, PagerDuty). WebSocket connections still receive muted alarm events.

Path Parameters:

• alarm_key: The alarm key in format asset_id:rule_id

Request Body:

• duration_minutes: Duration to mute in minutes (1–10080, defaults to 60)
• reason: Optional reason for muting

Note: The mute action is asynchronous.

Required scopes: alarm.write

Unmute an alarm.

Removes the operator mute. Asset-unavailability suppression remains effective.

Path Parameters:

• alarm_key: The alarm key in format asset_id:rule_id

Note: The unmute action is asynchronous.

Required scopes: alarm.write

What the asset can still do, and whether the cause is the asset's — read-only, computed in code (never an LLM).

For any open alarm:

• Physical signature: per direction (discharge, charge; magnitudes in MW) the nameplate, the baseline before the alarm opened, and the lowest/highest/latest available power over the assessment window (the alarm's opening, at most 30 minutes back); the usable energy (MWh) the same way, and where the SoC sits in it. The EMS's own asset_status.
• proposed_power_limit: per direction the lowest available power seen in the window, at most the nameplate, floored to the kW — the bounds a partial fault would declare (or amend to). Null with a reason when a direction has no telemetry or nothing is left (a full fault).
• peers: the other assets of the asset's pool (same TSO and pool id — the same dispatcher, TSO link and data pipeline), each with when its telemetry last arrived and its open alarms. Healthy peers make a shared EBX cause very unlikely. Null outside any pool.
• asset_path: the asset's own EBX path, which no peer shares — per MRX box the Asset Adapter's link, the Pulse configuration status and when EBX last set its target.
• isolation: alarms opened on any other asset in the last 30 minutes (a simultaneous burst is a system signature).
• registry: limits created on this asset in the last 24 hours, and the asset's last registry change.
• history: FAULT holds and this rule's alarm lifecycles on this asset over 30 days.
• impact: the blocks of the next 24 hours whose commitments (wholesale + 1.25 × FCR + aFRR) exceed the proposed limit.

Used by the L0 agent before it judges an alarm. Takes seconds (it reads the fleet's alarms and the alarm history); fault-evidence stays the fast preview.

Path Parameters:

• alarm_key: The alarm key in format asset_id:rule_id

Required scopes: alarm.read

Get currently active alarms for all assets in an organization.

Returns all non-resolved alarms. This is a fast, real-time view of current alarm state across the organization.

Query Parameters:

• organization_id: Target organization. Optional for users that map to exactly one organization — required for EBX admins and multi-org users.
• severity: Filter by severity levels (optional, can specify multiple)
• include_muted: Include muted alarms in the response (default: true)

Performance Notes:

• For alarm history, use GET /alarms with a time range

Required scopes: alarm.read

Get currently active fleet-level (pool) alarms.

Pool alarms (e.g. POOL-004, POOL-006, POOL-003) describe the aggregated fleet per TSO zone and span all customer organizations, so this endpoint is restricted to EBX admins. Their asset_id is tso-{tso_id}, identifying the TSO zone rather than an individual asset.

Query Parameters:

• include_muted: Include muted alarms in the response (default: true)

Required scopes: alarm.read

Get the alarm events of one TSO pool within a time range.

The history counterpart of GET /alarms/active/fleet: pool alarms live under the synthetic tso-{tso_id} partition, which has no asset-registry entry, so the asset history route cannot serve them. Restricted to EBX admins like every pool alarm. Results are ordered by timestamp (most recent first).

Required scopes: alarm.read

Get alarms for a specific asset within a time range.

Returns a paginated list of alarms that have been triggered for the specified asset. Results are ordered by timestamp (most recent first).

Query Parameters:

• start_time: Start of the time range (required, ISO 8601 format)
• end_time: End of the time range (required, ISO 8601 format)
• severity: Filter by severity levels (optional, can specify multiple)
• limit: Maximum number of alarms to return (default: 100, max: 1000)
• offset: Offset for pagination (default: 0)

Alarm Severity Levels:

• INFO: Informational alerts
• WARNING: Potential issues that may require attention
• ERROR: Errors that need immediate attention
• CRITICAL: Critical issues requiring immediate action

Performance Notes:

• Historical queries typically take 2-5 seconds
• Use date ranges efficiently for better performance
• For real-time updates, use the WebSocket connection

Required scopes: alarm.read

Get currently active alarms for a specific asset.

Returns all non-resolved alarms. This is a fast, real-time view of current alarm state.

Query Parameters:

• include_muted: Include muted alarms in the response (default: true)

Performance Notes:

• For alarm history, use GET /assets/{asset_id}/alarms with a time range