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 權杖身份驗證及按用戶隔離區域。
• 新增讀取及寫入範圍。
• 新增帳戶、區域清單及記錄管理端點。
• 新增包含請求識別碼的一致回應封裝。