Skip to main content
POST
Create a switchover

Authorizations

Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Path Parameters

organization
string
required

Organization name slug from list_organizations. Example: acme.

database
string
required

Database name slug from list_databases. Example: app-db.

branch
string
required

Branch name from list_branches. Example: main.

Body

application/json
candidate
string

The exact name of the replica returned by the branch's Postgres infrastructure endpoint to promote. Omit to let the operator select an eligible replica. Only applies to branches with replicas.

Response

Returns the new switchover

id
string
required

The ID of the switchover

state
enum<string>
required

The state of the switchover

Available options:
pending,
running,
succeeded,
failed,
canceled
started_at
string | null
required

When the switchover was requested

completed_at
string | null
required

When the switchover finished

created_at
string
required

When the switchover was created

updated_at
string
required

When the switchover was last updated

actor
object
required
method
enum<string> | null

How the primary was moved. switchover promotes a replica on a highly available branch; restart restarts the single instance of a branch that has no replicas. Absent until the operator selects one.

Available options:
switchover,
restart
error
string | null

Why the switchover failed. A failed switchover has an unconfirmed outcome and does not imply the primary stayed put.