Operation details
GET /v1/admin/cache-operations
List operations in an explicit tenant scope
- operationId
listAdminCacheOperations- 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
listAdminCacheOperations Parameters| Name | In | Type | Required | Description |
|---|
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. |
|---|
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
listAdminCacheOperations 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/admin/cache-operations
Persist an operation in an explicit tenant scope
- operationId
createAdminCacheOperation- 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)
queued means persisted, not dispatched.
Parameters
createAdminCacheOperation Parameters| Name | In | Type | Required | Description |
|---|
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
createAdminCacheOperation 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
createAdminCacheOperation 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/admin/cache-operations/daily-usage
Today's cache operation quotas of a tenant account (UTC+8 day; system follow-ups not counted)
- operationId
getAdminCacheDailyUsage- 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
getAdminCacheDailyUsage Parameters| Name | In | Type | Required | Description |
|---|
scope_id | query | string(uuid) | Yes | Explicit active tenant scope; platform scope is never implied. |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Responses
getAdminCacheDailyUsage 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
PUT /v1/admin/cache-operations/daily-usage
Set a tenant account's own daily purge/prewarm limits (null follows the system setting default)
- operationId
setAdminCacheAccountLimits- 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：identity.users.manage
Description (from the contract)
Audited as cache.account_quota.update. Every key is required; a stale expected_revision (the revision of the last read) is 412.
Parameters
setAdminCacheAccountLimits Parameters| Name | In | Type | Required | Description |
|---|
scope_id | query | string(uuid) | Yes | Explicit active tenant scope; platform scope is never implied. |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
setAdminCacheAccountLimits Request body| Name | Type | Required | Description |
|---|
expected_revision | integer | Yes | — |
|---|
url_purge_limit | integer | null | Yes | — |
|---|
directory_purge_limit | integer | null | Yes | — |
|---|
prewarm_limit | integer | null | Yes | — |
|---|
Responses
setAdminCacheAccountLimits Responses| Status | Description |
|---|
200 | The account's quotas after the change. 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. |
|---|
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.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-operations/{operation_id}
Get operation progress in an explicit tenant scope
- operationId
getAdminCacheOperation- 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
getAdminCacheOperation Parameters| Name | In | Type | Required | Description |
|---|
operation_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
getAdminCacheOperation 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/admin/cache-operations/{operation_id}/cancel
Cancel an operation in an explicit tenant scope
- operationId
cancelAdminCacheOperation- 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
cancelAdminCacheOperation Parameters| Name | In | Type | Required | Description |
|---|
operation_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
Responses
cancelAdminCacheOperation 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/admin/cache-operations/{operation_id}/resubmit
Re-submit an operation as a new one
- operationId
resubmitAdminCacheOperation- 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
resubmitAdminCacheOperation Parameters| Name | In | Type | Required | Description |
|---|
operation_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
Responses
resubmitAdminCacheOperation 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/admin/cache-operations/{operation_id}/retry
Retry an operation in an explicit tenant scope
- operationId
retryAdminCacheOperation- 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
retryAdminCacheOperation Parameters| Name | In | Type | Required | Description |
|---|
operation_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
Responses
retryAdminCacheOperation 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