Public API

Endpoint

https://httpsornot.com/api/v1/check?domain=<domain>

Replace <domain> with the hostname (e.g. example.com). Scheme and path are stripped.

CI policy (fail the PR)

Optional query params. When any are set and the check fails the policy, the API returns HTTP 422 with the full JSON plus policyFailures — so curl -f exits non-zero in GitHub Actions.

• minGrade — composite sslGrade.grade (A+, A, A-, B+, B, C, F)
• headersMinGrade — headers-only securityHeaders.grade (A+, A, B, C, D, F)
• requireHsts=true — require HSTS enabled

Bot protection while a policy is requested also returns 422 (fail closed) — we do not invent a grade. Details: accuracy pledge.

curl -fsS "https://httpsornot.com/api/v1/check?domain=example.com&headersMinGrade=B&requireHsts=true"

SecurityHeaders.com API migration

The programmatic api.securityheaders.com API was discontinued in April 2026. Use headersMinGrade on /api/v1/check for a headers-only CI gate (HTTP 422 on fail). Full field map and before/after curl: SecurityHeaders alternative.

Copy-paste workflow (set DOMAIN):

name: Security headers (httpsornot)
on:
  push:
  schedule:
    - cron: "0 8 * * 1"   # weekly smoke

jobs:
  headers:
    runs-on: ubuntu-latest
    steps:
      - name: Fail if headers grade below B
        env:
          DOMAIN: example.com   # ← change this
        run: |
          set -euo pipefail
          # One check per job — public API is 120 req/hour/IP; GHA runners share egress IPs.
          # headersMinGrade: A+|A|B|C|D|F (not sslGrade A-/B+).
          # Policy fail / bot block → HTTP 422. Our rate limit → 429 (different!).
          curl -fsS \
            "https://httpsornot.com/api/v1/check?domain=${DOMAIN}&headersMinGrade=B" \
            -o result.json
          jq '{ grade: .securityHeaders.grade, policyOk, gradingVersion: .sslGrade.gradingVersion }' result.json
          # Optional composite HTTPS gate:
          # curl -fsS "https://httpsornot.com/api/v1/check?domain=${DOMAIN}&minGrade=A-&requireHsts=true"

Rate limit

120 requests per hour per IP (no API key). Responses include RateLimit-* headers. Over limit → 429 with a Retry-After hint when available. For abuse prevention we may retain the caller IP, domain, and outcome for up to 90 days; see Privacy.

• CI / GitHub Actions: runners often share egress IPs. Prefer one check per job (not a matrix over many domains). A 429 from us means our API budget is exhausted — not that the target site failed policy.
• Do not poll in a tight loop; cache the JSON artifact in the workflow if several steps need it.
• Policy failure is 422; rate limit is 429 — treat them differently in scripts.

OpenAPI specification

Machine-readable contract (paths, CI policy params, 422 shape). Import into Postman, Insomnia, or codegen.

• Download openapi.json
• Open in Swagger Editor

Example

curl "https://httpsornot.com/api/v1/check?domain=example.com"

Response includes sslGrade.gradingVersion, securityHeaders, certificate, redirects, and more. Grading methodology. Migrating from SecurityHeaders.com API? Field map + GitHub Actions.

CORS

Access-Control-Allow-Origin: * is set for browser scripts and other origins.