Docs

Your first chart URL in three steps

No SDK, no signup: a chart is a URL that returns a PNG. Everything below works with a plain curl, an <img> tag or any HTTP client.

1. Build the URL

Start with the endpoint and add legacy parameters:

https://urlchart.com/chart?cht=bvg&chs=400x200&chd=t:10,40,80&chxt=y

cht=bvg is vertical grouped bars, chs=400x200 the image size, chd=t:… the data and chxt=y one y axis. Open it in a browser tab and you have the image.

Canvas size: the paid tier accepts up to 3000 px per side and 9,000,000 px total. The free tier is capped at 1000 px per side / 1,000,000 px total — a larger chs is not an error: the chart is scaled down proportionally and the size actually rendered is reported in X-UrlChart-Meta as a degraded entry (for example chs 1500x1500 exceeds the free-tier maximum (1000 px per side, 1 MP total); rendered at 1000x1000). The Tester reports the same note before you embed anything.

2. Add a key when you need production limits

Without a key you get the free tier: 60 requests/minute, 1,000 unique renders per month, and a canvas of at most 1000 px per side / 1 MP. With a paid subscription you get a key; add it as a query parameter, or send it as a bearer token or in an x-api-key header:

https://urlchart.com/chart?cht=bvg&chd=t:10,40,80&key=uc_live_…

The key is removed from the origin request and from the cache key, so a paid and a free request for the same chart are the same chart with different tier variants (the free variant is capped at 1000 px per side / 1 MP; the paid variants are not). If a key is malformed or revoked you get 401 JSON — a broken key is an error you can see, not a silent downgrade.

Signed URLs (no key in the image URL)

A key embedded in a chart URL is a long-lived secret in a leaky place: email templates, image proxies, page source. A signed URL carries an expiry instead, so a leaked embed stops working on its own — and the key itself never appears in the URL.

https://urlchart.com/chart?cht=bvg&chs=400x200&chd=t:10,40,80&chxt=y
  &kid=uc_live_1a2b3c4d&exp=1798761600&sig=…64 hex characters…

Canonical query — exactly the bytes you send: the canonical string is built from the query string exactly as it will be sent, byte for byte. Take the raw query string (everything after ?), drop sig, kid and exp, split on & and then at the first =, sort the pairs by name, and join them back as name=value with &. Nothing is decoded and nothing is re-encoded: if the URL carries percent-encoded values, the encoded forms are what get signed. chl=Hello%20World signs Hello%20World, never a decoded space; chl=Hello+World signs Hello+World. In the example below none of the values needs escaping, so the URL bytes and the canonical bytes happen to be identical — that is a property of the example, not a rule.

import { createHash, createHmac } from 'node:crypto';

const apiKey = process.env.URLCHART_KEY;
const kid = apiKey.slice(0, 16);
const exp = Math.floor(Date.now() / 1000) + 3600; // ≤ 30 days
const params = { cht: 'bvg', chs: '400x200', chd: 't:10,40,80', chxt: 'y' };

// The values go into the message exactly as they will appear in the URL
// (percent-encoding included): do not decode them before signing.
const canonical = Object.entries(params)
  .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
  .map(([name, value]) => `${name}=${value}`)
  .join('&');
const secret = createHash('sha256').update(apiKey).digest('hex');
const sig = createHmac('sha256', secret).update(`${kid}.${exp}.${canonical}`).digest('hex');

console.log(`https://urlchart.com/chart?${canonical}&kid=${kid}&exp=${exp}&sig=${sig}`);

A verified signature is treated exactly like presenting the key: paid tier, metered to the account, paid cache variant. Any failure — missing parameter, bad signature, expired expiry, expiry more than 30 days out, unknown or revoked kid — is not an error: the image is still served on the free tier (same 1000 px / 1 MP canvas cap and IP limits as an anonymous request), and X-UrlChart-Meta carries auth with verified:false and the reason. Rotating or revoking the key immediately invalidates signatures minted with it.

The three auth parameters are removed before rendering and before the cache key, so re-signing the same chart on every page render is a cache hit, not a new billable render. kid, exp and sig are reserved names: a URL that uses one for something else is treated as a failed signature and served as the free tier.

3. Embed it

<img src="https://urlchart.com/chart?cht=bvg&chd=t:10,40,80"
     width="400" height="200" alt="Quarterly signups">

Set width and height to chs so the page does not reflow. That is the whole integration. The same tag is what you paste into an email template — email clients have no JavaScript, so the PNG is the chart. Two extra rules apply there (charts in email).

Cache behaviour

Errors and limits

JSON charts

POST /chart also accepts a Chart.js configuration body and returns a PNG. That path is for callers who already hold Chart.js JSON; the legacy parameter endpoint above is the compatibility surface. POST /gchart is rejected — /gchart is GET-only by contract.

Usage API

GET /api/usage (or HEAD) returns the counters for the current calendar month (UTC) and for today. Authentication is optional: the endpoint answers whichever tier is asking, so the same call works for a script with a key and for a browser tab with nothing.

curl https://urlchart.com/api/usage
curl -H "Authorization: Bearer uc_live_…" https://urlchart.com/api/usage
curl "https://urlchart.com/api/usage?key=uc_live_…"

Free / anonymous response (warning is null, or "subscription-expired" when a key was sent but its subscription has lapsed):

{
  "tier": "free",
  "month": "2026-11",
  "warning": null,
  "uniqueRenders": 12,
  "todayRenders": 3,
  "monthlyCap": 1000,
  "rateLimitPerMinute": 60
}

Paid response — the same counters plus the account's plan and fair-use state:

{
  "tier": "paid",
  "month": "2026-11",
  "keyPrefix": "uc_live_1a2b3c4d",
  "plan": "monthly",
  "planAmount": "29.00",
  "currency": "USD",
  "status": "active",
  "currentPeriodEnd": "2026-12-17T12:00:00.000Z",
  "uniqueRenders": 1234,
  "todayRenders": 56,
  "monthlySoftCap": 100000,
  "dailyTrigger": 10000,
  "needsContact": false,
  "rateLimitPerMinute": 120
}