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/scansRequest body
| Prop | Type | Default | Description |
|---|---|---|---|
url | string | Required | Page to scan. |
forceNew | boolean | false | Bypass the scan-result cache. |
maxAgeHours | number | 24 | Max age of a cached result to serve. |
screenshot | boolean | false | Capture an above-the-fold WebP screenshot. |
recommendations | 'summary' | 'full' | 'summary' | Include inline issue copy when set to |
include | IncludeMember[] | [] | 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
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'.
{
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.
| Prop | Type | Default | Description |
|---|---|---|---|
version | '2.0' | Required | Contract version, not scanner version. |
scanId | string | Required | Opaque identifier. Never parse it. |
status | 'completed' | 'pending' | 'failed' | Required | Only |
cached | boolean | Required | True when served from a stored scan. |
url | string | Required | Final URL after redirects. |
website | string | Required | Hostname. Subdomains are tracked separately. |
scannedAt | string | Required | ISO-8601 timestamp of the measurement. |
grade | 'A+' | 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | Required | Derived from |
Types
Copy the definitions below into your project, or generate them from the OpenAPI schema:
npx openapi-typescript https://carbonfooter.nl/api/v2/openapi.json -o carbonfooter-api.d.tsErrors
| Status | error.code | When |
|---|---|---|
400 | INVALID_JSON / MISSING_URL / INVALID_URL / INVALID_REQUEST | Bad request body |
400 | URL_NOT_ALLOWED | URL is, or leads to, a private or internal address |
401 | UNAUTHORIZED | No API key was sent, or it is invalid or revoked |
402 | LIMIT_EXCEEDED | The key's monthly scans are used up |
422 | ACCESS_DENIED | The page refused the scanner |
422 | TARGET_ERROR | The page answered with an error status |
422 | UNREACHABLE | The page could not be loaded |
429 | RATE_LIMITED | Too many requests this minute |
500 | INTERNAL | Unexpected server error |
503 | SCANNER_UNAVAILABLE | The scanner could not run or is busy; retry after Retry-After |
504 | SCAN_TIMEOUT | Page load timed out |
See Errors for handling guidance.
Response headers
| Header | On | Meaning |
|---|---|---|
X-Request-Id | Every response | Identifies the request; matches error.requestId |
X-RateLimit-Limit | Every response except 401 | Requests allowed per minute |
X-RateLimit-Remaining | Every response except 401 | Requests left in the current minute |
X-RateLimit-Reset | Every response except 401 | End of the current minute, Unix seconds |
Retry-After | 429, 503 | Seconds to wait before retrying |