API reference

Compatibility policy

Every field in /api/v1/schema is tagged stable, provisional or internal in an x-stability keyword. The tag says how long you get between hearing a field will change and it changing.

Level	Fields	What can change within v1	Notice	How you are told
stable	208	Nothing within v1. Removing, renaming or retyping it needs a new major version (/api/v2), announced at least 180 days ahead.	180 days	Deprecation and Sunset headers on every response that carries it, deprecated:true in the schema, an entry in x-compatibility.deprecations, release notes.
provisional	287	Its shape may change within v1 (renamed, restructured, removed) after at least 30 days' notice. Never silently.	30 days	The same four signals as stable, 30 days ahead.
internal	10	Anything, at any time. It is in the response so you can see what the record is built from, not to be built on.	none	None promised.

505 fields across 16 response formats. The table below, the JSON Schema and /openapi.json are generated from one list, so they always agree.

Rules

Adding is never breaking. New fields, new formats and new endpoints can appear at any time at any level. Ignore fields you do not know, and validate against the live schema rather than a pinned copy.

A field is never more stable than its container. Everything inside a provisional object is provisional, whatever it is tagged on its own.

Undescribed contents are provisional. An object or array whose contents the schema does not spell out is provisional until they are written down. Three exceptions are stable because a standard or conformance suite v1 fixes them: the evidence bundle’s decision and lineage leaves, and the receipt issuer’s JWK.

Breaking a stable field needs v2. v1 keeps answering for at least 180 days after /api/v2 is published. A new enum value on a stable field counts as breaking.

Signed formats do not change in place. Receipts, manifests and evidence bundles carry their own version number (v), and a verifier for one version keeps verifying it. A new layout is a new version, never an edit to the old one.

The SDK follows the same line. @crawlcheck/sdk takes a new major version when a stable field changes, and a minor version when a provisional one does.

Finding codes are part of the contract. A code is never renamed or reused. When a rule changes what it reports it takes a new revision, the record keeps the revision that decided it, and a replay uses that revision. Every code, its meaning, its current revision and its share of scans are in the rulebook (/api/rules, validated by its schema).

How a change is announced

Where	What you see
Response headers	Deprecation: @<unix time> (RFC 9745), Sunset: <HTTP date> (RFC 8594) and Link: <https://crawlcheck.io/docs/api/compatibility>; rel="deprecation", on every v1 response that still carries the field
/api/v1/schema	deprecated: true and x-deprecation on the field; the list in x-compatibility.deprecations
/openapi.json	The same, so generated clients mark the field deprecated
This page and the release notes	The field, the date, the removal date and what to use instead

Deprecated now

None. No v1 field is deprecated today.

Every field

PublicReportV1 stable 75 fields · 48 stable · 23 provisional · 4 internal

Field	Type	Level
schema	string	stable
version	const "1.0"	stable
id	string \| null	stable
domain	string \| null	stable
path	string \| null	stable
scanned_host	string \| null	stable
scanned_at	string \| null	stable
score_version	number \| null	stable
grade	string \| null	stable
overall	number \| null	stable
grade_detail	object	stable
grade_detail.capped	boolean	stable
grade_detail.cap	string \| null	stable
grade_detail.cap_reason	string \| null	stable
sections	array	stable
sections.id	string \| null	stable
sections.title	string \| null	stable
sections.score	number \| null	stable
findings	array	stable
findings.code	string \| null	stable
findings.path	string \| null	stable
findings.severity	number \| null	stable
findings.title	string \| null	stable
findings.detail	string \| null	stable
findings.meaning	string \| null	stable
findings.evidence	string \| null	stable
findings.fid	string \| null	stable
findings.decision_id	string \| null	stable
findings.graph	string \| null	stable
findings.locked	boolean	stable
findings.fingerprint	string \| null	stable
findings.state	enum	provisional
findings.first_seen	string \| null	provisional
findings.scans_seen	number \| null	provisional
findings.recurrences	number \| null	provisional
findings.valid_time	object \| null	provisional
findings_withheld	string \| null	stable
findings_summary	object \| null	stable
findings_summary.total	number \| null	stable
findings_summary.serious	number \| null	stable
findings_summary.by_severity	object \| null	provisional
provenance	object \| null	provisional
root_causes	array \| null	provisional
fix_impact	array \| null	provisional
score_ledger	object \| null	provisional
confidence	object \| null	provisional
bitemporal	object \| null	provisional
non_observations	array \| null	provisional
non_observations.subject	string \| null	provisional
non_observations.state	string \| null	provisional
non_observations.reason	string \| null	provisional
non_observations.attempted	boolean \| null	provisional
fact_lineage	object \| null	provisional
checks	array	stable
checks.path	string \| null	stable
checks.status	number \| null	stable
checks.bytes	number \| null	stable
agentview	array	provisional
agentview.label	string \| null	provisional
agentview.status	number \| null	provisional
agentview.words	number \| null	provisional
nap	object \| null	internal
headroom	object \| null	internal
headroom.gain	number \| null	internal
headroom.failing	number \| null	internal
history	array	stable
history.at	string \| null	stable
history.overall	number \| null	stable
history.score_version	number \| null	stable
proof	object	stable
proof.digest	string \| null	stable
proof.algorithm	string \| null	stable
proof.anchored	string \| null	stable
proof.verify	string \| null	stable
links	object	provisional

MachineRecordV1 provisional 15 fields · 2 stable · 13 provisional · 0 internal

Field	Type	Level
kind	const "crawlcheck-machine-record"	stable
version	string	stable
subject	object	provisional
observation	object	provisional
findings	array	provisional
freshness	object	provisional
fix_impact	array \| object \| null	provisional
score_ledger	object \| null	provisional
confidence	object	provisional
contradictions	object	provisional
findings_summary	object \| null	provisional
findings_withheld	string \| null	provisional
capabilities	object	provisional
evidence	object	provisional
access	object	provisional

ErrorV1 stable 4 fields · 4 stable · 0 provisional · 0 internal

Field	Type	Level
error	object	stable
error.code	string	stable
error.status	integer	stable
error.message	string	stable

EvidenceBundleV1 stable 63 fields · 53 stable · 8 provisional · 2 internal

Field	Type	Level
kind	const "crawlcheck-evidence-bundle"	stable
version	integer	stable
generated_at	string	stable
report	object	stable
report.id	string \| null	stable
report.domain	string \| null	stable
report.path	string \| null	stable
report.scanned_at	string \| null	stable
report.score_version	number \| null	stable
report.archived	boolean	stable
verifier	object	stable
verifier.url	string	stable
verifier.sha256	string	stable
verifier.run	string	stable
verifier.page	string	stable
proves	array	provisional
does_not_prove	array	provisional
manifest	object \| null	stable
manifest.sha256	string	stable
manifest.body	string \| null	stable
manifest.body_missing	string \| null	stable
manifest.signature	object \| null	stable
manifest.signature.alg	string \| null	stable
manifest.signature.kid	string \| null	stable
manifest.signature.message	string \| null	stable
manifest.signature.sig	string \| null	stable
manifest.signature.signed_at	string \| null	stable
manifest.key	object \| null	stable
manifest.key.jwk	object	stable
manifest.key.jwk.kty	const "OKP"	stable
manifest.key.jwk.crv	const "Ed25519"	stable
manifest.key.jwk.x	string	stable
manifest.key.kid	string	stable
manifest.key.published_in	string	stable
manifest.key_missing	string \| null	stable
record	object \| null	stable
record.digest	string \| null	stable
record.subject	string \| null	stable
record.subject_withheld	string \| null	stable
record.recipe	string \| null	internal
record.decision_leaves	array \| null	stable
record.lineage_leaves	array \| null	stable
record.leaves_withheld	string \| null	stable
seal	object \| null	stable
seal.state	enum	stable
seal.day	string \| null	stable
seal.root	string \| null	stable
seal.path	array	stable
seal.path.side	enum	stable
seal.path.hash	string	stable
seal.leaves_that_day	number \| null	stable
seal.sealed_at	string \| null	stable
seal.calendars	array	stable
seal.ots_base64	string \| null	stable
seal.bitcoin_block	number \| null	stable
seal.recipe	string \| null	internal
seal.why	string \| null	stable
publish_guard	object	provisional
publish_guard.checked	array	provisional
publish_guard.withheld	array	provisional
publish_guard.withheld.section	string	provisional
publish_guard.withheld.matched	array	provisional
disclosure	string	provisional

RemediationReceiptV1 stable 53 fields · 47 stable · 4 provisional · 2 internal

Field	Type	Level
receipt_id	string	stable
kind	const "crawlcheck-remediation-receipt"	stable
v	const 1	stable
issued_at	string	stable
issuer	object	stable
issuer.observer	string \| null	stable
issuer.version_id	string \| null	stable
issuer.version_tag	string \| null	stable
issuer.key	object	stable
issuer.key.kid	string	stable
issuer.key.jwk	object	stable
issuer.key.published_in	string \| null	stable
subject	object	stable
subject.domain	string	stable
before	ReceiptSideV1	stable
after	ReceiptSideV1	stable
declared_fix	object	stable
declared_fix.kind	string	stable
declared_fix.declared_by	string \| null	stable
declared_fix.declared_at	string \| null	stable
declared_fix.plugin_version	string \| null	stable
declared_fix.fixes	array \| null	stable
declared_fix.note	string \| null	stable
deployed	object	stable
deployed.at	string \| null	stable
deployed.basis	string \| null	stable
verification	object	stable
verification.verdict	enum	stable
verification.summary	string \| null	stable
verification.comparable	boolean	stable
verification.findings	object	provisional
verification.rows	object	provisional
verification.files	array	stable
verification.files.path	string	stable
verification.files.state	string	stable
verification.files.before_sha256	string \| null	stable
verification.files.after_sha256	string \| null	stable
verification.files.before_status	number \| null	stable
verification.files.after_status	number \| null	stable
verification.rollback_needed	boolean	stable
verification.rollback_steps	array	provisional
verification.method	string \| null	internal
links	object	provisional
signature	object	stable
signature.v	number \| null	stable
signature.alg	const "Ed25519"	stable
signature.kid	string	stable
signature.over	string \| null	stable
signature.receipt_sha256	string	stable
signature.message	string	stable
signature.sig	string	stable
signature.signed_at	string \| null	stable
signature.canonical	string \| null	internal

TraceV1 provisional 34 fields · 0 stable · 34 provisional · 0 internal

Field	Type	Level
id	string \| null	provisional
domain	string \| null	provisional
scanned_at	string \| null	provisional
traced	boolean	provisional
why	string \| null	provisional
trace_id	string	provisional
root_span_id	string	provisional
traceparent	string	provisional
parent	object \| null	provisional
parent.span_id	string	provisional
parent.source	string \| null	provisional
parent.previous_trace_id	string \| null	provisional
scan_id	string \| null	provisional
started_at	string \| null	provisional
total_ms	number \| null	provisional
dropped	integer	provisional
recorded_through	any	provisional
spans	array	provisional
errors	array	provisional
errors.error_id	string \| null	provisional
errors.stage	string \| null	provisional
errors.span_id	string \| null	provisional
errors.error	string \| null	provisional
findings	array	provisional
findings.code	string \| null	provisional
findings.decision_id	string \| null	provisional
findings.span_id	string \| null	provisional
findings.parent_span_id	string \| null	provisional
findings.parent_stage	string \| null	provisional
findings.reads	number \| null	provisional
coverage	object	provisional
slowest	array	provisional
decisions_with_spans	number \| null	provisional
note	string \| null	provisional

SpanV1 provisional 17 fields · 0 stable · 17 provisional · 0 internal

Field	Type	Level
span_id	string	provisional
parent_span_id	string	provisional
stage	string	provisional
kind	enum	provisional
start_ms	number	provisional
dur_ms	number \| null	provisional
status	enum	provisional
error_id	string \| null	provisional
code	string \| null	provisional
path	string \| null	provisional
decision_id	string \| null	provisional
reads	array	provisional
reads.experience_id	string \| null	provisional
reads.fetched_in	string \| null	provisional
reads.stage	string \| null	provisional
reads.fetched_after_rule	boolean	provisional
parent_basis	string \| null	provisional

DisputeResolutionV1 provisional 76 fields · 0 stable · 76 provisional · 0 internal

Field	Type	Level
resolution_id	string	provisional
kind	const "crawlcheck-dispute-resolution"	provisional
v	const 1	provisional
schema	string \| null	provisional
dispute_id	string	provisional
issued_at	string	provisional
issuer	object	provisional
issuer.observer	string \| null	provisional
issuer.version_id	string \| null	provisional
issuer.version_tag	string \| null	provisional
issuer.key	object	provisional
issuer.key.kid	string	provisional
issuer.key.jwk	object	provisional
issuer.key.published_in	string	provisional
subject	object	provisional
subject.domain	string	provisional
subject.record	object	provisional
subject.finding	object	provisional
subject.finding.code	string	provisional
subject.finding.path	string \| null	provisional
subject.finding.fid	string \| null	provisional
subject.finding.decision_id	string \| null	provisional
subject.finding.title	string \| null	provisional
subject.finding.severity	number \| null	provisional
subject.finding.rule_revision	number \| null	provisional
dispute	object	provisional
dispute.filed_at	string	provisional
dispute.ground	enum	provisional
dispute.ground_text	string \| null	provisional
dispute.statement	string	provisional
dispute.ownership	object \| null	provisional
dispute.ownership.method	string	provisional
dispute.ownership.at	string	provisional
dispute.ownership.url	string \| null	provisional
dispute.ownership.sha256	string \| null	provisional
remeasurement	object	provisional
remeasurement.replay	object	provisional
remeasurement.replay.reproduces	boolean \| null	provisional
remeasurement.replay.rule	string \| null	provisional
remeasurement.replay.read	any	provisional
remeasurement.replay.why	string \| null	provisional
remeasurement.replay.rule_revision	number \| null	provisional
remeasurement.replay.over	string \| null	provisional
remeasurement.observers	array	provisional
remeasurement.observers.role	enum	provisional
remeasurement.observers.observer_id	string	provisional
remeasurement.observers.network_class	string \| null	provisional
remeasurement.observers.network	string \| null	provisional
remeasurement.observers.at	string \| null	provisional
remeasurement.observers.finding_present	boolean \| null	provisional
remeasurement.observers.inputs_agree	boolean \| null	provisional
remeasurement.observers.method	string \| null	provisional
remeasurement.observers.reading	string \| null	provisional
remeasurement.observers.side	object \| null	provisional
remeasurement.observers.observation	object \| null	provisional
remeasurement.deadline	string \| null	provisional
remeasurement.independent_wait_hours	number \| null	provisional
decision	object	provisional
decision.verdict	enum	provisional
decision.verdict_text	string \| null	provisional
decision.effect	enum	provisional
decision.effect_text	string \| null	provisional
decision.rule	string \| null	provisional
decision.table	string \| null	provisional
decision.derived_by	string \| null	provisional
links	object	provisional
signature	object	provisional
signature.v	const 1	provisional
signature.alg	const "Ed25519"	provisional
signature.kid	string	provisional
signature.over	const "resolution_sha256"	provisional
signature.resolution_sha256	string	provisional
signature.message	string	provisional
signature.sig	string	provisional
signature.signed_at	string	provisional
signature.canonical	string	provisional

RulebookV1 provisional 22 fields · 0 stable · 22 provisional · 0 internal

Field	Type	Level
ok	boolean	provisional
kind	const "crawlcheck-rulebook"	provisional
v	const 1	provisional
generated_at	string	provisional
score_version	number \| null	provisional
schema	string \| null	provisional
counts	object	provisional
counts.rules	integer	provisional
counts.by_kind	object	provisional
counts.by_family	object	provisional
counts.revised	integer	provisional
counts.scored	integer	provisional
scans_counted	integer \| null	provisional
severity_scale	array	provisional
severity_scale.level	string	provisional
method	object	provisional
method.revisions	string \| null	provisional
method.share	string \| null	provisional
method.grade	string \| null	provisional
rules	array	provisional
filter	object \| null	provisional
filter.code	string \| null	provisional

RuleV1 provisional 30 fields · 0 stable · 30 provisional · 0 internal

Field	Type	Level
code	string	provisional
kind	enum	provisional
family	object	provisional
family.id	string	provisional
family.label	string	provisional
title	string \| null	provisional
meaning	string \| null	provisional
severity	object	provisional
severity.level	string \| null	provisional
scored	boolean	provisional
measured_on	string \| null	provisional
revision	object	provisional
revision.current	integer	provisional
revision.revised_at	string \| null	provisional
fix	object	provisional
fix.advice	string \| null	provisional
fix.effort	string \| null	provisional
fix.endpoint	string \| null	provisional
share_of_scans	object	provisional
share_of_scans.pct	number \| null	provisional
share_of_scans.scans	integer \| null	provisional
share_of_scans.of_scans	integer \| null	provisional
share_of_scans.basis	string	provisional
links	object	provisional
links.self	string \| null	provisional
links.api	string \| null	provisional
links.glossary	array	provisional
links.workflow	string \| null	provisional
links.lineage	string \| null	provisional
links.explain_template	string \| null	provisional

FixOutcomesV1 provisional 48 fields · 0 stable · 48 provisional · 0 internal

Field	Type	Level
ok	boolean	provisional
kind	const "crawlcheck-fix-outcomes"	provisional
v	const 1	provisional
generated_at	string	provisional
cached	boolean	provisional
receipt	object	provisional
receipt.id	string	provisional
receipt.domain	string	provisional
receipt.verdict	string \| null	provisional
receipt.findings_cleared	array	provisional
receipt.url	string	provisional
receipt.anchor	object	provisional
receipt.anchor.at	string	provisional
receipt.anchor.day	string	provisional
receipt.anchor.basis	string	provisional
window	object	provisional
window.days	integer	provisional
window.before	object	provisional
window.before.from	string \| null	provisional
window.before.to	string \| null	provisional
window.after	object	provisional
window.after.from	string \| null	provisional
window.after.to	string \| null	provisional
window.after.days_elapsed	integer	provisional
window.after.complete	boolean	provisional
connected	integer	provisional
usable	integer	provisional
series	array	provisional
series.key	string	provisional
series.label	string	provisional
series.source	string	provisional
series.mode	enum	provisional
series.connected	boolean	provisional
series.note	string	provisional
series.how_to_connect	string \| null	provisional
series.before	\| null	provisional
series.after	\| null	provisional
series.delta_per_day	number \| null	provisional
series.pct	number \| null	provisional
series.usable	boolean	provisional
series.why	string	provisional
not_measured	array	provisional
not_measured.key	string	provisional
not_measured.why	string	provisional
summary	string	provisional
reading	string	provisional
not_proof	string	provisional
how_to_cite	string	provisional

OutcomeSideV1 provisional 6 fields · 0 stable · 6 provisional · 0 internal

Field	Type	Level
from	string \| null	provisional
to	string \| null	provisional
days	integer	provisional
measured	integer	provisional
sum	number	provisional
per_day	number \| null	provisional

ReceiptSideV1 stable 10 fields · 10 stable · 0 provisional · 0 internal

Field	Type	Level
report_id	string \| null	stable
scanned_at	string \| null	stable
grade	string \| null	stable
score	number \| null	stable
score_version	number \| null	stable
refused	boolean	stable
findings	number \| null	stable
manifest_sha256	string \| null	stable
decision_root	string \| null	stable
trace_id	string \| null	stable

MachineExperienceRecordV1 stable 28 fields · 23 stable · 4 provisional · 1 internal

Field	Type	Level
v	enum	stable
scanned_at	string \| null	stable
recorded_at	string	stable
observer	object	stable
observer.version_id	string \| null	stable
observer.version_tag	string \| null	stable
observer.score_version	integer \| null	stable
observer.meg_v	integer	stable
observer.vantage	object	provisional
observer.vantage.kind	string	provisional
observer.vantage.colo	string \| null	provisional
identity_basis	string	stable
representation	string	stable
stored_means	string	stable
request_profiles	object	provisional
experiences	array	stable
roots	object	stable
roots.v	integer	stable
roots.recipe	string	internal
roots.experiences	object	stable
roots.experiences.n	integer	stable
roots.experiences.root	string	stable
roots.decisions	object	stable
roots.decisions.n	integer	stable
roots.decisions.root	string	stable
roots.lineage	object	stable
roots.lineage.n	integer	stable
roots.lineage.root	string	stable

ExperienceV1 stable 14 fields · 12 stable · 2 provisional · 0 internal

Field	Type	Level
experience_id	string	stable
role	enum	stable
identity	string	stable
url	string	stable
final_url	string \| null	stable
status	integer \| null	stable
content_type	string \| null	stable
bytes	integer	stable
sha256	string \| null	stable
stored	enum	stable
request_profile	string \| null	stable
observed_at	string \| null	stable
error	string \| null	provisional
via	string \| null	provisional

ManifestSignatureV1 stable 10 fields · 9 stable · 0 provisional · 1 internal

Field	Type	Level
v	integer	stable
alg	const "Ed25519"	stable
kid	string	stable
key_storage	string \| null	internal
over	const "manifest_sha256"	stable
message	string	stable
sig	string	stable
signed_at	string	stable
key_directory	string	stable
verify	string	stable

Something you rely on is provisional or internal and you want it promoted? Write to hello@crawlcheck.io. Promotion is one-way: a field never moves from stable back to provisional.