DocsREST API
API reference
REST API v1 for short charts, usage and URL signing. Authenticate with your secret key (rc_sec_live_...) as a bearer token. The API needs a verified email address and a paid plan (Starter or above); changing a short chart's data needs Pro. Requests are limited to 120 a minute per key. API errors have the same shape (see Error); a wrong method (405) or a server error (500) answers with a plain message. See REST API for a guide.
Base URL https://app.renderchart.com/api/v1. Authenticate with Authorization: Bearer rc_sec_live_.... The OpenAPI 3.1 description is at openapi.yaml, for Redoc, Scalar or a client generator. The guide is REST API.
List short charts
GET /api/v1/charts The account's short charts, newest first, 50 a page.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
cursor | query | string | The next_cursor from the previous page. |
Responses
Create a short chart
POST /api/v1/charts Saves chart parameters behind a short URL (/s/{id}) that hides your key and data. The parameters are the URL spec's as strings; key, sig and exp are ignored and unknown parameters are dropped. The chart renders with the key you authenticated with.
Request body
A ChartInput object.
{
"name": "Weekly signups",
"params": {
"type": "bar",
"x": "Mon,Tue,Wed,Thu,Fri",
"y": "12,19,3,5,2",
"title": "Signups this week"
}
} Responses
| Status | Meaning | Body |
|---|---|---|
| 201 | The new chart. | Chart |
| 401 | Missing or unknown secret key. | Error |
| 403 | The email is not verified (email_unverified) or the plan lacks the feature (plan_required). | Error |
| 422 | The request or the chart parameters are not valid. | Error |
| 429 | More than 120 requests in a minute with this key. | Error |
| 503 | Charts are briefly unavailable; try again. | Error |
Get a short chart
GET /api/v1/charts/{id} Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path, required | string | Pattern ^[A-Za-z0-9]{10}$ |
Responses
Rename a chart or change its data
PATCH /api/v1/charts/{id} A new name works on any paid plan. New params make a live short URL, which needs Pro: the same /s/{id} shows the new chart within about five minutes, and the version goes up by one.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path, required | string | Pattern ^[A-Za-z0-9]{10}$ |
Request body
| Field | Type | Notes |
|---|---|---|
name | string or null | Up to 80 characters. |
params | Params | Chart parameters as strings, exactly as the URL spec defines them. Together they must make a URL of 8,000 characters or fewer. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The updated chart. | Chart |
| 401 | Missing or unknown secret key. | Error |
| 403 | The email is not verified (email_unverified) or the plan lacks the feature (plan_required). | Error |
| 404 | No such chart on this account. | Error |
| 422 | The request or the chart parameters are not valid. | Error |
| 429 | More than 120 requests in a minute with this key. | Error |
| 503 | Charts are briefly unavailable; try again. | Error |
Delete a short chart
DELETE /api/v1/charts/{id} /s/{id} returns the 403 image within a minute.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path, required | string | Pattern ^[A-Za-z0-9]{10}$ |
Responses
Renders this period
GET /api/v1/usage Unique renders in the current period against the plan's allowance, and the extra renders billed past it so far. Cached charts never count. At the limit blocked turns true: Free and unverified accounts stop making new charts. On a paid plan with extra renders on and under its cap, signed URLs and short charts keep rendering as extra renders, and unsigned URLs only from keys that allow them; with extra renders off or at the cap, new charts stop.
Responses
Sign a chart URL
POST /api/v1/sign Signs a chart URL (or chart parameters) with the authenticating key's secret, so it renders without a watermark on paid plans. Send url or params; when both are sent, url is used. The URL must be for the / endpoint (short URLs need no signature) and its host is replaced with the chart endpoint's. The URL's key must be that key; if it has none it is added. Optional exp (Unix seconds, in the future) makes the URL stop working after that time.
Request body
| Field | Type | Notes |
|---|---|---|
url | string | A chart URL for the / endpoint, or /? and its query. Up to 8000 characters. |
params | Params | Chart parameters as strings, exactly as the URL spec defines them. Together they must make a URL of 8,000 characters or fewer. |
exp | integer | Unix seconds, in the future. |
{
"url": "https://c.renderchart.com/?type=bar&x=Mon,Tue&y=1,2",
"exp": 1893456000
} Responses
Plans and prices
GET /api/public/pricing The plans on sale, their prices in US cents before tax, monthly allowances, extra render rates, rate limits and features. No authentication. Responses may be cached for five minutes, and any origin may read them.
No authentication.
Responses
Schemas
Params
Chart parameters as strings, exactly as the URL spec defines them. Together they must make a URL of 8,000 characters or fewer.
object
ChartInput
| Field | Type | Notes |
|---|---|---|
name | string or null | Up to 80 characters. |
params | Params, required | Chart parameters as strings, exactly as the URL spec defines them. Together they must make a URL of 8,000 characters or fewer. |
Chart
| Field | Type | Notes |
|---|---|---|
id | string, required | |
name | string or null, required | |
url | string, required | |
type | string, required | The chart type, or cfg in advanced mode. |
params | Params, required | Chart parameters as strings, exactly as the URL spec defines them. Together they must make a URL of 8,000 characters or fewer. |
version | integer, required | |
render_count | integer, required | Unique renders of this chart. |
last_rendered_at | string or null, required | Format date-time. |
created_at | string, required | Format date-time. |
updated_at | string, required | Format date-time. |
Usage
| Field | Type | Notes |
|---|---|---|
period | object, required | |
plan | string: free, starter, pro, business, admin, required | |
limit | integer or null, required | Null is unlimited. |
used | integer, required | |
remaining | integer or null, required | |
blocked | boolean, required | The allowance is used up. |
overage | object, required | Extra renders, billed per render when the period ends. Paid plans only. |
Pricing
| Field | Type | Notes |
|---|---|---|
currency | string, required | |
plans | array of object, required | |
unverified_renders | integer, required | Renders an account may make before verifying its email. |
Error
| Field | Type | Notes |
|---|---|---|
error | object, required |