Embed diagrams in Dropbox Paper: pasted URLs, no iframes, honest expectations

Paste an image URL into a Paper doc and the content appears on the page as an image; that part is documented and dependable. Paper also treats images differently from other files: pasted images do not count toward your Dropbox storage quota, while non-image files attached to a doc are uploaded into a Paper Uploads folder in your Dropbox and linked from the doc.

What Dropbox does not document is whether the displayed image remains a live reference to your URL or becomes a copy in Dropbox's content delivery. Absent a documented guarantee, the safe engineering assumption is a snapshot: treat the image in the doc as the diagram at paste time, not the diagram now. If freshness matters to the doc, verify the behavior once in your own workspace: paste the URL, edit the diagram, and reload the doc a few minutes later.

Paper embeds rich content from recognized products, but it has no generic iframe block, so an interactive pan-and-zoom diagram cannot live inside the doc. The pattern that works is the one Google Docs users know: the picture in the doc for reading flow, the link to the live diagram right under it for truth.

The link costs readers one click and pays it back reliably: the target always shows the current diagram, pannable and zoomable, with the image form served alongside it. Datadef serves that image with an ETag from the diagram's last edit and a five minute cache lifetime, so wherever a surface does hotlink it, an edit appears within minutes.

In the Paper doc, under the pasted diagram:

Live version: https://datadef.io/embed/my-platform-a1b2c3d4
Snapshot taken: 2026-08-12

Image URL, for surfaces that hotlink:
https://datadef.io/api/embed/my-platform-a1b2c3d4

Paper exports docs as Markdown, and the export is where URL-referenced content shows its portability: a link written into the doc exports as a plain URL that works anywhere the Markdown lands. Content that lives in Dropbox storage exports as links into Dropbox, which readers outside your team may not reach. A spec that will outlive Paper, migrated into a wiki or a repo, travels best when its diagram is referenced by a stable external URL rather than attached as a file.

Whichever way Paper treats the pixels, the diagram behind the live link is the thing to keep true. Do it manually in Datadef, or let the agent that just changed the code do it in the same session: with the io.datadef/mcp server configured, it can read the repository and update the diagram before the review is even over. What no agent setup does is notice changes by itself, because watching repositories is not something Datadef does; someone or something has to invoke the agent, and the API key it brings is a paid-plan credential.

A dated snapshot plus a live link is also a hedge against the failure mode Paper docs share with every document tool: the doc is written, the system moves on, and nobody owns the update. That accumulating gap has a name, documentation debt, and diagrams are usually its largest line item.

The live URLs exist only for projects shared public; a private project returns 404, and confidential architectures should stay as dated static images in the doc, staleness accepted. And this page has told you the uncomfortable part already: without a documented re-fetch guarantee from Paper, do not promise your team a live image inside the doc. Promise them a one-click path to the current diagram, which Paper supports without caveats. The Markdown baseline, where hotlinking behavior is precisely known, is covered in embed diagrams in Markdown.

• Embed diagrams in Markdown
• Embed diagrams in Google Docs
• Share live diagrams in Slack
• Documentation debt