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:
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:
{
"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:
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.jsonUse it to generate typed clients. The schema is generated from the TypeScript response types and kept in sync by contract tests.
JavaScript example
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.perVisitover time - CI checks — fail a build when
gradedrops 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
- Scan options — screenshots, recommendations tier, opt-in detail lists
- Error handling — error codes and retry guidance
- API reference — full endpoint documentation