The API currently encompasses the following endpoints related to creating and managing alerts. For POST requests, the body must be valid JSON and must contain a Content-Type header of application/json.

All API endpoints require a Authorization header with a value of "Bearer token" where token is a secret contained in one of your tokens.

To create a new alert or update an existing one:


It accepts a JSON body such as the following:

  "alerts": [
      "fingerprint": "highmem-net004",
      "status": "firing",
      "labels": {
        "service": "default",
        "alertname": "InstanceDown",
        "severity": "critical"
      "annotations": {
        "title": " is HighMemory (95.04%)"

There are a few required fields:

  • fingerprint: its value uniquely identifies the alert so that it can be resolved later on. It can be any kind of string up to 255 characters.
  • status: either firing or resolved
  • service: the name of the Service the alert corresponds to
  • title: a human-friendly description of the alert

Another optional, recognized field is:

  • severity: warning or critical. All alerts appear in the dashboard, but only critical level severity will result in a notification being sent. If no value is provided, level critical is assumed.

Each field can either be placed either at the root of the payload or within the labels object (as shown above, a common practice for some monitoring systems such as Prometheus.).

In the above example, our monitoring system has detected high memory usage on one of our machines, and submitted an alert. Later on, if memory usage falls below the alerting threshold, the monitoring system will send another alert with status "resolved" and the dash will clear again.

Updating the payload of an alert can be done via the same endpoint, using fingerprint to identify an existing alert.

The endpoints for assigning, acknowledging and resolving alerts are as follows:

PUT /alert/<<alert id>>/assign/<<account id>>"
PUT /alert/<<alert id>>/acknowledge"
PUT /alert/<<alert id>>/resolve"

No body is required for these endpoints.

How to get more alerts routed automatically to you team? Read more about Integrations.