{"_id":"56c51f367de3580d00bdaf2a","githubsync":"","project":"564e5930c3553e0d003e53d0","user":"564e5788230d7c1700c9073e","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":2,"slug":"patterns","title":"REST API"},"version":{"_id":"564e5a9b1560880d008d30dc","project":"564e5930c3553e0d003e53d0","__v":26,"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","5c33cd9eb47ba20051ac8d64","5c33df728bec1d0063431c34","5c4783ef523219027055513a","5c4f35033400f3010203a999"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"Foundation","version_clean":"2.0.0","version":"2"},"__v":2,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-02-18T01:32:38.105Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":12,"body":"Depending on your client's needs, you may want to have all of a resource's information available in the response of a related resource. Instead of just receiving the [reference](doc:references) (an abbreviated form of the related resource), including a type of resource will make all resources of that type contain their [full set of fields](#section-resource-schema-and-types) in the response.\n\nIncludes are specified with the `include[]` parameter. The values allowed in an `include[]` parameter vary from endpoint to endpoint, but will always be the pluralized type of a resource or the pluralized name of a resource field representing the relationship between resources.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Example\"\n}\n[/block]\nIn the below example, the `/incidents` API is accessed with and without including `services`.\nNote how including `services` causes a full `Service` [schema](doc:resource-schemas) (with type `service`) to be displayed in the `service` field of the incident, while without the `include[]` the `service` field contains a `ServiceReference` [schema](doc:resource-schemas)) (with type `service_reference`).\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# https://api.pagerduty.com/incidents\\n\\n{\\n  \\\"incidents\\\": [\\n    {\\n      \\\"incident_number\\\": 45938,\\n      \\\"created_at\\\": \\\"2016-01-23T17:49:10Z\\\",\\n      \\\"status\\\": \\\"resolved\\\",\\n      \\\"pending_actions\\\": [],\\n      \\\"incident_key\\\": \\\"srv01/HTTP\\\",\\n      \\\"service\\\": {\\n        \\\"id\\\": \\\"P3U7V58\\\",\\n        \\\"type\\\": \\\"service_reference\\\",\\n        \\\"summary\\\": \\\"Website\\\",\\n        \\\"self\\\": \\\"https://webdemo.pagerduty.com/api/v1/services/P3U7V58\\\",\\n        \\\"html_url\\\": \\\"https://webdemo.pagerduty.com/services/P3U7V58\\\"\\n      },\\n      \\\"assignments\\\": [],\\n      \\\"acknowledgements\\\": null,\\n      \\\"last_status_change_at\\\": \\\"2016-01-23T21:49:10Z\\\",\\n      \\\"last_status_change_by\\\": {\\n        \\\"id\\\": \\\"P3U7V58\\\",\\n        \\\"type\\\": \\\"service_reference\\\",\\n        \\\"summary\\\": \\\"Website\\\",\\n        \\\"self\\\": \\\"https://webdemo.pagerduty.com/api/v1/services/P3U7V58\\\",\\n        \\\"html_url\\\": \\\"https://webdemo.pagerduty.com/services/P3U7V58\\\"\\n      },\\n      \\\"first_trigger_log_entry\\\": {\\n        \\\"id\\\": \\\"Q1869ITH09X2CV\\\",\\n        \\\"type\\\": \\\"trigger_log_entry_reference\\\",\\n        \\\"summary\\\": \\\"Triggered through the API\\\",\\n        \\\"self\\\": \\\"https://webdemo.pagerduty.com/api/v1/log_entries/Q1869ITH09X2CV\\\",\\n        \\\"html_url\\\": \\\"https://webdemo.pagerduty.com/incidents/P6X6LJU/log_entries/Q1869ITH09X2CV\\\"\\n      },\\n      \\\"escalation_policy\\\": {\\n        \\\"id\\\": \\\"PEEJXL1\\\",\\n        \\\"type\\\": \\\"escalation_policy_reference\\\",\\n        \\\"summary\\\": \\\"DevOps team\\\",\\n        \\\"self\\\": \\\"https://webdemo.pagerduty.com/api/v1/escalation_policies/PEEJXL1\\\",\\n        \\\"html_url\\\": \\\"https://webdemo.pagerduty.com/escalation_policies/PEEJXL1\\\"\\n      },\\n      \\\"teams\\\": [\\n        {\\n          \\\"id\\\": \\\"PNOIFIV\\\",\\n          \\\"type\\\": \\\"team_reference\\\",\\n          \\\"summary\\\": \\\"Ops Team\\\",\\n          \\\"self\\\": \\\"https://webdemo.pagerduty.com/api/v1/teams/PNOIFIV\\\",\\n          \\\"html_url\\\": \\\"https://webdemo.pagerduty.com/teams/PNOIFIV\\\"\\n        }\\n      ],\\n      \\\"urgency\\\": \\\"high\\\",\\n      \\\"id\\\": \\\"P6X6LJU\\\",\\n      \\\"type\\\": \\\"incident\\\",\\n      \\\"summary\\\": \\\"[#45938] The server is on fire.\\\",\\n      \\\"self\\\": \\\"https://webdemo.pagerduty.com/api/v1/incidents/P6X6LJU\\\",\\n      \\\"html_url\\\": \\\"https://webdemo.pagerduty.com/incidents/P6X6LJU\\\"\\n    }\\n  ],\\n  \\\"limit\\\": 1,\\n  \\\"offset\\\": 0,\\n  \\\"total\\\": null,\\n  \\\"more\\\": true\\n}\",\n      \"language\": \"json\",\n      \"name\": \"without include[] values\"\n    },\n    {\n      \"code\": \"# https://api.pagerduty.com/incidents?include[]=services\\n\\n{\\n  \\\"incidents\\\": [\\n    {\\n      \\\"incident_number\\\": 45938,\\n      \\\"created_at\\\": \\\"2016-01-23T17:49:10Z\\\",\\n      \\\"status\\\": \\\"resolved\\\",\\n      \\\"pending_actions\\\": [],\\n      \\\"incident_key\\\": \\\"srv01/HTTP\\\",\\n      \\\"service\\\": {\\n        \\\"id\\\": \\\"P3U7V58\\\",\\n        \\\"name\\\": \\\"Website\\\",\\n        \\\"description\\\": \\\"Website Monitoring\\\",\\n        \\\"service_key\\\": \\\"73c3047621974a99a83e91babdd4a2ba\\\",\\n        \\\"auto_resolve_timeout\\\": 14400,\\n        \\\"acknowledgement_timeout\\\": 1800,\\n        \\\"created_at\\\": \\\"2015-07-27T18:16:20Z\\\",\\n        \\\"status\\\": \\\"critical\\\",\\n        \\\"last_incident_timestamp\\\": \\\"2016-02-23T17:19:38Z\\\",\\n        \\\"teams\\\": [\\n          {\\n            \\\"id\\\": \\\"PNOIFIV\\\",\\n            \\\"type\\\": \\\"team_reference\\\",\\n            \\\"summary\\\": \\\"Ops Team\\\",\\n            \\\"self\\\": \\\"https://webdemo.pagerduty.com/api/v1/teams/PNOIFIV\\\",\\n            \\\"html_url\\\": \\\"https://webdemo.pagerduty.com/teams/PNOIFIV\\\"\\n          }\\n        ],\\n        \\\"incident_urgency_rule\\\": {\\n          \\\"type\\\": \\\"constant\\\",\\n          \\\"urgency\\\": \\\"high\\\"\\n        },\\n        \\\"scheduled_actions\\\": [],\\n        \\\"support_hours\\\": null,\\n        \\\"integrations\\\": [\\n          {\\n            \\\"id\\\": \\\"P05SJ4C\\\",\\n            \\\"type\\\": \\\"generic_events_api_inbound_integration_reference\\\",\\n            \\\"summary\\\": \\\"Generic API\\\",\\n            \\\"self\\\": \\\"https://webdemo.pagerduty.com/api/v1/services/P3U7V58/integrations/P05SJ4C\\\",\\n            \\\"html_url\\\": \\\"https://webdemo.pagerduty.com/services/P3U7V58/integrations/P05SJ4C\\\"\\n          }\\n        ],\\n        \\\"escalation_policy\\\": {\\n          \\\"id\\\": \\\"PEEJXL1\\\",\\n          \\\"type\\\": \\\"escalation_policy_reference\\\",\\n          \\\"summary\\\": \\\"DevOps team\\\",\\n          \\\"self\\\": \\\"https://webdemo.pagerduty.com/api/v1/escalation_policies/PEEJXL1\\\",\\n          \\\"html_url\\\": \\\"https://webdemo.pagerduty.com/escalation_policies/PEEJXL1\\\"\\n        },\\n        \\\"type\\\": \\\"service\\\",\\n        \\\"summary\\\": \\\"Website\\\",\\n        \\\"self\\\": \\\"https://webdemo.pagerduty.com/api/v1/services/P3U7V58\\\",\\n        \\\"html_url\\\": \\\"https://webdemo.pagerduty.com/services/P3U7V58\\\"\\n      },\\n      \\\"assignments\\\": [],\\n      \\\"acknowledgements\\\": null,\\n      \\\"last_status_change_at\\\": \\\"2016-01-23T21:49:10Z\\\",\\n      \\\"last_status_change_by\\\": {\\n        \\\"id\\\": \\\"P3U7V58\\\",\\n        \\\"type\\\": \\\"service_reference\\\",\\n        \\\"summary\\\": \\\"Website\\\",\\n        \\\"self\\\": \\\"https://webdemo.pagerduty.com/api/v1/services/P3U7V58\\\",\\n        \\\"html_url\\\": \\\"https://webdemo.pagerduty.com/services/P3U7V58\\\"\\n      },\\n      \\\"first_trigger_log_entry\\\": {\\n        \\\"id\\\": \\\"Q1869ITH09X2CV\\\",\\n        \\\"type\\\": \\\"trigger_log_entry_reference\\\",\\n        \\\"summary\\\": \\\"Triggered through the API\\\",\\n        \\\"self\\\": \\\"https://webdemo.pagerduty.com/api/v1/log_entries/Q1869ITH09X2CV\\\",\\n        \\\"html_url\\\": \\\"https://webdemo.pagerduty.com/incidents/P6X6LJU/log_entries/Q1869ITH09X2CV\\\"\\n      },\\n      \\\"escalation_policy\\\": {\\n        \\\"id\\\": \\\"PEEJXL1\\\",\\n        \\\"type\\\": \\\"escalation_policy_reference\\\",\\n        \\\"summary\\\": \\\"DevOps team\\\",\\n        \\\"self\\\": \\\"https://webdemo.pagerduty.com/api/v1/escalation_policies/PEEJXL1\\\",\\n        \\\"html_url\\\": \\\"https://webdemo.pagerduty.com/escalation_policies/PEEJXL1\\\"\\n      },\\n      \\\"teams\\\": [\\n        {\\n          \\\"id\\\": \\\"PNOIFIV\\\",\\n          \\\"type\\\": \\\"team_reference\\\",\\n          \\\"summary\\\": \\\"Ops Team\\\",\\n          \\\"self\\\": \\\"https://webdemo.pagerduty.com/api/v1/teams/PNOIFIV\\\",\\n          \\\"html_url\\\": \\\"https://webdemo.pagerduty.com/teams/PNOIFIV\\\"\\n        }\\n      ],\\n      \\\"urgency\\\": \\\"high\\\",\\n      \\\"id\\\": \\\"P6X6LJU\\\",\\n      \\\"type\\\": \\\"incident\\\",\\n      \\\"summary\\\": \\\"[#45938] The server is on fire.\\\",\\n      \\\"self\\\": \\\"https://webdemo.pagerduty.com/api/v1/incidents/P6X6LJU\\\",\\n      \\\"html_url\\\": \\\"https://webdemo.pagerduty.com/incidents/P6X6LJU\\\"\\n    }\\n  ],\\n  \\\"limit\\\": 1,\\n  \\\"offset\\\": 0,\\n  \\\"total\\\": null,\\n  \\\"more\\\": true\\n}\\n\",\n      \"language\": \"json\",\n      \"name\": \"with included services\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"includes","type":"basic","title":"Includes"}

Getting Started

Libraries, Tools, and Examples

REST API

REST API v1 (Legacy)

Events API v2

Events API v1

Webhooks

Includes

Depending on your client's needs, you may want to have all of a resource's information available in the response of a related resource. Instead of just receiving the [reference](doc:references) (an abbreviated form of the related resource), including a type of resource will make all resources of that type contain their [full set of fields](#section-resource-schema-and-types) in the response. Includes are specified with the `include[]` parameter. The values allowed in an `include[]` parameter vary from endpoint to endpoint, but will always be the pluralized type of a resource or the pluralized name of a resource field representing the relationship between resources. [block:api-header] { "type": "basic", "title": "Example" } [/block] In the below example, the `/incidents` API is accessed with and without including `services`. Note how including `services` causes a full `Service` [schema](doc:resource-schemas) (with type `service`) to be displayed in the `service` field of the incident, while without the `include[]` the `service` field contains a `ServiceReference` [schema](doc:resource-schemas)) (with type `service_reference`). [block:code] { "codes": [ { "code": "# https://api.pagerduty.com/incidents\n\n{\n \"incidents\": [\n {\n \"incident_number\": 45938,\n \"created_at\": \"2016-01-23T17:49:10Z\",\n \"status\": \"resolved\",\n \"pending_actions\": [],\n \"incident_key\": \"srv01/HTTP\",\n \"service\": {\n \"id\": \"P3U7V58\",\n \"type\": \"service_reference\",\n \"summary\": \"Website\",\n \"self\": \"https://webdemo.pagerduty.com/api/v1/services/P3U7V58\",\n \"html_url\": \"https://webdemo.pagerduty.com/services/P3U7V58\"\n },\n \"assignments\": [],\n \"acknowledgements\": null,\n \"last_status_change_at\": \"2016-01-23T21:49:10Z\",\n \"last_status_change_by\": {\n \"id\": \"P3U7V58\",\n \"type\": \"service_reference\",\n \"summary\": \"Website\",\n \"self\": \"https://webdemo.pagerduty.com/api/v1/services/P3U7V58\",\n \"html_url\": \"https://webdemo.pagerduty.com/services/P3U7V58\"\n },\n \"first_trigger_log_entry\": {\n \"id\": \"Q1869ITH09X2CV\",\n \"type\": \"trigger_log_entry_reference\",\n \"summary\": \"Triggered through the API\",\n \"self\": \"https://webdemo.pagerduty.com/api/v1/log_entries/Q1869ITH09X2CV\",\n \"html_url\": \"https://webdemo.pagerduty.com/incidents/P6X6LJU/log_entries/Q1869ITH09X2CV\"\n },\n \"escalation_policy\": {\n \"id\": \"PEEJXL1\",\n \"type\": \"escalation_policy_reference\",\n \"summary\": \"DevOps team\",\n \"self\": \"https://webdemo.pagerduty.com/api/v1/escalation_policies/PEEJXL1\",\n \"html_url\": \"https://webdemo.pagerduty.com/escalation_policies/PEEJXL1\"\n },\n \"teams\": [\n {\n \"id\": \"PNOIFIV\",\n \"type\": \"team_reference\",\n \"summary\": \"Ops Team\",\n \"self\": \"https://webdemo.pagerduty.com/api/v1/teams/PNOIFIV\",\n \"html_url\": \"https://webdemo.pagerduty.com/teams/PNOIFIV\"\n }\n ],\n \"urgency\": \"high\",\n \"id\": \"P6X6LJU\",\n \"type\": \"incident\",\n \"summary\": \"[#45938] The server is on fire.\",\n \"self\": \"https://webdemo.pagerduty.com/api/v1/incidents/P6X6LJU\",\n \"html_url\": \"https://webdemo.pagerduty.com/incidents/P6X6LJU\"\n }\n ],\n \"limit\": 1,\n \"offset\": 0,\n \"total\": null,\n \"more\": true\n}", "language": "json", "name": "without include[] values" }, { "code": "# https://api.pagerduty.com/incidents?include[]=services\n\n{\n \"incidents\": [\n {\n \"incident_number\": 45938,\n \"created_at\": \"2016-01-23T17:49:10Z\",\n \"status\": \"resolved\",\n \"pending_actions\": [],\n \"incident_key\": \"srv01/HTTP\",\n \"service\": {\n \"id\": \"P3U7V58\",\n \"name\": \"Website\",\n \"description\": \"Website Monitoring\",\n \"service_key\": \"73c3047621974a99a83e91babdd4a2ba\",\n \"auto_resolve_timeout\": 14400,\n \"acknowledgement_timeout\": 1800,\n \"created_at\": \"2015-07-27T18:16:20Z\",\n \"status\": \"critical\",\n \"last_incident_timestamp\": \"2016-02-23T17:19:38Z\",\n \"teams\": [\n {\n \"id\": \"PNOIFIV\",\n \"type\": \"team_reference\",\n \"summary\": \"Ops Team\",\n \"self\": \"https://webdemo.pagerduty.com/api/v1/teams/PNOIFIV\",\n \"html_url\": \"https://webdemo.pagerduty.com/teams/PNOIFIV\"\n }\n ],\n \"incident_urgency_rule\": {\n \"type\": \"constant\",\n \"urgency\": \"high\"\n },\n \"scheduled_actions\": [],\n \"support_hours\": null,\n \"integrations\": [\n {\n \"id\": \"P05SJ4C\",\n \"type\": \"generic_events_api_inbound_integration_reference\",\n \"summary\": \"Generic API\",\n \"self\": \"https://webdemo.pagerduty.com/api/v1/services/P3U7V58/integrations/P05SJ4C\",\n \"html_url\": \"https://webdemo.pagerduty.com/services/P3U7V58/integrations/P05SJ4C\"\n }\n ],\n \"escalation_policy\": {\n \"id\": \"PEEJXL1\",\n \"type\": \"escalation_policy_reference\",\n \"summary\": \"DevOps team\",\n \"self\": \"https://webdemo.pagerduty.com/api/v1/escalation_policies/PEEJXL1\",\n \"html_url\": \"https://webdemo.pagerduty.com/escalation_policies/PEEJXL1\"\n },\n \"type\": \"service\",\n \"summary\": \"Website\",\n \"self\": \"https://webdemo.pagerduty.com/api/v1/services/P3U7V58\",\n \"html_url\": \"https://webdemo.pagerduty.com/services/P3U7V58\"\n },\n \"assignments\": [],\n \"acknowledgements\": null,\n \"last_status_change_at\": \"2016-01-23T21:49:10Z\",\n \"last_status_change_by\": {\n \"id\": \"P3U7V58\",\n \"type\": \"service_reference\",\n \"summary\": \"Website\",\n \"self\": \"https://webdemo.pagerduty.com/api/v1/services/P3U7V58\",\n \"html_url\": \"https://webdemo.pagerduty.com/services/P3U7V58\"\n },\n \"first_trigger_log_entry\": {\n \"id\": \"Q1869ITH09X2CV\",\n \"type\": \"trigger_log_entry_reference\",\n \"summary\": \"Triggered through the API\",\n \"self\": \"https://webdemo.pagerduty.com/api/v1/log_entries/Q1869ITH09X2CV\",\n \"html_url\": \"https://webdemo.pagerduty.com/incidents/P6X6LJU/log_entries/Q1869ITH09X2CV\"\n },\n \"escalation_policy\": {\n \"id\": \"PEEJXL1\",\n \"type\": \"escalation_policy_reference\",\n \"summary\": \"DevOps team\",\n \"self\": \"https://webdemo.pagerduty.com/api/v1/escalation_policies/PEEJXL1\",\n \"html_url\": \"https://webdemo.pagerduty.com/escalation_policies/PEEJXL1\"\n },\n \"teams\": [\n {\n \"id\": \"PNOIFIV\",\n \"type\": \"team_reference\",\n \"summary\": \"Ops Team\",\n \"self\": \"https://webdemo.pagerduty.com/api/v1/teams/PNOIFIV\",\n \"html_url\": \"https://webdemo.pagerduty.com/teams/PNOIFIV\"\n }\n ],\n \"urgency\": \"high\",\n \"id\": \"P6X6LJU\",\n \"type\": \"incident\",\n \"summary\": \"[#45938] The server is on fire.\",\n \"self\": \"https://webdemo.pagerduty.com/api/v1/incidents/P6X6LJU\",\n \"html_url\": \"https://webdemo.pagerduty.com/incidents/P6X6LJU\"\n }\n ],\n \"limit\": 1,\n \"offset\": 0,\n \"total\": null,\n \"more\": true\n}\n", "language": "json", "name": "with included services" } ] } [/block]