{"_id":"58e282276194cf3b00f301ae","version":{"_id":"564e5a9b1560880d008d30dc","project":"564e5930c3553e0d003e53d0","__v":22,"createdAt":"2015-11-19T23:26:19.166Z","releaseDate":"2015-11-19T23:26:19.166Z","categories":["564e5a9b1560880d008d30dd","566318e1f5ca460d00f41896","56631d08cd54d50d005015fa","56631d2a81ad7417006a202c","5668ba19fbd7680d009375f4","5668cb8b10bda80d00797ed9","5668cb9d10bda80d00797eda","56830d8a3f94e00d004e2a7a","56830d9072bb720d0091f594","56830d94cb4d190d0027698e","56830dc44aecbd0d00a464c5","569e90f3c9b43e0d00c4bab1","56a96d338791090d00113bab","56b12d8336d2580d00247877","56c36bf0a869d017002ea55b","56c36bf93d30210d00ea84bb","56c77749b935671700ff0304","56c7ab9e5652c217008e091a","56cb8bdad5c6241d00ef5e61","58aefce02470660f00b54539","58aefd0bebd7370f0078b954","59ca65ca4337830026edf24f"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"Foundation","version_clean":"2.0.0","version":"2"},"category":{"_id":"56a96d338791090d00113bab","__v":13,"pages":["56a96d492bb3910d000ee931","56c3cec2106c12170020db96","56c51da4ba4a540d0091b9b7","56c51dc3ba4a540d0091b9b9","56c51eb916c7190d00ff7b19","56c51ec2d7b9ed19008d1752","56c51eec668eb01900719bcd","56c51effba4a540d0091b9bb","56c51f1cf7c4da0d00614b02","56c51f2a8dc1c51900abc142","56c51f367de3580d00bdaf2a","56c67b6270e7660d004a8985","56c67b7cfd00bb0d0016daad"],"project":"564e5930c3553e0d003e53d0","version":"564e5a9b1560880d008d30dc","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-01-28T01:21:55.716Z","from_sync":false,"order":1,"slug":"patterns","title":"REST API v2"},"project":"564e5930c3553e0d003e53d0","user":"581bb9e88dc56225009fca3c","__v":0,"githubsync":"","parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-04-03T17:11:03.752Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":16,"body":"The PagerDuty Incident Creation API endpoint is provided by our [Overview](doc:rest-api)  and is usable by third parties. With this API, one can connect to a PagerDuty account and create or edit incidents on that account. This API is not to be used for connecting your monitoring tools to send events to PagerDuty; for that, use the [Events API Reference](doc:events-api-reference) \n[block:api-header]\n{\n  \"title\": \"What and Where\"\n}\n[/block]\nThis API is designed around RESTful principles and conforms to the conventions of our other [RESTful API endpoints](doc:endpoints).\n\nUnlike the Events API, the Incident Creation API is **heavily rate limited** on a per-account basis. It’s meant for the creation of events at “human speed” - in response to user action, rather than automated tooling. \n\nThis API is also **synchronous**, as it returns a fully-formed Incident object (rather than the incident key returned by the asynchronous Events API). The Events API accepts arbitrary JSON objects, while the Incident creation API currently **only supports string Incident bodies**.\n\nThe Incident Creation API is analogous to clicking on the “Create Incident” button in PagerDuty’s web or mobile interfaces. It captures incident information from users and uses that to create a new incident, regardless of monitoring tool data.\n\nThe Incident Creation API can be used to create incidents on a service. In order to create an incident the user must pass a **type** (“incident”), **title**, and the affected **service**. Some request headers must also be specified with the request:\n\n  * **Authorization**: All PagerDuty REST APIs require [Authentication](doc:authentication). In order to make successful requests to the API, you must provide a valid form of authorization.\n  * **Content-Type:** `application/json`\n  * **Accept**: `application/vnd.pagerduty+json;version=2`\n  * **From**: The email address of a valid PagerDuty user on the account associated with the auth token.\n\n[block:api-header]\n{\n  \"title\": \"Making a Request\"\n}\n[/block]\nIncidents created with the Incident Creation API can be updated with the existing [Incidents API update calls.](https://v2.developer.pagerduty.com/v2/page/api-reference#!/Incidents/post_incidents)\n\nThe Incident Creation API also accepts other optional parameters:\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"Body\",\n    \"h-0\": \"Name\",\n    \"h-2\": \"To Note:\",\n    \"0-1\": \"Provides a detailed description of the incident, in addition to the summary provided in the title.\",\n    \"1-0\": \"Incident Key\",\n    \"1-1\": \"Similar to PagerDuty’s Events API, the Incident Creation API allows you to pass a unique incident key to identify the incident.\",\n    \"2-0\": \"Assignee\",\n    \"3-0\": \"Escalation Policy\",\n    \"2-1\": \"A list of users to assign to the incident. Cannot be provided if escalation_policy is already specified. Only 1 assignee is supported at this time.\",\n    \"3-1\": \"Assign the incident to an escalation policy instead of assigning directly to a user. Cannot be provided if assignments are already specified.\",\n    \"h-1\": \"Description\",\n    \"3-2\": \"When included, the escalation policy defined will override the escalation policy defined on the service.\",\n    \"2-2\": \"When a user creates an incident assigned to themselves, the incident will be created in the ‘Acknowledged’ state and will not notify the user.\\n\\nIf an incident is created without an assigned user or escalation policy, the default escalation policy for the service will be used.\",\n    \"1-2\": \"If an incident exists on the provided service with the same incident key, a subsequent Incident Create request will be denied with a `400 Bad Request`.\",\n    \"0-2\": \"Details defined here will be included in the details of the web ui.\"\n  },\n  \"cols\": 3,\n  \"rows\": 4\n}\n[/block]\n##  Example Requests: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"incident\\\": {\\n    \\\"type\\\": \\\"incident\\\",\\n    \\\"title\\\": \\\"The server is on fire.\\\",\\n    \\\"service\\\": {\\n      \\\"id\\\": \\\"PWIXJZS\\\",\\n      \\\"type\\\": \\\"service_reference\\\"\\n    }\\n  }\\n}\\n\",\n      \"language\": \"json\",\n      \"name\": \"Simple Request\"\n    },\n    {\n      \"code\": \"{\\n  \\\"incident\\\": {\\n    \\\"type\\\": \\\"incident\\\",\\n    \\\"title\\\": \\\"Disk usage at 85%\\\",\\n    \\\"service\\\": {\\n      \\\"id\\\": \\\"PWIXJZS\\\",\\n      \\\"type\\\": \\\"service_reference\\\"\\n    },\\n    \\\"body\\\": {\\n      \\\"type\\\": \\\"incident_body\\\",\\n\\\"details\\\": \\\"A disk is getting full on this machine. You should investigate what is causing the disk to fill, and ensure that there is an automated process in place for ensuring data is rotated (eg. logs should have logrotate around them). If data is expected to stay on this disk forever, you should start planning to scale up to a larger disk.\\\"\\n    }\\n  }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Body Details\"\n    },\n    {\n      \"code\": \"{\\n  \\\"incident\\\": {\\n    \\\"type\\\": \\\"incident\\\",\\n    \\\"title\\\": \\\"The server is on fire.\\\",\\n    \\\"service\\\": {\\n      \\\"id\\\": \\\"PWIXJZS\\\",\\n      \\\"type\\\": \\\"service_reference\\\"\\n    },\\n    \\\"incident_key\\\": \\\"baf7cf21b1da41b4b0221008339ff357\\\"\\n  }\\n}\\n\",\n      \"language\": \"json\",\n      \"name\": \"Incident Key Details\"\n    },\n    {\n      \"code\": \"{\\n  \\\"incident\\\": {\\n    \\\"title\\\": \\\"it's Friday :)\\\",\\n    \\\"service\\\": {\\n      \\\"id\\\": \\\"PW7YESS\\\",\\n      \\\"type\\\": \\\"service_reference\\\"\\n    },\\n    \\\"assignments\\\": [{\\n      \\\"assignee\\\" : {\\n    \\t  \\\"id\\\": \\\"PZUVZZZ\\\",\\n    \\t  \\\"type\\\": \\\"user_reference\\\"\\n      }\\n    }]\\n  }\\n}\\n\",\n      \"language\": \"json\",\n      \"name\": \"Assignee Details\"\n    },\n    {\n      \"code\": \"{\\n  \\\"incident\\\": {\\n    \\\"type\\\": \\\"incident\\\",\\n    \\\"title\\\": \\\"The server is on fire.\\\",\\n    \\\"service\\\": {\\n      \\\"id\\\": \\\"PWIXJZS\\\",\\n      \\\"type\\\": \\\"service_reference\\\"\\n    },\\n    \\\"escalation_policy\\\": {\\n      \\\"id\\\": \\\"PT20YPA\\\",\\n      \\\"type\\\": \\\"escalation_policy_reference\\\"\\n    }\\n  }\\n}\\n\",\n      \"language\": \"json\",\n      \"name\": \"Escalation Policy Details\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"Data accepted by the incident creation api and the events API is different.The Events API accepts arbitrary JSON objects, while the Incident creation API currently only supports string Incident bodies. For added customization of these fields, refer to the [v1](doc:trigger-events) or [v2](doc:events-api-v2) Events API.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Use Case Examples\"\n}\n[/block]\nPaging a User Directly: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"incident\\\": {\\n    \\\"title\\\": \\\"Your desk is on fire!\\\",\\n    \\\"service\\\": {\\n      \\\"id\\\": \\\"PW7YESS\\\",\\n      \\\"type\\\": \\\"service_reference\\\"\\n    },\\n    \\\"assignments\\\": [{\\n      \\\"assignee\\\" : {\\n    \\t  \\\"id\\\": \\\"PZUVZZZ\\\",\\n    \\t  \\\"type\\\": \\\"user_reference\\\"\\n      }\\n    }]\\n  }\\n}\\n\",\n      \"language\": \"json\",\n      \"name\": \"Page a user\"\n    }\n  ]\n}\n[/block]\nPaging a team directly via an Escalation Policy:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"incident\\\": {\\n    \\\"type\\\": \\\"incident\\\",\\n    \\\"title\\\": \\\"The server is on fire.\\\",\\n    \\\"service\\\": {\\n      \\\"id\\\": \\\"PWIXJZS\\\",\\n      \\\"type\\\": \\\"service_reference\\\"\\n    },\\n    \\\"escalation_policy\\\": {\\n      \\\"id\\\": \\\"PT20YPA\\\",\\n      \\\"type\\\": \\\"escalation_policy_reference\\\"\\n    }\\n  }\\n}\\n\",\n      \"language\": \"json\",\n      \"name\": \"Page team via Escaltion Policy\"\n    }\n  ]\n}\n[/block]","excerpt":"Create incidents using the REST API","slug":"incident-creation-api","type":"basic","title":"Incident Creation API"}

Incident Creation API

Create incidents using the REST API

The PagerDuty Incident Creation API endpoint is provided by our [Overview](doc:rest-api) and is usable by third parties. With this API, one can connect to a PagerDuty account and create or edit incidents on that account. This API is not to be used for connecting your monitoring tools to send events to PagerDuty; for that, use the [Events API Reference](doc:events-api-reference) [block:api-header] { "title": "What and Where" } [/block] This API is designed around RESTful principles and conforms to the conventions of our other [RESTful API endpoints](doc:endpoints). Unlike the Events API, the Incident Creation API is **heavily rate limited** on a per-account basis. It’s meant for the creation of events at “human speed” - in response to user action, rather than automated tooling. This API is also **synchronous**, as it returns a fully-formed Incident object (rather than the incident key returned by the asynchronous Events API). The Events API accepts arbitrary JSON objects, while the Incident creation API currently **only supports string Incident bodies**. The Incident Creation API is analogous to clicking on the “Create Incident” button in PagerDuty’s web or mobile interfaces. It captures incident information from users and uses that to create a new incident, regardless of monitoring tool data. The Incident Creation API can be used to create incidents on a service. In order to create an incident the user must pass a **type** (“incident”), **title**, and the affected **service**. Some request headers must also be specified with the request: * **Authorization**: All PagerDuty REST APIs require [Authentication](doc:authentication). In order to make successful requests to the API, you must provide a valid form of authorization. * **Content-Type:** `application/json` * **Accept**: `application/vnd.pagerduty+json;version=2` * **From**: The email address of a valid PagerDuty user on the account associated with the auth token. [block:api-header] { "title": "Making a Request" } [/block] Incidents created with the Incident Creation API can be updated with the existing [Incidents API update calls.](https://v2.developer.pagerduty.com/v2/page/api-reference#!/Incidents/post_incidents) The Incident Creation API also accepts other optional parameters: [block:parameters] { "data": { "0-0": "Body", "h-0": "Name", "h-2": "To Note:", "0-1": "Provides a detailed description of the incident, in addition to the summary provided in the title.", "1-0": "Incident Key", "1-1": "Similar to PagerDuty’s Events API, the Incident Creation API allows you to pass a unique incident key to identify the incident.", "2-0": "Assignee", "3-0": "Escalation Policy", "2-1": "A list of users to assign to the incident. Cannot be provided if escalation_policy is already specified. Only 1 assignee is supported at this time.", "3-1": "Assign the incident to an escalation policy instead of assigning directly to a user. Cannot be provided if assignments are already specified.", "h-1": "Description", "3-2": "When included, the escalation policy defined will override the escalation policy defined on the service.", "2-2": "When a user creates an incident assigned to themselves, the incident will be created in the ‘Acknowledged’ state and will not notify the user.\n\nIf an incident is created without an assigned user or escalation policy, the default escalation policy for the service will be used.", "1-2": "If an incident exists on the provided service with the same incident key, a subsequent Incident Create request will be denied with a `400 Bad Request`.", "0-2": "Details defined here will be included in the details of the web ui." }, "cols": 3, "rows": 4 } [/block] ## Example Requests: [block:code] { "codes": [ { "code": "{\n \"incident\": {\n \"type\": \"incident\",\n \"title\": \"The server is on fire.\",\n \"service\": {\n \"id\": \"PWIXJZS\",\n \"type\": \"service_reference\"\n }\n }\n}\n", "language": "json", "name": "Simple Request" }, { "code": "{\n \"incident\": {\n \"type\": \"incident\",\n \"title\": \"Disk usage at 85%\",\n \"service\": {\n \"id\": \"PWIXJZS\",\n \"type\": \"service_reference\"\n },\n \"body\": {\n \"type\": \"incident_body\",\n\"details\": \"A disk is getting full on this machine. You should investigate what is causing the disk to fill, and ensure that there is an automated process in place for ensuring data is rotated (eg. logs should have logrotate around them). If data is expected to stay on this disk forever, you should start planning to scale up to a larger disk.\"\n }\n }\n}", "language": "json", "name": "Body Details" }, { "code": "{\n \"incident\": {\n \"type\": \"incident\",\n \"title\": \"The server is on fire.\",\n \"service\": {\n \"id\": \"PWIXJZS\",\n \"type\": \"service_reference\"\n },\n \"incident_key\": \"baf7cf21b1da41b4b0221008339ff357\"\n }\n}\n", "language": "json", "name": "Incident Key Details" }, { "code": "{\n \"incident\": {\n \"title\": \"it's Friday :)\",\n \"service\": {\n \"id\": \"PW7YESS\",\n \"type\": \"service_reference\"\n },\n \"assignments\": [{\n \"assignee\" : {\n \t \"id\": \"PZUVZZZ\",\n \t \"type\": \"user_reference\"\n }\n }]\n }\n}\n", "language": "json", "name": "Assignee Details" }, { "code": "{\n \"incident\": {\n \"type\": \"incident\",\n \"title\": \"The server is on fire.\",\n \"service\": {\n \"id\": \"PWIXJZS\",\n \"type\": \"service_reference\"\n },\n \"escalation_policy\": {\n \"id\": \"PT20YPA\",\n \"type\": \"escalation_policy_reference\"\n }\n }\n}\n", "language": "json", "name": "Escalation Policy Details" } ] } [/block] [block:callout] { "type": "warning", "body": "Data accepted by the incident creation api and the events API is different.The Events API accepts arbitrary JSON objects, while the Incident creation API currently only supports string Incident bodies. For added customization of these fields, refer to the [v1](doc:trigger-events) or [v2](doc:events-api-v2) Events API." } [/block] [block:api-header] { "title": "Use Case Examples" } [/block] Paging a User Directly: [block:code] { "codes": [ { "code": "{\n \"incident\": {\n \"title\": \"Your desk is on fire!\",\n \"service\": {\n \"id\": \"PW7YESS\",\n \"type\": \"service_reference\"\n },\n \"assignments\": [{\n \"assignee\" : {\n \t \"id\": \"PZUVZZZ\",\n \t \"type\": \"user_reference\"\n }\n }]\n }\n}\n", "language": "json", "name": "Page a user" } ] } [/block] Paging a team directly via an Escalation Policy: [block:code] { "codes": [ { "code": "{\n \"incident\": {\n \"type\": \"incident\",\n \"title\": \"The server is on fire.\",\n \"service\": {\n \"id\": \"PWIXJZS\",\n \"type\": \"service_reference\"\n },\n \"escalation_policy\": {\n \"id\": \"PT20YPA\",\n \"type\": \"escalation_policy_reference\"\n }\n }\n}\n", "language": "json", "name": "Page team via Escaltion Policy" } ] } [/block]