PagerDuty Helper Agent

Overview

Complete PagerDuty operations via REST API. This skill replaces PagerDuty MCP server functionality, providing API equivalents for all operations.

MCP Tool Equivalents Reference

MCP Tool	API Equivalent
list_incidents	curl "$API/incidents"
get_incident	curl "$API/incidents/{id}"
get_outlier_incident	curl "$API/incidents/{id}/outlier_incident"
get_past_incidents	curl "$API/incidents/{id}/past_incidents"
get_related_incidents	curl "$API/incidents/{id}/related_incidents"
list_incident_notes	curl "$API/incidents/{id}/notes"
list_incident_workflows	curl "$API/incident_workflows"
get_incident_workflow	curl "$API/incident_workflows/{id}"
list_services	curl "$API/services"
get_service	curl "$API/services/{id}"
list_teams	curl "$API/teams"
get_team	curl "$API/teams/{id}"
list_team_members	curl "$API/teams/{id}/members"
list_users	curl "$API/users"
get_user_data	curl "$API/users/me"
list_schedules	curl "$API/schedules"
get_schedule	curl "$API/schedules/{id}"
list_schedule_users	curl "$API/schedules/{id}/users"
list_oncalls	curl "$API/oncalls"
list_escalation_policies	curl "$API/escalation_policies"
get_escalation_policy	curl "$API/escalation_policies/{id}"
list_event_orchestrations	curl "$API/event_orchestrations"
get_event_orchestration	curl "$API/event_orchestrations/{id}"
get_event_orchestration_router	curl "$API/event_orchestrations/{id}/router"
get_event_orchestration_service	curl "$API/event_orchestrations/services/{service_id}"
get_event_orchestration_global	curl "$API/event_orchestrations/{id}/global"
list_alert_grouping_settings	curl "$API/alert_grouping_settings"
get_alert_grouping_setting	curl "$API/alert_grouping_settings/{id}"
list_change_events	curl "$API/change_events"
get_change_event	curl "$API/change_events/{id}"
list_service_change_events	curl "$API/services/{id}/change_events"
list_incident_change_events	curl "$API/incidents/{id}/related_change_events"
list_status_pages	curl "$API/status_pages"
list_status_page_severities	curl "$API/status_pages/{id}/severities"
list_status_page_impacts	curl "$API/status_pages/{id}/impacts"
list_status_page_statuses	curl "$API/status_pages/{id}/statuses"
get_status_page_post	curl "$API/status_pages/{id}/posts/{post_id}"
list_status_page_post_updates	curl "$API/status_pages/{id}/posts/{post_id}/post_updates"

Configuration

# Set environment variables
export PAGERDUTY_TOKEN="your-api-token"
export API="https://api.pagerduty.com"

# Standard headers
AUTH="Authorization: Token token=$PAGERDUTY_TOKEN"
ACCEPT="Accept: application/vnd.pagerduty+json;version=2"
CONTENT="Content-Type: application/json"

# Test connection
curl -H "$AUTH" -H "$ACCEPT" "$API/users/me"

---

Incident Operations

List Incidents

# All incidents
curl -H "$AUTH" -H "$ACCEPT" "$API/incidents"

# Filter by status
curl -H "$AUTH" -H "$ACCEPT" \
  "$API/incidents?statuses[]=triggered&statuses[]=acknowledged"

# Filter by service
curl -H "$AUTH" -H "$ACCEPT" "$API/incidents?service_ids[]=$SERVICE_ID"

# Filter by team
curl -H "$AUTH" -H "$ACCEPT" "$API/incidents?team_ids[]=$TEAM_ID"

# Filter by date range
curl -H "$AUTH" -H "$ACCEPT" \
  "$API/incidents?since=2024-01-01T00:00:00Z&until=2024-01-31T23:59:59Z"

# Filter by urgency
curl -H "$AUTH" -H "$ACCEPT" "$API/incidents?urgencies[]=high"

# Sort and limit
curl -H "$AUTH" -H "$ACCEPT" \
  "$API/incidents?sort_by=created_at:desc&limit=10"

# JSON output
curl -H "$AUTH" -H "$ACCEPT" "$API/incidents" | \
  jq '.incidents[] | {id, title, status, urgency, created_at}'

Get Incident Details

curl -H "$AUTH" -H "$ACCEPT" "$API/incidents/$INCIDENT_ID"

# With additional info
curl -H "$AUTH" -H "$ACCEPT" \
  "$API/incidents/$INCIDENT_ID?include[]=acknowledgers&include[]=assignees"

Get Outlier Incident

# Get outlier analysis for an incident
curl -H "$AUTH" -H "$ACCEPT" \
  "$API/incidents/$INCIDENT_ID/outlier_incident"

# With time range
curl -H "$AUTH" -H "$ACCEPT" \
  "$API/incidents/$INCIDENT_ID/outlier_incident?since=2024-01-01T00:00:00Z"

Get Past Incidents

# Get similar past incidents
curl -H "$AUTH" -H "$ACCEPT" "$API/incidents/$INCIDENT_ID/past_incidents"

# With limit
curl -H "$AUTH" -H "$ACCEPT" \
  "$API/incidents/$INCIDENT_ID/past_incidents?limit=5"

Get Related Incidents

curl -H "$AUTH" -H "$ACCEPT" "$API/incidents/$INCIDENT_ID/related_incidents"

# With additional details
curl -H "$AUTH" -H "$ACCEPT" \
  "$API/incidents/$INCIDENT_ID/related_incidents?additional_details[]=incident"

List Incident Notes

curl -H "$AUTH" -H "$ACCEPT" "$API/incidents/$INCIDENT_ID/notes"

# Add a note
curl -X POST -H "$AUTH" -H "$ACCEPT" -H "$CONTENT" \
  -H "From: user@example.com" \
  "$API/incidents/$INCIDENT_ID/notes" \
  -d '{
    "note": {
      "content": "Investigation update: found the root cause"
    }
  }'

Acknowledge/Resolve Incident

# Acknowledge
curl -X PUT -H "$AUTH" -H "$ACCEPT" -H "$CONTENT" \
  -H "From: user@example.com" \
  "$API/incidents/$INCIDENT_ID" \
  -d '{
    "incident": {
      "type": "incident_reference",
      "status": "acknowledged"
    }
  }'

# Resolve
curl -X PUT -H "$AUTH" -H "$ACCEPT" -H "$CONTENT" \
  -H "From: user@example.com" \
  "$API/incidents/$INCIDENT_ID" \
  -d '{
    "incident": {
      "type": "incident_reference",
      "status": "resolved"
    }
  }'

---

Service Operations

List Services

# All services
curl -H "$AUTH" -H "$ACCEPT" "$API/services"

# Search by name
curl -H "$AUTH" -H "$ACCEPT" "$API/services?query=production"

# Filter by team
curl -H "$AUTH" -H "$ACCEPT" "$API/services?team_ids[]=$TEAM_ID"

# Include integrations
curl -H "$AUTH" -H "$ACCEPT" \
  "$API/services?include[]=integrations&include[]=escalation_policies"

# JSON output
curl -H "$AUTH" -H "$ACCEPT" "$API/services" | \
  jq '.services[] | {id, name, status, description}'

Get Service Details

curl -H "$AUTH" -H "$ACCEPT" "$API/services/$SERVICE_ID"

# With integrations
curl -H "$AUTH" -H "$ACCEPT" \
  "$API/services/$SERVICE_ID?include[]=integrations"

List Service Change Events

curl -H "$AUTH" -H "$ACCEPT" "$API/services/$SERVICE_ID/change_events"

# With time range
curl -H "$AUTH" -H "$ACCEPT" \
  "$API/services/$SERVICE_ID/change_events?since=2024-01-01T00:00:00Z"

---

Team Operations

List Teams

# All teams
curl -H "$AUTH" -H "$ACCEPT" "$API/teams"

# Search by name
curl -H "$AUTH" -H "$ACCEPT" "$API/teams?query=platform"

# JSON output
curl -H "$AUTH" -H "$ACCEPT" "$API/teams" | \
  jq '.teams[] | {id, name, description}'

Get Team Details

curl -H "$AUTH" -H "$ACCEPT" "$API/teams/$TEAM_ID"

List Team Members

curl -H "$AUTH" -H "$ACCEPT" "$API/teams/$TEAM_ID/members"

# JSON output
curl -H "$AUTH" -H "$ACCEPT" "$API/teams/$TEAM_ID/members" | \
  jq '.members[] | {user: .user.summary, role: .role}'

---

User Operations

List Users

# All users
curl -H "$AUTH" -H "$ACCEPT" "$API/users"

# Search by name/email
curl -H "$AUTH" -H "$ACCEPT" "$API/users?query=john"

# Filter by team
curl -H "$AUTH" -H "$ACCEPT" "$API/users?team_ids[]=$TEAM_ID"

# JSON output
curl -H "$AUTH" -H "$ACCEPT" "$API/users" | \
  jq '.users[] | {id, name, email, role}'

Get Current User

curl -H "$AUTH" -H "$ACCEPT" "$API/users/me"

# With contact methods
curl -H "$AUTH" -H "$ACCEPT" \
  "$API/users/me?include[]=contact_methods&include[]=notification_rules"

---

Schedule Operations

List Schedules

# All schedules
curl -H "$AUTH" -H "$ACCEPT" "$API/schedules"

# Search by name
curl -H "$AUTH" -H "$ACCEPT" "$API/schedules?query=primary"

# Include schedule layers
curl -H "$AUTH" -H "$ACCEPT" "$API/schedules?include[]=schedule_layers"

# JSON output
curl -H "$AUTH" -H "$ACCEPT" "$API/schedules" | \
  jq '.schedules[] | {id, name, time_zone}'

Get Schedule Details

curl -H "$AUTH" -H "$ACCEPT" "$API/schedules/$SCHEDULE_ID"

# For specific time range
curl -H "$AUTH" -H "$ACCEPT" \
  "$API/schedules/$SCHEDULE_ID?since=2024-01-01&until=2024-01-07"

List Schedule Users

curl -H "$AUTH" -H "$ACCEPT" "$API/schedules/$SCHEDULE_ID/users"

# For specific time range
curl -H "$AUTH" -H "$ACCEPT" \
  "$API/schedules/$SCHEDULE_ID/users?since=2024-01-01&until=2024-01-07"

---

On-Call Operations

List On-Calls

# Current on-call
curl -H "$AUTH" -H "$ACCEPT" "$API/oncalls"

# Filter by schedule
curl -H "$AUTH" -H "$ACCEPT" "$API/oncalls?schedule_ids[]=$SCHEDULE_ID"

# Filter by escalation policy
curl -H "$AUTH" -H "$ACCEPT" \
  "$API/oncalls?escalation_policy_ids[]=$POLICY_ID"

# Filter by user
curl -H "$AUTH" -H "$ACCEPT" "$API/oncalls?user_ids[]=$USER_ID"

# Only earliest on-call per combination
curl -H "$AUTH" -H "$ACCEPT" "$API/oncalls?earliest=true"

# With time range
curl -H "$AUTH" -H "$ACCEPT" \
  "$API/oncalls?since=2024-01-01T00:00:00Z&until=2024-01-07T00:00:00Z"

# JSON output
curl -H "$AUTH" -H "$ACCEPT" "$API/oncalls" | \
  jq '.oncalls[] | {
    user: .user.summary,
    schedule: .schedule.summary,
    escalation_policy: .escalation_policy.summary,
    level: .escalation_level,
    start: .start,
    end: .end
  }'

---

Escalation Policy Operations

List Escalation Policies

# All policies
curl -H "$AUTH" -H "$ACCEPT" "$API/escalation_policies"

# Search by name
curl -H "$AUTH" -H "$ACCEPT" "$API/escalation_policies?query=engineering"

# Filter by team
curl -H "$AUTH" -H "$ACCEPT" "$API/escalation_policies?team_ids[]=$TEAM_ID"

# Include services and teams
curl -H "$AUTH" -H "$ACCEPT" \
  "$API/escalation_policies?include[]=services&include[]=teams"

# JSON output
curl -H "$AUTH" -H "$ACCEPT" "$API/escalation_policies" | \
  jq '.escalation_policies[] | {id, name, num_loops}'

Get Escalation Policy Details

curl -H "$AUTH" -H "$ACCEPT" "$API/escalation_policies/$POLICY_ID"

# Get escalation rules
curl -H "$AUTH" -H "$ACCEPT" "$API/escalation_policies/$POLICY_ID" | \
  jq '.escalation_policy.escalation_rules[] | {
    level: .escalation_delay_in_minutes,
    targets: [.targets[].summary]
  }'

---

Event Orchestration Operations

List Event Orchestrations

# All orchestrations
curl -H "$AUTH" -H "$ACCEPT" "$API/event_orchestrations"

# Sort by name
curl -H "$AUTH" -H "$ACCEPT" "$API/event_orchestrations?sort_by=name:asc"

# JSON output
curl -H "$AUTH" -H "$ACCEPT" "$API/event_orchestrations" | \
  jq '.orchestrations[] | {id, name, routes: .routes}'

Get Event Orchestration

curl -H "$AUTH" -H "$ACCEPT" "$API/event_orchestrations/$ORCHESTRATION_ID"

Get Event Orchestration Router

curl -H "$AUTH" -H "$ACCEPT" \
  "$API/event_orchestrations/$ORCHESTRATION_ID/router"

Get Event Orchestration Service

curl -H "$AUTH" -H "$ACCEPT" \
  "$API/event_orchestrations/services/$SERVICE_ID"

Get Event Orchestration Global

curl -H "$AUTH" -H "$ACCEPT" \
  "$API/event_orchestrations/$ORCHESTRATION_ID/global"

---

Alert Grouping Settings

List Alert Grouping Settings

# All settings
curl -H "$AUTH" -H "$ACCEPT" "$API/alert_grouping_settings"

# Filter by service
curl -H "$AUTH" -H "$ACCEPT" \
  "$API/alert_grouping_settings?service_ids[]=$SERVICE_ID"

Get Alert Grouping Setting

curl -H "$AUTH" -H "$ACCEPT" "$API/alert_grouping_settings/$SETTING_ID"

---

Change Events Operations

List Change Events

# All change events
curl -H "$AUTH" -H "$ACCEPT" "$API/change_events"

# Filter by time range
curl -H "$AUTH" -H "$ACCEPT" \
  "$API/change_events?since=2024-01-01T00:00:00Z&until=2024-01-31T23:59:59Z"

# Filter by team
curl -H "$AUTH" -H "$ACCEPT" "$API/change_events?team_ids[]=$TEAM_ID"

# Filter by integration
curl -H "$AUTH" -H "$ACCEPT" \
  "$API/change_events?integration_ids[]=$INTEGRATION_ID"

Get Change Event

curl -H "$AUTH" -H "$ACCEPT" "$API/change_events/$CHANGE_EVENT_ID"

List Incident Change Events

curl -H "$AUTH" -H "$ACCEPT" \
  "$API/incidents/$INCIDENT_ID/related_change_events"

---

Incident Workflow Operations

List Incident Workflows

# All workflows
curl -H "$AUTH" -H "$ACCEPT" "$API/incident_workflows"

# Search by name
curl -H "$AUTH" -H "$ACCEPT" "$API/incident_workflows?query=triage"

# Include steps and team
curl -H "$AUTH" -H "$ACCEPT" \
  "$API/incident_workflows?include[]=steps&include[]=team"

Get Incident Workflow

curl -H "$AUTH" -H "$ACCEPT" "$API/incident_workflows/$WORKFLOW_ID"

---

Status Page Operations

List Status Pages

# All status pages
curl -H "$AUTH" -H "$ACCEPT" "$API/status_pages"

# Filter by type
curl -H "$AUTH" -H "$ACCEPT" "$API/status_pages?status_page_type=public"

List Status Page Severities

curl -H "$AUTH" -H "$ACCEPT" "$API/status_pages/$STATUS_PAGE_ID/severities"

# Filter by post type
curl -H "$AUTH" -H "$ACCEPT" \
  "$API/status_pages/$STATUS_PAGE_ID/severities?post_type=incident"

List Status Page Impacts

curl -H "$AUTH" -H "$ACCEPT" "$API/status_pages/$STATUS_PAGE_ID/impacts"

# Filter by post type
curl -H "$AUTH" -H "$ACCEPT" \
  "$API/status_pages/$STATUS_PAGE_ID/impacts?post_type=maintenance"

List Status Page Statuses

curl -H "$AUTH" -H "$ACCEPT" "$API/status_pages/$STATUS_PAGE_ID/statuses"

Get Status Page Post

curl -H "$AUTH" -H "$ACCEPT" \
  "$API/status_pages/$STATUS_PAGE_ID/posts/$POST_ID"

# Include updates
curl -H "$AUTH" -H "$ACCEPT" \
  "$API/status_pages/$STATUS_PAGE_ID/posts/$POST_ID?include[]=status_page_post_update"

List Status Page Post Updates

curl -H "$AUTH" -H "$ACCEPT" \
  "$API/status_pages/$STATUS_PAGE_ID/posts/$POST_ID/post_updates"

# Filter by review status
curl -H "$AUTH" -H "$ACCEPT" \
  "$API/status_pages/$STATUS_PAGE_ID/posts/$POST_ID/post_updates?reviewed_status=approved"

---

Creating Incidents

Trigger via Events API v2

curl -X POST -H "Content-Type: application/json" \
  "https://events.pagerduty.com/v2/enqueue" \
  -d '{
    "routing_key": "your-integration-key",
    "event_action": "trigger",
    "dedup_key": "unique-incident-key",
    "payload": {
      "summary": "Critical: Database connection pool exhausted",
      "severity": "critical",
      "source": "production-db-01",
      "custom_details": {
        "pool_size": "100",
        "active_connections": "98"
      }
    },
    "links": [{
      "href": "https://monitoring.example.com/dashboard",
      "text": "View Dashboard"
    }]
  }'

Create via REST API

curl -X POST -H "$AUTH" -H "$ACCEPT" -H "$CONTENT" \
  -H "From: user@example.com" \
  "$API/incidents" \
  -d '{
    "incident": {
      "type": "incident",
      "title": "Critical database issue",
      "service": {
        "id": "SERVICE_ID",
        "type": "service_reference"
      },
      "urgency": "high",
      "body": {
        "type": "incident_body",
        "details": "Database is experiencing high load"
      }
    }
  }'

---

Common Workflows

Dashboard Script

#!/bin/bash
echo "=== Open Incidents ==="
curl -sH "$AUTH" -H "$ACCEPT" \
  "$API/incidents?statuses[]=triggered&statuses[]=acknowledged" | \
  jq -r '.incidents[] | "\(.id)\t\(.title)\t\(.status)\t\(.urgency)"' | \
  column -t -s$'\t'

echo ""
echo "=== Currently On-Call ==="
curl -sH "$AUTH" -H "$ACCEPT" "$API/oncalls?earliest=true" | \
  jq -r '.oncalls[] | "\(.user.summary)\t\(.escalation_policy.summary)"' | \
  column -t -s$'\t'

Who's On-Call Script

#!/bin/bash
# Show who's on-call for each escalation policy

curl -sH "$AUTH" -H "$ACCEPT" "$API/oncalls?earliest=true" | \
  jq -r '.oncalls[] | [
    .escalation_policy.summary,
    .user.summary,
    .schedule.summary // "Direct",
    .escalation_level
  ] | @tsv' | \
  sort | \
  column -t -s$'\t'

Incident Response Script

#!/bin/bash
INCIDENT_ID=$1
ACTION=$2

case $ACTION in
  ack)     STATUS="acknowledged" ;;
  resolve) STATUS="resolved" ;;
  *)       echo "Usage: $0 <incident-id> <ack|resolve>"; exit 1 ;;
esac

curl -X PUT -H "$AUTH" -H "$ACCEPT" -H "$CONTENT" \
  -H "From: $USER_EMAIL" \
  "$API/incidents/$INCIDENT_ID" \
  -d "{\"incident\":{\"type\":\"incident_reference\",\"status\":\"$STATUS\"}}"

---

CLI Tools

pd CLI (Third-party)

# Install
go install github.com/martindstone/pagerduty-cli/pd@latest

# Configure
pd auth:set --token $PAGERDUTY_TOKEN

# List incidents
pd incident:list

# Acknowledge incident
pd incident:ack --ids INCIDENT_ID

# Resolve incident
pd incident:resolve --ids INCIDENT_ID

# Show on-call
pd schedule:oncall --schedule-id SCHEDULE_ID

---

When to Ask for Help

Ask the user for clarification when:

• PagerDuty account or service ID is not specified
• User email is needed for incident updates but not provided
• Incident severity or urgency classification is ambiguous
• Integration key vs API key usage is unclear
• Multiple services, schedules, or teams match the description