CNF API · v1

概要

バージョン 1 は、DNS 管理から申請したゾーンの DNS 操作を提供します。トークンの作成と無効化はアカウント → API キーで行います。

ベース URL とバージョニング

https://api.c.nf/v1

すべてのエンドポイントは /v1 配下です。互換性を破る変更には新しいメジャーバージョンのパスを使用します。後方互換性のあるフィールドとエンドポイントは v1 に追加される場合があり、変更履歴に記録されます。

認証とスコープ

アカウントデータの読み取りまたは変更を行うすべてのリクエストには Bearer トークンが必要です。トークンは cnf_ に続く 32 桁の 16 進文字で構成されます。

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

トークンは一方向ハッシュとして保存され、完全な値は作成時にだけ表示されます。紛失した場合は無効化して、別のトークンを作成してください。

各トークンにはスコープがあります。スコープ未設定のトークンには、既定で dns:read が与えられます。書き込みスコープでは読み取りも可能です。

不一致の場合は 403 forbidden_scope が返され、診断用に required_scopes と token_scopes の両方が含まれます。

ユーザーごとの分離

Bearer トークンは正確に 1 つの 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 による確認 — 競合する申請に使用します。返された TXT 値を _cnfdns-verify.<zone> に追加してから、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

共有ファイルのエッジキャッシュとトラフィック。

SMS 転送

端末から転送されたメッセージと、それを許可する鍵。

静的サイト

zip をアップロードしてサイトを配信します。

デプロイ

公開したフォーム・Webhook・短縮リンクのエンドポイント。

ドメイン

ドメイン一覧とその登録情報。

パッケージ

リリースを公開し、バージョンとダウンロード数を取得します。

WHOIS

ドメインの登録情報。キャッシュされ、ドメインツールと共有されます。

AI エージェント向け

エージェントには /v1/ai を渡してください。プロンプトにそのまま貼れる要約です。/v1/ai?format=json は同じエンドポイントをツール定義として返します。/v1/openapi.json は完全な OpenAPI 3.1 契約、/llms.txt はクローラー向けの案内です。4 つともこのページと同じルーティング表から生成されるため、存在しないエンドポイントを説明することはありません。

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 — ゾーン管理

• 即時確認と TXT 確認を含む、API ベースのゾーン申請を追加しました。
• 単一ゾーンの状態取得と、べき等な確認エンドポイントを追加しました。
• レコードを暗黙に削除しない申請取り消しを追加しました。
• ゾーン一覧に確認済み、保留中、すべての絞り込みを追加しました。

v1.0.0 — 初回リリース

• Bearer トークン認証とユーザーごとのゾーン分離を追加しました。
• 読み取り・書き込みスコープを追加しました。
• アカウント、ゾーン一覧、レコード管理のエンドポイントを追加しました。
• リクエスト識別子を含む一貫した応答エンベロープを追加しました。