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 已绑定用户。

错误与限制

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

HTTP	错误码	说明
400	`invalid_request / invalid_nodes / trusted_dns_resolution_failed`	参数、目标、节点选择或可信公网 DNS 解析无效
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 已经使用
409	`entitlement_exceeded`	监控任务数量、周期、节点或月度节点额度超限
429	`quota_exceeded`	本月套餐请求配额已用完
429	`rate_limited / capacity_limited`	密钥频率或当前节点探测容量达到上限
503	`service_unavailable`	客户 API 暂停服务

每次成功受理的 API 请求消耗 1 次 API 月配额；监控轮次另按本轮选中节点数计入监控 units。两种额度独立，以 GET /v1/account 与监控接口返回的 entitlement 为准。节点筛选、批量容量和为单次探测预留槽位的规则与站内公开工具一致。