{
  "openapi": "3.1.0",
  "info": {
    "title": "SafeWebLink Link Safety API",
    "version": "1.0.0",
    "description": "Analyze a URL for link warning signs without opening the destination page. Results are advisory and do not prove a link is safe."
  },
  "servers": [{ "url": "https://safeweblink.com" }],
  "paths": {
    "/api/scan": {
      "get": {
        "operationId": "checkLinkSafetyGet",
        "summary": "Check a link by URL parameter",
        "description": "Prefer POST for integrations to keep the submitted URL out of the request path. The destination is not opened.",
        "parameters": [{
          "name": "url",
          "in": "query",
          "required": true,
          "description": "Complete destination URL or domain to analyze.",
          "schema": { "type": "string", "maxLength": 4096, "format": "uri-reference" }
        }],
        "responses": {
          "200": { "description": "Link analysis result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanResult" } } } },
          "400": { "description": "Missing or invalid URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      },
      "post": {
        "operationId": "checkLinkSafety",
        "summary": "Check a link from a JSON request",
        "description": "Read-only link analysis. No API key is required. Requests may be rate-limited. Do not submit private sign-in, reset, or invitation URLs in public contexts.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "required": ["url"], "properties": { "url": { "type": "string", "maxLength": 4096, "description": "Complete destination URL or domain to analyze." } } } } }
        },
        "responses": {
          "200": { "description": "Link analysis result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanResult" } } } },
          "400": { "description": "Missing or invalid URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }
      },
      "ScanResult": {
        "type": "object",
        "required": ["url", "normalizedUrl", "hostname", "domain", "protocol", "scannedAt", "riskScore", "verdict", "confidence", "summary", "signals", "dns", "popularity", "cached"],
        "properties": {
          "url": { "type": "string", "description": "Submitted input; treat as untrusted and potentially private." },
          "normalizedUrl": { "type": "string", "description": "Normalized link; treat as untrusted and potentially private." },
          "hostname": { "type": "string" },
          "domain": { "type": "string" },
          "protocol": { "type": "string", "enum": ["http", "https"] },
          "scannedAt": { "type": "string", "format": "date-time" },
          "riskScore": { "type": "integer", "minimum": 0, "maximum": 100 },
          "verdict": { "type": "string", "enum": ["LOW_RISK", "CAUTION", "SUSPICIOUS", "HIGH_RISK"] },
          "confidence": { "type": "string", "enum": ["LOW", "MEDIUM", "HIGH"] },
          "summary": { "type": "string" },
          "signals": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "severity": { "type": "string" }, "impact": { "type": "integer" } } } },
          "dns": { "type": "object", "properties": { "resolved": { "type": "boolean" }, "ipAddresses": { "type": "array", "items": { "type": "string" } } } },
          "popularity": { "type": "object", "properties": { "listId": { "type": "string" }, "snapshotDate": { "type": "string" }, "membership": { "type": "string", "enum": ["POSSIBLE_MATCH", "NOT_LISTED"] } } },
          "cached": { "type": "boolean" }
        }
      }
    }
  }
}
