Scan a page
POST /api/v2/scans — request body, parameters, and options.
Runs a synchronous scan and returns the complete result. Cached responses are shape-identical to fresh scans — check cached and scannedAt to tell them apart.
POST /api/v2/scansRequest body
interface ScanRequest {
/** Page to scan. http(s) only; scheme optional, defaults to https. */
url: string
forceNew?: boolean
maxAgeHours?: number
screenshot?: boolean
recommendations?: 'summary' | 'full'
include?: IncludeMember[]
}
type IncludeMember =
| 'thirdPartyDomains'
| 'fontFamilies'
| 'cacheByAsset'
| 'videoEmbeds'| Prop | Type | Default | Description |
|---|---|---|---|
url | string | Required | Page to scan. Must be |
forceNew | boolean | false | Bypass the cache and always run a fresh scan. |
maxAgeHours | number | 24 | Serve a cached scan only if it is younger than this. |
screenshot | boolean | false | Capture an above-the-fold WebP screenshot. |
recommendations | 'summary' | 'full' | 'summary' | Whether to include inline issue copy alongside the lean issue instances. |
include | IncludeMember[] | [] | Opt-in detail lists. Unrecognised members are ignored. |
Validation
Field types are strict. A string where a boolean belongs ("forceNew": "false") is rejected with 400 INVALID_REQUEST rather than guessed at, and error.details.fields names each offending field. null for an optional field means "not provided".
Values are lenient where that keeps old and new clients compatible: unknown include members, unknown recommendations values and unknown top-level keys are ignored.
URL rules
- Only
httpandhttps. Any other scheme is400 INVALID_URL. - URLs with embedded credentials (
https://user:pass@…) are refused. - The fragment (
#section) is dropped. Nothing else is rewritten — in particular a trailing slash is kept, since/blogand/blog/are different URLs. - The URL must be on the public internet.
localhost, private network ranges and other internal addresses are refused with400 URL_NOT_ALLOWED, including when a public URL redirects to one. - The page must answer successfully. A URL that returns an error status gives
422 TARGET_ERRORinstead of a measurement of the error page — see Errors.
Opt-in detail lists
Fields backed by an include member are null when not requested and [] when requested with no results. Unrecognised members are silently ignored, so new ones can be added without a version bump.
| Member | Populates | Why it's opt-in |
|---|---|---|
'thirdPartyDomains' | thirdParty.domains[] | Per-domain breakdown, typically 10–20 entries |
'fontFamilies' | assets.fonts.families[] | Descriptive, not scored |
'cacheByAsset' | delivery.caching.byAsset[] | Per-file cache headers, unbounded |
'videoEmbeds' | assets.video.embedded.providers[] | Embed-focused breakdown |
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",
"screenshot": true,
"recommendations": "full",
"include": ["thirdPartyDomains", "cacheByAsset"]
}'Scanner behaviour
- Pages are measured at a fixed 1440×900 viewport with
deviceScaleFactor: 1. - Above the fold means resources loaded before any scrolling.
- Full page means cumulative weight after auto-scrolling to the bottom.
- The browser cache is disabled and every scan starts in a clean browser profile, so each one measures a cold first visit with no cookies or storage from an earlier scan.
- A scan is limited to 50 seconds in total. A page that needs longer ends as
504 SCAN_TIMEOUT. - A page that never stops making requests (polling, streaming) is still measured: the scanner stops waiting for it and adds a
SCROLL_TIMEOUTwarning. - The scanner identifies as the desktop Chrome version it actually runs.
- Two requests for the same page at the same time share one scan. When the scanner has no free slot, the request ends as
503 SCANNER_UNAVAILABLEwithRetry-Afterand is not counted. - Requests carry
X-CarbonFooter-Scan: 1so site owners can allowlist the scanner.
Screenshots and the cache
If screenshot: true but the cached scan has no screenshot, the cache is bypassed and a fresh scan runs. When screenshot: false, the field is null even if a screenshot exists in storage.
The original /api endpoint
GET /api?target=<url> is the original, pre-v2 endpoint. It is still served, unchanged, for the plugins that were built on it, and returns its own older response shape — not the v2 response described here. It is frozen: nothing will be added to it. Build new integrations on /api/v2/.