API quickstart

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.

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"