Couchbase Public API
- reference
API reference guide for the Couchbase Capella Public API.
You can find this reference as an openapi.yaml file to import into tools such as Postman, Insomnia or similar, here.
| The API is regularly updated along with the documentation. In the process, documentation may be built first — so it is possible that a new endpoint listed here may be some hours from reaching the API. |
ClustersV3
POST /v3/clusters/{id}/auditlogs
Create Cluster Audit Log Export
Description
Creates a new request for the export of audit log files that cover a user-specified time-period. The returned value includes a download ID, which can be referenced in a subsequent Get Audit Log Request call. Time stamps must be in RFC3339 format.
Responses
| Code | Message | Datatype |
|---|---|---|
202 |
Success |
|
403 |
Access forbidden |
|
405 |
Method not allowed |
|
422 |
Request validation error |
|
500 |
Internal server error |
Description
Returns a list of all audit log export requests. The list starts with the most recent request. The information returned for each request includes the time of the request’s creation, the start and end times of the period for which records are required, a download URL for retrieval of a compressed file that contains the log files, and the progress-status of the request. When progress-status is 'ready', the compressed file can be manually downloaded, using the download URL.
Responses
| Code | Message | Datatype |
|---|---|---|
200 |
Success |
|
404 |
Resource was not found |
|
422 |
Request validation error |
|
500 |
Internal server error |
Description
Returns a specific audit log export request. The request is specified with a download ID, previously returned by Create Audit Log Request: the download ID must be appended to the URI of Get Audit Log Request. The information returned for the specified request includes the time of the request’s creation, the start and end times of the period for which records are required, a download URL for retrieval of a compressed file that contains the log files, and the progress-status of the request. When progress-status is 'ready', the compressed file can be manually downloaded, using the download URL.
Responses
| Code | Message | Datatype |
|---|---|---|
200 |
Success, job being processed |
|
404 |
Resource was not found |
|
422 |
Request validation error |
|
500 |
Internal server error |
Description
Configures the audit settings for the cluster. This allows auditing to be enabled or disabled for the cluster. It also allows specific audit events to be enabled, and specific users to be disabled.
Description
Creates a cluster with the given specifications and returns the id of the cluster on success
Responses
| Code | Message | Datatype |
|---|---|---|
202 |
Success |
<<>> |
403 |
Access forbidden |
|
422 |
Request validation error |
|
500 |
Internal server error |
Responses
| Code | Message | Datatype |
|---|---|---|
201 |
Successfully created cluster user |
<<>> |
403 |
Access forbidden |
|
404 |
Resource was not found |
|
422 |
Request validation error |
|
500 |
Internal server error |
Responses
| Code | Message | Datatype |
|---|---|---|
202 |
Successfully started the cluster deletion process |
<<>> |
403 |
Access forbidden |
|
404 |
Resource was not found |
|
422 |
Request validation error |
|
500 |
Internal server error |
Description
Retrieves the current audit settings for the cluster; including a list of all enabled audit events, a list of disabled users, and the overall enablement status of the cluster.
Responses
| Code | Message | Datatype |
|---|---|---|
200 |
Returns the current Audit settings for the cluster |
|
403 |
Access forbidden |
|
404 |
Resource was not found |
|
500 |
Internal server error |
Description
Returns the list of all filterable audit events for the cluster. Filterable audit events are those that can be either disabled or enabled. If a filterable audit event is currently disabled, it can be enabled through its inclusion in the enabledEventIDs field of Configure Cluster Audit Settings.
Responses
| Code | Message | Datatype |
|---|---|---|
200 |
Returns the list of filterable Audit Events for the cluster. |
|
403 |
Access forbidden |
|
404 |
Resource was not found |
|
500 |
Internal server error |
Responses
| Code | Message | Datatype |
|---|---|---|
200 |
Success |
|
403 |
Access forbidden |
|
422 |
Request validation error |
|
500 |
Internal server error |
Responses
| Code | Message | Datatype |
|---|---|---|
200 |
If found, returns the cluster information |
|
403 |
Access forbidden |
|
404 |
Resource was not found |
|
500 |
Internal server error |
Responses
| Code | Message | Datatype |
|---|---|---|
204 |
Successfully updated the cluster metadata |
<<>> |
403 |
Access forbidden |
|
404 |
Resource was not found |
|
422 |
Request validation error |
|
500 |
Internal server error |
Responses
| Code | Message | Datatype |
|---|---|---|
202 |
Success |
<<>> |
403 |
Access forbidden |
|
404 |
Resource was not found |
|
422 |
Request validation error |
|
500 |
Internal server error |
Responses
| Code | Message | Datatype |
|---|---|---|
204 |
Successfully updated the support package details |
<<>> |
403 |
Access forbidden |
|
404 |
Resource was not found |
|
422 |
Request validation error |
|
500 |
Internal server error |
EventsV3
GET /v3/events
List Events
Parameters
Query Parameters
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
page |
Sets how many results you would like to have on each page |
- |
null |
|
perPage |
Sets what page you would like to view |
- |
null |
|
sortBy |
Sets order of how you would like to sort results and also the key you would like to order by |
- |
null |
|
from |
Start point in the last 24 hours, RFC3339 format. Defaults to 24 hours before request. |
- |
null |
|
to |
End datetime in the last 24 hours, RFC3339 format. Defaults to Now. |
- |
null |
|
actor |
Filter by user UUID. Default returns all. |
- |
null |
|
cluster |
filter by cluster. Default is to return all. |
- |
null |
|
project |
Filter by project. Default is to return all. |
- |
null |
|
severity |
Filter by severity. Default is to return all. |
- |
null |
|
tag |
Filter by tag(s). Default is to return all. Tags are availability, billing, maintenance, performance, security, alert. |
- |
null |
Responses
| Code | Message | Datatype |
|---|---|---|
200 |
Successfully exported events |
|
403 |
Access forbidden |
|
422 |
Request validation error |
|
500 |
Internal server error |
Projects
POST /v2/projects
Create project
Responses
| Code | Message | Datatype |
|---|---|---|
201 |
Success |
|
403 |
Access forbidden |
|
422 |
Request validation error |
|
500 |
Internal server error |
Responses
| Code | Message | Datatype |
|---|---|---|
204 |
The project was deleted successfully |
<<>> |
403 |
Access forbidden |
|
404 |
Resource was not found |
|
422 |
Request validation error |
|
500 |
Internal server error |
Responses
| Code | Message | Datatype |
|---|---|---|
200 |
Success |
|
403 |
Access forbidden |
|
422 |
Request validation error |
|
500 |
Internal server error |
Models
AWSProviderSettings
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
region |
||||
bucket |
||||
supportBucket |
||||
accountId |
||||
vpcCidr |
||||
vpcId |
||||
stackId |
||||
privateSubnets |
List of [string] |
|||
availabilityZone |
List of [string] |
|||
azCount |
||||
lastRotated |
date-time |
AllowListEntry
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
cidrBlock |
X |
|||
ruleType |
X |
|||
duration |
||||
createdAt |
date-time |
|||
expiresAt |
date-time |
|||
updatedAt |
date-time |
|||
comment |
||||
state |
AppendAllowListRequest
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
cidrBlock |
X |
|||
ruleType |
X |
|||
comment |
||||
duration |
The duration you would like the temporary cidr block to be active |
AwsInstances
Allowable Values
m5.large, m5.xlarge, m5.2xlarge, m5.4xlarge, m5.8xlarge, m5.12xlarge, m5.16xlarge, m5.24xlarge, r5.large, r5.xlarge, r5.2xlarge, r5.4xlarge, r5.8xlarge, r5.12xlarge, r5.24xlarge, c5.large, c5.xlarge, c5.2xlarge, c5.4xlarge, c5.9xlarge, c5.12xlarge, c5.18xlarge, x1.16xlarge, x1.32xlarge
AzureInstances
Allowable Values
Standard_F4s_v2, Standard_F8s_v2, Standard_F16s_v2, Standard_F32s_v2, Standard_F48s_v2, Standard_F64s_v2, Standard_F72s_v2, Standard_D4s_v3, Standard_D8s_v3, Standard_D16s_v3, Standard_D32s_v3, Standard_D48s_v3, Standard_D64s_v3, Standard_E4s_v3, Standard_E8s_v3, Standard_E16s_v3, Standard_E20s_v3, Standard_E32s_v3, Standard_E48s_v3, Standard_E64s_v3, Standard_GS2, Standard_GS3, Standard_GS4, Standard_GS5
AzureProviderSettings
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
resourceGroupName |
||||
region |
||||
aksClusterName |
||||
dnsPrefix |
||||
defaultNodePoolName |
||||
tags |
Map of [string] |
|||
vNetCidr |
||||
vNetName |
||||
storageAccountName |
||||
configContainerName |
||||
importContainerName |
||||
availabilityZones |
List of [string] |
|||
azCount |
||||
deploymentName |
||||
msiName |
||||
tenantId |
||||
subscriptionId |
BucketRole
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
bucketName |
X |
Bucket Name |
||
bucketAccess |
X |
Set of BucketRoleTypes |
BucketStats
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
status |
X |
|||
totalCount |
X |
|||
unhealthyCount |
X |
|||
healthStats |
X |
Map of [string] |
Cloud
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
id |
X |
uuid |
||
name |
X |
|||
tenantId |
X |
uuid |
||
status |
X |
|||
provider |
X |
|||
createdAt |
X |
date-time |
||
updatedAt |
date-time |
|||
preflightStartedAt |
date-time |
|||
preflightFailedAt |
date-time |
|||
preflightCompletedAt |
date-time |
|||
bootstrappedAt |
date-time |
|||
deployedAt |
date-time |
|||
destroyedAt |
date-time |
|||
providerSettings |
X |
|||
version |
X |
CloudProviderSettings
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
resourceGroupName |
||||
region |
||||
aksClusterName |
||||
dnsPrefix |
||||
defaultNodePoolName |
||||
tags |
Map of [string] |
|||
vNetCidr |
||||
vNetName |
||||
storageAccountName |
||||
configContainerName |
||||
importContainerName |
||||
availabilityZones |
List of [string] |
|||
azCount |
||||
deploymentName |
||||
msiName |
||||
tenantId |
||||
subscriptionId |
||||
bucket |
||||
supportBucket |
||||
accountId |
||||
vpcCidr |
||||
vpcId |
||||
stackId |
||||
privateSubnets |
List of [string] |
|||
availabilityZone |
List of [string] |
|||
lastRotated |
date-time |
CloudSummary
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
id |
X |
uuid |
||
name |
X |
|||
status |
X |
|||
provider |
X |
|||
region |
X |
|||
virtualNetworkID |
X |
|||
virtualNetworkCIDR |
X |
CloudVersion
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
name |
X |
|||
components |
X |
Map of [string] |
Cluster
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
id |
X |
|||
name |
X |
|||
tenantId |
X |
|||
cloudId |
X |
|||
projectId |
X |
|||
status |
X |
|||
resourceIdentifier |
X |
Resource identifier name linked with the Cloud Provider |
||
createdAt |
date-time |
|||
updatedAt |
date-time |
|||
deployedAt |
date-time |
|||
version |
||||
endpointsURL |
List of [string] |
|||
privateEndpointURL |
List of [string] |
|||
endpointsSrv |
||||
privateEndpointsSrv |
ClusterHealth
Description
-
healthy- denotes that the resource is in a healthy state. -
unhealthy- denotes that the resource is in an uhealthy state. -
degraded- is reported for the overall health of a cluster or overall health for all nodes if all unhealthy nodes in the cluster are failed over. -
failedOver- enotes that a couchbase server node failed over to a new pod. This status is attached only to a node. -
inactiveFailed- is the value of the cluster membership as reported for a couchbase server node when it is in failed over state. -
N/A- is the value of the cluster membership if we are unable to determine the health of the cluster
ClusterHealthResponse
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
status |
X |
|||
health |
X |
|||
bucketStats |
||||
nodeStats |
ClusterStatus
Allowable Values
draft, needs_deploy, job_scheduled, deploying, deploy_failed, deploy_succeeded, ready, destroying, destroy_failed, destroy_succeeded, metrics_failed, preflight_started, preflight_failed, preflight_succeeded, management_blocked, upgrading
Description
-
draft- indicates that all fields under database model are mutable. -
needs_deploy- indicates that the new configuration changes have not been applied to the cluster -
job_scheduled- indicates that the new configuration changes have been scheduled to be applied. -
deploying- indicates that database is currently being deployed/new configurations being applied. -
deploy_failed- indicates that the last deployment failed. -
deploy_succeeded- indicates that the last deployment succeeded. -
ready- indicates that the database is ready. -
destroying- indicates that the database is being destroyed. -
destroy_failed- indicates that the database destroy job failed. -
destroy_succeeded- indicates that the database destroy job succeeded. -
metrics_failed- indicates that the database is not serving metrics. -
preflight_started- indicates a preflight check has started on the database -
preflight_failed- indicates a preflight check has failed on the database -
preflight_succeeded- indicates a preflight check has succeeded on the database -
management_blocked- indicates the IAM credentiald for the cloud hosting the databse have been deleted. -
upgrading- indicates the database is being upgrading.
ClusterSummary
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
id |
X |
uuid |
||
name |
X |
|||
tenantId |
X |
uuid |
||
cloudId |
X |
uuid |
||
projectId |
X |
uuid |
||
services |
X |
List of CouchbaseServices |
||
nodes |
X |
ClusterVersion
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
name |
X |
|||
components |
X |
Map of [string] |
CouchbaseBucketSpec
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
name |
X |
|||
memoryQuota |
X |
|||
replicas |
||||
conflictResolution |
CreateClusterRequest
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
name |
X |
|||
cloudId |
X |
uuid |
||
projectId |
X |
uuid |
||
servers |
List of Server |
|||
supportPackage |
||||
version |
CreateDatabaseUserRequest
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
userId |
Organization user which is assigned to the database user. |
uuid |
||
username |
X |
|||
password |
X |
|||
buckets |
List of BucketRole |
|||
allBucketsAccess |
CursorPages
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
page |
Current page starting from 1. |
|||
next |
Next page number, it is not set on the last page. |
|||
previous |
Previous page number, it is not set on the first page. |
|||
last |
Last page number. |
|||
perPage |
How many items are displayed in the page. |
|||
totalItems |
X |
Total items found by the given query. |
DeleteBucketRequest
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
name |
X |
The name of the bucket to be deleted |
EventResponse
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
id |
X |
Unique ID of the event |
||
key |
X |
Key defines the specific kind of Event. One from availability, billing, maintenance, performance or security |
||
severity |
The severity of the event. One from info, warning or critical |
|||
time |
X |
When the event happened, in RFC3339 format |
date-time |
|
tenantId |
X |
The TenantID this Event belongs to |
||
tenantName |
The name of the tenant at the time of event |
|||
cloudId |
The CloudID this Event refers to, only populated for In-VPC cluster |
|||
cloudName |
CloudName is the name of the cloud at the time of event emission. |
|||
projectId |
The ProjectID this Event refers to |
|||
projectName |
ProjectName is the name of the project at the time of event emission |
|||
clusterId |
The ClusterID this Event refers to |
|||
clusterName |
ClusterName is the name of the cluster at the time of event emission |
|||
syncGatewayId |
The SyncGatewayID this Event refers to |
|||
syncGatewayName |
SyncGatewayName is the name of the sync gateway at the time of event emission |
|||
actorId |
ActorID is the user id that initiated the request for this Event |
|||
actorName |
ActorName is the name of the associated user at the time of event emission |
|||
sessionId |
SessionID is the user that initiated the request for this Event |
|||
requestId |
RequestID string |
|||
summary |
Summary of the event |
ListBucketItem
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
id |
X |
|||
name |
X |
|||
memoryQuota |
X |
|||
replicas |
X |
|||
conflictResolution |
X |
|||
status |
X |
ListCloudsResponse
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
cursor |
X |
|||
data |
X |
List of CloudSummary |
ListClustersResponse
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
cursor |
X |
|||
data |
X |
List of ClusterSummary |
ListDatabaseUsersResponseItem
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
userId |
Organization user ID Database user is attached to |
uuid |
||
username |
X |
|||
access |
X |
List of BucketRole |
ListEventsResponse
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
cursor |
X |
|||
data |
X |
List of EventResponse |
ListProjectsResponse
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
cursor |
X |
|||
data |
X |
List of Project |
ListUsersResponse
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
cursor |
X |
|||
data |
X |
List of ListUsersResponseItem |
NodeStats
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
status |
X |
|||
totalCount |
X |
|||
failedOverCount |
X |
|||
unhealthyCount |
X |
|||
serviceStats |
X |
List of ServiceStats |
Project
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
id |
X |
uuid |
||
name |
X |
|||
tenantId |
X |
uuid |
||
createdAt |
X |
Creation date and time |
date-time |
Server
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
size |
X |
|||
services |
X |
List of CouchbaseServices |
||
aws |
||||
azure |
ServiceStats
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
services |
X |
List of [string] |
||
nodeName |
X |
|||
status |
X |
UpdateDatabaseUserRequest
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
userId |
Organization user to update which is assigned to the database user. |
uuid |
||
username |
||||
password |
||||
buckets |
List of BucketRole |
|||
allBucketsAccess |
V3Cluster
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
id |
X |
|||
name |
X |
|||
tenantId |
X |
|||
projectId |
X |
|||
createdAt |
X |
date-time |
||
updatedAt |
X |
date-time |
||
status |
X |
|||
version |
X |
|||
endpointsSrv |
||||
environment |
X |
|||
place |
X |
|||
servers |
X |
List of V3ClusterServers |
||
availabilityZones |
X |
List of [string] |
||
support |
X |
V3ClusterAuditFilterableEvent
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
id |
The event ID. |
|||
name |
The event name. |
|||
module |
The event module. |
|||
description |
A description of the event. |
V3ClusterAuditFilterableEventList
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
events |
List of V3ClusterAuditFilterableEvent |
V3ClusterAuditLogExport
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
status |
||||
downloadID |
||||
downloadURL |
||||
expiration |
date-time |
|||
createdAt |
date-time |
|||
start |
date-time |
|||
end |
date-time |
V3ClusterAuditLogExportCreate
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
start |
X |
Start time of requested audit logs. Must be at least 15 minutes in the past, and not exceed 30 days in the past. |
date-time |
|
end |
End time of requested audit logs. Must be at least 15 minutes after the given start time. Defaults to now. |
date-time |
V3ClusterAuditLogExportList
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
cursor |
X |
|||
data |
X |
List of V3ClusterAuditLogExport |
V3ClusterAuditSettings
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
auditdEnabled |
X |
Controls whether Audit logging is enabled or disabled. |
||
enabledEventIDs |
List of [integer] |
The disabled parameter indicates which individual filterable events are disabled. Its value must be one or more filterable-event IDs. Filterable-event IDs can be retrieved by means of the GET /clusters/{id}/audit/descriptors method and URI. |
||
disabledUsers |
The disabledUsers parameter disables filterable-event auditing on a per user basis. Its value must be an array of users, specified as objects with both name and domain fields. Each user may be:
- A local user, specified in the form |
V3ClusterAuditSettingsDisabledUsers
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
name |
X |
The name of the user. |
||
domain |
The domain of the user. |
V3ClusterListData
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
tenantId |
||||
items |
List of V3ClusterListDataItems |
V3ClusterListDataItems
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
environment |
X |
|||
cloudId |
||||
id |
X |
|||
name |
X |
|||
projectId |
X |
V3ClusterServers
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
size |
X |
|||
compute |
X |
Compute instance type |
||
services |
X |
List of [string] |
||
storage |
X |
V3CreateClusterRequest
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
environment |
X |
|||
clusterName |
X |
Name of the cluster |
||
projectId |
X |
Uniquely identifiable projectId |
uuid |
|
description |
A short description that describes the cluster |
|||
place |
X |
|||
servers |
X |
List of V3Servers |
Server specifications for creating the cluster |
|
supportPackage |
X |
V3CreateClusterUserRequest
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
username |
X |
|||
password |
X |
|||
allBucketsAccess |
||||
buckets |
V3CreateClusterUserRequestBuckets
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
name |
X |
|||
scope |
X |
enter '*' for getting access to all scopes within a bucket or the scope name for getting access to a single scope |
||
access |
X |
V3Place
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
singleAZ |
X |
Has to be true if the supportPackage.type is equal to "Basic" |
||
hosted |
V3PlaceHosted
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
provider |
X |
|||
region |
X |
A valid region for the cloudProvider |
||
CIDR |
X |
CIDR block. |
V3Servers
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
size |
X |
How many nodes, value >= 3, ⇐ 27. Total nodes in the cluster ⇐ 27 |
||
compute |
X |
Compute instance type |
||
services |
X |
List of V3CouchbaseServices |
Array of couchbase services to be installed on the nodes |
|
storage |
X |
V3ServersStorage
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
type |
X |
|||
IOPS |
Required for GP3 and IO2. Min 3000 for GP3, 1000 if IO2. If storageType="GP3", max = 16000. If storageType= "IO2", max= 64000 |
|||
size |
X |
Min 50GB, max 16TB |
V3UpdateClusterServersRequest
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
servers |
X |
List of V3Servers |