
= Alarms

NOTE: the default offset is 0, the default limit is 10 results. To get all results, use `limit=0` as a parameter on the URL (ie, `GET /events?limit=0`).

== GETs (reading data)

[caption=]
.Alarms API GET functions
[options="autowidth"]
|===
| Resource  | Description

| /alarms
| Get a list of alarms.

| /alarms/count
| Get the number of alarms (returns plaintext, rather than XML or JSON).

| /alarms/\{id}
| Get the alarms specified by the given ID.
|===

Note that you can also query by severity:

[options="autowidth"]
|===
| Resource  | Description

| /alarms?comparator=ge&amp;severity=MINOR
| Get the alarms with a severity greater than or equal to `MINOR`.
|===

== PUTs (modifying data)

PUT requires form data using `application/x-www-form-urlencoded` as a `Content-Type`.

[caption=]
.Alarms API PUT functions
[cols="1,3"]
|===
| Resource  | Description

| /alarms/\{id}?ack=''(true;false)''
| Acknowledges (or unacknowledges) an alarm.

| /alarms?x=y&...&ack=''(true;false)''
| Acknowledges (or unacknowledges) alarms matching the additional query parameters (for example, `/alarms?node.id=4&ack=true`).

| /alarms/\{id}?clear=true
| Clears an alarm.

| /alarms/\{id}?escalate=true
| Escalates an alarm (for example, NORMAL -> MINOR, MAJOR -> CRITICAL).

| /alarms?x=y&...&clear=true
| Clears alarms matching the additional query parameters.

| /alarms?x=y&...&escalate=true
| Escalates alarms matching the additional query parameters.
|===

Additionally, when acknowledging alarms (`ack=true`) you can specify an `ackUser` parameter.
You will only be allowed to `ack` as a different user if you are PUTting as an authenticated user who is in the admin role.

== v2 API

Since Horizon 20.1.0, an alarms endpoint has been available in the v2 API that uses link:https://github.com/jirutka/rsql-parser#rsql--fiql-parser[FIQL] for querying.

Examples:

* `/api/v2/alarms?_s=alarm.reductionKey==uei.opennms.org/nodes/nodeDown::*`
* `/api/v2/alarms?_s=alarm.uei==uei.opennms.org/nodes/nodeDown`
* `/api/v2/alarms?_s=alarm.ipAddr==127.0.0.1`
* `/api/v2/alarms?_s=node.label==localhost`

NOTE: If your query string includes a FIQL reserved character like a comma (,) or a semicolon (;) you need to double percent-escape it.

Suppose you have a service with a comma in the name, like `COMMA,SERVICE` and you want to retrieve all the alarms for its failure.
Your query would look like `/api/v2/alarms?_s=alarm.reductionKey==uei.opennms.org/nodes/nodeLostService::*:COMMA%252CSERVICE`.
