Operation details
GET /v1/cache-operations
List cache operations in a stable tenant snapshot
- operationId
listTenantCacheOperations- 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)
The cursor freezes the set of operations whose committed creation audit position is at or below the first page watermark. Mutable state, progress, and update/completion timestamps remain live on later pages.
Parameters
listTenantCacheOperations Parameters| Name | In | Type | Required | Description |
|---|
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. |
|---|
site_id | query | string(uuid) | No | Non-disclosing filter within the effective tenant scope. A foreign or nonexistent UUID returns the same 200 response with an empty items array. |
|---|
site_display_id | query | string | No | Tenant-scoped stable positive site identifier displayed by the UI. |
|---|
search | query | string | No | Exact operation/site short ID or a case-insensitive target URL fragment. |
|---|
action | query | string: purge / prewarm | No | — |
|---|
target_type | query | string: exact_url / directory_prefix / whole_site | No | — |
|---|
state | query | string | No | One state or several, comma separated (any of them). |
|---|
Responses
listTenantCacheOperations Responses| Status | Description |
|---|
200 | Stable operation page. Fields：items: array<OperationSummary> next_cursor?: string state_counts?: object |
|---|
400 | Invalid or non-canonical request. |
|---|
401 | Authentication required. |
|---|
403 | Exact cache permission is absent or route audience is wrong. |
|---|
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.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/cache-operations
Persist a purge or prewarm operation
- operationId
createTenantCacheOperation- 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)
Returns 202 after the operation and node/target projections are committed. queued never means that a node command was dispatched. Unknown results must be retried with the same Idempotency-Key and body.
Parameters
createTenantCacheOperation Parameters| Name | In | Type | Required | Description |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
createTenantCacheOperation Request body| Name | Type | Required | Description |
|---|
site_id | string(uuid) | Yes | — |
|---|
action | string: purge / prewarm | Yes | — |
|---|
target_type | string: exact_url / directory_prefix / whole_site | Yes | — |
|---|
targets | array<string(uri)> | Yes | Edge cachetask schema v2 wire envelope. At most 16 targets, each at most 16 KiB of UTF-8 bytes, with at most 64 KiB of raw target bytes across the array. The aggregate byte limit is enforced by the server in addition to this JSON Schema. |
|---|
node_ids | array<string(uuid)> | Yes | — |
|---|
max_retries | integer | Yes | — |
|---|
Responses
createTenantCacheOperation Responses| Status | Description |
|---|
202 | Durable operation accepted in queued state; no delivery is implied. Fields：id: string(uuid) display_id: string site_id: string(uuid) site_display_id: string action: string: purge / prewarm target_type: string: exact_url / directory_prefix / whole_site state: string: queued / running / succeeded / partial_failed / failed / cancelled max_attempts: integer progress: Progress auto_nodes: boolean parent_operation_id?: string(uuid) targets: array<Target> nodes: array<NodeProjection> cancel_requested_at?: string(date-time) created_at: string(date-time) started_at?: string(date-time) updated_at: string(date-time) completed_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. |
|---|
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.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/cache-operations/daily-usage
Today's cache operation quotas of the caller's account (UTC+8 day; system follow-ups not counted)
- operationId
getTenantCacheDailyUsage- 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)
Quotas count per account (tenant scope): the owner and its members share them across all its sites. A platform administrator's submissions on the tenant's behalf are neither counted nor refused (still audited as the administrator).
Parameters
getTenantCacheDailyUsage Parameters| Name | In | Type | Required | Description |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Responses
getTenantCacheDailyUsage Responses| Status | Description |
|---|
200 | The same limits and counts a create is checked against. Fields：scope_id: string(uuid) revision: integer url_purge: CacheDailyQuota directory_purge: object prewarm: CacheDailyQuota resets_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
GET /v1/cache-operations/{operation_id}
Get sanitized per-node operation progress
- operationId
getTenantCacheOperation- 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
getTenantCacheOperation Parameters| Name | In | Type | Required | Description |
|---|
operation_id | path | string(uuid) | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Responses
getTenantCacheOperation Responses| Status | Description |
|---|
200 | Sanitized cache operation. Fields：id: string(uuid) display_id: string site_id: string(uuid) site_display_id: string action: string: purge / prewarm target_type: string: exact_url / directory_prefix / whole_site state: string: queued / running / succeeded / partial_failed / failed / cancelled max_attempts: integer progress: Progress auto_nodes: boolean parent_operation_id?: string(uuid) targets: array<Target> nodes: array<NodeProjection> cancel_requested_at?: string(date-time) created_at: string(date-time) started_at?: string(date-time) updated_at: string(date-time) completed_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/cache-operations/{operation_id}/cancel
Cancel a queued or running cache operation
- operationId
cancelTenantCacheOperation- 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
cancelTenantCacheOperation Parameters| Name | In | Type | Required | Description |
|---|
operation_id | path | string(uuid) | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
Responses
cancelTenantCacheOperation Responses| Status | Description |
|---|
200 | Sanitized cache operation. Fields：id: string(uuid) display_id: string site_id: string(uuid) site_display_id: string action: string: purge / prewarm target_type: string: exact_url / directory_prefix / whole_site state: string: queued / running / succeeded / partial_failed / failed / cancelled max_attempts: integer progress: Progress auto_nodes: boolean parent_operation_id?: string(uuid) targets: array<Target> nodes: array<NodeProjection> cancel_requested_at?: string(date-time) created_at: string(date-time) started_at?: string(date-time) updated_at: string(date-time) completed_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. |
|---|
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.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/cache-operations/{operation_id}/resubmit
Re-submit an operation as a new one
- operationId
resubmitTenantCacheOperation- 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)
Creates a new operation with the original's site, action, target type, targets and retry budget, on the nodes the original named, or on every node carrying the site now when it named none (auto_nodes). The Idempotency-Key is the batch key: with the original operation it forms the new operation's idempotency key, so a retry of one batch replays (Idempotency-Replayed) and another batch creates another operation. Audited as cache.operation.resubmit on the original operation.
Parameters
resubmitTenantCacheOperation Parameters| Name | In | Type | Required | Description |
|---|
operation_id | path | string(uuid) | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
Responses
resubmitTenantCacheOperation Responses| Status | Description |
|---|
202 | Durable operation accepted in queued state; no delivery is implied. Fields：id: string(uuid) display_id: string site_id: string(uuid) site_display_id: string action: string: purge / prewarm target_type: string: exact_url / directory_prefix / whole_site state: string: queued / running / succeeded / partial_failed / failed / cancelled max_attempts: integer progress: Progress auto_nodes: boolean parent_operation_id?: string(uuid) targets: array<Target> nodes: array<NodeProjection> cancel_requested_at?: string(date-time) created_at: string(date-time) started_at?: string(date-time) updated_at: string(date-time) completed_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. |
|---|
429 | The account's daily purge or prewarm limit would be exceeded (daily_limit_exceeded; error.details names the quota). |
|---|
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.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/cache-operations/{operation_id}/retry
Requeue retryable failed projections only
- operationId
retryTenantCacheOperation- 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
retryTenantCacheOperation Parameters| Name | In | Type | Required | Description |
|---|
operation_id | path | string(uuid) | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
Responses
retryTenantCacheOperation Responses| Status | Description |
|---|
200 | Sanitized cache operation. Fields：id: string(uuid) display_id: string site_id: string(uuid) site_display_id: string action: string: purge / prewarm target_type: string: exact_url / directory_prefix / whole_site state: string: queued / running / succeeded / partial_failed / failed / cancelled max_attempts: integer progress: Progress auto_nodes: boolean parent_operation_id?: string(uuid) targets: array<Target> nodes: array<NodeProjection> cancel_requested_at?: string(date-time) created_at: string(date-time) started_at?: string(date-time) updated_at: string(date-time) completed_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. |
|---|
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.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list