{
  "openapi": "3.0.3",
  "info": {
    "title": "Domain Health Checker",
    "version": "1.0.0",
    "description": "DNS, TLS, email authentication, HTTP, and crawler checks. One scored report per domain. Try it without a key at https://api.impakt.dev. Demo calls are capped at 5 per address per day and $0.50 for everyone per UTC day."
  },
  "servers": [
    {
      "url": "https://api.impakt.dev",
      "description": "Public API at https://api.impakt.dev."
    }
  ],
  "tags": [
    {
      "name": "Domains"
    }
  ],
  "paths": {
    "/domains/health": {
      "get": {
        "operationId": "getDomainHealth",
        "tags": [
          "Domains"
        ],
        "summary": "Domain health audit: DNS, email auth (SPF/DKIM/DMARC), TLS, HTTP, crawlers",
        "description": "Up to 3 domains per call. Returns a score, a grade and a list of issues with severity.",
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": true,
            "description": "Comma-separated domains (max 3).",
            "schema": {
              "type": "string"
            },
            "example": "example.com"
          },
          {
            "name": "checks",
            "in": "query",
            "required": false,
            "description": "Comma-separated subset of dns,email,tls,http,crawlers (default all). Fewer checks run faster.",
            "schema": {
              "type": "string"
            },
            "example": "dns,email"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                },
                "example": {
                  "count": 1,
                  "limit": 1,
                  "results": [
                    {
                      "domain": "thisdomaindoesnotexist-zzqq-123.com",
                      "score": 0,
                      "grade": "F",
                      "summary": "Domain does not resolve.",
                      "issues": [
                        {
                          "severity": "critical",
                          "code": "domain_not_found",
                          "message": "The domain does not resolve (NXDOMAIN)."
                        }
                      ],
                      "checkedAt": "2026-11-19T04:11:52.861Z",
                      "dns": {
                        "exists": false,
                        "a": [],
                        "aaaa": [],
                        "mx": [],
                        "ns": [],
                        "caa": [],
                        "txtCount": 0
                      },
                      "issueCounts": {
                        "critical": 1,
                        "high": 0,
                        "medium": 0,
                        "low": 0,
                        "info": 0
                      }
                    }
                  ],
                  "request_id": "00000000-0000-4000-8000-000000000000"
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameter or body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing or invalid marketplace secret (call through the marketplace).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "The backend rejected the input.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable or daily capacity reached. Retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "504": {
            "description": "Took longer than 25 seconds; reduce the amount of work.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "EmailResult": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string"
          },
          "normalizedEmail": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "score": {
            "type": "integer"
          },
          "reasons": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "syntaxValid": {
            "type": "boolean"
          },
          "domain": {
            "type": "string"
          },
          "domainExists": {
            "type": "boolean"
          },
          "hasMx": {
            "type": "boolean"
          },
          "mxHosts": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "mxProvider": {
            "type": "string",
            "nullable": true
          },
          "isDisposable": {
            "type": "boolean"
          },
          "isRoleAccount": {
            "type": "boolean"
          },
          "isFreeProvider": {
            "type": "boolean"
          },
          "suggestion": {
            "type": "string",
            "nullable": true
          },
          "smtpChecked": {
            "type": "boolean"
          },
          "checkedAt": {
            "type": "string"
          }
        },
        "description": "One EmailResult record. Fields not offered by a source are null; some fields are omitted depending on the request (see property descriptions)."
      },
      "DomainAvailability": {
        "type": "object",
        "properties": {
          "domain": {
            "type": "string"
          },
          "tld": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "available": {
            "type": "boolean",
            "nullable": true
          },
          "method": {
            "type": "string"
          },
          "registrar": {
            "type": "string",
            "nullable": true
          },
          "registeredAt": {
            "type": "string",
            "nullable": true
          },
          "expiresAt": {
            "type": "string",
            "nullable": true
          },
          "updatedAt": {
            "type": "string",
            "nullable": true
          },
          "ageDays": {
            "type": "integer",
            "nullable": true
          },
          "daysUntilExpiry": {
            "type": "integer",
            "nullable": true
          },
          "nameservers": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "rdapStatus": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "reason": {
            "type": "string",
            "nullable": true
          },
          "checkedAt": {
            "type": "string"
          }
        },
        "description": "One DomainAvailability record. Fields not offered by a source are null; some fields are omitted depending on the request (see property descriptions)."
      },
      "DomainHealth": {
        "type": "object",
        "properties": {
          "domain": {
            "type": "string"
          },
          "score": {
            "type": "integer"
          },
          "grade": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "issues": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "checkedAt": {
            "type": "string"
          },
          "dns": {
            "type": "object",
            "properties": {
              "exists": {
                "type": "boolean"
              },
              "a": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "aaaa": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "mx": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "ns": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "caa": {
                "type": "array",
                "items": {}
              },
              "txtCount": {
                "type": "integer"
              }
            }
          },
          "issueCounts": {
            "type": "object",
            "properties": {
              "critical": {
                "type": "integer"
              },
              "high": {
                "type": "integer"
              },
              "medium": {
                "type": "integer"
              },
              "low": {
                "type": "integer"
              },
              "info": {
                "type": "integer"
              }
            }
          },
          "tls": {
            "type": "object",
            "properties": {
              "reachable": {
                "type": "boolean"
              },
              "protocol": {
                "type": "string"
              },
              "issuer": {
                "type": "string"
              },
              "subjectCommonName": {
                "type": "string"
              },
              "altNames": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "validFrom": {
                "type": "string"
              },
              "validTo": {
                "type": "string"
              },
              "daysRemaining": {
                "type": "integer"
              },
              "trusted": {
                "type": "boolean"
              },
              "trustError": {
                "nullable": true,
                "type": "string"
              },
              "hostnameMatches": {
                "type": "boolean"
              },
              "keyType": {
                "type": "string"
              }
            }
          },
          "emailAuth": {
            "type": "object",
            "properties": {
              "spf": {
                "type": "object",
                "additionalProperties": true
              },
              "dmarc": {
                "type": "object",
                "additionalProperties": true
              },
              "mtaSts": {
                "type": "object",
                "additionalProperties": true
              },
              "dkim": {
                "type": "object",
                "additionalProperties": true
              },
              "mx": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "crawlers": {
            "type": "object",
            "properties": {
              "robotsTxt": {
                "type": "boolean"
              },
              "sitemapsDeclared": {
                "type": "array",
                "items": {}
              },
              "sitemapXmlPresent": {
                "type": "boolean"
              },
              "llmsTxt": {
                "type": "boolean"
              },
              "securityTxt": {
                "type": "boolean"
              },
              "blocksAllCrawlers": {
                "type": "boolean"
              },
              "aiCrawlersBlocked": {
                "type": "array",
                "items": {}
              },
              "aiCrawlersAllowed": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "http": {
            "type": "object",
            "properties": {
              "reachable": {
                "type": "boolean"
              },
              "statusCode": {
                "type": "integer"
              },
              "finalUrl": {
                "type": "string"
              },
              "redirects": {
                "type": "integer"
              },
              "responseTimeMs": {
                "type": "integer"
              },
              "securityHeaders": {
                "type": "object",
                "additionalProperties": true
              },
              "cacheControl": {
                "nullable": true,
                "type": "string"
              },
              "httpRedirectsToHttps": {
                "type": "boolean"
              }
            }
          }
        },
        "description": "One DomainHealth record. Fields not offered by a source are null; some fields are omitted depending on the request (see property descriptions)."
      },
      "EmailsResponse": {
        "type": "object",
        "required": [
          "count",
          "limit",
          "results",
          "request_id"
        ],
        "properties": {
          "count": {
            "type": "integer",
            "description": "Number of records returned."
          },
          "limit": {
            "type": "integer",
            "description": "Maximum records for this call."
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EmailResult"
            }
          },
          "request_id": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "AvailabilityResponse": {
        "type": "object",
        "required": [
          "count",
          "limit",
          "results",
          "request_id"
        ],
        "properties": {
          "count": {
            "type": "integer",
            "description": "Number of records returned."
          },
          "limit": {
            "type": "integer",
            "description": "Maximum records for this call."
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DomainAvailability"
            }
          },
          "request_id": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "HealthResponse": {
        "type": "object",
        "required": [
          "count",
          "limit",
          "results",
          "request_id"
        ],
        "properties": {
          "count": {
            "type": "integer",
            "description": "Number of records returned."
          },
          "limit": {
            "type": "integer",
            "description": "Maximum records for this call."
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DomainHealth"
            }
          },
          "request_id": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "example": "invalid_parameter"
              },
              "message": {
                "type": "string"
              },
              "param": {
                "type": "string"
              }
            }
          },
          "request_id": {
            "type": "string",
            "format": "uuid"
          }
        }
      }
    }
  }
}
