Operation details
GET /v1/admin/site-rollouts
List rollouts for one tenant scope
- operationId
listAdminSiteRollouts- 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：edge_publications.read
Parameters
listAdminSiteRollouts Parameters| Name | In | Type | Required | Description |
|---|
scope_id | query | string(uuid) | Yes | Platform route target tenant access-scope UUID. |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string | No | Versioned base64url HMAC-SHA256 envelope returned by the immediately preceding page. It is bound to audience, resolved tenant scope, resource kind, and the rollout ID for deployment pages. It cannot be reused across those boundaries or modified. |
|---|
Responses
listAdminSiteRollouts Responses| Status | Description |
|---|
200 | Stable platform rollout page. Fields：items: array<AdminRollout> next_cursor?: string |
|---|
400 | Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | Wrong audience, missing permission, or tenant scope override. |
|---|
503 | Storage, signing, cancellation, response validation, or another internal dependency is unavailable. |
|---|
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/site-rollouts/reconciliations
Record the configuration proven to be active after an uncertain deployment result
- operationId
reconcileAdminNodeConfiguration- 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：edge_publications.manage
Description (from the contract)
Clears the rollback_failed reconciliation gate only when the named node, tenant scope, source deployment attempt, and observed immutable config all match persisted facts. It also permits operator-confirmed recovery of a legacy failed apply only when the deployment artifact, previous identity, fresh mTLS heartbeat pointer chain, missing current/loaded identity, stopped conservative OpenResty projection, and absence of active deployments all agree. That recovery moves only the version pointers; the next healthy publication establishes the current immutable identity. The append-only reconciliation record, live IAM authorization, node-state update, and audit event commit atomically. Retrying with the same Idempotency-Key returns the same fact; changing the payload with that key returns 409.
Parameters
reconcileAdminNodeConfiguration Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | Stable for the frozen business payload. Request, correlation, trace, and task identifiers may change on an identical retry. |
|---|
X-Request-ID | header | string(uuid) | Yes | — |
|---|
Traceparent | header | string | Yes | — |
|---|
X-Correlation-ID | header | string(uuid) | No | Defaults to X-Request-ID when omitted. |
|---|
X-Task-ID | header | string | No | — |
|---|
Request body
application/json · Required：Yes
reconcileAdminNodeConfiguration Request body| Name | Type | Required | Description |
|---|
configuration_scope_id | string(uuid) | Yes | — |
|---|
node_id | string(uuid) | Yes | — |
|---|
source_deployment_id | string(uuid) | Yes | — |
|---|
source_deployment_attempt | integer(int32) | Yes | — |
|---|
observed_config_version_id | string(uuid) | null | Yes | — |
|---|
resolution | string: agent_observed / operator_confirmed | Yes | — |
|---|
evidence | string | Yes | — |
|---|
Responses
reconcileAdminNodeConfiguration Responses| Status | Description |
|---|
201 | Created reconciliation fact, or the stored result of an identical retry. Fields：id: string(uuid) node_id: string(uuid) configuration_scope_id: string(uuid) source_deployment_id: string(uuid) source_deployment_attempt: integer(int32) previous_config_version_id: string(uuid) | null current_config_version_id: string(uuid) | null resolution: string: agent_observed / operator_confirmed reconciliation_required: boolean reconciled_at: string(date-time) |
|---|
400 | Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | Wrong audience, missing permission, or tenant scope override. |
|---|
404 | Resource is absent in the authorized tenant scope. Cross-tenant IDs use the same response. |
|---|
409 | Idempotency, target snapshot, rollout state, active deployment, or retry conflict. |
|---|
503 | Storage, signing, cancellation, response validation, or another internal dependency is unavailable. |
|---|
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/site-rollouts/{rollout_id}
Get deterministic rollout progress for one tenant scope
- operationId
getAdminSiteRollout- 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：edge_publications.read
Parameters
getAdminSiteRollout Parameters| Name | In | Type | Required | Description |
|---|
rollout_id | path | string(uuid) | Yes | — |
|---|
scope_id | query | string(uuid) | Yes | Platform route target tenant access-scope UUID. |
|---|
Responses
getAdminSiteRollout Responses| Status | Description |
|---|
200 | Platform rollout detail derived from latest deployment attempts. Fields：id: string(uuid) configuration_scope_id: string(uuid) config_version_id: string(uuid) action: string: apply / rollback state: string: queued / running / paused / succeeded / partial_failed / failed / cancelled revision: integer(int64) max_attempts: integer progress: RolloutProgress can_cancel: boolean can_retry: boolean can_start?: boolean can_pause?: boolean can_resume?: boolean rollout?: RolloutPolicyView pause_reason?: string: / operator / failure_threshold created_at: string(date-time) updated_at: string(date-time) replayed?: boolean |
|---|
400 | Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | Wrong audience, missing permission, or tenant scope override. |
|---|
404 | Resource is absent in the authorized tenant scope. Cross-tenant IDs use the same response. |
|---|
503 | Storage, signing, cancellation, response validation, or another internal dependency is unavailable. |
|---|
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/site-rollouts/{rollout_id}/cancel
Cancel queued work in a rollout
- operationId
cancelSiteRollout- 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：edge_publications.manage
Description (from the contract)
Progressive cancellation marks held or unclaimed commands and their queued deployment facts cancelled; already claimed or in-flight work may still report durable terminal facts. Legacy rollouts retain their all-pending precondition. Uses rollout revision CAS and idempotency.
Parameters
cancelSiteRollout Parameters| Name | In | Type | Required | Description |
|---|
rollout_id | path | string(uuid) | Yes | — |
|---|
Idempotency-Key | header | string | Yes | Stable for the frozen business payload. Request, correlation, trace, and task identifiers may change on an identical retry. |
|---|
X-Request-ID | header | string(uuid) | Yes | — |
|---|
Traceparent | header | string | Yes | — |
|---|
X-Correlation-ID | header | string(uuid) | No | Defaults to X-Request-ID when omitted. |
|---|
X-Task-ID | header | string | No | — |
|---|
Request body
application/json · Required：Yes
cancelSiteRollout Request body| Name | Type | Required | Description |
|---|
configuration_scope_id | string(uuid) | Yes | — |
|---|
expected_revision | integer(int64) | Yes | — |
|---|
Responses
cancelSiteRollout Responses| Status | Description |
|---|
200 | Updated rollout, or the stored result of an identical command retry. Fields：id: string(uuid) configuration_scope_id: string(uuid) config_version_id: string(uuid) action: string: apply / rollback state: string: queued / running / paused / succeeded / partial_failed / failed / cancelled revision: integer(int64) max_attempts: integer progress: RolloutProgress can_cancel: boolean can_retry: boolean can_start?: boolean can_pause?: boolean can_resume?: boolean rollout?: RolloutPolicyView pause_reason?: string: / operator / failure_threshold created_at: string(date-time) updated_at: string(date-time) replayed?: boolean |
|---|
400 | Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | Wrong audience, missing permission, or tenant scope override. |
|---|
404 | Resource is absent in the authorized tenant scope. Cross-tenant IDs use the same response. |
|---|
409 | Idempotency, target snapshot, rollout state, active deployment, or retry conflict. |
|---|
412 | The source or rollout expected revision is stale. |
|---|
503 | Storage, signing, cancellation, response validation, or another internal dependency is unavailable. |
|---|
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/site-rollouts/{rollout_id}/deployments
List latest per-node deployment attempts
- operationId
listAdminSiteRolloutDeployments- 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：edge_publications.read
Parameters
listAdminSiteRolloutDeployments Parameters| Name | In | Type | Required | Description |
|---|
rollout_id | path | string(uuid) | Yes | — |
|---|
scope_id | query | string(uuid) | Yes | Platform route target tenant access-scope UUID. |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string | No | Versioned base64url HMAC-SHA256 envelope returned by the immediately preceding page. It is bound to audience, resolved tenant scope, resource kind, and the rollout ID for deployment pages. It cannot be reused across those boundaries or modified. |
|---|
Responses
listAdminSiteRolloutDeployments Responses| Status | Description |
|---|
200 | Latest deployment attempt for each targeted node. Fields：items: array<AdminDeployment> next_cursor?: string |
|---|
400 | Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | Wrong audience, missing permission, or tenant scope override. |
|---|
404 | Resource is absent in the authorized tenant scope. Cross-tenant IDs use the same response. |
|---|
503 | Storage, signing, cancellation, response validation, or another internal dependency is unavailable. |
|---|
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/site-rollouts/{rollout_id}/pause
Pause a running progressive rollout
- operationId
pauseSiteRollout- 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：edge_publications.manage
Description (from the contract)
Re-holds commands in the released cohort that have not been claimed. Status reports already in flight remain durable facts but cannot release another cohort while the rollout is paused.
Parameters
pauseSiteRollout Parameters| Name | In | Type | Required | Description |
|---|
rollout_id | path | string(uuid) | Yes | — |
|---|
Idempotency-Key | header | string | Yes | Stable for the frozen business payload. Request, correlation, trace, and task identifiers may change on an identical retry. |
|---|
X-Request-ID | header | string(uuid) | Yes | — |
|---|
Traceparent | header | string | Yes | — |
|---|
X-Correlation-ID | header | string(uuid) | No | Defaults to X-Request-ID when omitted. |
|---|
X-Task-ID | header | string | No | — |
|---|
Request body
application/json · Required：Yes
pauseSiteRollout Request body| Name | Type | Required | Description |
|---|
configuration_scope_id | string(uuid) | Yes | — |
|---|
expected_revision | integer(int64) | Yes | — |
|---|
Responses
pauseSiteRollout Responses| Status | Description |
|---|
200 | Updated rollout, or the stored result of an identical command retry. Fields：id: string(uuid) configuration_scope_id: string(uuid) config_version_id: string(uuid) action: string: apply / rollback state: string: queued / running / paused / succeeded / partial_failed / failed / cancelled revision: integer(int64) max_attempts: integer progress: RolloutProgress can_cancel: boolean can_retry: boolean can_start?: boolean can_pause?: boolean can_resume?: boolean rollout?: RolloutPolicyView pause_reason?: string: / operator / failure_threshold created_at: string(date-time) updated_at: string(date-time) replayed?: boolean |
|---|
400 | Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | Wrong audience, missing permission, or tenant scope override. |
|---|
404 | Resource is absent in the authorized tenant scope. Cross-tenant IDs use the same response. |
|---|
409 | Idempotency, target snapshot, rollout state, active deployment, or retry conflict. |
|---|
412 | The source or rollout expected revision is stale. |
|---|
503 | Storage, signing, cancellation, response validation, or another internal dependency is unavailable. |
|---|
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
POST /v1/admin/site-rollouts/{rollout_id}/resume
Resume a paused progressive rollout
- operationId
resumeSiteRollout- 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：edge_publications.manage
Description (from the contract)
Recomputes the current cohort under the rollout lock. If it is terminal, the next cohort alone is released or the rollout becomes terminal; otherwise remaining held commands in the current cohort are released.
Parameters
resumeSiteRollout Parameters| Name | In | Type | Required | Description |
|---|
rollout_id | path | string(uuid) | Yes | — |
|---|
Idempotency-Key | header | string | Yes | Stable for the frozen business payload. Request, correlation, trace, and task identifiers may change on an identical retry. |
|---|
X-Request-ID | header | string(uuid) | Yes | — |
|---|
Traceparent | header | string | Yes | — |
|---|
X-Correlation-ID | header | string(uuid) | No | Defaults to X-Request-ID when omitted. |
|---|
X-Task-ID | header | string | No | — |
|---|
Request body
application/json · Required：Yes
resumeSiteRollout Request body| Name | Type | Required | Description |
|---|
configuration_scope_id | string(uuid) | Yes | — |
|---|
expected_revision | integer(int64) | Yes | — |
|---|
Responses
resumeSiteRollout Responses| Status | Description |
|---|
200 | Updated rollout, or the stored result of an identical command retry. Fields：id: string(uuid) configuration_scope_id: string(uuid) config_version_id: string(uuid) action: string: apply / rollback state: string: queued / running / paused / succeeded / partial_failed / failed / cancelled revision: integer(int64) max_attempts: integer progress: RolloutProgress can_cancel: boolean can_retry: boolean can_start?: boolean can_pause?: boolean can_resume?: boolean rollout?: RolloutPolicyView pause_reason?: string: / operator / failure_threshold created_at: string(date-time) updated_at: string(date-time) replayed?: boolean |
|---|
400 | Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | Wrong audience, missing permission, or tenant scope override. |
|---|
404 | Resource is absent in the authorized tenant scope. Cross-tenant IDs use the same response. |
|---|
409 | Idempotency, target snapshot, rollout state, active deployment, or retry conflict. |
|---|
412 | The source or rollout expected revision is stale. |
|---|
503 | Storage, signing, cancellation, response validation, or another internal dependency is unavailable. |
|---|
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
POST /v1/admin/site-rollouts/{rollout_id}/retry-failed
Append attempts for retryable failed deployments
- operationId
retryFailedSiteRolloutDeployments- 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：edge_publications.manage
Description (from the contract)
Only failed or rollback_failed latest attempts below max_attempts are retried. Existing attempts and artifact bindings remain immutable. The original rollout deadline remains authoritative; at or after that deadline can_retry is false and retry returns 409.
Parameters
retryFailedSiteRolloutDeployments Parameters| Name | In | Type | Required | Description |
|---|
rollout_id | path | string(uuid) | Yes | — |
|---|
Idempotency-Key | header | string | Yes | Stable for the frozen business payload. Request, correlation, trace, and task identifiers may change on an identical retry. |
|---|
X-Request-ID | header | string(uuid) | Yes | — |
|---|
Traceparent | header | string | Yes | — |
|---|
X-Correlation-ID | header | string(uuid) | No | Defaults to X-Request-ID when omitted. |
|---|
X-Task-ID | header | string | No | — |
|---|
Request body
application/json · Required：Yes
retryFailedSiteRolloutDeployments Request body| Name | Type | Required | Description |
|---|
configuration_scope_id | string(uuid) | Yes | — |
|---|
expected_revision | integer(int64) | Yes | — |
|---|
Responses
retryFailedSiteRolloutDeployments Responses| Status | Description |
|---|
200 | Updated rollout, or the stored result of an identical command retry. Fields：id: string(uuid) configuration_scope_id: string(uuid) config_version_id: string(uuid) action: string: apply / rollback state: string: queued / running / paused / succeeded / partial_failed / failed / cancelled revision: integer(int64) max_attempts: integer progress: RolloutProgress can_cancel: boolean can_retry: boolean can_start?: boolean can_pause?: boolean can_resume?: boolean rollout?: RolloutPolicyView pause_reason?: string: / operator / failure_threshold created_at: string(date-time) updated_at: string(date-time) replayed?: boolean |
|---|
400 | Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | Wrong audience, missing permission, or tenant scope override. |
|---|
404 | Resource is absent in the authorized tenant scope. Cross-tenant IDs use the same response. |
|---|
409 | Idempotency, target snapshot, rollout state, active deployment, or retry conflict. |
|---|
412 | The source or rollout expected revision is stale. |
|---|
503 | Storage, signing, cancellation, response validation, or another internal dependency is unavailable. |
|---|
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
POST /v1/admin/site-rollouts/{rollout_id}/start
Start a held progressive rollout
- operationId
startSiteRollout- 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：edge_publications.manage
Description (from the contract)
Releases only frozen cohort zero. Target membership and cohort assignment were fixed at publication time by ascending UUID bytes; later inventory changes cannot alter the rollout. Uses rollout revision CAS and domain idempotency.
Parameters
startSiteRollout Parameters| Name | In | Type | Required | Description |
|---|
rollout_id | path | string(uuid) | Yes | — |
|---|
Idempotency-Key | header | string | Yes | Stable for the frozen business payload. Request, correlation, trace, and task identifiers may change on an identical retry. |
|---|
X-Request-ID | header | string(uuid) | Yes | — |
|---|
Traceparent | header | string | Yes | — |
|---|
X-Correlation-ID | header | string(uuid) | No | Defaults to X-Request-ID when omitted. |
|---|
X-Task-ID | header | string | No | — |
|---|
Request body
application/json · Required：Yes
startSiteRollout Request body| Name | Type | Required | Description |
|---|
configuration_scope_id | string(uuid) | Yes | — |
|---|
expected_revision | integer(int64) | Yes | — |
|---|
Responses
startSiteRollout Responses| Status | Description |
|---|
200 | Updated rollout, or the stored result of an identical command retry. Fields：id: string(uuid) configuration_scope_id: string(uuid) config_version_id: string(uuid) action: string: apply / rollback state: string: queued / running / paused / succeeded / partial_failed / failed / cancelled revision: integer(int64) max_attempts: integer progress: RolloutProgress can_cancel: boolean can_retry: boolean can_start?: boolean can_pause?: boolean can_resume?: boolean rollout?: RolloutPolicyView pause_reason?: string: / operator / failure_threshold created_at: string(date-time) updated_at: string(date-time) replayed?: boolean |
|---|
400 | Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | Wrong audience, missing permission, or tenant scope override. |
|---|
404 | Resource is absent in the authorized tenant scope. Cross-tenant IDs use the same response. |
|---|
409 | Idempotency, target snapshot, rollout state, active deployment, or retry conflict. |
|---|
412 | The source or rollout expected revision is stale. |
|---|
503 | Storage, signing, cancellation, response validation, or another internal dependency is unavailable. |
|---|
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