{
  "openapi": "3.1.0",
  "info": {
    "title": "DomBrains API",
    "version": "1.0.0",
    "description": "REST API for every DomBrains tool — SSL, DMARC, SPF, DKIM, WHOIS, DNS, security headers, CT logs, subdomain takeover, typosquat watcher, and more.\n\nAuth: Bearer token. Rate limit: 60 req/min/key. Responses cached 10 min per tool+domain combo.",
    "contact": { "name": "DomBrains", "url": "https://dombrains.com" },
    "license": { "name": "Free during early access" }
  },
  "servers": [
    { "url": "https://dombrains.com/api/v1", "description": "Production" }
  ],
  "security": [{ "bearerAuth": [] }, { "apiKeyQuery": [] }],
  "tags": [
    { "name": "Tools", "description": "Run any single tool against a domain" },
    { "name": "Profile", "description": "Composite 8-check profile (same as /d/:domain, cached 24h)" },
    { "name": "Meta", "description": "Tool catalog + key usage" }
  ],
  "paths": {
    "/tools": {
      "get": {
        "tags": ["Meta"],
        "summary": "List available tool slugs",
        "responses": {
          "200": {
            "description": "OK",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolList" } } }
          }
        }
      }
    },
    "/usage": {
      "get": {
        "tags": ["Meta"],
        "summary": "Current API key metadata + usage stats",
        "responses": {
          "200": {
            "description": "OK",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } }
          }
        }
      }
    },
    "/check/{tool}/{domain}": {
      "get": {
        "tags": ["Tools"],
        "summary": "Run one tool on a domain",
        "parameters": [
          { "name": "tool",   "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tool slug (e.g. `ssl`, `dmarc`, `spf`). See `/tools` for the full list." },
          { "name": "domain", "in": "path", "required": true, "schema": { "type": "string", "format": "hostname" }, "example": "example.com" },
          { "name": "selector",    "in": "query", "schema": { "type": "string" }, "description": "Required for `dkim` tool (DKIM selector name, e.g. `default`, `google`, `s1`)" },
          { "name": "record_type", "in": "query", "schema": { "type": "string", "enum": ["A","AAAA","CNAME","MX","TXT","NS"] }, "description": "For `dns_propagation` tool" }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckResponse" } } }
          },
          "400": { "description": "Unknown tool or invalid domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "401": { "description": "Missing / invalid API key" },
          "429": { "description": "Rate limit exceeded (60/min)" }
        }
      }
    },
    "/profile/{domain}": {
      "get": {
        "tags": ["Profile"],
        "summary": "Composite 8-check profile (cached 24h)",
        "description": "Runs SSL + DMARC + SPF + MX + NS + WHOIS + DNSSEC + Security Headers in parallel and returns a summary per check. Same data as the public `/d/:domain` page, in JSON.",
        "parameters": [
          { "name": "domain", "in": "path", "required": true, "schema": { "type": "string", "format": "hostname" }, "example": "example.com" }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileResponse" } } }
          },
          "400": { "description": "Invalid domain" },
          "422": { "description": "Profile could not be built" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "dbk_*" },
      "apiKeyQuery": { "type": "apiKey", "in": "query", "name": "api_key", "description": "Alternative to Authorization header — pass the key as ?api_key=dbk_..." }
    },
    "schemas": {
      "Status": {
        "type": "string",
        "enum": ["ok", "warning", "critical", "error"],
        "description": "`ok` — healthy · `warning` — improvable · `critical` — broken but reachable · `error` — we couldn't check (connection failure, SSL handshake, etc.)"
      },
      "Error": {
        "type": "object",
        "properties": { "ok": { "type": "boolean", "example": false }, "error": { "type": "string" } }
      },
      "ToolList": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean" },
          "tools": { "type": "array", "items": { "type": "string" }, "example": ["ssl", "dmarc", "spf", "dkim", "mx", "ns", "whois"] }
        }
      },
      "Usage": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean" },
          "api_key": {
            "type": "object",
            "properties": {
              "label":        { "type": "string", "nullable": true },
              "created_at":   { "type": "string", "format": "date-time" },
              "last_used_at": { "type": "string", "format": "date-time", "nullable": true },
              "calls_count":  { "type": "integer" }
            }
          },
          "rate_limit_per_minute": { "type": "integer", "example": 60 }
        }
      },
      "CheckResponse": {
        "type": "object",
        "properties": {
          "ok":             { "type": "boolean" },
          "domain":         { "type": "string" },
          "status":         { "$ref": "#/components/schemas/Status" },
          "status_message": { "type": "string" },
          "data":           { "type": "object", "description": "Tool-specific fields (SSL returns chain/issuer/expiry; DMARC returns policy/alignment; etc.)" },
          "cache_hit":      { "type": "boolean", "description": "`true` if served from cache; `false` if freshly generated" },
          "generated_at":   { "type": "string", "format": "date-time" },
          "cached_until":   { "type": "string", "format": "date-time" }
        }
      },
      "ProfileCheck": {
        "type": "object",
        "properties": {
          "key":            { "type": "string", "example": "ssl" },
          "pretty":         { "type": "string", "example": "SSL Certificate" },
          "status":         { "$ref": "#/components/schemas/Status" },
          "status_message": { "type": "string" },
          "summary":        { "type": "string", "nullable": true }
        }
      },
      "ProfileResponse": {
        "type": "object",
        "properties": {
          "ok":             { "type": "boolean" },
          "domain":         { "type": "string" },
          "overall_status": { "$ref": "#/components/schemas/Status" },
          "generated_at":   { "type": "string", "format": "date-time" },
          "cached_until":   { "type": "string", "format": "date-time" },
          "checks":         { "type": "array", "items": { "$ref": "#/components/schemas/ProfileCheck" } }
        }
      }
    }
  }
}