Worlds / Eng and it ops

PagerDuty API

A local PagerDuty with services, incidents, escalation policies, schedules and on-call users. Test the incident agent that acknowledges, reassigns, merges and resolves incidents.

Base path: /
Auth: REST API key (Authorization: Token token=...), the world key
Endpoints: 17
Status: Active today

This reference previews the surface the PagerDuty world serves in the closed beta. Paths mirror the public PagerDuty API; the exact subset is confirmed when your workflow is scoped.

Connect

The run gives your agent these bindings. Keep your SDK; change only where it sends requests.

binding	meaning
`WORLDS_PAGERDUTY_URL`	This world's origin followed by `/`
`WORLDS_API_KEY`	The world key, accepted wherever PagerDuty expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · @pagerduty/pdjs

import { api } from "@pagerduty/pdjs";

const pd = api({
  token: process.env.WORLDS_API_KEY,
  server: process.env.WORLDS_PAGERDUTY_URL,
});

const { data } = await pd.get("/incidents?statuses[]=triggered");

API reference

17 of 17

Incidents

Alerts that need a human, with status and assignment.

GET/incidentsList incidents
POST/incidentsCreate an incident
GET/incidents/{id}Get an incident
PUT/incidents/{id}Acknowledge, resolve or reassign an incident
POST/incidents/{id}/notesAdd a note
GET/incidents/{id}/log_entriesList an incident's log entries

Fields · 6

`id`	string	Incident id
`title`	string	Title
`status`	string	triggered, acknowledged or resolved
`urgency`	string	high or low
`service`	object	Affected service
`assignments`	array	Who it is assigned to

Services

Things that get monitored, each with an escalation policy.

GET/servicesList services
POST/servicesCreate a service
GET/services/{id}Get a service
PUT/services/{id}Update a service

Fields · 4

`id`	string	Service id
`name`	string	Service name
`status`	string	active, warning, critical or maintenance
`escalation_policy`	object	Policy that handles incidents

On calls

Who is on call right now and at each escalation level.

GET/oncallsList on call entries
GET/schedulesList schedules
GET/schedules/{id}Get a schedule
POST/schedules/{id}/overridesCreate overrides

Fields · 5

`user`	object	On call user
`schedule`	object	Schedule
`escalation_level`	integer	Level in the policy
`start`	datetime	Start of the shift
`end`	datetime	End of the shift

Escalation policies

Who gets paged and when.

GET/escalation_policiesList escalation policies
GET/escalation_policies/{id}Get an escalation policy
POST/escalation_policiesCreate an escalation policy

Fields · 4

`id`	string	Policy id
`name`	string	Policy name
`num_loops`	integer	How many times to repeat
`escalation_rules`	array	Levels and targets

Test workflow

Prepare. Select the PagerDuty setup for your workflow and review its starting records, including incidents, services, on calls.
Connect. Configure your agent with this world's URL and key using the SDK example. Check that it reaches the intended API before running a test.
Define. Describe the task, expected final changes and records that must stay untouched. Keep expected outcomes separate from the agent's instructions.
Run and inspect. Use the dashboard or your workflow's generated CLI setup. Review final records and changes, then rerun from the same starting setup with the relevant failure conditions. Use Deployment and CI to automate the same workflow.

What to verify

#3012 acknowledged
#3013 merged into #3012
#3009 still acknowledged
No one outside primary on-call paged
Escalation policies unchanged

Test file

A task file names the jobs, the policy your agent is given and what the grader reads back from the world's final state. The agent never sees the expected outcomes.

yaml · worlds/tasks.yaml

# worlds/tasks.yaml · PagerDuty
version: 2
connector: pagerduty
seed: pagerduty-starter
mode: isolated
policy: >
  Handle the open checkout incidents. Acknowledge #3012, merge the duplicate
  #3013 into it, and leave the database incident to its owner.
tasks:
  - id: acknowledge-and-route-new-incidents-to-the-right-responder
    prompt: Acknowledge and route new incidents to the right responder
  - id: merge-duplicate-incidents-into-one
    prompt: Merge duplicate incidents into one
  - id: resolve-incidents-after-the-alert-clears
    prompt: Resolve incidents after the alert clears
expected:
  - "#3012 acknowledged"
  - "#3013 merged into #3012"
  - "#3009 still acknowledged"
  - No one outside primary on-call paged
  - Escalation policies unchanged
scenarios:
  - rate-limited
  - missing-from-header
  - re-triggered

See Tasks and outcomes for every field, and Deployment and CI to run the file on every pull request.

Failure conditions

Each one fires before the handler, at the same step on every run.

condition	what the agent sees
`rate-limited`	The REST API returns 429
`missing-from-header`	Writes without a valid From email return 400
`re-triggered`	An acknowledged incident re-triggers after the ack timeout
`dedup-key`	The same dedup_key on Events API v2 appends to the open incident
`token-revoked`	The API key is revoked mid run

Starting data

Start each run from the same records and relationships. The overview below describes the PagerDuty starter; use the setup supplied for your workflow when preparing your own snapshot.

Records	Starting setup
services	12 services with integrations and urgency rules
incidents	40 triggered, acknowledged and resolved
escalation policies	3 levels with timeouts
schedules	Primary and secondary on-call rotations
users	25 responders with contact methods

The record shapes below reuse this world's API field definitions. They show illustrative values and placeholders, not an importable seed. API responses and seed input can differ; include all required records and references in the accepted import format for your workflow.

Incidents records

Incidents

Alerts that need a human, with status and assignment.

Field	Type	Meaning / relationship
`id`	string	Incident id
`title`	string	Title
`status`	string	triggered, acknowledged or resolved
`urgency`	string	high or low
`service`	object	Affected service
`assignments`	array	Who it is assigned to

json · illustrative record shape

{
  "id": "<Incident id>",
  "title": "<Title>",
  "status": "<triggered, acknowledged or resolved>",
  "urgency": "<high or low>",
  "service": {},
  "assignments": []
}

See incidents operations

Services records

Services

Things that get monitored, each with an escalation policy.

Field	Type	Meaning / relationship
`id`	string	Service id
`name`	string	Service name
`status`	string	active, warning, critical or maintenance
`escalation_policy`	object	Policy that handles incidents

json · illustrative record shape

{
  "id": "<Service id>",
  "name": "<Service name>",
  "status": "<active, warning, critical or maintenance>",
  "escalation_policy": {}
}

See services operations

On calls records

On calls

Who is on call right now and at each escalation level.

Field	Type	Meaning / relationship
`user`	object	On call user
`schedule`	object	Schedule
`escalation_level`	integer	Level in the policy
`start`	datetime	Start of the shift
`end`	datetime	End of the shift

json · illustrative record shape

{
  "user": {},
  "schedule": {},
  "escalation_level": 1,
  "start": "<Start of the shift>",
  "end": "<End of the shift>"
}

See on calls operations

Escalation policies records

Escalation policies

Who gets paged and when.

Field	Type	Meaning / relationship
`id`	string	Policy id
`name`	string	Policy name
`num_loops`	integer	How many times to repeat
`escalation_rules`	array	Levels and targets

json · illustrative record shape

{
  "id": "<Policy id>",
  "name": "<Policy name>",
  "num_loops": 1,
  "escalation_rules": []
}

See escalation policies operations

See the PagerDuty world in the catalog