API reference

`/v1/admin/cache-policies`

4 operations

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

Method	Path	Summary	Auth
GET	`/v1/admin/cache-policies/{site_id}`	Get a current policy in an explicit tenant scope	Session
POST	`/v1/admin/cache-policies/{site_id}`	Publish a policy in an explicit tenant scope	Session
GET	`/v1/admin/cache-policies/{site_id}/revisions`	List policy history in an explicit tenant scope	Session
GET	`/v1/admin/cache-policies/{site_id}/revisions/{revision}`	Get one policy revision in an explicit tenant scope	Session

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

Operation details

GET `/v1/admin/cache-policies/{site_id}`

Get a current policy in an explicit tenant scope

operationId

getAdminCurrentCachePolicy

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

getAdminCurrentCachePolicy Parameters
Name	In	Type	Required	Description
`site_id`	path	`string(uuid)`	Yes	—
`scope_id`	query	`string(uuid)`	Yes	Explicit active tenant scope; platform scope is never implied.
`X-Request-ID`	header	`string`	Yes	—

Responses

getAdminCurrentCachePolicy Responses
Status	Description
`200`	Cache 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)`
`400`	Invalid or non-canonical request.
`401`	Authentication required.
`403`	Exact cache permission is absent or route audience is wrong.
`404`	Resource is absent or outside the effective tenant scope.
`408`	Request context was cancelled or exceeded its deadline.
`503`	A 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/admin/cache-policies/{site_id}`

Publish a policy in an explicit tenant scope

operationId

publishAdminCachePolicy

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

publishAdminCachePolicy Parameters
Name	In	Type	Required	Description
`site_id`	path	`string(uuid)`	Yes	—
`scope_id`	query	`string(uuid)`	Yes	Explicit active tenant scope; platform scope is never implied.
`X-Request-ID`	header	`string`	Yes	—
`Idempotency-Key`	header	`string`	Yes	—

Request body

application/json · Required：Yes

publishAdminCachePolicy Request body
Name	Type	Required	Description
`expected_revision`	`integer(int64)`	Yes	—
`binding_mode`	`object`	No	Omit for the simple per-site override workflow.
`definition_id`	`string(uuid)`	No	—
`definition_revision`	`integer(int64)`	No	—
`expected_definition_revision`	`integer(int64)`	No	—
`document`	`PolicyDocumentV1 \| PolicyDocumentV2`	No	—

Responses

publishAdminCachePolicy Responses
Status	Description
`201`	Created 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)`
`400`	Invalid or non-canonical request.
`401`	Authentication required.
`403`	Exact cache permission is absent or route audience is wrong.
`404`	Resource is absent or outside the effective tenant scope.
`408`	Request context was cancelled or exceeded its deadline.
`409`	Idempotency payload or operation state conflicts.
`412`	expected_revision no longer matches the current head.
`503`	A 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/admin/cache-policies/{site_id}/revisions`

List policy history in an explicit tenant scope

operationId

listAdminCachePolicyRevisions

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

listAdminCachePolicyRevisions Parameters
Name	In	Type	Required	Description
`site_id`	path	`string(uuid)`	Yes	—
`scope_id`	query	`string(uuid)`	Yes	Explicit active tenant scope; platform scope is never implied.
`X-Request-ID`	header	`string`	Yes	—
`limit`	query	`integer`	No	—
`cursor`	query	`string`	No	HMAC-authenticated cursor bound to scope, filters, and a committed creation-audit watermark. It freezes membership, not mutable operation state or progress.

Responses

listAdminCachePolicyRevisions Responses
Status	Description
`200`	Stable revision page. Fields：`items: array<Policy>` `next_cursor?: string`
`400`	Invalid or non-canonical request.
`401`	Authentication required.
`403`	Exact cache permission is absent or route audience is wrong.
`404`	Resource is absent or outside the effective tenant scope.
`408`	Request context was cancelled or exceeded its deadline.
`503`	A 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/admin/cache-policies/{site_id}/revisions/{revision}`

Get one policy revision in an explicit tenant scope

operationId

getAdminCachePolicyRevision

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

getAdminCachePolicyRevision Parameters
Name	In	Type	Required	Description
`site_id`	path	`string(uuid)`	Yes	—
`revision`	path	`integer(int64)`	Yes	—
`scope_id`	query	`string(uuid)`	Yes	Explicit active tenant scope; platform scope is never implied.
`X-Request-ID`	header	`string`	Yes	—

Responses

getAdminCachePolicyRevision Responses
Status	Description
`200`	Cache 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)`
`400`	Invalid or non-canonical request.
`401`	Authentication required.
`403`	Exact cache permission is absent or route audience is wrong.
`404`	Resource is absent or outside the effective tenant scope.
`408`	Request context was cancelled or exceeded its deadline.
`503`	A 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

/v1/admin/cache-policies

Operation details

GET /v1/admin/cache-policies/{site_id}

Parameters

Responses

What to do on failure

POST /v1/admin/cache-policies/{site_id}

Parameters

Request body

Responses

What to do on failure

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

Parameters

Responses

What to do on failure

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

Parameters

Responses

What to do on failure

`/v1/admin/cache-policies`

GET `/v1/admin/cache-policies/{site_id}`

POST `/v1/admin/cache-policies/{site_id}`

GET `/v1/admin/cache-policies/{site_id}/revisions`

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