API Documentation
The WebSentry API lets you scan URLs, retrieve results, manage API keys, and configure monitoring, all programmatically.
Base URL
https://websentry.devOfficial 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.
npm install websentry-apiimport 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.
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" }| Plan | API access | Scans | Monitors | PDF + JSON export |
|---|---|---|---|---|
| No key (IP) | Limited | 3 / week | 0 | No |
| Free | No (web only) | 20 / month | 0 | No |
| Pro | Yes | Unlimited | 5 | Yes |
| Agency Starter | Yes | Unlimited | 25 | Yes |
| Agency Growth | Yes | Unlimited | 75 | Yes |
| Agency Pro | Yes | Unlimited | 200 | Yes |
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
| Grade | Score range |
|---|---|
| A+ | 90 – 100 |
| A | 80 – 89 |
| B | 70 – 79 |
| C | 60 – 69 |
| D | 50 – 59 |
| F | 0 – 49 |
Check statuses
| Status | Meaning |
|---|---|
| pass | Check passed, full points awarded |
| warn | Partial pass or advisory issue |
| fail | Check failed, no points |
| info | Informational, 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.
| Header | Meaning |
|---|---|
| X-API-Version | API version (date-based, e.g. 2026-10). Changes only on breaking changes. |
| X-RateLimit-Limit | Scans allowed in the current window (3/week anonymous, 20/month free) |
| X-RateLimit-Remaining | Scans left in the window after this request |
| X-RateLimit-Reset | Unix timestamp when the oldest scan leaves the rolling window (sent on 429) |
Common error codes
| Code | Meaning |
|---|---|
| 400 | Invalid or missing URL / request body |
| 401 | Missing or invalid API key or session |
| 403 | Feature requires a Pro or Agency plan |
| 404 | Scan, key, or monitor not found |
| 409 | Duplicate (e.g. monitor already exists for that URL) |
| 429 | Rate or plan limit exceeded |
| 500 | Internal scan error |
Ready to integrate?
Get your API key from the dashboard, free plan included.