{
  "openapi": "3.1.0",
  "info": { "title": "EverThread public API", "version": "1.0.0", "description": "A free, plain-English security check of a website's home page, and the explanations behind every finding. No key required. Observation only.", "contact": { "email": "hello@everthread.live", "url": "https://everthread.live/api" } },
  "servers": [{ "url": "https://security.everthread.live" }],
  "paths": {
    "/api/v1/check": {
      "get": { "operationId": "checkSite", "summary": "Check a website's home page", "parameters": [
        { "name": "url", "in": "query", "required": true, "schema": { "type": "string" }, "example": "yourbakery.com" },
        { "name": "ref", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Name of the tool making the request (or send X-EverThread-Source)." } ],
        "responses": { "200": { "description": "Report card", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Report" } } } }, "400": { "description": "Not a public website address" }, "429": { "description": "Rate limited" } } },
      "post": { "operationId": "checkSitePost", "summary": "Check a website's home page", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["url"], "properties": { "url": { "type": "string" }, "source": { "type": "string" } } } } } },
        "responses": { "200": { "description": "Report card", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Report" } } } } } }
    },
    "/api/v1/explain": { "get": { "operationId": "listFindings", "summary": "Every finding type we report", "responses": { "200": { "description": "List" } } } },
    "/api/v1/explain/{type}": { "get": { "operationId": "explainFinding", "summary": "What a finding means and how to fix it", "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string" }, "example": "tls.expiring" }, { "name": "header", "in": "query", "required": false, "schema": { "type": "string" }, "description": "For header.missing: which header" } ], "responses": { "200": { "description": "Explanation" }, "404": { "description": "Unknown type" } } } }
  },
  "components": { "schemas": { "Report": { "type": "object", "properties": {
    "ok": { "type": "boolean" }, "url": { "type": "string" }, "host": { "type": "string" }, "title": { "type": "string" },
    "verdict": { "type": "string", "enum": ["clean", "attention", "urgent", "blocked"] }, "headline": { "type": "string" },
    "items": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "urgency": { "type": "string", "enum": ["now", "soon", "when convenient", "optional"] }, "urgencyLabel": { "type": "string" }, "title": { "type": "string" }, "what": { "type": "string" }, "fix": { "type": "string" }, "dev": { "type": ["string", "null"] }, "gated": { "type": "boolean", "description": "Exact address withheld from public results" }, "learnMore": { "type": ["string", "null"] } } } },
    "checked": { "type": "array", "items": { "type": "string" } }, "cached": { "type": "boolean" }, "next": { "type": "object", "properties": { "watch": { "type": "string" }, "docs": { "type": "string" } } } } } } }
}