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…
kidis your key's public prefix — thekeyPrefixthe account page (andGET /api/me) shows. It identifies the key; it is not a secret.expis unix seconds, required. It must be in the future and at most 30 days ahead; further out is rejected.sigishex(HMAC-SHA256(secret, kid + "." + exp + "." + canonicalQuery))wheresecret = hex(sha256(api_key))— one hash of the key you already hold. We never store the plaintext key, so that digest is what both sides can compute.
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
- Successful renders are immutable for one year:
Cache-Control: public, immutable, max-age=31536000. Browsers and the edge hold the bytes. - The query string is the chart's identity. Two URLs with the same parameters (in any order) are the same image; changing a rendered parameter produces a new URL and a new render.
- Cache-bust parameters (
_,cb,cachebust,t) are stripped before rendering and before keying. They cannot be used to bust the cache, and they never create a second render — that is intentional, so timestamped embeds do not inflate usage. - Cached hits are not metered. If you need to change a chart, change the data in the URL; if you need to invalidate an image that is already in someone's browser cache, the URL has to change.
Errors and limits
200 image/pngfor every URL whose data decodes — including URLs with unknown or invalid parameters (they degrade and are reported).400 JSONonly when thechdpayload cannot be interpreted at all. Never an error image.401 JSONfor a malformed, unknown or revoked API key.429 JSONwithRetry-Afterfor rate limits and the free monthly cap.X-UrlChart-Metaon successful renders carries the parsed axes, series-to-axis assignment, and the degraded/ignored/unsupported lists. It is the same data the tester shows.
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_…"
- Account view — send the key as a bearer token, as
?key=or in anx-api-keyheader, or call from a signed-in browser session (the session cookie counts). A paid account is metered by its active key, because that is where its renders land. - Anonymous view — no credentials: you get the free-tier counters for the IP hash you are calling from, which is the same hash your anonymous renders are metered under. The IP itself is not stored.
- A malformed, unknown or revoked key is
401JSON with areason. A signed-in free account without an entitled subscription keeps the free view rather than showing an empty paid panel. - Counters move only on a unique render — a request that missed the edge cache and produced an image. Cache hits,
4xxand5xxare never counted, so this is usage of image renders, not of requests.
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
}
tier,month(YYYY-MM, UTC),uniqueRenders,todayRendersandrateLimitPerMinuteare present in both shapes.- Free only:
monthlyCapis the hard monthly cap andwarningexplains a lapsed subscription. The free canvas cap (1000 px per side / 1 MP) is a rendering rule, not a usage counter. - Paid only:
keyPrefixis the key's public display prefix (never the key),plan/planAmount/currency/status/currentPeriodEnddescribe the subscription,monthlySoftCapanddailyTriggerare the fair-use lines, andneedsContactistrueonce the account has crossed one of them in the current month. Crossing a line only throttles — it never blocks a paying key. - Both numbers are
0for a scope that has not rendered anything this month; a fresh free caller sees zeros, not an error.