API Reference

All endpoints are under /api/v1 and require the Authorization: Bearer header described in Authentication.

Endpoints

Method	Path	Description
GET	`/api/v1/scans`	List your org's scan history.
POST	`/api/v1/scans`	Start an audit. Body: `{ url, depth? }`
GET	`/api/v1/scans/:id`	Status, findings count, severity breakdown.
GET	`/api/v1/scans/:id/findings`	Verified findings for a completed scan.
GET	`/api/v1/scans/:id/report`	The full HTML report.
GET	`/api/v1/scans/:id/gate`	Pass/fail against a severity threshold — see CI/CD.

Start an audit

curl -X POST https://your-notra-domain/api/v1/scans \
  -H "Authorization: Bearer notra_live_..." \
  -H "content-type: application/json" \
  -d '{"url": "example.com", "depth": "standard"}'

# 201 { "runId": "...", "host": "example.com" }

depth is standard (default) or deep — deep adds authenticated and chained-exploit checks, and needs a Deep entitlement. Same authorization gate as every other scan: the domain must already be verified for your org, or the request gets a 403 with needsOwnership: true.

Check status and pull results

curl https://your-notra-domain/api/v1/scans/RUN_ID \
  -H "Authorization: Bearer notra_live_..."

curl https://your-notra-domain/api/v1/scans/RUN_ID/findings \
  -H "Authorization: Bearer notra_live_..."

List recent scans

curl https://your-notra-domain/api/v1/scans \
  -H "Authorization: Bearer notra_live_..."

Errors

Status	Meaning
400	Malformed request — bad URL, invalid `depth`, invalid query param.
401	Missing, invalid, or revoked API key.
402	Out of scan credit — response includes `checkoutHint`.
403	Plan doesn't include API access, or the domain isn't authorized (`needsOwnership: true`).
404	Scan doesn't exist, or belongs to another org.
429	Rate limit — response includes `retry-after`.

See Errors for the full picture across every endpoint.