MethodPathSummaryAuth
GET/v1/site-defaults网站列表 > 默认设置 (the caller's defaults for new sites)Session
POST/v1/site-defaultsAdd a site defaultSession
PATCH/v1/site-defaults/{id}Change a site default's value or enable / disable itSession
DELETE/v1/site-defaults/{id}Delete a site defaultSession

Contract file:api/openapi/v1/sites.yaml

Operation details

GET /v1/site-defaults

网站列表 > 默认设置 (the caller's defaults for new sites)

operationId
listSiteDefaults
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. A tenant sees only its own scope. Defaults fill the fields a new site's create request leaves out; group rows win over global ones; existing sites are never changed.

Parameters

listSiteDefaults Parameters
NameInTypeRequiredDescription
pagequeryintegerNo—
limitqueryintegerNo—
setting_namequerystringNo—
enabledquerybooleanNo—

Responses

listSiteDefaults Responses
StatusDescription
200One page.

Fields:items: array<SiteUserDefault> total: integer(int64) page: integer limit: integer

400Invalid JSON, field, or query input.
401Authentication is required.
403The principal lacks sites.read or sites.manage.
500The operation failed without exposing internal details.

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/site-defaults

Add a site default

operationId
createSiteDefault
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. 409 site_default_conflict: the setting already has a default in the same scope (global, or the same group).

Parameters

createSiteDefault Parameters
NameInTypeRequiredDescription
Idempotency-KeyheaderstringYesStable per-actor key. Reuse with different normalized input returns 409 idempotency_conflict.

Request body

application/json · Required:Yes

createSiteDefault Request body
NameTypeRequiredDescription
target_scope_idstring(uuid)Noplatform only
owner_idstring(uuid)Noplatform only
setting_namestringYesPorts are space separated; balance_way is round_robin, ip_hash, url_hash, least_conn or random; backend_https_port 1-65535; ups_keepalive_timeout seconds 1-300; cc_ban_seconds 1-86400 and cc_pass_seconds 60-604800 (filled into a new CC policy that names none); dns_provider is the ID of a verified DNS account of the scope (checked when saved; a create that names none uses it when the creator has dns.manage, and skips the records if it is no longer usable); cc_policy, waf_policy and acl_policy are the ID of one of the owner's own rule libraries of that kind (not a subscribed one; checked when saved), copied into a library of the new site's own and bound to it in the create (later changes of the library or the default leave existing sites alone; a library gone by then, or a package without the feature, skips the copy); block_proxy 1 adds rules blocking requests with a Via, X-Forwarded-For or Forwarded header to the new site's WAF library (identified by proxy headers: users behind a corporate proxy are blocked too); req_header is one "Name: value" per line (up to 8192 characters), set on requests to the origin; post_size_limit is the upload limit in MB 1-1024 (client_max_body_size). req_header and post_size_limit become the new site's HTTP policy when the creator has http_policies.manage; http2, http3 and ssl_prefer_server_ciphers fill the new site's http2_enabled, http3_enabled and tls_prefer_server_ciphers; proxy_cache is a cache policy document (JSON, the document of /v1/cache-policies/{site_id}; up to 65536 characters) written as the new site's first cache policy revision in the create; cond_origin is {"routes": [...]} of conditional origin rules (as the site's conditional origin document) whose pool_id is the placeholder "@default", replaced by the new site's own default origin pool (no origin addresses are stored); block_region is abrord_inc (block outside mainland China, Hong Kong, Macao and Taiwan included), abrord_no_inc (outside CN/HK/MO/TW), china_inc (CN, HK, MO and TW), china_not_inc (CN only) or none, the competitor's values: a preset adds one WAF rule on the client's country (by the node's IP intelligence library) to the new site's WAF library as block_proxy does, none adds nothing; ssl_cipher_preset is modern, compatible, legacy or custom; ssl_cipher_suites is the custom preset's colon-separated suite list (the same whitelist and rules as the site's tls_cipher_suites), and a custom ssl_cipher_preset applies to a new site only together with it; the rest are 1 (on) or 0 (off).
setting_valuestringYesat most 256, req_header 8192, proxy_cache and cond_origin 65536
scope_namestring: global / groupNo—
group_idstring(uuid) | null(uuid)Norequired when scope_name is group

Responses

createSiteDefault Responses
StatusDescription
201Created.

Fields:id: string(uuid) display_id: string scope_id: string(uuid) owner_user_id: string(uuid) setting_name: string setting_value: string scope_name: string: global / group group_id: string(uuid) | null(uuid) group_name: string | null enabled: boolean version: integer(int64) created_at: string(date-time) updated_at: string(date-time)

400Invalid JSON, field, or query input.
401Authentication is required.
403The principal lacks sites.read or sites.manage.
409Domain, version, idempotency, website lock-state, or origin-section conflict.
500The operation failed without exposing internal details.

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

PATCH /v1/site-defaults/{id}

Change a site default's value or enable / disable it

operationId
updateSiteDefault
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; another tenant's ID is 404.

Parameters

updateSiteDefault Parameters
NameInTypeRequiredDescription
idpathstring(uuid)Yes—
Idempotency-KeyheaderstringYesStable per-actor key. Reuse with different normalized input returns 409 idempotency_conflict.

Request body

application/json · Required:Yes

updateSiteDefault Request body
NameTypeRequiredDescription
expected_versioninteger(int64)Yes—
setting_valuestringNoat most 256, req_header 8192, proxy_cache and cond_origin 65536
enabledbooleanNo—

Responses

updateSiteDefault Responses
StatusDescription
200Updated.

Fields:id: string(uuid) display_id: string scope_id: string(uuid) owner_user_id: string(uuid) setting_name: string setting_value: string scope_name: string: global / group group_id: string(uuid) | null(uuid) group_name: string | null enabled: boolean version: integer(int64) created_at: string(date-time) updated_at: string(date-time)

400Invalid JSON, field, or query input.
401Authentication is required.
403The principal lacks sites.read or sites.manage.
404The site is absent, deleted, or outside the tenant scope.
409Domain, version, idempotency, website lock-state, or origin-section conflict.
500The operation failed without exposing internal details.

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/site-defaults/{id}

Delete a site default

operationId
deleteSiteDefault
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; another tenant's ID is 404.

Parameters

deleteSiteDefault Parameters
NameInTypeRequiredDescription
idpathstring(uuid)Yes—
Idempotency-KeyheaderstringYesStable per-actor key. Reuse with different normalized input returns 409 idempotency_conflict.

Responses

deleteSiteDefault Responses
StatusDescription
204Deleted.
400Invalid JSON, field, or query input.
401Authentication is required.
403The principal lacks sites.read or sites.manage.
404The site is absent, deleted, or outside the tenant scope.
500The operation failed without exposing internal details.

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