> ## Documentation Index
> Fetch the complete documentation index at: https://onecli.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# PagerDuty Integration: Incidents and On-Call for Agents
> Agents can read PagerDuty incidents, services, schedules, and who is on call, and acknowledge or resolve incidents. Connect with a REST API key.
## Overview
OneCLI connects AI agents to [PagerDuty](https://www.pagerduty.com) with a REST API key. Agents can read incidents and their timelines, see who is on call, and acknowledge, resolve, or add notes to incidents. The gateway injects the key into requests to the PagerDuty API, so your agent never sees it.
This suits SRE and on-call agents: triaging a page as it fires, pulling the timeline for a postmortem, or answering "who is on call for payments right now?"
Connecting takes about a minute.
## Connect PagerDuty
PagerDuty has two kinds of REST API key. Pick the one that matches what the agent should reach.
| Key | Where to create it | What it reaches |
| - | - | - |
| **General Access key** | **Integrations** > **API Access Keys** > **Create New API Key** (admins only) | The whole account. Tick **Read-only API Key** when agents only need to read |
| **User key** | Your avatar > **My Profile** > **User Settings** > **Create API User Token** | Exactly what your own PagerDuty user can reach |
For a user key, give it a description such as `OneCLI Key` and select **Create Token**.
Copy the key right away. PagerDuty shows it only once.
For an agent that only investigates, create a **read-only** General Access key. PagerDuty itself then refuses every write, whatever the agent tries.
In the OneCLI dashboard, open **Connections** > **PagerDuty**, paste the key into **API key**, and pick your **Region**.
| Field | Value |
| - | - |
| **API key** | The key from the previous step |
| **Region** | **US** (the default), or **EU** if you sign in at `.eu.pagerduty.com` |
Select **Connect PagerDuty**. OneCLI checks the key against the API in your region before saving it, so a wrong key, or a key from the other region, is rejected right away.
Agents can always call the documented base URL, `https://api.pagerduty.com`. For an EU account, the gateway sends each request to `api.eu.pagerduty.com` for you.
## What agents can do
| Area | What agents can do |
| - | - |
| **Incidents** | List and filter incidents, read one with its alerts, notes, and timeline, and see related or past incidents |
| **On-call** | See who is on call now or for a time range, and read schedules and their overrides |
| **Services and policies** | Read services, business services, and escalation policies |
| **People** | Read users and teams |
| **Change events** | Read recent deploys and config changes, and record new ones |
| **Analytics** | Read aggregated and raw incident, service, team, and responder metrics |
| **Incident response** | Acknowledge, resolve, reassign, escalate, merge, or snooze incidents, add notes, and request more responders |
| **Maintenance** | Create, change, or delete maintenance windows and schedule overrides |
PagerDuty's Events API (`events.pagerduty.com`), which triggers alerts with an integration's routing key, uses a different credential and is not part of this connection.
## Quick example
No `Authorization` header is needed. The gateway adds PagerDuty's `Token token=` header:
```bash theme={null}
# Who is on call right now
curl -s "https://api.pagerduty.com/oncalls?earliest=true" \
-H "Accept: application/vnd.pagerduty+json;version=2"
# Open incidents, newest first
curl -s "https://api.pagerduty.com/incidents?statuses[]=triggered&statuses[]=acknowledged&sort_by=created_at:desc" \
-H "Accept: application/vnd.pagerduty+json;version=2"
```
For every endpoint and parameter, see the [PagerDuty API reference](https://docs.pagerduty.com/developer/api/reference).
## Controlling access
[Grant](/docs/guides/agent-access) the connection to each agent that needs it, and choose per tool what runs freely, what needs approval, and what's blocked.
Writes in PagerDuty page real people. **Create incident** and **Add responders** wake someone up, and a maintenance window silences paging for a service, so put those behind approval. A good default for an SRE agent is to let it read everything freely and require approval for acknowledging or resolving incidents.
Organization [rules](/docs/guides/rules) add guardrails on top. A blocked request never reaches PagerDuty.
To disconnect, remove the connection in **Connections** > **PagerDuty**, then delete the key in PagerDuty under **Integrations** > **API Access Keys** (or **User Settings** for a user key).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.