Registrar API

使用 Cloudflare Registrar API 搜索域名，检查实时可用性和定价，并以编程方式注册受支持的域名。

本指南介绍了使用 Cloudflare API 和 curl 的 Beta 版工作流程。这些相同的端点默认位于官方 Cloudflare API 参考和 Cloudflare MCP 中，这意味着它们可以用于脚本、后端服务、CI 管道和代理驱动的工具中，而无需额外的集成工作。

开始之前

在您发出第一次 API 请求之前，请确保您拥有：

Cloudflare 账户 ID。
具有 Registrar 写入权限的 API 令牌。在 https://dash.cloudflare.com/<ACCOUNT_ID>/api-tokens 创建一个。
具有有效默认付款方式的计费资料。在 https://dash.cloudflare.com/<ACCOUNT_ID>/billing/payment-info 管理计费。
账户上配置的默认注册人联系人，并在注册页面上接受了域名注册协议：https://dash.cloudflare.com/<ACCOUNT_ID>/domains/registrations。

有关相关设置帮助，请参阅：

查找您的账户 ID
创建 API 令牌
进行 API 调用
[Registrar API 文档] (/api/resources/registrar)

设置身份验证

Cloudflare API 请求使用承载令牌进行身份验证。

在您的终端中，为您的账户 ID 和 API 令牌定义环境变量：

export ACCOUNT_ID="<YOUR_ACCOUNT_ID>"
export CLOUDFLARE_API_TOKEN="<YOUR_API_TOKEN>"

本指南中的所有请求均使用 Cloudflare API v4 基本 URL：

https://api.cloudflare.com/client/v4/

Beta 版工作流程

Beta 版工作流程包含三个核心步骤：

搜索候选域名。
检查您想要的域名的实时可用性和定价。
注册域名。

搜索对发现很有用，但它不是事实的来源。务必在注册前立即调用 Check 端点，以减少注册过程中遇到错误的可能性。

代理的示例提示

如果您使用的是 Cloudflare MCP 或其他代理驱动的工作流程，提示可以非常简单：

Search for domains for a coffee shop based in Evergreen, Colorado.
Find 5 available .com or .dev domains for an AI expense tracker.
Check whether example.com is available and show me the current price.
Check these domains and tell me which ones are registrable right now: example.com, example.dev, example.cafe
Register example.com on my Cloudflare account.

1. 搜索域名

使用 Search 端点根据关键字、短语或部分域名生成候选域名。

搜索结果：

快速且旨在发现。
基于缓存数据。
仅包括 API Beta 版支持的扩展名。

curl --request GET \
  --url "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/registrar/domain-search?q=acme%20corp&limit=3" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

响应示例：

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "domains": [
      {
        "name": "acmecorp.com",
        "registrable": true,
        "tier": "standard",
        "pricing": {
          "currency": "USD",
          "registration_cost": "8.57",
          "renewal_cost": "8.57"
        }
      },
      {
        "name": "acmecorp.dev",
        "registrable": true,
        "tier": "standard",
        "pricing": {
          "currency": "USD",
          "registration_cost": "10.11",
          "renewal_cost": "10.11"
        }
      },
      {
        "name": "acmecorp.app",
        "registrable": true,
        "tier": "standard",
        "pricing": {
          "currency": "USD",
          "registration_cost": "11.00",
          "renewal_cost": "11.00"
        }
      }
    ]
  }
}

2. 检查实时可用性和定价

使用 Check 端点确认域名当前是否可注册并检索当前价格。

Check 结果：

直接查询注册局。
反映当前注册局状态。
应在调用注册端点之前立即使用。
当 registrable 为 false 时，响应可以包含 reason 字段。

此端点每个请求最多接受 20 个域名。

curl --request POST \
  --url "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/registrar/domain-check" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "domains": ["acmecorp.dev"]
  }'

响应示例：

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "domains": [
      {
        "name": "acmecorp.dev",
        "registrable": true,
        "tier": "standard",
        "pricing": {
          "currency": "USD",
          "registration_cost": "10.11",
          "renewal_cost": "10.11"
        }
      }
    ]
  }
}

如果无法通过 API 注册域名，响应将包含一个原因。例如：

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "domains": [
      {
        "name": "mybrand.uk",
        "registrable": false,
        "reason": "extension_not_supported_via_api"
      }
    ]
  }
}

常见的 reason 值包括：

domain_unavailable
extension_not_supported_via_api
extension_not_supported
extension_disallows_registration

3. 注册域名

使用 Registration 端点启动域名注册工作流程。

重要提示：

成功注册将向默认付款资料计费。
一旦成功完成，注册将不予退款。
在调用此端点之前，请务必确认域名和价格。

最简单的请求仅需 domain_name：

curl --request POST \
  --url "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/registrar/registrations" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "domain_name": "acmecorp.dev"
  }'

账户必须配置了默认注册人联系人。如果您不在线传递新联系人，API 将自动使用默认联系人。如果您想使用其他联系人注册域名，您可以在请求中传递该联系人。

当前的默认行为：

auto_renew 默认为 false。
如果 TLD 支持，privacy_mode 默认为 redaction，否则为 off。
自动收取账户的默认付款方式。

要覆盖单个注册的默认注册人联系人，请在线提供一个：

curl --request POST \
  --url "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/registrar/registrations" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "domain_name": "acmecorp.dev",
    "contacts": {
      "registrant": {
        "email": "[email protected]",
        "phone": "+1.5555555555",
        "postal_info": {
          "name": "Ada Lovelace",
          "organization": "Example Inc",
          "address": {
            "street": "123 Main St",
            "city": "Austin",
            "state": "TX",
            "postal_code": "78701",
            "country_code": "US"
          }
        }
      }
    }
  }'

成功响应示例：

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "domain_name": "acmecorp.dev",
    "state": "succeeded",
    "completed": true,
    "created_at": "2025-10-27T10:00:00Z",
    "updated_at": "2025-10-27T10:00:03Z",
    "context": {
      "registration": {
        "domain_name": "acmecorp.dev",
        "status": "active",
        "created_at": "2025-10-27T10:00:00Z",
        "expires_at": "2026-10-27T10:00:00Z",
        "auto_renew": false,
        "privacy_mode": "redaction",
        "locked": true
      }
    },
    "links": {
      "self": "/accounts/abc/registrar/registrations/acmecorp.dev/registration-status",
      "resource": "/accounts/abc/registrar/registrations/acmecorp.dev"
    }
  }
}

处理注册响应

默认情况下，注册端点在响应前最多等待 10 秒。

您可能会收到以下之一：

如果注册在等待窗口内完成，则为 201 Created。
如果注册仍在进行中，则为 202 Accepted。

要强制立即执行异步行为，请发送 Prefer: respond-async。

异步请求示例：

curl --request POST \
  --url "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/registrar/registrations" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Prefer: respond-async" \
  --data '{
    "domain_name": "acmecorp.dev"
  }'

202 Accepted 响应示例：

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "domain_name": "acmecorp.dev",
    "state": "in_progress",
    "completed": false,
    "created_at": "2025-10-27T10:00:00Z",
    "updated_at": "2025-10-27T10:00:10Z",
    "links": {
      "self": "/accounts/abc/registrar/registrations/acmecorp.dev/registration-status",
      "resource": "/accounts/abc/registrar/registrations/acmecorp.dev"
    }
  }
}

轮询注册状态

如果注册仍在进行中，请轮询状态端点，直到工作流程达到最终状态。

curl --request GET \
  --url "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/registrar/registrations/acmecorp.dev/registration-status" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

响应示例：

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "domain_name": "acmecorp.dev",
    "state": "succeeded",
    "completed": true,
    "created_at": "2025-10-27T10:00:00Z",
    "updated_at": "2025-10-27T10:00:03Z",
    "context": {
      "registration": {
        "domain_name": "acmecorp.dev",
        "status": "active",
        "created_at": "2025-10-27T10:00:00Z",
        "expires_at": "2026-10-27T10:00:00Z",
        "auto_renew": false,
        "privacy_mode": "redaction",
        "locked": true
      }
    },
    "links": {
      "self": "/accounts/abc/registrar/registrations/acmecorp.dev/registration-status",
      "resource": "/accounts/abc/registrar/registrations/acmecorp.dev"
    }
  }
}

可能的工作流程状态包括：

in_progress
succeeded
failed
action_required
blocked

如果工作流程返回 action_required，请停止轮询并显示所需的用户操作。

如果工作流程返回 failed，请在重试之前检查 error.code 和 error.message。

获取注册资源

注册完成后，直接检索注册资源：

curl --request GET \
  --url "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/registrar/registrations/acmecorp.dev" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

响应示例：

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "domain_name": "acmecorp.dev",
    "status": "active",
    "created_at": "2025-10-27T10:00:00Z",
    "expires_at": "2026-10-27T10:00:00Z",
    "auto_renew": false,
    "privacy_mode": "redaction",
    "locked": true
  }
}

Beta 版限制

这是 Registrar API 的第一个 Beta 版版本。

当前的限制包括：

通过 API Beta 版仅可使用受支持的 Cloudflare Registrar 扩展名的一个子集。
搜索结果范围仅限于 API 支持的扩展名。
仪表板中支持的某些扩展名尚未用于编程式注册。
如果支持，高级域名在注册前需要明确的费用确认。
目前无法通过 API 进行续订。
目前无法通过 API 进行转移。
目前无法通过 API 更新联系人。

如果您检查了 Cloudflare 在仪表板中支持但尚未在 API 中支持的域名，则 Check 响应将返回 extension_not_supported_via_api。

这些核心的 Registrar 功能将在 API 的未来版本中添加。

在支持的扩展名列表存在后在此处添加链接。

下一步

查看 Cloudflare API 身份验证和请求约定。

如果您使用 Registrar API Beta 版进行构建，特别是用于自动化、代理或多租户平台工作流程，我们希望收到您的反馈。