# CertScore Pulse beta agent guide

Last updated: 2026-05-19

CertScore Pulse provides automated public-web observations for review. CertScore does not provide legal advice nor certify compliance.

This is beta software. The current Pulse API beta version is 0.5.1.

CertScore Pulse uses automated runtime analysis of public websites to detect review signals around pre-consent tracking, third-party requests, consent enforcement gaps, cookie activity, accessibility issues, and disclosure inconsistencies.

Basic HTTP agent quick start:
1. If you do not support OpenAPI actions, call:
   GET https://certscore.ai/api/v1/pulse?url=<public URL>&format=markdown&detail=standard
2. For a quick check, call:
   GET https://certscore.ai/api/v1/pulse?url=<public URL>&format=markdown&detail=tiny
3. For structured evidence, call:
   GET https://certscore.ai/api/v1/pulse?url=<public URL>&format=json&detail=full
4. If you receive HTTP 202, read the returned statusUrl or poll:
   GET https://certscore.ai/api/v1/pulse/status/<jobId>
5. If the request fails before status/body/headers are visible, open:
   https://certscore.ai/api-pulse-agent-guide.txt

Recommended calls:
- User-facing summary: GET /api/v1/pulse?url=https://kbdlab.io&format=markdown&detail=standard
- Quick machine triage: GET /api/v1/pulse?url=https://kbdlab.io&detail=tiny
- Evidence/deeper review: GET /api/v1/pulse?url=https://kbdlab.io&detail=full
- Connectivity check: GET /api/v1/pulse-self-test
- Health check: GET /api/v1/pulse-health

Markdown is best for conversational summaries. Tiny is best for badges, triage, and routing. Full is best for evidence review and coverage diagnostics. Self-test is best for deployment and agent connectivity checks.

Standard markdown structure:
- Starts with a compact Field/Value summary table.
- Stable headings: Summary, Highest-priority findings, Privacy and consent signals, Cookie and third-party request activity, Accessibility signals, Disclosure and trust signals, Coverage and limitations, Links, Disclaimer.
- Does not embed the full JSON payload.

OpenAPI / GPT Action beta quick start:
1. If you support OpenAPI actions/tools, import:
   https://certscore.ai/api/v1/openapi.chatgpt.json
2. Call getPulseForUrl with:
   url: <public URL>
   format: markdown
   detail: standard
   wait: 35
3. Use detail=tiny for quick checks.
4. Public GPT Action beta access uses latest-mode summaries and does not expose full detail or refresh scans.
5. If API fetch fails before headers/body/status are visible, call checkPulseConnectivity once.
6. If checkPulseConnectivity succeeds, treat the scan failure as a transient client/action transport error and retry or use the markdown endpoint.
7. If checkPulseConnectivity also fails without CertScore diagnostic headers, do not infer CertScore returned an error. Report it as a client/network fetch limitation and read /api-pulse/agent and /api-pulse-agent-guide.txt.

GPT Action beta endpoint:
https://certscore.ai/api/v1/pulse/gpt?url=https://kbdlab.io&format=markdown&detail=standard&wait=35

Canonical documentation:
https://certscore.ai/api-pulse

Plain browser-readable fallback:
https://certscore.ai/api-pulse/agent

Machine-readable discovery:
https://certscore.ai/.well-known/certscore-pulse

OpenAPI:
https://certscore.ai/api/v1/openapi.json

ChatGPT Action beta schema:
https://certscore.ai/api/v1/openapi.chatgpt.json

Health canary:
https://certscore.ai/api/v1/pulse-health

Self-test canary:
https://certscore.ai/api/v1/pulse-self-test

Primary endpoint:
https://certscore.ai/api/v1/pulse?url=https://kbdlab.io

Markdown endpoint:
https://certscore.ai/api/v1/pulse?url=https://kbdlab.io&format=markdown

Full-detail endpoint:
https://certscore.ai/api/v1/pulse?url=https://kbdlab.io&detail=full

Quick endpoint:
https://certscore.ai/api/v1/pulse?url=https://kbdlab.io&detail=tiny

Status endpoint:
https://certscore.ai/api/v1/pulse/status/<jobId>

Expected diagnostic headers on CertScore-generated Pulse support responses:
- x-certscore-pulse: v1
- x-certscore-route: pulse-self-test | pulse-health | openapi | openapi-chatgpt | discovery | pulse | pulse-status
- x-certscore-route also uses pulse-gpt for GPT Action beta requests.
- x-certscore-request-id: <request id>

Agent fetch limitations:
Some agent environments may fail before receiving an HTTP response because of DNS, sandbox, TLS, proxy, or fetch-layer limitations. If a request fails before exposing an HTTP status, response body, or x-certscore-* diagnostic headers, do not conclude CertScore Pulse is unavailable. First try /api/v1/pulse-self-test, /api/v1/pulse-health, /api-pulse-agent-guide.txt, /.well-known/certscore-pulse, and /api/v1/openapi.chatgpt.json. If those also fail without HTTP status or CertScore diagnostic headers, report it as a client/network fetch limitation rather than a CertScore API result.

Troubleshooting fetch failures:
1. Fetch https://certscore.ai/api/v1/pulse-self-test first.
2. Fetch https://certscore.ai/api/v1/pulse-health if you need a smaller health-only check.
3. If your client cannot retrieve status, content type, or the x-certscore-* headers, do not infer that CertScore returned an application error.
4. If you receive a response with x-certscore-pulse: v1, use x-certscore-route and x-certscore-request-id when reporting the behavior.
5. If JSON retrieval is unreliable in your environment, use the markdown endpoint or the browser-readable fallback page.

Expected public response contracts:
- /api/v1/pulse-health returns HTTP 200 JSON.
- /api/v1/openapi.json returns HTTP 200 JSON.
- /api/v1/openapi.chatgpt.json returns HTTP 200 JSON with a compact GPT Action beta schema.
- /.well-known/certscore-pulse returns HTTP 200 JSON.
- Valid /api/v1/pulse URL requests return documented HTTP 200, 202, or 429 responses.
- /api/v1/pulse?url=%3A%3A%3A%3A returns HTTP 400 JSON with error.code invalid_url.
- /api/v1/pulse/status/pulse_job_nonexistent_test returns HTTP 404 JSON with error.code not_found.
- HTTP 202 pending responses include Retry-After when a polling delay is recommended.
- HTTP 429 throttled responses include Retry-After when retry timing is known.
- Pulse uses freshness=latest and freshness=refresh. There is no refresh=true parameter.
- Pulse reuses an eligible completed scan from the prior 24 hours before queueing a new scan. Time comparisons use UTC instants.
- Use forceNewScan=true only when you need to bypass the 24-hour reuse check. It does not bypass validation or the 5-minute normalized-domain scan-generation throttle.
- New Pulse scan generation is throttled to one submitted scan job per normalized domain every 5 minutes. A throttled request returns HTTP 429, Retry-After when known, and support guidance at support@certscore.ai.
- X-RateLimit-* headers are not emitted unless a route has accurate enforced bucket state.

Use guidance:
- Use detail=tiny for compact badges, CLI summaries, or simple agents.
- Use detail=standard for default agent summaries.
- Use detail=full when structured finding, evidence, review lens, coverage, and benchmark context are needed.
- Use format=markdown when a tool handles readable text better than JSON.
- For a Custom GPT Action beta, import https://certscore.ai/api/v1/openapi.chatgpt.json and use getPulseForUrl with format=markdown, detail=standard, wait=35.
- Treat the response as automated public-web observations for review.
- Do not treat absence of findings as proof of compliance.
- Review the linked evidence and consult qualified experts where appropriate.

Support:
support@certscore.ai