/v1/dns

GET /v1/dns/platform-config

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

operationId

getPlatformDNSConfig

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Responses

What to do on failure

• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.

↑ Back to list

PUT /v1/dns/platform-config

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

operationId

savePlatformDNSConfig

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Parameters

Request body

application/json · Required：Yes

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

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

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

operationId

testPlatformDNSConnection

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Description (from the contract)

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).

Request body

application/json · Required：Yes

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
• 429 Rate limited: wait, then retry with lower concurrency.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

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

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

operationId

startPlatformDNSOperation

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Description (from the contract)

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 系统管理 > 后台任务.

Parameters

Request body

application/json · Required：Yes

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.

↑ Back to list

GET /v1/dns/platform-zones

List the CNAME domains (CNAME域名)

operationId

listPlatformDNSZones

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.

↑ Back to list

POST /v1/dns/platform-zones

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

operationId

createPlatformDNSZone

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Parameters

Request body

application/json · Required：Yes

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.

↑ Back to list

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

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

operationId

updatePlatformDNSZone

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Parameters

Request body

application/json · Required：Yes

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 404 The resource does not exist or belongs to another tenant.
• 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.

↑ Back to list

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

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 404 The resource does not exist or belongs to another tenant.
• 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.

↑ Back to list

GET /v1/dns/providers

List DNS provider configurations

operationId

listDNSProviders

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Description (from the contract)

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.

Parameters

Responses

What to do on failure

• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.

↑ Back to list

POST /v1/dns/providers

Store an encrypted DNS provider configuration

operationId

createDNSProvider

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Parameters

Request body

application/json · Required：Yes

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

PATCH /v1/dns/providers/{id}

Update provider metadata or replace encrypted credentials

operationId

updateDNSProvider

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Parameters

Request body

application/json · Required：Yes

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 404 The resource does not exist or belongs to another tenant.
• 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

DELETE /v1/dns/providers/{id}

Delete an unreferenced DNS provider configuration

operationId

deleteDNSProvider

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 404 The resource does not exist or belongs to another tenant.
• 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.

↑ Back to list

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

Verify a DNS provider credential against its upstream API

operationId

verifyDNSProvider

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Description (from the contract)

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.

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 404 The resource does not exist or belongs to another tenant.
• 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
• 429 Rate limited: wait, then retry with lower concurrency.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list

GET /v1/dns/records

List structured records in a zone

operationId

listDNSRecords

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.

↑ Back to list

POST /v1/dns/records

Create a validated draft DNS record

operationId

createDNSRecord

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Parameters

Request body

application/json · Required：Yes

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 404 The resource does not exist or belongs to another tenant.
• 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.

↑ Back to list

PATCH /v1/dns/records/{id}

Update a validated draft DNS record

operationId

updateDNSRecord

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Parameters

Request body

application/json · Required：Yes

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 404 The resource does not exist or belongs to another tenant.
• 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.

↑ Back to list

DELETE /v1/dns/records/{id}

Delete a draft DNS record

operationId

deleteDNSRecord

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 404 The resource does not exist or belongs to another tenant.
• 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.

↑ Back to list

GET /v1/dns/settings

Read the DNS settings for the active tenant scope

operationId

getDNSSettings

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：dns.read

Responses

What to do on failure

• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

PATCH /v1/dns/settings

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

operationId

updateDNSSettings

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：dns.manage

Parameters

Request body

application/json · Required：Yes

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

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

Read a DNS DNS operation status

operationId

getDNSOperation

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：dns.read

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 404 The resource does not exist or belongs to another tenant.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

POST /v1/dns/settings/{kind}

Enqueue record repair or CDN-unrelated record cleanup

operationId

enqueueDNSOperation

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：dns.manage

Parameters

Request body

application/json · Required：Yes

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/dns/zones

List DNS zones

operationId

listDNSZones

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Responses

What to do on failure

• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.

↑ Back to list

POST /v1/dns/zones

Create a draft DNS zone

operationId

createDNSZone

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Parameters

Request body

application/json · Required：Yes

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 404 The resource does not exist or belongs to another tenant.
• 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.

↑ Back to list

DELETE /v1/dns/zones/{id}

Delete an unreferenced draft DNS zone

operationId

deleteDNSZone

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 404 The resource does not exist or belongs to another tenant.
• 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.

↑ Back to list