API 文档

鉴权

JSON 请求通过 X-API-Key 请求头传递 Key。无法自定义请求头的 DoH 客户端把 Key 放在 URL 路径中，格式见下方示例。Key 可随时在控制台重命名或吊销。

JSON API

向 POST /api/open/resolve 发送 JSON 请求体，或用 GET 加查询参数快速调试。region 必须为 cn 或 us；支持的类型为 A、AAAA、CNAME、TXT、MX、NS、SOA。

curl -s https://dns.litelake.cn/api/open/resolve \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com","type":"A","region":"cn"}'

JSON API

{
  "code": 200,
  "message": "ok",
  "data": {
    "status": "NOERROR",
    "rcode": 0,
    "answers": [
      { "name": "example.com.", "type": "A", "ttl": 300, "data": "93.184.216.34" }
    ],
    "provenance": {
      "region": "cn",
      "exec_region": "cn",
      "upstream": "223.5.5.5",
      "cache": "miss",
      "latency_ms": 23
    }
  }
}

DNS over HTTPS

GET /api/open/doh/{region}/{apikey}?dns={base64url}，以及使用 application/dns-message 请求体的 POST /api/open/doh/{region}/{apikey}。任何合法 DNS 应答（包括 NXDOMAIN 或 SERVFAIL）都返回 HTTP 200 与二进制报文。

GET

curl -s -H "Accept: application/dns-message" \
  "https://dns.litelake.cn/api/open/doh/cn/YOUR_KEY?dns=AAABAAABAAAAAAAAA3d3dwdleGFtcGxlA2NvbQAAAQAB"

POST

curl -s -X POST \
  -H "Content-Type: application/dns-message" \
  --data-binary @query.bin \
  "https://dns.litelake.cn/api/open/doh/cn/YOUR_KEY"

region 参数

视角是显式参数，不做 GeoDNS 自动判断。未知 region 返回 404。

• region=cn — cn — 中国视角，由境内边缘节点与境内上游执行。
• region=us — us — 海外视角，由海外边缘节点与无过滤上游执行。

应答溯源

每条 JSON 应答都携带视角、执行区域、实际应答上游、缓存状态（miss、fresh、stale）与耗时。DoH 通过 X-LiteDNS-Region、X-LiteDNS-Upstream、X-LiteDNS-Cache 暴露同样信息。

region · exec_region · upstream · cache · latency_ms · rcode

错误码

JSON API 失败时使用原生 HTTP 状态码。DoH 遵循 RFC 8484：合法 DNS 应答一律 2xx，4xx 表示没有产生 DNS 应答。

客户端配置

DoH URL 包含路径，标准客户端均支持。请使用控制台生成的完整带 Key URL。

Agent Skill

读取 Skill 文档无需鉴权。请勿把 API Key 写入共享日志。