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

# PagerDuty

> Client-mode REST API connector for a curated PagerDuty slice: Events API v2 trigger/resolve from alarms, list incidents by status, and add incident notes

Technical Preview

## Overview

A client-mode connector for a **curated ITSM / alerting** slice of [PagerDuty Events API v2](https://docs.pagerduty.com/developer/events-api-v2-overview) and the [REST API](https://docs.pagerduty.com/developer/api/reference/rest/incidents):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST v2/enqueue trigger | `POST /v2/enqueue` | **Host:** `https://events.pagerduty.com` — `event_action=trigger` + `routing_key` in body |
| POST v2/enqueue resolve | `POST /v2/enqueue` | Same host/path; `event_action=resolve` + `dedup_key` |
| GET incidents?statuses\[]= | `GET /incidents?statuses[]={status}` | **Host:** `https://api.pagerduty.com` — Token or OAuth |
| POST incidents/\{id}/notes | `POST /incidents/{id}/notes` | Requires `From` header (user email) |

Default `BASE_ADDRESS` is `https://api.pagerduty.com`. Topics use `itsm/pagerduty/<object>/<verb>`.

> [!NOTE]
>
> Events enqueue is **not** on `api.pagerduty.com`. Official path is `https://events.pagerduty.com/v2/enqueue`. When calling `Enqueuetrigger` / `Enqueueresolve`, set connector `BASE_ADDRESS` to `https://events.pagerduty.com` (or deploy a second connector copy). Auth for Events is the `routing_key` field in the JSON body, not an Authorization header.

> [!NOTE]
>
> Prefer Hub secrets for API tokens and routing keys. This template has not been verified against a live PagerDuty account. Status remains blocked until an authenticated live smoke succeeds.

## Basic Syntax

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — PagerDuty (Events API v2 + REST curated slice)
# Auth REST: Token token={value.json.token} (or Bearer access_token)
# Auth Events: routing_key in JSON body
# BASE_ADDRESS REST: https://api.pagerduty.com
# Events: set BASE_ADDRESS to https://events.pagerduty.com

DEFINE ROUTE PagerDutyRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.pagerduty.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Enqueuetrigger
        WITH SOURCE_TOPIC "itsm/pagerduty/event/trigger"
        WITH DESTINATION_TOPIC "itsm/pagerduty/event/trigger/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/enqueue"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT Enqueueresolve
        WITH SOURCE_TOPIC "itsm/pagerduty/event/resolve"
        WITH DESTINATION_TOPIC "itsm/pagerduty/event/resolve/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/enqueue"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT Listincidents
        WITH SOURCE_TOPIC "itsm/pagerduty/incident/list"
        WITH DESTINATION_TOPIC "itsm/pagerduty/incident/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/incidents?statuses[]={value.json.status}&limit={value.json.limit}"
        WITH HEADERS
            ADD "Accept" "application/vnd.pagerduty+json;version=2"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Token token={value.json.token}"
    ADD EVENT Createincidentnote
        WITH SOURCE_TOPIC "itsm/pagerduty/incident/note"
        WITH DESTINATION_TOPIC "itsm/pagerduty/incident/note/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/incidents/{value.json.id}/notes"
        WITH HEADERS
            ADD "Accept" "application/vnd.pagerduty+json;version=2"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Token token={value.json.token}"
            ADD "From" "{value.json.from_email}"
        WITH BODY "{payload}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Enqueuetrigger | POST | `/v2/enqueue` | `itsm/pagerduty/event/trigger` | `itsm/pagerduty/event/trigger/response` |
| Enqueueresolve | POST | `/v2/enqueue` | `itsm/pagerduty/event/resolve` | `itsm/pagerduty/event/resolve/response` |
| Listincidents | GET | `/incidents?statuses[]={status}&limit={limit}` | `itsm/pagerduty/incident/list` | `itsm/pagerduty/incident/list/response` |
| Createincidentnote | POST | `/incidents/{id}/notes` | `itsm/pagerduty/incident/note` | `itsm/pagerduty/incident/note/response` |

## Auth

**Events API v2 (trigger / resolve):**

1. Create an Events API v2 integration on a PagerDuty service; copy the Integration Key.
2. Set connector `BASE_ADDRESS` to `https://events.pagerduty.com`.
3. Put `routing_key` in the MQTT JSON body (with `event_action`, and for resolve a `dedup_key`). No Authorization header.
4. Prefer Hub secrets / `GET SECRET "PAGERDUTY_ROUTING_KEY"`. Never commit real keys.
5. Successful enqueue returns **HTTP 202**.

**REST API token (list / notes) — default in the template:**

1. Create a PagerDuty [API token](https://docs.pagerduty.com/developer/authentication) (account or user).
2. Set connector `BASE_ADDRESS` to `https://api.pagerduty.com`.
3. Pass `token` on the MQTT request payload so headers resolve:
   * `Authorization: Token token={value.json.token}`
4. Use `Accept: application/vnd.pagerduty+json;version=2`.
5. For notes, also pass `from_email` → `From` header (valid account user email).
6. Store the token in Hub secrets / `GET SECRET "PAGERDUTY_API_TOKEN"`. Never commit real credentials.

**OAuth 2.0 (REST alternative):**

1. Obtain an OAuth access token with `incidents.read` / `incidents.write` as needed.
2. Change the Authorization header to `Bearer {value.json.access_token}`.

## Example payloads

**Trigger from alarm** (`BASE_ADDRESS` = `https://events.pagerduty.com`):

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "routing_key": "YOUR_EVENTS_INTEGRATION_KEY",
  "event_action": "trigger",
  "dedup_key": "line-a/vibration",
  "payload": {
    "summary": "Vibration above threshold — Zone A",
    "severity": "critical",
    "source": "coreflux-broker",
    "component": "plc-line-a",
    "custom_details": { "rms_mm_s": 12.4 }
  },
  "client": "Coreflux"
}
```

**Resolve:**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "routing_key": "YOUR_EVENTS_INTEGRATION_KEY",
  "event_action": "resolve",
  "dedup_key": "line-a/vibration"
}
```

**List incidents:**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "token": "YOUR_API_TOKEN",
  "status": "triggered",
  "limit": "25"
}
```

**Create note:**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "token": "YOUR_API_TOKEN",
  "id": "PT4KHLK",
  "from_email": "oncall@example.com",
  "note": {
    "content": "Coreflux: vibration cleared after fan restart."
  }
}
```

## Deploy notes

* Deploy **`PagerDutyRestApi.lot` only** (`-addRoute`). Do **not** deploy `hub-metadata.lot` as a connector — it exists for Hub / `-listTemplates` (`ADD METADATA` + `WITH IMAGE` base64).
* Hub category: **REST API Connectors**.
* Doc link: [https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/pagerduty](https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/pagerduty)

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


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