Skip to Content
CarbonFooterv2.0
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=en

Query parameters

PropTypeDefaultDescription
langstring'en'

Language for issue copy. English only today; Dutch is planned.

Example

Terminal
curl -s 'https://carbonfooter.nl/api/v2/issues?lang=en'

Response

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

PropTypeDefaultDescription
titlestringRequired

Short, human-readable issue name.

messageTemplatestringRequired

Template with {placeholders} filled from each instance's data object.

whyItMattersstringRequired

One-sentence rationale.

howToFixstringRequired

Actionable remediation guidance.

docsUrlstringRequired

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:

render-message.ts
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

issue-catalog.d.ts
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

Statuserror.codeWhen
500INTERNALUnexpected server error

On this page