Skip to Content
CarbonFooterv2.0
API reference

Create scan

POST /api/v2/scans — measure a page and return emissions, grade, and issues.

Scan a URL and receive a complete ScanV2Response. Cached responses are shape-identical to fresh scans.

POST /api/v2/scans

Request body

PropTypeDefaultDescription
urlstringRequired

Page to scan. http or https, publicly reachable; scheme optional.

forceNewbooleanfalse

Bypass the scan-result cache.

maxAgeHoursnumber24

Max age of a cached result to serve. 0 to 720.

screenshotbooleanfalse

Capture an above-the-fold WebP screenshot.

recommendations'summary' | 'full''summary'

Include inline issue copy when set to full.

includeIncludeMember[][]

Opt-in detail lists. See Scan a page.

Authentication

Required. Send Authorization: Bearer <api_key> (or x-api-key); without a valid key the answer is 401. See Authentication.

Example

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"}'

Response

200 with a ScanV2Response when status is 'completed'.

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 },
}

The full object is large — see Response structure for every namespace.

PropTypeDefaultDescription
version'2.0'Required

Contract version, not scanner version.

scanIdstringRequired

Opaque identifier. Never parse it.

status'completed' | 'pending' | 'failed'Required

Only completed occurs in synchronous mode.

cachedbooleanRequired

True when served from a stored scan.

urlstringRequired

Final URL after redirects.

websitestringRequired

Hostname. Subdomains are tracked separately.

scannedAtstringRequired

ISO-8601 timestamp of the measurement.

grade'A+' | 'A' | 'B' | 'C' | 'D' | 'E' | 'F'Required

Derived from co2.perVisit.

Types

Copy the definitions below into your project, or generate them from the OpenAPI schema:

Terminal
npx openapi-typescript https://carbonfooter.nl/api/v2/openapi.json -o carbonfooter-api.d.ts

Errors

Statuserror.codeWhen
400INVALID_JSON / MISSING_URL / INVALID_URL / INVALID_REQUESTBad request body
400URL_NOT_ALLOWEDURL is, or leads to, a private or internal address
401UNAUTHORIZEDNo API key was sent, or it is invalid or revoked
402LIMIT_EXCEEDEDThe key's monthly scans are used up
422ACCESS_DENIEDThe page refused the scanner
422TARGET_ERRORThe page answered with an error status
422UNREACHABLEThe page could not be loaded
429RATE_LIMITEDToo many requests this minute
500INTERNALUnexpected server error
503SCANNER_UNAVAILABLEThe scanner could not run or is busy; retry after Retry-After
504SCAN_TIMEOUTPage load timed out

See Errors for handling guidance.

Response headers

HeaderOnMeaning
X-Request-IdEvery responseIdentifies the request; matches error.requestId
X-RateLimit-LimitEvery response except 401Requests allowed per minute
X-RateLimit-RemainingEvery response except 401Requests left in the current minute
X-RateLimit-ResetEvery response except 401End of the current minute, Unix seconds
Retry-After429, 503Seconds to wait before retrying

On this page