canonical: https://jentic.com/apis/mermaidchart.com/mermaidchart

# Mermaidchart Mermaid API

The Mermaid API validates and renders Mermaid diagram code for programs such as agents, LLM tool calls, and CI pipelines. The validate operation reports whether diagram code parses and, if not, why, along with the detected diagramType. The render operation turns the same code into SVG, PNG, or PDF, with PNG options for scale and background and a PDF fit option, using the latest Mermaid release. A balance operation shows the key owner's remaining API credits and what each endpoint costs.

## For AI agents

Validate Mermaid diagram code and render it to SVG, PNG, or PDF so an agent can check and ship the diagrams it writes.

## Scope

Does not store diagrams, host a diagram editor, or render other diagram languages such as PlantUML. Use for validating and rendering Mermaid code only.

## Capabilities

- Validate Mermaid diagram code and get back whether it is valid, the diagramType, and the reason it fails
- Render diagram code to svg, png, or pdf by setting the required format field
- Control PNG output with scale and background, or set pdf fit to size the page to the diagram
- Skip the shared render cache for a single call by sending cache false
- Check the key owner's API credit balance and the per-endpoint cost before a batch of renders

## Use cases

### Agent self-checks the diagrams it writes, through Jentic

LLMs often write Mermaid code that almost parses. An agent connected through Jentic sends its draft to the validate operation, reads the error message when the code is invalid, fixes it, and only then calls render to produce the final SVG or PNG. Your Mermaid key stays on your own Jentic One instance, and your rules decide whether the agent may call render as well as validate.

Example prompt: POST `/v1/validate` with code 'flowchart TD\n  A[Start] --> B[Done]'; if valid is false, correct the code from the returned message and validate again, then POST `/v1/render` with format 'svg'

### Diagrams in CI pipelines and docs builds

A docs build can render every Mermaid block to static images instead of shipping a client-side renderer. The render operation takes code and format, returns the image bytes with the matching content type, or a JSON envelope when the request accepts application/json. A failed parse returns ERR_DIAGRAM_INVALID so the pipeline can stop on a broken diagram.

Example prompt: POST `/v1/render` with code from docs/architecture.mmd, format 'png', and png { scale: 2, background: 'white' }, then save the bytes as architecture.png

### PDF exports of diagrams

Product teams that let users download diagrams can render to PDF. With pdf fit set to true the page is the size of the diagram; with fit false the diagram is scaled onto one A4 page, which suits printable reports.

Example prompt: POST `/v1/render` with the diagram code, format 'pdf', and pdf { fit: false } to produce a one-page A4 PDF

### Credit-aware batch rendering

Each keyed call spends API credits from the key owner's balance. Before a large batch, an agent calls the balance operation, which costs no credits, to see the remaining balance and every endpoint's cost, and stops before the allowance runs out.

Example prompt: GET `/v1/balance`, compare the remaining credits with the number of diagrams queued, and render only as many as the balance covers

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/validate` | Validate diagram code |
| POST | `/v1/render` | Render diagram code to svg, png, or pdf |
| GET | `/v1/balance` | Get the credit balance and endpoint costs |
| GET | `/v1/errors.json` | Get the error reference |
| GET | `/health` | Check liveness and deployed build |

## Key resources

- **Validate** — Check diagram code and get validity, diagram type, and error detail
- **Render** — Turn diagram code into SVG, PNG, or PDF bytes or a JSON envelope
- **Balance** — Read the key owner's credit balance and per-endpoint costs
- **Reference documents** — OpenAPI document, API reference page, error reference, and llms.txt

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 69 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 93 / 100
  - Developer Experience & Jentic Compatibility: 66 / 100
  - AI-Readiness & Agent Experience: 50 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 88 / 100
- **View full report:** https://jentic.com/apis/mermaidchart.com/mermaidchart/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the Mermaid API by hand means handling its bearer key, choosing bytes or JSON-envelope responses per content type, and tracking credit spend. Through Jentic you install once, import the Mermaid API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** The Mermaid API carries the diagram and output format inside the request body, so rules bound which operations your agent may call, not which diagrams. Limit the agent to the operations it needs, such as validation, so credit-spending renders are not included unless you add them.
- **Credential handling:** Your Mermaid API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'render a Mermaid diagram to PNG' or 'check if Mermaid code is valid', and Jentic returns the matching Mermaid operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **QuickChart API** — Renders charts and other images from a definition over HTTP
- **CloudConvert API** — Converts rendered SVG or PDF output into other file formats
- **GitHub REST API** — Where diagram source and rendered images are often committed

## FAQ

### What authentication does the Mermaid API use?

Per its OpenAPI spec, the Mermaid API uses a bearer API key (the apiKey scheme) sent as `Authorization: Bearer <key>` on validate, render, and balance. The health, openapi.json, docs, errors.json, and llms.txt reference endpoints need no auth. Through Jentic the key is stored encrypted by your own Jentic One instance and injected when the agent calls.

### Can I render Mermaid diagrams to PNG with a transparent background?

Yes. Send POST `/v1/render` with code, format set to png, and a png object whose background is a CSS colour or transparent. The png scale option sets device pixels per CSS pixel and is lowered automatically when the image would exceed the service ceiling.

### How do I validate a diagram through Jentic?

Install Jentic One with `curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh`, import the Mermaid API from the directory, and store your key. Your agent searches 'validate Mermaid diagram code', gets POST `/v1/validate` with its schema, and sends the code field. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the Mermaid API?

Yes. For example, write a rule that allows only POST `/v1/validate`, so the agent can check diagram code as often as it likes but cannot spend credits on renders. Add POST `/v1/render` when you want it to produce images, and every call it makes is logged.

### Is there a Mermaid MCP server?

You don't need an MCP server to give your agent the Mermaid API. Jentic connects it directly from the API Directory: import it, store your credential once, and your agent calls it.

### What are the rate limits for the Mermaid API?

The spec describes a burst limit reported per key in the ratelimit-policy and ratelimit response headers, with retry-after on a 429. Keyed calls also spend API credits: validate and render cost 1 credit each and balance costs 0. The allowance and burst defaults are service configuration, so check the API reference at https://api.mermaid.ai/v1/docs for current values.

### Is the Mermaid API stable?

No, it is in beta. The spec states that request and response fields, defaults, and limits may change and the Mermaid version can bump without notice, while the /v1 prefix, the error structure, and bearer authentication stay fixed. Every response carries the x-mermaid-api-phase header with the value beta.