API Documentation

Integrate security scanning into your workflow. Requires a Pro or Agency plan.

Authentication

All API requests require an API key. Create one from your dashboard. Include it in the Authorization header.

Authorization: ss_your_api_key_here

Base URL

https://websentry.dev

Rate limits

Plan	Limit
Free (no key)	3 scans/day by IP
Free (with account)	3 scans/month
Pro	Unlimited
Agency	Unlimited

POST /api/scan Run a security scan

Run a security scan on a URL. Returns the scan ID, grade, and score. The full report is available via the GET endpoint.

Request body

{
  "url": "example.com"
}

Field	Type	Required	Description
url	string	Yes	Domain or full URL to scan. Protocol is optional.

Response

{
  "ok": true,
  "scanId": "e926f8e2d15bf967ea36e5481a888289",
  "url": "example.com",
  "grade": "B",
  "score": 76
}

Example (cURL)

curl -X POST https://websentry.dev/api/scan \
  -H "Content-Type: application/json" \
  -H "Authorization: ss_your_api_key" \
  -d '{"url": "example.com"}'

GET /api/scan/:scanId/json Get full scan results

Retrieve the full scan results including all category scores and individual checks.

Path parameters

Parameter	Description
scanId	The ID returned by POST /api/scan

Response

{
  "ok": true,
  "scan": {
    "id": "e926f8e2d15bf967ea36e5481a888289",
    "url": "example.com",
    "grade": "B",
    "score": 76,
    "results": {
      "url": "example.com",
      "scannedAt": "2026-02-14T12:00:00.000Z",
      "durationMs": 2340,
      "grade": "B",
      "score": 76,
      "categories": {
        "ssl": {
          "name": "SSL / TLS",
          "score": 25,
          "maxScore": 30,
          "grade": "A",
          "checks": [
            {
              "name": "HTTPS Available",
              "status": "pass",
              "value": "Yes",
              "description": "Site is accessible over HTTPS."
            }
          ]
        },
        "headers": { "..." : "..." },
        "cookies": { "..." : "..." },
        "redirects": { "..." : "..." },
        "dns": { "..." : "..." },
        "server": { "..." : "..." }
      }
    },
    "created_at": "2026-02-14T12:00:00"
  }
}

Example (cURL)

curl https://websentry.dev/api/scan/SCAN_ID/json \
  -H "Authorization: ss_your_api_key"

POST /api/keys Create an API key

Create a new API key. Requires authentication via session cookie (logged-in dashboard). The full key is returned only once.

Request body

{
  "name": "My CI Pipeline"
}

Response

{
  "ok": true,
  "key": "ss_a1b2c3d4e5f6...",
  "id": "abc123",
  "name": "My CI Pipeline"
}

DELETE /api/keys/:keyId Delete an API key

Revoke an API key. Requires authentication via session cookie.

Response

{
  "ok": true
}

Monitors

Automated scheduled scans. Requires Pro (5 monitors) or Agency (25 monitors) plan.

GET /api/monitors List all monitors

List all monitors for the authenticated user. Requires session cookie.

Response

{
  "ok": true,
  "monitors": [
    {
      "id": "abc123",
      "url": "https://example.com",
      "frequency": "weekly",
      "last_grade": "A",
      "last_scan_id": "scan_xyz",
      "is_active": 1,
      "created_at": "2026-02-14T12:00:00"
    }
  ]
}

POST /api/monitors Create a monitor

Add a site to monitor. Runs an initial scan immediately and schedules future scans at the chosen frequency. Requires session cookie.

Request body

{
  "url": "https://example.com",
  "frequency": "weekly"
}

Field	Type	Required	Description
url	string	Yes	Full URL of the site to monitor
frequency	string	Yes	`daily`, `weekly`, or `monthly`

Response

{
  "ok": true,
  "monitor": {
    "id": "abc123",
    "url": "https://example.com",
    "frequency": "weekly",
    "last_grade": "A",
    "is_active": 1
  }
}

PATCH /api/monitors/:monitorId/toggle Pause or resume

Pause or resume a monitor. Toggling paused monitors stops scheduled scans until resumed. Requires session cookie.

Response

{
  "ok": true,
  "is_active": 0
}

DELETE /api/monitors/:monitorId Remove a monitor

Remove a monitor. Previous scan reports are kept. Requires session cookie.

Response

{
  "ok": true
}

Scheduled scan timing

Monitors are checked automatically via a cron trigger at 06:00 UTC daily.

Frequency	Runs
Daily	Every day at 6 AM UTC
Weekly	Every Monday at 6 AM UTC
Monthly	1st of each month at 6 AM UTC

Security categories

Each scan evaluates 6 security categories. The overall score is a weighted percentage of all category scores combined (max 100 points).

Category	Key	Max Score	Checks
SSL / TLS	ssl	30	HTTPS, TLS version, certificate, HSTS
Security Headers	headers	25	CSP, X-Frame-Options, XCTO, Referrer-Policy, Permissions-Policy
Cookie Security	cookies	15	Secure, HttpOnly, SameSite flags
Redirects	redirects	10	HTTP to HTTPS, chains, WWW normalization
DNS & Email Auth	dns	10	SPF, DMARC, DKIM
Server & Info Leakage	server	10	Server header, X-Powered-By, sensitive paths

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

Each individual check returns one of these statuses:

Status	Meaning
pass	Security best practice is properly implemented
warn	Partially implemented or could be improved
fail	Missing or misconfigured, action recommended
info	Informational, does not affect the score

Error responses

All errors return a JSON body with ok: false and an error message.

{
  "ok": false,
  "error": "Rate limit exceeded. Create a free account for more scans."
}

Status	Meaning
400	Bad request (missing or invalid URL)
401	Unauthorized (invalid or missing API key)
403	Forbidden (feature not available on your plan)
404	Scan or resource not found
429	Rate limit exceeded
500	Internal server error

Need help integrating?

We can help you set up CI/CD security scanning, custom integrations, or automated reporting.