Skip to content
REST API

API Documentation

The WebSentry API lets you scan URLs, retrieve results, manage API keys, and configure monitoring, all programmatically.

Base URL

https://websentry.dev

Official SDK

The official JavaScript/TypeScript client, zero dependencies, works in Node 18+, browsers, and edge runtimes. Fully typed, with rate-limit state and typed errors built in. Source of truth for every endpoint on this page.

bash
npm install websentry-api
typescript
import WebSentry from 'websentry-api';

const ws = new WebSentry('ss_your_api_key');

// Scan, synchronous, returns grade + score directly
const result = await ws.scan('example.com');
console.log(result.grade, result.score);

// Full results, all 15 categories (Pro+)
const report = await ws.getScan(result.scanId);

// Monitors
const monitor = await ws.monitors.create('example.com', 'daily');
await ws.monitors.toggle(monitor.id);

// Rate-limit awareness
console.log(ws.lastRateLimit);   // { limit, remaining } when limited
console.log(ws.apiVersion);      // "2026-10"

Package: npmjs.com/package/websentry-api

Authentication

Authenticate with an API key in the X-API-Key header (or as Authorization: Bearer). Keys start with ss_ and are created in the dashboard under API Keys. API access requires a Pro or Agency plan.

Without a key, requests are rate-limited by IP to 3 scans per week, the same allowance as the website's anonymous scanner.

http
POST /api/scan HTTP/1.1
Host: websentry.dev
Content-Type: application/json
X-API-Key: ss_your_api_key_here

{ "url": "https://example.com" }
PlanAPI accessScansMonitorsPDF + JSON export
No key (IP)Limited3 / week0No
FreeNo (web only)20 / month0No
ProYesUnlimited5Yes
Agency StarterYesUnlimited25Yes
Agency GrowthYesUnlimited75Yes
Agency ProYesUnlimited200Yes

Scanning

API Keys

Monitors

Monitors re-scan a URL on a schedule and alert you when the grade drops or recovers, by email, Slack, or webhook (configure integrations in the dashboard). Available on Pro and Agency plans.

Reference

Grading scale

GradeScore range
A+90 – 100
A80 – 89
B70 – 79
C60 – 69
D50 – 59
F0 – 49

Check statuses

StatusMeaning
passCheck passed, full points awarded
warnPartial pass or advisory issue
failCheck failed, no points
infoInformational, no score impact

Response headers

Every API response carries X-API-Version. Rate-limited callers (anonymous and free accounts) also get X-RateLimit-* headers on /api/scan; paid plans are unlimited, so none are sent.

HeaderMeaning
X-API-VersionAPI version (date-based, e.g. 2026-10). Changes only on breaking changes.
X-RateLimit-LimitScans allowed in the current window (3/week anonymous, 20/month free)
X-RateLimit-RemainingScans left in the window after this request
X-RateLimit-ResetUnix timestamp when the oldest scan leaves the rolling window (sent on 429)

Common error codes

CodeMeaning
400Invalid or missing URL / request body
401Missing or invalid API key or session
403Feature requires a Pro or Agency plan
404Scan, key, or monitor not found
409Duplicate (e.g. monitor already exists for that URL)
429Rate or plan limit exceeded
500Internal scan error

Ready to integrate?

Get your API key from the dashboard, free plan included.