HTTP API

HTTP API

The API is versioned as v1. Start it with:

hooray serve

The server is HTTP only. Terminate TLS in a trusted reverse proxy. Non-loopback binds require bearer authentication; see Configuration.

Routes

Health:

• GET /health
• GET /ready

Scanning and reports:

• POST /v1/scans
• GET /v1/runs
• GET /v1/runs/{run_id}
• GET /v1/runs/{run_id}/diff/{baseline_run_id}
• GET /v1/runs/{run_id}/findings
• GET /v1/runs/{run_id}/inventory
• GET /v1/findings
• GET /v1/inventory
• GET /v1/reports/{run_id}

Policy and exceptions:

• POST /v1/policies/validate
• POST /v1/policies/evaluate
• POST /v1/exceptions/validate

Operational contract

• Request bodies are bounded by max_request_bytes.
• Scan concurrency is bounded by max_concurrency.
• Read requests use a 30-second request timeout.
• Scan writes report success only after the blocking SQLite commit outcome is known; they do not return a timeout while a detached write can later commit.
• Pagination and filters are validated; unknown query fields are rejected.
• Errors have a stable versioned envelope and include a request ID.
• CORS defaults are conservative.

Content negotiation

The report endpoint supports canonical JSON and YAML response forms. Other report formats are generated with the CLI report command or scanning output options. See Reports and Integrations.

Redaction

Run, report, finding, inventory, and metadata responses pass through the same recursive sensitive-value sanitizer used by report rendering. Keys such as tokens, credentials, and authorization data are redacted, including nested values.

Example

curl -sS \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"kind":"project","path":"."}}' \
  http://127.0.0.1:8080/v1/scans

Request structures are strict; consult CLI behavior for the same input, policy, baseline, offline, and format concepts.