{"_id":"56c51dc3ba4a540d0091b9b9","__v":9,"parentDoc":null,"user":"564e5788230d7c1700c9073e","project":"564e5930c3553e0d003e53d0","version":{"_id":"564e5a9b1560880d008d30dc","project":"564e5930c3553e0d003e53d0","__v":21,"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"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"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"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-02-18T01:26:27.389Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"The version of the API that responds to a given request is based on the authentication token provided as part of the request, but can be overridden with a header.\n\n## Token-based versioning\n\nBy default, all new authentication tokens will be set to provide the latest version of the API. Existing authentication tokens will request the final released version of the API that was available at the time of their creation.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Accessing with an API v1 Token\",\n  \"body\": \"Either create a v2 API token or use [header-based versioning](#section-header-based-versioning) to access API v2. We recommend adding the header so that your code is always getting the API version it needs, regardless of token.\\n\\nIf you are using an API v1 token and not sending the header properly, you will receive a `404 Not Found`.\"\n}\n[/block]\n## Header-based versioning\n\nIf you're writing code that's designed to work with multiple authentication tokens or with a specific version of the API, the best way to ensure you get the right version is with [PagerDuty's `Accept` header](http://www.iana.org/assignments/media-types/application/vnd.pagerduty+json):\n\n```\nAccept: application/vnd.pagerduty+json;version=2\n```\n\nAny request made using this header will respond with the specified API version, regardless of the authentication token used.\n\n##### Samples\n\nHere's how you can set the `Accept` header in some popular HTTP libraries:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"req = Net::HTTP::Get.new('https://api.pagerduty.com/users')\\napi_version = '2'\\nreq.add_field('Accept', \\\"application/vnd.pagerduty+json;version=#{api_version}\\\")\",\n      \"language\": \"ruby\",\n      \"name\": \"Ruby + Net::HTTP\"\n    },\n    {\n      \"code\": \"var api_version = \\\"2\\\";\\n$.ajax({\\n  url: \\\"https://api.pagerduty.com/users\\\",\\n  type: \\\"GET\\\",\\n  headers: {\\\"Accept\\\": \\\"application/vnd.pagerduty+json;version=\\\" + api_version}\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"jQuery\"\n    },\n    {\n      \"code\": \"api_version = '2'\\nrequests.get('https://api.pagerduty.com/users', headers={'Accept': 'application/vnd.pagerduty+json;version=' + api_version})\",\n      \"language\": \"python\",\n      \"name\": \"Python + Requests\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"versioning","type":"basic","title":"Versioning"}
The version of the API that responds to a given request is based on the authentication token provided as part of the request, but can be overridden with a header. ## Token-based versioning By default, all new authentication tokens will be set to provide the latest version of the API. Existing authentication tokens will request the final released version of the API that was available at the time of their creation. [block:callout] { "type": "info", "title": "Accessing with an API v1 Token", "body": "Either create a v2 API token or use [header-based versioning](#section-header-based-versioning) to access API v2. We recommend adding the header so that your code is always getting the API version it needs, regardless of token.\n\nIf you are using an API v1 token and not sending the header properly, you will receive a `404 Not Found`." } [/block] ## Header-based versioning If you're writing code that's designed to work with multiple authentication tokens or with a specific version of the API, the best way to ensure you get the right version is with [PagerDuty's `Accept` header](http://www.iana.org/assignments/media-types/application/vnd.pagerduty+json): ``` Accept: application/vnd.pagerduty+json;version=2 ``` Any request made using this header will respond with the specified API version, regardless of the authentication token used. ##### Samples Here's how you can set the `Accept` header in some popular HTTP libraries: [block:code] { "codes": [ { "code": "req = Net::HTTP::Get.new('https://api.pagerduty.com/users')\napi_version = '2'\nreq.add_field('Accept', \"application/vnd.pagerduty+json;version=#{api_version}\")", "language": "ruby", "name": "Ruby + Net::HTTP" }, { "code": "var api_version = \"2\";\n$.ajax({\n url: \"https://api.pagerduty.com/users\",\n type: \"GET\",\n headers: {\"Accept\": \"application/vnd.pagerduty+json;version=\" + api_version}\n});", "language": "javascript", "name": "jQuery" }, { "code": "api_version = '2'\nrequests.get('https://api.pagerduty.com/users', headers={'Accept': 'application/vnd.pagerduty+json;version=' + api_version})", "language": "python", "name": "Python + Requests" } ] } [/block]