API documentation

Authentication

Send your API key as a bearer token or in the X-API-Key header:

curl https://vulny.app/api/v1/targets \
  -H "Authorization: Bearer vlny_your_key"

Rate limits

120 requests per minute per key. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. Exceeding the limit returns 429 with a Retry-After header.

Start a scan

POST /api/v1/scans — start an on-demand scan on a target (added to your account if new). Returns a scan id to poll.

curl -X POST https://vulny.app/api/v1/scans \
  -H "Authorization: Bearer vlny_your_key" \
  -H "Content-Type: application/json" \
  -d '{"target":"example.com"}'

# → { "id": "...", "target": "example.com", "status": "queued" }

Scan status & results

GET /api/v1/scans/{id} — poll until done is true. Returns a severity summary and the list of findings — use them to pass or fail a CI pipeline.

curl https://vulny.app/api/v1/scans/SCAN_ID \
  -H "Authorization: Bearer vlny_your_key"

# → { "status": "finished", "done": true, "progress": 100,
#     "summary": { "critical": 1, "high": 2, "medium": 0, "low": 3, "total": 6 },
#     "findings": [ { "severity": "critical", "title": "CVE-2024-...", "cvss_score": 9.8, "port": "443/tcp" } ] }

See DevSecOps pipeline for full GitLab CI and GitHub Actions examples that wait for the scan and fail the build on critical findings.

Add targets (bulk, up to 1000)

POST /api/v1/targets/bulk — accepts domains or IPs, optionally with tags. Respects your plan’s target limit.

curl -X POST https://vulny.app/api/v1/targets/bulk \
  -H "Authorization: Bearer vlny_your_key" \
  -H "Content-Type: application/json" \
  -d '{"targets":["example.com","203.0.113.10",{"value":"api.example.com","tags":["prod"]}]}'

Delete targets (bulk)

DELETE /api/v1/targets/bulk — by IDs or by values (IPs / hostnames).

curl -X DELETE https://vulny.app/api/v1/targets/bulk \
  -H "Authorization: Bearer vlny_your_key" \
  -H "Content-Type: application/json" \
  -d '{"values":["example.com","203.0.113.10"]}'

Update tags (bulk)

PATCH /api/v1/targets/tags — set, add or remove tags on many targets at once (mode: set | add | remove).

curl -X PATCH https://vulny.app/api/v1/targets/tags \
  -H "Authorization: Bearer vlny_your_key" \
  -H "Content-Type: application/json" \
  -d '{"values":["example.com"],"tags":["pci","prod"],"mode":"add"}'

OpenAPI spec

The full machine-readable specification is available at /api/v1/openapi.json — import it into Postman, Insomnia or your code generator.