PagerDuty APIs: Events API and REST API

Follow

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 created 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:

integration_keys.png

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 in Event Rules, the Infrastructure Health Application, 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.

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?

The Events API v2 is 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). PD-CEF events generate alerts in PagerDuty, which can then be grouped together into Incidents within PagerDuty.

For human-generated events, mysteries, or incidents, such as those from ServiceNow or JIRA, we suggest using the Events API v2, which enables direct, streamlined creation of PagerDuty incidents.

If you are using a custom monitoring tool, library, or script that has not yet been updated to V2, you should use the Events API v1.

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 on the API Access page, found in the Configuration menu.

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 Developer Hub.

Have more questions? Submit a request

Comments