{
  "openapi": "3.0.2",
  "info": {
    "title": "Zeah DomainGuard Security Posture API",
    "version": "1.1.0",
    "description": "Automated external attack-surface discovery and domain security posture checks covering public DNS/TLS surface, HTTP security headers, SPF, DMARC, MX, MTA-STS, TLS-RPT, and DNSSEC."
  },
  "servers": [
    {
      "url": "https://api.zeah.ai"
    }
  ],
  "paths": {
    "/api/public/domain-audit/{domain}": {
      "get": {
        "summary": "Audit a domain security posture",
        "parameters": [
          {
            "name": "domain",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "example.com"
          }
        ],
        "responses": {
          "200": {
            "description": "Security posture report with bounded public Surface Map",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "service": {
                      "type": "string"
                    },
                    "version": {
                      "type": "string"
                    },
                    "domain": {
                      "type": "string"
                    },
                    "score": {
                      "type": "integer"
                    },
                    "grade": {
                      "type": "string"
                    },
                    "surface": {
                      "type": "object",
                      "description": "Bounded public DNS/TLS discovery; not a port scan",
                      "properties": {
                        "mode": {
                          "type": "string"
                        },
                        "host_count": {
                          "type": "integer"
                        },
                        "public_ip_count": {
                          "type": "integer"
                        },
                        "nameservers": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "mail_exchangers": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "certificate_names": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "hosts": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "hostname": {
                                "type": "string"
                              },
                              "source": {
                                "type": "string"
                              },
                              "public_ips": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              "cname": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "private_dns_answer": {
                                "type": "boolean"
                              }
                            }
                          }
                        }
                      }
                    },
                    "checks": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "recommendations": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid or non-public domain"
          },
          "403": {
            "description": "Origin authentication failed"
          },
          "429": {
            "description": "Scanner busy"
          },
          "502": {
            "description": "Domain scan failed"
          }
        }
      }
    }
  }
}