Skip to Content
CarbonFooterv2.0

Getting started

Run your first CarbonFooter scan in under a minute.

Prerequisites

You need an HTTP client, a URL to scan and an API key. Ask for a key at [email protected]; see Authentication for how keys and limits work.

Scan a page

Send a POST request to /api/v2/scans with the page URL:

Terminal
curl -s -X POST https://carbonfooter.nl/api/v2/scans \
  -H 'Authorization: Bearer cf_live_…' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "example.com"
  }'

The url field accepts domains with or without a scheme; without one we use https://. The page must be publicly reachable.

Minimal response fields

A successful scan returns status: "completed" with these headline fields:

Response
{
  "version": "2.0",
  "status": "completed",
  "cached": false,
  "url": "https://example.com/",
  "website": "example.com",
  "grade": "A+",
  "co2": {
    "perVisit": { "value": 0.0000416, "unit": "gCO2e" }
  },
  "issueSummary": { "high": 0, "medium": 0, "low": 0, "total": 0 }
}

See Understanding the response for the full object.

Fetch the issue catalog

Issue instances in a scan response are lean (id, severity, data). Static copy — titles, fix instructions, documentation links — lives in a separate catalog:

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

Fetch this once and cache it. Join on issues[].id when rendering scan results.

OpenAPI schema

The machine-readable schema is available at:

GET https://carbonfooter.nl/api/v2/openapi.json

Use it to generate typed clients. The schema is generated from the TypeScript response types and kept in sync by contract tests.

JavaScript example

scan.js
const response = await fetch('https://carbonfooter.nl/api/v2/scans', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CARBONFOOTER_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ url: 'example.com' }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.code}: ${error.message}`);
}

const scan = await response.json();
console.log(scan.grade, scan.co2.perVisit);

What to build

Common integrations:

  • Agency dashboards — scan client sites on a schedule, chart co2.perVisit over time
  • CI checks — fail a build when grade drops below a threshold
  • PDF reports — request recommendations: "full" for inline issue copy
  • Issue widgets — join scan issues[] with the cached catalog for fix instructions

Next steps

On this page