dnspup Customer API v1

面向客户系统的探测与网站监控接口，支持一次性 Ping、TCPing、HTTP、DNS、DNS 传播、Find Ping、MTR、路由追踪和网站体检，以及 HTTP、PING、TCPING、DNS、DNS 传播、SSL 监控任务。访问凭证由管理员审核并分配。

API 基址 https://api.dnspup.com版本 v1认证 X-API-Key + X-API-Secret来源 单一 IP 或域名白名单

来源白名单

新密钥只能绑定一个固定公网 IP 或一个完整服务器域名；管理员编辑旧密钥时也必须补充来源。

固定 IP：请求必须从管理员填写的公网 IP 发出，服务端按可信代理链判断来源。
服务器域名：域名不能单独证明网络来源，因此每次请求还必须提供 X-API-Source-Domain、X-API-Timestamp、X-API-Nonce 和 X-API-Signature。签名覆盖请求方法、转义路径、原始查询串、时间戳、nonce、规范化域名和原始请求体 SHA-256，具体拼接规则见项目文档。

域名来源的普通自定义请求头可以被伪造，不能作为安全边界。请使用随机 nonce、90 秒内时间戳和 HMAC 签名；签名失败、来源不匹配或 nonce 重放不会消耗月配额。

请求生成器

生成可直接复制的 curl 命令，凭证仅通过本机环境变量读取。

API 基址（固定官方地址）https://api.dnspup.com

探测类型探测目标节点 ID（可选）

运行命令前，请在本机终端安全设置 DNSPUP_API_KEY 与 DNSPUP_API_SECRET 环境变量。本页不会要求、接收、存储或复制真实凭证。

接口列表

健康检查无需认证；监控接口要求 API Key 已绑定用户。

异步检测与结果查询

六类探测沿用现有参数；先确认账号能力，再创建一次任务并查询结果。

仅当 GET /v1/account 返回 data.capabilities.asyncProbesV1 为 true 时使用异步创建；字段缺失或为 false 时继续使用原同步接口。节点目录的 capabilities.ipVersions 和 capabilities.tools 表示当前密钥可用的节点能力，最终以创建时校验为准。

POST /v1/probes
Prefer: respond-async
Idempotency-Key: 9a7db0e5-3ec0-4ee9-9544-3ef909565c64
Content-Type: application/json

{"type":"ping","target":"example.com","count":4,"ipVersion":"4"}

GET /v1/probes/{requestId}

以上仅展示新增请求头与路径，仍需携带凭证并通过来源校验。每次有意发起的新检测应生成并保存一个 1–128 位、不含空格的可打印 ASCII 幂等键。相同密钥、幂等键和规范化参数重放返回原任务，不重复执行或扣费；参数改变返回 409 idempotency_conflict。仅添加 Idempotency-Key 不会使同步请求具备幂等性。

新任务返回 202，重放返回 200；保存 data.requestId 后，仅用 GET 查询。创建响应丢失且未获得任务编号时，保留未知状态，重试必须沿用原幂等键与参数。域名绑定的每次 POST 或 GET 都需重新生成时间戳、nonce 和签名；GET 按空请求体签名。

{"data":{
  "requestId":"req_0123456789abcdef01234567",
  "status":"running",
  "completedNodes":0,
  "totalNodes":2,
  "createdAt":"2026-10-13T00:00:00Z",
  "updatedAt":"2026-10-13T00:00:01Z",
  "expiresAt":"2026-10-14T00:00:00Z",
  "queryUrl":"/v1/probes/req_0123456789abcdef01234567"
}}

状态包括 queued、running、completed、partial、timeout、failed、unknown。completedNodes 是已终结节点数，包含超时节点，不等于成功数。result 可包含阶段结果，其结构为原同步响应的 data 正文，不再嵌套 data；检测完成不代表目标可达，unknown 或 failed 仍可能保留部分结果。

查询不消耗检测额度，使用每把密钥每分钟 180 次的独立查询限流。建议每 2 秒查询一次并遵守 Retry-After；多任务共用此限额。只允许查询同一密钥创建的任务，其他密钥与不存在的任务均返回 404 task_not_found。

结果自创建起保留 24 小时，幂等记录保留 30 天。结果过期后查询和同键重放返回 410 result_expired，不重新执行或扣费。收到任务编号后不得降级为同步 POST；查询失败、超时或 unknown 均不能自动换新键重跑。

幂等机制防止重复受理和扣费，不承诺 Agent 恰好执行一次。执行证据丢失时可能返回 unknown；需要再次检测时，应由调用方明确发起新任务。

错误与限制

所有错误均使用稳定的 JSON error envelope，便于客户系统统一处理。

HTTP	错误码	说明
400	`invalid_request / invalid_nodes / trusted_dns_resolution_failed`	参数、目标、节点选择或可信公网 DNS 解析无效
400	`invalid_idempotency_key`	异步幂等请求头缺失、重复或格式无效
401	`unauthorized`	密钥缺失、停用、到期或已撤销
401	`signature_required / malformed_signature / bad_signature / stale_signature`	域名来源调用缺少签名、签名格式错误、内容被篡改或时间戳过期
403	`source_forbidden / owner_required / target_restricted / tool_not_allowed`	来源 IP/域名不匹配、密钥未绑定用户、目标不允许探测，或密钥未开通该工具
409	`replay`	域名来源请求的 nonce 已经使用
404	`task_not_found`	任务不存在或不属于当前密钥
409	`idempotency_conflict`	同一幂等键已用于不同的规范化参数
410	`result_expired`	检测结果已过期，原任务不会重新执行或扣费
409	`entitlement_exceeded`	监控任务数量、周期、节点或月度节点额度超限
429	`quota_exceeded`	本月套餐请求配额已用完
429	`rate_limited / capacity_limited`	密钥频率或当前节点探测容量达到上限
503	`service_unavailable`	客户 API 暂停服务
503	`async_unavailable`	异步创建未启用或暂不可用

每次新受理的探测请求消耗 1 次 API 月配额，异步任务查询及同一幂等键的重放不重复扣费；监控轮次另按本轮选中节点数计入监控 units。两种额度独立，以 GET /v1/account 与监控接口返回的 entitlement 为准。节点筛选、批量容量和为单次探测预留槽位的规则与站内公开工具一致。