API Reference

Note

All datetime parameters must be in ISO 8601 format in UTC time (using time zone designator “Z”) and expressed to millisecond precision as recommended by the W3C Date and Time Formats Note eg. 2017-06-19T11:16:19.744Z

Alerts

Create an alert

Creates a new alert, or updates an existing alert if the environment- resource-event combination already exists.

POST /alert

Input

Name	Type	Description
resource	string	Required resource under alarm
event	string	Required event name
environment	string	environment, used to namespace the resource
severity	string	see Alert Severities table
correlate	list	list of related event names
status	string	see Alert Status table
service	list	list of effected services
group	string	used to group events of similar type
value	string	event value
text	string	freeform text description
tags	set	set of tags
attributes	dict	dictionary of key-value pairs
origin	string	monitoring component that generated the alert
type	string	event type
createTime	datetime	time alert was generated at the origin
timeout	integer	seconds before alert is considered stale
rawData	string	unprocessed raw data

Note

Only resource and event are mandatory. The status can be dynamically assigned by the Alerta API based on the severity.

Example Request

$ curl -XPOST http://localhost:8080/alert \
-H 'Authorization: Key demo-key' \
-H 'Content-type: application/json' \
-d '{
      "attributes": {
        "region": "EU"
      },
      "correlate": [
        "HttpServerError",
        "HttpServerOK"
      ],
      "environment": "Production",
      "event": "HttpServerError",
      "group": "Web",
      "origin": "curl",
      "resource": "web01",
      "service": [
        "example.com"
      ],
      "severity": "major",
      "tags": [
        "dc1"
      ],
      "text": "Site is down.",
      "type": "exceptionAlert",
      "value": "Bad Gateway (501)"
    }'

Example Response

201 CREATED

{
  "alert": {
    "attributes": {
      "flapping": false,
      "ip": "127.0.0.1",
      "notify": true,
      "region": "EU"
    },
    "correlate": [
      "HttpServerError",
      "HttpServerOK"
    ],
    "createTime": "2018-01-27T21:00:12.999Z",
    "customer": null,
    "duplicateCount": 0,
    "environment": "Production",
    "event": "HttpServerError",
    "group": "Web",
    "history": [
      {
        "event": "HttpServerError",
        "href": "http://localhost:8080/alert/17d8e7ea-b3ba-4bb1-9c5a-29e60865f258",
        "id": "17d8e7ea-b3ba-4bb1-9c5a-29e60865f258",
        "severity": "major",
        "status": null,
        "text": "Site is down.",
        "type": "severity",
        "updateTime": "2018-01-27T21:00:12.999Z",
        "value": "Bad Gateway (501)"
      }
    ],
    "href": "http://localhost:8080/alert/17d8e7ea-b3ba-4bb1-9c5a-29e60865f258",
    "id": "17d8e7ea-b3ba-4bb1-9c5a-29e60865f258",
    "lastReceiveId": "17d8e7ea-b3ba-4bb1-9c5a-29e60865f258",
    "lastReceiveTime": "2018-01-27T21:00:13.070Z",
    "origin": "curl",
    "previousSeverity": "indeterminate",
    "rawData": null,
    "receiveTime": "2018-01-27T21:00:13.070Z",
    "repeat": false,
    "resource": "web01",
    "service": [
      "example.com"
    ],
    "severity": "major",
    "status": "open",
    "tags": [
      "dc1"
    ],
    "text": "Site is down.",
    "timeout": 86400,
    "trendIndication": "moreSevere",
    "type": "exceptionAlert",
    "value": "Bad Gateway (501)"
  },
  "id": "17d8e7ea-b3ba-4bb1-9c5a-29e60865f258",
  "status": "ok"
}

Example Response (during blackout period)

202 ACCEPTED

{
  "message": "Suppressed alert during blackout period",
  "id": "1711c57e-5c6a-4c39-881b-9d8d174feafe",
  "status": "ok"
}

Retrieve an alert

Retrieves an alert with the given alert ID.

GET /alert/:id

Example Request

$ curl http://localhost:8080/alert/17d8e7ea-b3ba-4bb1-9c5a-29e60865f258 \
-H 'Authorization: Key demo-key'

Example Response

200 OK

{
  "alert": {
    "attributes": {
      "flapping": false,
      "ip": "127.0.0.1",
      "notify": true,
      "region": "EU"
    },
    "correlate": [
      "HttpServerError",
      "HttpServerOK"
    ],
    "createTime": "2018-01-27T21:00:12.999Z",
    "customer": null,
    "duplicateCount": 0,
    "environment": "Production",
    "event": "HttpServerError",
    "group": "Web",
    "history": [
      {
        "event": "HttpServerError",
        "href": "http://localhost:8080/alert/17d8e7ea-b3ba-4bb1-9c5a-29e60865f258",
        "id": "17d8e7ea-b3ba-4bb1-9c5a-29e60865f258",
        "severity": "major",
        "status": null,
        "text": "Site is down.",
        "type": "severity",
        "updateTime": "2018-01-27T21:00:12.999Z",
        "value": "Bad Gateway (501)"
      }
    ],
    "href": "http://localhost:8080/alert/17d8e7ea-b3ba-4bb1-9c5a-29e60865f258",
    "id": "17d8e7ea-b3ba-4bb1-9c5a-29e60865f258",
    "lastReceiveId": "17d8e7ea-b3ba-4bb1-9c5a-29e60865f258",
    "lastReceiveTime": "2018-01-27T21:00:13.070Z",
    "origin": "curl",
    "previousSeverity": "indeterminate",
    "rawData": null,
    "receiveTime": "2018-01-27T21:00:13.070Z",
    "repeat": false,
    "resource": "web01",
    "service": [
      "example.com"
    ],
    "severity": "major",
    "status": "open",
    "tags": [
      "dc1"
    ],
    "text": "Site is down.",
    "timeout": 86400,
    "trendIndication": "moreSevere",
    "type": "exceptionAlert",
    "value": "Bad Gateway (501)"
  },
  "status": "ok",
  "total": 1
}

Set alert status

Sets the status of an alert, and logs the status change to the alert history.

PUT /alert/:id/status

Input

Name	Type	Description
status	string	Required New status from open, assign, ack, closed, expired
text	string	reason for status change
timeout	integer	Seconds.

Example Request

$ curl -XPUT http://localhost:8080/alert/17d8e7ea-b3ba-4bb1-9c5a-29e60865f258/status \
-H 'Authorization: Key demo-key' \
-H 'Content-type: application/json' \
-d '{
      "status": "ack",
      "text": "disk needs replacing.",
      "timeout": 7200
    }'

Action alert

Takes an action against an alert which can change the status or severity of the alert and logs the action to the alert history.

PUT /alert/:id/action

Input

Name	Type	Description
action	string	Required Action from ack, unack` shelve, unshelve, close
text	string	reason for action
timeout	integer	Seconds.

Example Request

$ curl -XPUT http://localhost:8080/alert/17d8e7ea-b3ba-4bb1-9c5a-29e60865f258/action \
-H 'Authorization: Key demo-key' \
-H 'Content-type: application/json' \
-d '{
      "action": "shelve",
      "text": "swap out servers.",
      "timeout": 7200
    }'

Tag and untag alerts

Adds or removes tag values from the set of tags for an alert.

PUT /alert/:id/tag
PUT /alert/:id/untag

Input

Name	Type	Description
tags	set	tags to add or remove

Example Request

$ curl -XPUT http://localhost:8080/alert/17d8e7ea-b3ba-4bb1-9c5a-29e60865f258/tag \
-H 'Authorization: Key demo-key' \
-H 'Content-type: application/json' \
-d '{
      "tags": [
        "linux",
        "linux2.6",
        "dell"
      ]
    }'

Update alert attributes

Adds, deletes or modifies alert attributes. To delete an attribute assign “null” to the attribute.

PUT /alert/:id/attributes

Input

Name	Type	Description
attributes	dict	dictionary of key-value attributes

Example Request

$ curl -XPUT http://localhost:8080/alert/17d8e7ea-b3ba-4bb1-9c5a-29e60865f258/attributes \
-H 'Authorization: Key demo-key' \
-H 'Content-type: application/json' \
-d '{
      "attributes": {
        "incidentKey": "1234abcd",
        "ip": "10.1.1.1",
        "region": null
      }
    }'

Add an alert note

Adds a note to an alert.

PUT /alert/:id/note

Input

Name	Type	Description
note	string	note text

Example Request

$ curl -XPUT http://localhost:8080/alert/17d8e7ea-b3ba-4bb1-9c5a-29e60865f258/note \
-H 'Authorization: Key demo-key' \
-H 'Content-type: application/json' \
-d '{ "note": "This is the sample note" }'

List alert notes

Lists all notes for an alert.

GET /alert/:id/notes

Example Request

$ curl http://localhost:8080/alert/17d8e7ea-b3ba-4bb1-9c5a-29e60865f258/notes \
-H 'Authorization: Key demo-key'

Update an alert note

Updates an existing note on an alert.

PUT /alert/:id/note/:note_id

Input

Name	Type	Description
note	string	Required updated note text

Example Request

$ curl -XPUT http://localhost:8080/alert/17d8e7ea-b3ba-4bb1-9c5a-29e60865f258/note/ab01c02d-1234-5678-abcd-ef0123456789 \
-H 'Authorization: Key demo-key' \
-H 'Content-type: application/json' \
-d '{ "note": "Updated note text" }'

Delete an alert note

Permanently deletes a note from an alert.

DELETE /alert/:id/note/:note_id

Example Request

$ curl -XDELETE http://localhost:8080/alert/17d8e7ea-b3ba-4bb1-9c5a-29e60865f258/note/ab01c02d-1234-5678-abcd-ef0123456789 \
-H 'Authorization: Key demo-key'

Delete an alert

Permanently deletes an alert. It cannot be undone.

DELETE /alert/:id

Example Request

$ curl -XDELETE http://localhost:8080/alert/17d8e7ea-b3ba-4bb1-9c5a-29e60865f258 \
-H 'Authorization: Key demo-key'

Search alerts

Find alerts using various alert attributes or a mongo-type query parameter to filter results.

GET /alerts

Parameters

Name	Type	Description
<attr>	string	any alert attribute. eg. status=open
q (*)	string	query string query syntax eg. service:Web OR resource:web
from-date	datetime	lastReceiveTime > from-date
to-date	datetime	lastReceiveTime <= to-date (now)
sort-by	string	attr to sort by (default:lastReceiveTime)
reverse	boolean	change direction of default sort order
page	integer	number between 1 and total pages (default: 1)
page-size	integer	default: 1000 (set DEFAULT_PAGE_SIZE )
show-raw-data	boolean	show raw data
show-history	boolean	show alert history

Deprecated since version 6.3: The q parameter using Mongo-style query format has been replaced with a query format based on Lucene query syntax supported by both MongoDB and Postgres backends. For more information see API Query String Syntax.

Example Request

$ curl http://localhost:8080/alerts?group=Web \
-H 'Authorization: Key demo-key'

Example Response

200 OK

{
  "alerts": [
    {
      "attributes": {
        "flapping": false,
        "incidentKey": "1234abcd",
        "ip": "10.1.1.1",
        "notify": true
      },
      "correlate": [
        "HttpServerError",
        "HttpServerOK"
      ],
      "createTime": "2018-01-27T21:00:12.999Z",
      "customer": null,
      "duplicateCount": 0,
      "environment": "Production",
      "event": "HttpServerError",
      "group": "Web",
      "history": [
        {
          "event": "HttpServerError",
          "href": "http://localhost:8080/alert/17d8e7ea-b3ba-4bb1-9c5a-29e60865f258",
          "id": "17d8e7ea-b3ba-4bb1-9c5a-29e60865f258",
          "severity": "major",
          "status": null,
          "text": "Site is down.",
          "type": "severity",
          "updateTime": "2018-01-27T21:00:12.999Z",
          "value": "Bad Gateway (501)"
        },
        {
          "event": "HttpServerError",
          "href": "http://localhost:8080/alert/17d8e7ea-b3ba-4bb1-9c5a-29e60865f258",
          "id": "17d8e7ea-b3ba-4bb1-9c5a-29e60865f258",
          "severity": null,
          "status": "ack",
          "text": "disk needs replacing.",
          "type": "status",
          "updateTime": "2018-01-27T21:04:42.412Z",
          "value": null
        }
      ],
      "href": "http://localhost:8080/alert/17d8e7ea-b3ba-4bb1-9c5a-29e60865f258",
      "id": "17d8e7ea-b3ba-4bb1-9c5a-29e60865f258",
      "lastReceiveId": "17d8e7ea-b3ba-4bb1-9c5a-29e60865f258",
      "lastReceiveTime": "2018-01-27T21:00:13.070Z",
      "origin": "curl",
      "previousSeverity": "indeterminate",
      "rawData": null,
      "receiveTime": "2018-01-27T21:00:13.070Z",
      "repeat": false,
      "resource": "web01",
      "service": [
        "example.com"
      ],
      "severity": "major",
      "status": "ack",
      "tags": [
        "dc1",
        "linux",
        "linux2.6",
        "dell"
      ],
      "text": "Site is down.",
      "timeout": 86400,
      "trendIndication": "moreSevere",
      "type": "exceptionAlert",
      "value": "Bad Gateway (501)"
    }
  ],
  "autoRefresh": true,
  "lastTime": "2018-01-27T21:00:13.070Z",
  "more": false,
  "page": 1,
  "pageSize": 1000,
  "pages": 1,
  "severityCounts": {
    "major": 1
  },
  "status": "ok",
  "statusCounts": {
    "ack": 1
  },
  "total": 1
}

List all alert history

Returns a list of alert severity and status changes.

GET /alerts/history

Parameters

Name	Type	Description
<attr>	string

Example Request

$ curl http://localhost:8080/alerts/history?service=example.com \
-H 'Authorization: Key demo-key'

Example Response

200 OK

{
  "history": [
    {
      "attributes": {
        "flapping": false,
        "incidentKey": "1234abcd",
        "ip": "10.1.1.1",
        "notify": true
      },
      "customer": null,
      "environment": "Production",
      "event": "HttpServerError",
      "group": "Web",
      "href": "http://localhost:8080/alert/17d8e7ea-b3ba-4bb1-9c5a-29e60865f258",
      "id": "17d8e7ea-b3ba-4bb1-9c5a-29e60865f258",
      "origin": "curl",
      "resource": "web01",
      "service": [
        "example.com"
      ],
      "severity": "major",
      "tags": [
        "dc1",
        "linux",
        "linux2.6",
        "dell"
      ],
      "text": "Site is down.",
      "type": "severity",
      "updateTime": "2018-01-27T21:00:12.999Z",
      "value": "Bad Gateway (501)"
    },
    {
      "attributes": {
        "flapping": false,
        "incidentKey": "1234abcd",
        "ip": "10.1.1.1",
        "notify": true
      },
      "customer": null,
      "environment": "Production",
      "event": "HttpServerError",
      "group": "Web",
      "href": "http://localhost:8080/alert/17d8e7ea-b3ba-4bb1-9c5a-29e60865f258",
      "id": "17d8e7ea-b3ba-4bb1-9c5a-29e60865f258",
      "origin": "curl",
      "resource": "web01",
      "service": [
        "example.com"
      ],
      "status": "ack",
      "tags": [
        "dc1",
        "linux",
        "linux2.6",
        "dell"
      ],
      "text": "disk needs replacing.",
      "type": "status",
      "updateTime": "2018-01-27T21:04:42.412Z"
    }
  ],
  "status": "ok",
  "total": 2
}

Get severity and status counts for alerts

Returns a count of alerts grouped by severity and status.

GET /alerts/count

Parameters

Name	Type	Description
<attr>	string

Example Request

$ curl http://localhost:8080/alerts/count?environment=Production \
-H 'Authorization: Key demo-key'

Example Response

200 OK

{
  "severityCounts": {
    "critical": 1,
    "major": 1
  },
  "status": "ok",
  "statusCounts": {
    "ack": 1,
    "open": 1
  },
  "total": 2
}

Top 10 alerts by resource

Returns a list of the top 10 resources grouped by an alert attribute. By default it is grouped by event but this can be any valid attribute.

GET /alerts/top10/count
GET /alerts/top10/flapping

Parameters

Name	Type	Description
<attr>	string
q	dict	mongo query see `Mongo Query Operators`_
group-by	string	any valid alert attribute. Default:event

Example Request

$ curl http://localhost:8080/alerts/top10?group-by=group \
-H 'Authorization: Key demo-key'

Example Response

200 OK

{
  "status": "ok",
  "top10": [
    {
      "count": 2,
      "duplicateCount": 0,
      "environments": [
        "Production"
      ],
      "group": "Web",
      "resources": [
        {
          "href": "http://localhost:8080/alert/0099bae5-9683-48a1-a49d-f566fe143770",
          "id": "0099bae5-9683-48a1-a49d-f566fe143770",
          "resource": "web02"
        },
        {
          "href": "http://localhost:8080/alert/e9fb05a0-b65c-4faa-8868-6f06a74a2b5b",
          "id": "e9fb05a0-b65c-4faa-8868-6f06a74a2b5b",
          "resource": "web01"
        }
      ],
      "services": [
        "example.com"
      ]
    }
  ],
  "total": 1
}

Top N alerts

Returns a list of the top N resources grouped by an alert attribute, where N is configurable via the topn query parameter. Also includes standing alerts (ie. alerts that have been open for a long time).

GET /alerts/topn/count
GET /alerts/topn/flapping
GET /alerts/top10/standing
GET /alerts/topn/standing

Parameters

Name	Type	Description
<attr>	string
q	dict	mongo query see `Mongo Query Operators`_
group-by	string	any valid alert attribute. Default:event
topn	integer	number of results to return. Default: 10

Example Request

$ curl http://localhost:8080/alerts/topn/count?group-by=group&topn=20 \
-H 'Authorization: Key demo-key'

Environments

An environment cannot be created – it is a dynamically derived resource based on existing alerts.

List all environments

Returns a list of environments and an alert count for each.

GET /environments

Parameters

Name	Type	Description
<attr>	string

Example Request

$ curl http://localhost:8080/environments \
-H 'Authorization: Key demo-key'

Example Response

200 OK

{
  "environments": [
    {
      "count": 2,
      "environment": "Production"
    }
  ],
  "status": "ok",
  "total": 1
}

Services

A service cannot be created – it is a dynamically derived resource based on existing alerts.

List all services

Returns a list of services grouped by environment and an alert count for each.

GET /services

Parameters

Name	Type	Description
<attr>	string

Example Request

$ curl http://localhost:8080/services?environment=Production \
-H 'Authorization: Key demo-key'

Example Response

200 OK

{
  "services": [
    {
      "count": 2,
      "environment": "Production",
      "service": "example.com"
    }
  ],
  "status": "ok",
  "total": 1
}

Tags

A tag cannot be created – it is a dynamically derived resource based on existing alerts.

List all tags

Returns a list of tags grouped by environment and an alert count for each.

GET /tags

Parameters

Name	Type	Description
<attr>	string

Example Request

$ curl http://localhost:8080/tags?environment=Production \
-H 'Authorization: Key demo-key'

Example Response

200 OK

{
    "status": "ok",
    "tags": [
        {
            "count": 2,
            "environment": "Production",
            "tag": "linux"
        },
        {
            "count": 1,
            "environment": "Production",
            "tag": "dc2"
        },
        {
            "count": 1,
            "environment": "Production",
            "tag": "hp"
        },
        {
            "count": 2,
            "environment": "Production",
            "tag": "dell"
        },
        {
            "count": 2,
            "environment": "Production",
            "tag": "dc1"
        },
        {
            "count": 2,
            "environment": "Production",
            "tag": "linux2.6"
        }
    ],
    "total": 6
}

Blackout Periods

Create a blackout

Create a new blackout period for alert suppression.

POST /blackout

Input

Name	Type	Description
environment	string	Required
resource	string
service	list
event	string
group	string
tags	list
startTime	datetime	start time of blackout. Default: now
endTime	datetime	end time. Default: now + BLACKOUT_DURATION
duration	integer	seconds. Default: BLACKOUT_DURATION Only used if endTime not defined

Example Request

$ curl -XPOST http://localhost:8080/blackout \
-H 'Authorization: Key demo-key' \
-H 'Content-type: application/json' \
-d '{
      "environment": "Production",
      "service": ["example.com"],
      "group": "Web"
    }'

Example Response

201 CREATED

{
  "blackout": {
    "customer": null,
    "duration": 3600,
    "endTime": "2018-01-27T22:10:31.705Z",
    "environment": "Production",
    "event": null,
    "group": "Web",
    "href": "http://localhost:8080/blackout/79d12b79-45b9-4419-80e4-1f6c17478eb6",
    "id": "79d12b79-45b9-4419-80e4-1f6c17478eb6",
    "priority": 3,
    "remaining": 3599,
    "resource": null,
    "service": [
      "example.com"
    ],
    "startTime": "2018-01-27T21:10:31.705Z",
    "status": "active",
    "tags": []
  },
  "id": "79d12b79-45b9-4419-80e4-1f6c17478eb6",
  "status": "ok"
}

List all blackouts

Returns a list of blackout periods, including expired blackouts.

GET /blackouts

Example Request

$ curl http://localhost:8080/blackouts \
-H 'Authorization: Key demo-key'

Example Response

200 OK

{
  "blackouts": [
    {
      "customer": null,
      "duration": 3600,
      "endTime": "2018-01-27T22:10:31.705Z",
      "environment": "Production",
      "event": null,
      "group": "Web",
      "href": "http://localhost:8080/blackout/79d12b79-45b9-4419-80e4-1f6c17478eb6",
      "id": "79d12b79-45b9-4419-80e4-1f6c17478eb6",
      "priority": 3,
      "remaining": 3345,
      "resource": null,
      "service": [
        "example.com"
      ],
      "startTime": "2018-01-27T21:10:31.705Z",
      "status": "active",
      "tags": []
    },
    {
      "customer": null,
      "duration": 3600,
      "endTime": "2018-01-27T22:14:32.377Z",
      "environment": "Development",
      "event": null,
      "group": "Performance",
      "href": "http://localhost:8080/blackout/c17832d4-c477-4eb1-b2d5-662e7a3600be",
      "id": "c17832d4-c477-4eb1-b2d5-662e7a3600be",
      "priority": 5,
      "remaining": 3586,
      "resource": null,
      "service": [],
      "startTime": "2018-01-27T21:14:32.377Z",
      "status": "active",
      "tags": []
    }
  ],
  "status": "ok",
  "total": 2
}

Delete a blackout

Permanently deletes a blackout period. It cannot be undone.

DELETE /blackout/:id

Example Request

$ curl -XDELETE http://localhost:8080/blackout/c17832d4-c477-4eb1-b2d5-662e7a3600be \
-H 'Authorization: Key demo-key'

Retrieve a blackout

Retrieves a blackout with the given blackout ID.

GET /blackout/:id

Example Request

$ curl http://localhost:8080/blackout/79d12b79-45b9-4419-80e4-1f6c17478eb6 \
-H 'Authorization: Key demo-key'

Update a blackout

Updates the specified blackout period by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Uses the same input fields as creating a blackout.

PUT /blackout/:id

Input

Name	Type	Description
environment	string
resource	string
service	list
event	string
group	string
tags	list
startTime	datetime	start time of blackout
endTime	datetime	end time of blackout
duration	integer	seconds. Only used if endTime not defined

Example Request

$ curl -XPUT http://localhost:8080/blackout/79d12b79-45b9-4419-80e4-1f6c17478eb6 \
-H 'Authorization: Key demo-key' \
-H 'Content-type: application/json' \
-d '{
      "environment": "Production",
      "duration": 7200
    }'

Heartbeats

Send a heartbeat

Creates a new heartbeat, or updates an existing heartbeat if a heartbeat from the origin already exists.

POST /heartbeat

Input

Name	Type	Description
origin	string
tags	list
attributes	dict	dictionary of key-value pairs
createTime	datetime	time alert was generated at the origin
timeout	integer	Seconds.

Example Request

$ curl -XPOST http://localhost:8080/heartbeat \
-H 'Authorization: Key demo-key' \
-H 'Content-type: application/json' \
-d '{
      "origin": "cluster05",
      "timeout": 120,
      "tags": ["db05", "dc2"],
      "attributes": {
        "environment": "Production",
        "service": [
          "Core",
          "HA"
        ],
        "group": "Network",
        "severity": "major"
      }
    }'

Example Response

201 CREATED

{
  "heartbeat": {
    "attributes": {
      "environment": "Production",
      "group": "Network",
      "service": [
        "Core",
        "HA"
      ],
      "severity": "major"
    },
    "createTime": "2020-06-07T20:31:58.244Z",
    "customer": null,
    "href": "http://localhost:8080/heartbeat/ea2f41e3-16c4-412f-aaf2-874e3c4c771b",
    "id": "ea2f41e3-16c4-412f-aaf2-874e3c4c771b",
    "latency": 0,
    "maxLatency": 2000,
    "origin": "cluster05",
    "receiveTime": "2020-06-07T20:31:58.244Z",
    "since": 0,
    "status": "ok",
    "tags": [
      "db05",
      "dc2"
    ],
    "timeout": 120,
    "type": "Heartbeat"
  },
  "id": "ea2f41e3-16c4-412f-aaf2-874e3c4c771b",
  "status": "ok"
}

Get a heartbeat

Retrieves a heartbeat based on the heartbeat ID.

GET /heartbeat/:id

Example Request

$ curl http://localhost:8080/heartbeat/ea2f41e3-16c4-412f-aaf2-874e3c4c771b \
-H 'Authorization: Key demo-key'

Example Response

200 OK

{
  "heartbeat": {
    "attributes": {
      "environment": "Production",
      "group": "Network",
      "service": [
        "Core",
        "HA"
      ],
      "severity": "major"
    },
    "createTime": "2020-06-07T20:31:58.244Z",
    "customer": null,
    "href": "http://localhost:8080/heartbeat/ea2f41e3-16c4-412f-aaf2-874e3c4c771b",
    "id": "ea2f41e3-16c4-412f-aaf2-874e3c4c771b",
    "latency": 0,
    "maxLatency": 2000,
    "origin": "cluster05",
    "receiveTime": "2020-06-07T20:31:58.244Z",
    "since": 91,
    "status": "ok",
    "tags": [
      "db05",
      "dc2"
    ],
    "timeout": 120,
    "type": "Heartbeat"
  },
  "status": "ok",
  "total": 1
}

List all heartbeats

Returns a list of all heartbeats.

GET /heartbeats

Example Request

$ curl http://localhost:8080/heartbeats \
-H 'Authorization: Key demo-key'

Example Response

200 OK

{
  "heartbeats": [
    {
      "attributes": {
        "environment": "Production",
        "group": "Network",
        "service": [
          "Core",
          "HA"
        ],
        "severity": "major"
      },
      "createTime": "2020-06-07T20:31:58.244Z",
      "customer": null,
      "href": "http://localhost:8080/heartbeat/ea2f41e3-16c4-412f-aaf2-874e3c4c771b",
      "id": "ea2f41e3-16c4-412f-aaf2-874e3c4c771b",
      "latency": 0,
      "maxLatency": 2000,
      "origin": "cluster05",
      "receiveTime": "2020-06-07T20:31:58.244Z",
      "since": 136,
      "status": "expired",
      "tags": [
        "db05",
        "dc2"
      ],
      "timeout": 120,
      "type": "Heartbeat"
    }
  ],
  "status": "ok",
  "total": 1
}

Delete a heartbeat

Permanently deletes a heartbeat. It cannot be undone.

DELETE /heartbeat/:id

Example Request

$ curl -XDELETE http://localhost:8080/heartbeat/e0582765-ee64-4944-8a94-1869a079d81f \
-H 'Authorization: Key demo-key'

API Keys

Create an API key

Creates a new API key.

POST /key

Input

Name	Type	Description
user	string	username
scopes	string	admin, write, or read
text	string	freeform description text
expireTime	string
customer	string	Admin use only

Example Request

$ curl -XPOST http://localhost:8080/key \
-H 'Authorization: Key demo-key' \
-H 'Content-type: application/json' \
-d '{
      "user": "admin@alerta.io",
      "scopes": ["write"],
      "text": "API key for external system"
    }'

Example Response

201 CREATED

{
  "data": {
    "count": 0,
    "customer": null,
    "expireTime": "2019-01-27T22:18:42.245Z",
    "href": "http://localhost:8080/key/_Jwm-qaGa0kBM9R1CyyQn-0qxLtBtij4ToQf6beL",
    "id": "ca931aec-4e56-496f-a8d6-be11d93ddaed",
    "key": "_Jwm-qaGa0kBM9R1CyyQn-0qxLtBtij4ToQf6beL",
    "lastUsedTime": null,
    "scopes": [
      "write"
    ],
    "text": "API key for external system",
    "type": "read-write",
    "user": "admin@alerta.io"
  },
  "key": "_Jwm-qaGa0kBM9R1CyyQn-0qxLtBtij4ToQf6beL",
  "status": "ok"
}

List all API keys

Returns a list of API keys.

GET /keys

Example Request

$ curl http://localhost:8080/keys \
-H 'Authorization: Key demo-key'

Example Response

200 OK

{
  "keys": [
    {
      "count": 0,
      "customer": null,
      "expireTime": "2019-01-27T22:18:42.245Z",
      "href": "http://localhost:8080/key/_Jwm-qaGa0kBM9R1CyyQn-0qxLtBtij4ToQf6beL",
      "id": "ca931aec-4e56-496f-a8d6-be11d93ddaed",
      "key": "_Jwm-qaGa0kBM9R1CyyQn-0qxLtBtij4ToQf6beL",
      "lastUsedTime": null,
      "scopes": [
        "write"
      ],
      "text": "API key for external system",
      "type": "read-write",
      "user": "admin@alerta.io"
    },
    {
      "count": 21,
      "customer": null,
      "expireTime": "2019-01-27T19:22:27.120Z",
      "href": "http://localhost:8080/key/demo-key",
      "id": "532c9b59-9e90-40d4-8a3b-887362a79e9c",
      "key": "demo-key",
      "lastUsedTime": "2018-01-27T22:19:04.113Z",
      "scopes": [
        "admin",
        "write",
        "read"
      ],
      "text": "Admin key created by alertad script",
      "type": "read-write",
      "user": "foo@foobar.com"
    }
  ],
  "status": "ok",
  "total": 2
}

Delete an API key

Permanently deletes an API key. It cannot be undone.

DELETE /key/:key

Example Request

$ curl -XDELETE http://localhost:8080/key/532c9b59-9e90-40d4-8a3b-887362a79e9cO8rhJSKrdfQWXqRhvSwJQJRZg9yU0s2Z4VLP4855 \
-H 'Authorization: Key demo-key'

Retrieve an API key

Retrieves an API key with the given key.

GET /key/:key

Example Request

$ curl http://localhost:8080/key/_Jwm-qaGa0kBM9R1CyyQn-0qxLtBtij4ToQf6beL \
-H 'Authorization: Key demo-key'

Update an API key

Updates the specified API key by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

PUT /key/:key

Input

Name	Type	Description
scopes	string	admin, write, or read
text	string	freeform description text
expireTime	string
customer	string	Admin use only

Example Request

$ curl -XPUT http://localhost:8080/key/_Jwm-qaGa0kBM9R1CyyQn-0qxLtBtij4ToQf6beL \
-H 'Authorization: Key demo-key' \
-H 'Content-type: application/json' \
-d '{
      "scopes": ["read"],
      "text": "Read-only API key"
    }'

Users

Create a user

Creates a new Basic Auth user.

POST /auth/signup

Input

Name	Type	Description
name	string
email	string
password	string
text	string

Example Request

$ curl -XPOST http://localhost:8080/auth/signup \
-H 'Authorization: Key demo-key' \
-H 'Content-type: application/json' \
-d '{
      "name": "Joe Bloggs",
      "email": "joe.bloggs@example.com",
      "password": "secret",
      "text": "demo user"
    }'

Example Response

200 OK

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI4Y2IwYjYyNC0zY2Q3LTQ1YjktOThhNS01ZGZhYzVmMDE2NmMiLCJyb2xlcyI6WyJ1c2VyIl0sImlzcyI6Imh0dHA6Ly9sb2NhbGhvc3Q6ODA4MC8iLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJqb2UuYmxvZ2dzQGV4YW1wbGUuY29tIiwibmFtZSI6IkpvZSBCbG9nZ3MiLCJlbWFpbCI6ImpvZS5ibG9nZ3NAZXhhbXBsZS5jb20iLCJzY29wZSI6InJlYWQgd3JpdGUiLCJqdGkiOiI2ODlhMmY3Yy0zNTJlLTQ5M2ItYWZjYi1iOWUwOTE3ODAyMDgiLCJleHAiOjE1MTMxODIxNDcsInByb3ZpZGVyIjoiYmFzaWMiLCJpYXQiOjE1MTE5NzI1NDcsIm5iZiI6MTUxMTk3MjU0NywiYXVkIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwLyJ9.c5jpr8YksoJmoZ6KUwsYP5fgwZr-jdA4W3JUCbv1vXU"
}

Update a user

Updates the specified user by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

PUT /user/:user

Input

Name	Type	Description
name	string
email	string
password	string
status	string
roles	set	set of roles
attributes	dict	dictionary of key-value pairs
text	string
email_verified	boolean

Example Request

$ curl -XPUT http://localhost:8080/user/0a35bfd8-1175-4cd2-96f6-eda9861fd15d \
-H 'Authorization: Key demo-key' \
-H 'Content-type: application/json' \
-d '{
      "password": "p8ssw0rd",
      "text": "test user",
      "email_verified": false
    }'

Update me

Updates the logged in user by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

It is not allowed to update roles, email_verified status or change the email to one that is already associated with another user.

PUT /user/me

Input

Name	Type	Description
name	string
email	string
password	string
status	string
attributes	dict	dictionary of key-value pairs
text	string

Example Request

$ curl -XPUT http://localhost:8080/user/me \
-H 'Authorization: Key demo-key' \
-H 'Content-type: application/json' \
-d '{
      "password": "p8ssw0rd",
      "text": "test user me"
    }'

Update user attributes

Updates the specified user attributes.

PUT /user/:id/attributes

Input

Name	Type	Description
attributes	dict	dictionary of key-value pairs

Example Request

$ curl -XPUT http://localhost:8080/user/0a35bfd8-1175-4cd2-96f6-eda9861fd15d/attributes \
-H 'Authorization: Key demo-key' \
-H 'Content-type: application/json' \
-d '{
      "attributes": {
        "team": "developers"
      }
  }'

Update user me attributes

Updates the logged in user attributes.

PUT /user/me/attributes

Input

Name	Type	Description
attributes	dict	dictionary of key-value pairs

Example Request

$ curl -XPUT http://localhost:8080/user/me/attributes \
-H 'Authorization: Key demo-key' \
-H 'Content-type: application/json' \
-d '{
      "attributes": {
        "teams": ["developers", "operations"]
      }
  }'

Retrieve a user

Retrieves a user with the given user ID.

GET /user/:id

Example Request

$ curl http://localhost:8080/user/0a35bfd8-1175-4cd2-96f6-eda9861fd15d \
-H 'Authorization: Key demo-key'

Get current user

Returns the currently authenticated user.

GET /user/me

Example Request

$ curl http://localhost:8080/user/me \
-H 'Authorization: Key demo-key'

Get current user attributes

Returns attributes for the currently authenticated user.

GET /user/me/attributes

Example Request

$ curl http://localhost:8080/user/me/attributes \
-H 'Authorization: Key demo-key'

List user groups

Returns a list of groups that the specified user belongs to.

GET /user/:id/groups

Example Request

$ curl http://localhost:8080/user/0a35bfd8-1175-4cd2-96f6-eda9861fd15d/groups \
-H 'Authorization: Key demo-key'

List all users

Returns a list of users.

GET /users

Example Request

$ curl http://localhost:8080/users \
-H 'Authorization: Key demo-key'

Example Response

200 OK

{
  "domains": [
    "*"
  ],
  "groups": [
    "*"
  ],
  "orgs": [
    "*"
  ],
  "status": "ok",
  "time": "2017-01-02T00:24:00.393Z",
  "total": 2,
  "users": [
    {
      "createTime": "2017-01-01T23:49:38.486Z",
      "email_verified": false,
      "id": "b91811e7-52dd-4a8f-adae-b4d5c628d6f8",
      "login": "jane.doe@example.org",
      "name": "Jane Doe",
      "provider": "basic",
      "role": "user",
      "text": "demo user"
    },
    {
      "createTime": "2017-01-02T00:23:24.487Z",
      "email_verified": true,
      "id": "166b41d6-849f-440d-ba30-1a5345d86fb6",
      "login": "joe.bloggs@example.com",
      "name": "Joe Bloggs",
      "provider": "basic",
      "role": "user",
      "text": "demo user"
    }
  ]
}

Delete a user

Permanently deletes a user. It cannot be undone.

DELETE /user/:user

Example Request

$ curl -XDELETE http://localhost:8080/user/166b41d6-849f-440d-ba30-1a5345d86fb6 \
-H 'Authorization: Key demo-key'

Groups

Create a group

Creates a new group.

POST /group

Input

Name	Type	Description
name	string	Required group name
text	string	description of the group

Example Request

$ curl -XPOST http://localhost:8080/group \
-H 'Authorization: Key demo-key' \
-H 'Content-type: application/json' \
-d '{
      "name": "alerta_ops",
      "text": "Operations team"
    }'

Get a group

Retrieves a group with the given group ID.

GET /group/:id

Example Request

$ curl http://localhost:8080/group/5c0c5c8e-1b2a-3c4d-5e6f-7a8b9c0d1e2f \
-H 'Authorization: Key demo-key'

List all groups

Returns a list of groups.

GET /groups

Example Request

$ curl http://localhost:8080/groups \
-H 'Authorization: Key demo-key'

Update a group

Updates the specified group by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

PUT /group/:id

Input

Name	Type	Description
name	string	group name
text	string	description of the group

Example Request

$ curl -XPUT http://localhost:8080/group/5c0c5c8e-1b2a-3c4d-5e6f-7a8b9c0d1e2f \
-H 'Authorization: Key demo-key' \
-H 'Content-type: application/json' \
-d '{
      "name": "alerta_ops",
      "text": "Updated description"
    }'

Delete a group

Permanently deletes a group.

DELETE /group/:id

Example Request

$ curl -XDELETE http://localhost:8080/group/5c0c5c8e-1b2a-3c4d-5e6f-7a8b9c0d1e2f \
-H 'Authorization: Key demo-key'

List group members

Returns a list of users that are members of the specified group.

GET /group/:id/users

Example Request

$ curl http://localhost:8080/group/5c0c5c8e-1b2a-3c4d-5e6f-7a8b9c0d1e2f/users \
-H 'Authorization: Key demo-key'

Add user to group

Adds a user to the specified group.

PUT /group/:id/user/:user_id

Example Request

$ curl -XPUT http://localhost:8080/group/5c0c5c8e-1b2a-3c4d-5e6f-7a8b9c0d1e2f/user/166b41d6-849f-440d-ba30-1a5345d86fb6 \
-H 'Authorization: Key demo-key'

Remove user from group

Removes a user from the specified group.

DELETE /group/:id/user/:user_id

Example Request

$ curl -XDELETE http://localhost:8080/group/5c0c5c8e-1b2a-3c4d-5e6f-7a8b9c0d1e2f/user/166b41d6-849f-440d-ba30-1a5345d86fb6 \
-H 'Authorization: Key demo-key'

Permissions

Create permission

Creates a new permission lookup. Used to match user groups/roles to scopes.

POST /perm

Input

Name	Type	Description
scopes	string
match	regex

Example Request

$ curl -XPOST http://localhost:8080/perm \
-H 'Authorization: Key demo-key' \
-H 'Content-type: application/json' \
-d '{
      "scopes": ["read", "write", "admin:alerts"],
      "match": "alerta_ops"
    }'

Example Response

201 CREATED

{
  "id": "40c2daee-1d77-44d5-b62d-e3e446396cef",
  "permission": {
    "id": "40c2daee-1d77-44d5-b62d-e3e446396cef",
    "match": "alerta_ops",
    "scopes": [
      "read",
      "write",
      "admin:keys"
    ]
  },
  "status": "ok"
}

List all permissions

Returns a list of permissions.

GET /perms

Example Request

$ curl http://localhost:8080/perms \
-H 'Authorization: Key demo-key'

Example Response

200 OK

{
  "permissions": [
    {
      "id": "5b726183-019f-4add-b6dc-caba87e873f7",
      "match": "alerta_ro",
      "scopes": [
        "read"
      ]
    },
    {
      "id": "f4c91af3-5222-4201-9da0-02c40122f4c4",
      "match": "alerta_rw",
      "scopes": [
        "read",
        "write"
      ]
    },
    {
      "id": "1f84f919-c07a-4bd1-93b0-26e28871257f",
      "match": "alerta_ops",
      "scopes": [
        "read",
        "write",
        "admin:keys"
      ]
    }
  ],
  "status": "ok",
  "time": "2017-07-29T21:42:30.500Z",
  "total": 3
}

Delete a permission

Permanently delete a permission. It cannot be undone.

DELETE /perm/:perm

Example Request

$ curl -XDELETE http://localhost:8080/perm/1f84f919-c07a-4bd1-93b0-26e28871257f \
-H 'Authorization: Key demo-key'

Retrieve a permission

Retrieves a permission with the given permission ID.

GET /perm/:perm

Example Request

$ curl http://localhost:8080/perm/40c2daee-1d77-44d5-b62d-e3e446396cef \
-H 'Authorization: Key demo-key'

Update a permission

Updates the specified permission by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

PUT /perm/:perm

Input

Name	Type	Description
scopes	string
match	regex

Example Request

$ curl -XPUT http://localhost:8080/perm/40c2daee-1d77-44d5-b62d-e3e446396cef \
-H 'Authorization: Key demo-key' \
-H 'Content-type: application/json' \
-d '{
      "scopes": ["read", "write"],
      "match": "alerta_rw"
    }'

Scopes

List all scopes

Returns a list of all available permission scopes.

GET /scopes

Example Request

$ curl http://localhost:8080/scopes \
-H 'Authorization: Key demo-key'

Customers

Create a customer

Creates a new customer lookup. Used to match user logins to customers.

POST /customer

Input

Name	Type	Description
customer	string
match	regex

Example Request

$ curl -XPOST http://localhost:8080/customer \
-H 'Authorization: Key demo-key' \
-H 'Content-type: application/json' \
-d '{
      "customer": "Example Corp.",
      "match": "example.com"
    }'

Example Response

201 CREATED

{
  "customer": {
    "customer": "Example Corp.",
    "id": "289ca657-ea2c-4775-9e07-cc96844cc717",
    "match": "example.com"
  },
  "id": "289ca657-ea2c-4775-9e07-cc96844cc717",
  "status": "ok"
}

List all customers

Returns a list of customers.

GET /customers

Example Request

$ curl http://localhost:8080/customers \
-H 'Authorization: Key demo-key'

Example Response

200 OK

{
  "customers": [
    {
      "customer": "Example Corp.",
      "id": "289ca657-ea2c-4775-9e07-cc96844cc717",
      "match": "example.com"
    },
    {
      "customer": "Example Org.",
      "id": "90f4e211-c815-4112-9e1a-6e53de5a59c6",
      "match": "example.org"
    }
  ],
  "status": "ok",
  "time": "2017-01-02T01:21:38.958Z",
  "total": 2
}

Delete a customer

Permanently delete a customer. It cannot be undone.

DELETE /customer/:customer

Example Request

$ curl -XDELETE http://localhost:8080/customer/90f4e211-c815-4112-9e1a-6e53de5a59c6 \
-H 'Authorization: Key demo-key'

Bulk Operations

Bulk operations allow performing actions on multiple alerts at once. Alerts are selected using the same query parameters as the search alerts endpoint. Long-running bulk operations return a task ID that can be polled for status.

Get task status

Retrieves the status of an asynchronous bulk operation task.

GET /_bulk/task/:task_id

Example Request

$ curl http://localhost:8080/_bulk/task/7d8e7ea-b3ba-4bb1-9c5a-29e60865f258 \
-H 'Authorization: Key demo-key'

Bulk update alert status

Updates the status of multiple alerts selected by query parameters.

PUT /_bulk/alerts/status

Input

Name	Type	Description
status	string	Required new status
text	string	reason for status change
timeout	integer	seconds

Example Request

$ curl -XPUT http://localhost:8080/_bulk/alerts/status?environment=Production \
-H 'Authorization: Key demo-key' \
-H 'Content-type: application/json' \
-d '{
      "status": "ack",
      "text": "Bulk acknowledged"
    }'

Bulk action on alerts

Performs an action on multiple alerts selected by query parameters.

PUT /_bulk/alerts/action

Input

Name	Type	Description
action	string	Required action to perform
text	string	reason for action
timeout	integer	seconds

Example Request

$ curl -XPUT http://localhost:8080/_bulk/alerts/action?environment=Production \
-H 'Authorization: Key demo-key' \
-H 'Content-type: application/json' \
-d '{
      "action": "shelve",
      "text": "Bulk shelved for maintenance"
    }'

Bulk tag alerts

Adds tags to multiple alerts selected by query parameters.

PUT /_bulk/alerts/tag

Input

Name	Type	Description
tags	list	Required list of tags to add

Example Request

$ curl -XPUT http://localhost:8080/_bulk/alerts/tag?environment=Production \
-H 'Authorization: Key demo-key' \
-H 'Content-type: application/json' \
-d '{
      "tags": ["bulk-tagged", "maintenance"]
    }'

Bulk untag alerts

Removes tags from multiple alerts selected by query parameters.

PUT /_bulk/alerts/untag

Input

Name	Type	Description
tags	list	Required list of tags to remove

Example Request

$ curl -XPUT http://localhost:8080/_bulk/alerts/untag?environment=Production \
-H 'Authorization: Key demo-key' \
-H 'Content-type: application/json' \
-d '{
      "tags": ["maintenance"]
    }'

Bulk update alert attributes

Updates attributes on multiple alerts selected by query parameters.

PUT /_bulk/alerts/attributes

Input

Name	Type	Description
attributes	dict	Required dictionary of key-value pairs

Example Request

$ curl -XPUT http://localhost:8080/_bulk/alerts/attributes?environment=Production \
-H 'Authorization: Key demo-key' \
-H 'Content-type: application/json' \
-d '{
      "attributes": {
        "reviewed": true,
        "owner": "ops-team"
      }
    }'

Bulk delete alerts

Permanently deletes multiple alerts selected by query parameters. It cannot be undone.

DELETE /_bulk/alerts

Example Request

$ curl -XDELETE http://localhost:8080/_bulk/alerts?environment=Production&status=closed \
-H 'Authorization: Key demo-key'

Management

Manifest

Get build info, including build date, release number and git commit sha.

GET /management/manifest

Example Request

$ curl http://localhost:8080/management/manifest \
-H 'Authorization: Key demo-key'

Example Response

200 OK

{
  "build": "PROD",
  "date": "2021-11-22T23:46:52Z",
  "release": "8.6.2",
  "revision": "ecfe6ff2295ddc1a01be5aaeeef7dd9159fdfcf9"
}

Properties

Get HTTP request variables, environment variables, and application configuration settings for debug purposes.

GET /management/properties

Example Request

$ curl http://localhost:8080/management/properties \
-H 'Authorization: Key demo-key'

Example Response

200 OK

wsgi.version: (1, 0)
wsgi.url_scheme: http
wsgi.input: <_io.BufferedReader name=10>
wsgi.errors: <_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>
wsgi.multithread: True
wsgi.multiprocess: False
wsgi.run_once: False
werkzeug.server.shutdown: <function WSGIRequestHandler.make_environ.<locals>.shutdown_server at 0x11232a430>
werkzeug.socket: <socket.socket fd=10, family=AddressFamily.AF_INET, type=SocketKind.SOCK_STREAM, proto=0, laddr=('127.0.0.1', 8080), raddr=('127.0.0.1', 51203)>
SERVER_SOFTWARE: Werkzeug/2.0.2
REQUEST_METHOD: GET
SCRIPT_NAME:
PATH_INFO: /management/properties

“Good-to-go” Healthcheck

The “good-to-go” healthcheck checks the database is alive and returns HTTP status codes 200 or 503.

GET /management/gtg

Note

This healthcheck can be used as a READINESS check because it shows the container is ready to start accepting traffic.

Example Request

$ curl http://localhost:8080/management/gtg

Example Response

200 OK

OK

“Light” Healthcheck

The “underscore” healthcheck simply returns HTTP status code 200 OK if the application is up. It does not query the database.

GET /_

Note

This healthcheck can be used as a LIVENESS check because it simply shows the container is running.

Example Request

$ curl -XGET http://localhost:8080/_

Example Response

200 OK

OK

“Deep” Healthcheck

This healthcheck checks that all reported heartbeats are not more than 4 times their timeout value and reports HTTP status codes 200 or 503. It implicitly checks the database is up also.

GET /management/healthcheck

Example Request

$ curl -XGET http://localhost:8080/management/healthcheck

Example Response

200 OK

OK

JSON Metrics

Get application metrics in JSON format.

GET /management/status

Example Request

$ curl -XGET http://localhost:8080/management/status \
-H 'Authorization: Key demo-key'

Example Response

200 OK

{
    "application": "alerta",
    "metrics": [
        {
            "description": "Total number of alerts in the database",
            "group": "alerts",
            "name": "total",
            "title": "Total alerts",
            "type": "gauge",
            "value": 0
        },
        {
            "count": 12,
            "description": "Total time and number of alert queries",
            "group": "alerts",
            "name": "queries",
            "title": "Alert queries",
            "totalTime": 1210,
            "type": "timer"
        }
    ],
    "time": 1637794336233,
    "uptime": 1321373,
    "version": "8.6.2"
}

Prometheus Metrics

Get application metrics in prometheus format.

GET /management/metrics

Example Request

$ curl -XGET http://localhost:8080/management/metrics \
-H 'Authorization: Key demo-key'

Example Response

200 OK

# HELP alerta_alerts_total Total number of alerts in the database
# TYPE alerta_alerts_total gauge
alerta_alerts_total 0
# HELP alerta_alerts_queries Total time and number of alert queries
# TYPE alerta_alerts_queries summary
alerta_alerts_queries_count 12
alerta_alerts_queries_sum 1210
# HELP alerta_alerts_counts Total time and number of count queries
# TYPE alerta_alerts_counts summary
alerta_alerts_counts_count 2
alerta_alerts_counts_sum 73
# HELP alerta_uptime_msecs milliseconds since app has started
# TYPE alerta_uptime_msecs counter
alerta_uptime_msecs 1422377

Housekeeping

Triggers housekeeping to expire timed-out alerts and delete old closed/expired alerts.

GET /management/housekeeping

Example Request

$ curl http://localhost:8080/management/housekeeping \
-H 'Authorization: Key demo-key'

Switchboard

Get or set feature switches used to toggle runtime features.

GET /management/switchboard

Example Request

$ curl http://localhost:8080/management/switchboard \
-H 'Authorization: Key demo-key'

Client Configuration

Get client configuration settings used by the web UI.

GET /config

Example Request

$ curl http://localhost:8080/config