Creating incidents using our REST API

rest-api
howto
official

(Istvan Nagy) #1

When an event from a monitoring system is accepted by the PagerDuty events API, it goes through multiple stages and processing steps before it creates an incident.

The relationship between an event and an incident is not direct. Some events might get deduplicated to an existing incident, some events might get suppressed, or email events filtered. Some events might create alerts that are part of an existing incident (see alert triage, for more information). In case a service is in maintenance mode, the event might get ignored.

Therefore, the client sending an event may not know which incident(s) will be created in correlation with the event, if any.

There are some cases, when we just want to create an incident manually because we know that something is broken. We can do that using the create incident button using the website, but we can also do that using our REST API.

In order to create an incident, we just have to send a simple HTTP request (a POST to https://api.pagerduty.com/incidents) with a few parameters describing the incident.

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/vnd.pagerduty+json;version=2' --header 'From: <your email address>' --header 'Authorization: Token token=<your API token>' -d '{
  "incident": {
    "type": "incident",
    "title": "<title of the incident to be created>",
    "service": {
      "id": "<service ID to create the incident on>",
      "type": "service_reference"
    }
  }
}
' 'https://api.pagerduty.com/incidents'

The HTTP response body will contain both the incident’s ID and number, which we can use to manipulate the incident later if needed. Note that the response is a fully-formed incident object including every top level attribute, but some of them have been omitted for clarity in the example below.

The response will look similar to this:

{
  "incident": {
    "incident_number": 4887,
    "title": "<title of the incident to be created>",
    "created_at": "2017-06-19T17:56:06Z",
    "status": "triggered",
    "id": "PNRH2Q5",
    "type": "incident",
    "self": "https://api.pagerduty.com/incidents/PNRH2Q5",
 
    ... other incident attributes ...
 
  }
}

Some examples when the API call is useful:

  • create an incident when a monitoring system is not able to, e.g. a major incident
  • synchronize an existing incident that is present in another system (PagerDuty can do this automatically with ServiceNow, for example)
  • page a user or a team directly, as the incident can be directly assigned to a user or an escalation policy

For further details, please take a look at our incident create API documentation and our API reference.

We are interested to hear about your use cases or any feedback around using this API.

Note: if you are to connect a monitoring system to PagerDuty, use our Events API instead.


(system) #2