API reference

One endpoint, /chart. Send a Chart.js config as JSON and get a PNG back. The OpenAPI 3.1 spec is at /openapi.json.

Quick start

Put the URL in an <img>, an email, a Markdown file or a Slack message. No key is needed. Free images carry a small watermark.

<img src="https://chartpng.dev/chart?c=%7B%22type%22%3A%22bar%22%2C%22data%22%3A%7B%22labels%22%3A%5B%22Mon%22%2C%22Tue%22%2C%22Wed%22%5D%2C%22datasets%22%3A%5B%7B%22label%22%3A%22Signups%22%2C%22data%22%3A%5B12%2C19%2C7%5D%7D%5D%7D%7D&w=600&h=360" alt="Signups by day" />

The config never runs as code, so functions in it are not supported. Send JSON in Chart.js 4 syntax; the common options of a Chart.js v2 config, the kind QuickChart uses by default, are translated. The typical slips of language models are repaired for you (see lenient parsing). A GET accepts QuickChart's parameter names chart, width, height, backgroundColor and devicePixelRatio. QuickChart's other parameters, such as version, format and key, are refused with a 400.

• Chart types: bar, line, pie, doughnut, radar, polarArea, scatter, bubble.
• Responses are PNG on success and {"error": "..."} on failure.
• Browsers can load images and call /chart from any site (CORS is open), but without the Authorization header. Use signed URLs there.

GET /chart

All parameters go in the query string. Unknown or repeated parameters are refused with a 400, so a URL cannot be varied to bypass the cache. A QuickChart name and its short name count as the same parameter.

With a GET, k and s make a signed URL for a Pro key. See signed URLs.

POST /chart

The same fields in a JSON body of at most 20 KB. Use it for configs too long for a URL and for server-side calls with a Pro key.

• Send Content-Type: application/json. The name c may hold the config as an object or as a JSON string.
• Send Authorization: Bearer <key> for a Pro key. The response is then Cache-Control: private, no-store.
• Field names are the short ones only. QuickChart names are not mapped in a body, and unknown fields are ignored.
• A body that is not a JSON object is answered as if c were missing.

A missing or unknown key is not an error. The chart is drawn with the watermark, as on the free plan.

POST /chart.json

The same body as POST /chart, but nothing is drawn. It answers with the public URL of the free plan and the text and snippets to paste the image in a page, an email or Slack. No key is needed.

curl https://chartpng.dev/chart.json \
  -H "Content-Type: application/json" \
  -d '{"c":{"type":"bar","data":{"labels":["Mon","Tue","Wed"],"datasets":[{"label":"Signups","data":[12,19,7]}]}},"w":600,"h":360}'

{ "url": "https://chartpng.dev/chart?c=...&w=600&h=360", "alt": "Bar chart: ...", "markdown": "![...](...)", "html": "<img src="..." alt="..." width="600" height="360">", "fixes": [] }

• fixes lists the codes of the repairs applied to the config, the same ones GET /chart puts in X-ChartPNG-Fixes (see lenient parsing), and is an empty list when nothing was repaired. The QuickChart converter reads it.
• Validation and limits are those of /chart, with the same errors. The URL is the free plan's, so it has the watermark and the 4 megapixel limit, and it carries the config as repaired by lenient parsing. The config is drawn once to check it, so a theme or preset that does not exist or numbers too large to draw get their 400 here and not when the image is fetched. A large config makes a long URL, about twice the size of the config. Over 14,000 characters you get a 400 with url_too_long: Vercel's CDN answers 414 above 14 KB, so use POST /chart instead. Slack's image block accepts an image_url of at most 3000 characters, which a config of about 1.5 KB already reaches.
• alt is built from values in your data, with no model: chart type, title, number of series, the highest value with its label, the last value and, for line, the change from first to last. It has at most 2000 characters, the limit of Slack's image alt_text. Use it as is.
• html escapes quotes and < in the alt. Its width and height are CSS sizes, so a dpr of 2 does not double them.
• GET /chart and POST /chart answer with the same text in the X-Chart-Alt header, percent-encoded: read it with decodeURIComponent. Browsers can read it from any site.

Short URLs

POST /c takes the same body as POST /chart, keeps the chart for 90 days and answers with a short image URL, https://chartpng.dev/c/{id}.png. The URL stays short however large the config is, so it fits Slack's 3000-character image_url, emails and Markdown.

curl https://chartpng.dev/c \
  -H "Content-Type: application/json" \
  -d '{"c":{"type":"bar","data":{"labels":["Mon","Tue","Wed"],"datasets":[{"label":"Signups","data":[12,19,7]}]}},"w":600,"h":360}'

{ "id": "Ab3dE5gH7jK", "url": "https://chartpng.dev/c/Ab3dE5gH7jK.png", "expires": "2027-02-01T09:00:00.000Z", "alt": "Bar chart: ...", "markdown": "![...](...)", "html": "<img src="..." ...>" }

• Validation, limits and errors are those of /chart. The config is stored as repaired by lenient parsing, with the X-ChartPNG-Fixes header on the answer, and it is drawn once to check it, so errors that only show when drawing get their 400 here.
• GET /c/{id}.png draws the stored chart exactly as /chart would, with the same X-Chart-Alt header. Unknown or expired ids get a 404, and a query string a 400.
• The same chart sent again gets the same id and another 90 days from that moment. Ids come from a hash of the chart, so they cannot be guessed one after another.
• Send Authorization: Bearer <key> to make the short URL with a Pro key. The image then has no watermark for as long as the key stays paid; if the key is cancelled or blocked, the same URL draws with the watermark. The key never appears in the URL. Signed fields (k, s) are ignored here.
• Each address can make 200 short URLs a month on the free plan, and each Pro key 5,000. Free short URLs also share a daily storage budget. Past either limit, POST /c answers 429; POST /chart.json and POST /chart still work.
• The image is cached like a /chart image, until the short URL expires: Cache-Control: public, max-age=86400, s-maxage= the seconds left, immutable.
• Each fetch of a short URL that is not served from the cache counts as a render, like /chart.

Signed URLs

Chart images end up in emails and on public pages, and anyone who sees the page sees the URL. So the key never goes in a URL. A signed URL carries two values instead: k, an id derived from the key by a hash, and s, an HMAC-SHA256 ofc, w, h, bkg and dpr made with the key. The server checks it and draws without the watermark.

• Change any of those five values and the signature stops matching. The image is drawn with the watermark.
• theme, palette and preset are signed too, after those five, when the URL has any of them. A URL without them is signed as it always was, so URLs signed earlier keep working. Add, drop or change one of the three and the signature stops matching. Settings inside c are covered with it.
• Someone who copies the URL can reuse that one chart, not your key and not other charts.
• Sign on your server. A key in browser code is a leaked key.
• The @chartpng/client npm package does the signing. Run npm install @chartpng/client; it needs Node 22 or later.
• Keep URLs under 8,000 characters. Some email clients break past that. For large data, use renderChart or POST and attach the PNG.

import { chartUrl } from '@chartpng/client';

const config = {
  type: 'bar',
  data: {
    labels: ['Mon', 'Tue', 'Wed'],
    datasets: [{ label: 'Signups', data: [12, 19, 7] }],
  },
};

// Runs on your server. The URL carries k and s, never the key.
const url = chartUrl(config, {
  apiKey: process.env.CHARTPNG_API_KEY,
  width: 600,
  height: 360,
  dpr: 2,
});

Limits

Errors

Every error is JSON, {"error": "..."}, with CORS headers so browsers can read it. Nothing is drawn when a request is refused.

A report preset that is unknown, or that does not fit the config, is also a 400. The body carries only the error message; bad_preset (and bad_option for the shape errors above) is the internal reason these errors are counted under, not a field you can read. See report presets.

Theme

A config that does not style itself gets the ChartPNG look. Anything your config sets wins over it.

• A blue and orange palette for datasets without backgroundColor or borderColor.
• Horizontal grid lines only, rounded bars, smooth lines with a soft area under a single line.
• Legend at the top left when a series has a name or there are several. Pie and doughnut put it on the right.
• Values drawn on the chart: above bars (up to 2 datasets and 12 labels), at the last point of a line, and the total inside a doughnut.
• Light text on dark backgrounds. bkg as black, #rgb, #rrggbb or rgb() counts as dark below mid-grey.

Turn the whole theme off with options.plugins.chartpng.theme set to false (or the parameter theme=false). Chart.js then draws your config as it is.

{
  "type": "bar",
  "data": { "labels": ["Mon", "Tue"], "datasets": [{ "data": [12, 19] }] },
  "options": { "plugins": { "chartpng": { "theme": false } } }
}

Keep the theme and drop only the numbers drawn on the chart with values set to false:

"options": { "plugins": { "chartpng": { "values": false } } }

Named themes

Pick one of six palettes with the theme parameter, or with options.plugins.chartpng.theme in the config. They are the same setting: when both are set, the config wins. Light or dark is chosen from bkg as in the theme above, and colours your datasets set still win. An unknown name is a 400. false still turns the theme off.

https://chartpng.dev/chart?c={...}&theme=ocean

{ options: { plugins: { chartpng: { theme: 'editorial' } } } }

Every theme colour is checked in the test suite against two light backgrounds (white and paper) and two dark ones (near-black and black), with the WCAG contrast formula: text is at least 4.5:1. Series colours of vivid, ocean and editorial, and the dark variants of mono and colorblind, are at least 3:1. The default palette and the light variants of mono and colorblind keep a few colours below that (the Okabe-Ito yellow, for one), listed in that test. A custom palette is not checked: contrast is yours to judge.

default

The look above. Same as no theme at all.

editorial

Blue, rust and grey, with lighter tones on dark backgrounds.

mono

Ink, grey and paper tones. On dark backgrounds the greys run from paper to mid grey.

colorblind

The Okabe-Ito palette, chosen to stay apart for colour-blind readers. Its black becomes light ink on dark backgrounds.

vivid

Saturated blue, orange, green and purple for dashboards and slides. Lighter tones on dark backgrounds.

ocean

Blues and teal with a coral accent, then olive, violet and ochre. Lighter tones on dark backgrounds.

Palette

Your own series colours: palette as a parameter, or options.plugins.chartpng.palette in the config as a list or a comma-separated string. It replaces the theme's colours for datasets that set none, on light and dark backgrounds alike; the rest of the theme stays. When both are set, the config wins.

• 1 to 12 colours, #rgb or #rrggbb. The # is optional: in a URL it must be written %23, so palette=1f5fad,e0712c is easier.
• With more series than colours, the colours repeat in order. Pie and doughnut slices use them in order too, and the ranking preset highlights its first bar with the first.
• Anything else is a 400, with the message in the errors table: a colour name, an alpha channel (#rrggbbaa), an empty item, no colour or more than 12.

https://chartpng.dev/chart?c={...}&palette=1f5fad,e0712c,13896f
https://chartpng.dev/chart?c={...}&palette=%231f5fad,%23e0712c
{ options: { plugins: { chartpng: { palette: ['#1f5fad', '#e0712c', '#13896f'] } } } }

Report presets

A preset turns a plain config into a report image: a KPI, a ranking, a comparison, a funnel or a gauge. Set it under options.plugins.chartpng. No new chart types: a preset is a ready-made set of Chart.js options on top of the theme. Anything your config sets wins over the preset.

{
  "type": "line",
  "data": { "labels": ["W1", "W2", "W3"], "datasets": [{ "label": "MRR", "data": [8200, 9100, 9840] }] },
  "options": { "plugins": { "chartpng": { "preset": "kpi", "previous": 9100, "prefix": "$" } } }
}

One guide for each preset, with a config, a GET URL and a curl example: KPI with a sparkline, ranking chart comparison with the previous period, funnel chart and gauge chart. An n8n workflow that posts them to Slack is in the n8n guide, and the Slack message itself in Charts in Slack.

Output presets

A report preset says what the chart is; an output preset says where the image is going. They share the name preset and no values, so one request can have one of each, separated by a comma: preset=ranking,email. Use the preset parameter, or options.plugins.chartpng.preset in the config as "email" or "ranking,email". For each kind, the config wins when both set one.

• w, h and dpr that the request sends win; the preset only fills in what is missing. bkg that the request sends is kept, unless it is transparent (transparent, an empty value, rgba() or a hex colour with alpha below 1): inboxes and chats draw their own colour behind an image, so the background becomes white.
• Roomier margins around the chart than the default look, and no type below 11 pixels: a font size under 11 in your config is raised to 11, and so is the type of the watermark. A report preset that lays out its own margins, such as kpi, keeps them.
• The header row is yours: the title, the subtitle and the source line come from options.plugins.title, options.plugins.subtitle and options.plugins.chartpng.source. The preset adds none.
• theme: false keeps the size, the pixel ratio and the background, and drops the margins and the type floor.
• An unknown value, or two of one kind (email,slack), is a 400, see the errors table.
• POST /chart.json puts preset=email in the URL it returns, with w, h and dpr written out, and an html snippet at the CSS size.

https://chartpng.dev/chart?c={...}&preset=email
https://chartpng.dev/chart?c={...}&preset=ranking,slack&w=640
{ options: { plugins: { chartpng: { preset: 'ranking,email' } } } }

<img src="https://chartpng.dev/chart?c={...}&preset=email" width="600" alt="Signups by day" style="max-width: 100%; height: auto;" />

Lenient parsing

Models write almost-JSON. ChartPNG repairs the usual slips before it reads the config, and tells you what it changed in theX-ChartPNG-Fixes response header: the codes of the repairs applied, separated by commas. When nothing was repaired the header is absent. If a config cannot be repaired, the request is refused with the same clear error as always.

• Functions are never run. A function written as text is removed from the config. Nothing in the config is evaluated.
• The limits apply after the repair: 16 KB, 16 levels of nesting and 100 ticks.
• Browsers can read X-ChartPNG-Fixes from another site: it is exposed with Access-Control-Expose-Headers.
• A code in the header means the config you sent was not strict JSON. Send the corrected form next time.

curl -si -G https://chartpng.dev/chart \
  --data-urlencode "c={type:'bar',data:{labels:['Mon','Tue'],datasets:[{data:[12,19],}]}}" \
  | grep -i '^x-chartpng-fixes'

# x-chartpng-fixes: trailing_comma,single_quotes,unquoted_keys

Caching

• The same URL gives the same image. A GET without a Bearer header is answered with Cache-Control: public, max-age=86400, s-maxage=31536000, immutable: browsers keep it a day and the CDN keeps it up to a year.
• Any change to the URL is a new render. To refresh a chart, change something in c.
• A request with a Bearer header is answered with private, no-store. Nothing shared keeps it.
• The cache can be emptied when the service is redeployed, so an old URL may be drawn again later.

Examples

curl

GET, free plan:

curl -G https://chartpng.dev/chart \
  --data-urlencode 'c={"type":"bar","data":{"labels":["Mon","Tue","Wed"],"datasets":[{"label":"Signups","data":[12,19,7]}]}}' \
  -d w=600 -d h=360 -d dpr=2 \
  -o chart.png

POST with a Pro key:

curl https://chartpng.dev/chart \
  -H "Authorization: Bearer $CHARTPNG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"c":{"type":"bar","data":{"labels":["Mon","Tue","Wed"],"datasets":[{"label":"Signups","data":[12,19,7]}]}},"w":600,"h":360,"dpr":2}' \
  -o chart.png

Node

With fetch (Node 18 or later; the @chartpng/client package needs 22):

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

const config = {
  type: 'bar',
  data: {
    labels: ['Mon', 'Tue', 'Wed'],
    datasets: [{ label: 'Signups', data: [12, 19, 7] }],
  },
};

const res = await fetch('https://chartpng.dev/chart', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer ' + process.env.CHARTPNG_API_KEY,
  },
  body: JSON.stringify({ c: config, w: 600, h: 360, dpr: 2 }),
});
if (!res.ok) throw new Error((await res.json()).error);
await writeFile('chart.png', Buffer.from(await res.arrayBuffer()));

With the @chartpng/client package. chartUrl is under signed URLs; renderChart returns the PNG bytes:

import { writeFile } from 'node:fs/promises';
import { renderChart } from '@chartpng/client';

const config = {
  type: 'bar',
  data: {
    labels: ['Mon', 'Tue', 'Wed'],
    datasets: [{ label: 'Signups', data: [12, 19, 7] }],
  },
};

// Same call as the fetch above. Throws "ChartPNG 400: ..." on an error.
const png = await renderChart(config, { apiKey: process.env.CHARTPNG_API_KEY, width: 600, height: 360, dpr: 2 });
await writeFile('chart.png', png);

Python

import os
import requests

config = {
    "type": "bar",
    "data": {
        "labels": ["Mon", "Tue", "Wed"],
        "datasets": [{"label": "Signups", "data": [12, 19, 7]}],
    },
}

res = requests.post(
    "https://chartpng.dev/chart",
    headers={"Authorization": f"Bearer {os.environ['CHARTPNG_API_KEY']}"},
    json={"c": config, "w": 600, "h": 360, "dpr": 2},
    timeout=20,
)
if not res.ok:
    raise RuntimeError(res.json()["error"])
with open("chart.png", "wb") as f:
    f.write(res.content)

MCP server

The @chartpng/mcp server lets an AI agent draw charts. It needs Node 22 or later. It has two tools: chart_url returns a public PNG URL, signed if you set a key, and render_chart returns the image.

Claude Code:

claude mcp add -s user -e CHARTPNG_API_KEY=your-key chartpng -- npx -y @chartpng/mcp@0.2.0

Claude Desktop, Cursor and other clients, in their mcpServers config:

{
  "mcpServers": {
    "chartpng": {
      "command": "npx",
      "args": ["-y", "@chartpng/mcp@0.2.0"],
      "env": { "CHARTPNG_API_KEY": "optional, removes the watermark" }
    }
  }
}

Keep the key in your user-level config, not in a project file that gets committed. Without a key it works and images carry the watermark. CHARTPNG_BASE_URL changes the server, and defaults to https://chartpng.dev.