{ "openapi": "3.0.3", "info": { "title": "IPTrace API", "version": "1.0.0", "description": "Public REST API of IPTrace.net — IP geolocation and risk, BGP / ASN topology, Whois, DNS, TCP probing and MMDB dataset downloads.\n\n## Authentication\n\nSend your API key as `Authorization: Bearer YOUR_API_KEY`. The legacy `?token=` query parameter still works but is deprecated (the key leaks into logs and browser history).\n\nEndpoints marked `x-auth: optional` also answer without a key, metered per source IP at 30 requests/minute, 1000 requests/day and a batch size of 5. Anonymous calls never spend credits.\n\n## Rate limits\n\nEvery response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (Unix timestamp). Exceeding a limit returns HTTP 429. The per-minute limit and the dataset download quota add `Retry-After` (seconds); an exhausted **daily** quota does not — wait until 00:00 server time.\n\n| Plan | Requests/min | Requests/day | Batch size | Monthly credits |\n| --- | --- | --- | --- | --- |\n| anonymous | 30 | 1000 | 5 | — |\n| free | 120 | 10000 | 10 | 1000 |\n| pro | 600 | 100000 | 100 | 50000 |\n| enterprise | 3000 | unlimited | 500 | 500000 |\n\n## Errors\n\nBusiness errors are returned in the body as `code` / `msg` while the HTTP status usually stays 200; only infrastructure failures (401 / 402 / 429) change the status. Always test for `code === 0`.\n\n| HTTP | code | Meaning |\n| --- | --- | --- |\n| 200 | 0 | Success |\n| 200 | 400 | Bad request: invalid target, missing parameter, batch over batch_limit, … |\n| 200 | 401 | Unauthenticated: this endpoint requires a valid API key (the HTTP status is still 200 — the error is in the body's code) |\n| 200 | 403 | Forbidden: plan too low (dataset download) or private/reserved target (tcping) |\n| 200 | 404 | Target not found or could not be resolved |\n| 402 | 402 | Not enough credits; credits_required in the body says how many this call needs |\n| 429 | 429 | Rate limited (per-minute, per-day or dataset quota). The per-minute and dataset limits send Retry-After; the daily quota does not — wait until 00:00 server time |\n| 504 | 504 | The probe node did not answer in time (node-relayed probes only) |", "contact": { "name": "IPTrace", "url": "https://iptrace.net/docs/api/", "email": "contact@iptrace.net" } }, "servers": [ { "url": "https://iptrace.net" } ], "tags": [ { "name": "Keyless endpoints", "description": "These three endpoints describe the caller's own egress IP. No API key, 60 requests/minute per source IP, CORS enabled (Access-Control-Allow-Origin: *), so they work straight from a browser or a shell.", "x-name-zh": "免鉴权快查" }, { "name": "IP lookup", "description": "Merges eight geolocation databases with the IPNetDB BGP table plus proxy / cloud detection. Callable anonymously (anonymous quota, no credits charged); with an API key it uses your plan quota and spends credits.", "x-name-zh": "IP 查询" }, { "name": "Whois & DNS", "description": "Registration data for domains, IP ranges and ASNs, plus authoritative DNS records.", "x-name-zh": "Whois 与 DNS" }, { "name": "Network probing", "description": "Active probes from our origin server or from a global probe node. An API key is required.", "x-name-zh": "网络探测" }, { "name": "BGP & ASN data", "description": "No API key, no credits — only a per-source-IP limit of 60 requests/minute. All of them send CORS headers except /api/rdns.", "x-name-zh": "BGP / ASN 数据" }, { "name": "Global DNS (DoH)", "description": "DoH queries carrying an EDNS Client Subnet, so you can see how one domain resolves from different regions. No key, 120 requests/minute per source IP.", "x-name-zh": "全球 DNS (DoH)" }, { "name": "Account", "description": "Inspect your own plan and usage. An API key is required, and these calls count against your rate limit like any other.", "x-name-zh": "账户" }, { "name": "Dataset downloads", "description": "Three MMDB database files. The /info endpoints are free and keyless; the downloads themselves are enterprise-only and metered per dataset at 5 per hour and 30 per day. Downloads cost no credits.", "x-name-zh": "数据集下载" } ], "paths": { "/api/ip": { "get": { "tags": [ "Keyless endpoints" ], "operationId": "my_ip", "summary": "Full lookup of your own IP", "description": "Same envelope and fields as GET /api/ip/{target} ({code, data}), with the caller's egress IP as the target.\n\n### Response fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `code` | integer | 0 means success; anything else is a business error code |\n| `data.ip` | string | The IP that was looked up |\n| `data.version` | integer | 4 or 6 |\n| `data.country` | string | Country name (localized by lang) |\n| `data.country_code` | string | ISO 3166-1 alpha-2 |\n| `data.region` | string | Region / state |\n| `data.city` | string | City |\n| `data.latitude / longitude` | number|null | Latitude / longitude |\n| `data.timezone` | string | IANA time zone |\n| `data.asn` | integer|null | Autonomous system number |\n| `data.org` | string | Registered organisation of the ASN |\n| `data.isp` | string | ISP name |\n| `data.as_domain` | string | Primary domain of the AS |\n| `data.continent / continent_code` | string | Continent |\n| `data.ip_type` | string | Usage label — filled only when the IP is flagged as a proxy |\n| `data.rdns` | string | Reverse DNS; always empty here because it is slow — use /api/rdns |\n| `data.location` | string | Pre-formatted location string, ready to display |\n| `data.is_reserved` | boolean | true for reserved / special-use ranges; the other fields are then empty |\n| `data.bgp.prefix` | string|null | BGP prefix announcing this IP |\n| `data.bgp.as` | integer|null | Origin AS |\n| `data.bgp.as_name` | string|null | Origin AS name |\n| `data.bgp.as_cc` | string|null | Origin AS registration country |\n| `data.bgp.allocation` | string|null | Parent block allocated by the RIR |\n| `data.bgp.allocation_cc` | string|null | Country the parent block is registered in |\n| `data.bgp.rpki_status` | string|null | RPKI validation: valid / invalid / unknown |\n| `data.bgp.peers` | array | Peer AS list |\n| `data.bgp.ix` | array | Internet exchanges |\n| `data.bgp.line` | string | Recognized carrier line (e.g. CN2 GIA); key absent when unknown |\n| `data.is_proxy` | boolean | Whether the IP is in the proxy / VPN database |\n| `data.proxy_type` | string | Proxy type: VPN / TOR / DCH / PUB / WEB / SES … |\n| `data.usage_type` | string | Usage class: COM / ORG / ISP / MOB / DCH … |\n| `data.proxy_domain` | string | Domain of the proxy service |\n| `data.proxy_isp` | string | ISP of the proxy service |\n| `data.threat` | string | Threat label |\n| `data.fraud_score` | string | Fraud score |\n| `data.last_seen` | string | Last time the proxy database saw this IP |\n| `data.provider` | string | Proxy service provider |\n| `data.is_cloud_idc` | boolean | Whether the IP belongs to a cloud provider or IDC |\n| `data.cloud_provider` | string | Cloud provider name |", "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } }, "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 0, "data": { "ip": "1.1.1.1", "version": 4, "country": "Australia", "country_code": "AU", "region": "New South Wales", "city": "Sydney", "latitude": -33.8688, "longitude": 151.209, "timezone": "Australia/Brisbane", "asn": 13335, "org": "CloudFlare Inc", "isp": "APNIC and CloudFlare DNS Resolver Project", "ip_type": "", "rdns": "", "as_domain": "cloudflare.com", "continent": "", "continent_code": "", "bgp": { "prefix": "1.1.1.0/24", "as": 13335, "as_name": "CLOUDFLARENET", "as_cc": "US", "allocation": "1.1.1.0/24", "allocation_cc": "AU", "rpki_status": "valid", "peers": [], "ix": [] }, "is_proxy": false, "proxy_type": "", "usage_type": "", "proxy_domain": "", "proxy_isp": "", "threat": "", "fraud_score": "", "last_seen": "", "provider": "", "location": "Australia New South Wales Sydney APNIC and CloudFlare DNS Resolver Project", "is_cloud_idc": true, "cloud_provider": "Cloud/IDC" } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-summary-zh": "本机 IP 完整信息", "x-description-zh": "返回结构与 GET /api/ip/{target} 完全一致（{code, data}），target 为调用方出口 IP。", "x-auth": "none", "x-rate-limit": "60 requests/minute per source IP", "parameters": [ { "name": "lang", "in": "query", "required": false, "description": "zh or en — language of country / region / ISP names, default zh", "schema": { "type": "string" }, "x-description-zh": "zh 或 en，控制国家/地区/ISP 的语言，默认 zh" } ], "security": [] } }, "/json": { "get": { "tags": [ "Keyless endpoints" ], "operationId": "my_json", "summary": "Flat geo payload for your own IP", "description": "Flat object with no {code,data} envelope — convenient for shell scripts. Equivalent to GET /?format=json.\n\n### Response fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `ip` | string | Egress IP address |\n| `country` | string | Country name (localized by lang) |\n| `country_code` | string | ISO 3166-1 alpha-2 country code |\n| `region` | string | Region / state |\n| `city` | string | City |\n| `isp` | string | ISP name |\n| `asn` | integer|null | Autonomous system number |\n| `org` | string | Registered organisation of the ASN |\n| `latitude` | number|null | Latitude |\n| `longitude` | number|null | Longitude |\n| `timezone` | string | IANA time zone |", "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } }, "content": { "application/json": { "schema": { "type": "object" }, "example": { "ip": "203.0.113.45", "country": "美国", "country_code": "US", "region": "California", "city": "San Francisco", "isp": "Cloudflare", "asn": 13335, "org": "CloudFlare Inc", "latitude": 37.7749, "longitude": -122.4194, "timezone": "America/Los_Angeles" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-summary-zh": "本机 IP 精简地理信息", "x-description-zh": "扁平结构、无 code 包装，方便 shell/脚本直接取值。等价写法：GET /?format=json。", "x-auth": "none", "x-rate-limit": "60 requests/minute per source IP", "parameters": [ { "name": "lang", "in": "query", "required": false, "description": "zh or en — language of country / region / ISP names, default zh", "schema": { "type": "string" }, "x-description-zh": "zh 或 en，控制国家/地区/ISP 的语言，默认 zh" } ], "security": [] } }, "/ip": { "get": { "tags": [ "Keyless endpoints" ], "operationId": "my_plain_ip", "summary": "Your IP as plain text", "description": "text/plain, a single IP plus a newline — made for $(curl -s https://iptrace.net/ip).", "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } }, "content": { "text/plain": { "schema": { "type": "string" }, "example": "203.0.113.45\n" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-summary-zh": "纯文本返回本机 IP", "x-description-zh": "text/plain，只有一行 IP 加换行，适合 $(curl -s https://iptrace.net/ip) 这样用。", "x-auth": "none", "x-rate-limit": "60 requests/minute per source IP", "security": [] } }, "/api/ip/{target}": { "get": { "tags": [ "IP lookup" ], "operationId": "ip_lookup", "summary": "Look up one IP or hostname", "description": "target may be an IPv4 address, an IPv6 address or a hostname; hostnames are resolved to an IP first.\n\n### Response fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `code` | integer | 0 means success; anything else is a business error code |\n| `data.ip` | string | The IP that was looked up |\n| `data.version` | integer | 4 or 6 |\n| `data.country` | string | Country name (localized by lang) |\n| `data.country_code` | string | ISO 3166-1 alpha-2 |\n| `data.region` | string | Region / state |\n| `data.city` | string | City |\n| `data.latitude / longitude` | number|null | Latitude / longitude |\n| `data.timezone` | string | IANA time zone |\n| `data.asn` | integer|null | Autonomous system number |\n| `data.org` | string | Registered organisation of the ASN |\n| `data.isp` | string | ISP name |\n| `data.as_domain` | string | Primary domain of the AS |\n| `data.continent / continent_code` | string | Continent |\n| `data.ip_type` | string | Usage label — filled only when the IP is flagged as a proxy |\n| `data.rdns` | string | Reverse DNS; always empty here because it is slow — use /api/rdns |\n| `data.location` | string | Pre-formatted location string, ready to display |\n| `data.is_reserved` | boolean | true for reserved / special-use ranges; the other fields are then empty |\n| `data.bgp.prefix` | string|null | BGP prefix announcing this IP |\n| `data.bgp.as` | integer|null | Origin AS |\n| `data.bgp.as_name` | string|null | Origin AS name |\n| `data.bgp.as_cc` | string|null | Origin AS registration country |\n| `data.bgp.allocation` | string|null | Parent block allocated by the RIR |\n| `data.bgp.allocation_cc` | string|null | Country the parent block is registered in |\n| `data.bgp.rpki_status` | string|null | RPKI validation: valid / invalid / unknown |\n| `data.bgp.peers` | array | Peer AS list |\n| `data.bgp.ix` | array | Internet exchanges |\n| `data.bgp.line` | string | Recognized carrier line (e.g. CN2 GIA); key absent when unknown |\n| `data.is_proxy` | boolean | Whether the IP is in the proxy / VPN database |\n| `data.proxy_type` | string | Proxy type: VPN / TOR / DCH / PUB / WEB / SES … |\n| `data.usage_type` | string | Usage class: COM / ORG / ISP / MOB / DCH … |\n| `data.proxy_domain` | string | Domain of the proxy service |\n| `data.proxy_isp` | string | ISP of the proxy service |\n| `data.threat` | string | Threat label |\n| `data.fraud_score` | string | Fraud score |\n| `data.last_seen` | string | Last time the proxy database saw this IP |\n| `data.provider` | string | Proxy service provider |\n| `data.is_cloud_idc` | boolean | Whether the IP belongs to a cloud provider or IDC |\n| `data.cloud_provider` | string | Cloud provider name |", "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } }, "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 0, "data": { "ip": "1.1.1.1", "version": 4, "country": "Australia", "country_code": "AU", "region": "New South Wales", "city": "Sydney", "latitude": -33.8688, "longitude": 151.209, "timezone": "Australia/Brisbane", "asn": 13335, "org": "CloudFlare Inc", "isp": "APNIC and CloudFlare DNS Resolver Project", "ip_type": "", "rdns": "", "as_domain": "cloudflare.com", "continent": "", "continent_code": "", "bgp": { "prefix": "1.1.1.0/24", "as": 13335, "as_name": "CLOUDFLARENET", "as_cc": "US", "allocation": "1.1.1.0/24", "allocation_cc": "AU", "rpki_status": "valid", "peers": [], "ix": [] }, "is_proxy": false, "proxy_type": "", "usage_type": "", "proxy_domain": "", "proxy_isp": "", "threat": "", "fraud_score": "", "last_seen": "", "provider": "", "location": "Australia New South Wales Sydney APNIC and CloudFlare DNS Resolver Project", "is_cloud_idc": true, "cloud_provider": "Cloud/IDC" } } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-summary-zh": "单个 IP / 域名查询", "x-description-zh": "target 可以是 IPv4、IPv6 或域名；域名会先解析成 IP 再查。", "x-auth": "optional", "x-rate-limit": "Per plan — see the rate limit table", "parameters": [ { "name": "target", "in": "path", "required": true, "description": "IPv4 / IPv6 / hostname, e.g. 1.1.1.1, 2606:4700::1111, example.com", "schema": { "type": "string" }, "x-description-zh": "IPv4 / IPv6 / 域名，例如 1.1.1.1、2606:4700::1111、example.com" }, { "name": "lang", "in": "query", "required": false, "description": "zh or en — language of country / region / ISP names, default zh", "schema": { "type": "string" }, "x-description-zh": "zh 或 en，控制国家/地区/ISP 的语言，默认 zh" } ], "x-credit-cost": 1, "security": [ [], { "bearerAuth": [] }, { "tokenQuery": [] } ] } }, "/api/ip/{target}/sources": { "get": { "tags": [ "IP lookup" ], "operationId": "ip_sources", "summary": "Multi-source comparison", "description": "Returns each geolocation database's own verdict for the IP without merging, so you can compare them side by side.\n\n### Response fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `data.ip` | string | Resolved IP address |\n| `data.sources[].source` | string | Database name (IPTrace / MaxMind / DB-IP / IP2Location / CZ88 / IPIP / Ip2region / IPinfo) |\n| `data.sources[].country` | string | Country according to that database |\n| `data.sources[].region` | string | Region according to that database |\n| `data.sources[].city` | string | City according to that database |\n| `data.sources[].lat` | number|null | Latitude |\n| `data.sources[].lng` | number|null | Longitude |\n| `data.sources[].isp` | string | ISP according to that database |", "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } }, "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 0, "data": { "ip": "1.1.1.1", "sources": [ { "source": "IPTrace", "country": "Australia", "region": "", "city": "", "lat": null, "lng": null, "isp": "APNIC and CloudFlare DNS Resolver Project" }, { "source": "MaxMind", "country": "Australia", "region": "", "city": "", "lat": null, "lng": null, "isp": "" }, { "source": "DB-IP", "country": "Australia", "region": "New South Wales", "city": "Sydney", "lat": -33.8688, "lng": 151.209, "isp": "" }, { "source": "IP2Location", "country": "Australia", "region": "Queensland", "city": "Brisbane", "lat": -27.467541, "lng": 153.028091, "isp": "APNIC and CloudFlare DNS Resolver Project" }, { "source": "IPinfo", "country": "Australia", "region": "", "city": "", "lat": null, "lng": null, "isp": "Cloudflare, Inc. (cloudflare.com)" } ] } } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-summary-zh": "多数据源对比", "x-description-zh": "不做合并，原样返回每个地理库对该 IP 的判断，便于比较各库差异。", "x-auth": "optional", "x-rate-limit": "Per plan — see the rate limit table", "parameters": [ { "name": "target", "in": "path", "required": true, "description": "IPv4 / IPv6 / hostname", "schema": { "type": "string" }, "x-description-zh": "IPv4 / IPv6 / 域名" } ], "x-credit-cost": 2, "security": [ [], { "bearerAuth": [] }, { "tokenQuery": [] } ] } }, "/api/ip/batch": { "post": { "tags": [ "IP lookup" ], "operationId": "ip_batch", "summary": "Batch IP lookup", "description": "Up to batch_limit targets per call (5 anonymously, see the plan table otherwise). The whole batch is billed once. An invalid target yields an error field on that entry only.\n\nNote: The successful entry above is abridged; the real response carries the full field set of /api/ip/{target}.\n\n### Response fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `data[]` | object | One entry per target; same fields as data in /api/ip/{target} |\n| `data[].error` | string | Present on failed entries only: invalid target, or resolution failed |", "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } }, "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 0, "data": [ { "ip": "1.1.1.1", "version": 4, "country": "澳大利亚", "country_code": "AU", "city": "Brisbane", "asn": 13335, "isp": "Cloudflare", "bgp": { "prefix": "1.1.1.0/24", "as": 13335, "as_name": "CLOUDFLARENET", "rpki_status": "valid" }, "is_proxy": false, "is_cloud_idc": true, "cloud_provider": "Cloud/IDC", "location": "澳大利亚 Queensland Brisbane Cloudflare" }, { "ip": "192.0.2.999", "error": "无效的IP地址或域名" } ] } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-summary-zh": "批量 IP 查询", "x-description-zh": "一次最多查 batch_limit 个目标（匿名 5 个，其余见套餐表）。整批只扣一次点数。单个目标非法时该条返回 error 字段，不影响其它条目。", "x-auth": "optional", "x-rate-limit": "Per plan — see the rate limit table", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ips" ], "properties": { "ips": { "type": "array", "items": { "type": "string" } } } }, "example": { "ips": [ "1.1.1.1", "example.com" ] } } } }, "x-credit-cost": 5, "security": [ [], { "bearerAuth": [] }, { "tokenQuery": [] } ] } }, "/api/whois/{target}": { "get": { "tags": [ "Whois & DNS" ], "operationId": "whois", "summary": "Whois / RDAP lookup", "description": "target accepts a domain, an IP, a CIDR prefix or ASxxxx. RDAP first, falling back to classic whois.\n\n### Response fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `data.target` | string | Echo of the query target |\n| `data.raw` | string | Raw whois / RDAP text |\n| `data.registrar` | string | Registrar |\n| `data.creation_date` | string | Creation date (ISO 8601) |\n| `data.expiry_date` | string | Expiry date (ISO 8601) |\n| `data.updated_date` | string | Last updated date |\n| `data.nameservers` | string[] | Name servers |\n| `data.status` | string[] | EPP status codes |\n| `data.registrant` | string | Registrant (usually redacted) |\n| `data.dnssec` | string | DNSSEC status |\n| `data.is_asn` | boolean | Whether the target is an ASN |\n| `data.available` | boolean | Whether the domain is unregistered |", "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } }, "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 0, "data": { "target": "cloudflare.com", "raw": "Domain Name: CLOUDFLARE.COM\nRegistry Domain ID: 1542998887_DOMAIN_COM-VRSN\nRegistrar WHOIS Server: whois.cloudflare.com\n...", "registrar": "Cloudflare, Inc.", "creation_date": "2009-02-17T22:07:54Z", "expiry_date": "2033-02-17T22:07:54Z", "updated_date": "2024-01-15T01:58:26Z", "nameservers": [ "ns3.cloudflare.com", "ns4.cloudflare.com", "ns5.cloudflare.com" ], "status": [ "clientdeleteprohibited", "clienttransferprohibited" ], "registrant": "DATA REDACTED", "dnssec": "signedDelegation", "is_asn": false, "available": false } } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-summary-zh": "Whois / RDAP 查询", "x-description-zh": "target 支持域名、IP、CIDR 前缀与 ASxxxx。优先走 RDAP，失败时回落到传统 whois。", "x-auth": "optional", "x-rate-limit": "Per plan — see the rate limit table", "parameters": [ { "name": "target", "in": "path", "required": true, "description": "Domain / IP / CIDR / ASxxxx, e.g. cloudflare.com, 1.1.1.1, AS13335", "schema": { "type": "string" }, "x-description-zh": "域名 / IP / CIDR / ASxxxx，例如 cloudflare.com、1.1.1.1、AS13335" } ], "x-credit-cost": 1, "security": [ [], { "bearerAuth": [] }, { "tokenQuery": [] } ] } }, "/api/dns/{domain}": { "get": { "tags": [ "Whois & DNS" ], "operationId": "dns_all", "summary": "All DNS records", "description": "Returns every resolvable record at once: A / AAAA / NS / MX / TXT / SOA / CNAME …\n\n### Response fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `data.domain` | string | Echo of the domain |\n| `data.records[].type` | string | Record type |\n| `data.records[].name` | string | Record name |\n| `data.records[].ttl` | integer | TTL in seconds |\n| `data.records[].value` | string | Record value |\n| `data.records[].priority` | integer | MX / SRV only |\n| `data.records[].serial|refresh|retry|expire|minimum_ttl` | integer | SOA only |", "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } }, "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 0, "data": { "domain": "example.com", "records": [ { "type": "A", "name": "example.com", "ttl": 8, "value": "104.20.23.154" }, { "type": "AAAA", "name": "example.com", "ttl": 68, "value": "2606:4700:10::ac42:93f3" }, { "type": "NS", "name": "example.com", "ttl": 55249, "value": "hera.ns.cloudflare.com" }, { "type": "TXT", "name": "example.com", "ttl": 157, "value": "v=spf1 -all" }, { "type": "SOA", "name": "example.com", "ttl": 1784, "value": "elliott.ns.cloudflare.com dns.cloudflare.com", "serial": 2413856909, "refresh": 10000, "retry": 2400, "expire": 604800, "minimum_ttl": 1800 } ] } } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-summary-zh": "查询全部 DNS 记录", "x-description-zh": "一次返回 A / AAAA / NS / MX / TXT / SOA / CNAME 等全部可解析记录。", "x-auth": "optional", "x-rate-limit": "Per plan — see the rate limit table", "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain name; only a-z A-Z 0-9 . - are accepted", "schema": { "type": "string" }, "x-description-zh": "域名，只允许 a-z A-Z 0-9 . -" } ], "x-credit-cost": 1, "security": [ [], { "bearerAuth": [] }, { "tokenQuery": [] } ] } }, "/api/dns/{domain}/{type}": { "get": { "tags": [ "Whois & DNS" ], "operationId": "dns_type", "summary": "DNS records of one type", "description": "Supported types: A, AAAA, CNAME, MX, NS, TXT, SOA, SRV, PTR (case-insensitive). An unsupported type returns code 400.\n\n### Response fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `data.records[]` | object | Record array with the fields above; empty when nothing resolves |\n| `data.query` | string | Echo of the domain |\n| `data.type` | string | Echo of the record type |\n| `data.server` | string | Resolver used (empty = system resolver) |", "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } }, "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 0, "data": { "records": [ { "type": "MX", "name": "google.com", "ttl": 176, "value": "smtp.google.com", "priority": 10 } ], "query": "google.com", "type": "MX", "server": "" } } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-summary-zh": "查询指定类型 DNS 记录", "x-description-zh": "支持的类型：A、AAAA、CNAME、MX、NS、TXT、SOA、SRV、PTR（大小写不敏感）。类型非法返回 code 400。", "x-auth": "optional", "x-rate-limit": "Per plan — see the rate limit table", "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain name", "schema": { "type": "string" }, "x-description-zh": "域名" }, { "name": "type", "in": "path", "required": true, "description": "A / AAAA / CNAME / MX / NS / TXT / SOA / SRV / PTR", "schema": { "type": "string" }, "x-description-zh": "A / AAAA / CNAME / MX / NS / TXT / SOA / SRV / PTR" } ], "x-credit-cost": 1, "security": [ [], { "bearerAuth": [] }, { "tokenQuery": [] } ] } }, "/api/tcping/{target}": { "get": { "tags": [ "Network probing" ], "operationId": "tcping", "summary": "TCP port reachability and latency", "description": "Synchronous, at most 10 attempts spaced 100 ms apart. target may be host, host:port or [ipv6]:port; ?port= works too. Private and reserved ranges are refused with code 403.\n\nWithout a valid API key this endpoint answers **HTTP 200** with `{\"code\": 401, \"msg\": \"...\"}` in the body — not HTTP 401.\n\nNote: With country or node set: code 404 plus an available_countries list when no node is online there, and code 504 when the node does not answer within 14 seconds.\n\n### Response fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `data.target` | string | Echo of the raw target |\n| `data.host` | string | Host part parsed out of the target |\n| `data.ip` | string | IP actually probed |\n| `data.port` | integer | Port actually probed |\n| `data.sent` | integer | Attempts sent |\n| `data.recv` | integer | Successful connects |\n| `data.loss` | number | Failure rate (%) |\n| `data.min|max|avg` | number|null | Min / max / average RTT in ms |\n| `data.rtts` | array | Per-attempt RTT; null for a failed attempt |\n| `data.timeout_ms` | integer | Timeout used (origin probes only) |\n| `data.source.type` | string | origin (our server) or node (probe node) |\n| `data.source.code|name|country_code|city` | string | Node identity when source.type is node |", "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } }, "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 0, "data": { "target": "1.1.1.1:443", "host": "1.1.1.1", "ip": "1.1.1.1", "port": 443, "sent": 4, "recv": 4, "loss": 0, "min": 1.412, "max": 2.038, "avg": 1.664, "rtts": [ 2.038, 1.55, 1.412, 1.656 ], "timeout_ms": 3000, "source": { "type": "origin" } } } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-summary-zh": "TCP 端口连通性与延迟", "x-description-zh": "同步返回，最多 10 次尝试，每次之间间隔 100ms。target 可写成 host、host:port 或 [ipv6]:port；也可用 ?port= 指定端口。禁止探测私有/保留地址（返回 code 403）。", "x-auth": "required", "x-rate-limit": "Per plan — see the rate limit table", "parameters": [ { "name": "target", "in": "path", "required": true, "description": "host, host:port or [ipv6]:port", "schema": { "type": "string" }, "x-description-zh": "host、host:port 或 [ipv6]:port" }, { "name": "port", "in": "query", "required": false, "description": "Port 1–65535, used when target carries none; defaults to 80", "schema": { "type": "integer" }, "x-description-zh": "端口 1–65535，target 里没带端口时使用；默认 80" }, { "name": "count", "in": "query", "required": false, "description": "Number of attempts, 1–10, default 4", "schema": { "type": "integer" }, "x-description-zh": "探测次数，1–10，默认 4" }, { "name": "timeout", "in": "query", "required": false, "description": "Per-attempt timeout in ms, 100–5000, default 3000", "schema": { "type": "integer" }, "x-description-zh": "单次超时毫秒数，100–5000，默认 3000" }, { "name": "country", "in": "query", "required": false, "description": "ISO 3166-1 alpha-2 — probe from a node in that country", "schema": { "type": "string" }, "x-description-zh": "ISO 3166-1 alpha-2，从该国家的检测节点发起" }, { "name": "node", "in": "query", "required": false, "description": "Exact node code; takes precedence over country", "schema": { "type": "string" }, "x-description-zh": "指定节点 code，优先于 country" } ], "x-credit-cost": "1 × count (count defaults to 4, clamped to 1–10). Node-relayed probes (country/node) always run 4 attempts and are billed as 4 credits.", "security": [ { "bearerAuth": [] }, { "tokenQuery": [] } ] } }, "/api/as-profile/{asn}": { "get": { "tags": [ "BGP & ASN data" ], "operationId": "as_profile", "summary": "AS profile", "description": "Registry data for the AS plus every prefix it originates. Returns code 404 for an unknown ASN.\n\n### Response fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `data.asn` | integer | Autonomous system number |\n| `data.name` | string | AS name |\n| `data.entity` | string | Registered entity |\n| `data.cc` | string | Registration country code |\n| `data.registry` | string | RIR (arin / ripe / apnic / lacnic / afrinic) |\n| `data.status` | string | Allocation status |\n| `data.in_use` | boolean | Whether it currently originates prefixes |\n| `data.private` | boolean | Whether it is a private ASN |\n| `data.ipv4_prefix_count` | integer | Number of IPv4 prefixes |\n| `data.ipv6_prefix_count` | integer | Number of IPv6 prefixes |\n| `data.ipv4_prefixes` | string[] | IPv4 prefix list |\n| `data.ipv6_prefixes` | string[] | IPv6 prefix list |", "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } }, "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 0, "data": { "asn": 13335, "name": "CLOUDFLARENET", "entity": "Cloudflare, Inc.", "cc": "US", "registry": "arin", "status": "assigned", "in_use": true, "private": false, "ipv4_prefix_count": 2367, "ipv6_prefix_count": 2898, "ipv4_prefixes": [ "1.1.1.0/24", "104.16.0.0/13", "162.158.0.0/15" ], "ipv6_prefixes": [ "2606:4700::/32", "2a06:98c0::/29" ] } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-summary-zh": "AS 网络概况", "x-description-zh": "返回该 AS 的注册信息与它所通告的全部前缀。ASN 不存在时返回 code 404。", "x-auth": "none", "x-rate-limit": "60 requests/minute per source IP", "parameters": [ { "name": "asn", "in": "path", "required": true, "description": "Autonomous system number, digits only (no AS prefix)", "schema": { "type": "integer" }, "x-description-zh": "自治域号，纯数字（不带 AS 前缀）" } ], "security": [] } }, "/api/as-topo/{asn}": { "get": { "tags": [ "BGP & ASN data" ], "operationId": "as_topo", "summary": "AS topology", "description": "Upstream / downstream / peer ASes ranked by observation strength (power). Returns code 404 when no topology data exists.\n\n### Response fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `data.asn` | integer | The ASN queried |\n| `data.upstreams[]` | object | Upstream ASes: {asn, power, name} |\n| `data.downstreams[]` | object | Downstream ASes: {asn, power, name} |\n| `data.peers[]` | object | Peer ASes: {asn, power, name} |", "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } }, "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 0, "data": { "asn": 13335, "upstreams": [ { "asn": 1299, "power": 8260, "name": "Arelion (Twelve99)" }, { "asn": 3257, "power": 5773, "name": "GTT Communications (AS3257)" }, { "asn": 3356, "power": 5473, "name": "Lumen AS3356" } ], "downstreams": [], "peers": [] } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-summary-zh": "AS 上下游拓扑", "x-description-zh": "按观测强度（power）排序的上游 / 下游 / 对等 AS 列表。数据不可用时返回 code 404。", "x-auth": "none", "x-rate-limit": "60 requests/minute per source IP", "parameters": [ { "name": "asn", "in": "path", "required": true, "description": "Autonomous system number", "schema": { "type": "integer" }, "x-description-zh": "自治域号" } ], "security": [] } }, "/api/prefix-upstreams": { "get": { "tags": [ "BGP & ASN data" ], "operationId": "prefix_upstreams", "summary": "Prefix-level upstreams", "description": "Upstreams observed for one specific prefix rather than the whole AS; count is how many paths showed that upstream.\n\n### Response fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `data.prefix` | string | Echo of the prefix |\n| `data.origin_as` | integer | Origin AS |\n| `data.upstreams[].asn` | integer | Upstream ASN |\n| `data.upstreams[].count` | integer | Number of observed paths |", "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } }, "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 0, "data": { "prefix": "1.1.1.0/24", "origin_as": 13335, "upstreams": [ { "asn": 24482, "count": 11 }, { "asn": 199524, "count": 8 }, { "asn": 1299, "count": 7 } ] } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-summary-zh": "前缀级上游 AS", "x-description-zh": "按具体前缀（而不是整个 AS）统计上游，count 是观测到该上游的路径条数。", "x-auth": "none", "x-rate-limit": "60 requests/minute per source IP", "parameters": [ { "name": "prefix", "in": "query", "required": true, "description": "CIDR prefix, e.g. 1.1.1.0/24", "schema": { "type": "string" }, "x-description-zh": "CIDR 前缀，例如 1.1.1.0/24" } ], "security": [] } }, "/api/peeringdb/search": { "get": { "tags": [ "BGP & ASN data" ], "operationId": "peeringdb_search", "summary": "PeeringDB search", "description": "Searches the local PeeringDB index for networks and facilities, capped at 20 hits. A query shorter than 2 characters returns code 400.\n\n### Response fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `data.nets[]` | object | Networks: {asn, name, aka, info_type} |\n| `data.facs[]` | object | Facilities: {id, name, city, country} |", "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } }, "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 0, "data": { "nets": [ { "asn": 13335, "name": "Cloudflare", "aka": "", "info_type": "Content" }, { "asn": 209242, "name": "Cloudflare London", "aka": "", "info_type": "" } ], "facs": [] } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-summary-zh": "PeeringDB 搜索", "x-description-zh": "在本地 PeeringDB 索引里搜网络与机房，最多 20 条。搜索词少于 2 个字符返回 code 400。", "x-auth": "none", "x-rate-limit": "60 requests/minute per source IP", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Query: ASN, network name or facility name; at least 2 characters", "schema": { "type": "string" }, "x-description-zh": "搜索词，ASN / 网络名 / 机房名，至少 2 个字符" } ], "security": [] } }, "/api/rdns": { "get": { "tags": [ "BGP & ASN data" ], "operationId": "rdns", "summary": "Batch reverse DNS (PTR)", "description": "Up to 40 public IPs per call. To keep blocking resolution off the worker, at most 6 uncached lookups run per call under a 3-second budget; the rest come back in pending for a follow-up call (by then usually cached). Private and reserved addresses are dropped.\n\nNote: This endpoint carries no CORS headers, so cross-site fetch from a browser is blocked (server-side calls are fine). Its body has no {code} envelope either.\n\n### Response fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `resolved` | object | IP → PTR hostname; an empty string means \"confirmed no PTR\", do not ask again |\n| `pending` | string[] | IPs not resolved this round; ask again shortly |", "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } }, "content": { "application/json": { "schema": { "type": "object" }, "example": { "resolved": { "1.1.1.1": "one.one.one.one", "8.8.8.8": "dns.google" }, "pending": [] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-summary-zh": "批量反向 DNS（PTR）", "x-description-zh": "一次最多 40 个公网 IP。为了不让同步解析拖住进程，单次最多真正发起 6 个未缓存查询、总预算 3 秒，没轮到的放进 pending，下一轮再问（那时通常已命中缓存）。私有/保留地址会被直接丢弃。", "x-auth": "none", "x-rate-limit": "60 requests/minute per source IP", "parameters": [ { "name": "ips", "in": "query", "required": true, "description": "Comma-separated IP list, at most 40", "schema": { "type": "string" }, "x-description-zh": "逗号分隔的 IP 列表，最多 40 个" } ], "security": [] } }, "/api/nodes": { "get": { "tags": [ "BGP & ASN data" ], "operationId": "nodes", "summary": "Online probe nodes", "description": "Lists currently online probe nodes; use the code field as the node parameter of /api/tcping.\n\n### Response fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `data[].code` | string | Node identifier, used as /api/tcping?node= |\n| `data[].name / name_en` | string | Node name (Chinese / English) |\n| `data[].country / country_code / province / city` | string | Node location |\n| `data[].isp` | string | ISP code |\n| `data[].ipv6` | integer | Whether IPv6 probing is supported (1/0) |\n| `data[].status` | integer | 1 = online |\n| `data[].last_seen` | string | Last heartbeat time |", "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } }, "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 0, "data": [ { "id": 30, "name": "示例节点", "name_en": "Sample Node", "code": "sample-node-01", "isp": "ct", "region": "华中", "country": "中国", "country_code": "CN", "province": "湖北", "city": "襄阳市", "ipv6": 0, "agent_version": "1.0.2", "status": 1, "last_seen": "2026-09-11 02:55:43" } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-summary-zh": "在线检测节点列表", "x-description-zh": "列出当前在线的检测节点，可用来给 /api/tcping 的 node 参数取值。", "x-auth": "none", "x-rate-limit": "60 requests/minute per source IP", "security": [] } }, "/dns_global/api/regions": { "get": { "tags": [ "Global DNS (DoH)" ], "operationId": "dns_regions", "summary": "Available regions", "description": "Returns the regions accepted by the region parameter as a bare array (no {code} envelope).\n\n### Response fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `[].code` | integer | Value to pass as region |\n| `[].label` | string | Region label (localized) |\n| `[].flag` | string | Country code for the flag |\n| `[].subnet` | string | EDNS Client Subnet actually sent |", "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } }, "content": { "application/json": { "schema": { "type": "object" }, "example": [ { "code": 0, "label": "中国 - 电信", "flag": "cn", "subnet": "218.30.118.0/24" }, { "code": 1, "label": "中国 - 联通", "flag": "cn", "subnet": "221.12.1.0/24" }, { "code": 3, "label": "中国 - 香港", "flag": "hk", "subnet": "203.218.0.0/24" } ] } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-summary-zh": "可选地区列表", "x-description-zh": "返回可用于 region 参数的地区数组（裸数组，没有 code 包装）。", "x-auth": "none", "x-rate-limit": "120 requests/minute per source IP", "security": [] } }, "/dns_global/api/query": { "get": { "tags": [ "Global DNS (DoH)" ], "operationId": "dns_global_query", "summary": "Query DNS from a region", "description": "A and AAAA answers are enriched with geolocation for each IP. The body is a bare object with no {code} envelope; failures carry an error field.\n\n### Response fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `records[]` | object | {name, type, ttl, value}; A and AAAA also carry geo / isp / asn / org |\n| `rcode` | string | DNS response code, e.g. NOERROR / NXDOMAIN |\n| `time_ms` | integer | Resolution time in ms |\n| `resolver` | string | Resolver actually used |\n| `edns_client_subnet` | string | ECS that was sent |\n| `colo / country / location` | string | Resolver PoP information (present on the worker path) |\n| `source` | string | worker or doh — which path answered |\n| `region / regionLabel / subnet` | mixed | Echo of the requested region |\n| `error` | string | Present only on failure |", "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } }, "content": { "application/json": { "schema": { "type": "object" }, "example": { "records": [ { "name": "example.com", "type": "A", "ttl": 36, "value": "104.20.23.154", "geo": "美国 California San Francisco Cloudflare", "isp": "Cloudflare", "asn": 13335, "org": "CloudFlare Inc" } ], "rcode": "NOERROR", "time_ms": 1, "resolver": "cloudflare", "edns_client_subnet": "218.30.118.0/24", "colo": "CDG", "country": "FR", "location": "Lauterbourg, Grand Est, FR", "source": "worker", "region": 0, "regionLabel": "中国 - 电信", "subnet": "218.30.118.0/24" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-summary-zh": "按地区查询 DNS", "x-description-zh": "A / AAAA 结果会额外附带 IP 的归属地信息。返回体是裸对象，没有 code 包装；出错时带 error 字段。", "x-auth": "none", "x-rate-limit": "120 requests/minute per source IP", "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Domain name", "schema": { "type": "string" }, "x-description-zh": "域名" }, { "name": "type", "in": "query", "required": false, "description": "Record type, default A; an unknown type falls back to A", "schema": { "type": "string" }, "x-description-zh": "记录类型，默认 A；不认识的类型会退回 A" }, { "name": "provider", "in": "query", "required": false, "description": "Resolver index 0–13: 0=google 1=cloudflare 2=alidns 3=dnspod 4=adguard 5=nextdns 6=dns.sb 7=360 8=wikimedia 9=iij 10=cleanbrowsing 11=controld 12=surfshark 13=stormycloud; default 0", "schema": { "type": "integer" }, "x-description-zh": "解析器序号 0–13：0=google 1=cloudflare 2=alidns 3=dnspod 4=adguard 5=nextdns 6=dns.sb 7=360 8=wikimedia 9=iij 10=cleanbrowsing 11=controld 12=surfshark 13=stormycloud；默认 0" }, { "name": "region", "in": "query", "required": false, "description": "Region index from /dns_global/api/regions", "schema": { "type": "integer" }, "x-description-zh": "地区序号，取自 /dns_global/api/regions" } ], "security": [] } }, "/api/user/me": { "get": { "tags": [ "Account" ], "operationId": "user_me", "summary": "Current account", "description": "Returns the account behind the API key and the limits currently in effect.\n\nWithout a valid API key this endpoint answers **HTTP 200** with `{\"code\": 401, \"msg\": \"...\"}` in the body — not HTTP 401.\n\n### Response fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `data.id` | integer | User ID |\n| `data.email` | string | Email address |\n| `data.nickname` | string | Nickname |\n| `data.plan` | string | Plan name |\n| `data.rate_limit` | integer | Requests per minute |\n| `data.daily_limit` | integer | Requests per day, 0 = unlimited |\n| `data.batch_limit` | integer | Targets per batch call |", "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } }, "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 0, "data": { "id": 1024, "email": "you@example.com", "nickname": "example", "plan": "专业版", "rate_limit": 600, "daily_limit": 100000, "batch_limit": 100 } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-summary-zh": "当前账户信息", "x-description-zh": "返回 API Key 对应的账户与生效中的限额。", "x-auth": "required", "x-rate-limit": "Per plan — see the rate limit table", "security": [ { "bearerAuth": [] }, { "tokenQuery": [] } ] } }, "/api/user/usage": { "get": { "tags": [ "Account" ], "operationId": "user_usage", "summary": "Usage statistics", "description": "Today's call count, the 30-day total and a per-day breakdown (daily always has 30 entries; days with no calls are zero-filled).\n\nWithout a valid API key this endpoint answers **HTTP 200** with `{\"code\": 401, \"msg\": \"...\"}` in the body — not HTTP 401.\n\nNote: Only successful calls are counted: a request ApiAuth judges failed (HTTP ≥ 400, or code ≠ 0 in the JSON body) is neither counted nor billed, and its daily-quota slot is released.\n\n### Response fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `data.today` | integer | Successful calls today |\n| `data.month_total` | integer | Total over the last 30 days |\n| `data.daily_limit` | integer | Daily cap, 0 = unlimited |\n| `data.daily[]` | object | {date, count} — 30 entries in ascending date order |", "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } }, "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 0, "data": { "today": 128, "month_total": 4213, "daily_limit": 100000, "daily": [ { "date": "2026-08-13", "count": 96 }, { "date": "2026-08-14", "count": 210 }, { "date": "2026-09-11", "count": 128 } ] } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-summary-zh": "用量统计", "x-description-zh": "今日调用数、近 30 天合计与逐日明细（daily 固定 30 条，无调用的日期补 0）。", "x-auth": "required", "x-rate-limit": "Per plan — see the rate limit table", "security": [ { "bearerAuth": [] }, { "tokenQuery": [] } ] } }, "/api/datasets/{dataset}/info": { "get": { "tags": [ "Dataset downloads" ], "operationId": "dataset_info", "summary": "Dataset metadata", "description": "dataset is one of mmdb (geolocation, ~120 MB), asn (~10 MB) or isp (~140 MB). Compare sha256 before re-downloading — it saves a whole day of quota.\n\n### Response fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `data.filename` | string | File name |\n| `data.format` | string | Always mmdb |\n| `data.size` | integer | Size in bytes |\n| `data.mtime / mtime_iso` | mixed | File modification time |\n| `data.sha256` | string | SHA-256 of the file |\n| `data.build_epoch / build_iso` | mixed | MMDB build time |\n| `data.node_count` | integer | MMDB node count |\n| `data.ip_version` | integer | 4 or 6 |\n| `data.languages` | string[] | Languages present in the database |", "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } }, "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 0, "data": { "filename": "merged_geoip2_ccpa.mmdb", "format": "mmdb", "size": 126352313, "mtime": 1778358197, "mtime_iso": "2026-05-09T20:23:17Z", "sha256": "fa22f93e2ce790b5da8a626c7fd3ac0c45c064a7da73b22b1a1e1018195a89ab", "build_epoch": 1778357692, "build_iso": "2026-05-09T20:14:52Z", "node_count": 11780233, "ip_version": 6, "languages": [ "de", "en", "es", "fr", "ja", "pt-BR", "ru", "zh-CN" ] } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-summary-zh": "数据集元信息", "x-description-zh": "dataset 取 mmdb（地理库，约 120 MB）、asn（约 10 MB）或 isp（约 140 MB）。先比对 sha256 再决定要不要重新下载，可以省掉整天的配额。", "x-auth": "none", "x-rate-limit": "Per plan — see the rate limit table", "parameters": [ { "name": "dataset", "in": "path", "required": true, "description": "mmdb / asn / isp", "schema": { "type": "string" }, "x-description-zh": "mmdb / asn / isp" } ], "x-credit-cost": 0, "security": [] } }, "/api/datasets/{dataset}": { "get": { "tags": [ "Dataset downloads" ], "operationId": "dataset_download", "summary": "Download a dataset (enterprise)", "description": "On success the body is the raw file (application/octet-stream), not JSON. Non-enterprise plans get code 403; exceeding the meter gives HTTP 429.\n\nWithout a valid API key this endpoint answers **HTTP 200** with `{\"code\": 401, \"msg\": \"...\"}` in the body — not HTTP 401.\n\nNote: Over the meter you get HTTP 429 with Retry-After and a body of {\"code\":429,\"msg\":\"…\",\"limit\":N,\"reset_at\":…,\"reset_iso\":\"…\"}.\n\n### Response fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `X-Dataset-Hourly-Limit / X-Dataset-Hourly-Used` | header | Hourly quota and usage |\n| `X-Dataset-Daily-Limit / X-Dataset-Daily-Used` | header | Daily quota and usage |\n| `Content-Disposition` | header | attachment; filename=\"…mmdb\" |", "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } }, "content": { "text/plain": { "schema": { "type": "string" }, "example": "HTTP/1.1 200 OK\nContent-Type: application/octet-stream\nContent-Disposition: attachment; filename=\"merged_geoip2_ccpa.mmdb\"\nX-Dataset-Hourly-Limit: 5\nX-Dataset-Hourly-Used: 1\nX-Dataset-Daily-Limit: 30\nX-Dataset-Daily-Used: 1\n\n" } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-summary-zh": "下载数据集（企业版）", "x-description-zh": "成功时直接返回二进制文件流（application/octet-stream），不是 JSON。非企业版返回 code 403；超限返回 HTTP 429。", "x-auth": "required", "x-rate-limit": "5/hour + 30/day, counted per dataset", "parameters": [ { "name": "dataset", "in": "path", "required": true, "description": "mmdb / asn / isp", "schema": { "type": "string" }, "x-description-zh": "mmdb / asn / isp" } ], "x-credit-cost": "No credits, but metered per dataset at 5/hour and 30/day — an aborted download still counts.", "x-required-plan": "enterprise", "security": [ { "bearerAuth": [] }, { "tokenQuery": [] } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Recommended. Send the API key as `Authorization: Bearer YOUR_API_KEY`." }, "tokenQuery": { "type": "apiKey", "in": "query", "name": "token", "description": "Deprecated. Kept for legacy clients only — the key ends up in server logs and browser history." } }, "responses": { "PaymentRequired": { "description": "Not enough credits; `credits_required` says how many this call needs.", "content": { "application/json": { "example": { "code": 402, "msg": "点数不足，请充值后继续使用", "credits_required": 1 } } } }, "TooManyRequests": { "description": "Rate limited (per-minute, per-day or dataset quota).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying. Sent for the per-minute limit and the dataset quota; absent when the daily quota is exhausted (wait until 00:00 server time)." } }, "content": { "application/json": { "example": { "code": 429, "msg": "请求频率超限" } } } } } } }