{"openapi":"3.1.0","info":{"title":"Pull WHOIS API","version":"1.0.0","description":"简洁、易用、生产级的域名 WHOIS 查询 API。优先通过注册局 RDAP 获取结构化数据，未覆盖时自动回退到 WHOIS 43 端口，并统一输出字段。","license":{"name":"MIT"}},"servers":[{"url":"/","description":"当前服务"}],"tags":[{"name":"WHOIS","description":"域名查询"},{"name":"System","description":"服务状态"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"},"BearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Registrar":{"type":"object","description":"注册商信息","properties":{"name":{"type":["string","null"],"example":"MarkMonitor Inc."},"ianaId":{"type":["string","null"],"example":"292"},"url":{"type":["string","null"],"example":"http://www.markmonitor.com"},"abuseEmail":{"type":["string","null"],"example":"abusecomplaints@markmonitor.com"},"abusePhone":{"type":["string","null"],"example":"+1.2086851750"}}},"Registrant":{"type":"object","description":"注册人信息。受 GDPR / 隐私保护影响时字段可能被隐藏。","properties":{"name":{"type":["string","null"]},"organization":{"type":["string","null"]},"email":{"type":["string","null"]},"country":{"type":["string","null"]},"redacted":{"type":"boolean","description":"原始数据是否被隐私保护隐藏"}}},"Dates":{"type":"object","properties":{"created":{"type":["string","null"],"format":"date-time"},"updated":{"type":["string","null"],"format":"date-time"},"expires":{"type":["string","null"],"format":"date-time"}}},"WhoisData":{"type":"object","properties":{"domain":{"type":"string","example":"example.com","description":"ASCII / punycode 域名"},"unicodeDomain":{"type":"string","example":"example.com"},"tld":{"type":"string","example":"com"},"sld":{"type":"string","example":"example"},"idn":{"type":"boolean"},"available":{"type":"boolean","description":"域名是否可注册"},"registered":{"type":"boolean"},"registrar":{"oneOf":[{"$ref":"#/components/schemas/Registrar"},{"type":"null"}]},"registrant":{"oneOf":[{"$ref":"#/components/schemas/Registrant"},{"type":"null"}]},"dates":{"$ref":"#/components/schemas/Dates"},"statuses":{"type":"array","items":{"type":"string"},"example":["clientTransferProhibited"],"description":"已归一化为 EPP 风格的状态码"},"nameservers":{"type":"array","items":{"type":"string"},"example":["a.iana-servers.net","b.iana-servers.net"]},"dnssec":{"type":"string","enum":["signed","unsigned","unknown"]},"registryDomainId":{"type":["string","null"]},"raw":{"type":"string","description":"原始 RDAP JSON 或 WHOIS 文本，仅在 raw=true 时返回"}},"required":["domain","available","registered","statuses","nameservers"]},"RateLimit":{"type":"object","properties":{"limit":{"type":"integer","example":120},"remaining":{"type":"integer","example":118},"reset":{"type":"integer","description":"距离窗口重置的秒数","example":42}}},"Meta":{"type":"object","properties":{"source":{"type":"string","enum":["rdap","whois"]},"server":{"type":"string","example":"rdap.verisign.com"},"durationMs":{"type":"integer","example":612},"cached":{"type":"boolean"},"cacheTtlMs":{"type":"integer","example":600000},"queriedAt":{"type":"string","format":"date-time"},"requestId":{"type":"string"},"rateLimit":{"$ref":"#/components/schemas/RateLimit"}}},"SuccessEnvelope":{"type":"object","required":["success","data","meta"],"properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/WhoisData"},"meta":{"$ref":"#/components/schemas/Meta"}}},"ErrorEnvelope":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string","enum":["INVALID_DOMAIN","BAD_REQUEST","UNAUTHORIZED","NOT_FOUND","RATE_LIMITED","UPSTREAM_UNAVAILABLE","UPSTREAM_TIMEOUT","INTERNAL"]},"message":{"type":"string"},"details":{}}},"meta":{"type":"object","properties":{"requestId":{"type":"string"}}}}},"BatchRequest":{"type":"object","required":["domains"],"properties":{"domains":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string"},"example":["example.com","github.com","example.invalid"]},"raw":{"type":"boolean","default":false},"refresh":{"type":"boolean","default":false}}}}},"paths":{"/v1/whois/{domain}":{"get":{"tags":["WHOIS"],"operationId":"lookupDomainByPath","summary":"查询单个域名","description":"查询域名注册信息。优先使用注册局 RDAP，未覆盖时自动回退 WHOIS。结果默认缓存 10 分钟，可注册域名缓存 60 秒。","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]},{}],"parameters":[{"name":"domain","in":"path","required":true,"description":"域名、URL 或邮箱中的域名，支持 IDN","schema":{"type":"string","example":"example.com"}},{"name":"raw","in":"query","description":"返回原始 RDAP JSON / WHOIS 文本","schema":{"type":"boolean","default":false}},{"name":"refresh","in":"query","description":"跳过缓存强制刷新","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"查询成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"success":true,"data":{"domain":"example.com","unicodeDomain":"example.com","tld":"com","sld":"example","idn":false,"available":false,"registered":true,"registrar":{"name":"RESERVED-Internet Assigned Numbers Authority","ianaId":"376","url":"https://www.iana.org/","abuseEmail":null,"abusePhone":null},"registrant":null,"dates":{"created":"1995-08-14T04:00:00.000Z","updated":"2025-08-14T07:01:38.000Z","expires":"2026-08-13T04:00:00.000Z"},"statuses":["clientTransferProhibited"],"nameservers":["a.iana-servers.net","b.iana-servers.net"],"dnssec":"unsigned","registryDomainId":"2336799_DOMAIN_COM-VRSN"},"meta":{"source":"rdap","server":"rdap.verisign.com","durationMs":612,"cached":false,"cacheTtlMs":600000,"queriedAt":"2026-11-21T08:00:00.000Z","requestId":"req-1","rateLimit":{"limit":120,"remaining":118,"reset":42}}}}}},"400":{"description":"域名格式不合法","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"code":"INVALID_DOMAIN","message":"请输入完整域名（包含后缀），例如 example.com"},"meta":{"requestId":"req-2"}}}}},"429":{"description":"触发限流","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"上游 RDAP / WHOIS 不可用","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/whois":{"get":{"tags":["WHOIS"],"operationId":"lookupDomainByQuery","summary":"查询单个域名（查询参数形式）","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]},{}],"parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string","example":"example.com"}},{"name":"raw","in":"query","schema":{"type":"boolean","default":false}},{"name":"refresh","in":"query","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"查询成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"success":true,"data":{"domain":"example.com","unicodeDomain":"example.com","tld":"com","sld":"example","idn":false,"available":false,"registered":true,"registrar":{"name":"RESERVED-Internet Assigned Numbers Authority","ianaId":"376","url":"https://www.iana.org/","abuseEmail":null,"abusePhone":null},"registrant":null,"dates":{"created":"1995-08-14T04:00:00.000Z","updated":"2025-08-14T07:01:38.000Z","expires":"2026-08-13T04:00:00.000Z"},"statuses":["clientTransferProhibited"],"nameservers":["a.iana-servers.net","b.iana-servers.net"],"dnssec":"unsigned","registryDomainId":"2336799_DOMAIN_COM-VRSN"},"meta":{"source":"rdap","server":"rdap.verisign.com","durationMs":612,"cached":false,"cacheTtlMs":600000,"queriedAt":"2026-11-21T08:00:00.000Z","requestId":"req-1","rateLimit":{"limit":120,"remaining":118,"reset":42}}}}}},"400":{"description":"参数不合法","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/whois/batch":{"post":{"tags":["WHOIS"],"operationId":"lookupDomainsBatch","summary":"批量查询域名","description":"一次最多查询 20 个域名，服务端以 5 个并发执行。单个域名失败不会影响其他结果。","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchRequest"},"example":{"domains":["example.com","github.com"],"raw":false}}}},"responses":{"200":{"description":"批量查询结果","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"results":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"$ref":"#/components/schemas/ErrorEnvelope"}]}},"meta":{"type":"object","properties":{"count":{"type":"integer"},"durationMs":{"type":"integer"},"requestId":{"type":"string"}}}}},"example":{"success":true,"results":[{"success":true,"data":{"domain":"example.com","unicodeDomain":"example.com","tld":"com","sld":"example","idn":false,"available":false,"registered":true,"registrar":{"name":"RESERVED-Internet Assigned Numbers Authority","ianaId":"376","url":"https://www.iana.org/","abuseEmail":null,"abusePhone":null},"registrant":null,"dates":{"created":"1995-08-14T04:00:00.000Z","updated":"2025-08-14T07:01:38.000Z","expires":"2026-08-13T04:00:00.000Z"},"statuses":["clientTransferProhibited"],"nameservers":["a.iana-servers.net","b.iana-servers.net"],"dnssec":"unsigned","registryDomainId":"2336799_DOMAIN_COM-VRSN"},"meta":{"source":"rdap","server":"rdap.verisign.com","durationMs":480,"cached":false,"cacheTtlMs":600000,"queriedAt":"2026-11-21T08:00:00.000Z","requestId":"req-3","rateLimit":{"limit":120,"remaining":110,"reset":40}}},{"success":false,"error":{"code":"INVALID_DOMAIN","message":"请输入完整域名（包含后缀），例如 example.com"}}],"meta":{"count":2,"durationMs":731,"requestId":"req-3"}}}}},"400":{"description":"请求体不合法","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/tlds":{"get":{"tags":["WHOIS"],"operationId":"listTlds","summary":"列出内置支持的 TLD 与 WHOIS 服务器","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]},{}],"responses":{"200":{"description":"已内置映射的 TLD 列表（其他后缀会动态向 IANA 查询）","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"count":{"type":"integer"},"tlds":{"type":"array","items":{"type":"object","properties":{"tld":{"type":"string"},"host":{"type":"string"},"port":{"type":"integer"}}}}}}}},"example":{"success":true,"data":{"count":2,"tlds":[{"tld":"com","host":"whois.verisign-grs.com","port":43}]}}}}}}}},"/health":{"get":{"tags":["System"],"operationId":"health","summary":"健康检查","responses":{"200":{"description":"服务正常","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"version":{"type":"string","example":"1.0.0"},"uptimeSec":{"type":"integer"},"now":{"type":"string","format":"date-time"}}}}}}}}}}}}}