DocsREST API

REST API v1

The API manages short charts, reports usage and signs URLs. It needs a verified email address and a paid plan (Starter or above). The machine-readable reference is openapi.yaml.

Base URL: https://app.renderchart.com/api/v1

Authentication

Send your secret key as a bearer token. Keep it on your server: anyone with it can sign URLs and change your charts.

curl https://app.renderchart.com/api/v1/usage \
  -H "Authorization: Bearer rc_sec_live_YOUR_SECRET"

Each key authenticates on its own. A rotated key keeps working for its grace period (24 hours by default); a revoked key stops at once. During the grace period, URLs you sign and charts you create with the old key use the key it was rotated to, so they keep working after the grace period ends.

Limits

120 requests a minute per key. Over that, requests get 429 rate_limited with a Retry-After header.

Errors

Errors from the API have this shape:

{"error": {"code": "plan_required", "message": "Editing a saved chart's data needs the Pro plan. On Starter, save a new short URL instead.", "plan": "pro", "feature": "live_short"}}
Status Code When
401 unauthenticated The bearer token is missing or is not an active secret key.
403 email_unverified The account has not verified its email address.
403 plan_required The plan lacks the feature; plan names the cheapest plan that has it.
404 not_found No such chart on this account, or no such route.
422 validation_failed A field is invalid; fields lists messages by field. For chart parameters, reason carries the parser's code, such as invalid_param:y.
429 rate_limited More than 120 requests in a minute.
503 service_unavailable Charts are briefly unavailable; try again.

A wrong HTTP method on a real path (405) and an unexpected server error (500) answer with a plain {"message": "..."} instead.

Short charts

A short chart saves chart parameters behind /s/{id}, which hides your key and data. See Short URLs.

curl https://app.renderchart.com/api/v1/charts \
  -H "Authorization: Bearer rc_sec_live_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"name": "Weekly signups", "params": {"type": "bar", "x": "Mon,Tue,Wed,Thu,Fri", "y": "12,19,3,5,2", "title": "Signups this week"}}'

The response includes the chart's url. params are the URL spec's parameters as strings; key, sig and exp are ignored and unknown parameters are dropped. The chart renders with the key you authenticate with. Invalid parameters give 422 validation_failed, and format=pdf below Pro gives 403 plan_required.

Method and path Does
GET /charts Lists charts, newest first, 50 a page; pass next_cursor back as cursor.
POST /charts Creates a chart.
GET /charts/{id} Gets one chart, with its render count.
PATCH /charts/{id} Renames it (name), or on Pro changes its data (params): the same URL then shows the new chart within about five minutes.
DELETE /charts/{id} Deletes it; /s/{id} returns the 403 image within a minute.

Usage

GET /usage returns this month's unique renders against your monthly allowance, and the extra renders past it so far. Cached charts never count. Free accounts' months are calendar months (UTC); paid months start on your billing day, on annual billing too. For a Starter account billed on the 14th, past its allowance:

{"period": {"start": "2026-10-14T09:31:07+00:00", "end": "2026-11-14T09:31:07+00:00"}, "plan": "starter", "limit": 5000, "used": 6234, "remaining": 0, "blocked": true, "overage": {"enabled": true, "cents_per_1000": 500, "cap_cents": 5000, "renders": 1234, "cents": 617, "capped": false}}

Signing

POST /sign signs a chart URL with the authenticating key's secret, so it renders without a watermark on paid plans. Send a url or params (if you send both, url is used), and optionally exp (Unix seconds, in the future) to make the URL expire.

  • url is a chart URL for the / endpoint, or just /? and its query. Short URLs need no signature and are refused. The host is replaced with the chart endpoint's.
  • The URL's key must be the key you authenticate with; a URL without one gets it added.
curl https://app.renderchart.com/api/v1/sign \
  -H "Authorization: Bearer rc_sec_live_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://c.renderchart.com/?type=bar&x=Mon,Tue&y=1,2"}'

You can also sign on your own server without calling the API: see Signing.

Public pricing

GET https://app.renderchart.com/api/public/pricing needs no key. It returns the plans on sale with their prices in US cents before tax, monthly allowances, extra render rates, rate limits and features; openapi.yaml has the full shape. Any origin may read it, responses may be cached for five minutes, and each address may make 60 requests a minute (over that, 429 rate_limited).

Next: API reference