Background

Currently, when inserting attachments (such as images) directly into Jira issue comments via the REST API, the mapping between the media reference in the comment and the actual Jira attachment is performed using the alt property in the comment’s content and the filename property in the attachment object. This approach is unreliable, especially when multiple attachments have the same filename or when filenames are changed.

Current Behavior

• When retrieving a comment via the REST API (e.g., GET /rest/api/3/issue/ET-14/comment), the response includes a media object:
   

 
}{{ "type": "media",{{ "attrs": {}}{{ "type": "file",}}{{ "id": "f3541c98-1f1a-407a-8d61-ad3d788d5a48",}}{{ "alt": "Screenshot 2025-10-09 at 1.05.40 p.m..png",}}{{ "collection": "",}}{{ "height": 210,}}{{ "width": 175}}{{ }}}

• }

• When retrieving attachments for the issue (e.g., GET /rest/api/3/issue/ET-14?fields=attachment), the response includes:
   

 
}{{ "id": "10397",{{ "filename": "Screenshot 2025-10-09 at 1.05.40 p.m..png",}}{{ ...}}

• }

• The only way to map the media in the comment to the actual attachment is by matching the alt property in the comment to the filename property in the attachment.

Problem Statement

• Ambiguity: If multiple attachments have the same filename, mapping is ambiguous.

• Fragility: If a filename is changed, the mapping breaks.

• Lack of Direct Reference: The id property in the comment’s media object does not correspond to the attachment’s id property, making programmatic mapping unreliable.

Proposed Solution

• Enhance the REST API so that the media object in the comment references the actual attachment by its unique Jira attachment id, not just by filename.

• For example, the comment’s media object could include:
   

 
}{{ "type": "media",{{ "attrs": {}}{{ "type": "file",}}{{ "attachmentId": "10397", // direct mapping to attachment}}{{ ...}}{{ }}}

• }

• Alternatively, ensure that the existing id property in the media object matches the attachment’s id property.

Benefits

• Future-Proof: Changes to filenames or other metadata will not break the mapping.

References / Example

• Comment API:
  GET https://gaboleoni.atlassian.net/rest/api/3/issue/ET-14/comment

• Attachment API:
  GET https://gaboleoni.atlassian.net/rest/api/3/issue/ET-14?fields=attachment