See it as a diagram
Everything below, as a diagram you can edit. Describe yours and see it in seconds.
No account needed · Editable canvas, not a picture
Jira shows images it stores, and only those
The Jira Cloud editor stores content as Atlassian Document Format, and its media node points at an attachment id in the Atlassian media store. That is why the documented ways to get a picture into a description are dropping the file onto the work item or using Add and then Attachment. Attachment size is a site setting, and the figure most search results quote is the wrong one: Atlassian's Configure file attachments page puts the Jira Cloud default at 1 GB per file with a 2 GB ceiling, while the 10 MB default belongs to Jira Data Center.
Paste an image URL instead and Jira treats it as a link. Atlassian smart links give you display options for that link, and for a domain Jira has no integration with, the useful options are a plain URL or an inline card. None of them is an inline picture that repaints when the source changes.
Older self-managed Jira renderers accepted wiki markup that took an image address directly, which is why half the answers you find online do not apply to a Cloud site. On Cloud, the choice is an attachment or a link.
A ticket asks an image to do two different jobs
The first job is evidence. What did the topology look like when this incident started, what did the schema look like when this bug was filed. Evidence should freeze. An attached PNG export is exactly right, and its permanence is the feature.
The second job is reference. Someone reading the epic wants to know how the system is wired now, before they estimate the work. A frozen attachment answers that question wrongly and confidently. Reference belongs in a link.
Splitting them costs nothing and removes the failure mode. Attach the export when you are recording a moment. Link the live diagram when you are pointing at the system.
Current architecture (always the live version): https://datadef.io/embed/my-platform-a1b2c3d4 Attached: architecture-2026-08-21.png (state at the time of the incident)
The link that stays current, and what it costs the reader
A Datadef project shared public gets two stable addresses. The image endpoint at /api/embed/<slug> serves the current render as a PNG or JPEG, with optional width from 600 to 4000, height from 400 to 4000, and scale 1 to 3, defaulting to 1600 by 1000 at 2x. The page at /embed/<slug> is the same diagram with pan and zoom, chrome-less apart from a small attribution link.
Neither one asks the reader for an account. Contractors, an auditor, a stakeholder outside the Jira licence count: they open the link and see the diagram. That matters more in Jira than in a README, because work items get shared outward far more often than repositories do.
The image endpoint is also what you download from when you need the attachment. Export as PNG or JPEG, attach the file, and the exported picture and the live link are the same drawing at that moment.
Honest limit
Where the live picture actually lives for a Jira team
Jira is a work tracker, and work trackers are the wrong home for reference material. The Atlassian answer is the Confluence page next to it, where the iframe macro renders the interactive diagram inline and the work item links to the page. That route is covered in embed a diagram in Confluence.
For engineering-owned systems, the other home is the repository README, where a markdown image line renders the current diagram to anyone reading the code. See embed an architecture diagram in a GitHub README.
The Jira work item then holds one line: a link to the reference, plus whatever evidence the ticket needed frozen.
Keeping the thing on the other end of the link true
A live link is only worth having if the diagram behind it moves with the system. Connect the repository read-only from GitHub, GitLab or Azure DevOps, pick a branch or a tag, and the sync regenerates the diagram and an architecture.md daily.
The sync is deliberately unexcitable about what counts as a change. Before it generates anything it hashes the structure it just parsed, the Terraform draw plan for an infrastructure repository or the assembled file corpus otherwise, and compares that fingerprint with the previous run. A commit that edits a README, a test or a comment moves the commit sha and leaves the fingerprint identical, so the run stops there: no regeneration, no new arrangement for a picture that is already linked from forty work items. On the runs that do redraw, any node you dragged more than twelve pixels from where the last sync left it keeps its coordinates.
For teams working with agents, the Datadef MCP server exposes repo_status and repo_refresh, so an assistant in Claude Code or Cursor can refresh the diagram after a merge and paste the link into the work item in the same breath. Details on the agent workflow and on repository sync.
FAQ
Can I insert an image from a URL into a Jira work item description?
Why does the diagram attached to an old Jira ticket no longer match the system?
Does someone opening the diagram link need a Datadef account?
What image size should I attach to a Jira work item?
Can the diagram update itself when the code changes?