PagerDuty API Essential Guide

What type of API does PagerDuty provide?

PagerDuty primarily uses a REST API. The key points are:

PagerDuty's API Type

• PagerDuty offers a REST API that allows third parties to interact with configuration data in accounts.
• The REST API is available to customers on current pricing plans, though not available to some on legacy plans.

Key Features of PagerDuty's REST API

• It allows interaction with configuration data in PagerDuty accounts.
• PagerDuty enforces rate limits on the REST API to ensure fair access to resources.
• The API requires API access keys for authentication.

Other APIs Offered by PagerDuty

• In addition to the REST API, PagerDuty also offers an Events API.
• The Events API allows adding PagerDuty's event and incident management functionality to any system that can make outbound HTTP connections.

Best Practices

• When using the PagerDuty API, it's important to be aware of and respect the rate limits.
• Proper use of API access keys is crucial for security and authentication.

Does the PagerDuty API have webhooks?

Yes, the official PagerDuty API does have webhooks. Here are the key points about PagerDuty's webhook functionality:

Webhook Support

• PagerDuty offers webhook functionality through their V3 webhook subscriptions.

• Webhooks allow you to receive HTTP callbacks when significant events happen in your PagerDuty account.

Event Types

You can subscribe to the following types of events for incidents:

• triggered
• acknowledged
• unacknowledged
• resolved
• assigned
• escalated
• delegated
• annotated
• priority_updated
• reassigned
• reopened
• responder.added
• responder.replied
• status_update_published
• conference_bridge.updated
• custom_field_values.updated
• workflow.completed
• workflow.started

For services, you can subscribe to:

• created
• deleted
• updated

Key Points

• V3 webhooks offer more event types compared to previous versions.

• You can create up to 10 webhook subscriptions per unique service and Team ID.

• Webhooks can be managed via the PagerDuty web interface or API.

• Custom headers can be added to webhook subscriptions.

• PagerDuty provides a way to test webhook configurations by sending a test event.

Best Practices

• When migrating from older webhook versions, subscribe to all event types to receive the same data as before.

• Use the provided migration guide or script when upgrading from V1/V2 webhooks to V3.

• Verify webhook payloads using the provided secret for security.

• Consider safelisting PagerDuty's IP addresses for webhook traffic.

In summary, PagerDuty's API offers robust webhook functionality with a wide range of event types to subscribe to, allowing for real-time notifications of important incidents and service changes.

Rate Limits and other limitations

Here are the key points about the API Rate Limits of the PagerDuty API:

1. PagerDuty has implemented rate limits on their REST API to ensure resource availability and protect against fraudulent activity [3].

2. Key recommendations for working with the rate limits include:

   • Make use of rate limit headers: Parse the ratelimit-remaining and ratelimit-reset response headers to manage your API usage [3].

   • Use separate "bot users" for different application deployments to keep rate limits separate [3].

   • Use the latest Terraform PagerDuty provider version (v3.2.2 or later) for improved API retry logic [3].

3. The new rate limiting headers became active in October/November 2023. Applications can expect to see 429 responses when limits are reached [3].

4. To prepare for rate limits:

   • PagerDuty introduced new rate limiting headers on HTTP responses before fully implementing the limits [3].

   • For a period, 429 responses were not sent when limits were reached, allowing time for applications to adjust [3].

   • Mission-critical applications should incorporate these headers to minimize potential disruptions [3].

5. If experiencing throttling due to rate limits:

   • Consider adding more users and spreading out the API request load if using user API keys [3].

   • Register one scoped OAuth app per environment (e.g., staging, production) and use appropriate app tokens [3].

   • Consider registering a private scoped OAuth app in addition to using a user token to effectively double your API rate limit [3].

6. In most cases, applications should experience similar or more generous rate limits than before, but there may be exceptions depending on how the REST API is used [3].

7. The specific rate limit numbers are not provided in the given information. Developers should monitor the rate limit headers in API responses to understand their current limits and usage.

Latest API Version

Based on the search results provided, I do not have specific information about the most recent version of the PagerDuty API. The search results contain platform release notes and other general information about PagerDuty, but do not mention API versions. Without more specific information about the PagerDuty API versioning, I cannot provide a definitive answer about the most recent version.

Key points to consider:

• PagerDuty regularly updates its platform and services, as evidenced by the detailed release notes for different months in 2024.

• The company provides API documentation and developer resources, including an APIs Overview section.

• PagerDuty uses REST APIs, as mentioned in the "REST API Rate Limits" section.

To find the most up-to-date information about the PagerDuty API version:

1. Check the official PagerDuty API documentation or developer portal.
2. Look for any "API Changelog" or "API Version History" pages.
3. Contact PagerDuty support directly for the most accurate and current information.

Best practices:

• Always refer to the official documentation for the most recent API information.
• Subscribe to PagerDuty's developer newsletter or follow their developer blog for updates.
• When integrating with the API, use the latest stable version recommended by PagerDuty.

How to get a PagerDuty developer account and API Keys?

To get a developer account for PagerDuty and create an API integration, you can follow these steps:

Create a PagerDuty Account

1. Sign up for a PagerDuty account if you don't already have one. You can start with a free trial.

2. Once you have an account, log in to the PagerDuty web application.

Generate an API Key

1. Navigate to the "Integrations" section, then select "API Access Keys" under "Developer Tools".

2. Click on "Create New API Key" to generate a new API key.

3. Optionally, you can check the "Read-only API Key" box if you only need to make GET calls.

4. Store the generated API key securely, as it will only be displayed in full once.

Key Points to Consider

• API keys for the REST API are 20-character strings.
• There are two types of REST API keys: General Access and User Token.
• The REST API is available to all customers on current pricing plans, but may not be available on some legacy plans.
• Rate limits apply to ensure fair access to API resources.

Best Practices

• Store your API key securely, as it cannot be recovered if lost.
• Use appropriate permissions: Admins and Account Owners can create, disable, enable, and delete general access REST API keys.
• Consider using scoped tokens for more granular control over access.
• Be aware of and respect the API rate limits.

By following these steps and considering the key points, you should be able to set up a developer account and create an API integration with PagerDuty.

What can you do with the PagerDuty API?

Based on my knowledge of the PagerDuty API, here's a list of data models you can interact with and what's possible for each:

Incidents

• Create new incidents
• List and search incidents
• Update incident details
• Resolve or escalate incidents
• Add notes to incidents
• Assign and reassign incidents

Users

• Create, update, and delete users
• List and search users
• Get user contact methods
• Manage user notification rules

Services

• Create, update, and delete services
• List and search services
• Manage service integrations
• Configure service-specific settings

Schedules

• Create, update, and delete schedules
• List and search schedules
• Manage schedule layers and rotations
• Get schedule overrides

Escalation Policies

• Create, update, and delete escalation policies
• List and search escalation policies
• Manage escalation rules and targets

Teams

• Create, update, and delete teams
• List and search teams
• Manage team members
• Associate teams with other resources (e.g., services, schedules)

Alerts

• List and search alerts
• Update alert status
• Get alert details

Log Entries

• List and search log entries
• Get log entry details

Maintenance Windows

• Create, update, and delete maintenance windows
• List and search maintenance windows
• Get maintenance window details

Vendors

• List and search vendors
• Get vendor details

Extensions (Add-ons)

• Install and uninstall extensions
• List and search installed extensions
• Update extension configurations

Event Rules

• Create, update, and delete event rules
• List and search event rules
• Manage rule actions and conditions

Business Services

• Create, update, and delete business services
• List and search business services
• Manage service dependencies and impact

Response Plays

• Create, update, and delete response plays
• List and search response plays
• Run response plays on incidents

Analytics

• Retrieve various analytics data (e.g., incident frequency, resolution time)
• Generate custom reports

Please note that the exact capabilities for each data model may vary depending on the specific version of the PagerDuty API you're using. It's always a good idea to consult the official PagerDuty API documentation for the most up-to-date and detailed information on available endpoints and operations.