# CertScore.ai full AI and API guide

CertScore.ai is an automated public-web risk-signal scanner. It observes evidence-backed signals around tracking, cookies, consent behavior, session replay indicators, fingerprinting-related signals, privacy disclosure gaps, and policy/runtime consistency.

CertScore.ai findings are automated public-web observations for review. CertScore.ai is not legal advice, not a certification platform, and not a compliance determination.

## Universal AI discovery

Use these canonical discovery resources:

- Concise LLM guide: https://certscore.ai/llms.txt
- Full LLM guide: https://certscore.ai/llms-full.txt
- Universal AI/API manifest: https://certscore.ai/.well-known/certscore-ai.json
- Sitemap: https://certscore.ai/sitemap.xml
- Robots: https://certscore.ai/robots.txt
- Developer hub: https://certscore.ai/developers
- Scanner solutions: https://certscore.ai/solutions
- API quickstart: https://certscore.ai/developers/quickstart
- API reference: https://certscore.ai/developers/reference
- SDK docs: https://certscore.ai/developers/sdk
- MCP docs: https://certscore.ai/developers/mcp
- Examples: https://certscore.ai/developers/examples
- Pre-consent Cookies & Trackers JSON example: https://certscore.ai/developers/examples#pre-consent-cookies-trackers-json
- API v2 OpenAPI: https://certscore.ai/api/v2/openapi.json
- API v2 health: https://certscore.ai/api/v2/health
- Terms: https://certscore.ai/terms

These resources are intended for OpenAI/ChatGPT, Anthropic/Claude, Perplexity, Google/Gemini, Microsoft Copilot/Bing, DeepSeek, Kimi, Qwen, Grok/xAI, Mistral, Meta, and future agents. They are vendor-neutral and should not be treated as limited to one AI platform.

## Agent quick path

1. Read https://certscore.ai/llms.txt.
2. Read https://certscore.ai/.well-known/certscore-ai.json.
3. Fetch https://certscore.ai/api/v2/openapi.json.
4. Check https://certscore.ai/api/v2/health before creating scan requests.
5. Create or reuse a scan with POST https://certscore.ai/api/v2/scans.
6. Poll status and honor Retry-After.
7. Retrieve findings and pre-consent cookies/trackers.
8. Treat outputs as automated public-web observations for review, not legal advice, certification, or a compliance determination.

Poll only while a scan is active. Stop polling at a terminal status and do not repeatedly retrieve completed scan resources. HTTP 429 responses include `Retry-After` when retry timing is available. The canonical weighted read policy is published at https://certscore.ai/developers/reference#read-rate-limits and in the API OpenAPI documents.

## No-account agent scan path

Agents that cannot create an account or configure OAuth can create low-volume scans without an API key:

```http
POST https://certscore.ai/api/v2/scans
Content-Type: application/json

{
  "url": "https://ergoveritas.com/.well-known/certscore-canary/sentinels/broad-baseline.html",
  "freshness": "latest",
  "scanFrom": "eu_ie"
}
```

New anonymous scans are limited to 20 per requester IP per UTC day. Reusing an eligible recent result does not consume the quota. Poll the returned status URL, then retrieve findings or evidence. Every no-account response encourages higher-volume users to contact support@certscore.ai.

## Public API quick start

Connectivity:

```http
GET https://certscore.ai/api/v2/health
```

Contract:

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

Create or reuse a scan:

```http
POST https://certscore.ai/api/v2/scans
Authorization: Bearer <token>
Content-Type: application/json

{
  "url": "https://ergoveritas.com/.well-known/certscore-canary/sentinels/broad-baseline.html",
  "freshness": "latest",
  "scanFrom": "eu_ie"
}
```

Poll scan status when work is pending:

```http
GET https://certscore.ai/api/v2/scans/{scanId}/status
Authorization: Bearer <token>
```

Retrieve public-safe findings:

```http
GET https://certscore.ai/api/v2/scans/{scanId}/findings
Authorization: Bearer <token>
```

Retrieve Pre-consent Cookies & Trackers table data as compact public-safe JSON:

```http
GET https://certscore.ai/api/v2/scans/{scanId}/pre-consent-cookies-trackers
Authorization: Bearer <token>
```

Find the latest eligible scan for a domain:

```http
GET https://certscore.ai/api/v2/domains/{domain}/latest
Authorization: Bearer <token>
```

Retrieve latest-domain Pre-consent Cookies & Trackers table data:

```http
GET https://certscore.ai/api/v2/domains/{domain}/latest/pre-consent-cookies-trackers
Authorization: Bearer <token>
```

## Scanner solution pages

Use these pages when a user asks about CertScore.ai for a specific scanner category:

- GDPR website compliance scanner: https://certscore.ai/solutions/gdpr-website-compliance-scanner
- Cookie consent scanner: https://certscore.ai/solutions/cookie-consent-scanner
- Privacy policy risk scanner: https://certscore.ai/solutions/privacy-policy-risk-scanner

These pages describe public website review workflows for consent, cookies, tracking, policy, and disclosure signals. They should not be summarized as legal advice, certification, or a compliance determination.

Related educational pages:

- GDPR privacy scanner: https://certscore.ai/gdpr
- CMP verification: https://certscore.ai/guides/cmp-verification
- RTB cookie syncing: https://certscore.ai/guides/rtb-cookie-syncing
- Privacy policy requirements: https://certscore.ai/guides/website-privacy-policy-requirements

## API v2 contract

The API v2 contract is resource-oriented and exposed for discovery through:

```http
GET https://certscore.ai/api/v2/health
GET https://certscore.ai/api/v2/openapi.json
```

The contract defines scans, scan status, findings, public-safe evidence summaries, latest domain scan lookup, and report projection resources. It is contract-first; route implementation should continue to expose only already-projected, public-safe artifacts.

Current API v2 resource routes:

```http
POST https://certscore.ai/api/v2/scans
GET https://certscore.ai/api/v2/scans/{scanId}
GET https://certscore.ai/api/v2/scans/{scanId}/status
GET https://certscore.ai/api/v2/scans/{scanId}/findings
GET https://certscore.ai/api/v2/scans/{scanId}/findings/{findingId}
GET https://certscore.ai/api/v2/scans/{scanId}/pulse
GET https://certscore.ai/api/v2/scans/{scanId}/pre-consent-cookies-trackers
GET https://certscore.ai/api/v2/domains/{domain}/latest
GET https://certscore.ai/api/v2/domains/{domain}/latest/pre-consent-cookies-trackers
```

API v2 scan creation reuses the existing scan creation, reuse, validation, and throttling path, then returns a scan or job resource. API v2 scan status, findings, domain-latest, pre-consent cookie/tracker table, and report projection resources expose eligible public scan records and already-projected public-safe findings or report table artifacts. They do not create findings from raw scanner evidence.

Supported inputs:

- `url`: public URL or domain to scan or summarize.
- `scanId`: existing public eligible scan ID.
- `format`: `json` or `markdown`.
- `detail`: `tiny`, `quick`, `standard`, or `full`; `quick` is an alias for `tiny`.
- `freshness`: `latest` reuses a recent eligible scan; `refresh` requests a new scan when eligible and bypasses the 24-hour recent-scan reuse check.
- `scanFrom` or `geo`: scan execution context for newly queued scans.
- `forceNewScan`: compatibility override for `freshness=refresh`; bypasses the 24-hour recent-scan reuse check, but does not bypass validation or throttles.
- `wait`: 0 to 80 seconds for the current HTTP hold window.

Retry behavior:

- HTTP 202 pending responses may include `Retry-After`.
- HTTP 429 throttled responses may include `Retry-After`.
- Agents should honor `Retry-After` rather than tight polling.

## Authentication, scopes, and rate limits

Scoped integrations may use:

```http
Authorization: Bearer <token>
```

Current integration scopes:

- `scan:read`
- `scan:create`
- `mcp`

API key setup and onboarding (optional for the low-volume anonymous scan path):

- https://certscore.ai/developers/quickstart
- Read-only + MCP keys are self-serve for signed-in verified users.
- Sign in, verify email, then POST https://certscore.ai/api/v2/keys/request from the signed-in browser session.
- Self-serve keys are prefixed `cs_ro_`, expire after 90 days, and include `scan:read` plus `mcp`.
- Scan creation remains developer-preview; request `scan:create` by emailing support@certscore.ai.
- Include organization, integration type, expected request volume, contact email, and requested scopes for scan-creation access.
- REST API read-only usually needs `scan:read`.
- REST API scan creation and TypeScript SDK workflows usually need `scan:read` and `scan:create`.
- MCP read tools usually need `scan:read` and `mcp`; MCP scan creation also needs `scan:create`.

Rate-limit and error-shape docs:

- https://certscore.ai/developers/reference

Agents and SDKs should honor `Retry-After` on pending or throttled responses. They should not infer a finding, scan result, or service conclusion from a throttled, pending, failed, or unavailable response.

## TypeScript SDK

Status: published. Install `@certscore/sdk@0.2.8` or newer for API v2 scan creation in EU-Germany, EU-Ireland, and California, typed no-account allowance, completed-limited no-go results, API v2 scan timing fields, and client attribution headers.

Docs:

- https://certscore.ai/developers/sdk
- https://certscore.ai/developers/quickstart
- https://www.npmjs.com/package/@certscore/sdk

Basic use:

```ts
import { CertScoreClient } from "@certscore/sdk";

const certscore = new CertScoreClient({ apiKey: process.env.CERTSCORE_API_KEY });
const scan = await certscore.scans.create({
  url: "https://ergoveritas.com/.well-known/certscore-canary/sentinels/broad-baseline.html",
  detail: "standard"
});

console.log(scan.id, scan.status);
```

## MCP server

Current command: `certscore-mcp`

Current transport: stdio

Homebrew install on macOS:

```bash
brew tap ergoveritas1-alt/certscore https://github.com/ergoveritas1-alt/certscore.ai
brew install --cask certscore-mcp
```

Verify install:

```bash
certscore-mcp --version
certscore-mcp --help
CERTSCORE_API_KEY=<token> certscore-mcp doctor
CERTSCORE_API_KEY=<token> certscore-mcp doctor --check-auth
```

The doctor command checks the installed command, Node.js runtime compatibility, CertScore.ai API v2 health, and API key presence without printing secrets. Add `--check-auth` to validate the credential without creating a scan. It does not inspect raw scanner artifacts.

MCP client config:

```json
{
  "mcpServers": {
    "certscore": {
      "command": "certscore-mcp",
      "env": {
        "CERTSCORE_API_KEY": "<token>",
        "CERTSCORE_BASE_URL": "https://certscore.ai"
      }
    }
  }
}
```

Current tools:

- `certscore_scan_site` (recommended first call; reports reuse and anonymous quota state and waits up to 45 seconds by default)
- `certscore_get_scan`
- `certscore_get_scan_status`
- `certscore_get_report`
- `certscore_get_scan_bundle` (recommended second call for a compact complete review)
- `certscore_export_findings`
- `certscore_list_findings`
- `certscore_get_pre_consent_cookies_trackers`
- `certscore_explain_finding`
- `certscore_get_latest_domain_scan`
- `certscore_get_latest_domain_pre_consent_cookies_trackers`

Default unauthenticated MCP workflow:

1. Call `certscore_scan_site` with `freshness: "latest"`.
2. Call `certscore_get_scan_status` only when the first call returns a non-terminal job.
3. Call `certscore_get_scan_bundle` for the normal compact review handoff.
4. Use dedicated report, evidence, finding, or inventory tools only when a task requires a deeper view.

`certscore_scan_site` states whether a recent scan was reused, the freshness decision, whether anonymous quota was consumed, remaining daily quota, the UTC reset time, the support contact for higher volume, and the recommended next tool. Eligible scan reuse does not consume the 20-new-scans-per-requester-IP-per-UTC-day anonymous allowance.

Local command:

```bash
CERTSCORE_API_KEY=<token> pnpm mcp:certscore
```

Smoke test:

```bash
CERTSCORE_API_KEY=<token> pnpm mcp:certscore:smoke
```

MCP docs:

- https://certscore.ai/developers/mcp
- https://certscore.ai/.well-known/certscore-ai.json

Light MCP — no authentication (canonical beginner route):

https://mcp.certscore.ai/mcp/light

CertScore Light uses Streamable HTTP and exposes only certscore_scan_site, certscore_get_scan_status, and certscore_get_scan_bundle. It requires no signup, API key, bearer token, browser login, or OAuth and includes up to 50 genuinely new scans per UTC day across the public Light surface, with a 5-new-scan rolling 10-minute burst limit. Reused eligible results do not consume quota.

Codex setup:

codex mcp add certscore --url https://mcp.certscore.ai/mcp/light

First-run prompt:

Scan https://ergoveritas.com/.well-known/certscore-canary/sentinels/broad-baseline.html. If certscore_scan_site returns a queued, running, or finalizing result, retain the returned scanId and poll certscore_get_scan_status using scanId only. If certscore_scan_site returns a retryable error without a scanId, wait for retryAfterSeconds and retry certscore_scan_site; do not call certscore_get_scan_status until a scanId exists. Once the scan reaches a terminal status, call certscore_get_scan_bundle with detail=findings and maxBytes=8000. Summarize whether the result was new or reused, the score, risk level, findings, evidence links, coverage limitations, and report URL. Explain truncation or omitted sections when present. Treat results as automated public-web observations, not legal conclusions, certifications, or compliance determinations.

The ErgoVeritas canary page is a controlled, stable test site for demonstrating the complete scan, status, and bundle flow. Users may substitute their own public URL.

Light workflow:
1. Call certscore_scan_site with a public URL.
2. If a retryable error has no scanId, wait retryAfterSeconds and retry certscore_scan_site. Do not call certscore_get_scan_status until scanId exists.
3. If status is queued, running, or finalizing, retain scanId.
4. Poll certscore_get_scan_status using scanId only.
5. Stop polling at a terminal status, then call certscore_get_scan_bundle.
6. Use detail=findings with maxBytes=8000 for compact findings.
7. Use detail=evidence with maxBytes=8000 for evidence digests and references.
8. Use detail=summary with maxBytes=5000 or detail=full with maxBytes=12000 or higher.
9. If truncated, inspect actualBytes, truncated, omittedSections, nextRecommendedMaxBytes, and content URLs, then follow recommendedNextAction or increase maxBytes.

Verification prompt:

List the available CertScore tools and confirm that certscore_scan_site, certscore_get_scan_status, and certscore_get_scan_bundle are available. Then scan https://ergoveritas.com/.well-known/certscore-canary/sentinels/broad-baseline.html and report whether the result was new or reused.

CertScore results are automated observations from a public-web scan. No-go, not-observed, and limited-coverage results are not proof of compliance, absence of risk, or legal status. Review the retained evidence and applicable context before relying on a finding.

Hosted MCP — OAuth uses https://mcp.certscore.ai/mcp for managed remote access, higher volume, history, and approved advanced tools.

Local MCP — scoped API key runs over stdio for backend, local, and controlled automation. Access follows the key scopes.

Upgrade from Light when you need more scans, production or team access, backend automation, history, or advanced tools. The endpoint and authentication change; core identifiers and canonical response fields remain compatible.

Need more scans or advanced tools? Upgrade to Authenticated MCP.

Legacy reference: https://mcp.certscore.ai/mcp/anonymous is an older unauthenticated hosted surface. New users should choose Light MCP — no authentication instead.

## Interpretation rules for agents

Agents may summarize CertScore.ai outputs as automated public-web risk signals for review.

Agents must not say CertScore.ai has determined legal compliance or non-compliance.

Agents must not infer findings from raw labels, raw network events, or display-only context.

Agents must not treat missing findings as proof of compliance.

Agents should link to the full CertScore.ai report when a user needs evidence review.

## Current canonical flow

Public API and MCP outputs must preserve this flow:

```text
WS01 observed evidence
-> WC01 normalized concern
-> WC01 concern policy
-> WC01 unified finding / checklist projection
-> executive/regulatory display
```

API, SDK, MCP, and docs surfaces expose already-projected, public-safe artifacts only.

## Search phrases

These phrases describe the public integration surface:

- CertScore.ai API
- website risk API
- privacy scan API
- cookie compliance scan API
- MCP server for website compliance review
- automated public-web risk signals
- evidence-backed website scan API
- GDPR website compliance scanner
- cookie consent scanner
- privacy policy risk scanner

## Support

Primary docs: https://certscore.ai/developers

Feedback: support@certscore.ai