API Documentation

Updated Apr 4, 2026

API Documentation

The TrustedWeb REST API allows you to integrate security scanning, badge verification, and site management into your own applications.

API access requires a Developer ($99/mo) or Agency ($199/mo) plan. Basic and Advanced plans can use the dashboard and agent plugin but do not have direct API access.

Base URL

https://trustedweb.site/wp-json/trustedweb/v1/

Authentication

All API requests require your API key in the request header:

X-TW-Token: your-api-token-here
X-TW-Site-ID: your-site-id-here

Get your API key from the API Keys page in your dashboard.

Rate Limits

REST API: 30 requests/second
Exceeding limits returns 429 Too Many Requests with a Retry-After header
Response includes failover node URLs for high-availability setups

Public Endpoints (No Auth Required)

GET /nodes

Returns the list of available API nodes for failover/load balancing.

GET https://trustedweb.site/wp-json/trustedweb/v1/nodes

Response:
{
  "nodes": [
    "https://trustedweb.site/wp-json",
    "https://1.trustedweb.site/wp-json",
    "https://2.trustedweb.site/wp-json",
    "https://3.trustedweb.site/wp-json",
    "https://4.trustedweb.site/wp-json"
  ]
}

GET /health (on node subdomains)

GET https://1.trustedweb.site/health

Response:
{"ok": true, "node": "1", "service": "trustedweb"}

Agent Endpoints (Token Required)

POST /agent/register

POST /agent/register
Body: {
  "site_id": "twa_abc123...",
  "token": "random-64-char-token",
  "site_url": "https://example.com",
  "rest_url": "https://example.com/wp-json/trustedweb-agent/v1/",
  "site_info": { "wp_version": "6.5", "php_version": "8.2", ... },
  "agent": "1.0.0"
}

Response:
{
  "success": true,
  "server_id": 42,
  "badge": "scanned",
  "message": "Agent registered successfully."
}

POST /agent/report

Submit scan data from the agent. Server analyzes the data and returns results + badge level.

POST /agent/report
Headers: X-TW-Token, X-TW-Site-ID
Body: {
  "scan_data": {
    "files": { "php_files": [...], "uploads_php": [...], "permissions": [...] },
    "database": { "tables": [...], "admins": [...], "options": [...], "cron": [...] }
  },
  "site_info": { ... },
  "timestamp": "2026-04-04 12:00:00"
}

Response:
{
  "success": true,
  "analysis": {
    "threats": [...],
    "warnings": [...],
    "score": 85,
    "grade": "A"
  },
  "badge": "verified",
  "commands": []
}

GET /agent/badge

Get the current badge level for a site.

GET /agent/badge?site_id=twa_abc123
Headers: X-TW-Token, X-TW-Site-ID

Response:
{
  "badge": "verified",
  "embed": "https://trustedweb.site/badge/verified/example.com"
}

GET /agent/signatures

Get malware signatures for deep scanning. Returns patterns based on your plan tier.

GET /agent/signatures
Headers: X-TW-Token, X-TW-Site-ID

Response:
{
  "signatures": [
    {"id": "eval_base64", "name": "eval(base64_decode())", "pattern": "...", "severity": "critical", "type": "malware"},
    ...
  ],
  "version": "2026.04.01",
  "count": 33
}

GET /agent/fix-rules

Get available auto-fix rules for your plan.

GET /agent/fix-rules

Response:
{
  "rules": [
    {"id": "disable_xmlrpc", "name": "Disable XML-RPC", "auto": true, "description": "..."},
    ...
  ],
  "plan": "advanced"
}

WooCommerce Deep Scan Endpoints

Requires Advanced plan or WooCommerce Deep Scan add-on ($5/site/mo).

POST /agent/wc-report

Submit WooCommerce-specific scan data for analysis.

POST /agent/wc-report
Body: {
  "wc_data": {
    "wc_active": true,
    "wc_version": "8.8.0",
    "payment_gateways": [...],
    "checkout_js": [...],
    "wc_uploads_php": [...],
    "db_suspicious": [...],
    "wc_plugins": [...]
  },
  "site_info": { ... }
}

Response:
{
  "success": true,
  "analysis": {
    "wc_threats": [...],
    "wc_warnings": [...],
    "wc_score": 92
  },
  "fixes": [...]
}

GET /agent/wc-signatures

Get WooCommerce-specific malware signatures.

GET /agent/wc-signatures

Response:
{
  "signatures": [...],
  "vuln_plugins": {
    "woocommerce-payments": [{"below": "6.9.2", "severity": "critical", "cve": "CVE-2023-28121"}],
    ...
  },
  "version": "2026.04.01"
}

[twd_api_advanced_docs]

Error Responses

401 Unauthorized — Invalid or missing API token
403 Forbidden — Plan does not include this feature
429 Too Many Requests — Rate limit exceeded (includes Retry-After header + failover nodes)
400 Bad Request — Missing required parameters

SDKs and Integration

Official SDKs are planned for future releases. For now, use any HTTP client to call the REST API.

Support

API support is available for Developer and Agency plans.
Email: [email protected]