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:
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.
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.
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
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
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.
Example projects and more resources can be found in our Developer Documentation.