CNF API · v1

概览

第 1 版提供你通过 DNS 管理认领之区域的 DNS 操作。请在 账户 → API 密钥下建立及撤销令牌。

基础 URL 及版本管理

https://api.c.nf/v1

所有端点均位于 /v1 之下。破坏兼容性的变更会使用新的主要版本路径。v1 可新增向后兼容的字段及端点，并会记录于变更记录。

身份验证及范围

每项读取或更改账户数据的请求都必须包含 Bearer 令牌。令牌以 cnf_ 开头，后接 32 个十六进制字符。

curl https://api.c.nf/v1/dns/zones \
  -H "Authorization: Bearer cnf_a1b2c3d4e5f60718293a4b5c6d7e8f90"

令牌会以单向哈希形式存储，完整值只在建立时显示。如果丢失令牌，请撤销并另行建立。

每个令牌都带有范围。未设置范围的令牌默认获得 dns:read。写入范围也允许读取。

范围不符时会返回 403 forbidden_scope，并包含 required_scopes 及 token_scopes 以供诊断。

按用户隔离

每个 Bearer 令牌只会对应一个 user_id。每个区域处理程序均会在读取或写入前，检查该用户已验证的认领。系统没有管理员覆盖、冒充路径或跨用户绕过机制。

即使令牌具有 *，也只能操作其所属用户已验证的区域。尝试使用另一账户的区域会返回 403 forbidden_zone。

响应封装

成功响应

{
  "success": true,
  "data": { "zones": [] },
  "request_id": "req_abc123def456abcd"
}

错误响应

{
  "success": false,
  "error": "forbidden_zone",
  "message": "zone not verified for this account (or does not exist)",
  "request_id": "req_abc123def456abcd",
  "zone": "example.com"
}

每个响应都包含 request_id，可安全记录于客户端日志。

错误代码

区域验证

当 POST /v1/dns/zones 认领区域时，服务器会选择以下其中一种流程：

1. 即时验证（method: "auto"） — 在没有其他账户认领该区域时使用。认领会立即通过验证。只有拥有者在注册商处将权威 NS 委派指向返回的域名服务器后，记录才会生效。
2. TXT 验证 — 用于有争议的认领。请在 _cnfdns-verify.<zone> 新增返回的 TXT 值，然后调用 POST /v1/dns/zones/{zone}/verify。
3. 旧版 NS 验证 — 较早建立而仍待处理的认领可能使用 verify_method: "ns"。验证会比较区域当前的 NS 响应与预期的域名服务器组合。

验证是幂等操作。对已验证的认领重复验证，会返回 verified: true，而不会更改认领。

记录类型及限制

支援的记录类型

A, AAAA, CNAME, MX, TXT, NS, SRV, CAA, PTR, SPF.

priority 是 MX 及 SRV 的必填字段，其他类型则会忽略。ttl 必须介于 60 至 2,592,000 秒。

端点

公共工具

无需账号的小型可靠接口：时间、地址、国家、汇率与哈希。

账号

令牌属于谁，以及它能做什么。

DNS

认领域名、证明控制权，然后管理解析记录。

凭据

凭据工具背后的私有凭据库。

文件

个人文件存储：列出、上传、编辑、分享与删除。

CDN

你分享文件的边缘缓存与流量。

短信转发

从手机转发过来的消息，以及放行它的密钥。

静态站点

上传一个 zip，就是一个站点。

部署

你已部署的表单、Webhook 与短链接端点。

域名

你的域名组合及其注册信息。

软件包

发布版本，并读取其版本与下载量。

WHOIS

域名注册信息，带缓存并与域名工具共用。

面向 AI 代理

把代理指向 /v1/ai，那是一份可直接粘进提示词的说明；/v1/ai?format=json 则把同样的接口给成工具定义。/v1/openapi.json 是完整的 OpenAPI 3.1 契约，/llms.txt 是给爬虫看的索引。四者都由与本页相同的路由表生成，因此不会描述不存在的接口。

curl https://api.c.nf/v1/ai
curl https://api.c.nf/v1/ai?format=json
curl https://api.c.nf/v1/openapi.json

请求字段

建立区域认领

建立 DNS 记录

更新 DNS 记录

示例

curl -H "Authorization: Bearer $CNF_TOKEN" \
  https://api.c.nf/v1/dns/zones

curl -X POST https://api.c.nf/v1/dns/zones \
  -H "Authorization: Bearer $CNF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"zone":"example.com"}'

curl -X POST https://api.c.nf/v1/dns/zones/example.com/verify \
  -H "Authorization: Bearer $CNF_TOKEN"

curl -X POST https://api.c.nf/v1/dns/zones/example.com/records \
  -H "Authorization: Bearer $CNF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"A","host":"api","value":"192.0.2.10"}'

快速开始

1. 建立具有 dns:write 的 API 密钥；请前往账户 → API 密钥，并在密钥显示时复制。
2. 将令牌存储在你设备上受保护的环境变量中。
3. 调用 GET /v1/account/me，确认令牌及其范围。
4. 认领区域。响应会说明验证是即时完成、使用 TXT，还是使用旧版 NS 方式。
5. 如有需要，完成返回的 DNS 证明，然后调用验证端点。
6. 认领通过验证后，才可建立、读取、更新或删除记录。

变更记录

v1.1.0 — 区域管理

• 新增以 API 认领区域，包括即时及 TXT 验证流程。
• 新增单个区域状态及幂等验证端点。
• 新增撤销认领功能，而不会一并删除记录。
• 在区域清单新增已验证、待处理及全部筛选器。

v1.0.0 — 首次发布

• 新增 Bearer 令牌身份验证及按用户隔离区域。
• 新增读取及写入范围。
• 新增账户、区域清单及记录管理端点。
• 新增包含请求识别码的一致响应封装。