Overview

The PagerDuty connector integrates with the PagerDuty REST API v2 for end-to-end incident response automation. It supports 45 operations across 10 API families: Incidents, Alerts, Services, Escalation Policies, Schedules, Users, Teams, Maintenance Windows, Event Rules, and Analytics.

All operations are policy-evaluated and audit-logged through the ARX BaseConnector.execute() pipeline before reaching the PagerDuty API. Write operations require a From header with the requester's email address, which can be provided via vault credentials or per-request parameters.

Connector class: PagerDutyConnector Module: app.connectors.pagerduty

Prerequisites

Requirement Details
PagerDuty account An active PagerDuty account with API access
API key A REST API key generated from Integrations > API Access Keys in the PagerDuty console
Requester email Email of the user performing write operations (required by PagerDuty's From header)
Vault path Store credentials as api_key and requester_email in the ARX vault

Required Vault Credentials

{
  "api_key": "u+abcdefghijklmnop",
  "requester_email": "bot@yourorg.com"
}

SDK Usage

from app.connectors.pagerduty import PagerDutyConnector

pd = PagerDutyConnector(agent_id="agent-001", org_id="org-acme")

# List triggered incidents
incidents = await pd.list_incidents(
    statuses=["triggered", "acknowledged"],
    urgencies=["high"],
)

# Create a new incident
await pd.create_incident(
    title="Critical: Database replication lag > 30s",
    service_id="PABC123",
    urgency="high",
    body="Automated detection by ARX monitoring agent.",
)

# Acknowledge and add a note
await pd.acknowledge_incident("P1234AB")
await pd.add_incident_note("P1234AB", "Investigating -- automated triage in progress")

# Query on-call schedules
oncall = await pd.get_oncall_users()

# Get incident analytics
analytics = await pd.get_incident_analytics(since="2025-01-01T00:00:00Z")

# Create a maintenance window (HIGH risk -- silences alerts)
await pd.create_maintenance_window(
    start_time="2025-06-15T02:00:00Z",
    end_time="2025-06-15T04:00:00Z",
    service_ids=["PABC123"],
    description="Scheduled database maintenance",
)

Operations

Incidents (14 operations)

Operation Method Path Risk Description
incidents:read GET /incidents LOW List and query incidents with filters
incidents:read_detail GET /incidents/{incident_id} LOW Get full incident details by ID
incidents:create POST /incidents MEDIUM Create a new incident
incidents:update PUT /incidents/{incident_id} MEDIUM Update incident fields (status, urgency, etc.)
incidents:manage PUT /incidents MEDIUM Bulk manage incidents (acknowledge, resolve, merge)
incidents:snooze POST /incidents/{incident_id}/snooze LOW Snooze an incident for a duration
incidents:merge PUT /incidents/{incident_id}/merge MEDIUM Merge other incidents into this one
incidents:read_alerts GET /incidents/{incident_id}/alerts LOW Get alerts associated with an incident
incidents:read_log GET /incidents/{incident_id}/log_entries LOW Get log entries (timeline) for an incident
incidents:read_notes GET /incidents/{incident_id}/notes LOW Get notes on an incident
incidents:add_note POST /incidents/{incident_id}/notes LOW Add a note to an incident
incidents:reassign PUT /incidents/{incident_id} MEDIUM Reassign an incident to different user(s)
incidents:resolve PUT /incidents/{incident_id} MEDIUM Resolve an incident (set status=resolved)
incidents:acknowledge PUT /incidents/{incident_id} LOW Acknowledge an incident (set status=acknowledged)

Alerts (2 operations)

Operation Method Path Risk Description
alerts:read GET /incidents/{incident_id}/alerts LOW Get alerts for an incident
alerts:update PUT /incidents/{incident_id}/alerts/{alert_id} MEDIUM Update an alert (resolve, suppress, etc.)

Services (7 operations)

Operation Method Path Risk Description
services:read GET /services LOW List all services
services:read_detail GET /services/{service_id} LOW Get service details by ID
services:create POST /services HIGH Create a new service
services:update PUT /services/{service_id} MEDIUM Update an existing service
services:delete DELETE /services/{service_id} HIGH Delete a service permanently
services:read_integrations GET /services/{service_id}/integrations LOW List integrations for a service
services:create_integration POST /services/{service_id}/integrations MEDIUM Create a new integration on a service

Escalation Policies (5 operations)

Operation Method Path Risk Description
escalation:read GET /escalation_policies LOW List escalation policies
escalation:read_detail GET /escalation_policies/{policy_id} LOW Get escalation policy details
escalation:create POST /escalation_policies MEDIUM Create a new escalation policy
escalation:update PUT /escalation_policies/{policy_id} MEDIUM Update an existing escalation policy
escalation:delete DELETE /escalation_policies/{policy_id} HIGH Delete an escalation policy

Schedules (3 operations)

Operation Method Path Risk Description
schedules:read GET /schedules LOW List on-call schedules
schedules:read_detail GET /schedules/{schedule_id} LOW Get schedule details
schedules:read_oncall GET /oncalls LOW Query currently on-call users

Users (4 operations)

Operation Method Path Risk Description
users:read GET /users LOW List all users
users:read_detail GET /users/{user_id} LOW Get user details by ID
users:read_contact GET /users/{user_id}/contact_methods LOW Get contact methods for a user
users:read_notification GET /users/{user_id}/notification_rules LOW Get notification rules for a user

Teams (2 operations)

Operation Method Path Risk Description
teams:read GET /teams LOW List all teams
teams:read_detail GET /teams/{team_id} LOW Get team details by ID

Maintenance Windows (3 operations)

Operation Method Path Risk Description
maintenance:read GET /maintenance_windows LOW List maintenance windows
maintenance:create POST /maintenance_windows HIGH Create maintenance window (silences alerts for services)
maintenance:delete DELETE /maintenance_windows/{window_id} MEDIUM Delete (end) a maintenance window

Event Rules (3 operations)

Operation Method Path Risk Description
rules:read GET /event_rules LOW List global event rules
rules:create POST /event_rules MEDIUM Create a global event rule
rules:update PUT /event_rules/{rule_id} MEDIUM Update a global event rule

Analytics (2 operations)

Operation Method Path Risk Description
analytics:read POST /analytics/metrics/incidents/all LOW Get aggregate incident analytics metrics
analytics:services POST /analytics/metrics/incidents/services LOW Get per-service incident analytics metrics

Risk Classifications

Level Operations Rationale
LOW All read operations, acknowledge, snooze, notes, analytics No destructive state changes; safe for autonomous execution
MEDIUM Create/update incidents, escalation policies, event rules, service integrations, alert updates, maintenance window deletion, incident management (bulk), merge, reassign, resolve Modifies state but is generally reversible or scoped
HIGH services:create, services:delete, maintenance:create, escalation:delete Creates/removes core infrastructure (services, escalation chains) or silences alerting; may cause incident response gaps

Policy Examples

Incident responder -- manage incidents but not infrastructure

- name: pd-incident-responder
  connector: pagerduty
  operations:
    - "incidents:*"
    - "alerts:*"
    - "schedules:read*"
    - "users:read*"
    - "teams:read*"
    - "services:read*"
    - "escalation:read*"
    - "analytics:*"
  risk_max: medium
  approval: none

Read-only on-call dashboard

- name: pd-oncall-readonly
  connector: pagerduty
  operations:
    - "incidents:read*"
    - "alerts:read"
    - "services:read*"
    - "escalation:read*"
    - "schedules:read*"
    - "users:read*"
    - "teams:read*"
    - "maintenance:read"
    - "rules:read"
    - "analytics:*"
  risk_max: low
  approval: none

Full PagerDuty management with approval for HIGH actions

- name: pd-full-admin
  connector: pagerduty
  operations:
    - "incidents:*"
    - "alerts:*"
    - "services:*"
    - "escalation:*"
    - "schedules:*"
    - "users:*"
    - "teams:*"
    - "maintenance:*"
    - "rules:*"
    - "analytics:*"
  risk_max: high
  approval:
    medium: auto
    high: hitl
  hitl_channel: "#pd-admin-approvals"

Block maintenance window creation (prevent alert silencing)

- name: pd-no-maintenance
  connector: pagerduty
  deny:
    - "maintenance:create"
  description: "Prevents agents from silencing alerts via maintenance windows"