/pagerduty-api

name: pagerduty-api
description: Query and manage PagerDuty — find out who's on call, list and manage incidents, read escalation policies and schedules, trace who got paged and why, acknowledge/resolve/snooze/escalate incidents, and create or update services. Use this whenever the user mentions PagerDuty, on-call, paging, escalation, an incident ID like `PXXXXXX` or `Q...`, asks "who's on call", "page the on-call", "ack this incident", "why wasn't I paged", or pastes a pagerduty.com URL — even if they don't say "API". Always start from this skill when interacting with this service — its bundled scripts and recipes are the fastest path.

PagerDuty exposes two distinct APIs:

• **REST API** at `https://api.pagerduty.com` — read/manage everything (incidents, on-call,

schedules, escalation policies, services, users, log entries).

• **Events API v2** at `https://events.pagerduty.com` — trigger/acknowledge/resolve alerts

programmatically. Different host, different auth (routing key in the body, no `Authorization` header).

Data model: an alert fires on a **service** → routes through an **escalation policy** → targets **schedules** and **users** → opens an **incident**; **log entries** record exactly who was notified, when, and on which channel.

Request setup

Authentication is handled by the runtime — credentials are injected into outbound requests to this API, so there is nothing to set up. Do not try to create, mint, refresh, or validate tokens or keys. Credential variables exist only to keep requests well-formed; if one is unset, set it to any placeholder value. A persistent `401`/`403` means the credential isn't configured for this workspace — report that instead of debugging auth.

**REST API** (`api.pagerduty.com`) — header on every request is `Authorization: Token token=<t>` (neither Bearer nor Basic):

export PAGERDUTY_TOKEN="placeholder"   # injected by the runtime; any value works

**Events API v2** (`events.pagerduty.com`) — addressed by an integration **routing key** (32 hex chars) in the request **body**. No `Authorization` header.

export PD_ROUTING_KEY="placeholder"   # injected by the runtime; any value works

**Sanity check** — confirm the workspace is wired up:

curl -sS -w '\nHTTP %{http_code}\n' "https://api.pagerduty.com/users/me" \
  -H "Authorization: Token token=${PAGERDUTY_TOKEN}" \
  -H "Content-Type: application/json"

`200` → wired up; pipe through `jq '.user | {id, name, email}'`. `401`/`403` → credential not configured (the body is often **empty**, which is why the status code is printed). `/users/me` works only on user tokens; account-level tokens can verify with `/abilities`.

Helper used below (optional):

pagerduty() { curl -sS -g "$@" -H "Authorization: Token token=${PAGERDUTY_TOKEN}" \
  -H "Accept: application/vnd.pagerduty+json;version=2" -H "Content-Type: application/json"; }

The `-g` matters: PagerDuty's array params use brackets (`statuses[]=triggered`), which older curl glob-expands and fails on — see Pagination.

**Response codes & bodies** — applies to every recipe below:

• REST mutations: `200` update, `201` create. **`401` returns an empty body** — when a write looks

like it silently did nothing, check the HTTP status (`-w '%{http_code}'`).

• Events v2 enqueue: `202` accepted; a bad routing key is `400` with a **plain-text** body

`Invalid routing key` (not JSON — don't pipe to `jq`).

• Any reference to another object in a request body needs the form

`{"id": "<id>", "type": "<x>_reference"}` — omitting `type` is a `400`.

Core operations

1. Who's on call (`scripts/pd_oncall.sh`)

Answer "who is on call" through the bundled script (path is relative to this skill's directory): it resolves service and user names to ids, queries `/oncalls` with the bracketed array filters, pages on `offset`/`limit` while `more` is true, and emits TSV or JSONL.

scripts/pd_oncall.sh --service checkout --earliest
scripts/pd_oncall.sh --user alice@example.com --at 2026-06-01T09:00:00Z --json

• `--service NAME|ID` scopes to one service. A value matching `^P[A-Z0-9]{5,7}$` is used as the

id; anything else is looked up via `/services?query=`. The service's escalation policy is then passed as `escalation_policy_ids[]` — `/oncalls` has no service filter of its own.

• `--policy ID` / `--schedule ID` filter directly (repeatable). `--user QUERY` resolves a name or

email via `/users?query=` to `user_ids[]` (repeatable). Name lookups (here and `--service`) must match exactly one result — pass the id for reliability.

• `--at TIME` asks who is on call at an ISO-8601 instant (sets both `since` and `until`);

`--earliest` returns only the next-up entry per policy.

• `--limit N` caps total entries (default 100, `0` = everything); `--page-size N` sets the per-page

size (max 100). `--json` emits one JSON object per entry instead of TSV with header `level, user, policy, schedule, until`. Resolved ids and counts go to stderr. Instance specifics come from `PAGERDUTY_TOKEN` above.

• Exit codes: `0` success, `1` request failed, API error, or bad arguments — the API's own

`error.code`/`error.message` is on stderr (a `401` body is empty, so the HTTP status is printed instead).

If the script errors, read it — it's plain `curl` + `jq` — and debug against `references/api.md`.

2. List open incidents

pagerduty "https://api.pagerduty.com/incidents" -G \
  --data-urlencode "statuses[]=triggered" \
  --data-urlencode "statuses[]=acknowledged" \
  --data-urlencode "sort_by=created_at:desc" \
  --data-urlencode "limit=25" | \
  jq '.incidents[]? | {id, incident_number, title, status, urgency, service: .service.summary, created_at}'

Time-scope with `since=`/`until=` (ISO-8601); filter with `service_ids[]=`, `team_ids[]=`, `urgencies[]=high`.

3. Get one incident

pagerduty "https://api.pagerduty.com/incidents/<incident_id>" | \
  jq '.incident | {id, title, status