cdnca

API reference

/v1/cache-policies

4 operations

← All groups · First call? Read the tutorial: auth, permissions, requests and responses, common failures

MethodPathSummaryAuth
GET/v1/cache-policies/{site_id}Get the current cache policy for a tenant siteSession
POST/v1/cache-policies/{site_id}Publish an immutable cache-policy revision with CASSession
GET/v1/cache-policies/{site_id}/revisionsList immutable policy history in the tenant scopeSession
GET/v1/cache-policies/{site_id}/revisions/{revision}Get one immutable policy revision in the tenant scopeSession

Contract file：api/control-cache-operations.openapi.yaml

Operation details

GET /v1/cache-policies/{site_id}

Get the current cache policy for a tenant site

operationId
getTenantCurrentCachePolicy
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

Parameters

getTenantCurrentCachePolicy Parameters
NameInTypeRequiredDescription
site_idpathstring(uuid)Yes—
X-Request-IDheaderstringYes—

Responses

getTenantCurrentCachePolicy Responses
StatusDescription
200Cache policy revision.

Fields：site_id: string(uuid) revision: integer(int64) binding_mode: string: inherit / override definition_id: string(uuid) definition_revision: integer(int64) document: PolicyDocumentV1 | PolicyDocumentV2 created_by_user_id: string(uuid) request_id: string created_at: string(date-time)

400Invalid or non-canonical request.
401Authentication required.
403Exact cache permission is absent or route audience is wrong.
404Resource is absent or outside the effective tenant scope.
408Request context was cancelled or exceeded its deadline.
503A required store is unavailable; raw dependency errors are never returned.

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/cache-policies/{site_id}

Publish an immutable cache-policy revision with CAS

operationId
publishTenantCachePolicy
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

Parameters

publishTenantCachePolicy Parameters
NameInTypeRequiredDescription
site_idpathstring(uuid)Yes—
X-Request-IDheaderstringYes—
Idempotency-KeyheaderstringYes—

Request body

application/json · Required：Yes

publishTenantCachePolicy Request body
NameTypeRequiredDescription
expected_revisioninteger(int64)Yes—
binding_modeobjectNoOmit for the simple per-site override workflow.
definition_idstring(uuid)No—
definition_revisioninteger(int64)No—
expected_definition_revisioninteger(int64)No—
documentPolicyDocumentV1 | PolicyDocumentV2No—

Responses

publishTenantCachePolicy Responses
StatusDescription
201Created revision or stored identical replay.

Fields：site_id: string(uuid) revision: integer(int64) binding_mode: string: inherit / override definition_id: string(uuid) definition_revision: integer(int64) document: PolicyDocumentV1 | PolicyDocumentV2 created_by_user_id: string(uuid) request_id: string created_at: string(date-time)

400Invalid or non-canonical request.
401Authentication required.
403Exact cache permission is absent or route audience is wrong.
404Resource is absent or outside the effective tenant scope.
408Request context was cancelled or exceeded its deadline.
409Idempotency payload or operation state conflicts.
412expected_revision no longer matches the current head.
503A required store is unavailable; raw dependency errors are never returned.

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/cache-policies/{site_id}/revisions

List immutable policy history in the tenant scope

operationId
listTenantCachePolicyRevisions
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

Parameters

listTenantCachePolicyRevisions Parameters
NameInTypeRequiredDescription
site_idpathstring(uuid)Yes—
X-Request-IDheaderstringYes—
limitqueryintegerNo—
cursorquerystringNoHMAC-authenticated cursor bound to scope, filters, and a committed creation-audit watermark. It freezes membership, not mutable operation state or progress.

Responses

listTenantCachePolicyRevisions Responses
StatusDescription
200Stable revision page.

Fields：items: array<Policy> next_cursor?: string

400Invalid or non-canonical request.
401Authentication required.
403Exact cache permission is absent or route audience is wrong.
404Resource is absent or outside the effective tenant scope.
408Request context was cancelled or exceeded its deadline.
503A required store is unavailable; raw dependency errors are never returned.

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

GET /v1/cache-policies/{site_id}/revisions/{revision}

Get one immutable policy revision in the tenant scope

operationId
getTenantCachePolicyRevision
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

Parameters

getTenantCachePolicyRevision Parameters
NameInTypeRequiredDescription
site_idpathstring(uuid)Yes—
revisionpathinteger(int64)Yes—
X-Request-IDheaderstringYes—

Responses

getTenantCachePolicyRevision Responses
StatusDescription
200Cache policy revision.

Fields：site_id: string(uuid) revision: integer(int64) binding_mode: string: inherit / override definition_id: string(uuid) definition_revision: integer(int64) document: PolicyDocumentV1 | PolicyDocumentV2 created_by_user_id: string(uuid) request_id: string created_at: string(date-time)

400Invalid or non-canonical request.
401Authentication required.
403Exact cache permission is absent or route audience is wrong.
404Resource is absent or outside the effective tenant scope.
408Request context was cancelled or exceeded its deadline.
503A required store is unavailable; raw dependency errors are never returned.

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