Pagerduty

Creates a new webhook subscription in pagerduty to receive specific event notifications. this endpoint allows users to set up automated notifications for various incident-related events, such as triggers, acknowledgments, and resolutions. the webhook can be configured to filter events by service, team, or account-wide, and supports custom http headers for enhanced integration capabilities. use this when you need to integrate pagerduty's real-time incident updates with external systems or workflows. note that the webhook's secret for payload verification is only provided in the initial creation response and cannot be retrieved later.

Retrieves a list of escalation policies configured in the pagerduty account. this endpoint allows users to access detailed information about how incidents are escalated within their organization, including the sequence of notifications and assignments for different teams or individuals. it's particularly useful for reviewing and auditing the incident response process, ensuring that critical alerts are properly routed and escalated. the endpoint provides a comprehensive view of all escalation policies, which is essential for maintaining an effective incident management strategy. however, it does not modify any existing policies or create new ones; it's purely for retrieval and review purposes.

Retrieves a list of incidents from pagerduty based on specified criteria. this endpoint allows users to fetch multiple incidents, making it useful for incident management, reporting, and analysis. it supports filtering by status and date range, as well as pagination for handling large result sets. the endpoint is particularly valuable for obtaining an overview of recent or ongoing incidents, tracking incident trends, or integrating pagerduty incident data into external systems or dashboards. note that while this endpoint provides a summary of incidents, it may not include full details for each incident; separate api calls might be necessary to fetch comprehensive information for individual incidents.

Retrieves all alerts associated with a specific incident in pagerduty. this endpoint allows users to fetch detailed information about the notifications and alerts that were triggered as part of an incident's lifecycle. it is particularly useful for incident postmortems, auditing purposes, or understanding the notification flow during an incident. the endpoint returns a list of alerts, which may include information such as alert creation time, alert status, and the targets (users or services) that received the notifications. it should be used when detailed alert information for a known incident is required, but it will not provide information about the incident itself beyond its associated alerts.

Retrieves a list of services configured in the pagerduty account. this endpoint allows you to fetch details about various services set up for incident management and alerting. it's particularly useful for getting an overview of all services, their configurations, and associated teams or escalation policies. the endpoint supports filtering, sorting, and pagination to manage large sets of services efficiently. use this when you need to audit existing services, prepare for bulk updates, or integrate service information into other systems. note that the response may not include full details of each service, and separate api calls might be necessary to fetch comprehensive information for individual services.

Retrieves a list of maintenance windows from the pagerduty incident management platform. maintenance windows are scheduled periods during which alerts and notifications for specified services are suppressed to allow for system maintenance or updates without triggering unnecessary incidents. this endpoint should be used to get an overview of all maintenance windows, their schedules, and affected services. it supports filtering by team, service, and search query, as well as pagination for handling large result sets. the endpoint is particularly useful for reviewing upcoming maintenance schedules, auditing past maintenance windows, or integrating maintenance information into external systems or dashboards.

Retrieves a list of users from the pagerduty system. this endpoint allows you to fetch information about multiple users in your pagerduty account, which can be useful for user management, generating reports, or integrating user data with other systems. the response typically includes basic information about each user, such as their id, name, email, and role. use query parameters to filter, paginate, or search for specific users. this endpoint is ideal for bulk operations or when you need an overview of your pagerduty user base. note that the results may be paginated, so multiple calls might be necessary to retrieve all users for large accounts.

Updates an existing service in pagerduty with the provided configuration. this endpoint allows you to modify various aspects of a service, such as its name, description, escalation policy, incident urgency rules, and alert grouping settings. use this when you need to change the behavior or properties of an existing service. the endpoint requires the service id and accepts a 'service' object containing the updated configuration. note that some properties (like 'id' and 'created at') are read-only and cannot be modified. certain advanced features, such as alert grouping and auto-pause notifications, may only be available on specific pagerduty plans.

This endpoint adds a service to an existing incident workflow trigger in pagerduty. it allows you to associate a specific service with a trigger, enabling automated incident management processes for that service. use this endpoint when you need to connect a service to an incident workflow, typically during the setup or modification of your incident response procedures. the endpoint requires the trigger's id and the service's id to make the association. it's important to note that this operation doesn't create new services or triggers, but rather links existing ones. ensure that both the trigger and service exist in your pagerduty account before making this call.

This endpoint analyzes and aggregates incident metrics across all escalation policies in pagerduty. it allows for detailed filtering and customization of the analysis, enabling users to gain insights into incident patterns, response times, and escalation effectiveness. the endpoint is particularly useful for operational reviews, performance analysis, and identifying areas for improvement in incident management processes. it provides flexibility in data selection through various filters and supports different time-based aggregations for comprehensive reporting.

Retrieves and aggregates metrics for incidents across all services in pagerduty. this endpoint allows for extensive filtering and customization of incident data, enabling detailed analysis of operational performance. it's particularly useful for generating reports, identifying trends, and assessing incident management efficiency over specified time periods. the endpoint supports various filtering criteria, time zone adjustments, and aggregation options, making it a powerful tool for both high-level overviews and granular incident analytics. however, users should be aware of the complexity of the filtering options and ensure they provide accurate parameters to obtain relevant data.

Associates multiple service dependencies in pagerduty, allowing you to define relationships between supporting and dependent services. this endpoint is used to establish a hierarchical structure of services, which is crucial for effective incident management and impact analysis. it enables you to create multiple dependencies in a single api call, improving efficiency when setting up complex service relationships. use this endpoint when you need to define or update the dependency structure of your services in pagerduty, such as during initial setup, service restructuring, or when adding new services to your incident management workflow.

This endpoint associates a specific team with an automation action in pagerduty. it allows you to link a team to an automated workflow, enabling better organization and management of automation actions within your incident response processes. use this endpoint when you need to assign responsibility for an automation action to a particular team or when restructuring your automation workflows. the association helps in tracking, auditing, and managing permissions for automation actions across different teams in your organization. note that this endpoint only creates the association; it does not create new teams or automation actions.

Retrieves the audit records for a specific escalation policy in pagerduty. this endpoint allows users to access a detailed history of changes made to the escalation policy, including modifications to escalation rules, associated services, and on-call schedules. it's particularly useful for compliance tracking, troubleshooting, and understanding how the incident response process has been adjusted over time. the audit records provide transparency into who made changes, what was changed, and when the changes occurred, helping teams maintain accountability and optimize their incident management workflows.

Converts the rules associated with a specific pagerduty service to a new or optimized format. this endpoint is used to update and standardize the incident management rules for a given service, improving the efficiency and consistency of alert handling. it should be used when there's a need to modernize rule sets, apply best practices, or adapt rules to changing service requirements. the conversion process is applied to all rules linked to the specified service id, potentially modifying their structure or behavior. it's important to note that this operation may impact existing incident routing and alerting patterns, so it should be used cautiously and preferably during a maintenance window.

Retrieves the count of paused incident reports in the pagerduty system. this endpoint is part of pagerduty's incident management and analytics features, providing a quick way to quantify the number of incidents that are currently in a paused state. it's particularly useful for generating high-level analytics, tracking incident management efficiency, and identifying trends in incident handling. the endpoint returns a simple count, making it ideal for dashboard displays or periodic system status checks. it should be used when a rapid overview of paused incidents is needed, but it won't provide detailed information about individual incidents.

Creates a new custom field for incidents in pagerduty. this endpoint allows you to define additional data points to be associated with incidents, enhancing incident management and reporting capabilities. custom fields can be used to store various types of information such as environment, severity, or any other relevant metadata. the field can be configured with different data types and value constraints, allowing for flexible and structured data capture. use this endpoint when you need to extend the incident data model with organization-specific information. note that once created, certain properties of a custom field cannot be changed, so careful planning of field structure is important.

Create a new incident type. incident types are a feature which will allow customers to categorize incidents, such as a security incident, a major incident, or a fraud incident. <!-- theme: warning --> > ### early access > this endpoint is in early access and may change at any time. you must pass in the x-early-access header to access it. for more information see the [api concepts document](../../api-reference/zg9joji3ndc5nzc-api-concepts#incidenttype) scoped oauth requires: `incident types.write`

Creates a new automation runner in the pagerduty incident management system. this endpoint allows you to set up either a sidecar runner, which polls for invocations externally, or a runbook runner, which communicates directly with a runbook instance. use this when you need to automate actions within pagerduty, such as incident response processes or scheduled tasks. the runner can be associated with specific teams for better organization and access control. note that the required parameters differ based on the chosen runner type, with runbook runners requiring additional configuration for server connection.

Create a custom field for an incident type. custom fields (cf) are a feature which will allow customers to extend incidents with their own custom data, to provide additional context and support features such as customized filtering, search and analytics. custom fields can be applied to different incident types. <!-- theme: warning --> > ### early access > this endpoint is in early access and may change at any time. you must pass in the x-early-access header to access it. scoped oauth requires: `custom fields.write`