WebSecure
Agents and API · API reference

Get started

Scanning

Agents and API

Account

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

EndpointWhat 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/scansYour last 100 scans.
GET /api/scans/:idStatus, summary, full result and rescan comparison.
GET /api/scans/:id/eventsLive progress as server-sent events: status, plan, phase, check, finding, req, log, end.
GET /api/scans/:id/report.mdThe report in Markdown. Add ?download=1 to save it as a file.
GET /api/scans/:id/proof.jsonThe 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.pemThe public key that signs scan proofs.
POST /api/scans/:id/rescanScan the same URL again.
GET /api/meYour email, plan prices and protected sites.
GET /api/domainsYour domains with their verification status and instructions.
POST /api/domains {host}Get a verification token and instructions.
POST /api/domains/:host/checkCheck the DNS record or file now.
GET /api/protectYour Protect sites: status, renewal date, latest verdict and next check. Signed-in browser only; start and manage Protect in the console.
GET /api/billingWhat you pay for Protect and every payment (Protect months and older credit purchases), with receipt links and refund status.
GET /api/invoices/:id/receipt.pdfThe PDF receipt for a Protect payment.
GET /api/paymentsScan credit purchases made before scans became free, with receipt numbers.
GET /api/payments/:id/receipt.pdfThe PDF receipt for a payment.

Errors

Errors are JSON with an HTTP status: {"error": "code", "message": "…"}.

CodeMeaning
sign_in_requiredDeep scans need an account (API key or signed-in browser).
not_verifiedDeep scan on an unverified domain. Includes verify_url.
private_targetThe address is private or internal.
bad_urlThe URL could not be understood.
busyYou already have a scan running. One at a time per account.
rate_limitedToo many scans. Up to 20 an hour per account. See Retry-After.
intel_unavailableThe advisory database could not be reached. Try the package check again in a minute.
unauthorizedMissing, 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.