From a5375e002eea19c62fa22c47ad762c580703fab0 Mon Sep 17 00:00:00 2001 From: "pd-rae-stg[bot]" <242723647+pd-rae-stg[bot]@users.noreply.github.com> Date: Wed, 13 May 2026 02:05:43 +0000 Subject: [PATCH] Clarify Events API v1 vs v2 image attachment differences Addresses customer confusion (SIG-4790) about how images are attached differently between Events API v1 and v2: - V1 uses `contexts` array with `type: "image"` objects - V2 uses `images` array directly without a type field Changes: - Added cross-reference notes to both v1 and v2 docs explaining the structural differences - Clarified that image URLs must point directly to image files, not web pages containing images - Specified that URLs must be publicly accessible by PagerDuty This helps developers understand why their v1-style `contexts` payloads don't work in v2, and vice versa. Co-Authored-By: Claude Sonnet 4.5 --- docs/events-API-v1/02-Trigger-Events.md | 4 +++- docs/events-API-v2/02-Trigger-Events.md | 6 ++++-- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/events-API-v1/02-Trigger-Events.md b/docs/events-API-v1/02-Trigger-Events.md index c8b0f7e..ecde0dd 100644 --- a/docs/events-API-v1/02-Trigger-Events.md +++ b/docs/events-API-v1/02-Trigger-Events.md @@ -161,6 +161,8 @@ The `contexts` field is a JSON array of informational assets that can be attache Every `context` must have a `type`. There are a few different types of contexts supported; the fields allowed and required depend on the context type. +> **Note:** Events API v1 uses the `contexts` array with typed objects (e.g., `type: "image"` or `type: "link"`) for attaching assets to incidents. This is different from [Events API v2](../../docs/events-API-v2/02-Trigger-Events.md#context-properties), which uses separate `images` and `links` arrays without a `type` field. When migrating to v2, update your payload structure accordingly. + ### Link Context The `link` type is used to attach hyperlinks to an incident. @@ -179,7 +181,7 @@ The `image` type is used to attach images to an incident. Images must be served Name | Required | Description ------ | -------- | ----------- `type` | Yes | The type of context being attached to the incident. For image contexts, this must be `image`. -`src` | Yes | The source (URL) of the image being attached to the incident. This image must be served via HTTPS. +`src` | Yes | The source (URL) of the image being attached to the incident. This image must be served via HTTPS. The URL must be publicly accessible by PagerDuty and must point directly to an image file (e.g., `.png`, `.jpg`, `.gif`), not to a web page containing an image. `href` | No | Optional link for the image. `alt` | No | Optional alternative text for the image. diff --git a/docs/events-API-v2/02-Trigger-Events.md b/docs/events-API-v2/02-Trigger-Events.md index 6b100e0..066483a 100644 --- a/docs/events-API-v2/02-Trigger-Events.md +++ b/docs/events-API-v2/02-Trigger-Events.md @@ -136,13 +136,15 @@ See the [Events API v2 Overview page](../../docs/events-API-v2/01-Overview.md#re These properties can be used to attach informational assets to the incident record. Each element of these arrays is an [object](../../docs/REST-API/06-Types.md#object). +> **Note:** Events API v2 uses the `images` array directly for attaching images to alerts. This is different from [Events API v1](../../docs/events-API-v1/02-Trigger-Events.md#image-context), which uses the `contexts` array with `type: "image"` objects. When migrating from v1 to v2, update your payload structure accordingly. + #### The `images` Property This property is used to attach images to the incident. Each object in the list has the following properties: | Name | Required | Description | | ------ | -------- | -------------------------------------------------------------------------------------------------- | -| `src` | Yes | The source (URL) of the image being attached to the incident. This image must be served via HTTPS. | +| `src` | Yes | The source (URL) of the image being attached to the incident. This image must be served via HTTPS. The URL must be publicly accessible by PagerDuty and must point directly to an image file (e.g., `.png`, `.jpg`, `.gif`), not to a web page containing an image. | | `href` | No | Optional URL; makes the image a clickable link. | | `alt` | No | Optional alternative text for the image. | @@ -159,4 +161,4 @@ This property is used to attach text links to the incident. Each object in the l The Events API v2 requires a `routing_key`. You can [create an Events API v2 integration on any PagerDuty service](https://support.pagerduty.com/docs/services-and-integrations#section-events-API-v2) in order to get a routing key that will route an event to that service. You can also use an integration key from a [ruleset](https://support.pagerduty.com/docs/rulesets#section-global-rulesets) to send alert events. -[Try it out here](/send-event-form/) \ No newline at end of file +[Try it out here](/send-event-form/)