{"_id":"56c51f367de3580d00bdaf2a","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":1,"slug":"patterns","title":"REST API v2"},"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":true,"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":"","githubsync":"","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:references) (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"}

Basics

REST API v2

Events API v1

Events API v2

Webhooks v1

Webhooks v2

Build

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:references) (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]