开发者参考

版本控制与弃用

API 版本是路径的一部分，例如 /v1/status 。在同一版本内，现有请求会继续正常工作。本页说明哪些内容可能发生变化、你会获得多长的通知期，以及如何找出需要更新的请求。

版本控制与弃用

API 版本是路径的一部分，例如 /v1/status。在同一版本内，现有请求会继续正常工作。本页说明哪些内容可能发生变化、你会获得多长的通知期，以及如何找出需要更新的请求。

无需通知的变更

新的端点、可选参数、响应字段、现有选项列表中的新值、响应头和错误码可能随时添加。请让客户端忽略不认识的字段，并妥善处理新增的值。

破坏性变更

删除或重命名端点、参数或字段，或更改其含义，只会在至少提前 12 个月通知之后进行。在此期间，旧形式仍可继续使用，使用旧形式的请求的响应会带有 Deprecation 和 Sunset 请求头，并且该变更会列在更新日志中。

响应键命名

大多数响应键为 snake_case。若要让所有键都以 snake_case 返回，请添加 naming=snake 或发送 DomScan-Naming: snake 请求头。这是可选启用的功能，因此默认响应不会改变。参见snake_case 键。

已弃用的别名

以下旧参数目前仍可使用。每个参数至少会保持可用到其停用日期。请在此之前迁移到替代参数。

参数	端点	请改用	弃用日期	停用日期
`prefer_cache`	`GET /v1/status`	`max_age=2592000`	2026-10-10	2027-10-10
`skip_cache`	`GET /v1/status`	`max_age=0`	2026-10-10	2027-10-10
`cache_skip`	`GET /v1/status`	`max_age=0`	2026-10-10	2027-10-10
`cache-skip`	`GET /v1/status`	`max_age=0`	2026-10-10	2027-10-10
`options.prefer_cache` (JSON 请求体)	`POST /v1/status/bulk`	`max_age=2592000`	2026-10-10	2027-10-10
`prefer_cache` (JSON 请求体)	`POST /v1/status/bulk`	`max_age=2592000`	2026-10-10	2027-10-10
`options.skip_cache` (JSON 请求体)	`POST /v1/status/bulk`	`max_age=0`	2026-10-10	2027-10-10
`options.cache_skip` (JSON 请求体)	`POST /v1/status/bulk`	`max_age=0`	2026-10-10	2027-10-10
`options.cache-skip` (JSON 请求体)	`POST /v1/status/bulk`	`max_age=0`	2026-10-10	2027-10-10
`prefer_cache`	`GET /v1/subdomains`	`max_age=2592000`	2026-10-10	2027-10-10
`skip_cache`	`GET /v1/tech`	`max_age=0`	2026-10-10	2027-10-10
`skip_cache`	`GET /v1/categorize`	`max_age=0`	2026-10-10	2027-10-10
`skip_cache`	`GET /v1/identity-assets`	`max_age=0`	2026-10-10	2027-10-10
`skip_cache`	`GET /v1/identity-resolution`	`max_age=0`	2026-10-10	2027-10-10
`skip_cache`	`GET /v1/url-intelligence`	`max_age=0`	2026-10-10	2027-10-10
`skip_cache`	`GET /v1/agent-readiness`	`max_age=0`	2026-10-10	2027-10-10
`skip_cache`	`GET /v1/robots`	`max_age=0`	2026-10-10	2027-10-10
`refresh`	`GET /v1/ssl/deep-scan`	`max_age=0`	2026-10-10	2027-10-10
`cursor` (数值)	`GET /v1/certificates`	`cursor=<next_cursor>`	2026-10-10	2027-10-10
`offset`	`GET /v1/email/blacklist`	`cursor=<next_cursor>`	2026-10-10	2027-10-10

检测弃用

使用已弃用别名的请求会收到以下响应头。响应体保持不变。

Deprecation: 别名被弃用的日期，格式为 @ 后跟 Unix 秒数 (RFC 9745)。
Sunset: 别名最早可能停止工作的日期 (RFC 8594)。
Link: 指向本页的链接，带有 rel="deprecation"。

curl -i -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/status?name=example&tlds=com&skip_cache=true"

Deprecation: @1791590400
Sunset: Sun, 10 Oct 2027 00:00:00 GMT
Link: <https://domscan.net/docs/versioning#deprecated-aliases>; rel="deprecation"; type="text/html"

浏览器可以读取这三个请求头。请记录日志或针对 Deprecation 设置告警，以便在停用日期之前找出需要更新的代码。

每一项弃用也会在API 更新日志中公布。

客户支持

版本控制与弃用