{
  "openapi": "3.0.3",
  "info": {
    "title": "DNSPulse Domain Intelligence API",
    "description": "Domain intelligence for AI agents and security workflows. One call returns a domain's DNS records (A, AAAA, MX, NS, TXT, CNAME, SOA), its TLS certificate and its WHOIS registration data (RDAP); a second call lists subdomains seen in Certificate Transparency logs. Generated from packages/dns-pulse/src/handlers/api.ts and verified against the live API on Oct 8 2026.\n",
    "version": "1.1.0"
  },
  "servers": [
    {
      "url": "https://dnspulse.waltsoft.net/v1",
      "description": "DNSPulse production endpoint"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/lookup": {
      "get": {
        "operationId": "getDomainProfile",
        "summary": "DNS records, TLS certificate and WHOIS for a domain",
        "description": "Returns DNS records (A, AAAA, MX, NS, TXT, CNAME, SOA), the TLS certificate served on port 443 and WHOIS registration data from RDAP. ssl is null when the host serves no certificate; whois is null when the registry has no record (for example for a subdomain such as www.example.com).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/Domain"
          }
        ],
        "responses": {
          "200": {
            "description": "Domain profile",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LookupResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/subdomains": {
      "get": {
        "operationId": "getSubdomains",
        "summary": "Subdomains from Certificate Transparency logs",
        "description": "Lists up to 100 hostnames under the domain that appear in public TLS certificates (crt.sh, with certspotter as fallback). Wildcard names are omitted. Can take up to 20 seconds.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/Domain"
          }
        ],
        "responses": {
          "200": {
            "description": "Subdomains",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubdomainsResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "503": {
            "description": "Certificate Transparency sources unavailable; retry later (not billed)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Your AWS Marketplace API key (starts with mp_). Authorization Bearer is also accepted."
      }
    },
    "parameters": {
      "Domain": {
        "name": "domain",
        "in": "query",
        "required": true,
        "description": "Domain name, e.g. example.com (a URL such as https://example.com/path is reduced to its host; IP addresses are rejected)",
        "schema": {
          "type": "string",
          "example": "example.com"
        }
      }
    },
    "schemas": {
      "LookupResponse": {
        "type": "object",
        "properties": {
          "domain": {
            "type": "string",
            "example": "example.com"
          },
          "dns": {
            "type": "object",
            "properties": {
              "a": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "example": [
                  "104.20.23.154"
                ]
              },
              "aaaa": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "mx": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "exchange": {
                      "type": "string",
                      "example": "mail.example.com"
                    },
                    "priority": {
                      "type": "integer",
                      "example": 10
                    }
                  }
                }
              },
              "ns": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "example": [
                  "elliott.ns.cloudflare.com"
                ]
              },
              "txt": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "example": [
                  "v=spf1 -all"
                ]
              },
              "cname": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "soa": {
                "type": "object",
                "nullable": true,
                "properties": {
                  "nsname": {
                    "type": "string"
                  },
                  "hostmaster": {
                    "type": "string"
                  },
                  "serial": {
                    "type": "integer"
                  },
                  "refresh": {
                    "type": "integer"
                  },
                  "retry": {
                    "type": "integer"
                  },
                  "expire": {
                    "type": "integer"
                  },
                  "minttl": {
                    "type": "integer"
                  }
                }
              }
            }
          },
          "ssl": {
            "type": "object",
            "nullable": true,
            "properties": {
              "issuer": {
                "type": "string",
                "example": "SSL Corporation"
              },
              "subject": {
                "type": "string",
                "example": "example.com"
              },
              "validFrom": {
                "type": "string",
                "example": "Sep 26 22:49:11 2026 GMT"
              },
              "validTo": {
                "type": "string",
                "example": "Dec 25 22:56:35 2026 GMT"
              },
              "serialNumber": {
                "type": "string"
              },
              "fingerprint": {
                "type": "string",
                "description": "First bytes of the SHA-256 fingerprint"
              }
            }
          },
          "whois": {
            "type": "object",
            "nullable": true,
            "properties": {
              "registrar": {
                "type": "string",
                "nullable": true,
                "example": "RESERVED-Internet Assigned Numbers Authority"
              },
              "created": {
                "type": "string",
                "nullable": true,
                "format": "date-time",
                "example": "1995-08-14T04:00:00Z"
              },
              "updated": {
                "type": "string",
                "nullable": true,
                "format": "date-time"
              },
              "expires": {
                "type": "string",
                "nullable": true,
                "format": "date-time",
                "example": "2027-08-13T04:00:00Z"
              },
              "status": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "example": [
                  "client delete prohibited"
                ]
              },
              "nameservers": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "source": {
                "type": "string",
                "example": "rdap"
              }
            }
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "SubdomainsResponse": {
        "type": "object",
        "properties": {
          "domain": {
            "type": "string",
            "example": "example.com"
          },
          "subdomains": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "dev.example.com",
              "www.example.com"
            ]
          },
          "count": {
            "type": "integer",
            "example": 6
          },
          "source": {
            "type": "string",
            "example": "certificate-transparency"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "example": "Missing or invalid ?domain= parameter"
          }
        }
      },
      "AuthError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "integer",
                "example": 401
              },
              "message": {
                "type": "string",
                "example": "Invalid or inactive API key"
              }
            }
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Missing domain, or not a valid domain name (not billed)",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Invalid, inactive or other-product API key",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/AuthError"
            }
          }
        }
      },
      "ServerError": {
        "description": "Server error (not billed)",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}