API quickstart

Completed resources can include postAcceptObservation, postRefusalObservation, and gpcResponse. Read each observation's status before its verdict: a non-confirmed status is limited coverage and must not be reported as clean. Post-Accept activity is a score-neutral baseline.

CertScore.ai API, SDK, and MCP integrations use bearer API keys. Read-only report retrieval and MCP read tools can use a self-serve key after sign-in and email verification. Scan creation keys remain developer-preview and are issued by emailing [email protected].

Self-serve read-only key:
1. Sign in at https://certscore.ai/login and verify your email.
2. POST https://certscore.ai/api/v2/keys/request from the signed-in browser session.
3. Store the returned cs_ro_ key and use it as CERTSCORE_API_KEY.

curl -X POST https://certscore.ai/api/v2/keys/request \
  -H "Content-Type: application/json" \
  --data '{"name":"Read-only MCP key"}'

Recommended scopes by integration:
- REST API read-only: scan:read
- REST API scan creation: scan:read, scan:create
- TypeScript SDK: scan:read, scan:create
- MCP read tools: scan:read, mcp
- MCP scan creation: scan:read, scan:create, mcp

Self-serve keys are prefixed cs_ro_, expire after 90 days, and are limited to read-only report/API access plus MCP. For scan:create, include your organization, integration type, expected volume, callback or contact email, and requested scopes when emailing support. Active Trial workspaces connecting through Claude receive hosted OAuth scan creation automatically, limited to 20 new scans per hour and 100 per day per workspace; eligible recent-result reuse does not consume the allowance.

For discovery and evaluation, an agent can create a scan without an account or bearer token. New anonymous scans are limited to 20 per requester IP per UTC day; an eligible recent-result reuse does not consume the quota. Contact [email protected] for a higher-volume allowance. Poll the returned status resource and then retrieve findings. Use a scoped key or hosted OAuth for repeated or higher-volume workflows.

curl -X POST https://certscore.ai/api/v2/scans \
  -H "Content-Type: application/json" \
  -d '{"url":"https://ergoveritas.com/.well-known/certscore-canary/sentinels/broad-baseline.html","freshness":"latest","scanFrom":"eu_ie"}'

curl https://certscore.ai/api/v2/health
curl https://certscore.ai/api/v2/openapi.json

export CERTSCORE_API_KEY="cs_live_..."
TARGET_URL="https://ergoveritas.com/.well-known/certscore-canary/sentinels/broad-baseline.html"

SCAN_RESPONSE=$(curl -sS -D /tmp/certscore-create-headers.txt \
  -X POST https://certscore.ai/api/v2/scans \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CERTSCORE_API_KEY" \
  --data @- <<JSON
{"url":"$TARGET_URL","freshness":"latest","scanFrom":"eu_ie"}
JSON
)

SCAN_ID=$(printf '%s' "$SCAN_RESPONSE" | jq -r '.scanId // .scan.scanId // empty')
JOB_ID=$(printf '%s' "$SCAN_RESPONSE" | jq -r '.jobId // empty')

if [ -z "$SCAN_ID" ] && [ -n "$JOB_ID" ]; then
  echo "Scan queued as job $JOB_ID; poll the returned status link until a scanId is available."
  exit 1
fi

while true; do
  curl -sS -D /tmp/certscore-status-headers.txt \
    -H "Authorization: Bearer $CERTSCORE_API_KEY" \
    "https://certscore.ai/api/v2/scans/$SCAN_ID/status" \
    -o /tmp/certscore-status.json

  STATUS=$(jq -r '.status // "unknown"' /tmp/certscore-status.json)
  case "$STATUS" in
    completed|completed_limited) break ;;
    failed|expired|rate_limited)
      cat /tmp/certscore-status.json
      exit 1
      ;;
  esac

  RETRY_AFTER=$(awk 'BEGIN{IGNORECASE=1} /^Retry-After:/ {print $2}' /tmp/certscore-status-headers.txt | tr -d '\r')
  sleep "${RETRY_AFTER:-10}"
done

curl -sS -H "Authorization: Bearer $CERTSCORE_API_KEY" \
  "https://certscore.ai/api/v2/scans/$SCAN_ID/findings" \
  -o certscore-findings.json

curl -sS -H "Authorization: Bearer $CERTSCORE_API_KEY" \
  "https://certscore.ai/api/v2/scans/$SCAN_ID/pre-consent-cookies-trackers" \
  -o certscore-pre-consent-cookies-trackers.json

jq '.findings | length' certscore-findings.json
jq '.summary' certscore-pre-consent-cookies-trackers.json

This example uses jq to extract fields and print summaries. jq is optional; any JSON parser can read the same fields. Honor Retry-After on pending or throttled responses.

curl -X POST https://certscore.ai/api/v2/scans \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CERTSCORE_API_KEY" \
  -d '{
    "url": "https://ergoveritas.com/.well-known/certscore-canary/sentinels/broad-baseline.html",
    "freshness": "latest",
    "scanFrom": "eu_ie"
  }'

Scan creation may return a completed scan resource or a queued job resource.

curl https://certscore.ai/api/v2/scans/{scanId}/status \
  -H "Authorization: Bearer $CERTSCORE_API_KEY"

Honor Retry-After on pending or throttled responses. Queue time and page runtime can exceed the current HTTP request hold window.

curl https://certscore.ai/api/v2/scans/{scanId}/findings \
  -H "Authorization: Bearer $CERTSCORE_API_KEY"

Findings are sourced from already-projected public report artifacts. Evidence examples are compact and capped for public API use.

curl https://certscore.ai/api/v2/domains/ergoveritas.com/latest \
  -H "Authorization: Bearer $CERTSCORE_API_KEY"

curl https://certscore.ai/api/v2/scans/{scanId}/pre-consent-cookies-trackers \
  -H "Authorization: Bearer $CERTSCORE_API_KEY"