API 参考

idcd 全球网络诊断 API 完整参考文档。服务端 Origin: https://api-prod.idcd.com;下列端点路径已包含 /v1版本前缀。

GETPOSTPATCHDELETE
鉴权:使用 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。

本页是常用端点速查;完整请求/响应契约以线上 OpenAPI 3.1 规范为准。 服务端 Origin 固定使用 https://api-prod.idcd.com; 请直接拼接下方以 /v1 开头的端点路径。

拨测

多节点 HTTP / Ping / DNS / TCP / Traceroute 拨测

POST/v1/probe/httpHTTP 拨测
公开

创建异步 HTTP/HTTPS 拨测任务;使用返回的 task_id 轮询任务结果。

参数

名称位置类型必填描述
target
body
string目标 URL(示例:https://github.com)
node_ids
body
string[]固定节点 ID 列表,省略时自动选择
params.method
body
stringHTTP 方法,默认 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/pingICMP 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/dnsDNS 解析拨测
公开

创建异步 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/tcpTCPing 拨测
公开

创建异步 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/tracerouteTraceroute 路由追踪
公开

创建异步 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/ipIP 信息查询
公开

查询指定 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/whoisWHOIS 查询
公开

查询域名或 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/sslSSL/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/dnsDNS 记录查询
公开

查询域名的各类 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/icpICP 备案查询
公开

查询域名的 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/reputationIP 信誉 / 风险查询
公开

返回 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
stringAPI 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)