Docs
Build with Scovant.

Run scans, simulations, and showcase from the dashboard — or drive it all from your pipeline: the REST API, CI/CD trigger, webhooks, and the MCP interface are live today. Entries marked “Soon” are on the roadmap.

Quickstart · 4 of 8

Scans.

A scan crawls your site and evaluates every compatibility rule in the public catalog — the full, versioned catalog is public at /rules.

Trigger a scan

POST /api/scans

Body: { "site_id": "<uuid>", "targets": [{ "type": "url", "url": "https://example.com" }] }

POST /api/scans also accepts an scvt_ API token (Authorization: Bearer scvt_...), scoped to the token's workspace.

Returns { "id": "...", "status": "queued" } immediately.

Scans cost 1 credit — the same workspace balance used for simulations and Fix Plans. When the balance is insufficient the endpoint returns 402 with the available credit packs and no scan is created. Team, Business and Enterprise workspaces don't spend credits on scans. If a scan gets stuck in the pipeline, Scovant automatically sweeps it to failed and refunds the credit.

Scan lifecycle

pending → queued → running → scoring → completed | failed | partial

Scoring categories:

  • Discoverability (robots.txt, sitemap, canonical tags)
  • Structured data (JSON-LD schemas)
  • Consistency (price display vs structured data, conflicting or duplicate entities)
  • Actionability (works without JavaScript, deep links, MCP/agent-interface discovery)
  • Trust (returns policy, shipping info, citation/OpenGraph meta)
  • UCP (Universal Commerce Protocol profile, checkout, signing keys)
  • Citability (content sites only — how readily AI search engines can quote your pages)

Versioned JSON report

GET /api/scans/{scan_id}/report

Returns the scan as one versioned JSON document (schema_version, scores, readiness with the Agent and Technical results — rating, grade, badge, status, coverage and model id, plus on each result evidence_state (NOT_MEASURED — no number | ESTIMATED — passive evidence only | VERIFIED — at least one agent journey ran | ACCESS_REFUSED — every page we fetched was a bot challenge, so no rating is computed for public display), execution_performed, scope and label, and on the block labels_enabled and profile; plus degraded_reason (site_refused_fetch / site_errors / null) on a degraded Agent result — issues with rule maturity/version, and the exact ruleset_version that produced it) — the machine-readable counterpart of the dashboard view. Under the R2 scoring model overall_score on scan responses mirrors readiness.agent.rating and is a deprecated alias — read the readiness block. Returns 409 while the scan is still in flight (report_not_ready) or if it failed (report_unavailable).

Reports can be shared without authentication: POST /api/scans/{scan_id}/report/publish (workspace owner only) mints an opaque share token, .../report/revoke withdraws it, and the shared copy is served at GET /api/public/report/{token}.json. The same report is available to agents through the MCP tool get_scan_report (see MCP interface & badges).

Security section

Every scan report (schema_version 1.1) carries a security block: the passive Agentic Security & Trust checks that the open-source Scovant Core engine runs for the scanned domain (web baseline, disclosure, machine-facing data exposure, prompt/instruction surface). It is labelled PASSIVE SIGNALS ONLY and is never part of the readiness score.

  • status is measured, pending (the probe is still running for a scan that just finished), unavailable (the probe could not run — the reason is recorded) or disabled.
  • findings[] list each check with its family id, status, severity, confidence, verification mode (DECLARED or PASSIVE_OBSERVED), fix owner and redacted evidence; credential-shaped values are never stored.
  • conflicts[] name places where two observations of the same site disagree — the declared agent policy versus the observed edge behaviour, a human-vs-machine boundary mismatch (HUMAN_VS_MACHINE_BOUNDARY_MISMATCH, where the machine-facing mirror carries instructions that the visible page does not), or an agent-identity divergence (AGENT_IDENTITY_DIVERGENCE, where the edge served one declared crawler identity and refused another in the same scan). They describe a difference; they do not judge either side.
  • not_tested lists what a passive scan cannot establish: observed authorization, verified agent identity, prompt-injection resilience, tool invocation safety.

This section evaluates tested AI-agent security controls and machine-facing security signals. It is not an overall website or application security rating.

Active (authorized) checks

When you verify your domain by DNS TXT, switch on Active security testing for a site and store a credential, each scan also runs an authorized active check against the MCP endpoints your own discovery file declares. The report carries it as security.active.

  • It authenticates with the credential you supplied and calls only tools it classifies as read-only, with empty arguments. Against your production endpoints it never calls a tool that creates, changes, sends or deletes anything, and it never calls a tool whose declared annotations say it changes state.
  • authorization records what was checked at run time: the verification method, the live DNS re-check, your opt-in, the endpoints in scope and the endpoints skipped for being on another host. Consent is re-established on every run — switching the toggle off, deleting the credential or removing the TXT record stops it at the next scan.
  • calls records how many calls were planned, made and refused, and which tools were skipped with the class or schema reason for each.
  • findings are experimental and never affect your readiness score. Each one names the probe that produced it (probe.kind, probe.tool, probe.scope_variant) so you can reproduce it.
  • not_tested lists what an authorized read-only run cannot establish: write and destructive tools (exercised only against a declared sandbox — see below), gateway consistency, data safety under invocation, authorization-code flows and verified agent identity.

Response bodies are classified and discarded. Your credential is stored encrypted, is never logged, and never appears in any report.

Sandbox writes (opt-in)

With a sandbox endpoint (sandbox_endpoint_url — https, on your DNS-verified domain or a subdomain, never your production host) and a sandbox credential, the active check also exercises write-class tools — against the sandbox only, with canary arguments, within a budget of 8 calls. Results land in security.active.sandbox (owner-only) with rules TOOL-RISK-005..007; an elicitation (confirmation request) is recorded as confirmation_requested, never as a finding. Production endpoints stay read-only.