The Couchbase Server REST API provides programmatic access to manage and configure Couchbase Server clusters. It includes endpoints for cluster management, bucket operations, node administration, security settings, and server configuration. The API enables automation of deployment, monitoring, and maintenance tasks for Couchbase Server instances across distributed environments.
openapi: 3.1.0
info:
title: Couchbase Server REST API
description: >-
The Couchbase Server REST API provides programmatic access to manage and
configure Couchbase Server clusters. It includes endpoints for cluster
management, bucket operations, node administration, security settings,
and server configuration. The API enables automation of deployment,
monitoring, and maintenance tasks for Couchbase Server instances across
distributed environments.
version: '7.6'
contact:
name: Couchbase Support
url: https://support.couchbase.com
termsOfService: https://www.couchbase.com/terms-of-use
externalDocs:
description: Couchbase Server REST API Documentation
url: https://docs.couchbase.com/server/current/rest-api/rest-intro.html
servers:
- url: https://localhost:8091
description: Couchbase Server (default port)
- url: https://localhost:18091
description: Couchbase Server (SSL)
tags:
- name: Buckets
description: >-
Endpoints for creating, configuring, and managing buckets used to store
data in Couchbase Server.
- name: Cluster
description: >-
Endpoints for managing Couchbase Server clusters, including cluster
initialization, configuration, and information retrieval.
- name: Compaction
description: >-
Endpoints for managing auto-compaction settings and triggering compaction
operations.
- name: Index Service
description: >-
Endpoints for managing the Global Secondary Index service.
- name: Logs
description: >-
Endpoints for collecting and managing diagnostic logs.
- name: Nodes
description: >-
Endpoints for managing individual server nodes, including adding nodes,
failover, recovery, and rebalance operations.
- name: Scopes and Collections
description: >-
Endpoints for managing scopes and collections within buckets.
- name: Security
description: >-
Endpoints for managing security settings, users, roles, certificates,
and audit configurations.
- name: Server Groups
description: >-
Endpoints for managing server groups for rack-zone awareness.
- name: Settings
description: >-
Endpoints for managing server-wide settings and configuration parameters.
security:
- basicAuth: []
paths:
/pools:
get:
operationId: getPools
summary: Get cluster information
description: >-
Returns basic information about the cluster including the list of pools,
UUID, and implementation version.
tags:
- Cluster
responses:
'200':
description: Successful retrieval of cluster pool information
content:
application/json:
schema:
$ref: '#/components/schemas/Pools'
'401':
description: Unauthorized access
/pools/default:
get:
operationId: getPoolDefault
summary: Get default pool details
description: >-
Returns detailed information about the default pool including cluster
name, storage totals, RAM quotas, node list, and bucket information.
tags:
- Cluster
responses:
'200':
description: Successful retrieval of default pool details
content:
application/json:
schema:
$ref: '#/components/schemas/PoolDetails'
'401':
description: Unauthorized access
/pools/default/buckets:
get:
operationId: listBuckets
summary: List all buckets
description: >-
Returns a list of all buckets in the cluster with their configuration
details, including RAM quotas, replica settings, and item counts.
tags:
- Buckets
responses:
'200':
description: Successful retrieval of bucket list
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Bucket'
'401':
description: Unauthorized access
post:
operationId: createBucket
summary: Create a new bucket
description: >-
Creates a new bucket with the specified configuration including name,
type, RAM quota, replica count, and other settings.
tags:
- Buckets
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/BucketCreateRequest'
responses:
'202':
description: Bucket creation accepted
'400':
description: Invalid bucket configuration
'401':
description: Unauthorized access
/pools/default/buckets/{bucketName}:
get:
operationId: getBucket
summary: Get bucket details
description: >-
Returns detailed configuration and statistics for a specific bucket.
tags:
- Buckets
parameters:
- $ref: '#/components/parameters/bucketName'
responses:
'200':
description: Successful retrieval of bucket details
content:
application/json:
schema:
$ref: '#/components/schemas/Bucket'
'401':
description: Unauthorized access
'404':
description: Bucket not found
post:
operationId: updateBucket
summary: Update bucket settings
description: >-
Updates the configuration of an existing bucket, such as RAM quota,
authentication type, and replica settings.
tags:
- Buckets
parameters:
- $ref: '#/components/parameters/bucketName'
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/BucketUpdateRequest'
responses:
'200':
description: Bucket updated successfully
'400':
description: Invalid bucket configuration
'401':
description: Unauthorized access
'404':
description: Bucket not found
delete:
operationId: deleteBucket
summary: Delete a bucket
description: >-
Deletes the specified bucket and all of its data from the cluster.
tags:
- Buckets
parameters:
- $ref: '#/components/parameters/bucketName'
responses:
'200':
description: Bucket deleted successfully
'401':
description: Unauthorized access
'404':
description: Bucket not found
/pools/default/buckets/{bucketName}/scopes:
get:
operationId: listScopes
summary: List scopes in a bucket
description: >-
Returns the list of all scopes and their collections within the
specified bucket.
tags:
- Scopes and Collections
parameters:
- $ref: '#/components/parameters/bucketName'
responses:
'200':
description: Successful retrieval of scopes list
content:
application/json:
schema:
$ref: '#/components/schemas/ScopesList'
'401':
description: Unauthorized access
'404':
description: Bucket not found
post:
operationId: createScope
summary: Create a scope
description: >-
Creates a new scope within the specified bucket.
tags:
- Scopes and Collections
parameters:
- $ref: '#/components/parameters/bucketName'
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- name
properties:
name:
type: string
description: The name of the scope to create
responses:
'200':
description: Scope created successfully
'400':
description: Invalid scope name
'401':
description: Unauthorized access
'404':
description: Bucket not found
/pools/default/buckets/{bucketName}/scopes/{scopeName}/collections:
post:
operationId: createCollection
summary: Create a collection
description: >-
Creates a new collection within the specified scope and bucket.
tags:
- Scopes and Collections
parameters:
- $ref: '#/components/parameters/bucketName'
- $ref: '#/components/parameters/scopeName'
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- name
properties:
name:
type: string
description: The name of the collection to create
responses:
'200':
description: Collection created successfully
'400':
description: Invalid collection name
'401':
description: Unauthorized access
'404':
description: Bucket or scope not found
/pools/nodes:
get:
operationId: getNodes
summary: Get nodes information
description: >-
Returns information about all nodes in the cluster, including
their services, status, and system resources.
tags:
- Nodes
responses:
'200':
description: Successful retrieval of node information
content:
application/json:
schema:
$ref: '#/components/schemas/NodesInfo'
'401':
description: Unauthorized access
/controller/addNode:
post:
operationId: addNode
summary: Add a node to the cluster
description: >-
Adds a new node to the cluster. The node must be configured and
reachable before it can be added.
tags:
- Nodes
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- hostname
properties:
hostname:
type: string
description: The hostname or IP address of the node to add
services:
type: string
description: >-
Comma-separated list of services to enable on the node
(kv, n1ql, index, fts, cbas, eventing, backup)
user:
type: string
description: Administrator username for the node
password:
type: string
description: Administrator password for the node
responses:
'200':
description: Node added successfully
'400':
description: Invalid node configuration
'401':
description: Unauthorized access
/controller/rebalance:
post:
operationId: rebalanceCluster
summary: Rebalance the cluster
description: >-
Initiates a rebalance operation to redistribute data across the
cluster nodes after adding or removing nodes.
tags:
- Nodes
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
knownNodes:
type: string
description: Comma-separated list of known node OTP names
ejectedNodes:
type: string
description: Comma-separated list of node OTP names to eject
responses:
'200':
description: Rebalance initiated successfully
'400':
description: Invalid rebalance configuration
'401':
description: Unauthorized access
/controller/failOver:
post:
operationId: failOverNode
summary: Fail over a node
description: >-
Initiates a hard failover for the specified node, removing it from
the cluster immediately.
tags:
- Nodes
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- otpNode
properties:
otpNode:
type: string
description: The OTP name of the node to fail over
responses:
'200':
description: Failover initiated successfully
'400':
description: Invalid failover request
'401':
description: Unauthorized access
/pools/default/serverGroups:
get:
operationId: listServerGroups
summary: List server groups
description: >-
Returns the list of server groups and their member nodes for
rack-zone awareness configuration.
tags:
- Server Groups
responses:
'200':
description: Successful retrieval of server groups
content:
application/json:
schema:
$ref: '#/components/schemas/ServerGroups'
'401':
description: Unauthorized access
post:
operationId: createServerGroup
summary: Create a server group
description: >-
Creates a new server group for rack-zone awareness.
tags:
- Server Groups
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- name
properties:
name:
type: string
description: The name of the server group
responses:
'200':
description: Server group created successfully
'400':
description: Invalid server group name
'401':
description: Unauthorized access
/settings/web:
post:
operationId: configureWebSettings
summary: Configure web settings
description: >-
Configures the cluster web console settings including the admin
username, password, and port.
tags:
- Settings
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
username:
type: string
description: Administrator username
password:
type: string
description: Administrator password
port:
type: integer
description: Web console port
responses:
'200':
description: Web settings updated successfully
'401':
description: Unauthorized access
/settings/autoCompaction:
get:
operationId: getAutoCompaction
summary: Get auto-compaction settings
description: >-
Returns the current auto-compaction settings for the cluster.
tags:
- Compaction
responses:
'200':
description: Successful retrieval of auto-compaction settings
content:
application/json:
schema:
$ref: '#/components/schemas/AutoCompactionSettings'
'401':
description: Unauthorized access
post:
operationId: updateAutoCompaction
summary: Update auto-compaction settings
description: >-
Updates the auto-compaction settings for the cluster including
database and view fragmentation thresholds and compaction intervals.
tags:
- Compaction
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/AutoCompactionSettings'
responses:
'200':
description: Auto-compaction settings updated successfully
'400':
description: Invalid compaction settings
'401':
description: Unauthorized access
/settings/rbac/users:
get:
operationId: listUsers
summary: List all users
description: >-
Returns the list of all users configured in the cluster with their
roles and authentication domains.
tags:
- Security
responses:
'200':
description: Successful retrieval of user list
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
'401':
description: Unauthorized access
/settings/rbac/users/{domain}/{username}:
get:
operationId: getUser
summary: Get user details
description: >-
Returns detailed information about a specific user including their
roles and authentication configuration.
tags:
- Security
parameters:
- $ref: '#/components/parameters/domain'
- $ref: '#/components/parameters/username'
responses:
'200':
description: Successful retrieval of user details
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'401':
description: Unauthorized access
'404':
description: User not found
put:
operationId: createOrUpdateUser
summary: Create or update a user
description: >-
Creates a new user or updates an existing user with the specified
roles and authentication settings.
tags:
- Security
parameters:
- $ref: '#/components/parameters/domain'
- $ref: '#/components/parameters/username'
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
password:
type: string
description: User password (required for local domain)
roles:
type: string
description: Comma-separated list of roles
name:
type: string
description: Full name of the user
responses:
'200':
description: User created or updated successfully
'400':
description: Invalid user configuration
'401':
description: Unauthorized access
delete:
operationId: deleteUser
summary: Delete a user
description: >-
Deletes the specified user from the cluster.
tags:
- Security
parameters:
- $ref: '#/components/parameters/domain'
- $ref: '#/components/parameters/username'
responses:
'200':
description: User deleted successfully
'401':
description: Unauthorized access
'404':
description: User not found
/settings/rbac/roles:
get:
operationId: listRoles
summary: List available roles
description: >-
Returns the list of all available roles in the cluster that can be
assigned to users.
tags:
- Security
responses:
'200':
description: Successful retrieval of available roles
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Role'
'401':
description: Unauthorized access
/pools/default/certificate:
get:
operationId: getClusterCertificate
summary: Get cluster certificate
description: >-
Returns the cluster CA certificate in PEM format.
tags:
- Security
responses:
'200':
description: Successful retrieval of cluster certificate
content:
text/plain:
schema:
type: string
/settings/indexes:
get:
operationId: getIndexSettings
summary: Get index service settings
description: >-
Returns the current configuration settings for the Index service.
tags:
- Index Service
responses:
'200':
description: Successful retrieval of index settings
content:
application/json:
schema:
$ref: '#/components/schemas/IndexSettings'
'401':
description: Unauthorized access
post:
operationId: updateIndexSettings
summary: Update index service settings
description: >-
Updates the configuration settings for the Index service including
storage mode and memory allocation.
tags:
- Index Service
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/IndexSettings'
responses:
'200':
description: Index settings updated successfully
'400':
description: Invalid index settings
'401':
description: Unauthorized access
/diag:
get:
operationId: getDiagnostics
summary: Get diagnostic information
description: >-
Returns diagnostic information for the cluster including logs and
system statistics useful for troubleshooting.
tags:
- Logs
responses:
'200':
description: Successful retrieval of diagnostic information
content:
application/json:
schema:
type: object
'401':
description: Unauthorized access
/controller/startLogsCollection:
post:
operationId: startLogCollection
summary: Start log collection
description: >-
Initiates the collection of diagnostic logs across cluster nodes
for analysis and troubleshooting.
tags:
- Logs
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
nodes:
type: string
description: >-
Comma-separated list of node addresses to collect logs from
logRedactionLevel:
type: string
enum:
- none
- partial
description: Level of log redaction for sensitive data
responses:
'200':
description: Log collection started successfully
'401':
description: Unauthorized access
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >-
HTTP Basic Authentication using Couchbase Server administrator
credentials.
parameters:
bucketName:
name: bucketName
in: path
required: true
description: The name of the bucket
schema:
type: string
scopeName:
name: scopeName
in: path
required: true
description: The name of the scope
schema:
type: string
domain:
name: domain
in: path
required: true
description: The authentication domain (local or external)
schema:
type: string
enum:
- local
- external
username:
name: username
in: path
required: true
description: The username of the user
schema:
type: string
schemas:
Pools:
type: object
description: Cluster pool information
properties:
isAdminCreds:
type: boolean
description: Whether admin credentials are being used
isROAdminCreds:
type: boolean
description: Whether read-only admin credentials are being used
isEnterprise:
type: boolean
description: Whether this is an Enterprise Edition cluster
implementationVersion:
type: string
description: The version of the Couchbase Server implementation
uuid:
type: string
description: The unique identifier for the cluster
pools:
type: array
description: List of available pools
items:
type: object
properties:
name:
type: string
description: Pool name
uri:
type: string
description: URI to access pool details
streamingUri:
type: string
description: URI for streaming pool updates
PoolDetails:
type: object
description: Detailed information about the default pool
properties:
name:
type: string
description: Name of the pool
clusterName:
type: string
description: Human-readable cluster name
nodes:
type: array
description: List of nodes in the cluster
items:
$ref: '#/components/schemas/Node'
storageTotals:
type: object
description: Aggregate storage statistics
properties:
ram:
type: object
properties:
total:
type: integer
description: Total RAM in bytes
used:
type: integer
description: Used RAM in bytes
hdd:
type: object
properties:
total:
type: integer
description: Total disk space in bytes
used:
type: integer
description: Used disk space in bytes
rebalanceStatus:
type: string
description: Current rebalance status
Node:
type: object
description: Information about a cluster node
properties:
hostname:
type: string
description: Node hostname and port
status:
type: string
description: Node status
enum:
- healthy
- unhealthy
- warmup
clusterMembership:
type: string
description: Cluster membership status
enum:
- active
- inactiveAdded
- inactiveFailed
services:
type: array
description: List of services running on the node
items:
type: string
enum:
- kv
- n1ql
- index
- fts
- cbas
- eventing
- backup
os:
type: string
description: Operating system of the node
version:
type: string
description: Couchbase Server version on the node
memoryTotal:
type: integer
description: Total memory on the node in bytes
memoryFree:
type: integer
description: Free memory on the node in bytes
Bucket:
type: object
description: Bucket configuration and statistics
properties:
name:
type: string
description: Name of the bucket
bucketType:
type: string
description: Type of the bucket
enum:
- membase
- memcached
- ephemeral
authType:
type: string
description: Authentication type for the bucket
ramQuota:
type: integer
description: RAM quota for the bucket in bytes
replicaNumber:
type: integer
description: Number of replicas
minimum: 0
maximum: 3
replicaIndex:
type: boolean
description: Whether to replicate indexes
conflictResolutionType:
type: string
description: Conflict resolution mechanism
enum:
- seqno
- lww
evictionPolicy:
type: string
description: Eviction policy for the bucket
enum:
- valueOnly
- fullEviction
- noEviction
- nruEviction
durabilityMinLevel:
type: string
description: Minimum durability level for the bucket
enum:
- none
- majority
- majorityAndPersistActive
- persistToMajority
itemCount:
type: integer
description: Number of items in the bucket
BucketCreateRequest:
type: object
description: Request body for creating a new bucket
required:
- name
- ramQuota
properties:
name:
type: string
description: Name of the bucket
maxLength: 100
bucketType:
type: string
description: Type of the bucket
enum:
- couchbase
- memcached
- ephemeral
default: couchbase
ramQuota:
type: integer
description: RAM quota in megabytes
minimum: 100
replicaNumber:
type: integer
description: Number of replicas
minimum: 0
maximum: 3
default: 1
conflictResolutionType:
type: string
description: Conflict resolution mechanism
enum:
- seqno
- lww
default: seqno
evictionPolicy:
type: string
description: Eviction policy
enum:
- valueOnly
- fullEviction
- noEviction
- nruEviction
flushEnabled:
type: integer
description: Whether flush is enabled (0 or 1)
enum:
- 0
- 1
default: 0
BucketUpdateRequest:
type: object
description: Request body for updating a bucket
properties:
ramQuota:
type: integer
description: RAM quota in megabytes
minimum: 100
replicaNumber:
type: integer
description: Number of replicas
minimum: 0
maximum: 3
flushEnabled:
type: integer
description: Whether flush is enabled (0 or 1)
enum:
- 0
- 1
ScopesList:
type: object
description: List of scopes in a bucket
properties:
uid:
type: string
description: Unique identifier for the manifest
scopes:
type: array
description: List of scopes
items:
type: object
properties:
name:
type: string
description: Name of the scope
uid:
type: string
description: Unique identifier for the scope
collections:
type: array
description: Collections within the scope
items:
type: object
properties:
name:
type: string
description: Name of the collection
uid:
type: string
description: Unique identifier for the collection
maxTTL:
type: integer
description: Maximum TTL for documents in seconds
NodesInfo:
type: object
description: Information about cluster nodes
properties:
nodes:
type: array
description: List of nodes
items:
$ref: '#/components/schemas/Node'
ServerGroups:
type: object
description: Server groups configuration
properties:
groups:
type: array
description: List of server groups
items:
type: object
properties:
name:
type: string
description: Name of the server group
uri:
type: string
description: URI for the server group
nodes:
type: array
description: Nodes in the server group
items:
$ref: '#/components/schemas/Node'
User:
type: object
des
# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/couchbase/refs/heads/main/openapi/couchbase-server-rest-api-openapi.yml