Quick Start

A successful API call in under five minutes.

1. Get an API key

text

Authorization: Bearer pk_test_YOUR_KEY

You get a pk_test_… sandbox key for development and a pk_live_… key for production. Anonymous requests (no Authorization header) also work, at starter-plan limits.

2. Make the request

POST a JSON spec to /api/v1/render. The response is raw image bytes.

curl -X POST https://chart-output.com/api/v1/render \
  -H "Authorization: Bearer pk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  --output chart.png \
  -d '{
  "type": "bar",
  "width": 800,
  "height": 400,
  "format": "png",
  "data": {
    "labels": ["Jan", "Feb", "Mar", "Apr"],
    "datasets": [{
      "label": "Revenue",
      "data": [12000, 15000, 18000, 22000],
      "backgroundColor": "#6ee7b7",
      "borderRadius": 4
    }]
  }
}'

3. Read the response

The default response is binary image data. Every response includes diagnostic headers.

text

HTTP/1.1 200 OK
Content-Type: image/png
Content-Length: 28431
Cache-Control: public, max-age=31536000, immutable
ETag: "d41d8cd9..."
X-Render-Time-Ms: 52
X-Cache: MISS
X-Request-Id: req_01hx...

<binary PNG bytes>

Set returnUrl: true to get a CDN URL instead. Useful when you need a stable image URL for embedding in HTML or passing to another service.

json

{
  "type": "bar",
  "width": 800,
  "height": 400,
  "returnUrl": true,
  "data": {
    "labels": ["Jan", "Feb", "Mar"],
    "datasets": [{ "label": "Revenue", "data": [12000, 15000, 18000] }]
  }
}

text

HTTP/1.1 200 OK
Content-Type: application/json
X-Render-Time-Ms: 48
X-Cache: MISS
X-Request-Id: req_01hx...

{ "url": "https://cdn.chart-output.com/renders/abc123.png" }

Header	Meaning
Content-Type	`image/png`, `image/jpeg`, `image/svg+xml`, `image/webp`, or `application/pdf`
X-Render-Time-Ms	Server-side render latency in milliseconds
X-Cache	`HIT` or `MISS` — identical specs are cached
X-Request-Id	Unique request ID — include this when reporting issues
ETag	MD5 of the spec — use for client-side conditional requests

4. Embed in email

Use the GET endpoint with your key as a query parameter. Browsers cannot send Authorization headers with image requests, so ?key= is the right pattern here.

html

<img
  src="https://chart-output.com/api/v1/render?key=pk_live_YOUR_KEY&type=bar&labels=Jan,Feb,Mar,Apr&data=12000,15000,18000,22000&format=png&width=600&height=300"
  alt="Revenue chart"
  width="600"
  height="300"
/>

Use PNG for email — it has the broadest client support. See the Charts in Email guide for Resend, Nodemailer, and SendGrid examples.

Next steps

Authentication — Key types, query-param auth, 401 debugging
API Reference — All parameters and response shapes
Chart Specifications — Every dataset field, limits, null gaps
Brand Kits — Consistent colors, fonts, and logos across renders
Output Formats — PNG vs SVG vs PDF — when to use each
Error Reference — Every status code with cause and fix