Skip to main content

API Reference

REST API endpoints for chart rendering and management.

OpenAPI 3.1 specification – Use with Swagger UI, Redoc, or code generators.

Postman collection – Import into Postman to test all endpoints. Set baseUrl, apiKey, and sessionToken variables.

POST /api/v1/render

Renders a chart from a JSON specification. Returns the image as binary (PNG, JPEG, SVG, WebP, or PDF) or JSON with a CDN URL when returnUrl: true.

Request Body

json
{ "type": "line" | "bar" | "pie" | "doughnut" | "radar" | "polarArea", "width": 800, "height": 400, "format": "png" | "jpeg" | "svg" | "webp" | "pdf", "data": { "labels": ["Jan", "Feb", "Mar"], "datasets": [{ "label": "Revenue", "data": [12000, 15000, 18000] }] }, "brandKitId": "uuid-or-preset", "devicePixelRatio": 1, "returnUrl": false, "options": {} }

See Chart Specifications and Card Composition for the full field reference. Authentication: Authorization: Bearer pk_live_... (optional on GET — anonymous GET renders run at the anonymous limits described under Authentication; POST requires a key).

Response Headers

  • Content-Type – image/png, image/jpeg, image/svg+xml, image/webp, or application/pdf
  • X-Render-Time-Ms – Render latency in milliseconds
  • X-Cache – HIT or MISS when Redis caching is enabled
  • X-Request-Id – Unique request ID for debugging and support
  • ETag – MD5 of the spec for client-side caching

GET /api/v1/render

Renders a chart from URL parameters. Ideal for <img src="..."> embeds in emails, Slack, Markdown, and forums.

Supports two formats: base64-encoded JSON (full spec) or simple query parameters (basic charts). URL length limit: 2000 characters — use POST for complex specs that exceed this.

Authentication

Browsers cannot send Authorization headers with image requests. Pass your API key as a query parameter instead:

  • key – ?key=pk_live_...
  • apiKey – Alias for key: ?apiKey=pk_live_...

Format 1: Base64-encoded JSON

Encode your full chart spec as base64url. Use chart or the alias c.

text
GET /api/v1/render?key=pk_live_YOUR_KEY&chart=eyJ0eXBlIjoibGluZSIsIndpZHRoIjo4MDAsImhlaWdodCI6NDAwLCJkYXRhIjp7ImxhYmVscyI6WyJKYW4iLCJGZWIiLCJNYXIiXSwiZGF0YXNldHMiOlt7ImxhYmVsIjoiUmV2ZW51ZSIsImRhdGEiOlsxMjAwMCwxNTAwMCwxODAwMF19XX19

Format 2: Query Parameters

Simple charts with comma-separated values. Best for quick embeds.

  • type or cht – line, bar, pie, doughnut, radar, polarArea (defaults to line when omitted; any other value returns 400)
  • labels or l – Comma-separated labels
  • data or d – Comma-separated numbers
  • title or t – Chart title
  • width, height – Dimensions (100–4000 px). Your plan also caps the longest edge (width or height times devicePixelRatio): 1,200 px on Free, 3,000 px on Pro and Agency
  • format – png, jpeg, svg, webp, pdf
  • brandKitId – UUID or preset name (obsidian, linen, polar, studio, ember, harbor)
  • returnUrl – Return JSON with CDN URL instead of the image
text
GET /api/v1/render?key=pk_live_YOUR_KEY&type=bar&labels=Q1,Q2,Q3,Q4&data=100,150,120,180&title=Revenue&format=png&width=600&height=300

Google Image Charts URLs don't work with the host swapped. A request with a Google chart type in cht (such as bvs), Google-encoded data (t:, s: or e:), or Google-only parameters such as chs and chl returns 400 with an error naming the parameter. Rewrite it with type, labels and data, or send a Chart.js config as base64url JSON in c.

Email Embedding

Use the GET endpoint in HTML emails. PNG format recommended for best compatibility across Gmail, Outlook, and Apple Mail.

html
<img src="https://www.chart-output.com/api/v1/render?key=pk_live_YOUR_KEY&type=bar&labels=Jan,Feb,Mar&data=10,20,30&format=png" alt="Monthly stats" width="600" height="300" />

URL-encode special characters in labels (spaces → %20). Keep URLs under 2000 characters; use POST for complex charts.

GET /api/v1/templates/:templateId/render

Renders a built-in or custom template with optional query parameter overrides.

Query Parameters

  • labels – Comma-separated labels
  • data – Comma-separated values
  • title – Chart title
  • width, height
  • format – png, jpeg, svg, webp
  • brandKitId – UUID of brand kit or preset (obsidian, linen, polar, studio, ember, harbor)
  • scale / devicePixelRatio – 1–4; defaults to 2 on this route (retina output)
  • palette – Comma-separated hex colors (URL-encode # as %23)

Management APIs (Dashboard)

These endpoints require a session JWT (from the dashboard) or API key.

  • GET /api/v1/stats – Overview stats (renders this month, success rate, avg latency)
  • GET /api/v1/renders?limit=10 – Recent render history
  • GET /api/v1/usage – Usage data for current month
  • GET/POST/DELETE /api/v1/api-keys – API key management
  • GET/POST/PUT/DELETE /api/v1/brand-kits – Brand kit CRUD
  • GET/POST/DELETE /api/v1/webhooks – Webhook subscriptions
  • GET/POST/PUT/DELETE /api/v1/templates – Custom template CRUD
  • GET /api/v1/audit-logs – Audit log for account actions
  • GET/PUT /api/v1/settings/custom-domain – Custom CDN domain for returnUrl
  • POST /api/v1/jobs – Async render (returns 202 + jobId). A scheduled worker picks jobs up, so results are not immediate: they arrive via the render.complete webhook or GET /api/v1/jobs/:id polling once the worker has run. If you need the image right away, use the synchronous render endpoint.
  • GET /api/v1/jobs/:id – Poll async job status and result URL
  • POST /api/v1/ai/render – Natural-language chart generation (Pro and Agency). Has a separate AI render quota; see the AI rendering guide.

Error Responses

400 Bad Request

Invalid chart specification or malformed JSON.

401 Unauthorized

An Authorization header was present but the key was invalid, or a POST was sent with no key at all. A GET /api/v1/render with no key is the one exception: it returns 200 at the anonymous limits (PNG only, 1200px max, 5 renders per 15 minutes per IP address).

403 Forbidden

Valid key, but the plan does not allow the output format (for example PDF on Free) or the image size (the longest edge, width or height times devicePixelRatio, is above the plan's maximum).

Plan feature

json
{ "error": "plan_required", "message": "PDF output needs the Pro plan. Your Free plan includes PNG, JPEG, SVG, WEBP.", "feature": "format:pdf", "plan": "free", "required_plan": "pro", "upgrade_url": "https://www.chart-output.com/billing/upgrade?plan=pro" }

402 Payment Required

The plan's monthly allowance for renders (or another metered feature) is used up. Nothing is charged as overage; the allowance resets at the end of the period.

Allowance used up

json
{ "error": "quota_exceeded", "message": "You have used 1,000 of 1,000 renders this period on the free plan.", "metric": "renders", "limit": 1000, "used": 1000, "plan": "free", "resets_at": "2026-12-01T00:00:00.000Z", "upgrade_url": "https://www.chart-output.com/billing/upgrade?plan=pro" }

429 Too Many Requests

Rate limiting (100 requests per 15 minutes per API key or IP). Check the error body.

Rate limit

json
{ "error": "Rate limit exceeded", "retryAfter": 120 }
  • Retry-After – Seconds until the window resets
  • X-RateLimit-Limit – Request limit per window (100)
  • X-RateLimit-Remaining – Requests remaining in current window
  • X-RateLimit-Reset – ISO timestamp of window reset

500 Internal Server Error

Server error during rendering. Include X-Request-Id when reporting issues.