[ZEA] SIG-4790 - [PREMIUM] Dev Documentationon is unclear, only the V1 Events API uses the contexts JSON array to make images available

[pd-rae-stg]

Automated Customer Investigation Remediation

This PR contains an automated fix for the customer investigation described in the above Jira ticket, generated by the jira plugin's triage skill. Please
review it carefully before merging as this PR was automatically generated.

Jira Ticket: SIG-4790 - [PREMIUM] Dev Documentationon is unclear, only the V1 Events API uses the contexts JSON array to make images available

Fix Details

Perfect! The documentation has been successfully updated and pushed to GitHub. Let me provide the analysis summary:

---

Analysis Summary - SIG-4790

Issue Description

Customer reported that the developer documentation is unclear about the differences between Events API v1 and v2 regarding how images are attached to alerts. The confusion arises because:

• V1 Events API uses a contexts array with typed objects (e.g., type: "image")
• V2 Events API uses separate images and links arrays without a type field

Additionally, the documentation didn't clearly specify that image URLs must point directly to image files (not web pages) and must be publicly accessible by PagerDuty.

Root Cause

The documentation lacked clear cross-references and explicit warnings about the structural differences between API versions. Developers migrating from v1 to v2 (or vice versa) could easily miss this critical distinction, leading to failed image attachments.

Fix Applied

Updated documentation in the PagerDuty/developer-docs repository with the following changes:

1. Added clarifying notes to Events API v2 documentation (docs/events-API-v2/02-Trigger-Events.md):

   • Added a prominent note in the "Context Properties" section explaining that v2 uses images array directly
   • Cross-referenced v1 documentation showing the different approach
   • Enhanced src field description to specify that URLs must point directly to image files and be publicly accessible

2. Added clarifying notes to Events API v1 documentation (docs/events-API-v1/02-Trigger-Events.md):

   • Added a prominent note in the "Contexts" section explaining that v1 uses contexts array with typed objects
   • Cross-referenced v2 documentation showing the different approach
   • Enhanced src field description with the same clarity about direct image URLs

Example Clarification

The documentation now clearly shows:

V1 API Format:

"contexts": [
  {
    "type": "image",
    "src": "https://example.com/image.png"
  }
]

V2 API Format:

"images": [
  {
    "src": "https://example.com/image.png"
  }
]

Testing & Validation

• Documentation changes follow existing markdown conventions
• Cross-references use proper relative paths
• Added notes are prominently placed in both API version docs
• Changes are backward compatible (documentation only)

Impact

• Resolves customer confusion about API version differences
• Prevents future support tickets about failed image attachments
• Provides clear migration guidance for developers moving between API versions
• Documents the requirement that URLs must point directly to image files

Review Checklist

• Verify the fix matches the customer issue described in the ticket
• Confirm tests pass
• Check for any unintended side effects

[blagh]

It feels strange to do this for only one of the differences between v1 and v2 -- maybe there should be something more like a migration guide?

[blagh]

I think this is only true when the type is image