Start a cluster upgrade path
const url = 'http://localhost:8000/clusters/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/upgrade-paths';
const options = {
method: 'POST',
headers: {
'API-Version': '2026-06-01.beta',
'API-Key': '<API-Key>',
'Content-Type': 'application/json'
},
body: '{"target_version":"26.5.5","timing":"now","force":true}'
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}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
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Header Parameters
Section titled “Header Parameters”Request Bodyrequired
Section titled “Request Bodyrequired”Request to take a cluster to a target version, one version at a time.
object
Version the cluster should end on. Every version of the upgrade path up to it is run in order.
When each step runs: now starts each step when the previous one is confirmed complete, maintenance_window runs one step per maintenance window.
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.
Responses
Section titled “Responses”The request has been accepted for processing, but processing has not yet completed.
An upgrade path of a cluster.
object
Unique upgrade path identifier.
Cluster the path belongs to.
Version the cluster ran when the path was requested.
Version the cluster should end on.
When each step runs.
Whether breaking changes and major jumps were accepted.
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.
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.
Version of the step in progress. Absent when no step is running. The version the cluster runs is reached_version.
Every step of the path, in order.
One version a cluster moves through on an upgrade path.
object
Version of this step.
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.
Whether moving onto this version crosses a major version boundary.
Whether moving onto this version crosses recorded breaking changes.
Why the path stopped. Present when status is failed.
When the path was requested.
When the path completed, failed or was cancelled. Absent while it is active.
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.
RFC 9457 Problem Details object.
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com"
}Access is unauthorized.
RFC 9457 Problem Details object.
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com"
}The server cannot find the requested resource.
RFC 9457 Problem Details object.
object
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.
RFC 9457 Problem Details object.
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com"
}Client error
Returned when an upgrade path cannot start. blockers lists the blocking versions.
object
The versions that block the path and why. A blocker with overridable: true is accepted when force is set.
A reason a version on an upgrade path cannot be taken.
object
The blocking version.
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.
Whether force accepts this blocker.
Human-readable detail.
Extensions behind an extension blocker.
Titles of the breaking changes behind a breaking_change blocker.
Example
{
"blockers": [
{
"version": "26.5.5"
}
]
}Client error
RFC 9457 Problem Details object.
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com"
}Headers
Section titled “Headers”Server error
RFC 9457 Problem Details object.
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com"
}Server error
RFC 9457 Problem Details object.
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com"
}