{
  "openapi": "3.1.0",
  "info": {
    "title": "DNSTrace.dev API",
    "version": "2.1.0",
    "description": "DNS, RDAP, IP, ASN, TLS, HTTP, email-security and global DNS measurement endpoints. Every path uses good-faith rate limits, stable public results may be cached, and diagnostic routes require a short-lived Turnstile session when protection is configured."
  },
  "servers": [{ "url": "https://dnstrace.dev" }],
  "paths": {
    "/api/turnstile/status": {
      "get": {
        "operationId": "getLookupProtectionStatus",
        "summary": "Read Turnstile activation, session and rate-limit status",
        "responses": { "200": { "description": "Protection status and configured limit tiers", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/api/turnstile/verify": {
      "post": {
        "operationId": "verifyLookupAccess",
        "summary": "Validate a single-use Turnstile token and start a 15-minute lookup session",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "required": ["token"], "properties": { "token": { "type": "string" } } } } }
        },
        "responses": { "200": { "description": "Verification result with an HttpOnly session cookie" }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/api/dns": {
      "get": {
        "operationId": "lookupDns",
        "summary": "Resolve a DNS record",
        "parameters": [
          { "name": "target", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": ["A", "AAAA", "CNAME", "MX", "TXT", "NS", "SOA", "CAA", "SRV", "PTR"], "default": "A" } }
        ],
        "responses": { "200": { "description": "DNS answers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DnsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/api/email-security": {
      "get": {
        "operationId": "validateEmailSecurity",
        "summary": "Validate public email routing, authentication and transport policies",
        "parameters": [
          { "name": "domain", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "selector", "in": "query", "required": false, "description": "A known DKIM selector to test before the common selector set.", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Scored MX, SPF, DMARC, DKIM, MTA-STS, TLS-RPT and BIMI validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailSecurityResponse" } } } },
          "400": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" },
          "502": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/rdap": {
      "get": {
        "operationId": "lookupRdap",
        "summary": "Read domain or IP registration data",
        "parameters": [
          { "name": "target", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "type", "in": "query", "required": true, "schema": { "type": "string", "enum": ["domain", "ip"] } }
        ],
        "responses": { "200": { "description": "Registry and optional registrar RDAP objects", "content": { "application/json": { "schema": { "type": "object", "properties": { "registry": { "type": "object", "additionalProperties": true }, "registrar": { "type": ["object", "null"], "additionalProperties": true } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/api/inspect": {
      "get": {
        "operationId": "inspectTarget",
        "summary": "Inspect HTTPS and network routing, with optional TLS",
        "parameters": [
          { "name": "target", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "ip", "in": "query", "required": false, "schema": { "type": "string" } },
          { "name": "include_tls", "in": "query", "required": false, "description": "Set to false when TLS is requested separately through /api/tls.", "schema": { "type": "boolean", "default": true } }
        ],
        "responses": { "200": { "description": "HTTP, TLS and network evidence", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/api/tls": {
      "get": {
        "operationId": "inspectTlsCertificate",
        "summary": "Inspect the certificate currently served by a hostname",
        "parameters": [{ "name": "target", "in": "query", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Live TLS certificate evidence", "content": { "application/json": { "schema": { "type": "object", "required": ["tls"], "properties": { "tls": { "type": "object", "additionalProperties": true } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/api/global-dns": {
      "post": {
        "operationId": "measureGlobalDns",
        "summary": "Measure a DNS record from ten countries",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["target", "type"],
                "properties": {
                  "target": { "type": "string" },
                  "type": { "type": "string", "enum": ["A", "AAAA", "CNAME", "MX", "TXT", "NS", "SOA", "CAA"] }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "Globalping measurement", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/api/my-ip": {
      "get": {
        "operationId": "getMyIp",
        "summary": "Read the caller's connection metadata",
        "responses": { "200": { "description": "Connection address and Cloudflare edge metadata", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }
      }
    },
    "/api/ip-geo": {
      "get": {
        "operationId": "lookupIpGeolocation",
        "summary": "Read approximate public network geolocation",
        "parameters": [{ "name": "ip", "in": "query", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Approximate network metadata", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/api/ip-privacy": {
      "get": {
        "operationId": "classifyIpPrivacy",
        "summary": "Check an IP against Apple Private Relay egress ranges",
        "parameters": [{ "name": "ip", "in": "query", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Apple Private Relay egress classification", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/api/certificates": {
      "get": {
        "operationId": "lookupCertificateTransparency",
        "summary": "Read recent certificate-transparency issuances",
        "parameters": [{ "name": "domain", "in": "query", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Attributed crt.sh issuance records with optional Cert Spotter fallback", "content": { "application/json": { "schema": { "type": "object", "required": ["issuances", "providers_tried"], "properties": { "issuances": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "source": { "type": ["string", "null"] }, "source_id": { "type": ["string", "null"] }, "providers_tried": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderAttempt" } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/api/subdomains": {
      "get": {
        "operationId": "discoverSubdomains",
        "summary": "Discover certificate-transparency subdomains and resolve current DNS answers",
        "parameters": [{ "name": "domain", "in": "query", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Attributed historical names and live DNS checks for up to 50 subdomains", "content": { "application/json": { "schema": { "type": "object", "required": ["domain", "discovered_count", "checked_count", "active_count", "hosts", "source", "providers_tried"], "properties": { "domain": { "type": "string" }, "discovered_count": { "type": "integer" }, "checked_count": { "type": "integer" }, "active_count": { "type": "integer" }, "truncated": { "type": "boolean" }, "hosts": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "source": { "type": "string" }, "source_id": { "type": "string" }, "providers_tried": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderAttempt" } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/api/providers": {
      "get": {
        "operationId": "listProviders",
        "summary": "List data providers, capabilities, access rules and fallback policy",
        "responses": { "200": { "description": "Provider inventory and selection policy", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }
      }
    }
  },
  "components": {
    "schemas": {
      "DnsResponse": {
        "type": "object",
        "required": ["target", "type", "answers", "records", "source", "source_id", "providers_tried"],
        "properties": { "target": { "type": "string" }, "type": { "type": "string" }, "answers": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "records": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "source": { "type": "string" }, "source_id": { "type": "string" }, "providers_tried": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderAttempt" } } }
      },
      "EmailSecurityResponse": {
        "type": "object",
        "required": ["domain", "score", "grade", "checks", "mx", "tested_dkim_selectors", "recommendations"],
        "properties": {
          "domain": { "type": "string" },
          "score": { "type": "integer", "minimum": 0, "maximum": 100 },
          "grade": { "type": "string", "enum": ["A", "B", "C", "D", "F"] },
          "checks": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
          "mx": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
          "tested_dkim_selectors": { "type": "array", "items": { "type": "string" } },
          "recommendations": { "type": "array", "items": { "type": "object", "additionalProperties": true } }
        }
      },
      "ProviderAttempt": { "type": "object", "required": ["id", "name", "status"], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": ["ok", "failed"] }, "error": { "type": "string" } } },
      "Error": { "type": "object", "required": ["error"], "properties": { "error": { "type": "string" } } }
    },
    "responses": {
      "Error": { "description": "Lookup error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    }
  }
}