Anomalies

Overview

Anomaly management is built on three resources:

Anomalies are detected by the anomaly detection of the Apio products running on the platform, according to the configurations and subscriptions of the project. Your applications can also record anomalies of their own through the API.

Anomaly Configurations

A configuration describes a kind of anomaly and its severity levels:

{
  "name": "No data received",
  "description": "The device has not sent any measurement for longer than the threshold.",
  "type": "Communication",
  "category": "devices",
  "subCategory": "Energy meter",
  "code": "COM",
  "enabled": true,
  "checkContext": "<provided by Apio>",
  "checkFunction": "<provided by Apio>",
  "severity": [
    {
      "level": 2,
      "operator": "gt",
      "threshold": "3600",
      "formattedThreshold": "1",
      "uom": "h",
      "via": ["websocket"]
    },
    {
      "level": 4,
      "operator": "gt",
      "threshold": "86400",
      "formattedThreshold": "24",
      "uom": "h",
      "via": ["email"]
    }
  ]
}

Severity levels

Each configuration defines one or more severity levels, from 1 (lowest) to 5 (highest):

Anomaly Subscriptions

A subscription applies a configuration to the resources it should watch, optionally with its own severity levels:

{
  "name": "Energy meters of plant North",
  "configurationId": "my-configuration-uuid",
  "resources": [
    "/devices/meter-1-uuid",
    "/devices/meter-2-uuid"
  ],
  "enabled": true
}

Resources are referenced as /{resourceType}/{uuid}, for example /devices/…, /nodes/…, /plants/… or /assets/…. Set enabled to false to suspend a subscription without deleting it.

Anomalies

An anomaly records an occurrence of a configuration on one or more resources:

{
  "uuid": "4b8f3c2e-1d7a-4f6b-9a51-2e0c7d9f8a10",
  "projectId": "my-project-id",
  "configurationId": "my-configuration-uuid",
  "resources": ["/devices/meter-1-uuid"],
  "startedAt": "2026-10-01T08:00:00.000Z",
  "severity": [
    {
      "level": 2,
      "startedAt": "2026-10-01T08:00:00.000Z",
      "endedAt": "2026-10-01T09:00:00.000Z",
      "duration": 3600000
    },
    {
      "level": 4,
      "startedAt": "2026-10-01T09:00:00.000Z"
    }
  ],
  "metadata": {}
}

• startedAt, endedAt, duration: when the anomaly started and ended, and its duration in milliseconds. An anomaly without endedAt is still open
• resources: the resources involved, in the same /{resourceType}/{uuid} form used by subscriptions
• severity: the history of severity levels, each with its own start, end and duration. A severity without endedAt is still active
• metadata: free-form details added by the detection

When you read an anomaly, its configuration is included in the configuration field.

Reading anomalies

To get the name and type of the resources involved in an anomaly:

{
  "status": true,
  "data": [
    { "uuid": "meter-1-uuid", "name": "Meter 1", "type": "devices" }
  ]
}

Closing an anomaly

Closing sets endedAt to the current time and computes duration. Every severity that is still active is closed at the same time.

Events

Anomalies generate events like other resources: apio.core.anomalies.created, apio.core.anomalies.updated and apio.core.anomalies.closed.

Notifications

When an anomaly is created, the platform notifies it for each active severity, on the channels set in via for that level in the configuration:

• email: sent to the users of the project who have the apio.notifications.email.receive permission
• websocket: delivered in real time to the connected users who have the apio.notifications.websocket.receive permission

When the configuration lists additional permissions, only users who also have those permissions are notified. Notifications are grouped and sent at short intervals.

Anomalies that are already closed when they are created, or that have no resources, are not notified.

Email content can be customized per project, and per configuration, with templates. Contact Apio to set up custom templates.

Permissions