API reference
Issue catalog
GET /api/v2/issues — static copy for every known issue id.
Returns titles, message templates, fix instructions, and documentation links for all issue ids. Fetch once and cache — join on issues[].id from scan responses.
GET /api/v2/issues?lang=enQuery parameters
| Prop | Type | Default | Description |
|---|---|---|---|
lang | string | 'en' | Language for issue copy. English only today; Dutch is planned. |
Example
curl -s 'https://carbonfooter.nl/api/v2/issues?lang=en'Response
{
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',
},
},
}Catalog entry
| Prop | Type | Default | Description |
|---|---|---|---|
title | string | Required | Short, human-readable issue name. |
messageTemplate | string | Required | Template with |
whyItMatters | string | Required | One-sentence rationale. |
howToFix | string | Required | Actionable remediation guidance. |
docsUrl | string | Required | Link to a longer explainer. |
category | 'images' | 'code' | 'fonts' | 'media' | 'delivery' | 'hosting' | Required | Grouping for UI. Extensible enum — handle unknown values gracefully. |
defaultSeverity | 'high' | 'medium' | 'low' | Required | Severity before per-scan tuning. |
Render messages client-side with messageTemplate and each instance's data object:
function renderMessage(template: string, data: Record<string, string | number>) {
return template.replace(/\{(\w+)\}/g, (_, key) => String(data[key] ?? ''))
}See Issues & recommendations for the full workflow.
Types
type Severity = 'high' | 'medium' | 'low'
/** Static, reusable copy for an issue id. */
interface IssueCatalogEntry {
title: string
messageTemplate: string
whyItMatters: string
howToFix: string
docsUrl: string
category: string
defaultSeverity: Severity
}
type IssueCatalog = Record<string, IssueCatalogEntry>
/** GET /api/v2/issues */
interface IssueCatalogResponse {
version: '2.0'
lang: string
issues: IssueCatalog
}Errors
| Status | error.code | When |
|---|---|---|
500 | INTERNAL | Unexpected server error |