PagerDuty API Getting Started: Quickstart Guide (2026)

Getting started overview

Integrating with the PagerDuty API allows developers to programmatically manage incidents, on-call schedules, and other PagerDuty functionalities from external systems. This guide provides a structured approach to initiate your development efforts, covering account setup, API key generation, and the execution of a foundational API request. The PagerDuty API is designed to support various use cases, including automating incident creation, synchronizing user and team data, and integrating with monitoring tools or custom applications for enhanced operational visibility and control. The platform offers a comprehensive set of documentation to support these integrations.

The core process involves obtaining an API token, which serves as the primary authentication mechanism for all API calls. Once authenticated, you can interact with various API endpoints to perform operations such as creating incidents, retrieving service information, or managing on-call rotations. PagerDuty's API reference details the available endpoints, request/response formats, and required parameters for each operation. Supported SDKs for Python, Ruby, Go, Java, and Node.js simplify interaction with the API.

Here's a quick reference table outlining the initial steps:

Create an account and get keys

To begin using the PagerDuty API, you need an active PagerDuty account. If you do not have one, you can sign up for a free plan, which supports up to five users. This free tier provides access to core incident management features, suitable for initial API exploration and development.

Once your account is set up and you've logged in, the next crucial step is to generate an API Access Key. This key is a long-lived token that authenticates your requests to the PagerDuty API. Follow these steps to generate a General Access API Key:

1. Navigate to the PagerDuty web application.
2. From the top menu, select Integrations.
3. Choose API Access Keys from the dropdown.
4. Click the + Create New API Key button.
5. Provide a descriptive Description for your key (e.g., "My First API Integration").
6. Ensure the Read-only (v2) option is selected for your initial testing to minimize potential unintended changes. For production integrations, you might require a key with broader permissions.
7. Click Create Key.
8. The new API key will be displayed. Copy this key immediately and store it securely. PagerDuty will only display this key once, and it cannot be retrieved later. If lost, you will need to generate a new one.

This API key will be included in the Authorization header of your API requests, typically as a Bearer token. For example, Authorization: Token token=YOUR_API_KEY.

Your first request

With an API key in hand, you can now make your first authenticated request to the PagerDuty API. This example demonstrates how to retrieve a list of services using the /services endpoint. We will use cURL for this example, as it's a ubiquitous command-line tool for making HTTP requests and doesn't require installing an SDK.

Prerequisites:

• cURL installed on your system.
• Your PagerDuty General Access API Key (obtained in the previous step).

Retrieve a list of services:

Open your terminal or command prompt and execute the following cURL command. Replace YOUR_API_KEY with the actual API key you generated.

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

Let's break down this command:

• curl -X GET: Specifies that this is an HTTP GET request.
• -H "Accept: application/vnd.pagerduty+json;version=2": Sets the Accept header, indicating that you want the response in PagerDuty API v2 JSON format. This is critical for ensuring compatibility with the current API version.
• -H "Authorization: Token token=YOUR_API_KEY": Provides your API key for authentication. The format is Token token= followed by your key.
• "https://api.pagerduty.com/services": The endpoint URL for retrieving a list of services.

A successful response will return a JSON object containing an array of service objects configured in your PagerDuty account. Each service object will include details such as its ID, name, status, and associated escalation policy. If you receive an error, double-check your API key and ensure it has the necessary permissions.

Common next steps

After successfully making your first API call, you can explore more advanced integrations and functionalities. Here are some common next steps:

1. Explore other endpoints: Refer to the PagerDuty API Reference to discover other available endpoints. You might want to interact with incidents (create, acknowledge, resolve), users, teams, or schedules.
2. Use an SDK: While cURL is useful for quick tests, using one of the official PagerDuty SDKs (Python, Ruby, Go, Java, Node.js) can streamline development by handling authentication, request formatting, and response parsing. Each SDK has its own getting started guide.
3. Automate incident creation: A common use case is to integrate monitoring tools or custom scripts to automatically create incidents in PagerDuty when specific conditions are met. This typically involves making a POST request to the /incidents endpoint.
4. Manage on-call schedules: The API allows for programmatic management of on-call schedules, including adding or removing users, updating rotations, and fetching current on-call personnel.
5. Webhooks for real-time updates: For real-time integration, consider setting up PagerDuty webhooks. Webhooks allow PagerDuty to send automated HTTP POST requests to a specified URL whenever an event occurs (e.g., an incident is triggered or resolved). This push-based mechanism is more efficient than polling the API for changes. More information on webhooks can be found in the Mozilla Developer Network's webhook guide.
6. Implement robust error handling: As you build out your integration, implement comprehensive error handling to gracefully manage API rate limits, authentication failures, and other potential issues.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips for the PagerDuty API:

• Invalid API Key: The most frequent issue is an incorrect or expired API key. Double-check that your YOUR_API_KEY placeholder was replaced correctly and that no extra spaces or characters were introduced. Ensure the key is active and has the necessary permissions. If you suspect the key is compromised or invalid, generate a new one from the PagerDuty web app.
• Incorrect Authorization Header: Verify the format of your Authorization header. It must be Token token=YOUR_API_KEY. A common mistake is missing the Token token= prefix or using the wrong casing.
• Missing Accept Header: The Accept: application/vnd.pagerduty+json;version=2 header is crucial for specifying the API version and response format. Omitting or incorrectly formatting this header can lead to unexpected responses or errors.
• Network Issues: Ensure your network connection is stable and that there are no firewalls or proxies blocking your request to https://api.pagerduty.com.
• Rate Limiting: While unlikely on your very first call, repeated failed attempts or rapid successive calls can trigger PagerDuty API rate limits. The API will respond with a 429 Too Many Requests status code if you hit a rate limit. Implement exponential backoff for retries in production environments.
• Endpoint Typos: Verify the URL for the endpoint. Even a small typo, like /service instead of /services, will result in a 404 Not Found error. Refer to the PagerDuty API reference documentation for exact endpoint paths.
• Check PagerDuty Status Page: In rare cases, PagerDuty services might be experiencing an outage or degraded performance. Check the PagerDuty Status Page to rule out platform-wide issues.
• API Key Permissions: If you're trying to perform a write operation (e.g., create an incident) with a read-only API key, the API will return a permission error. Ensure your API key has the appropriate scope for the operations you intend to perform.