{"openapi":"3.1.0","info":{"title":"CarbonFooter Scan API","version":"2.0","description":"Measures the carbon footprint of a web page.\n\nConventions that hold across the whole response:\n\n- Every dimensioned quantity is `{ value, unit }`. Units never appear in field names.\n- Counts are bare integers.\n- Every field is always present. Unavailable values are `null`, or `[]` for lists — never omitted.\n- Checks that can fail to run are `\"true\" | \"false\" | \"unknown\"`, not booleans.\n- `measurement.*.resources.byType` buckets are mutually exclusive and sum exactly to `total`.\n  Third-party weight overlaps them and lives in its own namespace.\n\nMethodology constants that hold for every scan (and are therefore not repeated in each response):\n\n- Pages are measured at a fixed desktop viewport of 1440×900, deviceScaleFactor 1. This is what\n  \"above the fold\" means throughout the response.\n- Emissions cover data transfer only. Excluded: device energy, server processing, and embedded\n  video streams (embed players are reported separately, as estimates, and never folded into `co2`).\n- The model (SWD v4, `methodology.model`/`version`) charges every visit the full page weight with\n  no return-visit cache benefit. This is fixed behaviour of the model, not a configurable input.\n\nAuthentication and limits:\n\n- An API key is required. Send it as `Authorization: Bearer <key>` (or `x-api-key: <key>`).\n  There is no anonymous tier: the API never looks at client addresses.\n- The limits are those of the key — by default 60 requests per minute and\n  1000 new scans per calendar month (UTC).\n- Only a *new* scan counts against a scan allowance. A result served from cache is free, and so\n  is a scan that fails through a fault of ours.\n- `GET /api/v2/usage` reports the limits that apply to the caller and what is left of them.\n\nEvery response carries `X-Request-Id`; quote it when reporting a problem.\n\nNew fields may be added within a version; clients must ignore unknown ones.\nSee docs/api-v2-contract.md for the full contract."},"servers":[{"url":"https://carbonfooter.nl"}],"paths":{"/api/v2/scans":{"post":{"operationId":"createScan","summary":"Scan a page and return its measured emissions","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanRequest"}}}},"responses":{"200":{"description":"A completed scan. Identical in shape whether served fresh or from cache; `cached` and `scannedAt` say which.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanV2Response"}}}},"400":{"description":"The request is malformed or names a URL that may not be scanned. For `INVALID_REQUEST`, `error.details.fields` lists each offending field. `error.code`: INVALID_JSON / MISSING_URL / INVALID_URL / INVALID_REQUEST / URL_NOT_ALLOWED.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanErrorResponse"}}}},"401":{"description":"No API key was sent, or the key is invalid or revoked. Every endpoint requires a key. `error.code`: UNAUTHORIZED.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanErrorResponse"}}}},"402":{"description":"The API key's monthly allowance of new scans is used up. Cached results are still served. `error.code`: LIMIT_EXCEEDED.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanErrorResponse"}}}},"422":{"description":"The request was valid but the page could not be scanned: it blocked the scanner, answered with an error status, or could not be loaded. `error.details.targetStatus` carries the HTTP status the page returned, or `null` if there was none. Retrying will not help. `error.code`: ACCESS_DENIED / TARGET_ERROR / UNREACHABLE.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanErrorResponse"}}}},"429":{"description":"Too many requests per minute for this API key. `error.code`: RATE_LIMITED.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanErrorResponse"}}}},"500":{"description":"Unexpected error. `error.code`: INTERNAL.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanErrorResponse"}}}},"503":{"description":"The scanner could not start, failed mid-scan, or is busy with other scans. Safe to retry; the scan is not counted against any allowance. `error.code`: SCANNER_UNAVAILABLE.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanErrorResponse"}}}},"504":{"description":"The page did not finish loading within the scan time limit. `error.code`: SCAN_TIMEOUT.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanErrorResponse"}}}}}}},"/api/v2/usage":{"get":{"operationId":"getUsage","summary":"Limits that apply to the caller, and what is left of them","description":"Answers for the API key on the request. Counts as one request against the per-minute limit.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"responses":{"200":{"description":"Current limits and usage.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}}},"401":{"description":"No API key was sent, or the key is invalid or revoked. Every endpoint requires a key. `error.code`: UNAUTHORIZED.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanErrorResponse"}}}},"429":{"description":"Too many requests per minute for this API key. `error.code`: RATE_LIMITED.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanErrorResponse"}}}},"500":{"description":"Unexpected error. `error.code`: INTERNAL.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanErrorResponse"}}}}}}},"/api/v2/issues":{"get":{"operationId":"getIssueCatalog","summary":"Static copy for every known issue id","description":"Fetch once and cache, then join on `issues[].id`. The copy is identical for every scan, which is why it is not embedded per instance.","parameters":[{"name":"lang","in":"query","required":false,"schema":{"type":"string","default":"en","enum":["en"]}}],"responses":{"200":{"description":"The catalog.","content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string"},"lang":{"type":"string"},"issues":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/IssueCatalogEntry"}}}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An API key, as `Authorization: Bearer <key>`."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"The same API key, for clients that cannot set `Authorization`."}},"headers":{"X-Request-Id":{"description":"Identifies this request in our logs. Also in `error.requestId`.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this caller. Absent when the caller has no per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current minute ends, in Unix seconds.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before trying again.","schema":{"type":"integer"}}},"schemas":{"ScanRequest":{"type":"object","required":["url"],"additionalProperties":false,"properties":{"url":{"type":"string","description":"The page to scan. `http` or `https` only; the scheme may be omitted and defaults to `https`. Must be publicly reachable: private, loopback and internal addresses are refused with `URL_NOT_ALLOWED`. A fragment is ignored; the path is used exactly as given, trailing slash included."},"forceNew":{"type":"boolean","default":false,"description":"Bypass the cache and always run a fresh scan."},"maxAgeHours":{"type":"number","default":24,"minimum":0,"maximum":720,"description":"Maximum age of a cached scan that may be served. `0` never serves from cache."},"screenshot":{"type":"boolean","default":false,"description":"Capture an above-the-fold screenshot. A cached scan without one is not reused."},"recommendations":{"type":"string","enum":["summary","full"],"default":"summary","description":"Detail tier. `full` adds a sibling `issueCatalog`; the shape of `issues[]` never varies."},"include":{"type":"array","items":{"type":"string","enum":["thirdPartyDomains","fontFamilies","videoEmbeds","cacheByAsset"]},"default":[],"description":"Opt-in detail lists. Omitted lists are `null`, never absent."}}},"ScanV2Response":{"type":"object","properties":{"version":{"type":"string","const":"2.0"},"scanId":{"type":"string"},"status":{"type":"string","enum":["completed","pending","failed"]},"cached":{"type":"boolean"},"url":{"type":"string"},"website":{"type":"string"},"scannedAt":{"type":"string"},"grade":{"$ref":"#/components/schemas/Grade"},"co2":{"type":"object","properties":{"perVisit":{"$ref":"#/components/schemas/Measure"},"perByte":{"$ref":"#/components/schemas/Measure"},"range":{"type":"object","properties":{"min":{"$ref":"#/components/schemas/Measure"},"max":{"$ref":"#/components/schemas/Measure"}},"required":["min","max"],"additionalProperties":false,"description":"Floor (above-the-fold) and ceiling (full page) for one visit."}},"required":["perVisit","perByte","range"],"additionalProperties":false},"measurement":{"$ref":"#/components/schemas/MeasurementPhases"},"assets":{"$ref":"#/components/schemas/AssetsBlock"},"thirdParty":{"$ref":"#/components/schemas/ThirdPartyBlock"},"delivery":{"$ref":"#/components/schemas/DeliveryBlock"},"hosting":{"type":"object","properties":{"green":{"$ref":"#/components/schemas/Verdict"},"provider":{"type":["string","null"]},"evidenceUrl":{"type":["string","null"]}},"required":["green","provider","evidenceUrl"],"additionalProperties":false},"page":{"$ref":"#/components/schemas/PageMetadata"},"issues":{"type":"array","items":{"$ref":"#/components/schemas/IssueInstance"},"description":"Always present; `[]` when clean. Shape never varies with detail tier."},"issueSummary":{"$ref":"#/components/schemas/IssueSummary"},"issueCatalog":{"anyOf":[{"$ref":"#/components/schemas/IssueCatalog"},{"type":"null"}],"description":"Sibling copy for the ids present; null unless `recommendations: \"full\"`."},"screenshot":{"anyOf":[{"type":"object","properties":{"url":{"type":"string"},"pageUrl":{"type":"string"},"width":{"anyOf":[{"$ref":"#/components/schemas/Measure"},{"type":"null"}]},"height":{"anyOf":[{"$ref":"#/components/schemas/Measure"},{"type":"null"}]},"size":{"anyOf":[{"$ref":"#/components/schemas/Measure"},{"type":"null"}]},"format":{"type":"string"},"capturedAt":{"type":"string"}},"required":["url","pageUrl","width","height","size","format","capturedAt"],"additionalProperties":false},{"type":"null"}]},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/Warning"}},"methodology":{"$ref":"#/components/schemas/MethodologyBlock"}},"required":["version","scanId","status","cached","url","website","scannedAt","grade","co2","measurement","assets","thirdParty","delivery","hosting","page","issues","issueSummary","issueCatalog","screenshot","warnings","methodology"],"additionalProperties":false},"Grade":{"type":"string","enum":["A+","A","B","C","D","E","F"]},"Measure":{"type":"object","properties":{"value":{"type":"number"},"unit":{"$ref":"#/components/schemas/Unit"},"estimated":{"type":"boolean","const":true,"description":"Present only when the value is modelled rather than observed."}},"required":["value","unit"],"additionalProperties":false},"Unit":{"type":"string","enum":["bytes","ms","s","px","percent","gCO2e","gCO2e/kWh"],"description":"Closed (but extensible) set of units used across the public contract."},"MeasurementPhases":{"type":"object","properties":{"aboveTheFold":{"type":"object","properties":{"resources":{"$ref":"#/components/schemas/ResourcePhase"}},"required":["resources"],"additionalProperties":false,"description":"Above-the-fold load (no scroll). Note this already includes eagerly loaded below-the-fold resources — browsers fetch non-lazy images regardless of position — so the gap to `fullPage` is what the page deliberately deferred. Its emissions are `co2.range.min`."},"fullPage":{"type":"object","properties":{"resources":{"$ref":"#/components/schemas/ResourcePhase"}},"required":["resources"],"additionalProperties":false,"description":"Cumulative load after auto-scrolling. Canonical basis for co2/grade/issues; its emissions are `co2.perVisit` (and `co2.range.max`)."},"deferred":{"type":"object","properties":{"size":{"$ref":"#/components/schemas/Measure"},"requests":{"type":"number"}},"required":["size","requests"],"additionalProperties":false,"description":"`fullPage − aboveTheFold`: what the page deferred."}},"required":["aboveTheFold","fullPage","deferred"],"additionalProperties":false},"ResourcePhase":{"type":"object","properties":{"total":{"$ref":"#/components/schemas/ResourceBucket"},"byType":{"type":"object","properties":{"html":{"$ref":"#/components/schemas/ResourceBucket"},"images":{"$ref":"#/components/schemas/ResourceBucket"},"scripts":{"$ref":"#/components/schemas/ResourceBucket"},"styles":{"$ref":"#/components/schemas/ResourceBucket"},"fonts":{"$ref":"#/components/schemas/ResourceBucket"},"video":{"$ref":"#/components/schemas/ResourceBucket"},"other":{"$ref":"#/components/schemas/ResourceBucket"}},"required":["html","images","scripts","styles","fonts","video","other"],"additionalProperties":false,"description":"Mutually exclusive; sums exactly to `total`."}},"required":["total","byType"],"additionalProperties":false},"ResourceBucket":{"type":"object","properties":{"size":{"$ref":"#/components/schemas/Measure"},"requests":{"type":"number"}},"required":["size","requests"],"additionalProperties":false,"description":"One resource type bucket. Identical shape for every type, including html."},"AssetsBlock":{"type":"object","properties":{"images":{"type":"object","properties":{"total":{"type":"number"},"modern":{"type":"number"},"legacy":{"type":"number"},"animatedGif":{"type":"number"},"lazy":{"type":"number"},"eager":{"type":"number"},"offscreenEager":{"type":"number","description":"Eager and outside the first viewport — the actionable subset."}},"required":["total","modern","legacy","animatedGif","lazy","eager","offscreenEager"],"additionalProperties":false},"fonts":{"type":"object","properties":{"formats":{"$ref":"#/components/schemas/Record_FontFormat_number_"},"display":{"$ref":"#/components/schemas/Record_FontDisplay_number_"},"origin":{"type":"object","properties":{"selfHosted":{"type":"number"},"thirdParty":{"type":"number"}},"required":["selfHosted","thirdParty"],"additionalProperties":false},"families":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"null unless `include: [\"fontFamilies\"]`."}},"required":["formats","display","origin","families"],"additionalProperties":false},"scripts":{"type":"object","properties":{"minified":{"$ref":"#/components/schemas/Verdict"},"sampled":{"type":"number"}},"required":["minified","sampled"],"additionalProperties":false},"styles":{"type":"object","properties":{"minified":{"$ref":"#/components/schemas/Verdict"},"sampled":{"type":"number"}},"required":["minified","sampled"],"additionalProperties":false},"video":{"type":"object","properties":{"selfHosted":{"type":"object","properties":{"count":{"type":"number"},"size":{"$ref":"#/components/schemas/Measure"},"autoplay":{"type":"number"},"preloadAuto":{"type":"number"},"withoutPoster":{"type":"number"},"lazy":{"type":"number"}},"required":["count","size","autoplay","preloadAuto","withoutPoster","lazy"],"additionalProperties":false},"embedded":{"type":"object","properties":{"count":{"type":"number"},"size":{"$ref":"#/components/schemas/Measure","description":"Always `estimated` — the stream is never fetched during a scan."},"providers":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"provider":{"$ref":"#/components/schemas/VideoProvider"},"count":{"type":"number"},"lazy":{"type":"number"},"size":{"$ref":"#/components/schemas/Measure"}},"required":["provider","count","lazy","size"],"additionalProperties":false}},{"type":"null"}],"description":"null unless `include: [\"videoEmbeds\"]`."}},"required":["count","size","providers"],"additionalProperties":false}},"required":["selfHosted","embedded"],"additionalProperties":false},"iframes":{"type":"object","properties":{"total":{"type":"number"},"lazy":{"type":"number"},"eager":{"type":"number"}},"required":["total","lazy","eager"],"additionalProperties":false}},"required":["images","fonts","scripts","styles","video","iframes"],"additionalProperties":false},"Record_FontFormat_number_":{"type":"object","properties":{"woff2":{"type":"number"},"woff":{"type":"number"},"ttf":{"type":"number"},"otf":{"type":"number"},"eot":{"type":"number"},"other":{"type":"number"}},"required":["woff2","woff","ttf","otf","eot","other"],"additionalProperties":false},"Record_FontDisplay_number_":{"type":"object","properties":{"swap":{"type":"number"},"optional":{"type":"number"},"fallback":{"type":"number"},"block":{"type":"number"},"auto":{"type":"number"}},"required":["swap","optional","fallback","block","auto"],"additionalProperties":false},"Verdict":{"type":"string","enum":["true","false","unknown"],"description":"A check that can fail to run. A boolean cannot distinguish \"measured, and it's bad\" from \"could not measure\", and conflating those forces breaking changes later."},"VideoProvider":{"type":"string","enum":["youtube","vimeo","wistia","loom","dailymotion","brightcove","jwplayer","mux","vidyard","tiktok","other"],"description":"Video platforms detectable from an iframe `src`."},"ThirdPartyBlock":{"type":"object","properties":{"size":{"$ref":"#/components/schemas/Measure"},"requests":{"type":"number"},"share":{"$ref":"#/components/schemas/Measure"},"domains":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"category":{"$ref":"#/components/schemas/ThirdPartyCategory"},"size":{"$ref":"#/components/schemas/Measure"},"requests":{"type":"number"}},"required":["domain","category","size","requests"],"additionalProperties":false}},{"type":"null"}],"description":"null unless `include: [\"thirdPartyDomains\"]`."}},"required":["size","requests","share","domains"],"additionalProperties":false},"ThirdPartyCategory":{"type":"string","enum":["analytics","ads","tagmanager","social","video","fonts","cdn","chat","consent","maps","payment","other"],"description":"Categories used to group third-party domains in the API response."},"DeliveryBlock":{"type":"object","properties":{"ttfb":{"$ref":"#/components/schemas/Measure"},"redirects":{"type":"number"},"protocol":{"type":["string","null"]},"compression":{"type":"object","properties":{"document":{"$ref":"#/components/schemas/Verdict"},"textAssets":{"type":"object","properties":{"total":{"type":"number"},"compressed":{"type":"number"},"uncompressed":{"type":"number"},"unknown":{"type":"number"}},"required":["total","compressed","uncompressed","unknown"],"additionalProperties":false}},"required":["document","textAssets"],"additionalProperties":false},"caching":{"type":"object","properties":{"document":{"type":"object","properties":{"browserCache":{"$ref":"#/components/schemas/BrowserCachePolicy","description":"HTML response: may the browser store it? (from Cache-Control / Expires)"},"maxAge":{"anyOf":[{"$ref":"#/components/schemas/Measure"},{"type":"null"}]},"directives":{"type":["string","null"],"description":"Raw Cache-Control on the HTML response, reported unjudged."},"observed":{"type":"object","properties":{"status":{"type":["number","null"]},"servedFromCache":{"$ref":"#/components/schemas/Verdict","description":"Was the HTML served from a CDN / shared cache on this scan?"},"age":{"anyOf":[{"$ref":"#/components/schemas/Measure"},{"type":"null"}]},"evidence":{"type":["string","null"]}},"required":["status","servedFromCache","age","evidence"],"additionalProperties":false}},"required":["browserCache","maxAge","directives","observed"],"additionalProperties":false},"staticAssets":{"type":"object","properties":{"total":{"type":"number"},"longLived":{"type":"number"},"shortLived":{"type":"number"},"uncacheable":{"type":"number"},"unknown":{"type":"number"}},"required":["total","longLived","shortLived","uncacheable","unknown"],"additionalProperties":false},"byAsset":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/CacheByAssetEntry"}},{"type":"null"}],"description":"null unless `include: [\"cacheByAsset\"]`."}},"required":["document","staticAssets","byAsset"],"additionalProperties":false}},"required":["ttfb","redirects","protocol","compression","caching"],"additionalProperties":false},"BrowserCachePolicy":{"type":"string","enum":["allowed","blocked","unknown"],"description":"Whether response headers allow the browser to store this resource."},"CacheByAssetEntry":{"type":"object","properties":{"url":{"type":"string"},"type":{"type":"string"},"browserCache":{"$ref":"#/components/schemas/BrowserCachePolicy"},"maxAge":{"anyOf":[{"$ref":"#/components/schemas/Measure"},{"type":"null"}]},"compressed":{"$ref":"#/components/schemas/Verdict"}},"required":["url","type","browserCache","maxAge","compressed"],"additionalProperties":false},"PageMetadata":{"type":"object","properties":{"title":{"type":["string","null"]},"description":{"type":["string","null"]},"favicon":{"type":["string","null"]},"ogImage":{"type":["string","null"]},"lang":{"type":["string","null"]}},"required":["title","description","favicon","ogImage","lang"],"additionalProperties":false},"IssueInstance":{"type":"object","properties":{"id":{"type":"string"},"severity":{"$ref":"#/components/schemas/Severity"},"data":{"$ref":"#/components/schemas/Record_string__number_string__","description":"Dynamic, issue-specific measured values, interpolated into the catalog's `messageTemplate`. A flat scalar bag by design (see contract §12.1): it is the documented exception to the units-never-in-field-names rule, because template rendering needs flat values."},"estimatedSaving":{"anyOf":[{"$ref":"#/components/schemas/Measure"},{"type":"null"}],"description":"Conservative projection; null when not estimable."}},"required":["id","severity","data","estimatedSaving"],"additionalProperties":false,"description":"Lean issue instance — what a scan returns, at every detail tier."},"Severity":{"type":"string","enum":["high","medium","low"]},"Record_string__number_string__":{"type":"object","additionalProperties":{"type":["number","string"]}},"IssueSummary":{"type":"object","properties":{"high":{"type":"number"},"medium":{"type":"number"},"low":{"type":"number"}},"required":["high","medium","low"],"additionalProperties":false},"IssueCatalog":{"$ref":"#/components/schemas/Record_string_IssueCatalogEntry_","description":"Catalog copy for the ids present in a response (the `full` tier sibling)."},"Record_string_IssueCatalogEntry_":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/IssueCatalogEntry"}},"IssueCatalogEntry":{"type":"object","properties":{"title":{"type":"string"},"messageTemplate":{"type":"string"},"whyItMatters":{"type":"string"},"howToFix":{"type":"string"},"docsUrl":{"type":"string"},"category":{"type":"string"},"defaultSeverity":{"$ref":"#/components/schemas/Severity"}},"required":["title","messageTemplate","whyItMatters","howToFix","docsUrl","category","defaultSeverity"],"additionalProperties":false,"description":"Static, reusable copy for an issue id. Served once via GET /api/v2/issues."},"Warning":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/WarningCode"},"message":{"type":"string"},"details":{"anyOf":[{"$ref":"#/components/schemas/Record_string_unknown_"},{"type":"null"}]}},"required":["code","message"],"additionalProperties":false},"WarningCode":{"type":"string","enum":["RESOURCES_CAPPED","SCROLL_TIMEOUT","MINIFICATION_UNKNOWN","EMBEDDED_VIDEO_ESTIMATED","GRID_WORLD_AVERAGE","GREENCHECK_UNAVAILABLE","SCREENSHOT_FAILED","DEPRECATED_FIELD"]},"Record_string_unknown_":{"type":"object","additionalProperties":{}},"MethodologyBlock":{"type":"object","properties":{"model":{"type":"string"},"version":{"type":"number"},"basis":{"type":"string","enum":["fullPage","aboveTheFold"],"description":"Which phase `co2.perVisit` and `grade` reflect. Changing this is breaking."},"grid":{"type":"object","properties":{"dataCenter":{"$ref":"#/components/schemas/GridSegmentBlock"},"network":{"$ref":"#/components/schemas/GridSegmentBlock"},"device":{"$ref":"#/components/schemas/GridSegmentBlock"}},"required":["dataCenter","network","device"],"additionalProperties":false,"description":"Per SWD segment — a single scalar would be true of no segment."},"scannerVersion":{"type":"string"},"scrolled":{"type":"boolean"}},"required":["model","version","basis","grid","scannerVersion","scrolled"],"additionalProperties":false},"GridSegmentBlock":{"type":"object","properties":{"value":{"type":"number"},"unit":{"$ref":"#/components/schemas/Unit"},"estimated":{"type":"boolean","const":true,"description":"Present only when the value is modelled rather than observed."},"source":{"type":"string","enum":["cf-ray","ip","world-average"]},"countryCode":{"type":["string","null"]}},"required":["countryCode","source","unit","value"],"additionalProperties":false},"ScanErrorResponse":{"type":"object","properties":{"version":{"type":"string","const":"2.0"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{},"requestId":{"type":"string"}},"required":["code","message","details","requestId"],"additionalProperties":false}},"required":["version","error"],"additionalProperties":false},"UsageResponse":{"type":"object","properties":{"version":{"type":"string","const":"2.0"},"tier":{"type":"string","const":"key","description":"Always `key`: the API requires one."},"key":{"type":"object","properties":{"prefix":{"type":"string"},"label":{"type":"string"}},"required":["prefix","label"],"additionalProperties":false,"description":"The key the request was made with; never the key itself."},"requests":{"type":"object","properties":{"limit":{"type":["number","null"]},"remaining":{"type":["number","null"]},"resetsAt":{"type":"string"}},"required":["limit","remaining","resetsAt"],"additionalProperties":false,"description":"All requests, per minute."},"scans":{"type":"object","properties":{"limit":{"type":["number","null"]},"used":{"type":"number"},"remaining":{"type":["number","null"]},"period":{"type":"string","const":"month","description":"Per calendar month (UTC)."},"resetsAt":{"type":"string"}},"required":["limit","used","remaining","period","resetsAt"],"additionalProperties":false,"description":"Fresh scans only — a result served from cache is never counted."}},"required":["version","tier","key","requests","scans"],"additionalProperties":false,"description":"GET /api/v2/usage — the caller's limits and how much of them is left. A `null` limit (and `null` remaining) means unlimited."}}}}