Skip to main content

Templates

Pre-built chart templates for common use cases. Render with query parameter overrides. Use GET /api/v1/templates to list all templates including your custom ones.

Looking for finished, branded examples? The gallery has 15 charts, each with its exact request, and /gallery.json lists them for scripts and agents. Gallery slugs are not template IDs.

Built-in Templates

17 production-ready templates. All support brand kit overrides via brandKitId and data overrides via labels / data query parameters. Each template ships with sample numbers; labels replaces the x-axis labels and data replaces the first series only, so send both together and keep the number of values equal to the number of labels.

Template IDChartDefault sizeDescription
mrr-trendline800×400Monthly recurring revenue with target line and launch window annotations
signups-barbar800×400New user signups with on-bar data labels
weekly-volume-ratebar800×400Bar chart volume with line conversion rate (dual Y axes)
plan-distributionpie600×400Customer distribution across plans
funnel-conversionbar800×400User journey conversion rates
nps-trendline800×400Net Promoter Score over time
churn-rateline800×400Monthly churn percentage
mrr-growthline (card)760×440Monthly recurring revenue for 12 months against a target line, as a titled card
email-performancebar800×400Email campaign metrics
ad-spend-roibar800×400Advertising ROI by channel
csat-breakdowndoughnut600×400Customer satisfaction by category
support-volumebar800×400Support tickets over time
pipeline-stagesbar800×400Deals by sales stage
win-rate-trendline800×400Sales win rate over time
quota-attainmentbar800×400Team quota achievement
ltv-cacbar800×400Customer lifetime value vs acquisition cost
mrr-growth-ratebar800×400MRR growth rate by month

mrr-growth is the MRR line chart with a target line, drawn as a titled card (it shows the same thing as the gallery's mrr-growth chart; gallery slugs are not template IDs). The bar chart of month-over-month growth is mrr-growth-rate.mrr-growth is always drawn at 3×; scale does not change it.

Rendering a Template

Use the GET endpoint with optional data and style overrides:

text
GET /api/v1/templates/mrr-trend/render?labels=Jan,Feb,Mar,Apr,May&data=12000,15000,18000,22000,25000&format=png&brandKitId=obsidian

Omitting scale defaults to 3× output (retina). Pass scale=1 for 1×.

Query Parameters

ParameterDescription
labelsComma-separated labels; replaces the template's x-axis (or slice) labels
dataComma-separated numbers; replaces the first series only
titleRenames the first series (the legend and tooltip name). It does not add a chart heading
width, heightDimensions in pixels (100–4000)
formatpng, jpeg, svg, webp
brandKitIdSaved kit UUID or preset: obsidian, linen, polar, studio, ember, harbor
scale / devicePixelRatio1–4; defaults to 3 on this route when omitted
paletteComma-separated hex colors (URL-encode # as %23) — overrides series colors

Card Template Example

Templates that include card composition (header, kpiStrip, footer) render the full card. You can also supply a full card spec to POST /api/v1/render directly:

json
{ "type": "line", "brandKitId": "obsidian", "header": { "eyebrow": "Metrics · Jan–May 2024", "title": "MRR Trend", "badge": { "text": "+14%", "backgroundColor": "#166534", "color": "#dcfce7" } }, "kpiStrip": [ { "label": "MRR", "value": "$25,000", "color": "#22c55e" }, { "label": "ARR", "value": "$300k", "color": "#22c55e" }, { "label": "Growth", "value": "+14%", "color": "#22c55e" } ], "footer": { "left": "chart-output.com", "right": "Updated daily" }, "data": { "labels": ["Jan", "Feb", "Mar", "Apr", "May"], "datasets": [{ "label": "MRR", "data": [12000, 15000, 18000, 22000, 25000] }] } }

Custom Templates

Save any chart spec as a reusable template via the dashboard or API:

json
POST /api/v1/templates { "name": "Monthly MRR", "description": "Standard MRR line chart with card", "chartType": "line", "spec": { ... } // Any valid chart spec including card composition }

Once saved, render it the same way as built-in templates using the returned UUID as the templateId.