POST AI agent ready /v1/security/grade

Security Headers Grade API - A-F Rating for Any URL

Fetches the target URL and evaluates 6 security headers: Strict-Transport-Security (25pts), Content-Security-Policy (25pts), X-Content-Type-Options (15pts), X-Frame-Options (10pts), Referrer-Policy (15pts), and Permissions-Policy (10pts). Returns an overall score out of 100, letter grade, per-header breakdown, and recommendations for missing headers.

Endpoint

Code examples

curl -X POST https://api.botoi.com/v1/security/grade \
  -H "Content-Type: application/json" \
  -d '{"url":"https://stripe.com"}'

When to use this API

CI/CD security gates

Add a security header check to your deployment pipeline. Fail the build if the grade drops below B, preventing configuration regressions from reaching production.

Security posture dashboards

Batch-grade all your company's domains and track scores over time. Surface domains with missing HSTS or CSP headers for the security team to prioritize.

Client security audits

Include security header grades in client deliverables. Grade the client's domain before and after your recommendations to show measurable improvement.

Frequently asked questions

What headers does the grading check?

Six headers: Strict-Transport-Security (HSTS), Content-Security-Policy (CSP), X-Content-Type-Options, X-Frame-Options, Referrer-Policy, and Permissions-Policy. Each has a weighted point value based on security impact.

How is the letter grade calculated?

Points are summed from all 6 headers (max 100). A+ = 95+, A = 85+, B = 70+, C = 55+, D = 40+, F = below 40. HSTS gets bonus points for includeSubDomains and preload directives.

Does this check the actual TLS certificate?

No. This endpoint grades HTTP response headers only. For TLS certificate inspection, use the /v1/ssl-cert/certificate endpoint.

Can I grade URLs behind authentication?

The endpoint fetches the URL as a public visitor with no cookies or auth tokens. If the URL requires login, the grade reflects the login page's headers, not the authenticated content.

Why does my site score 0 on Content-Security-Policy?

The endpoint checks for the presence of the CSP header. If your server doesn't send it, the score is 0 for that category. Many sites omit CSP because it requires careful configuration to avoid breaking scripts and styles.

Get your API key

Free tier includes 5 requests per minute with no credit card required. Upgrade for higher limits.