Cloud render

ChartKit Cloud renders a spec for any agent or app. There is no signup. Free images include a small chartkit.dev mark, linked to /cloud. A valid API key removes the mark. This service draws the mark. @chartkitdev/core does not, and the core bundles do not include it.

Every render runs validate() and repair() first. Response headers carry the JSON Patch, the warning codes, and the error codes. POST also returns them as JSON. render_chart on @chartkitdev/mcp (npx -y @chartkitdev/mcp) returns the image URL plus those repairs. Example URLs on this site use https://cloud.chartkit.dev unless the site build sets PUBLIC_CHARTKIT_CLOUD_URL.

GET /render

spec is URL-encoded JSON or base64url JSON. Omit format, or pass svg. SVG is the default: it skips rasterizing and stays sharp in chat. Pass png only when the host cannot display SVG, such as email, a GitHub README image, or some Slack clients. w and h set the pixel size. scale is the PNG zoom, from 1 to 4. Prefer 2 or higher when the format is PNG. theme is a preset name such as soft or midnight. background is a CSS color (#ffffff, rgb(), hsl(), oklch(), or transparent). This GET always includes the mark. A key on the query string is ignored, so an image URL stays free of secrets.

html
<img
  alt="Revenue stays near the target and finishes above it."
  src="https://cloud.chartkit.dev/render?spec=%7B%22version%22%3A%221%22%2C%22type%22%3A%22line%22%2C%22title%22%3A%22Revenue%22%2C%22data%22%3A%5B%7B%22month%22%3A%22Jan%22%2C%22revenue%22%3A42%2C%22target%22%3A40%7D%2C%7B%22month%22%3A%22Feb%22%2C%22revenue%22%3A46%2C%22target%22%3A43%7D%2C%7B%22month%22%3A%22Mar%22%2C%22revenue%22%3A44%2C%22target%22%3A46%7D%2C%7B%22month%22%3A%22Apr%22%2C%22revenue%22%3A51%2C%22target%22%3A49%7D%2C%7B%22month%22%3A%22May%22%2C%22revenue%22%3A58%2C%22target%22%3A52%7D%2C%7B%22month%22%3A%22Jun%22%2C%22revenue%22%3A55%2C%22target%22%3A55%7D%5D%2C%22encoding%22%3A%7B%22x%22%3A%22month%22%2C%22y%22%3A%5B%7B%22field%22%3A%22revenue%22%2C%22title%22%3A%22Revenue%22%2C%22area%22%3Atrue%7D%2C%7B%22field%22%3A%22target%22%2C%22title%22%3A%22Target%22%7D%5D%7D%2C%22mark%22%3A%7B%22curve%22%3A%22monotone%22%7D%2C%22a11y%22%3A%7B%22alt%22%3A%22Revenue+stays+near+the+target+and+finishes+above+it.%22%7D%7D&format=svg&w=960&h=480"
/>

POST /render

js
const spec = {"version":"1","type":"line","title":"Revenue","data":[{"month":"Jan","revenue":42,"target":40},{"month":"Feb","revenue":46,"target":43},{"month":"Mar","revenue":44,"target":46},{"month":"Apr","revenue":51,"target":49},{"month":"May","revenue":58,"target":52},{"month":"Jun","revenue":55,"target":55}],"encoding":{"x":"month","y":[{"field":"revenue","title":"Revenue","area":true},{"field":"target","title":"Target"}]},"mark":{"curve":"monotone"},"a11y":{"alt":"Revenue stays near the target and finishes above it."}};

const res = await fetch("https://cloud.chartkit.dev/render", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ spec, format: "svg", w: 960, h: 480 }),
});
const { url, applied, warnings, svg } = await res.json();

The JSON body is spec, format, w, h, scale, theme, and background. Send a key only as Authorization: Bearer. The body includes url, applied, warnings, errors, and either svg or base64 png. A valid key stores the repaired spec and returns /c/<id>.svg (or .png) with no secret in the query. Without a key, a short spec keeps a GET /render URL and a spec longer than 1,800 characters is stored with the mark. Soft, Refined, and Editorial leave the plot transparent so a web page can show through. Cloud paints #ffffff instead, unless you pass background or the spec already sets theme.tokens.background. The query param wins over that token. Pass background=transparent to keep the plot clear. On a dark host, pass theme=midnight (light text on an opaque dark plate) or a dark background together with a dark theme. PNG uses the same plate.

POST /charts and POST /validate

POST /charts stores the repaired spec and returns id, shareUrl, svgUrl, and pngUrl. shareUrl is /s/<id>, an HTML page with a 1200×628 card so X, Slack, LinkedIn, and iMessage show a preview. The same spec and the same mark state return the same id. A valid Authorization: Bearer stores it unmarked. GET /c/<id> serves that stored image and does not read a key. GET /c/<id>/card.png is the card. POST /validate does not draw. It returns the repaired spec, applied, and the remaining diagnostics.

Headers

  • X-ChartKit-Repairs and X-ChartKit-Repair-Patch (base64url JSON Patch)
  • X-ChartKit-Warnings and X-ChartKit-Errors
  • X-ChartKit-Watermark is 1 or 0. X-ChartKit-Key is valid, invalid, or absent
  • Cache-Control: public, max-age=31536000, immutable and an ETag on rendered images

Errors and limits

A spec that repair cannot draw returns 422 and an image that lists the CK codes, for GET. POST returns the same codes as JSON. A missing or unreadable spec returns 400 and an error image. More than 120 renders a minute from one IP returns 429. The limit is the same with a key.

Keys

Remove the watermark starts checkout. Pricing is coming soon. When checkout is available, POST /stripe/webhook issues one key per completed Checkout Session, and the success page shows that key. Send it as Authorization: Bearer on POST /charts or POST /render. Use the returned /c/<id> URL in an img. Do not put the key in that URL.

js
const spec = {"version":"1","type":"line","title":"Revenue","data":[{"month":"Jan","revenue":42,"target":40},{"month":"Feb","revenue":46,"target":43},{"month":"Mar","revenue":44,"target":46},{"month":"Apr","revenue":51,"target":49},{"month":"May","revenue":58,"target":52},{"month":"Jun","revenue":55,"target":55}],"encoding":{"x":"month","y":[{"field":"revenue","title":"Revenue","area":true},{"field":"target","title":"Target"}]},"mark":{"curve":"monotone"},"a11y":{"alt":"Revenue stays near the target and finishes above it."}};

const res = await fetch("https://cloud.chartkit.dev/charts", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    authorization: `Bearer ${process.env.CHARTKIT_CLOUD_KEY}`,
  },
  body: JSON.stringify({ spec }),
});
const { url } = await res.json();
// url is /c/<id>.svg. It does not contain the key.
const img = `<img alt="Revenue stays near the target and finishes above it." src="${url}">`;

Hosted keys and stored charts use Vercel KV or Upstash when KV_REST_API_URL and KV_REST_API_TOKEN are set. A Workers deploy reads those same variables from Worker secrets. Without them, the process keeps keys and charts in memory.

PNG uses resvg wasm with Inter and Roboto bundled in the service. SVG text stays on the library font stack. Agents should omit format and attach the SVG. PNG is the fallback for a host that cannot show SVG.