A diagram at a link, instead of a screenshot in a thread

Export first, host second

This hosts what a tool exported; it is not a rendering service. Mermaid, PlantUML, D2, Excalidraw and hand-coded diagrams all produce standalone HTML or SVG, and that output is what gets published. Rendering belongs where the diagram is authored — usually in the agent that wrote it.

Mermaid

npx -y @mermaid-js/mermaid-cli -i architecture.mmd -o architecture.svg
curl -X POST https://read.botook.ai/sites \
  -H "Authorization: Bearer otr_live_YOUR_KEY" -F file=@architecture.svg

SVG is stored byte-for-byte and served as an image, so the diagram looks exactly as your tool drew it.

PlantUML

plantuml -tsvg architecture.puml
curl -X POST https://read.botook.ai/sites \
  -H "Authorization: Bearer otr_live_YOUR_KEY" -F file=@architecture.svg

Excalidraw

Export to SVG from the app and publish the file. The result is a link a colleague opens with no account, rather than an image in a thread that loses its labels when scaled.

Keeping it current when the architecture moves

A diagram is wrong the week after it is drawn, and a stale diagram at a shared link is worse than none. Publish once, then have the same job that regenerates the export also update the page behind the existing token — the link in the design doc keeps resolving to the current drawing:

# regenerate, then replace in place — same URL, new bytes
npx -y @mermaid-js/mermaid-cli -i architecture.mmd -o architecture.svg
curl -X PUT https://read.botook.ai/sites/$SITE_ID \
  -H "Authorization: Bearer otr_live_YOUR_KEY" -F file=@architecture.svg

Every upload route accepts the same file: multipart as above, a raw body, JSON, or a tool call from the agent that maintains the diagram. A zip works too when the drawing links out to other pages — see agent-loop hosting for the loop version of this.

A diagram with an explanation around it

Usually better than the bare image: put the SVG inside a page with the reasoning next to it. Ask the agent to produce one self-contained document and publish that.

publish_html({
  content: "<h1>Ingest pipeline</h1><svg …></svg><p>Why the queue is here…</p>",
  expires_in_hours: "never"
})

Diagrams that change

Architecture drifts. Replace in place so the link in the design document is never out of date:

curl -X PUT https://read.botook.ai/sites/SITE_ID \
  -H "Authorization: Bearer otr_live_YOUR_KEY" -F file=@architecture.svg

Generated in the same session

Claude, Codex and Cursor all write Mermaid happily. With the server registered, the agent that drew the diagram renders it and publishes it without you touching a file — how to register it.

Why not a screenshot

• Text in an image cannot be searched, selected or read by a screen reader.
• It is unreadable on a phone as soon as the diagram is non-trivial.
• Updating it means finding everyone you sent it to.

Why not a public diagram service

Your architecture is a description of your systems. A private link keeps it that way; a public render URL does not, and neither does a paste into a third-party editor.

Keeping it internal

An email-domain gate restricts opens to your company. For a contractor, a passcode or a separate share token with a view limit is easier to withdraw later.

SVG safety

SVG is stored unmodified — altering the bytes would break the drawing — and served under the same strict policy as everything else, so a script embedded in an exported file does not execute.

Collecting comments on it

Enable the toolbar and reviewers can attach a comment to the box they think is wrong, which is the entire point of reviewing a diagram at all.

Questions

Do you render Mermaid for me?

No. Export to HTML or SVG first — the rendering step lives in the tool or the agent that authored it.

Can I publish a whole set?

Zip the directory; the tree is served with an index.

Does it work for hand-coded SVG?

Yes, that is the simplest case.

Keep reading