Developer docs

API reference

Reference for the CertScore API v2 resource model, OpenAPI contract, status lifecycle, public-safe evidence summaries, errors, throttling, and legal posture.

CertScore outputs are automated public-web observations for review. They are not legal advice, certification, or a compliance determination.

Routes

API v2 resources

Method	Route	Purpose
POST	/api/v2/scans	Create or reuse a public scan through the resource API.
GET	/api/v2/scans/{scanId}	Retrieve the public-safe scan resource.
GET	/api/v2/scans/{scanId}/status	Check scan or job status without inferring from partial evidence.
GET	/api/v2/scans/{scanId}/findings	List already-projected public findings for a scan.
GET	/api/v2/scans/{scanId}/findings/{findingId}	Retrieve one public-safe finding and capped evidence summary.
GET	/api/v2/domains/{domain}/latest	Find the latest eligible public scan for a domain.
GET	/api/v2/openapi.json	Fetch the machine-readable API v2 contract.
GET	/api/v2/health	Check API v2 discovery health.

Contract

OpenAPI and operation IDs

GET https://certscore.ai/api/v2/openapi.json

The OpenAPI contract uses stable operation IDs, explicit status examples, error examples, retry guidance, and public-safe evidence language for generic AI agents and developer tools.

Auth

API keys, scopes, and rate limits

Authorization: Bearer <token>

Current scopes:
- scan:read
- scan:create
- mcp

Scoped integrations use bearer API keys. HTTP 202 pending responses and HTTP 429 throttled responses may include Retry-After; agents and SDKs should honor that value rather than tight polling.

Errors

Public-safe error envelope

{
  "type": "certscore_api_error",
  "error": {
    "code": "not_found",
    "message": "Scan not found."
  },
  "links": {
    "docs": "https://certscore.ai/developers/reference"
  }
}

Status

Polling and retry behavior

completed

The scan resource and public-safe projections are ready.

pending/running/finalizing

Poll the status resource and honor Retry-After when present.

failed/not_found/throttled

Use the public error envelope and do not infer missing findings from failed work.

Evidence discipline

What API v2 exposes

API v2 exposes scan resources, status, already-projected findings, public-safe evidence summaries, latest-domain lookup, and report-ready review context. It does not expose raw DOM, raw request bodies, internal scanner artifacts, internal reasoning, or display-only findings.