Using the REST API

Generating a General Access REST API Key

Depending on the type of API key you are creating, for more information about authenticating using an API key, please consult the related documentation for v1 or v2.

Most integrations will require a v1 API key. For more information on the differences between the APIs, check out our article on the differences between our REST and Events APIs.

Note

You must be an admin or account owner within PagerDuty to access your API key. REST API access is only included on the current Basic plan or higher — API access is not included on the Lite plan.

  1. Go to Configuration → API Access and click Create New API Key.
  2. Enter a Description that will help you identify the key later on.
  3. Select the version of the API you will be using (v1 or v2) and whether you want it to be a read-only key, then click Create Key. Many integrations, especially older ones will require a v1 API key. For more information on the difference between v1 and v2, and which API key you should create, check out this article.
  1. A unique API key will be generated. Copy it to a safe place and click Close.

Once you click Close you will be asked to confirm that you copied the API key. This is your last chance to copy the key — you will only be able to see the last 4 characters of the key in the PagerDuty interface after you confirm. If you lose a key you will need to delete it and create a new one.

Once created, you will see your key appear in the list of keys on the API Access page, with versioning noted.

Generating a Personal REST API key

Users can create personal REST API keys on their User Settings page of the user profile. Keys created this way will provide access to the REST API that matches their user permissions.

Getting Started with the REST API

The best place to start your API journey is with our blog post introducing the API for suggestions and examples of what other customers have done.

When you're ready for more, head over to the PagerDuty Developer site for detailed documentation on our API endpoints.

You can also consult our script library for examples of scripts that interact with our API. Scripts are available in Ruby, Python and PHP; most are simple curl calls with variables defined at the top where you will substitute your own values. These scripts should be easy to run from the command line on Unix, Linux and Mac.

Let's use curl to interact with the GET schedules endpoint of our REST API from the command line as an example. In these examples, you will need to replace <YOUR_API_KEY> with a valid v2 REST API key. If you do not already have an access token, please take a look at our article on Generating an API Key.

With an API key, I can run the following command to list the details for all of my account's schedules:

curl -H "Accept: application/vnd.pagerduty+json;version=2" \
 -H "Authorization: Token token=<YOUR_API_KEY>" -X GET \
 "https://api.pagerduty.com/schedules"

I would then see the following output in my command line interface in JSON format:

Note

This output has been formatted for readability. Your output may appear minified until you have used a program to format the JSON for readability.

{
  "schedules": [
    {
      "id": "P6JZ92K",
      "type": "schedule",
      "summary": "Admin - Global",
      "self": "https://api.pagerduty.com/schedules/P6JZ92K",
      "html_url": "https://webdemo.pagerduty.com/schedules/P6JZ92K",
      "name": "Admin - Global",
      "time_zone": "Australia/Sydney",
      "description": null,
      "escalation_policies": [
        {
          "id": "PJZ9LK2",
          "type": "escalation_policy_reference",
          "summary": "SiteAdmin 24x7",
          "self": "https://api.pagerduty.com/escalation_policies/PJZ9LK2",
          "html_url": "https://webdemo.pagerduty.com/escalation_policies/PJZ9LK2"
        },
        {
          "id": "PA5W587",
          "type": "escalation_policy_reference",
          "summary": "Operations",
          "self": "https://api.pagerduty.com/escalation_policies/PA5W587",
          "html_url": "https://webdemo.pagerduty.com/escalation_policies/PA5W587"
        }
      ],
      "users": [
        {
          "id": "PSAHZUD",
          "type": "user_reference",
          "summary": "David Shackelford",
          "self": "https://api.pagerduty.com/users/PSAHZUD",
          "html_url": "https://webdemo.pagerduty.com/users/PSAHZUD"
        },
        {
          "id": "PRMXSSO",
          "type": "user_reference",
          "summary": "Benedict Cumberbatch",
          "self": "https://api.pagerduty.com/users/PRMXSSO",
          "html_url": "https://webdemo.pagerduty.com/users/PRMXSSO"
        },
        {
          "id": "P1BU2CE",
          "type": "user_reference",
          "summary": "Dave Cliffe",
          "self": "https://api.pagerduty.com/users/P1BU2CE",
          "html_url": "https://webdemo.pagerduty.com/users/P1BU2CE"
        },
        {
          "id": "P0VLWEU",
          "type": "user_reference",
          "summary": "Samuel Clemens",
          "self": "https://api.pagerduty.com/users/P0VLWEU",
          "html_url": "https://webdemo.pagerduty.com/users/P0VLWEU"
        },
        {
          "id": "P0YSUGZ",
          "type": "user_reference",
          "summary": "Han Solo",
          "self": "https://api.pagerduty.com/users/P0YSUGZ",
          "html_url": "https://webdemo.pagerduty.com/users/P0YSUGZ"
        },
        {
          "id": "PC92TC3",
          "type": "user_reference",
          "summary": "Luke Skywalker",
          "self": "https://api.pagerduty.com/users/PC92TC3",
          "html_url": "https://webdemo.pagerduty.com/users/PC92TC3"
        },
        {
          "id": "P79LCJF",
          "type": "user_reference",
          "summary": "Andrew Bakhtiari",
          "self": "https://api.pagerduty.com/users/P79LCJF",
          "html_url": "https://webdemo.pagerduty.com/users/P79LCJF"
        },
        {
          "id": "PQ8MK00",
          "type": "user_reference",
          "summary": "Blake McMillan",
          "self": "https://api.pagerduty.com/users/PQ8MK00",
          "html_url": "https://webdemo.pagerduty.com/users/PQ8MK00"
        },
        {
          "id": "P8GWIGI",
          "type": "user_reference",
          "summary": "Colby Glieden",
          "self": "https://api.pagerduty.com/users/P8GWIGI",
          "html_url": "https://webdemo.pagerduty.com/users/P8GWIGI"
        },
        {
          "id": "PX6RN71",
          "type": "user_reference",
          "summary": "Angela Chapman",
          "self": "https://api.pagerduty.com/users/PX6RN71",
          "html_url": "https://webdemo.pagerduty.com/users/PX6RN71"
        },
        {
          "id": "PBJEGFZ",
          "type": "user_reference",
          "summary": "David Lanstein",
          "self": "https://api.pagerduty.com/users/PBJEGFZ",
          "html_url": "https://webdemo.pagerduty.com/users/PBJEGFZ"
        },
        {
          "id": "PEJV34Q",
          "type": "user_reference",
          "summary": "Kyle Fitzpatrick",
          "self": "https://api.pagerduty.com/users/PEJV34Q",
          "html_url": "https://webdemo.pagerduty.com/users/PEJV34Q"
        }
      ],
      "teams": [
        {
          "id": "PNOIFIV",
          "type": "team_reference",
          "summary": "Ops Team",
          "self": "https://api.pagerduty.com/teams/PNOIFIV",
          "html_url": "https://webdemo.pagerduty.com/teams/PNOIFIV"
        },
        {
          "id": "P7W0ZIU",
          "type": "team_reference",
          "summary": "Monitoring Tools Team",
          "self": "https://api.pagerduty.com/teams/P7W0ZIU",
          "html_url": "https://webdemo.pagerduty.com/teams/P7W0ZIU"
        }
      ]
    },
    {
      "id": "PEECITZ",
      "type": "schedule",
      "summary": "After Hours ",
      "self": "https://api.pagerduty.com/schedules/PEECITZ",
      "html_url": "https://webdemo.pagerduty.com/schedules/PEECITZ",
      "name": "After Hours ",
      "time_zone": "America/Los_Angeles",
      "description": null,
      "escalation_policies": [
        {
          "id": "P69WI9G",
          "type": "escalation_policy_reference",
          "summary": "John (Ops)",
          "self": "https://api.pagerduty.com/escalation_policies/P69WI9G",
          "html_url": "https://webdemo.pagerduty.com/escalation_policies/P69WI9G"
        },
        {
          "id": "PA5W587",
          "type": "escalation_policy_reference",
          "summary": "Operations",
          "self": "https://api.pagerduty.com/escalation_policies/PA5W587",
          "html_url": "https://webdemo.pagerduty.com/escalation_policies/PA5W587"
        },
        {
          "id": "PWRYUY4",
          "type": "escalation_policy_reference",
          "summary": "Operations - AWS",
          "self": "https://api.pagerduty.com/escalation_policies/PWRYUY4",
          "html_url": "https://webdemo.pagerduty.com/escalation_policies/PWRYUY4"
        },
        {
          "id": "PBJRITM",
          "type": "escalation_policy_reference",
          "summary": "Weekends",
          "self": "https://api.pagerduty.com/escalation_policies/PBJRITM",
          "html_url": "https://webdemo.pagerduty.com/escalation_policies/PBJRITM"
        },
        {
          "id": "PWCQTOV",
          "type": "escalation_policy_reference",
          "summary": "Alexis demo EP",
          "self": "https://api.pagerduty.com/escalation_policies/PWCQTOV",
          "html_url": "https://webdemo.pagerduty.com/escalation_policies/PWCQTOV"
        }
      ],
      "users": [
        {
          "id": "PX6RN71",
          "type": "user_reference",
          "summary": "Angela Chapman",
          "self": "https://api.pagerduty.com/users/PX6RN71",
          "html_url": "https://webdemo.pagerduty.com/users/PX6RN71"
        },
        {
          "id": "P52YQZX",
          "type": "user_reference",
          "summary": "Dave",
          "self": "https://api.pagerduty.com/users/P52YQZX",
          "html_url": "https://webdemo.pagerduty.com/users/P52YQZX"
        }
      ],
      "teams": [
        {
          "id": "PTN67DJ",
          "type": "team_reference",
          "summary": "Applications - PayPal",
          "self": null,
          "html_url": null
        },
        {
          "id": "PRJ4D5C",
          "type": "team_reference",
          "summary": "ops",
          "self": "https://api.pagerduty.com/teams/PRJ4D5C",
          "html_url": "https://webdemo.pagerduty.com/teams/PRJ4D5C"
        },
        {
          "id": "P7W0ZIU",
          "type": "team_reference",
          "summary": "Monitoring Tools Team",
          "self": "https://api.pagerduty.com/teams/P7W0ZIU",
          "html_url": "https://webdemo.pagerduty.com/teams/P7W0ZIU"
        }
      ]
    }
  ],
  "limit": 25,
  "offset": 0,
  "total": null,
  "more": true
}

On the Schedules API index, I see that I can also pass arguments for individual schedules, by ID, with GET schedules/{id}.

I'll use the first schedule listed above, with ID P6JZ92K, and enter in the following curl command into my command line interface:

curl -H "Accept: application/vnd.pagerduty+json;version=2" \
 -H "Authorization: Token token=<YOUR_API_KEY>" -X GET \
 "https://api.pagerduty.com/schedules/P6JZ92K"

I would then see the following output:

{
  "schedule": {
    "id": "P6JZ92K",
    "type": "schedule",
    "summary": "Admin - Global",
    "self": "https://api.pagerduty.com/schedules/P6JZ92K",
    "html_url": "https://webdemo.pagerduty.com/schedules/P6JZ92K",
    "name": "Admin - Global",
    "time_zone": "Australia/Sydney",
    "description": null,
    "escalation_policies": [
      {
        "id": "PJZ9LK2",
        "type": "escalation_policy_reference",
        "summary": "SiteAdmin 24x7",
        "self": "https://api.pagerduty.com/escalation_policies/PJZ9LK2",
        "html_url": "https://webdemo.pagerduty.com/escalation_policies/PJZ9LK2"
      },
      {
        "id": "PA5W587",
        "type": "escalation_policy_reference",
        "summary": "Operations",
        "self": "https://api.pagerduty.com/escalation_policies/PA5W587",
        "html_url": "https://webdemo.pagerduty.com/escalation_policies/PA5W587"
      }
    ],
    "users": [
      {
        "id": "PRMXSSO",
        "type": "user_reference",
        "summary": "Benedict Cumberbatch",
        "self": "https://api.pagerduty.com/users/PRMXSSO",
        "html_url": "https://webdemo.pagerduty.com/users/PRMXSSO"
      },
      {
        "id": "P1BU2CE",
        "type": "user_reference",
        "summary": "Dave Cliffe",
        "self": "https://api.pagerduty.com/users/P1BU2CE",
        "html_url": "https://webdemo.pagerduty.com/users/P1BU2CE"
      },
      {
        "id": "PSAHZUD",
        "type": "user_reference",
        "summary": "David Shackelford",
        "self": "https://api.pagerduty.com/users/PSAHZUD",
        "html_url": "https://webdemo.pagerduty.com/users/PSAHZUD"
      },
      {
        "id": "P0YSUGZ",
        "type": "user_reference",
        "summary": "Han Solo",
        "self": "https://api.pagerduty.com/users/P0YSUGZ",
        "html_url": "https://webdemo.pagerduty.com/users/P0YSUGZ"
      },
      {
        "id": "PC92TC3",
        "type": "user_reference",
        "summary": "Luke Skywalker",
        "self": "https://api.pagerduty.com/users/PC92TC3",
        "html_url": "https://webdemo.pagerduty.com/users/PC92TC3"
      },
      {
        "id": "P0VLWEU",
        "type": "user_reference",
        "summary": "Samuel Clemens",
        "self": "https://api.pagerduty.com/users/P0VLWEU",
        "html_url": "https://webdemo.pagerduty.com/users/P0VLWEU"
      },
      {
        "id": "PX6RN71",
        "type": "user_reference",
        "summary": "Angela Chapman",
        "self": "https://api.pagerduty.com/users/PX6RN71",
        "html_url": "https://webdemo.pagerduty.com/users/PX6RN71"
      },
      {
        "id": "P79LCJF",
        "type": "user_reference",
        "summary": "Andrew Bakhtiari",
        "self": "https://api.pagerduty.com/users/P79LCJF",
        "html_url": "https://webdemo.pagerduty.com/users/P79LCJF"
      },
      {
        "id": "PBJEGFZ",
        "type": "user_reference",
        "summary": "David Lanstein",
        "self": "https://api.pagerduty.com/users/PBJEGFZ",
        "html_url": "https://webdemo.pagerduty.com/users/PBJEGFZ"
      },
      {
        "id": "PQ8MK00",
        "type": "user_reference",
        "summary": "Blake McMillan",
        "self": "https://api.pagerduty.com/users/PQ8MK00",
        "html_url": "https://webdemo.pagerduty.com/users/PQ8MK00"
      },
      {
        "id": "PEJV34Q",
        "type": "user_reference",
        "summary": "Kyle Fitzpatrick",
        "self": "https://api.pagerduty.com/users/PEJV34Q",
        "html_url": "https://webdemo.pagerduty.com/users/PEJV34Q"
      },
      {
        "id": "P8GWIGI",
        "type": "user_reference",
        "summary": "Colby Glieden",
        "self": "https://api.pagerduty.com/users/P8GWIGI",
        "html_url": "https://webdemo.pagerduty.com/users/P8GWIGI"
      }
    ],
    "schedule_layers": [
      {
        "name": "Layer 2",
        "rendered_schedule_entries": [],
        "rendered_coverage_percentage": null,
        "id": "PS8Y15O",
        "start": "2016-05-18T07:00:39+10:00",
        "end": null,
        "rotation_virtual_start": "2016-05-16T20:00:00+10:00",
        "rotation_turn_length_seconds": 604800,
        "users": [
          {
            "user": {
              "id": "P0VLWEU",
              "type": "user_reference",
              "summary": "Samuel Clemens",
              "self": "https://api.pagerduty.com/users/P0VLWEU",
              "html_url": "https://webdemo.pagerduty.com/users/P0VLWEU"
            }
          },
          {
            "user": {
              "id": "P0YSUGZ",
              "type": "user_reference",
              "summary": "Han Solo",
              "self": "https://api.pagerduty.com/users/P0YSUGZ",
              "html_url": "https://webdemo.pagerduty.com/users/P0YSUGZ"
            }
          },
          {
            "user": {
              "id": "PC92TC3",
              "type": "user_reference",
              "summary": "Luke Skywalker",
              "self": "https://api.pagerduty.com/users/PC92TC3",
              "html_url": "https://webdemo.pagerduty.com/users/PC92TC3"
            }
          }
        ],
        "restrictions": [
          {
            "type": "daily_restriction",
            "start_time_of_day": "20:00:00",
            "duration_seconds": 43200
          }
        ]
      },
      {
        "name": "Layer 1",
        "rendered_schedule_entries": [],
        "rendered_coverage_percentage": null,
        "id": "PD3V39R",
        "start": "2016-05-18T07:00:39+10:00",
        "end": null,
        "rotation_virtual_start": "2016-05-16T08:00:00+10:00",
        "rotation_turn_length_seconds": 604800,
        "users": [
          {
            "user": {
              "id": "PSAHZUD",
              "type": "user_reference",
              "summary": "David Shackelford",
              "self": "https://api.pagerduty.com/users/PSAHZUD",
              "html_url": "https://webdemo.pagerduty.com/users/PSAHZUD"
            }
          },
          {
            "user": {
              "id": "PRMXSSO",
              "type": "user_reference",
              "summary": "Benedict Cumberbatch",
              "self": "https://api.pagerduty.com/users/PRMXSSO",
              "html_url": "https://webdemo.pagerduty.com/users/PRMXSSO"
            }
          },
          {
            "user": {
              "id": "P1BU2CE",
              "type": "user_reference",
              "summary": "Dave Cliffe",
              "self": "https://api.pagerduty.com/users/P1BU2CE",
              "html_url": "https://webdemo.pagerduty.com/users/P1BU2CE"
            }
          }
        ],
        "restrictions": [
          {
            "type": "daily_restriction",
            "start_time_of_day": "08:00:00",
            "duration_seconds": 43200
          }
        ]
      }
    ],
    "overrides_subschedule": {
      "name": "Overrides",
      "rendered_schedule_entries": [],
      "rendered_coverage_percentage": null
    },
    "final_schedule": {
      "name": "Final Schedule",
      "rendered_schedule_entries": [],
      "rendered_coverage_percentage": null
    },
    "teams": [
      {
        "id": "PNOIFIV",
        "type": "team_reference",
        "summary": "Ops Team",
        "self": "https://api.pagerduty.com/teams/PNOIFIV",
        "html_url": "https://webdemo.pagerduty.com/teams/PNOIFIV"
      },
      {
        "id": "P7W0ZIU",
        "type": "team_reference",
        "summary": "Monitoring Tools Team",
        "self": "https://api.pagerduty.com/teams/P7W0ZIU",
        "html_url": "https://webdemo.pagerduty.com/teams/P7W0ZIU"
      }
    ]
  }
}

Reading the documentation again, I see that I can also pass two parameters of interest to since and until. I can include these parameters in the request as follows:

curl -H "Accept: application/vnd.pagerduty+json;version=2" \
 -H "Authorization: Token token=<YOUR_API_KEY>" -X GET \
 "https://api.pagerduty.com/schedules/P6JZ92K?since=2016-06-01&until=2016-07-01"

Please note that submitted data should be encoded. This means that here and elsewhere, the first argument can be submitted at the end of the URL with a question mark (?), and every other argument after the first using an ampersand (&). You should not include quotation marks around arguments, even if the argument has a space within it (i.e. for a service named Ops - Weekly). Instead, using percent encoding, spaces would be represented as %20.

curl also provides a - -data-urlencode flag that can be used to automatically encode your parameters properly. We suggest using this flag in most situations to avoid potential issues with special characters in your parameters. I can run the same command as above with the - -data-urlencode flag as follows:

curl -H "Accept: application/vnd.pagerduty+json;version=2" \
 -H "Authorization: Token token=<YOUR_API_KEY>" -X GET -G \
 - -data-urlencode "since=2016-06-01" \
 - -data-urlencode "until=2016-07-01" \
 "https://api.pagerduty.com/schedules/P6JZ92K"

Using the REST API