How to manage Alert Groups and Alerts via API

Last updated on Jun 18, 2026

How to create a new Alert Group and Alert Rule

You always need an Alert Group to add an Alert Rule.

Below is an example of how to create a new Alert Group and Alert Rule using the STACKIT CLI. You will need to set the following environment variables (or replace them directly in the command): PROJECT_ID to your project ID and INSTANCE_ID to your instance ID.

API prerequisites: To learn how to execute these commands and locate your instance identifiers, refer to our guide on Interacting with the Observability API.

Example: Create a new Alert Group

stackit curl -X POST "https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/alertgroups" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{"name":"TestAlertGroup","interval":"60s","rules":[{"alert":"HostCheck","expr":"up == 0","for":"60s","labels":{"severity":"critical"},"annotations":{"testAnnotation":"testAnnotation"}}]}'

The request body in the command to create the Alert Group can be seen below:

{
  "name": "TestAlertGroup",
  "interval": "60s",
  "rules": [
    {
      "alert": "HostCheck",
      "expr": "up == 0",
      "for": "60s",
      "labels": {
        "severity": "critical"
      },
      "annotations": {
        "testAnnotation": "testAnnotation"
      }
    }
  ]
}

An explanation of the request body follows:

Level	Field	Description
Alert Group	`Name`	Name of the Alert Group
Alert Group	`Interval`	Time interval at which the alert rules are evaluated
Alert Group	`Rules`	Array of alert rules; multiple rules can be defined in one Alert Group
Rule	`Alert`	Name of the individual Alert Rule
Rule	`Expr`	Expression to evaluate (e.g., `up == 0` means the process is down)
Rule	`For`	Duration the condition must be true before the alert is triggered
Rule	`Labels`	Key-value pairs used to categorize or filter the alert
Rule	`Annotations`	Additional metadata such as alert description or helpful information

In the request body above, we used the expression up == 0. Below are more Kubernetes-specific examples:

Kubernetes Node not Ready

kube_node_status_condition{condition='Ready',status='true'} == 0

Expression to Alert on Failed Pods

kube_pod_status_phase{phase='Failed'} > 0

More Kubernetes examples can be found here.

How to change an existing Alert Rule

You always need an Alert Group to modify an Alert Rule.

Below is an example of how to update an existing Alert Rule. You will need to set your PROJECT_ID and INSTANCE_ID as environment variables.

Example: Update an Alert Group config

stackit curl -X PUT "https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/alertgroups/TestAlertGroup" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{"interval": "60s","rules": [{"alert": "HostCheck","expr": "up == 0","for": "60s","labels": {"severity": "critical"},"annotations": {"testAnnotation":"testAnnotation"}},{"alert": "SystemLoad","expr": "system_load1{} >= 5",  "for": "60s","labels": {"severity": "warning"}}]}'

The request body in the command to update the Alert Group can be seen below:

Example: Alert Group update request body

{
  "interval": "60s",
  "rules": [
    {
      "alert": "HostCheck",
      "expr": "up == 0",
      "for": "60s",
      "labels": {
        "severity": "critical"
      },
      "annotations": {
        "testAnnotation": "testAnnotation"
      }
    },
    {
      "alert": "SystemLoad",
      "expr": "system_load1{} >= 5",
      "for": "60s",
      "labels": {
        "severity": "warning"
      }
    }
  ]
}

How to change the name of an Alert Group

Unfortunately, it is not possible to change the name of an Alert Group directly. You have to delete it and create a new group using the desired name.

How to delete an Alert Rule

You can delete a specific Alert Rule from an Alert Group. Below is an example of deleting an Alert Rule. You will need to set your PROJECT_ID and INSTANCE_ID as environment variables:

Example: Delete an Alert Rule

stackit curl -X DELETE "https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/alertgroups/TestAlertGroup/alertrules/SystemLoad" \
  -H "accept: application/json"

How to delete an Alert Group

Below is an example of deleting an Alert Group. You will need to set your PROJECT_ID and INSTANCE_ID as environment variables:

Example: Delete an Alert Group

stackit curl -X DELETE "https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/alertgroups?groupName=TestAlertGroup" \
  -H "accept: application/json"

An alternative way of deleting an Alert Group is:

Example: Delete an Alert Group (Alternative)

stackit curl -X DELETE "https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/alertgroups/TestAlertGroup" \
  -H "accept: application/json"