> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ancha.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These docs describe the Ancha CLI, npm package @ancha-labs/cli version 0.1.4, and the hosted workspace at app.ancha.io. Coding agents should start at https://docs.ancha.io/coding-agents. Run the CLI as `ancha` after `npm install -g @ancha-labs/cli`, or as `npx -y @ancha-labs/cli@0.1.4` without installing. Pass --json for machine-readable output, or set ANCHA_JSON=1. Every command ends with a `next:` line naming the next command. Exit codes: 0 pass, 1 a check failed or a comparison regressed, 2 usage, config or authentication error, 3 infrastructure error, 4 unimplemented endpoint with --strict.

# PagerDuty

> A stateful replica of PagerDuty's REST API v2 and Events API v2: users, services, escalation policies, schedules, on-call, incidents, notes and alert events.

The PagerDuty replica implements 17 endpoints of REST API v2 and the Events API v2 `enqueue` endpoint. Incidents move through triggered, acknowledged and resolved, and escalation policies assign them over simulated time. Its key is `pagerduty`. It was tested with `@pagerduty/pdjs`.

## Connect

| Variable | Value |
| - | - |
| `PAGERDUTY_API_URL` | Base URL of the REST API and of `/v2/enqueue`. |
| `PAGERDUTY_API_TOKEN` | Fake REST token. Send `Authorization: Token token=<token>`. |
| `PAGERDUTY_FROM_EMAIL` | The email to send in the `From` header on writes, such as acknowledging an incident. |
| `PAGERDUTY_ROUTING_KEY` | Events API routing key of the default service. |
| `PAGERDUTY_ROUTING_KEYS` | JSON object of routing keys by service ref, for example `{"pagerduty_orders": "..."}`. |
| `PAGERDUTY_SIGNING_SECRET` | Signs webhook deliveries to your agent. |

```js Node theme={null}
import { api } from '@pagerduty/pdjs';
const pd = api({ token: process.env.PAGERDUTY_API_TOKEN! });
const base = process.env.PAGERDUTY_API_URL!;
const result = await pd.get('/services', { url: `${base}/services` });
// Use result.data and result.next(); every REST call requires the complete local url.
// Attributed writes require headers: { From: process.env.PAGERDUTY_FROM_EMAIL! }.
// Native Events v2: fetch(`${base}/v2/enqueue`, ...) with PAGERDUTY_ROUTING_KEY.
// PDJS server, resource/all and Events convenience helpers assume production HTTPS.
```

This is what `ancha connect pagerduty --lang ts` prints. Pass the full local URL on every PDJS call; its `server` option, `all` helpers and Events helpers assume production HTTPS. Send events with `fetch` instead. `ancha connect` has no Python snippet for PagerDuty.

## Endpoints

All endpoints are partial. Any other route returns HTTP 501 with PagerDuty's error shape and `x-ancha-gap: 1`.

### Users and services

| Method | Path |
| - | - |
| `GET` | `/users` |
| `GET` | `/users/:id` |
| `GET` | `/services` |
| `GET` | `/services/:id` |

### Escalation, schedules and on-call

| Method | Path |
| - | - |
| `GET` | `/escalation_policies` |
| `GET` | `/escalation_policies/:id` |
| `GET` | `/schedules` |
| `GET` | `/schedules/:id` |
| `GET` | `/schedules/:id/users` |
| `GET` | `/oncalls` |

Schedules hold explicit on-call intervals. Rotations, layers, restrictions and overrides are not modeled.

### Incidents

| Method | Path |
| - | - |
| `GET` | `/incidents` |
| `GET` | `/incidents/:id` |
| `PUT` | `/incidents/:id` |
| `GET` | `/incidents/:id/notes` |
| `POST` | `/incidents/:id/notes` |
| `GET` | `/incidents/:id/log_entries` |

`PUT /incidents/:id` acknowledges, resolves, reassigns to a user or hands the incident to an escalation policy or level. It needs the `From` header. Reopening, urgency changes, snoozing and bulk updates are coverage gaps. Incident lists cover the previous 30 days by default.

### Events

| Method | Path |
| - | - |
| `POST` | `/v2/enqueue` |

`POST /v2/enqueue` takes Events API v2 `trigger`, `acknowledge` and `resolve` payloads with a service's routing key. Each incident holds one alert, and open events with the same dedup key and routing key update the same incident.

## Starter data

The `pagerduty-starter` dataset is Acme's on-call setup: four services, two escalation policies and five resolved incidents.

| Ref | Record |
| - | - |
| `$pagerduty_bot` | User "Ancha assistant", `ancha@acme.example`. Writes are attributed to this user. |
| `$pagerduty_rachel`, `$pagerduty_greg`, `$pagerduty_victor` | Users Rachel Moore, Greg Wilson and Victor Lane, at `acme.example`. |
| `$pagerduty_policy` | Escalation policy "Orders on-call": the bot first, then Rachel after 5 minutes. |
| `$pagerduty_platform` | Escalation policy "Platform on-call": Greg first, then Victor after 10 minutes. |
| `$pagerduty_orders` | Service "Orders API", using "Orders on-call". The default service for `PAGERDUTY_ROUTING_KEY`. |
| `$pagerduty_checkout`, `$pagerduty_payments`, `$pagerduty_sync` | Services "Checkout", "Payments" and "Warehouse sync", using "Platform on-call". |
| `$pagerduty_previous` | Incident "Orders API slow requests", resolved, created 20 minutes before start, assigned to Rachel. |
| `$pagerduty_rollback` | Incident "Orders API latency after the 4.12.1 deploy", resolved, 3 hours before start, assigned to Rachel. |
| `$pagerduty_checkout_slow`, `$pagerduty_webhooks`, `$pagerduty_sync_stall` | Resolved incidents on Checkout (50 hours before start, Greg), Payments (30 hours, Greg) and Warehouse sync (20 hours, Victor). |

## Checks

```yaml theme={null}
- id: incident_resolved
  state:
    pagerduty.incident: { service: $pagerduty_orders, first: true }
    status: resolved
    assigned_to: [$pagerduty_rachel]
    resolved_within: 5m
```

`pagerduty.incident` selects an incident by ref (`{ ref: $pagerduty_previous }`) or the first one created for a service, including incidents created during the attempt. It needs at least one of `status`, `assigned_to`, `acknowledged_within` or `resolved_within`. `assigned_to` is the exact final set of assignees. The `_within` durations run from creation to the first real transition. See [Checks reference](https://docs.ancha.io/reference/checks.md#pagerduty).

## Limits

* No contact methods, notification rules, teams, rotations or overrides.
* One alert per incident; no alert grouping or event orchestration.
* Escalation timers advance with the simulated clock.


## Related topics

- [Checks reference](https://docs.ancha.io/reference/checks.md)
- [Test file (scene.yaml)](https://docs.ancha.io/reference/test-file.md)
- [Changelog](https://docs.ancha.io/changelog.md)
- [Quickstart](https://docs.ancha.io/quickstart.md)
- [Okta](https://docs.ancha.io/tools/okta.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.