Skip to content

Start a cluster upgrade path

POST
/clusters/{cluster_id}/upgrade-paths
curl --request POST \
  --url http://localhost:8000/clusters/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/upgrade-paths \
  --header 'API-Key: <API-Key>' \
  --header 'API-Version: 2026-06-01.beta' \
  --header 'Content-Type: application/json' \
  --data '{ "target_version": "26.5.5", "timing": "now", "force": true }'

Takes the cluster to target_version one version at a time, running every version of the upgrade path in order, either right now (timing: now) or one step per maintenance window (timing: maintenance_window).

Without force, a path with a breaking-change step or a major jump is refused up front with 422, and the body lists the blocking versions in blockers; the cluster is unchanged. With force: true those steps are accepted and the path is recorded in the audit log as forced. A step with an incompatible extension, or an inactive or quarantined version, refuses the request with or without force, naming the version and the extension.

A cluster holds one active path at a time. Returns 409 Conflict while the cluster already has an active path, is being upgraded, or has an upgrade queued.

A forced path can cross breaking changes with no rollback once the database has migrated. Use GET /clusters/{cluster_id}/upgrade-path-preview to see the path first.

Required scope: clusters:write

cluster_id
required
string format: uuid
API-Version
required
string
Allowed values: 2026-06-01.beta
Media typeapplication/json

Request to take a cluster to a target version, one version at a time.

object
target_version
required

Version the cluster should end on. Every version of the upgrade path up to it is run in order.

string
>= 1 characters <= 20 characters /^[0-9]+\.[0-9]+(\.[0-9]+)?$/
timing
required

When each step runs: now starts each step when the previous one is confirmed complete, maintenance_window runs one step per maintenance window.

string
Allowed values: now maintenance_window
force

Accept breaking changes and major version jumps. Does not override an incompatible extension or an inactive version. A forced path is recorded in the audit log. Defaults to false.

boolean

The request has been accepted for processing, but processing has not yet completed.

Media typeapplication/json

An upgrade path of a cluster.

object
id
required

Unique upgrade path identifier.

string
cluster_id
required

Cluster the path belongs to.

string format: uuid
from_version
required

Version the cluster ran when the path was requested.

string
>= 1 characters <= 20 characters /^[0-9]+\.[0-9]+(\.[0-9]+)?$/
target_version
required

Version the cluster should end on.

string
>= 1 characters <= 20 characters /^[0-9]+\.[0-9]+(\.[0-9]+)?$/
timing
required

When each step runs.

string
Allowed values: now maintenance_window
force
required

Whether breaking changes and major jumps were accepted.

boolean
status
required

Lifecycle of the path. One of: pending, running, completed, failed, cancelled. pending and running hold the cluster: no second path or manual upgrade is accepted.

string
reached_version
required

Last version the cluster confirmed running. When the path is cancelled it is the version at the moment of the cancel and is not updated if the step in progress then finishes.

string
>= 1 characters <= 20 characters /^[0-9]+\.[0-9]+(\.[0-9]+)?$/
in_progress_version

Version of the step in progress. Absent when no step is running. The version the cluster runs is reached_version.

string
>= 1 characters <= 20 characters /^[0-9]+\.[0-9]+(\.[0-9]+)?$/
steps
required

Every step of the path, in order.

Array<object>

One version a cluster moves through on an upgrade path.

object
version
required

Version of this step.

string
>= 1 characters <= 20 characters /^[0-9]+\.[0-9]+(\.[0-9]+)?$/
state
required

State of this step. One of: pending, running, done, failed, skipped. Cancelling a path leaves the step in progress as it is and marks every step that had not started skipped.

string
is_major_change
required

Whether moving onto this version crosses a major version boundary.

boolean
has_breaking_changes
required

Whether moving onto this version crosses recorded breaking changes.

boolean
failure_reason

Why the path stopped. Present when status is failed.

string
created_at
required

When the path was requested.

string format: date-time
finished_at

When the path completed, failed or was cancelled. Absent while it is active.

string format: date-time

Example

{
  "from_version": "26.5.5",
  "target_version": "26.5.5",
  "timing": "now",
  "reached_version": "26.5.5",
  "in_progress_version": "26.5.5",
  "steps": [
    {
      "version": "26.5.5"
    }
  ]
}

The server could not understand the request due to invalid syntax.

Media typeapplication/problem+json

RFC 9457 Problem Details object.

object
type
required
string format: uri
title
required
string
status
required
integer
detail
required
string
instance
string format: uri

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

Access is unauthorized.

Media typeapplication/problem+json

RFC 9457 Problem Details object.

object
type
required
string format: uri
title
required
string
status
required
integer
detail
required
string
instance
string format: uri

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

The server cannot find the requested resource.

Media typeapplication/problem+json

RFC 9457 Problem Details object.

object
type
required
string format: uri
title
required
string
status
required
integer
detail
required
string
instance
string format: uri

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

The request conflicts with the current state of the server.

Media typeapplication/problem+json

RFC 9457 Problem Details object.

object
type
required
string format: uri
title
required
string
status
required
integer
detail
required
string
instance
string format: uri

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

Client error

Media typeapplication/problem+json

Returned when an upgrade path cannot start. blockers lists the blocking versions.

object
type
required
string format: uri
title
required
string
status
required
integer
detail
required
string
instance
string format: uri
blockers
required

The versions that block the path and why. A blocker with overridable: true is accepted when force is set.

Array<object>

A reason a version on an upgrade path cannot be taken.

object
version
required

The blocking version.

string
>= 1 characters <= 20 characters /^[0-9]+\.[0-9]+(\.[0-9]+)?$/
kind
required

Why the version blocks the path. breaking_change and major_jump are accepted with force. extension (an installed extension has no compatible build for the step, or a TideCloak cluster has any extension) and inactive_version (the version is inactive or quarantined) are never overridden.

string
overridable
required

Whether force accepts this blocker.

boolean
detail
required

Human-readable detail.

string
extensions

Extensions behind an extension blocker.

Array<string>
breaking_changes

Titles of the breaking changes behind a breaking_change blocker.

Array<string>

Example

{
  "blockers": [
    {
      "version": "26.5.5"
    }
  ]
}

Client error

Media typeapplication/problem+json

RFC 9457 Problem Details object.

object
type
required
string format: uri
title
required
string
status
required
integer
detail
required
string
instance
string format: uri

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}
Retry-After
integer
RateLimit-Limit
integer
RateLimit-Remaining
integer
RateLimit-Reset
integer
X-RateLimit-Limit-Second
integer
X-RateLimit-Remaining-Second
integer
X-RateLimit-Limit-Minute
integer
X-RateLimit-Remaining-Minute
integer
X-RateLimit-Limit-Hour
integer
X-RateLimit-Remaining-Hour
integer
X-RateLimit-Limit-Day
integer
X-RateLimit-Remaining-Day
integer

Server error

Media typeapplication/problem+json

RFC 9457 Problem Details object.

object
type
required
string format: uri
title
required
string
status
required
integer
detail
required
string
instance
string format: uri

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

Server error

Media typeapplication/problem+json

RFC 9457 Problem Details object.

object
type
required
string format: uri
title
required
string
status
required
integer
detail
required
string
instance
string format: uri

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}