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.

Updated November 19, 2026 · 2 min read

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 image

Get 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/diagrams lists projects and diagrams; GET /v1/diagrams/:id returns one with its code, theme, and version.
  • POST /v1/diagrams creates one; PUT /v1/diagrams/:id updates it, sending the version you read as baseVersion. 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