{"openapi":"3.0.3","info":{"title":"HTTP Security Header Scanner API","version":"1.0.0","description":"Audits HSTS, Content-Security-Policy quality, X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy, and CORS configuration with a 0-100 score and copy-paste fixes."},"servers":[{"url":"https://api.tinplate.dev","description":"Production Edge Gateway"}],"components":{"schemas":{"SecurityHeadersResponse":{"type":"object","properties":{"target_url":{"type":"string","nullable":true},"http_status":{"type":"integer","nullable":true},"score":{"type":"integer","minimum":0,"maximum":100},"grade":{"type":"string","enum":["A","B","C","D","F"]},"checks":{"type":"object","properties":{"hsts":{"type":"object","properties":{"status":{"type":"string","enum":["pass","warn","fail"]},"score":{"type":"integer","minimum":0},"max_score":{"type":"integer","minimum":0},"value":{"type":"string","nullable":true},"issues":{"type":"array","items":{"type":"string"}},"fix":{"type":"string","nullable":true}},"required":["status","score","max_score","value","issues","fix"]},"csp":{"type":"object","properties":{"status":{"type":"string","enum":["pass","warn","fail"]},"score":{"type":"integer","minimum":0},"max_score":{"type":"integer","minimum":0},"value":{"type":"string","nullable":true},"issues":{"type":"array","items":{"type":"string"}},"fix":{"type":"string","nullable":true}},"required":["status","score","max_score","value","issues","fix"]},"x_content_type_options":{"type":"object","properties":{"status":{"type":"string","enum":["pass","warn","fail"]},"score":{"type":"integer","minimum":0},"max_score":{"type":"integer","minimum":0},"value":{"type":"string","nullable":true},"issues":{"type":"array","items":{"type":"string"}},"fix":{"type":"string","nullable":true}},"required":["status","score","max_score","value","issues","fix"]},"frame_protection":{"type":"object","properties":{"status":{"type":"string","enum":["pass","warn","fail"]},"score":{"type":"integer","minimum":0},"max_score":{"type":"integer","minimum":0},"value":{"type":"string","nullable":true},"issues":{"type":"array","items":{"type":"string"}},"fix":{"type":"string","nullable":true}},"required":["status","score","max_score","value","issues","fix"]},"referrer_policy":{"type":"object","properties":{"status":{"type":"string","enum":["pass","warn","fail"]},"score":{"type":"integer","minimum":0},"max_score":{"type":"integer","minimum":0},"value":{"type":"string","nullable":true},"issues":{"type":"array","items":{"type":"string"}},"fix":{"type":"string","nullable":true}},"required":["status","score","max_score","value","issues","fix"]},"permissions_policy":{"type":"object","properties":{"status":{"type":"string","enum":["pass","warn","fail"]},"score":{"type":"integer","minimum":0},"max_score":{"type":"integer","minimum":0},"value":{"type":"string","nullable":true},"issues":{"type":"array","items":{"type":"string"}},"fix":{"type":"string","nullable":true}},"required":["status","score","max_score","value","issues","fix"]}},"required":["hsts","csp","x_content_type_options","frame_protection","referrer_policy","permissions_policy"]},"cors":{"type":"object","properties":{"allow_origin":{"type":"string","nullable":true},"allow_credentials":{"type":"string","nullable":true},"wildcard":{"type":"boolean"},"misconfigured":{"type":"boolean"}},"required":["allow_origin","allow_credentials","wildcard","misconfigured"]},"fixes":{"type":"array","items":{"type":"object","properties":{"header":{"type":"string"},"priority":{"type":"string","enum":["high","medium","low"]},"recommended_value":{"type":"string"}},"required":["header","priority","recommended_value"]}}},"required":["target_url","http_status","score","grade","checks","cors","fixes"]},"SecurityHeadersRequest":{"type":"object","properties":{"url":{"type":"string","maxLength":2048,"format":"uri","example":"https://example.com","description":"Target URL to fetch via private fetcher and inspect security headers."},"headers":{"type":"object","additionalProperties":{"type":"string","maxLength":4096},"example":{"strict-transport-security":"max-age=31536000; includeSubDomains","x-content-type-options":"nosniff"},"description":"Optional raw response headers to audit offline without making an HTTP request."}}},"ResponseMeta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","format":"uuid"},"ms":{"type":"integer","minimum":0},"version":{"type":"string","example":"1.0.0"}}},"ErrorEnvelope":{"type":"object","required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"invalid_input"},"message":{"type":"string","example":"Request body failed validation"}}},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}}},"parameters":{}},"paths":{"/v1/security-headers":{"post":{"tags":["07_SECURITY_HEADERS"],"summary":"Scan a URL (via private fetcher) or raw headers for HTTP security posture","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SecurityHeadersRequest"}}}},"responses":{"200":{"description":"Security header audit result","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/SecurityHeadersResponse"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["ok","data","meta"]}}}},"400":{"description":"Invalid input or malformed JSON request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid authentication credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request payload exceeds subscribed plan byte cap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}