PagerDuty has a few different APIs, including the Events API 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.
The 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. Events API calls do not count against the number of REST API requests included with your plan.
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:
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, however it cannot be used to create new incidents. PagerDuty incidents can only be created via triggers sent to the Events API (for API-based services), via email (for email-based services), or manually via the Create New Incident button in the web interface (for any service type).
There are two versions of the REST API, the current API v2, as well as 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. Also note that the number of REST API requests you can make each month may be limited by your pricing plan.
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, however 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.
Here are some other examples of what you would use each API for and what others have built:
More resources can be found on the PagerDuty Developer Hub.