REST API
Run scans from a deployment pipeline, a scheduler or your own dashboard. Every scan follows the same rules as in the browser: verified domains only, one credit per scan.
Authentication
Create a key on your account page and send it in the Authorization header. A key acts as your account on the /api/ endpoints only; revoke it there at any time.
curl https://domain-security-scanner.64.226.71.191.sslip.io/api/me \ -H "Authorization: Bearer dss_your_key"
Start a scan
The target is a domain verified on your account, or any of its subdomains. The answer arrives at once with the scan id; the scan takes about a minute.
curl -X POST https://domain-security-scanner.64.226.71.191.sslip.io/api/scans \
-H "Authorization: Bearer dss_your_key" \
-H "Content-Type: application/json" \
-d '{"target": "www.example.com"}'{"scan_id": "3f1c…", "target": "www.example.com", "status": "queued", "tier": "full"}Read the result
Poll the scan until status is completed (or failed, which refunds the credit). The completed report holds the score, the grade, the category scores, the action plan and every finding with its evidence.
curl https://domain-security-scanner.64.226.71.191.sslip.io/api/scans/SCAN_ID \ -H "Authorization: Bearer dss_your_key"
{
"status": "completed",
"assessment": {"score": 78, "grade": "C", "counts": {"high": 1, "medium": 3, …}, …},
"findings": [{"severity": "high", "title": "…", "evidence": "…", "recommendation": "…"}, …]
}curl -o report.pdf https://domain-security-scanner.64.226.71.191.sslip.io/api/scans/SCAN_ID/report.pdf \ -H "Authorization: Bearer dss_your_key"
All endpoints
| Method and path | What it does |
|---|---|
GET /api/me | Account e-mail and credit balance. |
GET /api/domains | Your domains with their verification state and the DNS record or file that verifies them. |
POST /api/domains | Add a domain: {"hostname": "example.com"}. |
POST /api/domains/{id}/verify | Check the DNS record or file and mark the domain verified. |
POST /api/scans | Start a scan: {"target": "example.com"}. Uses one credit. |
GET /api/scans | Your recent scans. |
GET /api/scans/{id} | Status, score and findings of a scan. |
GET /api/scans/{id}/report.pdf | The completed report as a PDF document. |
POST /api/scans/{id}/unlock | Turn a limited report into the full one. Uses one paid credit. |
GET /api/alerts | Open monitoring alerts for your domains. |
Machine-readable description: /api/openapi.json (OpenAPI 3).
Errors
Errors answer with a JSON body {"detail": "…"} that says what to do.
| Status | Meaning |
|---|---|
| 401 | Missing, revoked or wrong API key. |
| 402 | No credit left for the scan or the unlock. |
| 403 | The target is not covered by a verified domain, or the e-mail address is not confirmed yet. |
| 404 | The scan or domain does not exist on your account. |
| 409 | The domain could not be verified, or the report is not complete yet. |
| 422 | The target resolves to a private or reserved network address. |
| 429 | Another scan of yours is running, or a rate limit was reached. |