Events and REST APIs

PagerDuty APIs: Events API and REST API

PagerDuty has a few different APIs, including the Events API v1, Events API v2 and REST API, as well as an older version of the REST API. These APIs serve different purposes and have different plan availability, endpoints, and API keys.

Events API

Events API v1

The v1 Events API — formerly known as the Integration API or Generic Service API — is used to integrate your monitoring systems and other tools you want to be able to trigger, acknowledge, and resolve incidents in PagerDuty. This API is available to all customers at a common endpoint on events.pagerduty.com, and uses integration keys to determine which service an event should be routed to.

The Events API cannot be used for any purpose other than triggering, acknowledging, or resolving PagerDuty incidents. It uses 32-character integration keys that cannot be used with the REST API, so it is safe to store these API keys in monitoring systems and other tools without fear that they can be used to gain access to sensitive data in your account.

Integration keys are generated by creating a new service, or creating a new integration for an existing service in PagerDuty, and can be found on a service's Integrations tab:

Events API v2

With the Events API v2, monitoring partners and customers running their own custom monitoring code can send to this endpoint, enabling users to see and use PD-CEF fields, and the details section on individual alerts.

You must have Create alerts and incidents enabled to use our Events API v2, as this API can only be applied to alerts. Like our v1 Events API, integrations with the v2 Events API also use integration keys.

Our develops docs For more information about the v2 Events API take a look at our dev docs on the subject.

Which version of the Events API should I use?

Both versions of the Events API are designed to handle machine-generated monitoring and event data, such as infrastructure monitoring (Nagios, SignalFX, Datadog), application performance monitoring (New Relic, AppDynamics), and external site checks (Pingdom, Wormly).

However, v2 of the Events API provides a direct interface to set PD-CEF fields in the PagerDuty alerts. This makes it easier to generate rich alert data in PagerDuty for better classification, filtering and operational intelligence.

Hence, if you are creating a new or custom integration, we strongly recommend using the Events API v2. If you are using a custom monitoring tool, library, or script that has not yet been updated to v2, you can still use the Events API v1. There are no plans as of 2017 to deprecate the Events API v1 in the foreseeable future.

REST API

The REST API is used to create, read, update, and delete services, schedules, escalation policies, and users — including their contact methods and notification rules. This API can also be used to GET a list of incidents, GET specific details for a single incident, or add notes to an incident.

There are two versions of the REST API, the current API v2 and the older API v1. Both versions are available to customers on Basic or higher plans and use different endpoints: API v2 uses a generic endpoint (api.pagerduty.com), while API v1 uses the account's subdomain (i.e. your-company.pagerduty.com).

REST API keys are 20-character strings and cannot be used with the Events API. Only Admin users or the Account Owner can create REST API keys due to the fact they they provide full access to your account; this means API keys should be protected like your login password.

REST API keys are created and managed in the web UI under Configuration → API Access.

Creating incidents

We've expanded the scope of our v2 REST API to include incident creation capabilities. For more granular information about this, please reference our developer documentation. Please note: the REST API should not be used to create incidents originating from monitoring systems or other automated tools - for that, use the Events API instead. The incident creation API is designed to accommodate human-generated input.

Which version of the REST API should I use?

We recommend using API v2 when creating or updating your scripts and tools, as it supports new features, offers better performance, and has been simplified so that less work is required to get the information you want (i.e. there is now a single on-calls endpoint).

API v1 is also supported, so you will be able to continue using scripts or tools built for v1, but any new features added to PagerDuty will not be added to API v1. For example, you cannot add or remove multiple integrations to a service in API v1. If you would like to upgrade a script or tool you use from API v1 to API v2, our API v2 migration guide outlines some of the changes and improvements we've made.

Examples

Here are some other examples of what you would use each API for and what others have built:

Events API

REST API

More resources can be found on the PagerDuty Dev Platform.

Events and REST APIs