API 参考
idcd 全球网络诊断 API 完整参考文档。服务端 Origin: https://api-prod.idcd.com;下列端点路径已包含 /v1版本前缀。
Authorization: Bearer <token> 。应用 API Key 格式为 sk_live_xxx,个人访问令牌格式为 idcd_pat_xxx;不支持 X-API-Key。不需要鉴权的端点标记为 Core API Key 仅用于服务器到服务器调用,不要写入浏览器或移动应用代码。 MCP token 只能访问 MCP 入口,不能替代 Core API Key。可在 设置 → API Keys 创建 production key。
https://api-prod.idcd.com; 请直接拼接下方以 /v1 开头的端点路径。拨测
多节点 HTTP / Ping / DNS / TCP / Traceroute 拨测
POST/v1/probe/http— HTTP 拨测公开
创建异步 HTTP/HTTPS 拨测任务;使用返回的 task_id 轮询任务结果。
参数
| 名称 | 位置 | 类型 | 必填 | 描述 |
|---|---|---|---|---|
target | body | string | 是 | 目标 URL(示例:https://github.com) |
node_ids | body | string[] | 否 | 固定节点 ID 列表,省略时自动选择 |
params.method | body | string | 否 | HTTP 方法,默认 GET(示例:GET) |
params.timeout_ms | body | integer | 否 | 超时毫秒数,1000–30000(示例:10000) |
响应示例
{
"data": {
"task_id": "pt_01J8XXXXX",
"task_ids": [
"pt_01J8XXXXX"
],
"status": "queued"
},
"request_id": "req_01J8XXXXX"
}POST/v1/probe/ping— ICMP Ping公开
创建异步 ICMP Ping 拨测任务;使用 task_id 轮询往返延迟和丢包结果。
参数
| 名称 | 位置 | 类型 | 必填 | 描述 |
|---|---|---|---|---|
target | body | string | 是 | 目标主机名或 IP(示例:8.8.8.8) |
node_ids | body | string[] | 否 | 固定节点 ID 列表,省略时自动选择 |
params.count | body | integer | 否 | 发包数量,默认 4,最大 50 |
params.timeout_ms | body | integer | 否 | 超时毫秒数,默认 5000 |
响应示例
{
"data": {
"task_id": "pt_01J8XXXXX",
"task_ids": [
"pt_01J8XXXXX"
],
"status": "queued"
},
"request_id": "req_01J8XXXXX"
}POST/v1/probe/dns— DNS 解析拨测公开
创建异步 DNS 拨测任务;DNS 类型参数放在 params 对象中。
参数
| 名称 | 位置 | 类型 | 必填 | 描述 |
|---|---|---|---|---|
target | body | string | 是 | 目标域名(示例:github.com) |
node_ids | body | string[] | 否 | 固定节点 ID 列表,省略时自动选择 |
params.record_type | body | string | 否 | 记录类型 A/AAAA/MX/TXT/NS/CNAME/SOA(示例:A) |
params.server | body | string | 否 | 自定义 DNS 服务器(示例:8.8.8.8) |
响应示例
{
"data": {
"task_id": "pt_01J8XXXXX",
"task_ids": [
"pt_01J8XXXXX"
],
"status": "queued"
},
"request_id": "req_01J8XXXXX"
}POST/v1/probe/tcp— TCPing 拨测公开
创建异步 TCP 连接拨测任务;端口可写在 target 或 params.port。
参数
| 名称 | 位置 | 类型 | 必填 | 描述 |
|---|---|---|---|---|
target | body | string | 是 | 目标 host:port,或仅 host 并设置 params.port(示例:github.com:443) |
node_ids | body | string[] | 否 | 固定节点 ID 列表,省略时自动选择 |
params.port | body | integer | 否 | 目标端口 (1–65535) |
params.timeout_ms | body | integer | 否 | 超时毫秒数,默认 5000 |
响应示例
{
"data": {
"task_id": "pt_01J8XXXXX",
"task_ids": [
"pt_01J8XXXXX"
],
"status": "queued"
},
"request_id": "req_01J8XXXXX"
}POST/v1/probe/traceroute— Traceroute 路由追踪公开
创建异步 Traceroute 拨测任务;使用 task_id 轮询每跳 IP 和延迟。
参数
| 名称 | 位置 | 类型 | 必填 | 描述 |
|---|---|---|---|---|
target | body | string | 是 | 目标主机名或 IP(示例:github.com) |
node_ids | body | string[] | 否 | 固定节点 ID 列表,省略时自动选择 |
params.max_hops | body | integer | 否 | 最大跳数,默认 30 |
响应示例
{
"data": {
"task_id": "pt_01J8XXXXX",
"task_ids": [
"pt_01J8XXXXX"
],
"status": "queued"
},
"request_id": "req_01J8XXXXX"
}网络信息
IP / WHOIS / SSL / DNS 记录 / ICP 备案查询
GET/v1/info/ip— IP 信息查询公开
查询指定 IP 地址的归属地、ASN、运营商等信息。参数名必须为 q。
参数
| 名称 | 位置 | 类型 | 必填 | 描述 |
|---|---|---|---|---|
q | query | string | 是 | 要查询的 IPv4 或 IPv6(示例:8.8.8.8) |
响应示例
{
"data": {
"ip": "8.8.8.8",
"country": "US",
"country_name": "美国",
"isp": "Google LLC",
"asn": "AS15169"
},
"request_id": "req_01J8XXXXX"
}GET/v1/info/whois— WHOIS 查询公开
查询域名或 IP 的 WHOIS 注册信息。
参数
| 名称 | 位置 | 类型 | 必填 | 描述 |
|---|---|---|---|---|
q | query | string | 是 | 查询目标(域名或 IP)(示例:github.com) |
响应示例
{
"data": {
"domain": "github.com",
"registrar": "MarkMonitor Inc.",
"expires_at": "2026-10-09",
"name_servers": [
"ns1.github.com",
"ns2.github.com"
]
},
"request_id": "req_01J8XXXXX"
}GET/v1/info/ssl— SSL/TLS 证书深审公开
查询域名的 SSL/TLS 证书并做深度审计:完整证书链、TLS 1.0–1.3 协议矩阵、OCSP 吊销状态、内嵌 SCT 计数、弱算法/到期/域名不匹配等分级告警,以及 ssllabs 式简评。
参数
| 名称 | 位置 | 类型 | 必填 | 描述 |
|---|---|---|---|---|
q | query | string | 是 | 要查询的域名(裸域名,不含 https://)(示例:github.com) |
响应示例
{
"data": {
"domain": "github.com",
"issuer": "Sectigo Limited",
"subject": "github.com",
"not_before": "2025-03-07T00:00:00Z",
"not_after": "2026-03-14T00:00:00Z",
"san_domains": [
"github.com",
"www.github.com"
],
"protocol": "TLS 1.3",
"days_until_expiry": 305,
"valid": true,
"grade": "A",
"cipher_suite": "TLS_AES_128_GCM_SHA256",
"ocsp_status": "good",
"sct_count": 2,
"tls_versions": [
{
"version": "TLS 1.0",
"supported": false
},
{
"version": "TLS 1.1",
"supported": false
},
{
"version": "TLS 1.2",
"supported": true
},
{
"version": "TLS 1.3",
"supported": true
}
],
"warnings": [],
"chain": [
{
"subject": "CN=github.com",
"issuer": "CN=Sectigo ECC ...",
"not_before": "2025-03-07T00:00:00Z",
"not_after": "2026-03-14T00:00:00Z",
"signature_algorithm": "ECDSA-SHA256",
"public_key_algorithm": "ECDSA",
"public_key_bits": 256,
"serial_number": "0a1b2c",
"fingerprint_sha256": "…",
"is_ca": false
}
]
},
"request_id": "req_01J8XXXXX"
}GET/v1/info/dns— DNS 记录查询公开
查询域名的各类 DNS 记录(A/AAAA/MX/TXT/NS/CNAME/SOA)。
参数
| 名称 | 位置 | 类型 | 必填 | 描述 |
|---|---|---|---|---|
q | query | string | 是 | 要查询的域名(示例:github.com) |
type | query | string | 否 | 记录类型,留空返回所有类型(示例:A) |
响应示例
{
"data": {
"domain": "github.com",
"records": [
{
"type": "A",
"value": "140.82.114.4",
"ttl": 60
}
]
},
"request_id": "req_01J8XXXXX"
}GET/v1/info/icp— ICP 备案查询公开
查询域名的 ICP 备案信息(中国大陆)。
参数
| 名称 | 位置 | 类型 | 必填 | 描述 |
|---|---|---|---|---|
q | query | string | 是 | 要查询的域名(示例:baidu.com) |
响应示例
{
"data": {
"domain": "baidu.com",
"icp_number": "京ICP证030173号",
"company": "北京百度网讯科技有限公司",
"license_type": "经营性ICP许可证"
},
"request_id": "req_01J8XXXXX"
}IP 信誉 / 风险
IP 风险评分与类型标签数据 API(代理 / VPN / 数据中心 / Tor)
GET/v1/ip/reputation— IP 信誉 / 风险查询公开
返回 IP 的 0–100 风险评分、风险等级、类型标签(proxy / vpn / hosting / tor / residential)及判定证据。匿名调用按 IP 限流(防批量刷库);携带 API Key 调用计入账户 API 配额与按量计费,并按 Key 限速。
参数
| 名称 | 位置 | 类型 | 必填 | 描述 |
|---|---|---|---|---|
q | query | string | 是 | 要查询的 IPv4/IPv6 或域名(示例:1.1.1.1) |
响应示例
{
"data": {
"ip": "185.220.101.1",
"score": 80,
"risk_level": "high",
"types": [
"tor",
"hosting"
],
"evidence": [
{
"signal": "tor_exit",
"description": "IP is a known Tor exit node",
"weight": 60
},
{
"signal": "hosting",
"description": "IP belongs to a datacenter / hosting / cloud network",
"weight": 20
}
],
"country": "Germany",
"asn": "AS24940 Hetzner",
"isp": "Hetzner Online GmbH"
},
"request_id": "req_01J8XXXXX"
}账号
注册 / 登录 / 个人资料 / API Key 管理
POST/v1/auth/register— 用户注册公开
注册新用户账号,注册后发送验证邮件。
参数
| 名称 | 位置 | 类型 | 必填 | 描述 |
|---|---|---|---|---|
email | body | string | 是 | 邮箱地址(示例:user@example.com) |
password | body | string | 是 | 密码,最少 8 位 |
响应示例
{
"data": {
"access_token": "eyJhbGciOiJIUzI1...",
"token_type": "Bearer",
"expires_in": 900
},
"request_id": "req_01J8XXXXX"
}POST/v1/auth/login— 用户登录公开
使用邮箱和密码登录,返回 JWT access token(有效期 15 分钟)。
参数
| 名称 | 位置 | 类型 | 必填 | 描述 |
|---|---|---|---|---|
email | body | string | 是 | 邮箱地址(示例:user@example.com) |
password | body | string | 是 | 密码 |
响应示例
{
"data": {
"access_token": "eyJhbGciOiJIUzI1...",
"token_type": "Bearer",
"expires_in": 900
},
"request_id": "req_01J8XXXXX"
}POST/v1/auth/logout— 用户登出需要鉴权
吊销当前 session token。
响应示例
{
"data": null,
"request_id": "req_01J8XXXXX"
}GET/v1/account/profile— 获取用户资料需要鉴权
获取当前登录用户的真实资料。未绑定的邮箱/手机号为空字符串,手机号始终脱敏;订阅方案请使用 billing API。
响应示例
{
"data": {
"id": "u_01J8XXXXX",
"email": "user@example.com",
"email_verified": true,
"phone": "+8613****8000",
"phone_verified": true,
"has_password": true,
"display_name": "张三",
"avatar_url": null,
"bio": null,
"locale": "cn",
"timezone": "Asia/Shanghai",
"theme": "system",
"status": "active"
},
"request_id": "req_01J8XXXXX"
}PATCH/v1/account/profile— 更新用户资料需要鉴权
仅更新显示名称、简介、语言、IANA 时区和主题。省略字段表示保持不变;display_name/bio 传 null 或空白字符串表示清空。未知字段返回 400。
参数
| 名称 | 位置 | 类型 | 必填 | 描述 |
|---|---|---|---|---|
display_name | body | string | null | 否 | 显示名称,最大 64 个 Unicode 字符;null/空白清空 |
bio | body | string | null | 否 | 个人简介,最大 500 个 Unicode 字符;null/空白清空 |
locale | body | cn | en | tw | 否 | 公开 wire 语言码 |
timezone | body | string | 否 | 有效 IANA 时区,如 Asia/Shanghai |
theme | body | system | light | dark | 否 | 主题偏好 |
响应示例
{
"data": {
"id": "u_01J8XXXXX",
"email": "user@example.com",
"email_verified": true,
"phone": "+8613****8000",
"phone_verified": true,
"has_password": true,
"display_name": "李四",
"avatar_url": null,
"bio": null,
"locale": "cn",
"timezone": "Asia/Shanghai",
"theme": "system",
"status": "active"
},
"request_id": "req_01J8XXXXX"
}GET/v1/account/api-keys— 获取 API Key 列表需要鉴权
获取当前用户的所有 API Key(不含完整密钥)。
响应示例
{
"data": {
"api_keys": [
{
"id": "key_01J8XXXXX",
"name": "生产环境",
"key_prefix": "sk_live_xxx...",
"scopes": [
"read"
]
}
],
"total": 1,
"limit": 20,
"offset": 0
},
"request_id": "req_01J8XXXXX"
}POST/v1/account/api-keys— 创建 API Key需要鉴权
创建新的 API Key。完整密钥仅在创建时返回一次,请妥善保管。
参数
| 名称 | 位置 | 类型 | 必填 | 描述 |
|---|---|---|---|---|
name | body | string | 是 | API Key 名称(便于识别)(示例:生产环境) |
scopes | body | string[] | 否 | read / write;省略或传空数组会授予 read + write,合作方只读密钥必须显式传 ["read"] |
expires_days | body | integer | 否 | 有效期 1–90 天,默认 90 |
响应示例
{
"data": {
"id": "key_01J8XXXXX",
"name": "生产环境",
"key": "sk_live_01J8XXXXXXXXXXX"
},
"request_id": "req_01J8XXXXX"
}监控
监控项创建 / 查询 / 更新 / 删除 / 暂停 / 恢复
GET/v1/monitors— 获取监控列表需要鉴权
获取当前用户的所有监控项,支持分页。
参数
| 名称 | 位置 | 类型 | 必填 | 描述 |
|---|---|---|---|---|
page | query | integer | 否 | 页码,默认 1 |
limit | query | integer | 否 | 每页条数,默认 20,最大 100 |
响应示例
{
"data": {
"items": [
{
"id": "m_01J8XXXXX",
"name": "GitHub 主页",
"type": "http",
"target": "https://github.com",
"status": "active",
"interval_s": 60
}
],
"total": 1,
"page": 1,
"limit": 20
},
"request_id": "req_01J8XXXXX"
}POST/v1/monitors— 创建监控需要鉴权
创建新的监控项。
参数
| 名称 | 位置 | 类型 | 必填 | 描述 |
|---|---|---|---|---|
name | body | string | 是 | 监控名称(示例:GitHub 主页) |
type | body | string | 是 | 监控类型 http/ping/tcp/dns/traceroute(示例:http) |
target | body | string | 是 | 拨测目标(示例:https://github.com) |
config | body | object | 否 | 类型特定参数,例如 method / expected_status |
interval_s | body | integer | 否 | 拨测间隔(秒);省略时使用服务端策略默认值 |
响应示例
{
"data": {
"id": "m_01J8XXXXX",
"name": "GitHub 主页",
"type": "http",
"target": "https://github.com",
"status": "active",
"interval_s": 60
},
"request_id": "req_01J8XXXXX"
}GET/v1/monitors/{id}— 获取监控详情需要鉴权
获取指定监控项的详细信息。
参数
| 名称 | 位置 | 类型 | 必填 | 描述 |
|---|---|---|---|---|
id | path | string | 是 | 监控 ID(示例:mon_01J8XXXXX) |
响应示例
{
"data": {
"id": "m_01J8XXXXX",
"name": "GitHub 主页",
"type": "http",
"target": "https://github.com",
"status": "active",
"interval_s": 60
},
"request_id": "req_01J8XXXXX"
}PATCH/v1/monitors/{id}— 更新监控需要鉴权
更新指定监控项的配置(名称、间隔等)。
参数
| 名称 | 位置 | 类型 | 必填 | 描述 |
|---|---|---|---|---|
id | path | string | 是 | 监控 ID |
name | body | string | 否 | 新名称 |
interval_s | body | integer | 否 | 新拨测间隔(秒) |
响应示例
{
"data": {
"id": "m_01J8XXXXX",
"name": "新名称",
"interval_s": 120
},
"request_id": "req_01J8XXXXX"
}DELETE/v1/monitors/{id}— 删除监控需要鉴权
删除指定监控项(不可恢复)。
参数
| 名称 | 位置 | 类型 | 必填 | 描述 |
|---|---|---|---|---|
id | path | string | 是 | 监控 ID |
响应示例
{
"data": null,
"request_id": "req_01J8XXXXX"
}POST/v1/monitors/{id}/pause— 暂停监控需要鉴权
暂停指定监控项的拨测任务。
参数
| 名称 | 位置 | 类型 | 必填 | 描述 |
|---|---|---|---|---|
id | path | string | 是 | 监控 ID |
响应示例
{
"data": {
"id": "mon_01J8XXXXX",
"status": "paused"
},
"request_id": "req_01J8XXXXX"
}POST/v1/monitors/{id}/resume— 恢复监控需要鉴权
恢复已暂停的监控项。
参数
| 名称 | 位置 | 类型 | 必填 | 描述 |
|---|---|---|---|---|
id | path | string | 是 | 监控 ID |
响应示例
{
"data": {
"id": "mon_01J8XXXXX",
"status": "active"
},
"request_id": "req_01J8XXXXX"
}告警
告警通道 / 策略 / 事件管理
GET/v1/alert-channels— 获取告警通道列表需要鉴权
获取当前用户配置的所有告警通道。
响应示例
{
"data": {
"items": [
{
"id": "ch_01J8XXXXX",
"name": "邮件通知",
"type": "email"
}
]
},
"request_id": "req_01J8XXXXX"
}POST/v1/alert-channels— 创建告警通道需要鉴权
创建新的告警通道(邮件/Webhook/企微/钉钉/飞书等)。
参数
| 名称 | 位置 | 类型 | 必填 | 描述 |
|---|---|---|---|---|
name | body | string | 是 | 通道名称 |
type | body | string | 是 | 通道类型:email/webhook/wecom/dingtalk/feishu/sms/pagerduty/slack |
config | body | object | 否 | 通道配置(因类型而异) |
响应示例
{
"data": {
"id": "ch_01J8XXXXX",
"name": "企业微信",
"type": "wecom"
},
"request_id": "req_01J8XXXXX"
}GET/v1/alert-policies— 获取告警策略列表需要鉴权
获取当前用户的所有告警策略。
响应示例
{
"data": {
"items": [
{
"id": "pol_01J8XXXXX",
"name": "可用性告警",
"monitor_id": "mon_01J8XXXXX"
}
]
},
"request_id": "req_01J8XXXXX"
}POST/v1/alert-policies— 创建告警策略需要鉴权
创建新的告警策略,绑定监控项和告警通道。
参数
| 名称 | 位置 | 类型 | 必填 | 描述 |
|---|---|---|---|---|
name | body | string | 是 | 策略名称 |
monitor_id | body | string | 是 | 关联的监控项 ID |
channel_ids | body | string[] | 否 | 告警通道 ID 列表 |
响应示例
{
"data": {
"id": "pol_01J8XXXXX",
"name": "可用性告警",
"monitor_id": "mon_01J8XXXXX"
},
"request_id": "req_01J8XXXXX"
}GET/v1/alert-events— 获取告警事件列表需要鉴权
获取当前用户的所有告警事件历史。
响应示例
{
"data": {
"items": [
{
"id": "evt_01J8XXXXX",
"policy_id": "pol_01J8XXXXX",
"type": "down",
"created_at": "2026-05-14T06:00:00Z"
}
]
},
"request_id": "req_01J8XXXXX"
}计费
订阅 / 取消 / 账单查询
POST/v1/billing/subscribe— 订阅付费计划需要鉴权
发起付费计划订阅,返回 PaymentHub 支付跳转 URL。
参数
| 名称 | 位置 | 类型 | 必填 | 描述 |
|---|---|---|---|---|
plan | body | string | 是 | 计划名称:pro / business(示例:pro) |
响应示例
{
"data": {
"checkout_url": "https://checkout.paymenthub.com/..."
},
"request_id": "req_01J8XXXXX"
}GET/v1/billing/subscription— 获取当前订阅信息需要鉴权
获取当前登录用户的订阅状态和到期时间。
响应示例
{
"data": {
"plan": "pro",
"status": "active",
"current_period_end": "2026-06-14T00:00:00Z"
},
"request_id": "req_01J8XXXXX"
}GET/v1/billing/invoices— 获取账单列表需要鉴权
获取当前用户的历史账单记录。
响应示例
{
"data": {
"items": [
{
"id": "inv_01J8XXXXX",
"amount": 99,
"currency": "CNY",
"status": "paid",
"created_at": "2026-05-14T00:00:00Z"
}
]
},
"request_id": "req_01J8XXXXX"
}节点
拨测节点目录
GET/v1/nodes— 获取节点列表公开
获取所有可用的拨测节点信息,包括地区、运营商和在线状态。
响应示例
{
"data": {
"items": [
{
"id": "cn-bj",
"name": "北京",
"country": "CN",
"region": "华北",
"provider": "阿里云",
"status": "online"
},
{
"id": "cn-sh",
"name": "上海",
"country": "CN",
"region": "华东",
"provider": "腾讯云",
"status": "online"
},
{
"id": "us-west",
"name": "美国西部",
"country": "US",
"region": "西海岸",
"provider": "AWS",
"status": "online"
}
]
},
"request_id": "req_01J8XXXXX"
}机器可读规范: GET /v1/openapi.json (OpenAPI 3.1 JSON,可导入 Postman / Insomnia)