Build with the REST API.

Check Mermaid syntax before you render a diagram. Use the same API to save private diagrams and publish snapshots.

Set up your key

Sign in to account settings.
Create an API key with the MERMAID_RENDER permission.
Copy the key. You can see the complete key only once.
Store it in the MERMAIDDESK_API_KEY environment variable on your server.

Keep the key out of browser code, URLs, and source control. Send it in the Authorization: Bearer header.

The examples use Node.js 22 or later. They do not need an additional package. Replace YOUR_API_KEY below.

Bash — set your key

export MERMAIDDESK_API_KEY='YOUR_API_KEY'

Use PowerShell

PowerShell — set your key

$env:MERMAIDDESK_API_KEY = 'YOUR_API_KEY'

Validate Mermaid

Save this example as validate.mjs. Run node validate.mjs in the same terminal.

JavaScript — validate.mjs

const key = process.env.MERMAIDDESK_API_KEY;
if (!key) throw new Error("Set MERMAIDDESK_API_KEY.");

const source = "flowchart LR\n  App --> API\n  API --> Database";
const response = await fetch(
  "https://www.mermaiddesk.com/api/v1/mermaid/validate",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${key}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ source }),
    signal: AbortSignal.timeout(30000),
  },
);
if (!response.ok) throw new Error(await response.text());

const { data } = await response.json();
if (!data.valid) throw new Error(JSON.stringify(data.diagnostic));
console.log("Mermaid syntax is valid.");

A valid diagram prints Mermaid syntax is valid. Validation saves no diagram and creates no public link.

Invalid Mermaid also returns HTTP 200. Check data.valid. If it is false, use data.diagnostic to correct the source.

The diagnostic contains a summary and available line and column details. Validation checks syntax. Rendering can still fail because of resource limits.

Use curl in Bash

Bash — validate with curl

curl --fail-with-body \
  https://www.mermaiddesk.com/api/v1/mermaid/validate \
  --header "Authorization: Bearer $MERMAIDDESK_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"source":"flowchart LR\n  App --> API"}'

Read data.valid in the response. A successful HTTP request does not confirm valid Mermaid syntax.

JSON — valid response

{ "data": { "valid": true } }

Render a file

Save this example as render.mjs. Run node render.mjs. It writes diagram.svg in the current folder.

JavaScript — render.mjs

import { writeFile } from "node:fs/promises";

const key = process.env.MERMAIDDESK_API_KEY;
if (!key) throw new Error("Set MERMAIDDESK_API_KEY.");

const response = await fetch(
  "https://www.mermaiddesk.com/api/v1/mermaid/render",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${key}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      source: "flowchart LR\n  App --> API\n  API --> Database",
      format: "svg",
      theme: "light",
    }),
    signal: AbortSignal.timeout(30000),
  },
);
if (!response.ok) throw new Error(await response.text());
if (!response.headers.get("content-type")?.startsWith("image/svg+xml")) {
  throw new Error("Expected an SVG file.");
}
await writeFile("diagram.svg", new Uint8Array(await response.arrayBuffer()));
console.log("Saved diagram.svg.");

The response contains file bytes. Errors contain JSON. Check the status and content type before you save the file.

Use svg, png, or pdf for format. Change the content type check and filename to match. Use light or dark for theme.

Save and share diagrams

Use these endpoints when you need stored diagrams. See the OpenAPI reference for complete request and response schemas.

POST /api/v1/diagrams: Create a private diagram. Send source and an optional title. Add DIAGRAMS_WRITE to your key.
GET /api/v1/diagrams: List your diagrams. Add DIAGRAMS_READ to your key.
PATCH /api/v1/diagrams/{diagramId}: Update a diagram. Read it first. Include its updatedAt value as expectedUpdatedAt.
POST /api/v1/diagrams/{diagramId}/publish: Publish a snapshot. Include name and expectedUpdatedAt. This makes the saved source public. Add read and share permissions.

For creation, send a unique Idempotency-Key header. Reuse the key and identical request after a lost response. This prevents duplicate diagrams.

Keep drafts private until you intend to share them. Revoking an API key does not revoke public snapshots.

Handle errors

Read error.code and error.message in JSON error responses. Some responses include error.details.

401 / 403: Check the bearer key and permissions. For plan_limit_reached, check account usage.
409 stale_document: Read the latest diagram. Reconcile your changes before you retry.
422 invalid_mermaid: Correct the source with the diagnostic in error.details.
429 / 503: Wait for the Retry-After interval. Limit the number of retries.
504 render_timeout: Simplify the diagram before you retry.

For agent tool calls, use the MCP setup guide.

Choose permissions

Select only the permissions that your client needs. Each permission applies to all diagrams in your account.

MERMAID_RENDER: Validate Mermaid source. Render SVG, PNG, and PDF files.
DIAGRAMS_READ: List and read private diagrams. Download Mermaid source.
DIAGRAMS_WRITE: Create, update, and delete private diagrams. This permission does not include read access.
DIAGRAMS_SHARE: Revoke public snapshots. Add DIAGRAMS_READ to publish snapshots.

To export a saved diagram as SVG, PNG, or PDF, select both DIAGRAMS_READ and MERMAID_RENDER.

Check limits

The Free plan includes 100 saved diagrams and 200 API renders per UTC calendar month. REST and MCP share this allowance.

Validation does not use the monthly render allowance. Request and source size limits still apply. Source can contain up to 50,000 UTF-16 code units.

View your remaining allowance and reset date in account settings. There is no self-service upgrade at this time.