Perf API

The Perf API runs request-driven Lighthouse audits against a live site and returns web-vitals metrics. It's the first public Yoshi API, live on api.yoshi.site.

Run an audit

curl -X POST https://api.yoshi.site/perf/run \
  -H "Authorization: Bearer $YOSHI_API_KEY" \
  -d '{"limit":3,"samples":3}'

The request is fully parameterised — no rebuild to change behaviour:

field	meaning
limit	how many pages to audit
samples	median-of-N runs per page (tier-gated: free 1 / pro 3 / internal 5)
cpuReference	CPU calibration reference (host-aware auto by default)
pages[]	explicit page list (otherwise sampled from the site map)

The metrics{} object

Every run returns per-page scores (performance, accessibility, best-practices, SEO) plus raw web-vitals (LCP, FCP, TTI, TBT) with both the Lighthouse score and the raw value.

Scoring philosophy

Scores reflect the site, not the noisy shared host: desktop throttling matches real desktop results, the reference is host-aware, and stability comes from a median rather than a tuned constant. A heavy page should score below 100 — that's an honest signal, not a bug to inflate away.

Results are written to public R2 and read back with X-Data-Source: r2. Per-tier daily caps apply (/perf/usage reports remaining quota).