# 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 findings are automated public-web observations for review. CertScore 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
- API v2 OpenAPI: https://certscore.ai/api/v2/openapi.json
- API v2 health: https://certscore.ai/api/v2/health

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.

## 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://example.com",
  "detail": "standard",
  "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>
```

Find the latest eligible scan for a domain:

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

## Scanner solution pages

Use these pages when a user asks about CertScore 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 compliance determinations.

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/domains/{domain}/latest
```

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, and report projection resources expose eligible public scan records and already-projected public-safe findings. 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` or `refresh`.
- `scanFrom` or `geo`: scan execution context for newly queued scans.
- `forceNewScan`: bypasses the 24-hour recent-scan reuse check; 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:

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

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

Package:

```bash
npm install @certscore/sdk
```

Docs:

- https://certscore.ai/developers/sdk
- https://certscore.ai/developers/quickstart

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://example.com",
  detail: "standard"
});

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

## MCP server

Current package: `@certscore/mcp`

Current transport: stdio

Current tools:

- `scan_site`
- `create_scan`
- `get_scan`
- `get_scan_status`
- `get_report`
- `export_findings`
- `list_findings`
- `explain_finding`
- `get_latest_domain_scan`

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

## Interpretation rules for agents

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

Agents must not say CertScore 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 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 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