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

# Let On-Call Agents Triage PagerDuty Incidents

> Let SRE agents read PagerDuty incidents and on-call schedules, and acknowledge or resolve pages. Connect a REST API key that the gateway keeps hidden.

## Overview

Buckle 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.

## What you will set up

* A PagerDuty REST API key, General Access or user, ideally read-only
* A connection pinned to your US or EU region
* Per-agent, per-tool access, such as approval before resolving

## Connect PagerDuty

**1. Create an API key in 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 `Buckle Key` and select **Create Token**.

![PagerDuty Create User Key dialog, explaining that API user keys are tied to your user account with the same level of access, a Description field filled with Buckle Key, and Cancel and Create Token buttons.](https://mintcdn.com/onecli-17d3f772/h1DTAVlDkLshz4JZ/images/integrations/pagerduty/pagerduty-create-user-key.png?fit=max\&auto=format\&n=h1DTAVlDkLshz4JZ\&q=85\&s=fc24b9d9ceba3d3db29e51d8ecae4fae)

Creating a user key in PagerDuty. It carries your own user's access.

Copy the key right away. PagerDuty shows it only once.

> [!TIP]
>
> For an agent that only investigates, create a **read-only** General Access key. PagerDuty itself then refuses every write, whatever the agent tries.

**2. Paste it in Buckle**

In the Buckle dashboard, open **Settings** > **Apps** > **PagerDuty**, paste the key into **API key**, and pick your **Region**.

![Buckle connect window for PagerDuty, showing the setup guide link, the API key field with a link to PagerDuty's instructions, the Region dropdown set to US, and the Connect PagerDuty button.](https://mintcdn.com/onecli-17d3f772/h1DTAVlDkLshz4JZ/images/integrations/pagerduty/buckle-connect-pagerduty.png?fit=max\&auto=format\&n=h1DTAVlDkLshz4JZ\&q=85\&s=c98116fc53dea267ff624f47e61920b2)

The PagerDuty connect window in Buckle.

| Field | Value |
| - | - |
| **API key** | The key from the previous step |
| **Region** | **US** (the default), or **EU** if you sign in at `<subdomain>.eu.pagerduty.com` |

Select **Connect PagerDuty**. Buckle 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.

> [!NOTE]
>
> 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.md) 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.md) add guardrails on top. A blocked request never reaches PagerDuty.

To disconnect, remove the connection in **Settings** > **Apps** > **PagerDuty**, then delete the key in PagerDuty under **Integrations** > **API Access Keys** (or **User Settings** for a user key).

## FAQ

> [accordion] How do I rotate my PagerDuty API key?
>
> Create a new key in PagerDuty, then paste it into **Settings** > **Apps** > **PagerDuty**. Agents pick it up automatically. Then delete the old key.

> [accordion] How do I keep the key out of the agent's context?
>
> Store it in Buckle. The gateway injects it at the proxy, so the agent never holds the key. See [How it works](/docs/how-it-works.md).

> [accordion] How do I make an agent read-only?
>
> Create a **read-only** General Access key. PagerDuty then refuses every write, whatever the agent tries.

> [accordion] Why was my key rejected?
>
> Buckle checks the key against your selected region. A wrong key, or a key from the other region, is rejected. Pick **EU** if you sign in at `<subdomain>.eu.pagerduty.com`.


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