# PagerDuty

{% hint style="info" %}
The following documentation is for **PagerDuty v1.0.3** *(BDK)*.
{% endhint %}

## Overview

PagerDuty is an incident management platform that helps teams respond to and resolve critical issues quickly. This integration enables automated incident creation, escalation management, and on-call scheduling workflows. Improve incident response times and maintain system reliability through automated monitoring.

## Prerequisites

### 1. Required Books

The following Book(s) need to be added to your agent so it can learn and understand the automation procedures defined within them:

* **PagerDuty**

#### How to Add the Book(s)

1. Go to **Books** → **All Books**.
2. Search for the name of the book and click on it.
3. Click on <kbd>**Install**</kbd> or <kbd>**Add Connection**</kbd> to add the book to your agent.
4. If adding a connection, you'll be prompted for [**connectivity**](#connectivity) details.

## Connectivity

This section outlines the available methods for connecting to the Book, along with the required configuration details for each.

### Connect using API Key

Connect to PagerDuty API using API key.

| Label   | Description                     | Type        |
| ------- | ------------------------------- | ----------- |
| API Key | The API key for authentication. | `sensitive` |

## Procedures

### to create an (incident) in *pagerduty*

Create an incident in PagerDuty.

**Input Concepts**

| Concept                                           | Description                          | Type                                  | Required | Default Value |
| ------------------------------------------------- | ------------------------------------ | ------------------------------------- | -------- | ------------- |
| [`payload`](#pagerduty-incident-creation-payload) | The data for the incident to create. | `pagerduty incident creation payload` | Yes      | (no default)  |

**Output Concepts**

| Concept                           | Description           | Type                 |
| --------------------------------- | --------------------- | -------------------- |
| [`incident`](#pagerduty-incident) | The created incident. | `pagerduty incident` |

**Examples**

Create an incident in PagerDuty

```generic
create a json
use the above as the body
the body's title is "Application Failure"
the body's type is "incident"
get '{"id": "P0ED7MS", "type": "service_reference"}' as a json
use the above as the service
the body's service is the service
create an incident in pagerduty
    the payload is the body
```

### to get some (incidents) from *pagerduty*

![FILTER - CAPABLE](https://img.shields.io/static/v1?label=FILTER\&message=CAPABLE\&color=blue)

Get incidents from PagerDuty using a Filter Expression.

**Output Concepts**

| Concept                            | Description          | Type                 |
| ---------------------------------- | -------------------- | -------------------- |
| [`incidents`](#pagerduty-incident) | A list of incidents. | `pagerduty incident` |

**Examples**

Get all incidents from PagerDuty

```generic
get some incidents from pagerduty
```

### to manage an (incident) in *pagerduty*

Manage an incident in PagerDuty.

Manage (update) an incident in PagerDuty. The 'From' header with a valid user email may be required by PagerDuty for this operation, depending on what was the authentication method used.

**Input Concepts**

| Concept                                         | Description                                                            | Type                                | Required | Default Value |
| ----------------------------------------------- | ---------------------------------------------------------------------- | ----------------------------------- | -------- | ------------- |
| [`incident`](#pagerduty-incident)               | The ID of the incident to update.                                      | `pagerduty incident`                | Yes      | (no default)  |
| [`payload`](#pagerduty-incident-update-payload) | The data to update for the incident.                                   | `pagerduty incident update payload` | Yes      | (no default)  |
| `user email`                                    | The email of the PagerDuty user for 'From' header in write operations. | `text`                              | No       | (no default)  |

**Output Concepts**

| Concept                           | Description           | Type                 |
| --------------------------------- | --------------------- | -------------------- |
| [`incident`](#pagerduty-incident) | The updated incident. | `pagerduty incident` |

**Examples**

Manage an incident in PagerDuty

```generic
get some incidents from pagerduty
get the first incident as the incident
create a json
use the above as the body
the body's status is "acknowledged"
manage the incident in pagerduty
    the payload is the incident
    the user email is "integrations@kognitos.com"
```

## Concepts

### Pagerduty incident creation payload

Payload for creating a PagerDuty incident.Payload for creating an incident

| Field Name                                                                    | Description                                  | Type                     |
| ----------------------------------------------------------------------------- | -------------------------------------------- | ------------------------ |
| `title`                                                                       | The title of the incident.                   | `text`                   |
| `service`                                                                     | The service the incident is associated with. | `json`                   |
| `type`                                                                        | The type of the incident.                    | `optional[text]`         |
| [`priority`](#priority-pagerduty-incident-creation-payload)                   | The priority of the incident.                | `optional[json]`         |
| `urgency`                                                                     | The urgency of the incident.                 | `optional[text]`         |
| [`body`](#body-pagerduty-incident-creation-payload)                           | The body of the incident.                    | `optional[json]`         |
| `incident_key`                                                                | The incident key.                            | `optional[text]`         |
| [`assignments`](#assignments-pagerduty-incident-creation-payload)             | The assignments of the incident.             | `optional[list of json]` |
| [`escalation_policy`](#escalation_policy-pagerduty-incident-creation-payload) | The escalation policy of the incident.       | `optional[json]`         |
| [`conference_bridge`](#conference_bridge-pagerduty-incident-creation-payload) | The conference bridge of the incident.       | `optional[json]`         |
| `incident_type_name`                                                          | The incident type name.                      | `optional[text]`         |

### Pagerduty incident

PagerDuty incident data model.A PagerDuty incident.

| Field Name                                                               | Description                                  | Type                     |
| ------------------------------------------------------------------------ | -------------------------------------------- | ------------------------ |
| `id`                                                                     | The ID of the incident.                      | `text`                   |
| `type`                                                                   | The type of the incident.                    | `text`                   |
| `summary`                                                                | The summary of the incident.                 | `optional[text]`         |
| `self_url`                                                               | The self URL of the incident.                | `optional[text]`         |
| `html_url`                                                               | The HTML URL of the incident.                | `optional[text]`         |
| `incident_number`                                                        | The incident number.                         | `optional[number]`       |
| `title`                                                                  | The title of the incident.                   | `optional[text]`         |
| `created_at`                                                             | The creation time of the incident.           | `optional[text]`         |
| `updated_at`                                                             | The last update time of the incident.        | `optional[text]`         |
| `status`                                                                 | The status of the incident.                  | `optional[text]`         |
| `incident_key`                                                           | The incident key.                            | `optional[text]`         |
| [`service`](#service-pagerduty-incident)                                 | The service the incident is associated with. | `optional[json]`         |
| [`assignments`](#assignments-pagerduty-incident)                         | The assignments of the incident.             | `optional[list of json]` |
| `assigned_via`                                                           | The assigned via of the incident.            | `optional[text]`         |
| `last_status_change_at`                                                  | The last status change time of the incident. | `optional[text]`         |
| `resolved_at`                                                            | The resolution time of the incident.         | `optional[text]`         |
| [`first_trigger_log_entry`](#first_trigger_log_entry-pagerduty-incident) | The first trigger log entry of the incident. | `optional[json]`         |
| [`alert_counts`](#alert_counts-pagerduty-incident)                       | The alert counts of the incident.            | `optional[json]`         |
| `is_mergeable`                                                           | Whether the incident is mergeable.           | `optional[boolean]`      |
| [`incident_type`](#incident_type-pagerduty-incident)                     | The type of the incident.                    | `optional[json]`         |
| [`escalation_policy`](#escalation_policy-pagerduty-incident)             | The escalation policy of the incident.       | `optional[json]`         |
| [`teams`](#teams-pagerduty-incident)                                     | The teams of the incident.                   | `optional[list of json]` |
| [`pending_actions`](#pending_actions-pagerduty-incident)                 | The pending actions of the incident.         | `optional[list of json]` |
| [`acknowledgements`](#acknowledgements-pagerduty-incident)               | The acknowledgements of the incident.        | `optional[list of json]` |
| [`last_status_change_by`](#last_status_change_by-pagerduty-incident)     | The last status change by of the incident.   | `optional[json]`         |
| [`priority`](#priority-pagerduty-incident)                               | The priority of the incident.                | `optional[json]`         |
| [`conference_bridge`](#conference_bridge-pagerduty-incident)             | The conference bridge of the incident.       | `optional[json]`         |
| `urgency`                                                                | The urgency of the incident.                 | `optional[text]`         |
| [`body`](#body-pagerduty-incident)                                       | The body of the incident.                    | `optional[json]`         |

### Pagerduty incident update payload

Payload for updating a PagerDuty incident.Payload for updating an incident (subset of fields)

| Field Name                                                                  | Description                            | Type                     |
| --------------------------------------------------------------------------- | -------------------------------------- | ------------------------ |
| `status`                                                                    | The status of the incident.            | `optional[text]`         |
| `resolution`                                                                | The resolution of the incident.        | `optional[text]`         |
| `title`                                                                     | The title of the incident.             | `optional[text]`         |
| [`priority`](#priority-pagerduty-incident-update-payload)                   | The priority of the incident.          | `optional[json]`         |
| `escalation_level`                                                          | The escalation level of the incident.  | `optional[number]`       |
| [`assignments`](#assignments-pagerduty-incident-update-payload)             | The assignments of the incident.       | `optional[list of json]` |
| `incident_type_name`                                                        | The incident type name.                | `optional[text]`         |
| [`escalation_policy`](#escalation_policy-pagerduty-incident-update-payload) | The escalation policy of the incident. | `optional[json]`         |
| `urgency`                                                                   | The urgency of the incident.           | `optional[text]`         |
| [`conference_bridge`](#conference_bridge-pagerduty-incident-update-payload) | The conference bridge of the incident. | `optional[json]`         |

**Concept attribute specifications**

**priority (pagerduty incident creation payload)**

| Name       | Type             |
| ---------- | ---------------- |
| `id`       | `text`           |
| `type`     | `optional[text]` |
| `summary`  | `optional[text]` |
| `self_url` | `optional[text]` |
| `html_url` | `optional[text]` |

**body (pagerduty incident creation payload)**

| Name      | Type             |
| --------- | ---------------- |
| `type`    | `optional[text]` |
| `details` | `optional[any?]` |

**assignments (pagerduty incident creation payload)**

| Name       | Type             |
| ---------- | ---------------- |
| `at`       | `optional[text]` |
| `assignee` | `optional[json]` |

**escalation\_policy (pagerduty incident creation payload)**

| Name       | Type             |
| ---------- | ---------------- |
| `id`       | `text`           |
| `type`     | `optional[text]` |
| `summary`  | `optional[text]` |
| `self_url` | `optional[text]` |
| `html_url` | `optional[text]` |

**conference\_bridge (pagerduty incident creation payload)**

| Name                | Type             |
| ------------------- | ---------------- |
| `conference_number` | `optional[text]` |
| `conference_url`    | `optional[text]` |

**service (pagerduty incident)**

| Name       | Type             |
| ---------- | ---------------- |
| `id`       | `text`           |
| `type`     | `optional[text]` |
| `summary`  | `optional[text]` |
| `self_url` | `optional[text]` |
| `html_url` | `optional[text]` |

**assignments (pagerduty incident)**

| Name       | Type             |
| ---------- | ---------------- |
| `at`       | `optional[text]` |
| `assignee` | `optional[json]` |

**first\_trigger\_log\_entry (pagerduty incident)**

| Name       | Type             |
| ---------- | ---------------- |
| `id`       | `text`           |
| `type`     | `optional[text]` |
| `summary`  | `optional[text]` |
| `self_url` | `optional[text]` |
| `html_url` | `optional[text]` |

**alert\_counts (pagerduty incident)**

| Name        | Type               |
| ----------- | ------------------ |
| `triggered` | `optional[number]` |
| `resolved`  | `optional[number]` |
| `all`       | `optional[number]` |

**incident\_type (pagerduty incident)**

| Name   | Type             |
| ------ | ---------------- |
| `name` | `optional[text]` |

**escalation\_policy (pagerduty incident)**

| Name       | Type             |
| ---------- | ---------------- |
| `id`       | `text`           |
| `type`     | `optional[text]` |
| `summary`  | `optional[text]` |
| `self_url` | `optional[text]` |
| `html_url` | `optional[text]` |

**teams (pagerduty incident)**

| Name       | Type             |
| ---------- | ---------------- |
| `id`       | `text`           |
| `type`     | `optional[text]` |
| `summary`  | `optional[text]` |
| `self_url` | `optional[text]` |
| `html_url` | `optional[text]` |

**pending\_actions (pagerduty incident)**

| Name   | Type             |
| ------ | ---------------- |
| `type` | `text`           |
| `at`   | `text`           |
| `to`   | `optional[text]` |

**acknowledgements (pagerduty incident)**

| Name           | Type             |
| -------------- | ---------------- |
| `at`           | `optional[text]` |
| `acknowledger` | `optional[json]` |

**last\_status\_change\_by (pagerduty incident)**

| Name       | Type             |
| ---------- | ---------------- |
| `id`       | `text`           |
| `type`     | `text`           |
| `summary`  | `optional[text]` |
| `self_url` | `optional[text]` |
| `html_url` | `optional[text]` |

**priority (pagerduty incident)**

| Name       | Type             |
| ---------- | ---------------- |
| `id`       | `text`           |
| `type`     | `optional[text]` |
| `summary`  | `optional[text]` |
| `self_url` | `optional[text]` |
| `html_url` | `optional[text]` |

**conference\_bridge (pagerduty incident)**

| Name                | Type             |
| ------------------- | ---------------- |
| `conference_number` | `optional[text]` |
| `conference_url`    | `optional[text]` |

**body (pagerduty incident)**

| Name      | Type             |
| --------- | ---------------- |
| `type`    | `optional[text]` |
| `details` | `optional[any?]` |

**priority (pagerduty incident update payload)**

| Name       | Type             |
| ---------- | ---------------- |
| `id`       | `text`           |
| `type`     | `optional[text]` |
| `summary`  | `optional[text]` |
| `self_url` | `optional[text]` |
| `html_url` | `optional[text]` |

**assignments (pagerduty incident update payload)**

| Name       | Type             |
| ---------- | ---------------- |
| `at`       | `optional[text]` |
| `assignee` | `optional[json]` |

**escalation\_policy (pagerduty incident update payload)**

| Name       | Type             |
| ---------- | ---------------- |
| `id`       | `text`           |
| `type`     | `optional[text]` |
| `summary`  | `optional[text]` |
| `self_url` | `optional[text]` |
| `html_url` | `optional[text]` |

**conference\_bridge (pagerduty incident update payload)**

| Name                | Type             |
| ------------------- | ---------------- |
| `conference_number` | `optional[text]` |
| `conference_url`    | `optional[text]` |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kognitos.com/legacy/legacy-experience/books/reference/pagerduty.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.