Operation details
GET /v1/admin/control-upgrade-rollouts
List durable control upgrade rollouts
- operationId
listControlUpgradeRollouts- 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：control.upgrades.read
Description (from the contract)
Requires a platform-scoped identity with control.upgrades.read. The response is ordered by created_at descending and id descending. Unknown or repeated query parameters are rejected.
Parameters
listControlUpgradeRollouts Parameters| Name | In | Type | Required | Description |
|---|
page | query | integer | No | — |
|---|
page_size | query | integer | No | — |
|---|
state | query | string: queued / canary / running / paused / rolling_back / completed / failed | No | — |
|---|
node_id | query | string(uuid) | No | — |
|---|
Responses
listControlUpgradeRollouts Responses| Status | Description |
|---|
200 | A page of rollout summaries. Fields：data: array<ControlUpgradeRolloutSummary> page: integer page_size: integer total: integer(int64) |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
503 | A required 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/control-upgrade-rollouts
Create a durable control upgrade rollout
- operationId
createControlUpgradeRollout- 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：control.upgrades.manage
Description (from the contract)
Requires control.upgrades.manage in a platform scope. The canonical request freezes the sorted target cohort, canary subset, batch size, and mandatory automatic rollback. A replay rechecks live RBAC and returns the original durable snapshot without another license call or NATS publication. A changed request under the same idempotency key returns 409.
Parameters
createControlUpgradeRollout Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
createControlUpgradeRollout Request body| Name | Type | Required | Description |
|---|
schema | string | Yes | — |
|---|
node_ids | array<string(uuid)> | Yes | Canonical lowercase UUIDs in strictly increasing byte order. |
|---|
canary_node_ids | array<string(uuid)> | Yes | One or two strictly sorted canonical UUIDs, each also present in node_ids. |
|---|
batch_size | integer | Yes | — |
|---|
automatic_rollback | boolean | Yes | — |
|---|
Responses
createControlUpgradeRollout Responses| Status | Description |
|---|
201 | The rollout was created or replayed. Fields：data: ControlUpgradeRolloutDetail replayed: boolean |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
409 | The requested state conflicts with an existing resource or idempotency fact. |
|---|
413 | The request body exceeds the one MiB limit. |
|---|
415 | Content-Type must be exactly application/json without parameters. |
|---|
503 | A required 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/control-upgrade-rollouts/{rollout_id}
Get a durable control upgrade rollout
- operationId
getControlUpgradeRollout- 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：control.upgrades.read
Description (from the contract)
Requires control.upgrades.read in a platform scope.
Parameters
getControlUpgradeRollout Parameters| Name | In | Type | Required | Description |
|---|
rollout_id | path | string(uuid) | Yes | — |
|---|
Responses
getControlUpgradeRollout Responses| Status | Description |
|---|
200 | The rollout summary, batches, nodes, ordered state events, and durable status broker receipts. Fields：data: ControlUpgradeRolloutDetail |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
503 | A required 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/control-upgrade-rollouts/{rollout_id}/pause
Pause a running control upgrade rollout
- operationId
pauseControlUpgradeRollout- 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：control.upgrades.manage
Description (from the contract)
Requires control.upgrades.manage and a current expected revision.
Parameters
pauseControlUpgradeRollout Parameters| Name | In | Type | Required | Description |
|---|
rollout_id | path | string(uuid) | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
pauseControlUpgradeRollout Request body| Name | Type | Required | Description |
|---|
expected_revision | string | Yes | Canonical decimal uint63 in the inclusive range 1..9223372036854775807. |
|---|
reason | string | Yes | — |
|---|
Responses
pauseControlUpgradeRollout Responses| Status | Description |
|---|
200 | The rollout transition committed, or the exact durable result was replayed. Fields：data: ControlUpgradeRolloutDetail replayed: boolean |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
409 | The requested state conflicts with an existing resource or idempotency fact. |
|---|
413 | The request body exceeds the one MiB limit. |
|---|
415 | Content-Type must be exactly application/json without parameters. |
|---|
503 | A required 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
POST /v1/admin/control-upgrade-rollouts/{rollout_id}/resume
Resume a paused control upgrade rollout
- operationId
resumeControlUpgradeRollout- 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：control.upgrades.manage
Description (from the contract)
Requires control.upgrades.manage and a current expected revision.
Parameters
resumeControlUpgradeRollout Parameters| Name | In | Type | Required | Description |
|---|
rollout_id | path | string(uuid) | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
resumeControlUpgradeRollout Request body| Name | Type | Required | Description |
|---|
expected_revision | string | Yes | Canonical decimal uint63 in the inclusive range 1..9223372036854775807. |
|---|
reason | string | Yes | — |
|---|
Responses
resumeControlUpgradeRollout Responses| Status | Description |
|---|
200 | The rollout transition committed, or the exact durable result was replayed. Fields：data: ControlUpgradeRolloutDetail replayed: boolean |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
409 | The requested state conflicts with an existing resource or idempotency fact. |
|---|
413 | The request body exceeds the one MiB limit. |
|---|
415 | Content-Type must be exactly application/json without parameters. |
|---|
503 | A required 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
POST /v1/admin/control-upgrade-rollouts/{rollout_id}/rollback
Roll back a control upgrade rollout
- operationId
rollbackControlUpgradeRollout- 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：control.upgrades.manage
Description (from the contract)
Requires control.upgrades.manage and a current expected revision. Rollback remains blocked for irreversible migrations, missing rollback artifacts, or an in-flight dispatched batch.
Parameters
rollbackControlUpgradeRollout Parameters| Name | In | Type | Required | Description |
|---|
rollout_id | path | string(uuid) | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
rollbackControlUpgradeRollout Request body| Name | Type | Required | Description |
|---|
expected_revision | string | Yes | Canonical decimal uint63 in the inclusive range 1..9223372036854775807. |
|---|
reason | string | Yes | — |
|---|
Responses
rollbackControlUpgradeRollout Responses| Status | Description |
|---|
200 | The rollout transition committed, or the exact durable result was replayed. Fields：data: ControlUpgradeRolloutDetail replayed: boolean |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
409 | The requested state conflicts with an existing resource or idempotency fact. |
|---|
413 | The request body exceeds the one MiB limit. |
|---|
415 | Content-Type must be exactly application/json without parameters. |
|---|
503 | A required 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
POST /v1/admin/control-upgrade-rollouts/{rollout_id}/start
Start a queued control upgrade rollout
- operationId
startControlUpgradeRollout- 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：control.upgrades.manage
Description (from the contract)
Requires control.upgrades.manage and a current expected revision.
Parameters
startControlUpgradeRollout Parameters| Name | In | Type | Required | Description |
|---|
rollout_id | path | string(uuid) | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
startControlUpgradeRollout Request body| Name | Type | Required | Description |
|---|
expected_revision | string | Yes | Canonical decimal uint63 in the inclusive range 1..9223372036854775807. |
|---|
reason | string | Yes | — |
|---|
Responses
startControlUpgradeRollout Responses| Status | Description |
|---|
200 | The rollout transition committed, or the exact durable result was replayed. Fields：data: ControlUpgradeRolloutDetail replayed: boolean |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
409 | The requested state conflicts with an existing resource or idempotency fact. |
|---|
413 | The request body exceeds the one MiB limit. |
|---|
415 | Content-Type must be exactly application/json without parameters. |
|---|
503 | A required 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