Getting a diagram from an agent into your README

export_diagram renders a diagram and returns the image inline, so the client can show it in the conversation, plus a short-lived signed download URL that serves the file directly with an attachment header and needs no API key. The inline image is content in the chat, not a file on disk. The URL is how "save this" works for a client that holds no credentials.

The knobs are deliberately few: format is PNG or JPEG, viewport width runs from 600 to 4000 pixels and defaults to 1600, height runs from 400 to 4000 and defaults to 1000. A wide architecture diagram usually wants a wider viewport rather than a taller one, because the export follows the canvas rather than reflowing it.

There is no PDF and no SVG. For documentation that is fine, since every wiki, README renderer and chat client displays PNG, and PNG is the right choice for a diagram with icons and text.

Alongside the prose the call returns a structured payload: the diagram name, the rendered width and height, the mime type, the download URL, and, when the project is published, an embed image URL and a ready-made markdown line. An agent that reads the structured half never has to parse a sentence to find the link it needs, which is the difference between a reliable documentation step and one that breaks when the wording changes.

The download URL is signed, scoped to that one canvas, and valid for 900 seconds. That is a deliberate limit: a leaked export link should not be a standing grant on a diagram. Fifteen minutes is long enough for a person to read the reply and click, and far too short for documentation. The same budget covers the inline preview link the tools hand a chat client to paste into its reply, so both expire together and neither becomes a quiet public URL.

Pasted into a README, it renders for the duration of the review and breaks before anyone else looks. It is worth telling your agent this explicitly, because a model that has just received a working image URL will reach for it, and nothing about the URL announces its expiry.

A published Datadef diagram exposes a stable embed URL, and one markdown image line renders the current diagram wherever markdown renders. The image follows the canvas, so an edit or a repository sync updates the README without a commit, and readers need no account to see it.

One check before promising that line: the permanent URL exists only for a published project. Export a diagram that is still invite-only and the tool says so in as many words, telling you to share the project publicly first and then ask again. An agent that writes the embed line without checking produces a README image that renders for the person who exported it and for nobody else.

For wikis that accept an iframe rather than an image, the same public slug serves an interactive embed. Confluence, Notion and most documentation platforms take one or the other, which is the whole configuration.

The practical division is simple. The signed export URL is for the moment: attach it, drop it into a message, save the file. The embed line is for the artifact that outlives the session.

<!-- README.md: renders the current diagram, no commit needed -->
![Architecture](https://datadef.io/api/embed/acme-platform)

<!-- a wiki that prefers an interactive frame -->
<iframe src="https://datadef.io/embed/acme-platform"
        width="100%" height="600"></iframe>

Three cases justify a file in the repository. A renderer that will not fetch the image, whether it strips remote sources, proxies them, or refuses anything off its own domain. An environment with no outbound network, where an embedded image resolves to nothing. And a document that has to be reproducible at a past commit, such as an architecture snapshot attached to a release tag. Test the first case rather than assuming it: paste the line, look at the rendered page, and only commit a file once you have seen the embed fail.

In those cases the agent downloads the export through the signed URL, writes the PNG into the repository, and you accept the maintenance: the file is now a copy that ages, and somebody has to regenerate it. Keeping it honest costs one line under the image saying which commit and which date it came from, so a reader can tell how much to trust it.

For everything else, the embed line wins because it removes the regeneration step entirely. The README stops being a place where diagrams go stale and becomes a window onto one that does not.

• Live embeds: one line, always current
• Embedding documentation
• Embed diagrams in a GitHub README
• The architecture section of a README
• SVG or PNG for architecture diagrams