API 文档
REST / JSON-RPC / GraphQL 三种调用形态 · 面向 Agent 友好
REST Base
/rest
资源化 URL
RPC Base
/rpc
单端点 + 批量调用
GraphQL Base
/graphql
按需取字段
认证方式
X-API-Key + X-API-Secret
或 Bearer key:secret
端点矩阵
🔐 认证与检测
🌐 子域名
📜 DNS 记录
📊 配额
🔎 WHOIS
🛠️ 系统
验证凭证
POST校验 API Key + Secret 是否有效，并返回账户基本信息
REST
POST /rest/auth/verify
JSON-RPC method
auth.verify
GraphQL (query)
verifyCredentials(...)
说明
通过调用此接口，可以快速判断当前凭证是否可用。Agent 在执行任何操作前应先调用此接口进行 sanity check。返回的 account 字段包含配额摘要，可避免额外请求。
响应结构
{
"success": true,
"account": {
"api_key": "cfsd_xxx",
"quota": { "used": 3, "total": 7, "available": 4 }
}
}调用示例
curl -X POST https://your-host/rest/auth/verify \
-H "X-API-Key: cfsd_xxx" \
-H "X-API-Secret: yyyy"可能的错误
auth_invalid_credentials
401
API Key 或 Secret 无效
auth_ip_not_allowed
403
请求 IP 不在白名单
统一错误码
error_code
HTTP
描述
bad_request
400
请求参数无效或缺失必填字段
auth_invalid_credentials
401
API Key 或 Secret 缺失/无效
auth_ip_not_allowed
403
请求 IP 不在白名单
api_access_disabled
403
API 访问在后台被禁用
not_found
404
资源不存在
subdomain_not_found
404
子域名不存在或不属于当前账户
dns_record_not_found
404
DNS 记录不存在
insufficient_balance
402
账户余额不足
renewal_not_yet_available
422
续费窗口尚未开放
renewal_window_expired
403
续费宽限期已过
quota_exceeded
429
子域名配额超限
rate_limit_exceeded
429
请求频率超限（默认 60/分钟）
provider_operation_failed
502
上游 DNS 服务商操作失败
internal_error
500
服务器内部错误
Agent 接入指南
推荐流程
- 调用
POST /api/v1/rest/auth/verify验证凭证并获取配额 - 根据任务选择 REST / RPC / GraphQL 任意一种形态调用
- 对于查询类操作，使用 GET + 查询参数；对于写操作，使用 POST + JSON body
- 遇到
rate_limit_exceeded错误时，等待 details.reset_at 后重试 - 对于危险操作（删除子域名、删除 DNS 记录），应在调用前向用户确认
何时选择哪种形态
- REST — 资源化操作（如 CRUD 子域名），URL 语义清晰
- JSON-RPC — 批量调用（支持 array 一次发多个 method），方法命名稳定
- GraphQL — 一次查询多资源，按需取字段
认证
# 方式 1: HTTP Headers (推荐)
X-API-Key: cfsd_xxxxxxxxxxxxxxxx
X-API-Secret: yyyyyyyyyyyyyyyyyyyy
# 方式 2: Authorization Bearer
Authorization: Bearer cfsd_xxx:yyyy