Render and validate Mermaid diagrams in CI with an API
Keep diagrams as code in your repository and let the build check and render them: validate Mermaid in CI, render themed SVG or PNG files, update saved diagrams, and give coding assistants access through MCP.
Diagrams that live in the repository change in the same pull request as the code they describe. The missing piece is the build: something that fails when a diagram is broken and produces the images your docs use. Flowgraph Studio's render API does both, with the same renderer and themes as the editor.
How it fits in a pipeline
sequenceDiagram
participant Dev as Developer
participant Repo as Repository
participant CI as CI job
participant API as Flowgraph API
Dev->>Repo: Push docs/checkout.mmd
Repo->>CI: Run the docs workflow
CI->>API: POST /v1/validate
API-->>CI: valid: true
CI->>API: POST /v1/render (SVG, your theme)
API-->>CI: checkout.svg
CI->>Repo: Publish the docs with the new imageGet a key
Sign in, open Account settings, and under Render API choose Create key. The key is shown once; store it as a secret in your CI system (for example FLOWGRAPH_API_KEY). Keep keys on servers and build systems, never in a web page.
A key renders and validates by default. Tick Read and change saved diagrams to also let it read and update the diagrams in your account (Pro and Pro Max), which is what coding assistants need.
Validate a diagram
POST /v1/validate checks whether Mermaid can draw the code:
curl -s https://flowgraph.studio/v1/validate \
-H "Authorization: Bearer $FLOWGRAPH_API_KEY" \
-H "Content-Type: application/json" \
-d '{"code": "flowchart LR\n A --> B"}'
A readable diagram returns { "valid": true }. A broken one also returns HTTP 200, with valid: false, an error message, and a line number when one is known, so check valid rather than the status code. A valid check uses one render from your monthly allowance; an invalid one is refunded.
Render an image
POST /v1/render returns SVG (the default) or PNG. Send the code as JSON, or as a file in a multipart form:
curl https://flowgraph.studio/v1/render \
-H "Authorization: Bearer $FLOWGRAPH_API_KEY" \
-F "diagram=@docs/checkout.mmd;type=text/plain" \
-F "theme=@docs/diagram.theme.json;type=application/json" \
-F "format=png" -F "scale=2" \
--output docs/checkout.png
| Field | Meaning |
|---|---|
code or diagram |
The Mermaid source (required); in a form, diagram can be a file |
theme |
A theme object, or the Theme JSON file exported from the editor |
format |
svg or png |
scale |
PNG pixel density, 1 to 4 (default 2) |
transparent |
true for a transparent PNG |
The theme file is the bridge between design and the build: style a diagram in the editor, export Theme JSON, commit it, and every rendered diagram matches. Saved positions from Manual mode (the %% flowgraph-layout line) are kept too.
A GitHub Actions example
This workflow validates every .mmd file under docs/ and renders each one to SVG:
name: Diagrams
on: [push, pull_request]
jobs:
diagrams:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Validate and render
env:
FLOWGRAPH_API_KEY: ${{ secrets.FLOWGRAPH_API_KEY }}
run: |
set -euo pipefail
for file in $(find docs -name '*.mmd'); do
body=$(jq -Rs '{code: .}' "$file")
result=$(curl -s https://flowgraph.studio/v1/validate \
-H "Authorization: Bearer $FLOWGRAPH_API_KEY" \
-H "Content-Type: application/json" -d "$body")
if [ "$(echo "$result" | jq -r .valid)" != "true" ]; then
echo "::error file=$file::$(echo "$result" | jq -r .error)"
exit 1
fi
curl -sf https://flowgraph.studio/v1/render \
-H "Authorization: Bearer $FLOWGRAPH_API_KEY" \
-F "diagram=@$file;type=text/plain" -F "format=svg" \
--output "${file%.mmd}.svg"
done
Add a theme file to the render step to apply your house style.
If Node.js is available in the job, the flowgraph-cli package does the same in one line, and also finds the ```mermaid blocks in Markdown files: npx --yes flowgraph-cli@0.1.1 check docs fails the job and names the file and line of each broken diagram, and render docs --out-dir build/diagrams writes the images. See validating Mermaid diagrams in CI for a complete workflow.
Limits and headers
| Plan | API renders a month | Watermark |
|---|---|---|
| Free | 50 | Yes |
| Pro | 5,000 | No |
| Pro Max | 20,000 | No |
Each successful render returns X-Quota-Limit, X-Quota-Remaining and X-Quota-Reset headers, failed renders are refunded, and GET /v1/usage reports the month's usage. A key can make up to 30 requests a minute. Diagrams can be up to 200,000 characters.
Update saved diagrams and connect coding assistants
With a key that can read and change saved diagrams, the API reaches the diagrams in your account:
GET /v1/diagramslists projects and diagrams;GET /v1/diagrams/:idreturns one with its code, theme, and version.POST /v1/diagramscreates one;PUT /v1/diagrams/:idupdates it, sending the version you read asbaseVersion. If someone changed it since, you get HTTP 409 with the current version instead of overwriting their work, and every update lands in version history.
The same capabilities are available to coding assistants over MCP at https://flowgraph.studio/mcp, with the key as a bearer token. Its tools validate and render Mermaid, search icons, and list, read, create and update saved diagrams. The Render API section of Account settings shows the exact setup line for Claude Code and a JSON configuration for other clients.
flowchart LR
ai[Coding assistant] -->|MCP| fg[Flowgraph Studio]
fg --> v[validate_mermaid]
fg --> r[render_diagram]
fg --> s[search_icons]
fg --> d[list, get, create,<br/>update diagrams]The full reference is on the API page. For the diagrams themselves, see the flowchart cheat sheet and how to draw an AWS architecture diagram with Mermaid.
More guides
- Animate a Mermaid diagram as a short technical explanationTurn a static Mermaid flow into a captioned explanation. Plan the story, select GIF or video output, and check that animation preserves the system's meaning.
- Explain an Azure background-job architecture with MermaidDraw an illustrative Azure job-processing architecture with API, queue, worker, and storage boundaries. Explain acknowledgment, completion, and failure handling.
- Build a consistent technical carousel with a reusable brand kitCreate readable technical carousel slides using a reusable brand kit. Keep colors, typography, diagrams, and export checks consistent across the series.