Render Timeline

POST/visual/v1/render-timeline

What it does

Takes an array of events (each with a date, title, and optional description) and renders a polished timeline infographic — vertical or horizontal — as SVG or PNG. The layout is fully server-side via Satori, so there's no browser or headless Chrome involved. By default, success is a JSON wrapper; set responseFormat: "file" when you want raw SVG or PNG output.

Why use it?

Project roadmaps. Generate visual roadmaps from structured data — perfect for README files, pitch decks, and status pages.
Changelog visuals. Turn your release history into a shareable timeline image for social media or documentation.
Event sequences. Visualise incident timelines, onboarding steps, or product milestones without design tools.
Deterministic output. Same events, same dimensions → identical image every time. Great for CI/CD pipelines.

Examples

Minimal example

curl -X POST https://api.creatornode.io/visual/v1/render-timeline \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{
    "events": [
      { "date": "2026-02-01", "title": "MVP shipped", "text": "First public release" },
      { "date": "2026-02-10", "title": "10k users" }
    ]
  }'

Returns the default JSON wrapper with an SVG timeline in data and render metadata in meta.

Raw file response

curl -X POST https://api.creatornode.io/visual/v1/render-timeline   -H "Content-Type: application/json"   -H "X-API-Key: YOUR_KEY"   -d '{
    "events": [
      { "date": "2026-02-01", "title": "MVP shipped" },
      { "date": "2026-02-10", "title": "10k users" }
    ],
    "format": "png",
    "responseFormat": "file"
  }'   --output roadmap.png

Full-featured example

{
  "title": "Product Roadmap 2026",
  "events": [
    { "date": "Jan 2026", "title": "Project Kickoff", "text": "Team assembled, requirements finalized" },
    { "date": "Feb 2026", "title": "MVP Shipped", "text": "First public release with core features" },
    { "date": "Mar 2026", "title": "10k Users", "text": "Organic growth milestone" },
    { "date": "Apr 2026", "title": "Series A", "text": "Funding round closed" }
  ],
  "orientation": "vertical",
  "format": "png",
  "theme": "dark",
  "accentColor": "#10b981",
  "width": 1200,
  "height": 630
}

Orientation

Value	Layout	Best for
`vertical`	Central vertical axis, events alternate left/right	Tall images, many events, docs & READMEs
`horizontal`	Central horizontal axis, events alternate above/below	Wide images, few events, presentations & banners

Card layout

Value	Description	Best for
`alternate`	Cards zigzag left/right (vertical) or top/bottom (horizontal)	Default. Full-width timelines with plenty of space.
`compact`	All cards on one side — dot left, card right (vertical)	Narrow containers, sidebars, mobile views.

Theming

Use theme to switch between colour presets, and accentColor to customise the dot and date colours.

Theme	Background	Text	Accents
`light` (default)	White	Dark grey	Blue dots & dates
`dark`	Dark slate	Light grey	Blue dots & dates

Pass accentColor as a #RRGGBB hex to override the dot and date colours in any theme — great for matching your brand.

Set transparent: true to remove the background fill entirely (SVG only). This makes it easy to embed the timeline into pages with a custom background colour.

Font family

Use fontFamily to choose the typeface for the entire timeline:

Value	Font	Best for
`inter` (default)	Inter	Clean sans-serif. Great for general use, docs, marketing.
`roboto`	Roboto	Geometric sans-serif. Familiar from Material Design / Android.
`mono`	JetBrains Mono	Monospace. Ideal for developer/tech timelines, changelogs, version histories.

Auto-sizing

Width and height are both optional. Omit either (or both) and the API auto-calculates based on event count and orientation:

Vertical — width defaults to 800, height grows at ~90 px per event.
Horizontal — height defaults to 400, width grows at ~220 px per event.

Explicit values always take priority.

Parameters

Field	Type	Default	Notes
`events`	array	—	Required. 1–50 objects with `date`, `title`, optional `text`.
`title`	string	—	Optional heading displayed above the timeline.
`width`	number	auto	200–4096 px. Omit to auto-calculate.
`height`	number	auto	200–4096 px. Omit to auto-calculate.
`orientation`	string	`vertical`	`vertical` or `horizontal`
`format`	string	`svg`	`svg` or `png`
`layout`	string	`alternate`	`alternate` or `compact`
`theme`	string	`light`	`light` or `dark`
`accentColor`	string	—	`#RRGGBB` hex — overrides dot & date colours.
`transparent`	boolean	`false`	Transparent background (SVG only).
`fontFamily`	string	`inter`	`inter`, `roboto`, or `mono`

Event ordering

Events are rendered in the order they appear in the array. The API does not sort them by date — you control the display order. This gives you full flexibility: chronological, reverse-chronological, or any custom order you need.

Tips & tricks

Choose the transport based on the consumer. JSON mode is better when you need dimensions, event counts, or recommendations. File mode is better when you just need the final image.
Let the API size it. Omit width and height — auto-sizing produces great results for most use cases, scaling with event count automatically.
Add a title. Set "title": "Product Roadmap" for a clear heading above the timeline — especially useful for standalone images and social shares.
Use compact for narrow spaces. Set layout: "compact" with a narrow width (300–400 px) for sidebars, mobile views, or embedded widgets.
Match your site's theme. Use theme: "dark" for dark-mode pages. Add accentColor: "#10b981" to match your brand colour.
Transparent for custom backgrounds. Set transparent: true when embedding into pages with a non-white background — the timeline blends right in.
Try mono for changelogs. Set fontFamily: "mono" for version histories and developer timelines — JetBrains Mono gives a clean technical look.
Horizontal works best with ≤ 6 events. Cards get narrow with many items. For longer histories, stick to vertical.
Use short dates. "Feb 2026" or "Q1 2026" looks cleaner than full ISO dates in the rendered image.
Open Graph roadmaps. Set width: 1200, height: 630, format: "png" for a link-preview-ready image showing your product roadmap.
Keep descriptions brief. The text field works best at 1–2 short sentences. Long descriptions may overflow card bounds.

💡 Tip: Combine render-timeline with render-code to create a full release overview: a timeline image for milestones plus code snippets for API changes — all generated programmatically.

Cost & Limits

Feature	Detail
Credit cost	2 credits per request
Output formats	SVG, PNG
Themes	light, dark + custom accentColor
Font families	Inter, Roboto, JetBrains Mono

Tier Limits

Limit	Free	Premium
Max events	10	50
Max PNG resolution	800 × 800	2048 × 2048

Other Endpoints

POST/visual/v1/render-code