Module Reference

This page covers the documentation of individual methods and classes provided by the package. For general usage and examples, refer to the User Guide.

API Client Classes

For convenience and backwards compatibility, the API client classes supplied by this library are imported into the root namespace of the module. For example:

# Instead of this:
from pagerduty.rest_api_v2_client import RestApiV2Client

# One can write the import as:
from pagerduty import RestApiV2Client
class pagerduty.ApiClient(api_key: str, debug=False)

Base class for making HTTP requests to PagerDuty APIs

This is an opinionated wrapper of requests.Session, with a few additional features:

  • The client will reattempt the request with auto-increasing cooldown/retry intervals, with attempt limits configurable through the retry attribute.

  • When making requests, headers specified ad-hoc in calls to HTTP verb functions will not replace, but will be merged into, default headers.

  • The request URL, if it doesn’t already start with the REST API base URL, will be prepended with the default REST API base URL.

  • It will only perform requests with methods as given in the permitted_methods list, and will raise Error for any other HTTP methods.

Parameters:

  • api_key – The API secret to use for authentication in HTTP requests

  • debug – Sets print_debug. Set to True to enable verbose command line output.

after_set_api_key()

Setter hook for setting or updating the API key.

Child classes should implement this to perform additional steps.

property api_key: str

Property representing the credential used for accessing the given API.

property auth_header: dict

Generates the header with the API credential used for authentication.

log = None

A logging.Logger object for logging messages. By default it is configured without any handlers and so no messages will be emitted. See: Logger Objects.

max_http_attempts = 10

The number of times that the client will retry after error statuses, for any that are defined greater than zero in retry.

max_network_attempts = 3

The number of times that connecting to the API will be attempted before treating the failure as non-transient; a Error exception will be raised if this happens.

normalize_params(params: dict) → dict

Modify the user-supplied parameters to ease implementation

Returns:

The query parameters after modification

normalize_url(url: str) → str

Compose the URL whether it is a path or an already-complete URL

parent = None

The super object (requests.Session)

permitted_methods = ()

A tuple of the methods permitted by the API which the client implements.

For instance:

  • The REST API accepts GET, POST, PUT and DELETE.

  • The Events API and Change Events APIs only accept POST.

postprocess(response: Response)

Perform supplemental actions immediately after receiving a response.

This method is called once per request not including retries, and can be extended in child classes.

prepare_headers(method: str, user_headers: dict | None = None) → dict

Append special additional per-request headers.

Parameters:

  • method – The HTTP method, in upper case.

  • user_headers – Headers that can be specified to override default values.

Returns:

The final list of headers to use in the request

property print_debug: bool

Printing debug flag

If set to True, the logging level of log is set to logging.DEBUG and all log messages are emitted to sys.stderr. If set to False, the logging level of log is set to logging.NOTSET and the debugging log handler that prints messages to sys.stderr is removed. This value thus can be toggled to enable and disable verbose command line output.

It is False by default and it is recommended to keep it that way in production settings.

request(method: str, url: str, **kwargs) → Response

Make a generic PagerDuty API request.

Parameters:

  • method (str) – The request method to use. Case-insensitive. May be one of get, put, post or delete.

  • url (str) – The path/URL to request. If it does not start with the base URL, the base URL will be prepended.

  • **kwargs –

    Custom keyword arguments to pass to requests.Session.request.

Returns:

The requests.Response object corresponding to the HTTP response

retry = {}

A dict defining the retry behavior for each HTTP response status code.

Each key in this dictionary is an int representing a HTTP response code. The behavior is specified by the int value at each key as follows:

  • -1 to retry without limit.

  • 0 has no effect; the default behavior will take effect.

  • n, where n > 0, to retry n times (or up to max_http_attempts total for all statuses, whichever is encountered first), and then return the final response.

The default behavior is to retry without limit on status 429, raise an exception on a 401, and return the requests.Response object in any other case (assuming a HTTP response was received from the server).

sleep_timer = 1.5

Default initial cooldown time factor for rate limiting and network errors.

Each time that the request makes a followup request, there will be a delay in seconds equal to this number times sleep_timer_base to the power of how many attempts have already been made so far, unless stagger_cooldown is nonzero.

sleep_timer_base = 2

After each retry, the time to sleep before reattempting the API connection and request will increase by a factor of this amount.

property stagger_cooldown: float

Randomizing factor for wait times between retries during rate limiting.

If set to number greater than 0, the sleep time for rate limiting will (for each successive sleep) be adjusted by a factor of one plus a uniformly-distributed random number between 0 and 1 times this number, on top of the base sleep timer sleep_timer_base.

For example:

  • If this is 1, and sleep_timer_base is 2 (default), then after each status 429 response, the sleep time will change overall by a random factor between 2 and 4, whereas if it is zero, it will change by a factor of 2.

  • If sleep_timer_base is 1, then the cooldown time will be adjusted by a random factor between one and one plus this number.

If the number is set to zero, then this behavior is effectively disabled, and the cooldown factor (by which the sleep time is adjusted) will just be sleep_timer_base

Setting this to a nonzero number helps avoid the “thundering herd” effect that can potentially be caused by many API clients making simultaneous concurrent API requests and consequently waiting for the same amount of time before retrying. It is currently zero by default for consistent behavior with previous versions.

timeout = 60

This is the value sent to Requests as the timeout parameter that determines the TCP read timeout.

property trunc_key: str

Truncated key for secure display/identification purposes.

class pagerduty.OAuthTokenClient(client_secret: str, client_id: str, debug=False)

Client with helpers for performing an OAuth exchange to obtain an access token.

Tokens obtained using the client can then be used to authenticate REST API clients, e.g.

oauth_exchange_client = pagerduty.OAuthTokenClient(client_secret, client_id)
oauth_response = oauth_exchange_client.get_scoped_app_token('read')
client = pagerduty.RestApiV2Client(oauth_response['access_token'], auth_type='bearer')

Requires registering a PagerDuty App to obtain the necessary credentials, and must be used in the context of an OAuth2 authorization flow.

For further details, refer to:

Parameters:

  • client_secret – The secret associated with the application.

  • client_id – The client ID provided when registering the application.

  • debug – Passed to the parent constructor as the debug argument. See: ApiClient

amended_auth_response(response: Response) → dict

Amends the auth response map as necessary for other functionality.

Parameters:

auth_response – A response from the /oauth/token endpoint as a dictionary.

Returns:

The same response from the API in dictionary form with an additional key expiration_date containing the expiration date/time of the token in ISO8601 format. This value can then be used in refresh_client.

authorize_url(scope: str, redirect_uri: str) → str

The authorize URL in PagerDuty that the end user will visit to authorize the app

Parameters:

  • scope – Scope of the OAuth grant requested

  • redirect_uri – The redirect URI in the application that receives the authorization code through client redirect from PagerDuty

Returns:

The formatted authorize URL.

early_refresh_buffer = 86400

Number of seconds before the expiration date to perform a token refresh.

Used when constructing a RestApiV2Client; if the current date/time is after the expiration date, or less than this number of seconds before it, a token refresh is first performed.

If the application is expected to use the resulting client object for more than this amount of time between each new call to refresh_client, this value can be set higher.

By default, this is 24 hours.

classmethod get_authorize_url(client_id: str, scope: str, redirect_uri: str) → str

Generate an authorize URL.

This method can be called directly to circumvent the need to produce a client secret that is otherwise required to instantiate an object.

This is the URL that the user initially visits in the application to authorize the application, which will ultimately redirect the user to redirect_uri but with the authorization code.

Parameters:

  • client_id – Client ID of the application

  • scope – Scope of the OAuth grant requested

  • redirect_uri – The redirect URI in the application that receives the authorization code through client redirect from PagerDuty

Returns:

The formatted authorize URL.

get_new_token(**kw) → dict

Make a token request.

There should not be any need to call this method directly. Each of the supported types of token exchange requests are implemented in other methods:

Returns:

The JSON response from identity.pagerduty.com as a dictionary after amending via amended_auth_response. It should contain a key access_token with the new token and expiration_date containing the date and time when the token will expire in ISO8601 format.

get_new_token_from_code(auth_code: str, scope: str, redirect_uri: str) → dict

Exchange an authorization code granted by the user for an access token.

Parameters:

  • auth_code – The authorization code received by the application at the redirect URI provided.

  • scope – The scope of the authorization request.

Redirect_uri:

The redirect URI that was used in the authorization request.

Returns:

The JSON response from identity.pagerduty.com, containing a key access_token with the new token, as a dict

get_refreshed_token(refresh_token: str) → dict

Obtain a new access token using a refresh token.

Parameters:

refresh_token – The refresh token provided in the response of the original access token, i.e. in the dict returned by get_new_token

Returns:

The JSON response from identity.pagerduty.com, containing a key access_token with the new token, as a dict

get_scoped_app_token(scope: str)

Obtain a scoped app token.

This can be used to grant a server-side app a scoped non-user application token.

Parameters:

scope – The scope of the authorization request.

Returns:

The JSON response from identity.pagerduty.com, containing a key access_token with the new token, as a dict

refresh_client(access_token: str, refresh_token: str, expiration_date: str, base_url: str = 'https://api.pagerduty.com', **kw) → Tuple[RestApiV2Client, dict | None]

Instantiate and return a pagerduty.RestApiV2Client client object

Performs a token refresh if the current time is later than early_refresh_buffer seconds before the expiration date.

Parameters:

  • access_token – The current REST API access token.

  • refresh_token – The refresh token required to refresh the access token.

  • expiration_date – The expiration date of the access token, formatted as an ISO8601 datetime string, including the timezone suffix as a UTC offset. The value contained in the expiration_date key of the amended response dictionary returned by any of the “get token” methods should be usable as this parameter.

  • base_url – The value to use for the url attribute of the API client object.

  • kw – Keyword arguments to pass to the constructor of the API client object.

Returns:

A tuple containing a pagerduty.RestApiV2Client object as its first element and the the amended OAuth response if a refresh was performed (and None otherwise) as its second element.

class pagerduty.RestApiV2BaseClient(api_key: str, auth_type: str = 'token', debug: bool = False)

Abstract base class for all API clients that support APIs similar to REST API v2

This class implements some common features like numeric pagination that also appear and are supported to varying degrees outside of REST API v2.

Parameters:

  • api_key – REST API access token to use for HTTP requests

  • auth_type – The type of credential in use. If authenticating with an OAuth access token, this must be set to oauth2 or bearer. This will determine the format of the Authorization header that is sent to the API in each request.

  • debug – Sets pagerduty.ApiClient.print_debug. Set to True to enable verbose command line output.

api_call_counts = None

A dict object recording the number of API calls per endpoint

api_time = None

A dict object recording the total time of API calls to each endpoint

property auth_type: str

Defines the method of API authentication.

This value determines how the Authorization header will be set. By default this is “token”, which will result in the format Token token=<api_key>.

canonical_path(url: str) → str

Return the canonical path of a URL for a particular API implementation.

See: pagerduty.rest_api_v2_base_client.canonical_path

Parameters:

url – The URL. Must be supported by the API.

Returns:

The canonical path corresponding to the URL.

property canonical_paths: List[str]

List of canonical paths supported by the particular API client.

Child classes that do not implement this method do not a-priori support any API endpoints for features that require entity wrapping, e.g. pagination.

This value is used as the first argument to pagerduty.rest_api_v2_base_client.canonical_path from pagerduty.RestApiV2BaseClient.canonical_path.

property cursor_based_pagination_paths: List[str]

List of paths known by the client to support standard cursor-based pagination.

default_page_size = 100

This will be the default number of results requested in each page when iterating/querying an index (the limit parameter).

dict_all(path: str, by: str = 'id', **kw) → dict

Dictionary representation of all results from an index endpoint.

With the exception of by, all keyword arguments passed to this method are also passed to iter_all; see the documentation on that method for further details.

Parameters:

  • path – The index endpoint URL to use.

  • by – The attribute of each object to use for the key values of the dictionary. This is id by default. Please note, there is no uniqueness validation, so if you use an attribute that is not distinct for the data set, this function will omit some data in the results. If a property is named that the schema of the API requested does not have, this method will raise KeyError.

  • kw – Keyword arguments to pass to iter_all.

Returns:

A dictionary keyed by the values of the property of each result specified by the by parameter.

property entity_wrapper_config: dict

Entity wrapping antipattern specification for the given client.

This dictionary object is sent to pagerduty.rest_api_v2_base_client.entity_wrappers when looking up how any given API endpoint wraps (or doesn’t wrap) response and request entities; refer to the documentation on that method for further details.

Child classes should implement this method and return appropriate configuration to cover all schema antipatterns in the APIs that they support. It is otherwise assumed that all endpoints in its corresponding API follow orthodox entity wrapping conventions, in which case the wrapper information can be inferred from the path itself.

entity_wrappers(http_method: str, path: str) → Tuple[str | None, str | None]

Get the entity-wrapper specification for any given API / API endpoint.

See: pagerduty.rest_api_v2_base_client.entity_wrappers.

Parameters:

  • http_method – The method of the request.

  • path – The canonical API path of the request.

Returns:

The entity wrapper tuple to use in the given request.

get_total(url: str, params: dict | None = None) → int

Gets the total count of records from a classic pagination index endpoint.

Parameters:

  • url – The URL of the API endpoint to query

  • params – An optional dictionary indicating additional parameters to send to the endpoint, i.e. filters, time range (since and until), etc. This may influence the total, i.e. if specifying a filter that matches a subset of possible results.

Returns:

The total number of results from the endpoint with the parameters given.

iter_all(url, params: dict | None = None, page_size: int | None = None, item_hook: callable | None = None, total: bool = False) → Iterator[dict]

Iterator for the contents of an index endpoint or query.

Automatically paginates and yields the results in each page, until all matching results have been yielded or a HTTP error response is received.

If the URL to use supports cursor-based pagintation, then this will return iter_cursor with the same keyword arguments. Otherwise, it implements classic pagination, a.k.a. numeric pagination.

Each yielded value is a dict object representing a result returned from the index. For example, if requesting the /users endpoint, each yielded value will be an entry of the users array property in the response.

Parameters:

  • url – The index endpoint URL to use.

  • params – Additional URL parameters to include.

  • page_size – If set, the page_size argument will override the default_page_size parameter on the session and set the limit parameter to a custom value (default is 100), altering the number of pagination results. The actual number of results in the response will still take precedence, if it differs; this parameter and default_page_size only dictate what is requested of the API.

  • item_hook – Callable object that will be invoked for each item yielded, i.e. for printing progress. It will be called with three parameters: a dict representing a given result in the iteration, an int representing the number of the item in the series, and a value representing the total number of items in the series. If the total isn’t knowable, i.e. the total parameter is False or omitted, the value passed in for the third argument will be the string value "?".

  • total – If True, the total parameter will be included in API calls, and the value for the third parameter to the item hook will be the total count of records that match the query. Leaving this as False confers a small performance advantage, as the API in this case does not have to compute the total count of results in the query.

Yields:

Results from each page of results.

iter_cursor(url: str, params: dict | None = None, item_hook: callable | None = None, page_size: int | None = None) → Iterator[dict]

Iterator for results from an endpoint using cursor-based pagination.

Parameters:

  • url – The index endpoint URL to use.

  • params – Query parameters to include in the request.

  • item_hook – A callable object that accepts 3 positional arguments; see iter_all for details on how this argument is used.

  • page_size – Number of results per page of results (the limit parameter). If unspecified, default_page_size will be used.

Yields:

Results from each page of results.

jget(resource, **kw)

Performs a GET request, returning the JSON-decoded body as a dictionary

jpost(resource, **kw)

Performs a POST request, returning the JSON-decoded body as a dictionary

jput(resource, **kw)

Performs a PUT request, returning the JSON-decoded body as a dictionary

list_all(url: str, **kw) → list

Returns a list of all objects from a given index endpoint.

All keyword arguments passed to this function are also passed directly to iter_all; see the documentation on that method for details.

Parameters:

url – The index endpoint URL to use.

postprocess(response: Response, suffix: str | None = None)

Records performance information / request metadata about the API call.

Parameters:
rdelete(resource, **kw)

Delete a resource.

Parameters:

  • resource – The path/URL to which to send the request, or a dict object representing an API resource that contains an item with key self whose value is the URL of the resource.

  • **kw –

    Custom keyword arguments to pass to requests.Session.delete

rget(resource, **kw)

Wrapped-entity-aware GET function.

Retrieves a resource via GET and returns the wrapped entity in the response.

Parameters:

  • resource – The path/URL to which to send the request, or a dict object representing an API resource that contains an item with key self whose value is the URL of the resource.

  • **kw –

    Custom keyword arguments to pass to requests.Session.get

Returns:

The API response after JSON-decoding and unwrapping

rpost(url, **kw)

Wrapped-entity-aware POST function.

Creates a resource and returns the created entity if successful.

Parameters:

  • path – The path/URL to which to send the POST request, which should be an index endpoint.

  • **kw –

    Custom keyword arguments to pass to requests.Session.post

Returns:

The API response after JSON-decoding and unwrapping

rput(resource, **kw)

Wrapped-entity-aware PUT function.

Update an individual resource, returning the wrapped entity.

Parameters:

  • resource – The path/URL to which to send the request, or a dict object representing an API resource that contains an item with key self whose value is the URL of the resource.

  • **kw –

    Custom keyword arguments to pass to requests.Session.put

Returns:

The API response after JSON-decoding and unwrapping. In the case of at least one Teams endpoint (within REST API v2) and any other future API endpoint that responds with 204 No Content, the return value will be None.

property total_call_count: int

The total number of API calls made by this instance.

property total_call_time: float

The total time spent making API calls.

class pagerduty.RestApiV2Client(api_key: str, default_from: str | None = None, auth_type: str = 'token', debug: bool = False)

PagerDuty REST API v2 client class.

Implements abstractions for the particular features of PagerDuty’s REST API v2. Inherits from pagerduty.RestApiV2BaseClient.

Parameters:

  • api_key – REST API access token to use for HTTP requests.

  • default_from – The default email address to use in the From header when making API calls using an account-level API access key.

  • auth_type – The type of credential in use. If authenticating with an OAuth access token, this must be set to oauth2 or bearer. This will determine the format of the Authorization header that is sent to the API in each request.

  • debug – Sets pagerduty.ApiClient.print_debug. Set to True to enable verbose command line output.

account_has_ability(ability: str) → bool

Test that the account has an ability.

Parameters:

ability – The named ability, i.e. teams.

Returns:

True or False based on whether the account has the named ability.

property api_key_access: str

Memoized API key access type getter.

Will be “user” if the API key is a user-level token (all users should have permission to create an API key with the same permissions as they have in the PagerDuty web UI).

If the API key in use is an account-level API token (as only a global administrator user can create), this property will be “account”.

default_from = None

The default value to use as the From request header

find(resource: str, query: str, attribute: str = 'name', params: dict | None = None) → dict | None

Finds an object of a given resource type exactly matching a query.

Works by querying a given resource index endpoint using the query parameter. To use this function on any given resource, the resource’s index must support the query parameter; otherwise, the function may not work as expected. If the index ignores the parameter, for instance, this function will take much longer to return; results will not be constrained to those matching the query, and so every result in the index will be downloaded and compared against the query up until a matching result is found or all results have been checked.

The comparison between the query and matching results is case-insenitive. When determining uniqueness, APIs are mostly case-insensitive, and therefore objects with similar characters but differing case can’t even exist. All results (and the search query) are for this reason reduced pre-comparison to a common form (all-lowercase strings) so that case doesn’t need to match in the query argument (which is also interpreted by the API as case-insensitive).

If said behavior differs for a given API, i.e. the uniqueness constraint on a field is case-sensitive, it should still return the correct results because the search term sent to the index in the querystring is not lower-cased.

Parameters:

  • resource – The name of the resource endpoint to query, i.e. escalation_policies

  • query – The string to query for in the the index.

  • attribute – The property of each result to compare against the query value when searching for an exact match. By default it is name, but when searching for user by email (for example) it can be set to email

  • params – Optional additional parameters to use when querying.

Returns:

The dictionary representation of the result, if found; None will be returned if there is no exact match result.

iter_alert_grouping_settings(service_ids: list | None = None, limit: int | None = None) → Iterator[dict]

Iterator for the contents of the “List alert grouping settings” endpoint.

The API endpoint “GET /alert_grouping_settings” has its own unique method of pagination. This method provides an abstraction for it similar to what iter_all provides for endpoints that implement classic pagination.

See: List alert grouping settings

Parameters:

  • service_ids – A list of specific service IDs to which results will be constrained.

  • limit – The number of results retrieved per page. By default, the value default_page_size will be used.

Yields:

Results from each page in the alert_grouping_settings response property.

iter_analytics_raw_incidents(filters: dict, order: str = 'desc', order_by: str = 'created_at', limit: int | None = None, time_zone: str | None = None) → Iterator[dict]

Iterator for raw analytics data on multiple incidents.

The API endpoint POST /analytics/raw/incidents has its own unique method of pagination. This method provides an abstraction for it similar to iter_all.

See: Get raw data - multiple incidents

Parameters:

  • filters – Dictionary representation of the required filters parameters.

  • order – The order in which to sort results. Must be asc or desc.

  • order_by – The attribute of results by which to order results. Must be created_at or seconds_to_resolve.

  • limit – The number of results to yield per page before requesting the next page. If unspecified, default_page_size will be used. The particular API endpoint permits values up to 1000.

Yields:

Entries of the data property in the response body from each page

iter_history(url: str, since: datetime, until: datetime, recursion_depth: int = 0, **kw) → Iterator[dict]

Yield all historical records from an endpoint in a given time interval.

This method works around the limitation of classic pagination (see pagerduty.rest_api_v2_base_client.ITERATION_LIMIT) by recursively bisecting the initially-provided time interval until the total number of results in each sub-interval is less than the hard pagination limit.

Parameters:

  • url – Index endpoint (API URL) from which to yield results. In the event that a cursor-based pagination endpoint is given, this method calls iter_cursor directly, as cursor-based pagination has no such limitation.

  • since – The beginning of the time interval. This must be a non-naïve datetime object (i.e. it must be timezone-aware), in order to format the since parameter when transmitting it to the API such that it unambiguously takes the time zone into account. See: datetime (Python documentation)

  • until – The end of the time interval. A timezone-aware datetime object must be supplied for the same reason as for the since parameter.

  • kw – Custom keyword arguments to pass to the iteration method. Note, if providing params in order to add query string parameters for filtering, the since and until keys (if present) will be ignored.

Yields:

All results from the resource collection API within the time range specified by since and until.

iter_incident_notes(incident_id: str | None = None, **kw) → Iterator[dict]

Iterator for incident notes.

This is a filtered iterator for log entries of type annotate_log_entry.

Parameters:

  • incident_id – Optionally, request log entries for a specific incident. If included, the team_ids[] query parameter will be removed and ignored.

  • kw – Custom keyword arguments to send to iter_all.

Yields:

Incident note log entries as dictionary objects

normalize_params(params: dict) → dict

Modify the user-supplied parameters to ease implementation

Current behavior:

  • If a parameter’s value is of type list, and the parameter name does not already end in “[]”, then the square brackets are appended to keep in line with the requirement that all set filters’ parameter names end in “[]”.

Returns:

The query parameters after modification

persist(resource: str, attr: str, values: dict, update: bool = False) → dict

Finds or creates and returns a resource with a matching attribute

Given a resource name, an attribute to use as an idempotency key and a set of attribute:value pairs as a dict, create a resource with the specified attributes if it doesn’t exist already and return the resource persisted via the API (whether or not it already existed).

Parameters:

  • resource – The URL to use when creating the new resource or searching for an existing one. The underlying AP must support entity wrapping to use this method with it.

  • attr – Name of the attribute to use as the idempotency key. For instance, “email” when the resource is “users” will not create the user if a user with the email address given in values already exists.

  • values – The content of the resource to be created, if it does not already exist. This must contain an item with a key that is the same as the attr argument.

  • update – (New in 4.4.0) If set to True, any existing resource will be updated with the values supplied.

rpatch(url, **kw)

Wrapped-entity-aware PATCH function.

Currently the only API endpoint that uses or supports this method is “Update Workflow Integration Connection”: PATCH /workflows/integrations/{integration_id}/connections/{id}

It cannot use the resource_url decorator because the schema in that case has no self property, and so the URL or path must be supplied.

Parameters:

  • path – The URL to be requested

  • kw – Keyword arguments to send to the request function, i.e. params

Returns:

The API response after JSON-decoding and unwrapping

property subdomain: str

Subdomain of the PagerDuty account of the API access token.

url = 'https://api.pagerduty.com'

Base URL of the REST API

class pagerduty.EventsApiV2Client(api_key: str, debug: bool = False)

Session class for submitting events to the PagerDuty v2 Events API.

Implements methods for submitting events to PagerDuty through the Events API, including change events, and inherits from pagerduty.ApiClient. For more details on usage of this API, refer to the Events API v2 documentation

For constructor arguments, see pagerduty.ApiClient.

acknowledge(dedup_key: str) → str

Acknowledge an alert via Events API.

Parameters:

dedup_key – The deduplication key of the alert to set to the acknowledged state.

Returns:

The deduplication key

post(*args, **kw) → Response

Override of requests.Session.post

Adds the routing_key parameter to the body before sending.

resolve(dedup_key: str) → str

Resolve an alert via Events API.

Parameters:

dedup_key – The deduplication key of the alert to resolve.

send_change_event(payload: dict | None = None, links: List[dict] | None = None, routing_key: str | None = None, images: List[dict] | None = None)

Send a change event to the v2 Change Events API.

See: https://developer.pagerduty.com/docs/events-api-v2/send-change-events/

Parameters:

  • payload – A dictionary object with keys summary, source, timestamp and custom_details as described in the above documentation.

  • links – A list of dictionary objects each with keys href and text representing the target and display text of each link

  • routing_key – (Deprecated) the routing key. The parameter is set automatically to the ApiClient.api_key property in the final payload and this argument is ignored.

  • images – Optional list of images to attach to the change event.

send_event(action: str, dedup_key: str | None = None, **properties) → str

Send an event to the v2 Events API.

See: https://v2.developer.pagerduty.com/docs/send-an-event-events-api-v2

Parameters:

  • action (str) – The action to perform through the Events API: trigger, acknowledge or resolve.

  • dedup_key (str) – The deduplication key; used for determining event uniqueness and associating actions with existing incidents.

  • **properties –

    Additional properties to set, i.e. if action is trigger this would include payload.

Returns:

The deduplication key of the incident

submit(summary: str, source: str | None = None, custom_details: dict | None = None, links: List[dict] | None = None, timestamp: str | None = None)

Submit a change event.

See: https://developer.pagerduty.com/docs/send-change-event

This is a wrapper method for send_change_event that composes an event payload from keyword arguments and an auto-generated event timestamp. To send an event with a wholly custom payload, use send_change_event instead.

Parameters:

  • summary (str) – Summary / brief description of the change, for payload.summary.

  • source (str) – A human-readable name identifying the source of the change, for the payload.source event property.

  • custom_details (dict) – A dictionary object to use as the payload.custom_details property.

  • links (list) – A list of dict objects to use as the links property of the event.

  • timestamp (str) – Specifies an event timestamp. Must be an ISO8601-format date/time.

trigger(summary: str, source: str, dedup_key: str | None = None, severity: str = 'critical', payload: str | None = None, custom_details: dict | None = None, images: List[dict] | None = None, links: List[dict] | None = None) → str

Send an alert-triggering event

Parameters:

  • summary (str) – Summary / brief description of what is wrong.

  • source (str) – A human-readable name identifying the system that is affected.

  • dedup_key (str) – The deduplication key; used for determining event uniqueness and associating actions with existing incidents.

  • severity (str) – Alert severity. Sets the payload.severity property.

  • payload (dict) – Set the payload directly. Can be used in conjunction with other parameters that also set payload properties; these properties will be merged into the default payload, and any properties in this parameter will take precedence except with regard to custom_details.

  • custom_details (dict) – The payload.custom_details property of the payload. Will override the property set in the payload parameter if given.

  • images (list) – Set the images property of the event.

  • links (list) – Set the links property of the event.

Returns:

The deduplication key of the incident, if any.

class pagerduty.JiraCloudIntegrationApiClient(api_key: str, auth_type: str = 'token', debug: bool = False)

Client for the PagerDuty Jira Server Integration API.

Inherits from pagerduty.RestApiV2BaseClient.

This client provides an abstraction layer for the PagerDuty Jira Cloud Integration API.

For constructor arguments, see pagerduty.RestApiV2BaseClient.

class pagerduty.JiraServerIntegrationApiClient(api_key: str, jira_signature_token: str, debug: bool = False)

Client for the PagerDuty Jira Server Integration API.

Inherits from pagerduty.RestApiV2BaseClient.

This client provides an abstraction layer for the PagerDuty Jira Server Integration API.

Its documentation indicates that it only supports “Bearer” (OAuth-based) authentication and does not support the original token-style API authentication. For that reason, its constructor does not accept an “auth_type” argument, and it is assumed that the provided API key was generated using an OAuth flow.

Parameters:

  • api_key – REST API access token to use for HTTP requests

  • jira_signature_token – Connected Jira instance signature token. This validates the connection between PagerDuty and a specific Jira instance.

  • debug – Sets pagerduty.ApiClient.print_debug. Set to True to enable verbose command line output.

class pagerduty.MsTeamsIntegrationApiClient(api_key: str, debug: bool = False)

Client for the PagerDuty Microsoft Teams Integration API.

Inherits from pagerduty.RestApiV2BaseClient.

This client provides an abstraction layer for the PagerDuty MS Teams Integration API.

Its documentation indicates that it only supports the original “Token” style authentication and does not support OAuth token (“Bearer”) authentication. For that reason, its constructor does not accept an “auth_type” argument, and it is assumed that the provided API key was generated through the PagerDuty web UI.

For constructor arguments, see pagerduty.ApiClient.

class pagerduty.SlackIntegrationApiClient(api_key: str, auth_type: str = 'token', debug: bool = False)

Client for the PagerDuty Slack Integration API.

Inherits from pagerduty.RestApiV2BaseClient.

This client provides an abstraction layer for all of the endpoints of the PagerDuty Slack Integration API except for the “Slack Connections” features, which are supported by pagerduty.SlackIntegrationConnectionsApiClient.

For constructor arguments, see pagerduty.RestApiV2BaseClient.

class pagerduty.SlackIntegrationConnectionsApiClient(api_key: str, auth_type: str = 'token', debug: bool = False)

Client for the PagerDuty Slack Integration API’s “Connections” endpoints.

Inherits from pagerduty.RestApiV2BaseClient.

This client provides an abstraction layer for the PagerDuty Slack Integration API, specifically the “Connections” API endpoints, which use a different hostname in the base URL, app.pagerduty.com, as opposed to api.pagerduty.com.

For constructor arguments, see pagerduty.RestApiV2BaseClient.

Errors

As with client classes, all errors are imported to the root module namespace, so that one can import them directly from pagerduty.

class pagerduty.Error(message, response=None)

General API errors base class.

Note, the name of this class does not imply it solely includes errors experienced by the client or HTTP status 4xx responses, but descendants can include issues with the API backend.

response = None

The HTTP response object, if a response was successfully received.

In the case of network errors, this property will be None.

class pagerduty.HttpError(message, response: Response)

Error class representing errors strictly associated with HTTP responses.

This class was created to make it easier to more cleanly handle errors by way of a class that is guaranteed to have its response be a valid requests.Response object.

Whereas, the more generic Error could also be used to denote such things as non-transient network errors wherein no response was received from the API. For instance, instead of this:

try:
    user = session.rget('/users/PABC123')
except pagerduty.Error as e:
    if e.response is not None:
        print("HTTP error: "+str(e.response.status_code))
    else:
        raise e

one could write this:

try:
    user = session.rget('/users/PABC123')
except pagerduty.HttpError as e:
    print("HTTP error: "+str(e.response.status_code))
class pagerduty.ServerHttpError(message, response: Response)

Error class representing failed expectations made of the server.

This is raised in cases where the response schema differs from the expected schema because of an API bug, or because it’s an early access endpoint and changes before GA, or in cases of HTTP status 5xx where a successful response is required.

class pagerduty.UrlError

Exception class for unsupported URLs or malformed input.

Common Features

Miscellaneous methods and constants used in the client that are used widely and/or don’t fit neatly into any other category are defined in pagerduty.common.

A few of these features are imported to the root namespace for backwards compatibility, but new features will not, going forward.

pagerduty.common.DATETIME_FMT = '%Y-%m-%dT%H:%M:%S%z'

The full ISO8601 format used for parsing and formatting datestamps.

pagerduty.common.TEXT_LEN_LIMIT = 100

The longest permissible length of API content to include in error messages.

pagerduty.common.TIMEOUT = 60

The default timeout in seconds for any given HTTP request.

Modifying this value will not affect any preexisting API session instances. Rather, it will only affect new instances. It is recommended to use pagerduty.ApiClient.timeout to configure the timeout for a given session.

pagerduty.common.datetime_intervals(since: datetime, until: datetime, n=10) → List[Tuple[datetime, datetime]]

Break up a given time interval into a series of smaller consecutive time intervals.

Parameters:

  • since – A datetime object repesenting the beginning of the time interval.

  • until – A datetime object representing the end of the time interval.

  • n – The target number of sub-intervals to generate.

Returns:

A list of tuples representing beginnings and ends of sub-intervals within the time interval. If the resulting intervals would be less than one second, they will be one second.

pagerduty.common.datetime_to_relative_seconds(datestr: str)

Convert an ISO8601 string to a relative number of seconds from the current time.

pagerduty.common.deprecated_kwarg(deprecated_name: str, details: str | None = None, method: str | None = None)

Raises a warning if a deprecated keyword argument is used.

Parameters:

  • deprecated_name – The name of the deprecated function

  • details – An optional message to append to the deprecation message

  • method – An optional method name

pagerduty.common.http_error_message(r: Response, context: str | None = None) → str

Formats a message describing a HTTP error.

Parameters:

  • r – The response object.

  • context – A description of when the error was received, or None to not include it

Returns:

The message to include in the HTTP error

pagerduty.common.last_4(secret: str) → str

Truncate a sensitive value to its last 4 characters

Parameters:

secret – text to truncate

Returns:

The truncated text

pagerduty.common.normalize_url(base_url: str, url: str) → str

Normalize a URL or path to be a complete API URL before query parameters.

The url argument may be a path relative to the base URL or a full URL.

Parameters:

  • url – The URL or path to normalize to a full URL.

  • base_url – The base API URL, excluding any trailing slash, i.e. “https://api.pagerduty.com”

Returns:

The full API URL.

pagerduty.common.plural_name(obj_type: str) → str

Pluralizes a name, i.e. the API name from the type property

Parameters:

obj_type – The object type, i.e. user or user_reference

Returns:

The name of the resource, i.e. the last part of the URL for the resource’s index URL

pagerduty.common.relative_seconds_to_datetime(seconds_remaining: int) → str

Convert a number of seconds in the future to an absolute UTC ISO8601 time string.

pagerduty.common.requires_success(method: callable) → callable

Decorator that validates HTTP responses.

Uses pagerduty.common.successful_response for said validation.

pagerduty.common.singular_name(r_name: str) → str

Singularizes a name, i.e. for the entity wrapper in a POST request

Para r_name:

The “resource” name, i.e. “escalation_policies”, a plural noun that forms the part of the canonical path identifying what kind of resource lives in the collection there, for an API that follows classic wrapped entity naming patterns.

Returns:

The singularized name

pagerduty.common.strftime(time_obj: datetime) → str

Format a datetime object to a string

Parameters:

date – The datetime object

Returns:

The formatted string

pagerduty.common.strptime(datestr: str) → datetime

Parse a string in full ISO8601 format into a datetime.datetime object.

Parameters:

datestr – Full ISO8601 string representation of the date and time, including time zone

Returns:

The datetime object representing the string

pagerduty.common.successful_response(r: Response, context: str | None = None) → Response

Validates the response as successful.

Returns the response if it was successful; otherwise, raises pagerduty.errors.Error

Parameters:

  • r – Response object corresponding to the response received.

  • context – A description of when the HTTP request is happening, for error reporting

Returns:

The response object, if it was successful

pagerduty.common.truncate_text(text: str) → str

Truncates a string longer than pagerduty.common.TEXT_LEN_LIMIT

Parameters:

text – The string to truncate if longer than the limit.

pagerduty.common.try_decoding(r: Response) → dict | list | str | None

JSON-decode a response body

Returns the decoded body if successful; raises pagerduty.ServerHttpError otherwise.

Parameters:

r – The response object

REST API v2 Helpers

REST API v2 and the integration APIs have some common features, such as classic pagination, which are implemented in rest_api_v2_base_client so as to be able to repurpose them in APIs that follow similar conventions.

pagerduty.rest_api_v2_base_client.CanonicalPath

Canonical path type (alias of str).

Canonical paths are the bold-typed portion of the path of the URL displayed in the API reference at the top of each reference page for the given API endpoint. They are interpreted as patterns, i.e. any part of the path enclosed in curly braces (as determined by pagerduty.rest_api_v2_base_client.is_path_param) is interpreted as a variable parameter versus a literal substring of the path.

pagerduty.rest_api_v2_base_client.EntityWrapping

Descriptive entity wrapping type.

If a string, it indicates that the entity is wrapped in a single property of the body of the request or response named after the value of that string. If None, it indicates that entity wrapping is not enabled or should be ignored, i.e. send the user-supplied request body in the API request or return the response body without any modification.

alias of str | None

pagerduty.rest_api_v2_base_client.EntityWrappingSpec

Descriptive type that specifies how entity wrapping is configured for an API endoint.

The first member indicates the entity wrapping of the request body. The second indicates the entity wrapping of the response body. The two may differ.

alias of Tuple[str | None, str | None]

pagerduty.rest_api_v2_base_client.ITERATION_LIMIT = 10000

The maximum position of a result in classic pagination.

The offset plus limit parameter may not exceed this number. This is enforced server-side and is not something the client may override. Rather, this value is reproduced in the client to enable short-circuiting pagination, so that the client can avoid the HTTP 400 error that will result if the sum of the limit and offset parameters exceeds it.

See: Pagination.

pagerduty.rest_api_v2_base_client.auto_json(method: callable) → callable

Decorator to return the full response body object after decoding from JSON.

Intended for use on functions that take a URL positional argument followed by keyword arguments and return a requests.Response object.

The new return value is the JSON-decoded response body (dict or list).

pagerduty.rest_api_v2_base_client.canonical_path(paths: List[str], base_url: str, url: str) → str

The canonical path from the API documentation corresponding to a URL.

This method is used to identify and classify URLs according to which particular API endpoint within the client’s corresponding API it belongs to, in order to account for any antipatterns that the endpoint might have.

For examle, in List a user’s contact methods, the canonical path is /users/{id}/contact_methods.

Parameters:

  • paths – A list of paths supported by the API client. One example of this is pagerduty.rest_api_v2_client.CANONICAL_PATHS.

  • base_url – The base URL of the API

  • url – A non-normalized URL (a path or full URL)

Returns:

The canonical API path corresponding to the URL.

pagerduty.rest_api_v2_base_client.endpoint_matches(endpoint_pattern: str, method: str, path: str) → bool

Whether an endpoint (method and canonical path) matches a given pattern.

This is used by pagerduty.rest_api_v2_base_client.entity_wrappers for finding the appropriate entity wrapper configuration entry to use for a given HTTP method and API path.

Parameters:

  • endpoint_pattern – The endpoint pattern in the form METHOD PATH where METHOD is the HTTP method in uppercase or * to match all methods, and PATH is a canonical API path.

  • method – The HTTP method.

  • path – The canonical API path

Returns:

True or False based on whether the pattern matches the endpoint

pagerduty.rest_api_v2_base_client.entity_wrappers(wrapper_config: dict, method: str, path: str) → Tuple[str | None, str | None]

Obtains entity wrapping information for a given endpoint (canonical path and method)

The information about the API is dependency-injected as the wrapper_config parameter. An example of such a dictionary object is pagerduty.rest_api_v2_client.ENTITY_WRAPPER_CONFIG.

When trying to determine the entity wrapper name for a given API endpoint, the dictionary wrapper_config is first checked for keys that apply to a given request method and canonical API path based on a matching logic. If no keys are found that match, it is assumed that the API endpoint follows classic entity wrapping conventions, and the wrapper name can be inferred based on those conventions (see pagerduty.rest_api_v2_base_client.infer_entity_wrapper). Any new API that does not follow these conventions should therefore be given an entry in the wrapper_config dictionary in order to properly support it for entity wrapping.

Each of the keys of should be a capitalized HTTP method (or * to match any method), followed by a space, followed by a canonical path. Each value is either a tuple with request and response body wrappers (if they differ), a string (if they are the same for both cases) or None (if wrapping is disabled and the data is to be marshaled or unmarshaled as-is). Values in tuples can also be None to denote that either the request or response is unwrapped.

An endpoint, under the design logic of this client, is said to have entity wrapping if the body (request or response) has only one property containing the content requested or transmitted, apart from properties used for pagination. If there are any secondary content-bearing properties (other than those used for pagination), entity wrapping should be disabled to avoid discarding those properties from responses or preventing the use of those properties in request bodies.

Parameters:

  • wrapper_config – A dictionary in which the entity wrapper antipattern configuration is specified.

  • method – A HTTP method.

  • path – A canonical API path.

Returns:

The entity wrapping specification.

pagerduty.rest_api_v2_base_client.infer_entity_wrapper(method: str, path: str) → str

Infer the entity wrapper name from the endpoint using orthodox patterns.

This is based on patterns that are broadly applicable but not universal in the v2 REST API, where the wrapper name is predictable from the path and method. This is the default logic applied to determine the wrapper name based on the path if there is no explicit entity wrapping defined for the given path i.e. in pagerduty.rest_api_v2_client.ENTITY_WRAPPER_CONFIG for pagerduty.RestApiV2Client.

Parameters:

  • method – The HTTP method

  • path – A canonical API path i.e. from pagerduty.rest_api_v2_client.CANONICAL_PATHS

pagerduty.rest_api_v2_base_client.is_path_param(path_node: str) → bool

Whether a part of a canonical path represents a variable parameter

Parameters:

path_node – The node (value between slashes) in the path

Returns:

True if the node represents a variable parameter, False if it is a fixed value

pagerduty.rest_api_v2_base_client.resource_url(method: callable) → callable

API call decorator that allows passing a resource dict as the path/URL

Most resources returned by the API will contain a self attribute that is the URL of the resource itself.

Using this decorator allows the implementer to pass either a URL/path or such a resource dictionary as the path argument, thus eliminating the need to re-construct the resource URL or hold it in a temporary variable.

pagerduty.rest_api_v2_base_client.unwrap(response: Response, wrapper: str | None) → dict | list

Unwraps a wrapped entity from a HTTP response.

Parameters:

  • response – The response object.

  • wrapper – The entity wrapper (string), or None to skip unwrapping

Returns:

The value associated with the wrapper key in the JSON-decoded body of the response, which is expected to be a dictionary (map).

pagerduty.rest_api_v2_base_client.wrapped_entities(method: callable) → callable

Decorator to automatically wrap request entities and unwrap response entities.

Used for defining the r{method} functions, i.e. pagerduty.RestApiV2BaseClient.rpost. It makes the methods always return an object representing the resource entity in the response (whether wrapped in a root-level property or not) rather than the full response body, after JSON-decoding. When making a post / put request, and passing the json keyword argument to specify the content to be JSON-encoded as the body, that keyword argument can be either the to-be-wrapped content or the full body including the entity wrapper, and the json keyword argument will be normalized to include the wrapper.

Methods using this decorator will raise a pagerduty.HttpError with its response property being being the requests.Response object in the case of any error, so that the implementer can access it by catching the exception, and thus design their own custom logic around different types of error responses.

Parameters:

method – Method being decorated. Must take one positional argument after self that is the URL/path to the resource, followed by keyword any number of keyword arguments, and must return an object of class requests.Response, and be named after the HTTP method but with “r” prepended.

Returns:

A callable object; the reformed method