---
title: "Update a Switchover Pair"
method: PUT
path: "/switchover/v1/switchover-pairs/{id}"
tags: ["Switchover Pairs (switchover/v1)"]
---
# Update a Switchover Pair
`PUT /switchover/v1/switchover-pairs/{id}`
## Request
- Base URL: `https://api.confluent.cloud`
- URL: `https://api.confluent.cloud/switchover/v1/switchover-pairs/{id}`
- Auth: one of:
- HTTP basic
- HTTP basic
[](#section/Versioning/API-Lifecycle-Policy) [](mailto:ccloud-api-access+switchover-v1-early-access@confluent.io?subject=Request%20to%20join%20switchover/v1%20API%20Early%20Access&body=I%E2%80%99d%20like%20to%20join%20the%20Confluent%20Cloud%20API%20Early%20Access%20for%20switchover/v1%20to%20provide%20early%20feedback%21%20My%20Cloud%20Organization%20ID%20is%20%3Cretrieve%20from%20https%3A//confluent.cloud/settings/billing/payment%3E.)
Make a request to update a switchover pair.
## Path parameters
- `id` string, required
## Query parameters
- `environment` string, required: Filter a collection by a string search
## Request body
- SwitchoverV1SwitchoverPairUpdateRequest: Request body for updating a `SwitchoverPair`. Only `display_name` is mutable via this operation; use the `:failover` operation to change the active member.
- `spec` object, required
- `display_name` string: A human-readable name for the switchover pair.
## Response `200`
Switchover Pair.
- object: `SwitchoverPair` represents a cluster-level Disaster Recovery pairing between two Kafka clusters in different regions of the same environment. Exactly one member is active at any time; the other is passive and kept in sync via a bidirectional cluster link. The API allows you to list, create, read, update, and delete switchover pairs, and to trigger a failover (promotion of the passive member) via the `:failover` operation. Related guide: [Disaster Recovery for Kafka in Confluent Cloud](https://docs.confluent.io/cloud/current/clusters/cluster-linking/index.html). ## The Switchover Pairs Model
- `api_version` 'switchover/v1', required: APIVersion defines the schema version of this representation of a resource.
- `kind` 'SwitchoverPair', required: Kind defines the object this REST resource represents.
- `id` string, required: ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object `kinds` or objects of the same `kind` within a different scope/namespace ("space").
- `metadata` object: ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.
- `self` string, uri, required: Self is a Uniform Resource Locator (URL) at which an object can be addressed. This URL encodes the service location, API version, and other particulars necessary to locate the resource at a point in time
- `resource_name` string, uri: Resource Name is a Uniform Resource Identifier (URI) that is globally unique across space and time. It is represented as a Confluent Resource Name
- `created_at` string, date-time: The date and time at which this object was created. It is represented in RFC3339 format and is in UTC.
- `updated_at` string, date-time: The date and time at which this object was last updated. It is represented in RFC3339 format and is in UTC.
- `deleted_at` string, date-time: The date and time at which this object was (or will be) deleted. It is represented in RFC3339 format and is in UTC.
- `spec` object, required: The desired state of the Switchover Pair
- `environment_crn` string, uri, required: The CRN of the environment this resource belongs to. Every reference in a request body is a CRN (see `member_crn`), so this is one too rather than an `{id}` relationship object — callers learn a single convention, and the organization always travels with the reference. A CRN that names no environment is rejected; it is not defaulted. The `?environment=` query parameter on the other operations remains a bare environment ID: it is the standard Confluent collection filter, not a reference to a stored resource.
- `display_name` string, required: A human-readable name for the switchover pair.
- `members` SwitchoverV1SwitchoverPairMember[], required: The two clusters participating in this switchover pair. Must contain exactly 2 members.
- `name` string, required: A logical name for this member (e.g. "west" or "east"), unique within the pair.
- `member_crn` string, uri, required: The Confluent Resource Name (CRN) of the resource this member represents. A CRN rather than an ID plus an environment because member types do not share a parent hierarchy: a Kafka cluster is `environment → cloud-cluster`, a Flink compute pool is `environment → flink-region → compute-pool`, and a Connect connector is `environment → cloud-cluster → connector` with a *name* as its leaf, unique only within its cluster. A single `environment` field cannot address the latter two unambiguously. The environment is read from the CRN, so a pair whose two members live in different environments needs no separate per-member environment field. For a Kafka cluster both the canonical form and the variant carrying the redundant trailing `/kafka=` (which the cmk API returns in `metadata.resource_name`) are accepted. The short `crn://confluent.cloud/kafka=` form is rejected: it is a valid CRN but carries no environment. In Terraform the value is available as `confluent_kafka_cluster..rbac_crn`.
- `location` object: The cloud location of this member's cluster. Derived server-side from the cluster the member's CRN names; not settable by the client.
- `cloud` string: The cloud provider hosting this member (e.g. `aws`, `gcp`, `azure`).
- `region` string: The cloud region hosting this member (e.g. `us-west-2`).
- `active_member` string, required: The name of the member that is currently active. On create, this selects which member starts as active; it must match one of the `members[].name` values. Use the `:failover` operation to change the active member after creation.
- `first_active` string: The member that was active when the pair was created. Output-only and immutable; set implicitly at create time and never accepted as input. Comparing it with `active_member` distinguishes a pair that has failed over (they differ) from one still on its original active member (they match).
- `failover_type` string: The failover semantics most recently applied to this pair via the `:failover` operation. Not settable directly; empty until a failover has been triggered.
- `status` SwitchoverV1SwitchoverPairStatus, required: The status of the Switchover Pair
- `phase` string, required: The lifecycle phase of the switchover pair: PROVISIONING: the pair is being created and validated; READY_TO_FAILOVER: the pair is validated and a failover (planned or unplanned) can be triggered; UPDATING: a failover, failback, or restore operation is in progress; READY_TO_RESTORE: an unplanned failover has completed; the cluster link can be restored; FAILED: resource validation failed for the pair; it must be deleted and recreated; DEPROVISIONING: the pair is being deleted.
- `conditions` SwitchoverV1Condition[]: Status conditions providing detailed information about the switchover pair's current state.
- `member` string: The `SwitchoverPair` member this condition belongs to. Conditions are recorded per member and flattened into a single list, so the same condition `type` can appear once per member; this field disambiguates them. Empty for pair-level conditions that have no member dimension.
- `type` string, required: The condition type — one of `ResourceValidationComplete`, `ResourcePlannedFailoverComplete`, `ResourceUnplannedFailoverComplete`, or `ResourceRestoreComplete`.
- `status` string, required: The status of the condition.
- `reason` string: A machine-readable reason for the condition's current status.
- `message` string: A human-readable message providing additional detail about the condition.
## Other responses
- `400`: Bad Request
- `401`: The request lacks valid authentication credentials for this resource.
- `403`: The access credentials were considered insufficient to grant access
- `404`: Not Found
- `409`: The request is in conflict with the current server state
- `422`: Validation Failed
- `429`: Rate Limit Exceeded
- `500`: Oops, something went wrong!
## Changes
- **2026-10-02** `4bbccb7fdb6d`: 1 info
- endpoint added
[Operation history](https://skmtc.dev/confluent/apis/confluent-cloud-apis/changes/switchover/v1/switchover-pairs/:id/put.md)
---
[API](https://skmtc.dev/confluent/apis/confluent-cloud-apis.md) - [All operations](https://skmtc.dev/confluent/apis/confluent-cloud-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/confluent/apis/confluent-cloud-apis/revisions/018ddeaf203e?raw)