---
url: /api/docs/notifications.md
---
# Notifications

Access the notifications produced by the BGP monitoring, and all the services offered by PacketVis through a single API.

## Getting started

1. [Generate an API key](https://packetvis.com/settings/apikeys) (see [Authentication](/docs/authentication)).
2. Build the request URL. Replace `YOUR_API_KEY` in the examples with your API key.

## List notifications

Returns the notifications produced by the BGP monitoring and by the other PacketVis services, with optional filters.

### Parameters

| Name | Description | Default |
|------|-------------|---------|
| `key` | The API key. |  |
| `services` | A comma-separated list of service names you want to receive notifications from. See [services and types](#services-and-types). This parameter is optional. | All of them |
| `types` | A comma-separated list of notification types to retrieve (e.g., `hijack` events). See [services and types](#services-and-types). This parameter is optional. | All of them |
| `severity` | The minimum severity of the notifications to retrieve: `1` min, `2` med, `3` high, `4` critical. This parameter is optional. | `1` |
| `warning` | The amount of minutes (between 1 and 120) the warning remains active after a notification. The warning parameter allows you to integrate this API endpoint directly with third-party alerting systems. This parameter is optional. | `10` |
| `status` | Return HTTP `418` if there is a warning ongoing. The usual payload is sent as well. This is the same as the warning parameter, which allows you to integrate this API endpoint directly with third-party alerting systems. In this case, no JSON body parsing is required and you can use normal HTTP checks (e.g., in nagios or checkmk). This parameter is optional. | `false` |
| `start` | A UNIX timestamp (seconds) used as start time to filter the notifications. Optional, but if used `stop` must be declared as well. |  |
| `stop` | A UNIX timestamp (seconds) used as stop time to filter the notifications. It must be in the past. Optional, but if used `start` must be declared as well. |  |

### Response

200 OK

```json
{
  "data": {
    "notifications": [
      {
        "service": "bgp",
        "type": "rpki-invalid",
        "summary": "The route XXXX announced by ASXXX is not RPKI valid.",
        "url": "https://packetvis.com/bgp/event/23ff",
        "id": "23ff",
        "dispatched": true,
        "createdAt": "2022-09-07T05:33:41.981Z",
        "severity": 4,
        "resolved": null
      }
    ],
    "warning": false
  },
  "metadata": {
    "useStatusCode": false,
    "warningMinutes": 10
  }
}
```

Fields of each object in `data.notifications`:

| Field | Type | Description |
|-------|------|-------------|
| `service` | string | The service that produced the notification. See [services and types](#services-and-types). |
| `type` | string | The notification type. See [services and types](#services-and-types). |
| `summary` | string | A short description of the event. |
| `url` | string | Link to the event on packetvis.com. |
| `id` | string | integer | The unique identifier of the notification. |
| `dispatched` | boolean | Whether the notification was dispatched to your configured channels. |
| `createdAt` | string (ISO 8601) | When the notification was created. |
| `severity` | integer | `1` min, `2` med, `3` high, `4` critical. |
| `resolved` | string (ISO 8601) | null | When the event that triggered the notification was resolved. `null` means the event is not resolved or has no possible resolution (purely informative). |

Other fields:

| Field | Type | Description |
|-------|------|-------------|
| `data.warning` | boolean | `true` if there was an unresolved notification within the warning window. See [warning and status codes](#warning-and-status-codes). |
| `metadata.useStatusCode` | boolean | Whether the `status` parameter was set. |
| `metadata.warningMinutes` | integer | The warning window, in minutes. |

## Services and types

| Service | Types |
|---------|-------|
| `generic` | `setup`, `test`, `admin`, `resolution` |
| `bgp` | `hijack`, `visibility`, `misconfiguration`, `bogons`, `path`, `newprefix`, `neighbors`, `rpki-invalid`, `rpki-unknown`, `ta-expire`, `ta-malfunction`, `roa-diff`, `roa-expire`, `upstreams-visibility`, `upstreams-availability`, `grouped` |

## Warning and status codes

The `warning` parameter controls how long a notification keeps the warning active. For example, with `warning=30` the returned JSON contains `"warning": true` if there was an unresolved notification in the last 30 minutes.

This makes integration with systems such as Icinga or Nagios easy: poll the API and look for `warning: true`, without parsing the notifications.

To avoid parsing the JSON entirely, set `status=true`. In addition to `warning: true`, the API returns an HTTP `418` status code, so your monitoring solution marks the HTTP call as failing automatically. The payload remains intact for inspection.