Alerts API

Overview

Alert APIs manage alert definitions that evaluate monitor data and trigger actions. Alerts run on the conductor and evaluate incoming monitor samples from servers.

List Alerts

GET /api/app/get_alerts/v1 Fetch all alert definitions.

Response

{
  "code": 0,
  "rows": [
    {
      "id": "load_avg_high",
      "title": "High CPU Load",
      "expression": "monitors.load_avg >= (cpu.cores + 1)",
      "message": "CPU load average is too high: {{float(monitors.load_avg)}} ({{cpu.cores}} CPU cores)",
      "enabled": true,
      "samples": 1
    }
  ],
  "list": { "length": 1 }
}

Get Alert

GET /api/app/get_alert/v1 Fetch a single alert definition.

Parameters

string

required

Alert ID

Example

cURL

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://your-server.com/api/app/get_alert/v1?id=load_avg_high"

Create Alert

POST /api/app/create_alert/v1 Create a new alert definition. Requires the create_alerts privilege.

Parameters

title

string

required

Display name for the alert

expression

string

required

JEXL expression that evaluates to true when alert should fire

message

string

required

Alert message with optional template macros

enabled

boolean

Whether alert is active (default: true)

samples

number

Number of consecutive samples required to trigger (default: 1)

actions

array

Array of action definitions to execute when alert fires

string

Custom alert ID (auto-generated if omitted)

Example

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "title": "High CPU Load",
    "expression": "monitors.load_avg >= (cpu.cores + 1)",
    "message": "CPU load average is too high: {{float(monitors.load_avg)}} ({{cpu.cores}} CPU cores)",
    "enabled": true,
    "samples": 1,
    "actions": [
      {
        "type": "email",
        "enabled": true,
        "condition": "alert_new",
        "users": ["admin"],
        "email": ""
      }
    ]
  }' \
  https://your-server.com/api/app/create_alert/v1

The expression is evaluated against server data. Use monitors.MONITOR_ID to reference monitor values and standard server properties like cpu.cores.

Update Alert

POST /api/app/update_alert/v1 Update an existing alert. Requires the edit_alerts privilege.

Parameters

string

required

Alert ID to update

...

any

Any alert properties to update

Example

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "id": "load_avg_high",
    "enabled": false
  }' \
  https://your-server.com/api/app/update_alert/v1

Test Alert

POST /api/app/test_alert/v1 Test an alert expression and message against a specific server. Requires the edit_alerts privilege.

Parameters

server

string

required

Server ID to test against

expression

string

required

Alert expression to test

message

string

required

Alert message template to test

Response

result

boolean

Whether the alert would fire with current server data

message

string

The evaluated message with template macros replaced

Example

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "server": "s12345",
    "expression": "monitors.load_avg >= (cpu.cores + 1)",
    "message": "CPU load average is too high: {{float(monitors.load_avg)}} ({{cpu.cores}} CPU cores)"
  }' \
  https://your-server.com/api/app/test_alert/v1

Delete Alert

POST /api/app/delete_alert/v1 Delete an alert definition. Requires the delete_alerts privilege.

Parameters

string

required

Alert ID to delete

Example

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"id": "load_avg_high"}' \
  https://your-server.com/api/app/delete_alert/v1

Deletions are permanent and cannot be undone. All alert invocations are also deleted in the background.

Get Alert Invocations

POST /api/app/get_alert_invocations/v1 Fetch information about multiple alert invocations (historical alert firing events).

Parameters

ids

array

required

Array of alert invocation IDs

Example

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"ids": ["inv123", "inv456"]}' \
  https://your-server.com/api/app/get_alert_invocations/v1

Response

{
  "code": 0,
  "alerts": [
    {
      "id": "inv123",
      "alert": "load_avg_high",
      "server": "s12345",
      "date": 1234567890,
      "active": false,
      "modified": 1234567900
    }
  ]
}

Manage Alert Invocation Tickets

POST /api/app/manage_alert_invocation_tickets/v1 Update the ticket list for an alert invocation. Requires the edit_tickets privilege.

Parameters

string

required

Alert invocation ID

tickets

array

required

Array of ticket IDs to associate

Example

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "id": "inv123",
    "tickets": ["t12345", "t67890"]
  }' \
  https://your-server.com/api/app/manage_alert_invocation_tickets/v1

Delete Alert Invocation

POST /api/app/delete_alert_invocation/v1 Delete a single alert invocation. Requires the delete_alerts privilege.

Parameters

string

required

Alert invocation ID to delete

Example

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"id": "inv123"}' \
  https://your-server.com/api/app/delete_alert_invocation/v1

Message Template Macros

Alert messages support template macros using double curly braces:

{{expression}}

Common examples:

Macro	Description
`{{monitors.load_avg}}`	Monitor value
`{{float(monitors.load_avg)}}`	Formatted float
`{{cpu.cores}}`	Server property
`{{mem.total}}`	Memory total

Example Message

CPU load average is {{float(monitors.load_avg)}} on a {{cpu.cores}} core system ({{int(monitors.load_avg / cpu.cores * 100)}}% per core)

Action Types

Alerts support multiple action types:

Type	Description
`email`	Send email notification
`web_hook`	Call webhook
`run_event`	Trigger another event
`channel`	Send to notification channel
`ticket`	Create support ticket

Actions are triggered based on the condition field: alert_new when alert first fires, alert_cleared when it clears.

Overview

Endpoints

Overview

List Alerts

Response

Get Alert

Parameters

Example

Create Alert

Parameters

Example

Update Alert

Parameters

Example

Test Alert

Parameters

Response

Example

Delete Alert

Parameters

Example

Get Alert Invocations

Parameters

Example

Manage Alert Invocation Tickets

Parameters

Example

Delete Alert Invocation

Parameters

Example

Message Template Macros

Example Message

Action Types

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Overview

​List Alerts

​Response

​Get Alert

​Parameters

​Example

​Create Alert

​Parameters

​Example

​Update Alert

​Parameters

​Example

​Test Alert

​Parameters

​Response

​Example

​Delete Alert

​Parameters

​Example

​Get Alert Invocations

​Parameters

​Example

​Manage Alert Invocation Tickets

​Parameters

​Example

​Delete Alert Invocation

​Parameters

​Example

​Message Template Macros

​Example Message

​Action Types

Build docs developers (and LLMs) love

Overview

List Alerts

Response

Get Alert

Parameters

Example

Create Alert

Parameters

Example

Update Alert

Parameters

Example

Test Alert

Parameters

Response

Example

Delete Alert

Parameters

Example

Get Alert Invocations

Parameters

Example

Manage Alert Invocation Tickets

Parameters

Example

Delete Alert Invocation

Parameters

Example

Message Template Macros

Example Message

Action Types