Using the REST API

Generating a General Access REST API Key

For more information about authenticating using an API key, please consult the related documentation.

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 Platform Team 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. If you would like it to be read-only, check the Read-only option.
  3. Click Create Key. Note that as of Oct. 19, 2018, the v1 REST API is deprecated and v1 keys cannot be created. For more information on this, please see our v1 REST API decommissioning FAQ.
  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.

OpenAPI Spec

One can access and download the OpenAPI JSON specification for the PagerDuty REST API at the following URL:

https://api-reference.pagerduty.com/output.json

Integrations that Require REST API Access

Note

REST API access is only included on the current Basic plan or higher. Because API access is not included on the Lite plan, the above integrations will not be available to accounts on Lite plans.

Generating a Personal REST API key

If your account has Advanced Permissions enabled, users can create personal REST API keys on the User Settings tab of their user profile. Requests made using personal REST API keys will be restricted to the user's 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"