Issues & recommendations
Issue instances, the catalog endpoint, and recommendation tiers.
Issues are the actionable layer on top of raw measurements. They carry severity, context data, and optional estimated savings — separate from the observation-only assets and delivery namespaces.
One shape, forever
Every issue instance has the same shape regardless of detail tier:
{
"id": "image_format",
"severity": "high",
"data": { "count": 8 },
"estimatedSaving": { "value": 735000, "unit": "bytes", "estimated": true }
}estimatedSaving is null when not estimable. When present, it always includes estimated: true.
The data object is a flat bag of scalars used for messageTemplate interpolation in the catalog. Keys vary by issue id but are stable within an id.
Recommendation tiers
Controlled by the recommendations request parameter:
| Tier | issues[] | issueCatalog | Use case |
|---|---|---|---|
"summary" (default) | lean instances | null | Dashboards and SDKs that cache the catalog |
"full" | lean instances | copy for present ids | One-shot callers (PDFs, quick reports) |
issueSummary is always populated regardless of tier.
The "none" tier was dropped pre-launch. Unrecognised values fall back to "summary".
Issue catalog
Static copy lives behind a separate endpoint — fetch once and cache:
GET /api/v2/issues?lang=en{
"version": "2.0",
"lang": "en",
"issues": {
"image_format": {
"title": "Use modern image formats",
"messageTemplate": "{count} images aren't served as WebP or AVIF.",
"whyItMatters": "Modern formats cut image transfer by 25–50%.",
"howToFix": "Convert images to WebP/AVIF and serve via <picture> or your CDN.",
"docsUrl": "https://carbonfooter.nl/learn/image-formats",
"category": "images",
"defaultSeverity": "high"
}
}
}Render messages client-side with messageTemplate and data:
function renderMessage(template, data) {
return template.replace(/\{(\w+)\}/g, (_, key) => String(data[key] ?? ''));
}Issue categories
Issues are grouped by domain:
| Category | Example ids |
|---|---|
| Hosting & carbon | green_hosting, high_grid_intensity |
| Page weight | page_weight, too_many_requests |
| Images | image_format, image_lazyload, image_gif |
| Code | js_minify, css_minify, js_weight |
| Fonts | font_format, font_display, font_weight |
| Media | video_autoplay, embed_weight, iframe_lazyload |
| Third-party | third_party_weight, third_party_requests |
| Delivery | compression, caching, slow_ttfb, redirects |
Thresholds are retunable without a version bump. New issue ids may be added at any time.
Ordering
Issues are sorted by severity (high → low), then by estimatedSaving.value descending.
Related
- Response structure — where
issues[]lives in the scan payload - API reference — catalog endpoint details