Agents and API
API reference
Endpoints, authentication, events and errors.
Everything on the website is also available as a JSON API at https://scan.hoopgram.com.
Authentication
Create a key under API keys and send it as a bearer token. Keys start with ws_. You can have up to 10 and revoke any of them.
Authorization: Bearer $WEBSECURE_API_KEY
Start a scan
curl -s https://scan.hoopgram.com/api/scans \
-H "Authorization: Bearer $WEBSECURE_API_KEY" -H "Content-Type: application/json" \
-d '{"url":"https://example.com"}'
Add "deep": true for a deep scan of a verified domain. The response has the scan id, status and charge (reserved, or free for a rescan).
Wait and fetch the report
curl -s https://scan.hoopgram.com/api/scans/$ID -H "Authorization: Bearer $WEBSECURE_API_KEY" curl -s https://scan.hoopgram.com/api/scans/$ID/report.md -H "Authorization: Bearer $WEBSECURE_API_KEY"
Poll every few seconds until status is done or failed, or listen to the events stream. A finished scan includes summary (counts by severity), result (all checks and findings) and, for a rescan, comparison.
Endpoints
| Endpoint | What it does |
|---|---|
| POST /api/scans {url, deep?} | Start a scan. Free. Works without a key for a passive scan; deep scans need a key and a verified domain. |
| GET /api/scans | Your last 100 scans. |
| GET /api/scans/:id | Status, summary, full result and rescan comparison. |
| GET /api/scans/:id/events | Live progress as server-sent events: status, plan, phase, check, finding, req, log, end. |
| GET /api/scans/:id/report.md | The report in Markdown. Add ?download=1 to save it as a file. |
| GET /api/scans/:id/proof.json | The signed record of the scan. See Proof of what we checked. |
| POST /api/deps/check {lockfile | packages} | Free. Checks a project's installed npm packages (the text of package-lock.json, or a list of {name, version}) against OSV.dev and CISA's exploited list. Returns a verdict and, per vulnerable package, the advisories and the version to upgrade to. Up to 30 checks an hour. |
| GET /.well-known/websecure-signing-key.pem | The public key that signs scan proofs. |
| POST /api/scans/:id/rescan | Scan the same URL again. |
| GET /api/me | Your email, plan prices and protected sites. |
| GET /api/domains | Your domains with their verification status and instructions. |
| POST /api/domains {host} | Get a verification token and instructions. |
| POST /api/domains/:host/check | Check the DNS record or file now. |
| GET /api/protect | Your Protect sites: status, renewal date, latest verdict and next check. Signed-in browser only; start and manage Protect in the console. |
| GET /api/billing | What you pay for Protect and every payment (Protect months and older credit purchases), with receipt links and refund status. |
| GET /api/invoices/:id/receipt.pdf | The PDF receipt for a Protect payment. |
| GET /api/payments | Scan credit purchases made before scans became free, with receipt numbers. |
| GET /api/payments/:id/receipt.pdf | The PDF receipt for a payment. |
Errors
Errors are JSON with an HTTP status: {"error": "code", "message": "…"}.
| Code | Meaning |
|---|---|
| sign_in_required | Deep scans need an account (API key or signed-in browser). |
| not_verified | Deep scan on an unverified domain. Includes verify_url. |
| private_target | The address is private or internal. |
| bad_url | The URL could not be understood. |
| busy | You already have a scan running. One at a time per account. |
| rate_limited | Too many scans. Up to 20 an hour per account. See Retry-After. |
| intel_unavailable | The advisory database could not be reached. Try the package check again in a minute. |
| unauthorized | Missing, wrong or revoked API key. |
For AI agents
A plain-text index of these docs is at /llms.txt, and the agent skill is at /skill/SKILL.md.