/v1/sites

GET /v1/sites

List websites visible in the authenticated scope

operationId

listSites

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)

Platform administrators can list all tenant scopes. Tenant principals are always restricted by the server to their active tenant scope, and owner and region are redacted in their response. The owner, region_id, and node_group_id filters are platform-only to prevent count-based disclosure of redacted metadata.

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.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list

POST /v1/sites

Create a website

operationId

createSite

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 sites.manage and Idempotency-Key. A platform principal must provide target_scope_id and owner_id. A tenant principal is forced to its active scope and own user ID even if those fields are supplied.

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.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list

POST /v1/sites/batch-action

Enable, disable, soft-delete, queue CNAME regeneration for, or set the HTTPS protocols of websites

operationId

batchSiteAction

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 sites.manage and Idempotency-Key. The response preserves input order while rows are locked in UUID order. Business failures are reported per item and do not undo successful items; a database or audit failure rolls back the complete batch. Tenant principals see resources outside their active scope as site_not_found. Tenant actions against a platform-locked site fail with site_locked, while platform principals retain maintenance access. Enable performs the same local entitlement feature, state, and domains.count checks as a single website update. Disable and delete remain available while entitlement is in grace or expired state. These actions change control-plane desired state only and do not claim that an edge configuration has been activated. regenerate_cname applies only to failed CNAME allocations, requires sites.manage and dns.manage, and transactionally creates one durable CNAME job per accepted site. Its per-item result is queued; the returned site.cname_task_id is the durable task identity and site.cname_state remains pending until provider reconciliation plus authoritative and public recursive convergence completes. set_protocols (网站协议批量设置) writes basic.http2_enabled, basic.http3_enabled and basic.tls_prefer_server_ciphers of each selected site at its expected_version, as a single-site basic update would; keys left out of protocols keep each site's value. Each changed site records site.tls_profile.update, and every scope with an updated site queues its automatic publication (site.update). Its per-item result is updated.

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.
• 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/sites/export

Export an immutable snapshot of site domains

operationId

exportSiteDomains

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 sites.export. Tenant principals are restricted to their active tenant scope. Platform principals must provide target_scope_id. The response is a UTF-8 CSV produced from an immutable, actor- and filter-bound snapshot; cells that could be interpreted as spreadsheet formulas are escaped.

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.
• 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/sites/{id}

Get one website and its basic settings

operationId

getSite

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.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list

PATCH /v1/sites/{id}

Replace the complete basic or origin settings section

operationId

updateSiteSettings

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)

section=basic and section=origin are writable discriminated variants. expected_version is a shared optimistic concurrency guard, so basic and origin writes against one website serialize on the same version. The complete selected section is required. Origin writes update control-plane desired state and the legacy basic.origins compatibility projection in one transaction; no edge configuration is generated or activated in this slice. A basic write may preserve an identical rich origin projection, but replacing origins while non-default origin metadata exists returns 409 origin_section_conflict. Identical retries require the same normalized payload and Idempotency-Key.

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.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list

DELETE /v1/sites/{id}

Soft-delete a website

operationId

deleteSite

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.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list

POST /v1/sites/{id}/access-check

接入状态 > 立即检查 (resolve the site's domains now)

operationId

checkSiteAccess

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 sites.read. Resolves every domain of the site through the control plane host's resolver now (no DNS provider or third-party API), stores the result as the background check does and returns the site's access_readiness. Once a minute per site: 429 access_check_throttled with Retry-After (seconds) within the minute.

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.
• 429 Rate limited: wait, then retry with lower concurrency.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list

POST /v1/sites/{id}/auto-dns/sync

解析检测 > 同步解析 (run the site's automatic DNS records again)

operationId

syncSiteAutoDNS

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 sites.manage and dns.manage. Resets the site's auto_dns task to pending (creating it with provider_id when the site has none) and returns at once; the records are written in the background. Repeating the call is harmless. 422 dns_provider_unusable: not a verified account of the site owner.

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.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list

POST /v1/sites/{id}/lock

Lock a website against tenant writes

operationId

lockSite

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 sites.manage in a platform scope. The expected version is checked atomically. Locking changes only control-plane lock metadata and the website version; it does not disable or republish the active edge configuration. Tenant edit, enable/disable, and delete attempts return 409 site_locked until a platform administrator unlocks the site.

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.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list

POST /v1/sites/{id}/origin-failback

Switch the pool back to the highest healthy level (manual failback)

operationId

failbackSiteOrigin

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 sites.manage and Idempotency-Key. Moves the active level to the lowest-numbered level that is healthy (the primary when it is), records site.origin.failback and republishes the site. 409 origin_failback_unavailable: no higher level is healthy.

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.
• 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.
• 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/sites/{id}/origin-routing

Get the normalized conditional origin-routing document

operationId

getSiteOriginRouting

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 sites.read. Tenant principals can only read sites in their active scope. The document is ordered deterministically and represents control-plane desired state, not proof of edge activation. The response-only effective_retry and effective_l2_fallback objects expose the fixed fail-safe edge retry and L1-to-L2 direct-origin fallback guards. These guards are not caller-configurable and do not indicate that L2 routing is enabled for this site.

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.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list

PUT /v1/sites/{id}/origin-routing

Replace the complete conditional origin-routing document

operationId

replaceSiteOriginRouting

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 sites.manage, Idempotency-Key, and a strong If-Match value for the shared site version. The update, idempotency claim, automatic edge publication request, and site.origin_route.update audit event commit in one transaction. Identical semantic input is normalized before the idempotency digest is calculated. effective_retry and effective_l2_fallback are response-only and are rejected if supplied in this request document.

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.
• 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/sites/{id}/origin-status

Origin pool probe state and the active origin level

operationId

getSiteOriginStatus

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 sites.read. The control plane probes every origin of the pool (origin address with the pool's origin Host / SNI and health check path, from the tenant's own nodes when they can, else from the control plane). An origin is unhealthy after 3 consecutive failures, healthy after 2 consecutive successes, unknown before that or when it cannot be probed. Aggregated edge scheduling reads overall.

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.
• 404 The resource does not exist or belongs to another tenant.
• 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/sites/{id}/schedule302

Get the site's HTTP 302 scheduling settings

operationId

getSiteSchedule302

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 sites.read. HTTP 302 scheduling (together with DNS scheduling) lets the node a visitor reaches redirect large downloads and video to the best node for the visitor's carrier and region. Disabled sites return the default settings with enabled false. plain_http reports whether the site has a plain HTTP port, which scheduling needs.

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.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list

PUT /v1/sites/{id}/schedule302

Replace the site's HTTP 302 scheduling settings

operationId

replaceSiteSchedule302

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 sites.manage, Idempotency-Key, and a strong If-Match value for the shared site version. The update, idempotency claim, automatic edge publication request and the site.schedule302.update audit event commit in one transaction; a refused write records the event with result denied and a reason code. Turning scheduling off deletes the settings and the site's signing key. 422 schedule302_no_plain_http: the site has no plain HTTP port.

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.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list

POST /v1/sites/{id}/transfer

Move a website to another user

operationId

transferSite

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 sites.manage in a platform scope held by a platform administrator. In one transaction the website is re-created in the target user's tenant (new website ID, newly allocated CNAME) and the current website is deleted; the old CNAME retires by the delete rules and the customer must repoint DNS from from_cname to the new site's CNAME. Historical statistics, logs and bills stay with the previous owner. The target is another active user with a tenant of its own; target_package_subscription_id is one of that user's own package subscriptions, or null for no package. copied lists what was carried to the new website and released what the administrator must configure again; item names are http_policy, cache_policy, certificate, waf_policy, cc_policy, acl_policy, auto_defense and js_challenge (automatic DNS records are not moved). Without a carried certificate HTTPS is off on the new website. Errors: 422 site_transfer_target_invalid (target is not an active user with its own tenant, or is the current owner), 422 domain_blocked, 409 domain_verified_by_other (an apex is verified by another account, including the previous owner; domain ownership is not transferred), 409 domain_ownership_required, 409 site_locked, 409 version_conflict (stale expected_version) and 409 idempotency_conflict. Domain errors carry the refused domain and apex.

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.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list

POST /v1/sites/{id}/unlock

Restore tenant write access to a website

operationId

unlockSite

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 sites.manage in a platform scope. The expected version is checked atomically and the previous lock metadata is cleared. Existing edge traffic and operational website status are not changed.

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.
• 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/sites/{site_id}/access

Get a site's request handling settings

operationId

getSiteAccess

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：sites.read

Description (from the contract)

Basic auth users are returned by name only; passwords are never stored or returned. Tenant principals only reach sites of their scope. ETag is the site version.

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.

↑ Back to list

PUT /v1/sites/{site_id}/access

Replace a site's request handling settings

operationId

replaceSiteAccess

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：sites.manage

Description (from the contract)

Replaces every setting; an absent or null setting is off, and all off removes the site's row. A basic auth user without password keeps its stored secret (SHA-256 of site_id:username:password). HSTS and a forced HTTPS status other than 301 or excluded domains need the site's HTTPS. The write advances the site version: a manual scope shows it pending, an automatic scope publishes it. The write and its site.access.update audit event (changes, no secrets) commit together; a refused write is audited as denied with its reason code.

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

GET /v1/sites/{site_id}/certificate-binding

Get the active certificate binding for one site

operationId

getCertificateSiteBinding

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：certificates.read

Description (from the contract)

Returns the current bound fact and its active immutable certificate version in one tenant-scoped read. An unbound site returns the stable certificate_site_binding_not_found error code.

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.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list

POST /v1/sites/{site_id}/dns-reconcile/apply

Persist and enqueue a DNS reconciliation task

operationId

applyDNSReconciliation

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

Description (from the contract)

Requires dns.manage and a live DNS reconciliation entitlement. The authenticated tenant, site path, idempotency key, canonical payload digest, and provider revision form the durable command identity. A same-key retry with a different payload returns 409.

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.
• 412 The revision changed: read the latest ETag, decide again, then send the new If-Match.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

POST /v1/sites/{site_id}/dns-reconcile/dry-run

Build a deterministic repair plan without provider side effects

operationId

dryRunDNSReconciliation

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

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.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/sites/{site_id}/dns-reconcile/tasks/{task_id}

Read one durable DNS reconciliation task

operationId

getDNSReconciliationTask

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

Description (from the contract)

Requires dns.read. Unknown, cross-tenant, and task/site mismatches all return the same 404 response. Tenant scope is never accepted from a path, query parameter, or request body.

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/sites/{site_id}/dns-reconcile/tasks/{task_id}/cancel

Persist a cancellation request for a DNS reconciliation task

operationId

cancelDNSReconciliationTask

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.
• 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.
• 412 The revision changed: read the latest ETag, decide again, then send the new If-Match.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

POST /v1/sites/{site_id}/dns-reconcile/tasks/{task_id}/commit

Delete superseded records after propagation is healthy

operationId

commitDNSReconciliationTask

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

Description (from the contract)

Requires dns.manage and a live DNS reconciliation entitlement. Commit rechecks convergence and provider revision before processing deferred deletes. Crash/retry reuses the same command identity and durable task.

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.
• 412 The revision changed: read the latest ETag, decide again, then send the new If-Match.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/sites/{site_id}/traffic-limit

Read a website's traffic caps and their enforcement (sites.read)

operationId

getSiteTrafficLimit

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

↑ Back to list

PUT /v1/sites/{site_id}/traffic-limit

Replace a website's traffic caps (sites.manage)

operationId

putSiteTrafficLimit

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