How to manage Loki alerts via API

Prerequisites

• You have created an Observability instance with Loki.
• You are familiar with creating Alerts via the API.
• Your Alertmanager is exposed.
• You understand the Authentication Overview and have the required access to the Observability API.

For a complete list of all available endpoints, parameters, and schemas, refer to the STACKIT Observability Logs API Specification.

To execute the following commands, you need to set your PROJECT_ID and INSTANCE_ID as environment variables (or replace them directly in the commands).

If you need help locating these identifiers or want to learn how the stackit curl wrapper handles authentication automatically, refer to our central guide: Interacting with the Observability API.

How to create Loki alerts with a new Alert Group

To create a new Loki Alert Group, you must send an HTTP POST request to the logs-alertgroups endpoint.

Request body example:

{
  "name": "YourAlertGroupName",
  "interval": "30m",
  "rules": [
    {
      "alert": "error",
      "expr": "count_over_time({app=\"yourAppName\", severity=\"critical\"} |~ \".*error*\"[5m]) > 25",
      "for": "0m",
      "labels": {
        "app": "yourAppName",
        "project_name": "yourProjectName",
        "id": "yourAppId",
        "severity": "critical"
      },
      "annotations": {
        "summary": "Too many errors are coming frequently!"
      }
    }
  ]
}

Command:

stackit curl -X POST "https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/logs-alertgroups" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{"name":"YourAlertGroupName","interval":"30m","rules":[{"alert":"error","expr":"count_over_time({app=\"yourAppName\", severity=\"critical\"} |~ \".*error*\"[5m]) > 25","for":"0m","labels":{"app":"yourAppName","project_name":"yourProjectName","id":"yourAppId","severity":"critical"},"annotations":{"summary":"Too many errors are coming frequently!"}}]}'

Verify the creation of Loki Alert Groups and Alert Rules

You can verify the creation of your Loki Alert Group and Alert Rules by issuing an HTTP GET request to the same endpoint.

Command:

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

How to create Loki alerts with an existing Alert Group

To add a new alert to an already existing Alert Group, you need to update the group by providing the complete configuration request body.

1. Retrieve the existing configuration: First, get the current setup of your Alert Group by executing a GET request (as shown above). Copy the JSON response.

2. Modify the payload: Add your new alert rule to the rules array in the JSON payload you just copied.

3. Update the Alert Group: Send the modified JSON payload via an HTTP PUT request to update the group (replace <GROUP_NAME> with the name of your specific Alert Group):

   stackit curl -X PUT "https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/logs-alertgroups/<GROUP_NAME>" \
     -H "accept: application/json" \
     -H "Content-Type: application/json" \
     --data '<YOUR_MODIFIED_JSON_PAYLOAD>'