Render Mermaid to SVG or PNG with an API

Generate themed Mermaid images with the Flowgraph render API. Send source and theme files, handle errors, and keep documentation exports reproducible.

Updated November 19, 2026 · 2 min read

A render API turns Mermaid source into an image that another tool can use. It is useful when a documentation build, report generator, or internal portal needs diagrams without a person exporting each one manually.

Keep the source and styling inputs together. Otherwise a later render may preserve the architecture while unexpectedly changing its appearance.

Prepare a source file

Save this as request-path.mmd:

flowchart LR
  Client --> Gateway
  Gateway --> Service
  Service --> Store[(Data store)]

Create an API key in Flowgraph Studio under Account settings → Render API (a free account works). Store the key as a local environment variable or CI secret, never inside the Mermaid file or a committed workflow value.

Request an SVG

This Bash example sends the file to the hosted endpoint:

curl --fail-with-body https://flowgraph.studio/v1/render \
  -H "Authorization: Bearer $FLOWGRAPH_API_KEY" \
  -F "diagram=@request-path.mmd;type=text/plain" \
  -F "format=svg" \
  --output request-path.svg

In PowerShell use curl.exe and $env:FLOWGRAPH_API_KEY, with PowerShell line continuation or a single command line. Successful output is the requested image; an error response is not an image even when it is saved to an .svg filename. Inspect the response status before publishing artifacts.

For PNG, change format=svg to format=png, use a .png output name, and add -F "scale=2". The scale controls PNG pixel density. Use transparent=true when the image needs a transparent background, then check legibility against its actual destination.

Keep the theme explicit

Export a theme JSON file from the editor and add:

-F "theme=@theme.json;type=application/json"

That line is an extra argument to the preceding curl command, not a standalone shell command. The endpoint also accepts a JSON request containing code, theme, format, scale, and transparent.

Record the source, theme, and output format as build inputs. Fonts, renderer versions, or application updates can still affect the resulting image, so archive approved output when an exact historical appearance matters.

Handle predictable failures

Authentication failures return 401. Invalid Mermaid returns 422 with a JSON body explaining why. Using Gen AI icons on the Free plan returns 403, and a request over 2 MB or a diagram over 200,000 characters returns 413. Burst limits (30 requests a minute per key) and exhausted monthly allowances return 429; do not retry an exhausted monthly quota indefinitely. Rendering infrastructure failures return 502 and are worth one retry.

Successful renders count against the account's monthly allowance; failed renders are not counted. Every response carries X-Quota-Limit, X-Quota-Remaining, and X-Quota-Reset, and GET /v1/usage reports the same numbers. Free API output carries a small watermark line. Check the current limits in the API reference and the pricing page before designing a high-volume job.

To check a diagram without writing an image, POST /v1/validate returns {"valid": false, "error": …, "line": …} for broken code. The CI guide shows both endpoints in a GitHub Actions workflow.

Start by reproducing one approved image. Then connect the same request to your build system, with clear failure reporting and intentional artifact replacement.

More guides