Alarms

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 via Athena typically take 2-5 seconds
• Queries across many assets may take longer
• Use date ranges efficiently for better performance

curl "https://api.ebx.energy/v1/alarms?start_time=2026-02-03T00:00:00Z&end_time=2026-02-04T00:00:00Z" \
  -H "Authorization: Bearer $EBX_TOKEN"

import httpx

r = httpx.get(
    "https://api.ebx.energy/v1/alarms?start_time=2026-02-03T00:00:00Z&end_time=2026-02-04T00:00:00Z",
    headers={"Authorization": f"Bearer {token}"},
)
print(r.json())

const res = await fetch("https://api.ebx.energy/v1/alarms?start_time=2026-02-03T00:00:00Z&end_time=2026-02-04T00:00:00Z", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`,
  },
});
const data = await res.json();

{
  "alarms": [
    {
      "event_id": "<string>",
      "event_type": "alarm.opened",
      "alarm_id": "<string>",
      "alarm_key": "<string>",
      "asset_id": "<string>",
      "rule_id": "TELEMETRY-001",
      "alarm_type": "<string>",
      "severity": "INFO",
      "message": "<string>",
      "evidence": "<string>",
      "timestamp": "2026-01-01T00:00:00Z",
      "opened_at": "2026-01-01T00:00:00Z",
      "resolved_at": "2026-01-01T00:00:00Z",
      "date_partition": "<string>",
      "muted": false,
      "acknowledged": false,
      "acknowledged_by": "<string>",
      "acknowledged_at": "2026-01-01T00:00:00Z",
      "user_id": "<string>",
      "user_email": "<string>",
      "notes": "<string>",
      "mute_reason": "<string>",
      "mute_expires_at": "2026-01-01T00:00:00Z"
    }
  ],
  "total": 0,
  "limit": 0,
  "offset": 0
}

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.

curl -X PUT "https://api.ebx.energy/v1/alarms/DE_BESS_01:CONTROL-003/acknowledge" \
  -H "Authorization: Bearer $EBX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"notes":"<string>"}'

import httpx

r = httpx.put(
    "https://api.ebx.energy/v1/alarms/DE_BESS_01:CONTROL-003/acknowledge",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "notes": "<string>",
    },
)
print(r.json())

const res = await fetch("https://api.ebx.energy/v1/alarms/DE_BESS_01:CONTROL-003/acknowledge", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"notes":"<string>"}),
});
const data = await res.json();

{
  "event_id": "<string>",
  "alarm_key": "<string>",
  "acknowledged": true,
  "acknowledged_by": "<string>",
  "acknowledged_at": "2026-01-01T00:00:00Z"
}

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

A notification is accepted from human operators only: the L0 agent's machine identity may declare without one and is refused (403) otherwise — LLM text goes out only after a human reviewed it.

Effects, in order:

1. The asset_fault_notification record is inserted (pending).
2. The asset is set unavailable (reason fault) — synchronous and authoritative, committed together with the record. The window ends at notification.unavailability_end (the deadline the reviewed text states) or, without a notification, 8 hours from now.
3. Events go out via EventBridge, fire-and-forget: one partner.fault_notification per selected contact channel (email and/or Slack, resolved server-side from the contact directory; the reviewed subject/body are sent verbatim — one delivery per event), plus one partner.fault_declared audit event, always.
4. The record's status is finalised.

Callable by an EBX operator (Cognito, alarm.write) or the autonomous L0 agent (an EBX M2M integration granted alarm.write); EBX-internal because it notifies the asset's contact directory. The agent always declares with notification: null — LLM text is sent only after a human reviewed it.

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 8 h (+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 unavailability, already_declared=true is returned with that window's real bounds and no second window is created — but the events are still emitted (idempotency keys dedup downstream) so a retry after a failed request still reaches the contacts.

Response notification_status: requested (every event accepted; notified lists the contacts with their channels), not_requested (no notification), or failed (at least one event was not accepted — the unavailability 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
• notification: {language, subject, body, recipient_contact_ids, unavailability_end} or null

Path Parameters:

• alarm_key: The alarm key in format asset_id:rule_id

curl -X POST "https://api.ebx.energy/v1/alarms/DE_BESS_01:CONTROL-003/declare-asset-fault" \
  -H "Authorization: Bearer $EBX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"alarm_id":"<string>","notes":"<string>","notification":{"language":"de","subject":"<string>","body":"<string>","recipient_contact_ids":[0],"unavailability_end":"2026-09-10T13:30:00Z"}}'

import httpx

r = httpx.post(
    "https://api.ebx.energy/v1/alarms/DE_BESS_01:CONTROL-003/declare-asset-fault",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "alarm_id": "<string>",
        "notes": "<string>",
        "notification": {
            "language": "de",
            "subject": "<string>",
            "body": "<string>",
            "recipient_contact_ids": [
                0,
            ],
            "unavailability_end": "2026-09-10T13:30:00Z",
        },
    },
)
print(r.json())

const res = await fetch("https://api.ebx.energy/v1/alarms/DE_BESS_01:CONTROL-003/declare-asset-fault", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"alarm_id":"<string>","notes":"<string>","notification":{"language":"de","subject":"<string>","body":"<string>","recipient_contact_ids":[0],"unavailability_end":"2026-09-10T13:30:00Z"}}),
});
const data = await res.json();

{
  "alarm_key": "<string>",
  "asset_id": "<string>",
  "declared_by": "<string>",
  "unavailability_start": "2026-01-01T00:00:00Z",
  "unavailability_end": "2026-01-01T00:00:00Z",
  "already_declared": false,
  "notification_status": "pending",
  "notified": [
    {
      "contact_id": 0,
      "name": "<string>",
      "channels": [
        "email"
      ]
    }
  ]
}

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 fixed unavailability length, 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

curl "https://api.ebx.energy/v1/alarms/DE_BESS_01:CONTROL-003/fault-evidence" \
  -H "Authorization: Bearer $EBX_TOKEN"

import httpx

r = httpx.get(
    "https://api.ebx.energy/v1/alarms/DE_BESS_01:CONTROL-003/fault-evidence",
    headers={"Authorization": f"Bearer {token}"},
)
print(r.json())

const res = await fetch("https://api.ebx.energy/v1/alarms/DE_BESS_01:CONTROL-003/fault-evidence", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`,
  },
});
const data = await res.json();

{
  "alarm_key": "<string>",
  "asset_id": "<string>",
  "asset_name": "<string>",
  "tso": "<string>",
  "rule_id": "TELEMETRY-001",
  "rule_name": "<string>",
  "severity": "INFO",
  "facts": [
    "<string>"
  ],
  "deep_link": "<string>",
  "sustained_seconds": 0,
  "concurrent_alarm_rule_ids": [
    "<string>"
  ],
  "unavailability_hours": 0,
  "active_fault_hold": {
    "start_time": "2026-09-10T13:30:00Z",
    "end_time": "2026-09-10T13:30:00Z"
  },
  "recipients": [
    {
      "contact_id": 0,
      "name": "<string>",
      "role": "asset_owner",
      "company": "<string>",
      "email": "<string>",
      "phone": "<string>",
      "has_slack": false,
      "is_emergency": false,
      "notifiable": false
    }
  ]
}

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. LLM text never reaches a partner unreviewed — the L0 agent neither drafts nor notifies.

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 + 8 h. It is returned as unavailability_end and must be sent back as notification.unavailability_end so the declaration is checked against exactly the instant the text states. 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

Path Parameters:

• alarm_key: The alarm key in format asset_id:rule_id

curl -X POST "https://api.ebx.energy/v1/alarms/DE_BESS_01:CONTROL-003/fault-message-draft" \
  -H "Authorization: Bearer $EBX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"language":"de","assessment":"<string>"}'

import httpx

r = httpx.post(
    "https://api.ebx.energy/v1/alarms/DE_BESS_01:CONTROL-003/fault-message-draft",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "language": "de",
        "assessment": "<string>",
    },
)
print(r.json())

const res = await fetch("https://api.ebx.energy/v1/alarms/DE_BESS_01:CONTROL-003/fault-message-draft", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"language":"de","assessment":"<string>"}),
});
const data = await res.json();

{
  "language": "de",
  "subject": "<string>",
  "body": "<string>",
  "unavailability_end": "2026-09-10T13:30:00Z",
  "unverified_numbers": [
    "<string>"
  ]
}

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.

curl "https://api.ebx.energy/v1/alarms/DE_BESS_01:CONTROL-003/incident" \
  -H "Authorization: Bearer $EBX_TOKEN"

import httpx

r = httpx.get(
    "https://api.ebx.energy/v1/alarms/DE_BESS_01:CONTROL-003/incident",
    headers={"Authorization": f"Bearer {token}"},
)
print(r.json())

const res = await fetch("https://api.ebx.energy/v1/alarms/DE_BESS_01:CONTROL-003/incident", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`,
  },
});
const data = await res.json();

{
  "found": false,
  "incident_id": "<string>",
  "status": "<string>",
  "acknowledged": false,
  "acknowledged_by": "<string>",
  "acknowledged_by_agent": false,
  "acknowledged_at": "<string>",
  "started_at": "<string>",
  "url": "<string>"
}

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.

curl -X PUT "https://api.ebx.energy/v1/alarms/DE_BESS_01:CONTROL-003/mute" \
  -H "Authorization: Bearer $EBX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"duration_minutes":60,"reason":"<string>"}'

import httpx

r = httpx.put(
    "https://api.ebx.energy/v1/alarms/DE_BESS_01:CONTROL-003/mute",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "duration_minutes": 60,
        "reason": "<string>",
    },
)
print(r.json())

const res = await fetch("https://api.ebx.energy/v1/alarms/DE_BESS_01:CONTROL-003/mute", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"duration_minutes":60,"reason":"<string>"}),
});
const data = await res.json();

{
  "event_id": "<string>",
  "alarm_key": "<string>",
  "muted": true,
  "muted_by": "<string>",
  "muted_at": "2026-01-01T00:00:00Z",
  "mute_expires_at": "2026-01-01T00:00:00Z"
}

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.

curl -X DELETE "https://api.ebx.energy/v1/alarms/DE_BESS_01:CONTROL-003/mute" \
  -H "Authorization: Bearer $EBX_TOKEN"

import httpx

r = httpx.delete(
    "https://api.ebx.energy/v1/alarms/DE_BESS_01:CONTROL-003/mute",
    headers={"Authorization": f"Bearer {token}"},
)
print(r.json())

const res = await fetch("https://api.ebx.energy/v1/alarms/DE_BESS_01:CONTROL-003/mute", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${token}`,
  },
});
const data = await res.json();

{
  "event_id": "<string>",
  "alarm_key": "<string>",
  "muted": false,
  "unmuted_by": "<string>",
  "unmuted_at": "2026-01-01T00:00:00Z"
}

Get currently active alarms for all assets in an organization.

Returns all non-resolved alarms from the alarm state table (DynamoDB). 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:

• This endpoint reads from DynamoDB and is fast
• Uses GSI on status for efficient querying
• For alarm history, use GET /alarms with a time range

curl "https://api.ebx.energy/v1/alarms/active" \
  -H "Authorization: Bearer $EBX_TOKEN"

import httpx

r = httpx.get(
    "https://api.ebx.energy/v1/alarms/active",
    headers={"Authorization": f"Bearer {token}"},
)
print(r.json())

const res = await fetch("https://api.ebx.energy/v1/alarms/active", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`,
  },
});
const data = await res.json();

{
  "alarms": [
    {
      "alarm_key": "<string>",
      "alarm_id": "<string>",
      "asset_id": "<string>",
      "rule_id": "TELEMETRY-001",
      "alarm_type": "<string>",
      "severity": "INFO",
      "message": "<string>",
      "status": "open",
      "opened_at": "2026-01-01T00:00:00Z",
      "last_updated": "2026-01-01T00:00:00Z",
      "condition_active": true,
      "condition_ended_at": "2026-01-01T00:00:00Z",
      "muted": false,
      "source_muted": false,
      "mute_expires_at": "2026-01-01T00:00:00Z",
      "mute_reason": "<string>",
      "acknowledged": false,
      "acknowledged_by": "<string>",
      "acknowledged_at": "2026-01-01T00:00:00Z",
      "evidence": "<string>"
    }
  ],
  "total": 0
}

Get currently active fleet-level (pool) alarms.

Pool alarms (e.g. POOL-004, POOL-006, POOL-003) are published by the asset-state monitoring service under synthetic tso-{tso_id} partition keys — one partition per TSO zone — rather than under real asset ids. They describe the aggregated fleet per TSO zone and span all customer organizations, so this endpoint is restricted to EBX admins.

Query Parameters:

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

curl "https://api.ebx.energy/v1/alarms/active/fleet" \
  -H "Authorization: Bearer $EBX_TOKEN"

import httpx

r = httpx.get(
    "https://api.ebx.energy/v1/alarms/active/fleet",
    headers={"Authorization": f"Bearer {token}"},
)
print(r.json())

const res = await fetch("https://api.ebx.energy/v1/alarms/active/fleet", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`,
  },
});
const data = await res.json();

{
  "alarms": [
    {
      "alarm_key": "<string>",
      "alarm_id": "<string>",
      "asset_id": "<string>",
      "rule_id": "TELEMETRY-001",
      "alarm_type": "<string>",
      "severity": "INFO",
      "message": "<string>",
      "status": "open",
      "opened_at": "2026-01-01T00:00:00Z",
      "last_updated": "2026-01-01T00:00:00Z",
      "condition_active": true,
      "condition_ended_at": "2026-01-01T00:00:00Z",
      "muted": false,
      "source_muted": false,
      "mute_expires_at": "2026-01-01T00:00:00Z",
      "mute_reason": "<string>",
      "acknowledged": false,
      "acknowledged_by": "<string>",
      "acknowledged_at": "2026-01-01T00:00:00Z",
      "evidence": "<string>"
    }
  ],
  "total": 0
}

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 via Athena typically take 2-5 seconds
• Use date ranges efficiently for better performance
• For real-time updates, use the WebSocket connection

curl "https://api.ebx.energy/v1/assets/DE_BESS_01/alarms?start_time=2026-02-03T00:00:00Z&end_time=2026-02-04T00:00:00Z" \
  -H "Authorization: Bearer $EBX_TOKEN"

import httpx

r = httpx.get(
    "https://api.ebx.energy/v1/assets/DE_BESS_01/alarms?start_time=2026-02-03T00:00:00Z&end_time=2026-02-04T00:00:00Z",
    headers={"Authorization": f"Bearer {token}"},
)
print(r.json())

const res = await fetch("https://api.ebx.energy/v1/assets/DE_BESS_01/alarms?start_time=2026-02-03T00:00:00Z&end_time=2026-02-04T00:00:00Z", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`,
  },
});
const data = await res.json();

{
  "alarms": [
    {
      "event_id": "<string>",
      "event_type": "alarm.opened",
      "alarm_id": "<string>",
      "alarm_key": "<string>",
      "asset_id": "<string>",
      "rule_id": "TELEMETRY-001",
      "alarm_type": "<string>",
      "severity": "INFO",
      "message": "<string>",
      "evidence": "<string>",
      "timestamp": "2026-01-01T00:00:00Z",
      "opened_at": "2026-01-01T00:00:00Z",
      "resolved_at": "2026-01-01T00:00:00Z",
      "date_partition": "<string>",
      "muted": false,
      "acknowledged": false,
      "acknowledged_by": "<string>",
      "acknowledged_at": "2026-01-01T00:00:00Z",
      "user_id": "<string>",
      "user_email": "<string>",
      "notes": "<string>",
      "mute_reason": "<string>",
      "mute_expires_at": "2026-01-01T00:00:00Z"
    }
  ],
  "total": 0,
  "limit": 0,
  "offset": 0
}

Get currently active alarms for a specific asset.

Returns all non-resolved alarms from the alarm state table (DynamoDB). 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:

• This endpoint reads from DynamoDB and is very fast (<100ms)
• For alarm history, use GET /assets/{asset_id}/alarms with a time range

curl "https://api.ebx.energy/v1/assets/DE_BESS_01/alarms/active" \
  -H "Authorization: Bearer $EBX_TOKEN"

import httpx

r = httpx.get(
    "https://api.ebx.energy/v1/assets/DE_BESS_01/alarms/active",
    headers={"Authorization": f"Bearer {token}"},
)
print(r.json())

const res = await fetch("https://api.ebx.energy/v1/assets/DE_BESS_01/alarms/active", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`,
  },
});
const data = await res.json();

{
  "alarms": [
    {
      "alarm_key": "<string>",
      "alarm_id": "<string>",
      "asset_id": "<string>",
      "rule_id": "TELEMETRY-001",
      "alarm_type": "<string>",
      "severity": "INFO",
      "message": "<string>",
      "status": "open",
      "opened_at": "2026-01-01T00:00:00Z",
      "last_updated": "2026-01-01T00:00:00Z",
      "condition_active": true,
      "condition_ended_at": "2026-01-01T00:00:00Z",
      "muted": false,
      "source_muted": false,
      "mute_expires_at": "2026-01-01T00:00:00Z",
      "mute_reason": "<string>",
      "acknowledged": false,
      "acknowledged_by": "<string>",
      "acknowledged_at": "2026-01-01T00:00:00Z",
      "evidence": "<string>"
    }
  ],
  "total": 0
}