Getting Started with the PagerDuty API

Follow

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 me: 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"
Have more questions? Submit a request

Comments