API documentation

Authentication

Send the key in the X-API-Key header for JSON requests. DoH clients that cannot set custom headers put the key in the URL path, exactly as shown below. Keys can be renamed or revoked at any time in the console.

JSON API

POST /api/open/resolve with a JSON body, or use GET with query parameters for a quick curl check. The region must be cn or us. Supported types are A, AAAA, CNAME, TXT, MX, NS and 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} and POST /api/open/doh/{region}/{apikey} with an application/dns-message body. Any valid DNS answer, including NXDOMAIN or SERVFAIL, is returned with HTTP 200 and the wire response.

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 parameter

The region is an explicit parameter, not an automatic GeoDNS decision. Unknown regions return 404.

• region=cn — cn — China vantage, executed by the China edge with mainland upstreams.
• region=us — us — overseas vantage, executed by the overseas edge with unfiltered upstreams.

Provenance

Every JSON answer carries the region, executing region, upstream that produced the answer, cache state (miss, fresh or stale) and latency. DoH exposes region, upstream and cache through X-LiteDNS-Region, X-LiteDNS-Upstream and X-LiteDNS-Cache.

region · exec_region · upstream · cache · latency_ms · rcode

Error codes

The JSON API uses native HTTP status codes for failures. DoH follows RFC 8484: valid DNS answers are always 2xx, while 4xx status codes indicate that no DNS answer was produced.

Client configuration

The DoH URL contains a path, which standard clients support. Use the full keyed URL from the console.

Agent skill

No authentication is required to read the skill document. Keep your API key out of shared logs.