Reference

The whole API

Four endpoints. Two URLs per chart: one that reads and one that writes. Nothing to install, and no header to set — the secret is the key in the path.

Sending a reading

Your chart's write key is on its page in Sparkline. Everything below is the same endpoint, reached three ways, because a deploy script, a CI step and an application all have a different idea of what is convenient.

POST /i/{write_key}

Query string

curl -fsS 'https://sparkline.dev/i/KEY?value=42&label=build-1183'

Form body

curl -fsS -d value=42 -d label=build-1183 https://sparkline.dev/i/KEY

JSON

curl -fsS -H 'content-type: application/json' -d '{"value":42,"label":"build-1183"}' https://sparkline.dev/i/KEY

GET /i/{write_key}

With a value, this records one — the shortest line that fits in a Makefile. Without one, it tells you how full the chart is and writes nothing.

curl -fsS https://sparkline.dev/i/KEY?value=42

DELETE /i/{write_key}

Empties the chart. The chart, its codes and everything that embeds it all survive — it just starts again from nothing.

curl -fsS -X DELETE https://sparkline.dev/i/KEY

What comes back

Small enough to read in a terminal, and shaped the same whether it worked or not — so jq -e .ok is a complete health check.

{
  "ok": true,
  "chart": "api p95 latency",
  "value": 42.0,
  "points": 87,
  "capacity": 256,
  "url": "https://sparkline.dev/g/k3n8pq7wv2xa"
}

404: No chart has that write key. The same answer for a key that is the wrong shape, deliberately.
422: No usable value. Infinities and NaN are refused here rather than stored.
429: This key is going too fast. Carries a Retry-After header and a retry_after in seconds, so sleep $(curl -s … | jq -r .retry_after) is a complete backoff.

Reading a chart

The read code is public and cannot write. Three representations, chosen by the extension.

The page

https://sparkline.dev/g/CODE

The picture

https://sparkline.dev/g/CODE.svg

The numbers

https://sparkline.dev/g/CODE.json

The image takes ?w= and ?h=, clamped to something sensible. Below about 320 × 120 the axis labels are dropped, because at that size they are larger than the plot they describe.

In a README

![latency](https://sparkline.dev/g/CODE.svg?w=420&h=90)

Limits, and why

Readings a chart: 256. The oldest is dropped as the next arrives, in the same transaction — so a chart is never briefly over, and nothing has to be pruned.
How fast: 120 readings at once, then 120 a minute per write key. The burst is the generous half on purpose: sending two hundred at once is a backfill, and sending two hundred a second for an hour is a loop somebody left running.
Label length: 48 characters. Longer ones are cut, not refused.
Authentication: The write key, and nothing else. Treat it as a secret: anybody holding one can add readings to that chart, and nothing more. Rotating it is one click.

Make a chart It takes about a minute.