Security Headers API — /api/v1/security/headers

Issues a HEAD/GET request to the apex URL and returns the full header set plus pass/fail grading on key security headers (CSP, HSTS, X-Frame-Options, etc.).

• Method GET
• Path /api/v1/security/headers
• Stability STABLE
• Version v2026-05-15
• Summary Fetch and grade the HTTP response headers for a domain.

Pass these as query-string parameters (or, where indicated, in the request headers). Required params marked required.

• domain (required) — string Hostname.
• raw — boolean, default false Include full upstream response body summary.

All successful responses follow the standard `{ success: true, data: {...} }` envelope. Notable fields on the data object for this endpoint:

• data.success — boolean Whether the upstream returned a 2xx/3xx.
• data.status — integer Upstream HTTP status code.
• data.headers — object Header name → value map (lowercased keys).

Truncated but representative example for a real lookup:

{
  "success": true,
  "data": {
    "success": true,
    "status": 200,
    "headers": {
      "content-type": "text/html; charset=UTF-8",
      "x-xss-protection": "0",
      "x-frame-options": "SAMEORIGIN",
      "content-security-policy-report-only": "object-src 'none'; base-uri 'self'..."
    }
  }
}

Errors return HTTP status codes paired with stable machine-readable codes. Match on the code field rather than the human-readable message.

• 504 UPSTREAM_TIMEOUT Upstream took longer than 15s.
• 502 UPSTREAM_ERROR Upstream returned a non-2xx/3xx response.

Patterns we recommend when integrating this endpoint:

• Audit every public-facing domain monthly. Drift is silent.
• Pair with `/security/ssl-info` for a complete TLS-layer audit.
• Check `set-cookie` flags (`HttpOnly`, `Secure`, `SameSite`) in the response.

• Why no overall grade? Grades depend on threat model. Render the headers, score in your own UI.