The Couchbase XDCR (Cross Data Center Replication) REST API enables configuration and management of data replication between Couchbase clusters across different data centers. It provides endpoints for creating replication references, configuring replication streams, monitoring replication statistics, and managing replication settings.
openapi: 3.1.0
info:
title: Couchbase XDCR REST API
description: >-
The Couchbase XDCR (Cross Data Center Replication) REST API enables
configuration and management of data replication between Couchbase
clusters across different data centers. It provides endpoints for creating
replication references, configuring replication streams, monitoring
replication statistics, and managing replication settings. XDCR supports
both unidirectional and bidirectional replication for high availability
and disaster recovery scenarios.
version: '7.6'
contact:
name: Couchbase Support
url: https://support.couchbase.com
termsOfService: https://www.couchbase.com/terms-of-use
externalDocs:
description: Couchbase XDCR REST API Documentation
url: https://docs.couchbase.com/server/current/rest-api/rest-xdcr-intro.html
servers:
- url: https://localhost:8091
description: Couchbase Server (default port)
- url: https://localhost:18091
description: Couchbase Server (SSL)
tags:
- name: Cluster References
description: >-
Endpoints for managing remote cluster references used as XDCR targets.
- name: Replication Settings
description: >-
Endpoints for configuring replication-level and global XDCR settings.
- name: Replication Statistics
description: >-
Endpoints for monitoring replication progress and performance statistics.
- name: Replications
description: >-
Endpoints for creating, managing, and deleting XDCR replication streams.
security:
- basicAuth: []
paths:
/pools/default/remoteClusters:
get:
operationId: listRemoteClusters
summary: List remote cluster references
description: >-
Returns the list of all remote cluster references configured for
XDCR replication.
tags:
- Cluster References
responses:
'200':
description: Successful retrieval of remote cluster references
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/RemoteClusterReference'
'401':
description: Unauthorized access
post:
operationId: createRemoteCluster
summary: Create a remote cluster reference
description: >-
Creates a new remote cluster reference that can be used as a target
for XDCR replications.
tags:
- Cluster References
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/RemoteClusterCreateRequest'
responses:
'200':
description: Remote cluster reference created successfully
'400':
description: Invalid cluster reference configuration
'401':
description: Unauthorized access
/pools/default/remoteClusters/{clusterName}:
put:
operationId: updateRemoteCluster
summary: Update a remote cluster reference
description: >-
Updates the configuration of an existing remote cluster reference.
tags:
- Cluster References
parameters:
- $ref: '#/components/parameters/clusterName'
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/RemoteClusterCreateRequest'
responses:
'200':
description: Remote cluster reference updated successfully
'400':
description: Invalid cluster reference configuration
'401':
description: Unauthorized access
'404':
description: Remote cluster reference not found
delete:
operationId: deleteRemoteCluster
summary: Delete a remote cluster reference
description: >-
Deletes the specified remote cluster reference. All replications
using this reference must be deleted first.
tags:
- Cluster References
parameters:
- $ref: '#/components/parameters/clusterName'
responses:
'200':
description: Remote cluster reference deleted successfully
'401':
description: Unauthorized access
'404':
description: Remote cluster reference not found
/controller/createReplication:
post:
operationId: createReplication
summary: Create an XDCR replication
description: >-
Creates a new XDCR replication stream from a source bucket to a
target bucket on a remote cluster.
tags:
- Replications
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/ReplicationCreateRequest'
responses:
'200':
description: Replication created successfully
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: Replication ID
'400':
description: Invalid replication configuration
'401':
description: Unauthorized access
/controller/cancelXDCR/{replicationId}:
delete:
operationId: deleteReplication
summary: Delete an XDCR replication
description: >-
Deletes the specified XDCR replication stream, stopping all data
replication for that stream.
tags:
- Replications
parameters:
- $ref: '#/components/parameters/replicationId'
responses:
'200':
description: Replication deleted successfully
'401':
description: Unauthorized access
'404':
description: Replication not found
/settings/replications:
get:
operationId: getGlobalReplicationSettings
summary: Get global XDCR settings
description: >-
Returns the global default settings for all XDCR replications.
tags:
- Replication Settings
responses:
'200':
description: Successful retrieval of global replication settings
content:
application/json:
schema:
$ref: '#/components/schemas/ReplicationSettings'
'401':
description: Unauthorized access
post:
operationId: updateGlobalReplicationSettings
summary: Update global XDCR settings
description: >-
Updates the global default settings applied to all XDCR replications.
tags:
- Replication Settings
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/ReplicationSettings'
responses:
'200':
description: Global replication settings updated successfully
'400':
description: Invalid settings
'401':
description: Unauthorized access
/settings/replications/{replicationId}:
get:
operationId: getReplicationSettings
summary: Get replication-specific settings
description: >-
Returns the settings for a specific XDCR replication stream.
tags:
- Replication Settings
parameters:
- $ref: '#/components/parameters/replicationId'
responses:
'200':
description: Successful retrieval of replication settings
content:
application/json:
schema:
$ref: '#/components/schemas/ReplicationSettings'
'401':
description: Unauthorized access
'404':
description: Replication not found
post:
operationId: updateReplicationSettings
summary: Update replication-specific settings
description: >-
Updates the settings for a specific XDCR replication stream,
overriding the global defaults.
tags:
- Replication Settings
parameters:
- $ref: '#/components/parameters/replicationId'
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/ReplicationSettings'
responses:
'200':
description: Replication settings updated successfully
'400':
description: Invalid settings
'401':
description: Unauthorized access
'404':
description: Replication not found
/pools/default/buckets/{bucketName}/stats/{statName}:
get:
operationId: getReplicationStats
summary: Get XDCR replication statistics
description: >-
Returns statistics for XDCR replications on a specific bucket,
including items replicated, replication latency, and bandwidth usage.
tags:
- Replication Statistics
parameters:
- name: bucketName
in: path
required: true
description: The name of the source bucket
schema:
type: string
- name: statName
in: path
required: true
description: >-
The specific statistic to retrieve (e.g.,
replications/{replicationId}/docs_written)
schema:
type: string
responses:
'200':
description: Successful retrieval of replication statistics
content:
application/json:
schema:
type: object
'401':
description: Unauthorized access
'404':
description: Bucket or statistic not found
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >-
HTTP Basic Authentication using Couchbase Server administrator
credentials.
parameters:
clusterName:
name: clusterName
in: path
required: true
description: The name of the remote cluster reference
schema:
type: string
replicationId:
name: replicationId
in: path
required: true
description: >-
The XDCR replication ID in the format
{remoteClusterUUID}/{sourceBucket}/{targetBucket}
schema:
type: string
schemas:
RemoteClusterReference:
type: object
description: Remote cluster reference for XDCR
properties:
name:
type: string
description: Name of the remote cluster reference
uuid:
type: string
description: UUID of the remote cluster
hostname:
type: string
description: Hostname and port of the remote cluster
username:
type: string
description: Administrator username for the remote cluster
uri:
type: string
description: URI for accessing this cluster reference
deleted:
type: boolean
description: Whether the reference is marked for deletion
demandEncryption:
type: boolean
description: Whether encryption is required
encryptionType:
type: string
description: Type of encryption used
enum:
- none
- half
- full
RemoteClusterCreateRequest:
type: object
description: Request to create or update a remote cluster reference
required:
- name
- hostname
- username
- password
properties:
name:
type: string
description: Name for the remote cluster reference
hostname:
type: string
description: Hostname and port of the remote cluster
username:
type: string
description: Administrator username on the remote cluster
password:
type: string
description: Administrator password on the remote cluster
demandEncryption:
type: integer
description: Whether to require encryption (0 or 1)
enum:
- 0
- 1
encryptionType:
type: string
description: Type of encryption to use
enum:
- none
- half
- full
certificate:
type: string
description: CA certificate for the remote cluster in PEM format
ReplicationCreateRequest:
type: object
description: Request to create an XDCR replication
required:
- fromBucket
- toCluster
- toBucket
- replicationType
properties:
fromBucket:
type: string
description: Name of the source bucket
toCluster:
type: string
description: Name of the remote cluster reference
toBucket:
type: string
description: Name of the target bucket on the remote cluster
replicationType:
type: string
description: Type of replication
enum:
- continuous
filterExpression:
type: string
description: Regular expression filter for document IDs
compressionType:
type: string
description: Compression type for replication data
enum:
- None
- Auto
- Snappy
priority:
type: string
description: Replication priority
enum:
- High
- Medium
- Low
ReplicationSettings:
type: object
description: XDCR replication settings
properties:
checkpointInterval:
type: integer
description: Interval between checkpoints in seconds
minimum: 60
maximum: 14400
docBatchSizeKb:
type: integer
description: Document batch size in kilobytes
minimum: 10
maximum: 10000
failureRestartInterval:
type: integer
description: Interval before restarting after failure in seconds
minimum: 1
maximum: 300
filterExpression:
type: string
description: Regular expression filter for document IDs
logLevel:
type: string
description: Log level for the replication
enum:
- Error
- Warn
- Info
- Debug
- Trace
networkUsageLimit:
type: integer
description: Network usage limit in MB per second (0 for unlimited)
minimum: 0
optimisticReplicationThreshold:
type: integer
description: >-
Document size threshold in bytes for optimistic replication
minimum: 0
sourceNozzlePerNode:
type: integer
description: Number of source nozzles per node
minimum: 1
maximum: 100
targetNozzlePerNode:
type: integer
description: Number of target nozzles per node
minimum: 1
maximum: 100
statsInterval:
type: integer
description: Interval for statistics updates in milliseconds
minimum: 200
maximum: 600000
compressionType:
type: string
description: Compression type for replicated data
enum:
- None
- Auto
- Snappy
priority:
type: string
description: Replication priority
enum:
- High
- Medium
- Low