API Reference

POST /api/v1/render

Renders a chart from a JSON specification. Returns the image as binary (PNG, JPEG, SVG, or WebP).

Request Body

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

Response Headers

• X-Render-Time-Ms – Render latency in milliseconds
• X-Cache – HIT or MISS if Redis caching is enabled
• X-Request-Id – Request ID for debugging

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).

Format 1: Base64-encoded JSON

Encode your full chart spec as base64url. Use chart or c parameter.

GET /api/v1/render?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
• labels or l – Comma-separated labels
• data or d – Comma-separated numbers
• title or t – Chart title
• width, height – Dimensions (100–4000)
• format – png, jpeg, svg, webp
• brandKitId – UUID of brand kit

GET /api/v1/render?type=bar&labels=Q1,Q2,Q3,Q4&data=100,150,120,180&title=Revenue&format=png&width=600&height=300

Email Embedding

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

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

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

URL Length Limit

URLs longer than 2000 characters return 400. For complex charts with many data points, use POST instead.

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

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/DELETE /api/v1/brand-kits – Brand kit CRUD
• GET/POST/DELETE /api/v1/webhooks – Webhook subscriptions