API Documentation

Updated Apr 4, 2026

API Documentation

The TrustedWeb REST API lets you run scans, read the threat feed, and (on the Agency plan) pull your own sites' data programmatically.

/api/my-sites requires an Agency-plan API key. Generate one from the API access page in your dashboard. The scan/reviews/threats endpoints below are public and need no key.

Base URL

https://trustedweb.site/api/

Rate limits

Public endpoints (scan, reviews, threats, widget-data): 10 requests / 5 minutes per IP on /api/scan; generous limits elsewhere.
Agent registration: 5 / 10 minutes per IP.
Exceeding a limit returns 429 Too Many Requests with a Retry-After header.

Public Endpoints (No Auth Required)

POST /api/scan

Run a full scan (32 checks across security, SEO, trust, conversion, cookie compliance) on any public URL.

POST https://trustedweb.site/api/scan
Body: { "url": "https://example.com", "email": "[email protected]" }

Response:
{
  "ok": true,
  "scan_id": 42,
  "url": "https://example.com/",
  "score": 74,
  "grade": "B",
  "categories": { "security": 80, "seo": 70, "trust": 60, "conversion": 75, "cookie": 90 },
  "checks": [ { "category": "security", "key": "https", "label": "Served over HTTPS", "ok": true, "weight": 25 }, ... ]
}

GET /api/threats

Live WordPress plugin vulnerability feed.

GET https://trustedweb.site/api/threats?limit=10

Response:
{ "ok": true, "count": 10, "totals": { "critical": 18, "high": 60, "medium": 150, "low": 2 }, "threats": [ ... ] }

GET /api/reviews & POST /api/reviews

Read approved public reviews, or submit a new one (goes into a moderation queue).

GET /api/widget-data?site=example.com

Public trust status lookup for any registered domain — powers the embeddable widget.js badges.

Agency API Key (Required for /api/my-sites)

Generate your key from the API access page in your dashboard (Agency plan). Send it in the X-TW-Token header.

GET /api/my-sites

GET https://trustedweb.site/api/my-sites
Headers: X-TW-Token: twk_...

Response:
{ "ok": true, "sites": [
  { "root_domain": "example.com", "client_name": "Acme Inc", "score": 82, "badge": "verified", "agent_connected": true, "last_scan": "2026-07-19 04:00:00" }
] }

Agent Endpoints (Site Credentials Required)

Used by the TrustedWeb Agent WordPress plugin — you won't call these directly unless you're building an integration.

POST /api/agent/register

POST /api/agent/register
Body: { "site_url": "https://example.com", "wp_version": "6.5", "php_version": "8.2", "agent_version": "1.3.0" }

Response: { "ok": true, "site_id": "tw_...", "token": "...", "badge": "scanned" }

POST /api/agent/check-in

Headers: X-Site-Id, X-Agent-Token. Reports a scan result from the agent.

POST /api/agent/fix-report

Reports which auto-fixes the agent applied on the site.

GET /api/agent/status

Agent polls this hourly to receive queued commands (scan_now, apply_fixes, refresh_badge).

Error Responses

401 Unauthorized — invalid or missing token/key
404 Not Found — unknown action or resource
429 Too Many Requests — rate limit exceeded (includes Retry-After header)
400 Bad Request — missing required parameters

Support

Email: [email protected]