APIs Overview

PagerDuty has a few different APIs, like our Events APIs, REST API, and webhooks. These APIs serve different purposes and have different plan availability, endpoints, and methods of authorization.

Events APIs

Events API v1

Events API v1 — 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 — formerly known as service keys — to determine which service an event should be routed to.

The Events APIs 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 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 alerts and incidents enabled to use Events API v2, as this API can only be applied to alerts. Like Events API v1, integrations using Events API v2 also use integration keys.

Complete documentation for Events API v2 can be found in the PagerDuty Developer portal.

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, Events API v2 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.

Events API Examples

REST API

The REST API is used to create, read, update, and delete services, integrations, schedules, escalation policies, and users — including their contact methods and notification rules. This API can also be used to create, read, and update incidents, and create and read notes for an incident.

The REST API is available to all customers on current pricing plans. It is not available to some customers on legacy pricing plans.

There are two types of REST API keys, general access and user tokens, both of which are 20-character strings. REST API keys cannot be used with the Events APIs, they can only be used for the REST API at api.pagerduty.com.

General access keys are available to all accounts with REST API access, but can only be created by Admin users or the Account Owner due to the fact they they provide full access to your account. This means general access API keys should be protected like an admin login password.

If your account has the Advanced Permissions ability, individual non-admin users can also create their own REST API keys. These keys will have the same permissions as the user, and if a client attempts to use the key for an operation that the user in question is not permitted to perform, the API will respond with status 403 Forbidden.

General access REST API keys are created and managed in the web UI under Configuration → API Access. User REST API keys are created and managed in the web UI under My Profile → User Settings.

Creating incidents

We've expanded the scope of REST API v2 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 APIs instead. The incident creation endpoint in our REST API is designed to accommodate human-generated input.

REST API Examples

More resources can be found in our Developer Documentation.