cdnca

开放接口

/v1/dns

24 个接口

← 全部分组 · 第一次调用？先看教程：认证、权限、请求与响应、常见失败

方法路径摘要认证
GET/v1/dns/platform-configRead the installation-wide DNS configuration (节点管理 > DNS配置, platform administrator)登录会话
PUT/v1/dns/platform-configSave the installation-wide DNS configuration and synchronise every tenant copy登录会话
POST/v1/dns/platform-config/connection-test连接测试 - verify DNS credentials and the CNAME domains they host (read-only)登录会话
POST/v1/dns/platform-config/{kind}Start 记录修复 (repair) or 清除CDN无关解析 (cleanup) as background jobs登录会话
GET/v1/dns/platform-zonesList the CNAME domains (CNAME域名)登录会话
POST/v1/dns/platform-zonesAdd a CNAME domain (copied into every tenant; the first is the default allocation zone)登录会话
PATCH/v1/dns/platform-zones/{id}Edit a CNAME domain; renaming one with allocated CNAMEs is refused (dns_zone_in_use)登录会话
DELETE/v1/dns/platform-zones/{id}Delete a CNAME domain and its tenant copies; refused while sites use it (dns_zone_in_use)登录会话
GET/v1/dns/providersList DNS provider configurations登录会话
POST/v1/dns/providersStore an encrypted DNS provider configuration登录会话
PATCH/v1/dns/providers/{id}Update provider metadata or replace encrypted credentials登录会话
DELETE/v1/dns/providers/{id}Delete an unreferenced DNS provider configuration登录会话
POST/v1/dns/providers/{id}/verifyVerify a DNS provider credential against its upstream API登录会话
GET/v1/dns/recordsList structured records in a zone登录会话
POST/v1/dns/recordsCreate a validated draft DNS record登录会话
PATCH/v1/dns/records/{id}Update a validated draft DNS record登录会话
DELETE/v1/dns/records/{id}Delete a draft DNS record登录会话
GET/v1/dns/settingsRead the DNS settings for the active tenant scope登录会话
PATCH/v1/dns/settingsUpdate the compatibility DNS TTL with compare-and-swap semantics登录会话
GET/v1/dns/settings/operations/{operation_id}Read a DNS DNS operation status登录会话
POST/v1/dns/settings/{kind}Enqueue record repair or CDN-unrelated record cleanup登录会话
GET/v1/dns/zonesList DNS zones登录会话
POST/v1/dns/zonesCreate a draft DNS zone登录会话
DELETE/v1/dns/zones/{id}Delete an unreferenced draft DNS zone登录会话

契约文件：api/openapi/v1/control.yaml api/openapi/v1/dns-acme.yaml

接口详情

GET /v1/dns/platform-config

Read the installation-wide DNS configuration (节点管理 > DNS配置, platform administrator)

operationId
getPlatformDNSConfig
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

响应

getPlatformDNSConfig 响应
状态码说明
200Provider, non-secret identifiers, TTL, IP weight, tenant sync summary and the last DNS write failure.

字段：provider_type?: string identifiers: object secret_saved: boolean ttl: integer ip_weight: boolean weight_supported: boolean version: integer updated_at?: string(date-time) sync: object last_error: object

401认证失败或会话已失效。
403当前身份没有执行该操作的权限。

失败时怎么办

  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。

↑ 回到列表

PUT /v1/dns/platform-config

Save the installation-wide DNS configuration and synchronise every tenant copy

operationId
savePlatformDNSConfig
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

参数

savePlatformDNSConfig 参数
名称位置类型必填说明
Idempotency-Keyheaderstring是—
If-Matchheaderstring是—

请求体

application/json · 必填：是

savePlatformDNSConfig 请求体
名称类型必填说明
provider_typestring: aliyun / huawei / dns_la / dnspod_cn / dns_com / cloudflare / namecom / custom_http是—
credentialsobject否Every credential field of the provider; omitted keeps the stored credentials of the same provider.
ttlinteger是Cloudflare requires at least 60; name.com at least 300.
ip_weightboolean是—

响应

savePlatformDNSConfig 响应
状态码说明
200Saved configuration.

字段：provider_type?: string identifiers: object secret_saved: boolean ttl: integer ip_weight: boolean weight_supported: boolean version: integer updated_at?: string(date-time) sync: object last_error: object

400请求体或参数不合法。
401认证失败或会话已失效。
403当前身份没有执行该操作的权限。
409请求的状态与已有资源或幂等记录冲突。
503A required dependency is unavailable.

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/dns/platform-config/connection-test

连接测试 - verify DNS credentials and the CNAME domains they host (read-only)

operationId
testPlatformDNSConnection
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

说明（契约原文）

Verifies the entered credentials (or, without credentials, the saved ones of provider_type) with the same provider check as a save, then lists the account's domains once per CNAME domain. Nothing is saved and no DNS record is written. Custom HTTP and plugin providers have no domain list (status unchecked).

请求体

application/json · 必填：是

testPlatformDNSConnection 请求体
名称类型必填说明
provider_typestring是—
credentialsobject否—

响应

testPlatformDNSConnection 响应
状态码说明
200The provider accepted the credentials.

字段：provider_type: string zones: array<object>

400请求体或参数不合法。
401认证失败或会话已失效。
403当前身份没有执行该操作的权限。
409dns_not_configured (no saved credentials to test).
422provider_credentials_rejected or provider_credentials_invalid.
429provider_verification_rate_limited.
503provider_verification_unavailable or credential_encryption_unavailable.
504provider_verification_timeout.

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 429 被限速：等待后再试，降低并发。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/dns/platform-config/{kind}

Start 记录修复 (repair) or 清除CDN无关解析 (cleanup) as background jobs

operationId
startPlatformDNSOperation
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

说明（契约原文）

repair queues one dns.repair.v1 job per tenant with settled CNAME owners (one item per owner); cleanup lists the CNAME domains at the provider and queues one dns.cleanup.v1 job with one item per A/AAAA/CNAME record that is neither the zone apex nor an allocated CNAME hostname. Item ids are the result lines shown under 系统管理 > 后台任务.

参数

startPlatformDNSOperation 参数
名称位置类型必填说明
kindpathstring: repair / cleanup是—
Idempotency-Keyheaderstring是—

请求体

application/json · 必填：是

响应

startPlatformDNSOperation 响应
状态码说明
202Background jobs accepted (or replayed).

字段：operations: array<DNSOperation> replayed: boolean

400请求体或参数不合法。
401认证失败或会话已失效。
403当前身份没有执行该操作的权限。
409dns_not_configured, dns_no_tenant or an idempotency conflict.
502dns_provider_unavailable (the provider records could not be listed).

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。

↑ 回到列表

GET /v1/dns/platform-zones

List the CNAME domains (CNAME域名)

operationId
listPlatformDNSZones
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

参数

listPlatformDNSZones 参数
名称位置类型必填说明
pagequeryinteger否—
limitqueryinteger否—
searchquerystring否—

响应

listPlatformDNSZones 响应
状态码说明
200One page of CNAME domains.

字段：items: array<PlatformDNSZone> total: integer

400请求体或参数不合法。
401认证失败或会话已失效。
403当前身份没有执行该操作的权限。

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。

↑ 回到列表

POST /v1/dns/platform-zones

Add a CNAME domain (copied into every tenant; the first is the default allocation zone)

operationId
createPlatformDNSZone
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

参数

createPlatformDNSZone 参数
名称位置类型必填说明
Idempotency-Keyheaderstring是—

请求体

application/json · 必填：是

createPlatformDNSZone 请求体
名称类型必填说明
namestring是—
remarkstring是—
random_allocationboolean否参与随机分配. New sites without a CNAME domain draw one of the marked domains (any DNS provider); with none marked they use the default CNAME domain. Allocated CNAMEs do not move. Omitted on update keeps the current value; omitted on create is false.

响应

createPlatformDNSZone 响应
状态码说明
201Created CNAME domain.

字段：id: string(uuid) display_id: integer name: string remark: string in_use: boolean random_allocation: boolean version: integer created_at: string(date-time) updated_at: string(date-time)

400请求体或参数不合法。
401认证失败或会话已失效。
403当前身份没有执行该操作的权限。
409请求的状态与已有资源或幂等记录冲突。

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。

↑ 回到列表

PATCH /v1/dns/platform-zones/{id}

Edit a CNAME domain; renaming one with allocated CNAMEs is refused (dns_zone_in_use)

operationId
updatePlatformDNSZone
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

参数

updatePlatformDNSZone 参数
名称位置类型必填说明
idpathstring(uuid)是—
Idempotency-Keyheaderstring是—
If-Matchheaderstring是—

请求体

application/json · 必填：是

updatePlatformDNSZone 请求体
名称类型必填说明
namestring是—
remarkstring是—
random_allocationboolean否参与随机分配. New sites without a CNAME domain draw one of the marked domains (any DNS provider); with none marked they use the default CNAME domain. Allocated CNAMEs do not move. Omitted on update keeps the current value; omitted on create is false.

响应

updatePlatformDNSZone 响应
状态码说明
200Updated CNAME domain.

字段：id: string(uuid) display_id: integer name: string remark: string in_use: boolean random_allocation: boolean version: integer created_at: string(date-time) updated_at: string(date-time)

400请求体或参数不合法。
401认证失败或会话已失效。
403当前身份没有执行该操作的权限。
404请求的资源不存在。
409请求的状态与已有资源或幂等记录冲突。

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。

↑ 回到列表

DELETE /v1/dns/platform-zones/{id}

Delete a CNAME domain and its tenant copies; refused while sites use it (dns_zone_in_use)

operationId
deletePlatformDNSZone
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

参数

deletePlatformDNSZone 参数
名称位置类型必填说明
idpathstring(uuid)是—
Idempotency-Keyheaderstring是—
If-Matchheaderstring是—

响应

deletePlatformDNSZone 响应
状态码说明
204Deleted.
400请求体或参数不合法。
401认证失败或会话已失效。
403当前身份没有执行该操作的权限。
404请求的资源不存在。
409请求的状态与已有资源或幂等记录冲突。

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。

↑ 回到列表

GET /v1/dns/providers

List DNS provider configurations

operationId
listDNSProviders
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

说明（契约原文）

A tenant scope lists only the accounts it entered (managed_by=tenant); the platform DNS copy is not returned. The platform scope lists every tenant's accounts, platform copies included.

参数

listDNSProviders 参数
名称位置类型必填说明
limitqueryinteger否—
cursorquerystring否Opaque cursor bound to the authenticated scope and page limit.

响应

listDNSProviders 响应
状态码说明
200Provider metadata without credentials or credential-derived fingerprints.

字段：items: array<Provider> next_cursor?: string

401Authentication is required.
403The active role lacks the required permission.

失败时怎么办

  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。

↑ 回到列表

POST /v1/dns/providers

Store an encrypted DNS provider configuration

operationId
createDNSProvider
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

参数

createDNSProvider 参数
名称位置类型必填说明
Idempotency-Keyheaderstring是—

请求体

application/json · 必填：是

createDNSProvider 请求体
名称类型必填说明
target_scope_idstring(uuid)否—
namestring是—
remarkstring否备注; trimmed

响应

createDNSProvider 响应
状态码说明
201Stored as unverified; no provider request has been made.

字段：id: string(uuid) scope_id: string(uuid) name: string remark?: string provider_type: string: aliyun / cloudflare / huawei / dnspod_cn / dns_com / dns_la / namecom / custom_http / dnsdun credentials_configured: boolean status: string: unverified / verified / disabled managed_by?: string: tenant / platform version: integer(int64) created_at: string(date-time) updated_at: string(date-time)

400Invalid request or structurally invalid DNS/certificate data.
401Authentication is required.
403The active role lacks the required permission.
409Duplicate, referenced, stale, or conflicting idempotent request.
503Deployment credential encryption is not configured.

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

PATCH /v1/dns/providers/{id}

Update provider metadata or replace encrypted credentials

operationId
updateDNSProvider
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

参数

updateDNSProvider 参数
名称位置类型必填说明
idpathstring(uuid)是—
Idempotency-Keyheaderstring是—

请求体

application/json · 必填：是

updateDNSProvider 请求体
名称类型必填说明
expected_versioninteger(int64)是—
namestring是—
remarkstring否备注; omitted keeps the stored remark
statusstring: unverified / disabled是unverified means enabled: without new credentials a verified provider stays verified (renaming or a remark change keeps the verification); with new credentials it becomes unverified; disabled disables it.
credentialsobject否To pass verification, replacement credentials must match the existing provider type. Cloudflare requires only api_token; Aliyun requires only access_key_id and access_key_secret; Huawei Cloud requires only access_key, secret_key, region, and project_id; DNSPod CN requires only dp_id and dp_key; DNS.COM requires only api_key and api_secret; DNS.LA requires only api_id and api_secret; Name.com requires only username and api_token; custom_http requires only endpoint and secret.

响应

updateDNSProvider 响应
状态码说明
200Updated provider metadata.

字段：id: string(uuid) scope_id: string(uuid) name: string remark?: string provider_type: string: aliyun / cloudflare / huawei / dnspod_cn / dns_com / dns_la / namecom / custom_http / dnsdun credentials_configured: boolean status: string: unverified / verified / disabled managed_by?: string: tenant / platform version: integer(int64) created_at: string(date-time) updated_at: string(date-time)

400Invalid request or structurally invalid DNS/certificate data.
401Authentication is required.
403The active role lacks the required permission.
404Resource absent or hidden by tenant isolation.
409Duplicate, referenced, stale, or conflicting idempotent request.
503Deployment credential encryption is not configured.

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

DELETE /v1/dns/providers/{id}

Delete an unreferenced DNS provider configuration

operationId
deleteDNSProvider
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

参数

deleteDNSProvider 参数
名称位置类型必填说明
idpathstring(uuid)是—
Idempotency-Keyheaderstring是—
If-Matchheaderstring是Quoted positive resource version.

响应

deleteDNSProvider 响应
状态码说明
204Provider deleted.
400Invalid request or structurally invalid DNS/certificate data.
401Authentication is required.
403The active role lacks the required permission.
404Resource absent or hidden by tenant isolation.
409Duplicate, referenced, stale, or conflicting idempotent request.

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。

↑ 回到列表

POST /v1/dns/providers/{id}/verify

Verify a DNS provider credential against its upstream API

operationId
verifyDNSProvider
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

说明（契约原文）

Requires dns.manage in the active scope, an empty request body, a quoted If-Match revision, and an Idempotency-Key. The first implemented adapter verifies a Cloudflare API Token with GET /user/tokens/verify. A verified result proves token activity only; it does not prove zone-specific permissions, mutate DNS records, or start ACME issuance. Deterministic denials are audited and idempotently replayed. Rate limits, timeouts, upstream failures, and invalid upstream responses leave the provider unchanged and the key retryable.

参数

verifyDNSProvider 参数
名称位置类型必填说明
idpathstring(uuid)是Tenant-scoped DNS provider UUID.
Idempotency-Keyheaderstring是—
If-Matchheaderstring是—

响应

verifyDNSProvider 响应
状态码说明
200The token is active and the provider is now verified, or an identical completed request was replayed.

字段：id: string(uuid) scope_id: string(uuid) name: string provider_type: string: aliyun / cloudflare / huawei / dnspod_cn / dns_com / dns_la / namecom / custom_http / dnsdun credentials_configured: boolean status: string: unverified / verified / disabled managed_by?: string: tenant / platform version: integer(int64) created_at: string(date-time) updated_at: string(date-time)

400请求体或参数不合法。
401认证失败或会话已失效。
403当前身份没有执行该操作的权限。
404请求的资源不存在。
409请求的状态与已有资源或幂等记录冲突。
422Stable deterministic denial: provider_verification_unsupported, provider_credentials_invalid, provider_token_inactive, or provider_credentials_rejected.
429The provider rate limited verification. Retry-After is returned only when the upstream value was valid.
502The provider returned an oversized, malformed, or otherwise unexpected response.
503A required dependency is unavailable.
504Provider verification exceeded the bounded request timeout.
500服务内部故障，请求未完成。

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 429 被限速：等待后再试，降低并发。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

GET /v1/dns/records

List structured records in a zone

operationId
listDNSRecords
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

参数

listDNSRecords 参数
名称位置类型必填说明
zone_idquerystring(uuid)是—

响应

listDNSRecords 响应
状态码说明
200Draft records visible in the authenticated scope.

字段：items: array<Record>

400Invalid request or structurally invalid DNS/certificate data.
401Authentication is required.
403The active role lacks the required permission.

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。

↑ 回到列表

POST /v1/dns/records

Create a validated draft DNS record

operationId
createDNSRecord
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

参数

createDNSRecord 参数
名称位置类型必填说明
Idempotency-Keyheaderstring是—

请求体

application/json · 必填：是

createDNSRecord 请求体
名称类型必填说明
target_scope_idstring(uuid)否—
zone_idstring(uuid)是—
namestring是—
typestring: A / AAAA / CNAME / TXT是—
contentstring是—
ttlinteger是—

响应

createDNSRecord 响应
状态码说明
201Draft created; the provider has not been called.

字段：id: string(uuid) scope_id: string(uuid) zone_id: string(uuid) name: string type: string: A / AAAA / CNAME / TXT content: string ttl: integer status: string: draft / failed version: integer(int64) created_at: string(date-time) updated_at: string(date-time)

400Invalid request or structurally invalid DNS/certificate data.
401Authentication is required.
403The active role lacks the required permission.
404Resource absent or hidden by tenant isolation.
409Duplicate, referenced, stale, or conflicting idempotent request.

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。

↑ 回到列表

PATCH /v1/dns/records/{id}

Update a validated draft DNS record

operationId
updateDNSRecord
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

参数

updateDNSRecord 参数
名称位置类型必填说明
idpathstring(uuid)是—
Idempotency-Keyheaderstring是—

请求体

application/json · 必填：是

updateDNSRecord 请求体
名称类型必填说明
expected_versioninteger(int64)是—
namestring是—
typestring: A / AAAA / CNAME / TXT是—
contentstring是—
ttlinteger是—

响应

updateDNSRecord 响应
状态码说明
200Updated draft record.

字段：id: string(uuid) scope_id: string(uuid) zone_id: string(uuid) name: string type: string: A / AAAA / CNAME / TXT content: string ttl: integer status: string: draft / failed version: integer(int64) created_at: string(date-time) updated_at: string(date-time)

400Invalid request or structurally invalid DNS/certificate data.
401Authentication is required.
403The active role lacks the required permission.
404Resource absent or hidden by tenant isolation.
409Duplicate, referenced, stale, or conflicting idempotent request.

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。

↑ 回到列表

DELETE /v1/dns/records/{id}

Delete a draft DNS record

operationId
deleteDNSRecord
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

参数

deleteDNSRecord 参数
名称位置类型必填说明
idpathstring(uuid)是—
Idempotency-Keyheaderstring是—
If-Matchheaderstring是Quoted positive resource version.

响应

deleteDNSRecord 响应
状态码说明
204Record deleted.
400Invalid request or structurally invalid DNS/certificate data.
401Authentication is required.
403The active role lacks the required permission.
404Resource absent or hidden by tenant isolation.
409Duplicate, referenced, stale, or conflicting idempotent request.

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。

↑ 回到列表

GET /v1/dns/settings

Read the DNS settings for the active tenant scope

operationId
getDNSSettings
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

全部需要：dns.read

响应

getDNSSettings 响应
状态码说明
200Scope-level DNS TTL. Provider secrets are never returned.

字段：scope_id: string(uuid) ttl: integer version: integer(int64) updated_at?: string(date-time)

401认证失败或会话已失效。
403当前身份没有执行该操作的权限。
503A required dependency is unavailable.

失败时怎么办

  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

PATCH /v1/dns/settings

Update the compatibility DNS TTL with compare-and-swap semantics

operationId
updateDNSSettings
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

全部需要：dns.manage

参数

updateDNSSettings 参数
名称位置类型必填说明
Idempotency-Keyheaderstring是—
If-Matchheaderstring是—

请求体

application/json · 必填：是

updateDNSSettings 请求体
名称类型必填说明
ttlinteger是—

响应

updateDNSSettings 响应
状态码说明
200Updated scope-level DNS TTL.

字段：scope_id: string(uuid) ttl: integer version: integer(int64) updated_at?: string(date-time)

400请求体或参数不合法。
401认证失败或会话已失效。
403当前身份没有执行该操作的权限。
409请求的状态与已有资源或幂等记录冲突。
503A required dependency is unavailable.

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

GET /v1/dns/settings/operations/{operation_id}

Read a DNS DNS operation status

operationId
getDNSOperation
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

全部需要：dns.read

参数

getDNSOperation 参数
名称位置类型必填说明
operation_idpathstring(uuid)是—

响应

getDNSOperation 响应
状态码说明
200Current durable operation state.

字段：id: string(uuid) kind: string: dns.repair.v1 / dns.cleanup.v1 subject: string state: string: queued / running / succeeded / partial_failed / failed / cancelled attempt: integer max_attempts: integer progress: object last_error_code?: string created_at: string(date-time) started_at?: string(date-time) updated_at: string(date-time) completed_at?: string(date-time)

400请求体或参数不合法。
401认证失败或会话已失效。
403当前身份没有执行该操作的权限。
404请求的资源不存在。
503A required dependency is unavailable.

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/dns/settings/{kind}

Enqueue record repair or CDN-unrelated record cleanup

operationId
enqueueDNSOperation
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

全部需要：dns.manage

参数

enqueueDNSOperation 参数
名称位置类型必填说明
kindpathstring: repair / cleanup是—
Idempotency-Keyheaderstring是—

请求体

application/json · 必填：是

响应

enqueueDNSOperation 响应
状态码说明
202Durable background job accepted; no provider mutation is reported until a worker completes it.

字段：operation: DNSOperation replayed: boolean

400请求体或参数不合法。
401认证失败或会话已失效。
403当前身份没有执行该操作的权限。
409请求的状态与已有资源或幂等记录冲突。
503A required dependency is unavailable.

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

GET /v1/dns/zones

List DNS zones

operationId
listDNSZones
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

响应

listDNSZones 响应
状态码说明
200Zones visible in the authenticated scope.

字段：items: array<Zone>

401Authentication is required.
403The active role lacks the required permission.

失败时怎么办

  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。

↑ 回到列表

POST /v1/dns/zones

Create a draft DNS zone

operationId
createDNSZone
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

参数

createDNSZone 参数
名称位置类型必填说明
Idempotency-Keyheaderstring是—

请求体

application/json · 必填：是

createDNSZone 请求体
名称类型必填说明
target_scope_idstring(uuid)否—
provider_idstring(uuid)是—
namestring是—

响应

createDNSZone 响应
状态码说明
201Draft created; the provider has not been called.

字段：id: string(uuid) scope_id: string(uuid) provider_id: string(uuid) name: string status: string: draft / failed version: integer(int64) created_at: string(date-time) updated_at: string(date-time)

400Invalid request or structurally invalid DNS/certificate data.
401Authentication is required.
403The active role lacks the required permission.
404Resource absent or hidden by tenant isolation.
409Duplicate, referenced, stale, or conflicting idempotent request.

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。

↑ 回到列表

DELETE /v1/dns/zones/{id}

Delete an unreferenced draft DNS zone

operationId
deleteDNSZone
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

参数

deleteDNSZone 参数
名称位置类型必填说明
idpathstring(uuid)是—
Idempotency-Keyheaderstring是—
If-Matchheaderstring是Quoted positive resource version.

响应

deleteDNSZone 响应
状态码说明
204Zone deleted.
400Invalid request or structurally invalid DNS/certificate data.
401Authentication is required.
403The active role lacks the required permission.
404Resource absent or hidden by tenant isolation.
409Duplicate, referenced, stale, or conflicting idempotent request.

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。

↑ 回到列表