API docs by Redocly

Couchbase Capella Management API (v4.0)

Download OpenAPI specification:Download

The Couchbase Capella Management API provides a set of REST APIs for creating and managing Capella instances. It enables users to perform operations such as creating new Capella instances, managing their configurations, and interacting with the Capella services. This API documentation specifies the endpoints, request and response formats, and authentication requirements for seamless integration with Couchbase Capella.

To access the Management API, you need an API key. To create an initial bootstrap API key you must use the Capella UI. Once you have created an initial bootstrap API key, you can use the Management API itself to create further API keys. To learn more, see Get Started with the Management API v4.0.

For a history of updates to the Management API, see Management API v4.0 Change Log.

API Base URL:

https://cloudapi.cloud.couchbase.com

Back to Management API v4.0 Documentation

apikeys

Couchbase Capella Public API uses a Bearer token mechanism for authentication; each call to the Public API has to be authenticated by API key.

Create API Key

Creates a new API key under an organization.

Organization Owners can create Organization and Project scoped API keys.

Project Owner and Project Creator can create project scoped keys.

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

Request Body schema: application/json
name
required
string (APIKeyName)

Name of the API key.

description
string (APIKeyDescription)
Default: ""

Description for the API key.

expiry
number <float> (APIKeyExpiry)
Default: 180

Expiry of the API key in number of days. If set to -1, the token will not expire.

allowedCIDRs
Array of strings (APIKeyAllowedCIDRs)
Default: ["0.0.0.0/0"]

List of inbound CIDRs for the API key. The system making a request must come from one of the allowed CIDRs.

organizationRoles
required
Array of strings (APIKeyOrganizationRoles)
Items Enum: "organizationOwner" "organizationMember" "projectCreator"
Array of objects (APIKeyResources)
Default: []

Resources are the resource level permissions associated with the API key.

To learn more about Organization Roles, see Organization Roles.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Organization Owner API Key",
  • "description": "Creates an API key with a Organization Owner role.",
  • "expiry": 720,
  • "allowedCIDRs": [
    ],
  • "organizationRoles": [
    ],
  • "resources": [ ]
}

Response samples

Content type
application/json
{
  • "id": "IS9DrRsw4KWFS72Zhbj4xmhllHvPcdCL",
  • "token": "QktxVUtFU1dKV1FlMmxwbzJBYXdnTVlRemFZdlRDZTg6eFh4dzU4JUYjekJVYWZPY3lqdUwwYkJoTjZSTmlzRWFIRHF0b1h4a08yazBpQjJ1bms1OW4yTUhAenRib3IhVQ=="
}

List API keys

Lists all the API keys under an organization.

Organization Owners can list all the API keys inside the Organization.

Organization Members and Project Creators can list all the Project scoped API key for which they are Project Owner.

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

query Parameters
page
integer

Sets the page you would like to view.

perPage
integer

Sets the number of results you would like to have on each page.

sortBy
Array of strings
Example: sortBy=name

Sets the order of how you would like to sort the results and the key you would like to order by. Valid fields to sort the results are: name, expiry, description.

sortDirection
string
Enum: "asc" "desc"
Example: sortDirection=asc

The order in which the items will be sorted.

Responses

Response samples

Content type
application/json
{}

Get API Key

Fetches the details of the given API key under an organization.

Organization Owners can get any API key inside the Organization.

Organization Members and Project Creator can get any Project scoped API key for which they are Project Owner.

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

ApiKeyId
required
string
Example: ffffffffaaaa1414eeee000000000000

The ID (Access key) of the API key.

Responses

Response samples

Content type
application/json
{
  • "id": "IS9DrRsw4KWFS72Zhbj4xmhllHvPcdCL",
  • "name": "Organization Owner API Key",
  • "description": "Creates an API key with an Organization Owner role.",
  • "expiry": 720,
  • "allowedCIDRs": [
    ],
  • "organizationRoles": [
    ],
  • "resources": [ ],
  • "audit": {
    }
}

Delete API Key

Deletes the given API key under an organization.

Organization Owners can delete any API key inside the Organization.

Organization Members and Project Creator can delete any Project scoped API key for which they are Project Owner.

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

ApiKeyId
required
string
Example: ffffffffaaaa1414eeee000000000000

The ID (Access key) of the API key.

Responses

Response samples

Content type
application/json
{
  • "httpStatusCode": 403,
  • "code": 1002,
  • "message": "Access Denied.",
  • "hint": "Your access to the requested resource is denied. Please make sure you have the necessary permissions to access the resource."
}

Rotate API Key

Rotate the secret of a given API key under an organization.

Organization Owners can rotate any API key inside the Organization.

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

ApiKeyId
required
string
Example: ffffffffaaaa1414eeee000000000000

The ID (Access key) of the API key.

Request Body schema: application/json
secret
string

A secret associated with API key. One has to follow the secret key policy, such as allowed characters and a length of 64 characters. If this field is left empty, a secret will be auto-generated.

Responses

Request samples

Content type
application/json
{
  • "secret": "GaC4FQLCoUqoKUMBvl6BgRK1Ivqu5yF8OkDBhnP%#CH%S4T@bTVUdP#rY#VSicbx"
}

Response samples

Content type
application/json
{
  • "secretKey": "GaC4FQLCoUqoKUMBvl6BgRK1Ivqu5yF8OkDBhnP%#CH%S4T@bTVUdP#rY#VSicbx"
}

projects

Projects contain and allow access to Couchbase databases. Projects are used to organize and manage groups of Couchbase databases within organizations. An organization can contain any number of projects, and a project can contain any number of databases.

Create Project

Creates a new project under the organization.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Creator

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

Request Body schema: application/json
name
required
string <= 128 characters

The name of the project (up to 128 characters).

description
string <= 256 characters

A short description of the project (up to 256 characters).

Responses

Request samples

Content type
application/json
{
  • "name": "My Project",
  • "description": "My awesome project"
}

Response samples

Content type
application/json
{
  • "id": "ffffffff-aaaa-1414-eeee-000000000000"
}

List Project

Lists all the projects under the organization.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager
  • Project Viewer
  • Database Data Reader/Writer
  • Database Data Reader

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

query Parameters
page
integer

Sets the page you would like to view.

perPage
integer

Sets the number of results you would like to have on each page.

sortBy
Array of strings
Example: sortBy=name

Sets the order of how you would like to sort the results and the key you would like to order by. Valid fields to sort the results are: id, name.

sortDirection
string
Enum: "asc" "desc"
Example: sortDirection=asc

The order in which the items will be sorted.

Responses

Response samples

Content type
application/json
{}

Get Project

Fetches the details of the given project.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager
  • Project Viewer
  • Database Data Reader/Writer
  • Database Data Reader

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

Responses

Response samples

Content type
application/json
{
  • "id": "ffffffff-aaaa-1414-eeee-000000000000",
  • "description": "The description of my awesome project",
  • "name": "My-Awesome-Project",
  • "audit": {
    }
}

Update Project

Update project name and or project description.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

header Parameters
If-Match
string
Example: 12

A precondition header that specifies the entity tag of a resource.

Request Body schema: application/json
name
required
string <= 128 characters

The new project name (up to 128 characters).

description
string <= 256 characters

The new project description (up to 256 characters).

Responses

Request samples

Content type
application/json
{
  • "name": "My-New-Project",
  • "description": "The extended description of my awesome project."
}

Response samples

Content type
application/json
{
  • "httpStatusCode": 400,
  • "code": 6007,
  • "message": "The request was malformed or invalid.",
  • "hint": "The request was malformed or invalid."
}

Delete Project

Deletes an existing project.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

Responses

Response samples

Content type
application/json
{
  • "httpStatusCode": 403,
  • "code": 1002,
  • "message": "Access Denied.",
  • "hint": "Your access to the requested resource is denied. Please make sure you have the necessary permissions to access the resource."
}

clusters

A Couchbase cluster consists of one or more instances of Couchbase Capella, each running on an independent node. Data and services are shared across the cluster. A cluster may be referred to as a "database" in the documentation and in the Couchbase Capella user interface.

Create Cluster

Creates a new Couchbase Capella provisioned cluster.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

Request Body schema: application/json
name
required
string <= 256 characters

Name of the cluster (up to 256 characters).

description
string <= 1024 characters

Description of the cluster (up to 1024 characters).

configurationType
string (ConfigurationType)
Default: ["multiNode"]
Enum: "singleNode" "multiNode"
  • Multi-node databases are best for deployments that require high availability. If your app requires high performance and high availability, choose the Multi-node option.
  • Single-node databases have resource limitations that make them a good choice for learning, prototyping, and non-production uses. They have limited availability.
  • Single-node databases should contain only 1 node and 1 Service Group. Adding number of nodes or service groups > 1 is not allowed for such databases.
  • By default the configurationType is multiNode.
required
object (CloudProvider)

The cloud provider where the cluster will be hosted. For information about providers and supported regions, see:

object (CouchbaseServer)
required
Array of objects (ServiceGroup) non-empty

The couchbase service groups to be run. - The set of nodes that share the same disk, number of nodes and services. - At least one service group must contain the data service.

required
object (Availability)
required
object (Support)
cmekId
string <uuid>

The ID of the CMEK Key.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Test-Cluster-1",
  • "description": "My first test AWS cluster for multiple services.",
  • "cloudProvider": {
    },
  • "couchbaseServer": {
    },
  • "serviceGroups": [
    ],
  • "availability": {
    },
  • "support": {
    }
}

Response samples

Content type
application/json
{
  • "id": "ffffffff-aaaa-1414-eeee-000000000000"
}

List Clusters

Lists all the clusters under the organization.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager
  • Project Viewer
  • Database Data Reader/Writer
  • Database Data Reader

Returned set of clusters is reduced to what the caller has access to view. To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

query Parameters
page
integer

Sets the page you would like to view.

perPage
integer

Sets the number of results you would like to have on each page.

sortBy
Array of strings
Example: sortBy=name

Sets the order of how you would like to sort the results and the key you would like to order by. Valid fields to sort the results are: id, availability, cloudProvider, couchbaseServer, currentState, name.

sortDirection
string
Enum: "asc" "desc"
Example: sortDirection=asc

The order in which the items will be sorted.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "cursor": {}
}

Get Cluster

Fetches the details of the given cluster.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager
  • Project Viewer
  • Database Data Reader/Writer
  • Database Data Reader

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

Responses

Response samples

Content type
application/json
{
  • "id": "ffffffff-aaaa-1414-eeee-000000000000",
  • "appServiceId": "ffffffff-aaaa-1414-eeee-000000000000",
  • "name": "Test Cluster",
  • "description": "Description of the cluster",
  • "configurationType": "multiNode",
  • "connectionString": "couchbases://cb.irxmynm6vekhe5.aws-cb.couchbase.com",
  • "cloudProvider": {
    },
  • "couchbaseServer": {
    },
  • "serviceGroups": [
    ],
  • "availability": {
    },
  • "support": {
    },
  • "currentState": "deploying",
  • "audit": {
    },
  • "cmekId": "ffffffff-aaaa-1414-eeee-000000000000"
}

Update Cluster

Updates an existing cluster.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

header Parameters
If-Match
string
Example: 12

A precondition header that specifies the entity tag of a resource.

Request Body schema: application/json
name
required
string <= 256 characters

The new name of the cluster (up to 256 characters).

description
required
string <= 1024 characters

The new cluster description (up to 1024 characters).

required
object (Support)
required
Array of objects (ServiceGroup)

Responses

Request samples

Content type
application/json
{
  • "name": "My-New-Cluster",
  • "description": "The extended description of my new cluster.",
  • "support": {
    },
  • "serviceGroups": [
    ]
}

Response samples

Content type
application/json
{
  • "httpStatusCode": 403,
  • "code": 1002,
  • "message": "Access Denied.",
  • "hint": "Your access to the requested resource is denied. Please make sure you have the necessary permissions to access the resource."
}

Delete Cluster

Deletes an existing cluster.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

Responses

Response samples

Content type
application/json
{
  • "httpStatusCode": 403,
  • "code": 1002,
  • "message": "Access Denied.",
  • "hint": "Your access to the requested resource is denied. Please make sure you have the necessary permissions to access the resource."
}

Turn On Cluster

Turn cluster on.

In order to access this endpoint, the provided API key must have at least one of the roles referenced below:

  • Organization Owner
  • Project Owner

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

Request Body schema: application/json
turnOnLinkedAppService
boolean
Default: false

Set this value to true if you want to turn on the app service linked with the cluster, false if not. If set to true, the app service, if present, will turn on with the cluster. Default value for this is false, which means the linked app service will be kept off.

Responses

Request samples

Content type
application/json
Example
{
  • "turnOnLinkedAppService": true
}

Response samples

Content type
application/json
{
  • "httpStatusCode": 403,
  • "code": 1002,
  • "message": "Access Denied.",
  • "hint": "Your access to the requested resource is denied. Please make sure you have the necessary permissions to access the resource."
}

Turn Off Cluster

Turn cluster off.

  • Turning off your cluster turns off the compute for your cluster but the storage remains. All of the data, schema (buckets, scopes, and collections), and indexes remain, as well as cluster configuration, including users and allow lists.

  • Turning off cluster will also turn off any linked app services.

In order to access this endpoint, the provided API key must have at least one of the roles referenced below:

  • Organization Owner
  • Project Owner

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

Responses

Response samples

Content type
application/json
{
  • "httpStatusCode": 403,
  • "code": 1002,
  • "message": "Access Denied.",
  • "hint": "Your access to the requested resource is denied. Please make sure you have the necessary permissions to access the resource."
}

users

To access an organization, your Couchbase Capella user account must be added to it. Accounts are added to an organization using email invitations sent from Capella by a user with the Organization Owner organization role. All organization users are given one or more organization roles that define what they can view and manage in their organization.

Create User

Invites a new user under the organization.

After making a REST API request, an invitation email is triggered and sent to the user. Upon receiving the invitation email, the user is required to click on a provided URL, which will redirect them to a page with a user interface (UI) where they can set their username and password.

The modification of any personal information related to a user can only be performed by the user through the UI. Similarly, the user can solely conduct password updates through the UI.

The "caller" possessing Organization Owner access rights retains the exclusive user creation capability. They hold the authority to assign roles at the organization and project levels.

At present, our support is limited to the resourceType of "project" exclusively.

In order to access this endpoint, the provided API key must have the following role:

  • Organization Owner

To learn more, see Organization Roles.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

Request Body schema: application/json
name
string <= 128 characters

The name of the user.

email
required
string (Email)

Email of the user.

organizationRoles
required
Array of strings (OrganizationRoles)
Items Enum: "organizationOwner" "organizationMember" "projectCreator"
Array of objects (Resource)
Default: []

Responses

Request samples

Content type
application/json
Example

At present, our support is limited to the resourceType of "project" exclusively. Furthermore, the role designation is solely related to roles at the project level.

{
  • "name": "John",
  • "email": "john.doe@example.com",
  • "organizationRoles": [
    ],
  • "resources": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "ffffffff-aaaa-1414-eeee-000000000000"
}

List Users

Lists all the users in the organization and filter on the basis of projectId.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Organization Member
  • Project Creator

The results are always limited by the role and scope of the caller's privileges.

When retrieving a list of users through a GET request, if a user holds the organization owner role, the response will exclude project-level permissions for those users. This is because organization owners have full access to all resources within the organization, making project-level permissions irrelevant for them.

To learn more about the roles, see Organization Roles and Project Roles.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

query Parameters
page
integer

Sets the page you would like to view.

perPage
integer

Sets the number of results you would like to have on each page.

sortBy
Array of strings
Example: sortBy=name

Sets the order of how you would like to sort the results and the key you would like to order by. Valid fields to sort the results are: id, name, email, status, inactive.

sortDirection
string
Enum: "asc" "desc"
Example: sortDirection=asc

The order in which the items will be sorted.

projectId
string <uuid>
Example: projectId=ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

Responses

Response samples

Content type
application/json
Example

In the event that the API key holds "organizationOwner" access, information related to all projects within the organization will be returned.

{
  • "data": [
    ],
  • "cursor": {}
}

Get User

Fetches the details of the given user.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Organization Member
  • Project Creator

The results are always limited by the role and scope of the caller's privileges.

When performing a GET request for a user with an organization owner role, the response will exclude project-level permissions for that user. This is because organization owners have access to all resources at the organization level, rendering project-level permissions unnecessary for them.

To learn more about the roles, see Organization Roles and Project Roles.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

userId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the control plane user.

Responses

Response samples

Content type
application/json
{
  • "id": "ffffffff-aaaa-1414-eeee-000000000000",
  • "name": "alex",
  • "email": "john.doe@example.com",
  • "status": "not-verified",
  • "inactive": false,
  • "organizationId": "ffffffff-aaaa-1414-eeee-000000000000",
  • "organizationRoles": [
    ],
  • "lastLogin": "2023-07-17T07:05:39.116124897Z",
  • "region": "North America",
  • "timeZone": "(UTC -9:00) Alaska Standard Time",
  • "enableNotifications": true,
  • "expiresAt": "2023-07-17T07:05:39.116124897Z",
  • "resources": [
    ],
  • "audit": {
    }
}

Update User

Updates organizationRole and resources of the user.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner

An Organization Owner API key can be utilized to update organizational-level roles and project-level roles for all projects within the organization.

The Project Owner API key allows for updating project-level roles, solely within the projects where the API key holds the Project Owner role.

The modification of any personal information related to a user, such as password updates, can only be performed by the respective user through the user interface (UI).

The results are always limited by the role and scope of the caller's privileges. To learn more about the roles, see Organization Roles and Project Roles.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

userId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the control plane user.

Request Body schema: application/json
Array
op
required
string
Enum: "add" "remove"

Type of operation.

path
required
string

Path of resource that needs to be updated.

Organization Roles: /organizationRoles

Resources: /resources/{resourceId}

Resource Roles: /resources/{resourceId}/roles

Array of OrganizationRoles (strings) or Array of ProjectRoles (strings) or Resource (object)

Responses

Request samples

Content type
application/json
Example
[
  • {
    }
]

Response samples

Content type
application/json
Example
{
  • "id": "ffffffff-aaaa-1414-eeee-000000000000",
  • "name": "Jane",
  • "email": "jane.doe@example.com",
  • "status": "verified",
  • "inactive": false,
  • "organizationId": "ffffffff-aaaa-1414-eeee-000000000000",
  • "organizationRoles": [
    ],
  • "lastLogin": "2023-07-17T07:05:39.116Z",
  • "region": "North America",
  • "timeZone": "(UTC +5:30) India Standard Time",
  • "enableNotifications": false,
  • "expiresAt": "2023-07-17T07:05:39.116Z",
  • "resources": [
    ],
  • "audit": {
    }
}

Delete User

Removes user from the organization.

In order to access this endpoint, the provided API key must have the following role:

  • Organization Owner

To learn more about the roles, see Organization Roles.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

userId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the control plane user.

Responses

Response samples

Content type
application/json
{
  • "httpStatusCode": 403,
  • "code": 1002,
  • "message": "Access Denied.",
  • "hint": "Your access to the requested resource is denied. Please make sure you have the necessary permissions to access the resource."
}

Update Username

Updates the user name of the user.

In order to access this endpoint, the provided API key must have the following role:

  • Organization Owner

To learn more about the roles, see Organization Roles.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

userId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the control plane user.

Request Body schema: application/json
name
required
string <= 128 characters

The new name of the user.

Responses

Request samples

Content type
application/json
{
  • "name": "John"
}

Response samples

Content type
application/json
{
  • "httpStatusCode": 400,
  • "code": 6007,
  • "message": "The request was malformed or invalid.",
  • "hint": "The request was malformed or invalid."
}

allowedCIDRs(Cluster)

Couchbase Capella only allows trusted IP addresses to connect to databases. Each database has a configurable Allowed IP list that can include up to 75 entries. Each entry can be a single IP address or an IP address space. Any IP address you add to this list can have a user-specified expiration time for temporary access, or be permanent. Capella automatically denies any connection attempts to and from an IP not in the allowed IP list.

Create Allowed CIDR

Adds a trusted CIDR to a cluster's list of allowed CIDRs.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager

To learn more, see Organization, Project, and Database Access Overview.

Note that updating this resource is not supported; you must delete and recreate allowed CIDRs instead. As a result, ETags are also not supported for this resource.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

Request Body schema: application/json
cidr
required
string

The trusted CIDR to allow the database connections from. The example represents a single IP address (i.e. a subnet mask of 32).

comment
string

A short description of the allowed CIDR.

expiresAt
string <date-time>

An RFC3339 timestamp determining when the allowed CIDR should expire. If this field is empty/omitted then the allowed CIDR is permanent and will never automatically expire.

Responses

Request samples

Content type
application/json
{
  • "cidr": "6.60.28.100/32",
  • "comment": "Allows access from my local developer machine",
  • "expiresAt": "2023-05-14T21:49:58.465Z"
}

Response samples

Content type
application/json
{
  • "id": "ffffffff-aaaa-1414-eeee-000000000000"
}

List Allowed CIDRs

Lists all of the allowed CIDRs for a given cluster.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager
  • Project Viewer
  • Database Data Reader/Writer
  • Database Data Reader

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

query Parameters
page
integer

Sets the page you would like to view.

perPage
integer

Sets the number of results you would like to have on each page.

sortBy
Array of strings
Example: sortBy=id

Sets the order of how you would like to sort the results and the key you would like to order by. Valid fields to sort the results are: id, type, status.

sortDirection
string
Enum: "asc" "desc"
Example: sortDirection=asc

The order in which the items will be sorted.

Responses

Response samples

Content type
application/json
{}

Get Allowed CIDR

Fetches the details for the specified allowed CIDR.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager
  • Project Viewer
  • Database Data Reader/Writer
  • Database Data Reader

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

allowedCidrId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the allowed CIDR.

Responses

Response samples

Content type
application/json
{
  • "id": "ffffffff-aaaa-1414-eeee-000000000000",
  • "cidr": "1.23.45.67/32",
  • "comment": "Allows access from my local developer machine",
  • "expiresAt": "2023-05-14T21:49:58.465Z",
  • "status": "active",
  • "type": "temporary",
  • "audit": {
    }
}

Delete Allowed CIDR

Deletes the existing allowed CIDR.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

allowedCidrId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the allowed CIDR.

Responses

Response samples

Content type
application/json
{
  • "httpStatusCode": 403,
  • "code": 1002,
  • "message": "Access Denied.",
  • "hint": "Your access to the requested resource is denied. Please make sure you have the necessary permissions to access the resource."
}

databaseCredentials

Database credentials provide programmatic and application-level access to data on a database. Only database credentials can access data.

List Database Credentials

Lists all the database credential information under a cluster.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager
  • Project Viewer

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

query Parameters
page
integer

Sets the page you would like to view.

perPage
integer

Sets the number of results you would like to have on each page.

sortBy
Array of strings
Example: sortBy=name

Sets the order of how you would like to sort the results and the key you would like to order by. Valid fields to sort the results are: name, id.

sortDirection
string
Enum: "asc" "desc"
Example: sortDirection=asc

The order in which the items will be sorted.

Responses

Response samples

Content type
application/json
{}

Create Database Credentials

Creates a new database credential under a cluster.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner

Valid fields to sort the results are: "id", "name".

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

Request Body schema: application/json
name
required
string [ 2 .. 128 ] characters

Username for the database credential. The name should adhere to the following rules:

  1. The name must be between 2 & 128 characters.

  2. The name cannot contain spaces.

  3. The name cannot contain the following characters - ) ( > < , ; : " \ / ] [ ? = } {

  4. The name cannot begin with @ character.

password
string >= 8 characters

A password associated with the database credential. If this field is left empty, a password will be auto-generated.

  • The password should adhere to the following rules:

    1. The password should have at least 8 characters.

    2. Characters used for the password should contain at least one uppercase (A-Z), one lowercase (a-z), one numerical (0-9), and one special character.

    3. The password must not contain any of the following characters: < > ; . * & | £

required
Array of objects (Access)

Describes the access information of the database credential.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "ReadWriteOnSpecificCollections",
  • "access": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "ffffffff-aaaa-1414-eeee-000000000000",
  • "password": "P@ssw0rd!"
}

Get Database Credentials

Fetches the details of a given cluster's database credential information.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager
  • Project Viewer

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

userId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the database credential.

Responses

Response samples

Content type
application/json
{
  • "id": "ffffffff-aaaa-1414-eeee-000000000000",
  • "name": "ReadInventory",
  • "audit": {
    },
  • "access": [
    ]
}

Update Database Credentials

Updates an existing database credential.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

userId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the database credential.

header Parameters
If-Match
string
Example: 12

A precondition header that specifies the entity tag of a resource.

Request Body schema: application/json
Array of objects (Access)

Describes the access information of the database credential.

password
string

The updated password of the database credential.

Responses

Request samples

Content type
application/json
{
  • "access": [
    ]
}

Response samples

Content type
application/json
{
  • "httpStatusCode": 403,
  • "code": 1002,
  • "message": "Access Denied.",
  • "hint": "Your access to the requested resource is denied. Please make sure you have the necessary permissions to access the resource."
}

Delete Database Credentials

Deletes an existing cluster's database credential.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

userId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the database credential.

Responses

Response samples

Content type
application/json
{
  • "httpStatusCode": 403,
  • "code": 1002,
  • "message": "Access Denied.",
  • "hint": "Your access to the requested resource is denied. Please make sure you have the necessary permissions to access the resource."
}

buckets, scopes, & collections

A bucket is the fundamental space for storing data in Couchbase Capella. Scopes and Collections are logical containers within a bucket and a way for organizing data within buckets. A scope is a mechanism for the grouping of multiple collections. A collection is a data container for related documents.

Create Bucket

Creates a new bucket configuration under a cluster.

To learn more about bucket configuration, see Buckets.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

Request Body schema: application/json
name
required
string <= 100 characters

Name of the bucket. This field cannot be changed later. The name should adhere to the following rules:

  1. Characters used for the name should be in the ranges of A-Z, a-z, and 0-9; plus the underscore, period, dash, and percent characters.

  2. The name can be a maximum of 100 characters in length.

  3. The name cannot have 0 characters or empty. Minimum length of name is 1.

  4. The name cannot start with a . (period).

type
string (Type)
Default: "couchbase"
Enum: "couchbase" "ephemeral"

Type of the bucket.

  • If selected Ephemeral, it is not eligible for imports or App Endpoints creation. This field cannot be changed later.

  • The options may also be referred to as Memory and Disk (Couchbase), Memory Only (Ephemeral) in the Couchbase documentation.

To learn more, see Create a Bucket.

storageBackend
string (StorageBackend)
Default: "couchstore"
Enum: "couchstore" "magma"

The storage engine to be assigned to and used by the bucket.

  • Ephemeral buckets do not support StorageBackend, hence not applicable for Ephemeral buckets and throws an error if this field is added.

  • This field is only applicable for a Couchbase bucket. The default value mentioned (Couchstore) is for Couchbase bucket.

  • This field cannot be changed later.

    To learn more, see Storage Engines.

memoryAllocationInMb
integer
Default: 100

The amount of memory to allocate for the bucket memory in MiB. This is the maximum limit is dependent on the allocation of the KV service. For example, 80% of the allocation.

  • The default value (100MiB) mentioned is for Couchbase type buckets with Couchstore as the Storage Backend.

  • For Couchbase buckets, the default and minimum memory allocation changes according to the Storage Backend type as follows:

    1. For Couchstore, the default and minimum memory allocation is 100 MiB.

    2. For Magma, the default and minimum memory allocation is 1024 MiB.

  • For Ephemeral buckets, the default and minimum memory allocation is 100 MiB.

bucketConflictResolution
string (BucketConflictResolution)
Default: "seqno"
Enum: "seqno" "lww"

The means by which conflicts are resolved during replication.

  • This field may be referred to as "conflict resolution" in the Couchbase documentation, and seqno and lww may be referred to as "sequence number" and "timestamp" respectively.

  • This field cannot be changed later.

To learn more, see Conflict Resolution.

durabilityLevel
string (DurabilityLevel)
Default: "none"
Enum: "none" "majority" "majorityAndPersistActive" "persistToMajority"

This is the minimum level at which all writes to the bucket must occur.

The options for Durability level are as follows, according to the bucket type.

  • For a Couchbase bucket:

    1. None

    2. Replicate to Majority

    3. Majority and Persist to Active

    4. Persist to Majority

  • For an Ephemeral bucket:

    1. None

    2. Replicate to Majority

To learn more, see Create a Bucket.

replicas
integer (Replicas)
Default: 1
Enum: 1 2 3

The number of replicas for the bucket. To learn more, see Create a Bucket.

flush
boolean
Default: false

Determines whether flushing is enabled on the bucket. Enable Flush to delete all items in this bucket at the earliest opportunity. Disable Flush to avoid inadvertent data loss.

timeToLiveInSeconds
integer
Default: 0

Specify the time to live (TTL) value in seconds. This is the maximum time to live for items in the bucket. Default is 0, that means TTL is disabled. This is a non-negative value.

evictionPolicy
string (EvictionPolicy)
Default: "fullEviction"
Enum: "fullEviction" "noEviction" "nruEviction"

The policy which Capella adopts to prevent data loss due to memory exhaustion. This may be also known as Ejection Policy in the Couchbase documentation.

  • For Couchbase bucket, Eviction Policy is fullEviction by default.

  • For Ephemeral buckets, Eviction Policy is a required field, and should be one of the following:

    1. noEviction

    2. nruEviction

    To learn more, see Ejection Policy.

priority
integer (BucketPriority)
Default: 0

Priority of the bucket.

  • Specify relative bucket priority so that buckets will be recovered in the order specified during failover.

  • Bucket ranking/priority is only available in Couchbase Server 7.6 and above

  • Default bucket priority is 0 and can be set to a value between 0 and 1000. 1000 is the highest priority and 0 is the lowest.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "CBExample1",
  • "type": "couchbase",
  • "storageBackend": "couchstore",
  • "memoryAllocationInMb": 105,
  • "bucketConflictResolution": "seqno",
  • "durabilityLevel": "majorityAndPersistActive",
  • "replicas": 2,
  • "flush": true,
  • "timeToLiveInSeconds": 100
}

Response samples

Content type
application/json
{
  • "id": "dGVzdA"
}

List Buckets

Lists all the buckets under the cluster.

To learn more about bucket configuration, see Buckets.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager
  • Project Viewer
  • Database Data Reader/Writer
  • Database Data Reader

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get Bucket

Fetches the configuration of the given bucket.

To learn more about bucket configuration, see Buckets.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager
  • Project Viewer
  • Database Data Reader/Writer
  • Database Data Reader

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

bucketId
required
string
Example: dGVzdA

The ID of the bucket. It is the URL-compatible base64 encoding of the bucket name.

Responses

Response samples

Content type
application/json
{
  • "id": "dGVzdA",
  • "name": "My-First-Bucket",
  • "type": "string",
  • "storageBackend": "couchstore",
  • "memoryAllocationInMb": 100,
  • "bucketConflictResolution": "string",
  • "durabilityLevel": "string",
  • "replicas": 0,
  • "flush": false,
  • "timeToLiveInSeconds": 100,
  • "evictionPolicy": "fullEviction",
  • "stats": {
    },
  • "priority": 0
}

Update Bucket

Updates an existing bucket.

To learn more about bucket configuration, see Buckets.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

bucketId
required
string
Example: dGVzdA

The ID of the bucket. It is the URL-compatible base64 encoding of the bucket name.

Request Body schema: application/json
memoryAllocationInMb
required
integer

The new amount of memory to allocate for the bucket memory in MiB. The maximum limit is dependent on the allocation of the KV service; for example, 80% of the allocation.

  • For Couchbase buckets, the default and minimum memory allocation changes according to the Storage Backend type, as follows:

    1. For Couchstore, the default and minimum memory allocation is 100 MiB.

    2. For Magma, the default and minimum memory allocation is 1024 MiB.

  • For Ephemeral buckets, the default and minimum memory allocation is 100 MiB.

durabilityLevel
required
string
Enum: "none" "majority" "majorityAndPersistActive" "persistToMajority"

This is the minimum level at which all writes to the bucket must occur.

The options for Durability level are as follows, according to the bucket type.

  • For a Couchbase bucket:

    1. None

    2. Replicate to Majority

    3. Majority and Persist to Active

    4. Persist to Majority

  • For an Ephemeral bucket:

    1. None

    2. Replicate to Majority

    To learn more, see Create a Bucket.

replicas
required
integer
Enum: 1 2 3

The number of replicas for the bucket. To learn more, see Create a Bucket.

flush
required
boolean

The new value of flush. This determines whether flushing is enabled on the bucket. Enable Flush to delete all items in this bucket at the earliest opportunity. Disable Flush to avoid inadvertent data loss.

timeToLiveInSeconds
required
integer

Specify the new time to live (TTL) value in seconds. This is the maximum time to live for items in the bucket. If specified as 0, TTL is disabled. This is a non-negative value.

priority
integer (BucketPriority)
Default: 0

Priority of the bucket.

  • Specify relative bucket priority so that buckets will be recovered in the order specified during failover.

  • Bucket ranking/priority is only available in Couchbase Server 7.6 and above

  • Default bucket priority is 0 and can be set to a value between 0 and 1000. 1000 is the highest priority and 0 is the lowest.

Responses

Request samples

Content type
application/json
{
  • "memoryAllocationInMb": 100,
  • "durabilityLevel": "none",
  • "replicas": 1,
  • "flush": true,
  • "timeToLiveInSeconds": 100,
  • "priority": 0
}

Response samples

Content type
application/json
{
  • "httpStatusCode": 403,
  • "code": 1002,
  • "message": "Access Denied.",
  • "hint": "Your access to the requested resource is denied. Please make sure you have the necessary permissions to access the resource."
}

Delete Bucket

Deletes an existing bucket.

To learn more about bucket configuration, see Buckets.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

bucketId
required
string
Example: dGVzdA

The ID of the bucket. It is the URL-compatible base64 encoding of the bucket name.

Responses

Response samples

Content type
application/json
{
  • "httpStatusCode": 403,
  • "code": 1002,
  • "message": "Access Denied.",
  • "hint": "Your access to the requested resource is denied. Please make sure you have the necessary permissions to access the resource."
}

Create Scope

Creates a new scope in a bucket.

To learn more about scopes and collections, see Buckets, Scopes, and Collections.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

bucketId
required
string
Example: dGVzdA

The ID of the bucket. It is the URL-compatible base64 encoding of the bucket name.

Request Body schema: application/json
name
required
string

The name of the scope. The name should adhere to the following rules:

  1. The name must be between 1 and 251 characters in length.

  2. The name can contain only the characters A-Z, a-z, 0-9, and the symbols _, -, and %.

  3. The name cannot start with _ or %.

Note that scope and collection names are case-sensitive.

Responses

Request samples

Content type
application/json
{
  • "name": "my-scope"
}

Response samples

Content type
application/json
{
  • "httpStatusCode": 400,
  • "code": 6007,
  • "message": "The request was malformed or invalid.",
  • "hint": "The request was malformed or invalid."
}

List Scopes

Lists all the scopes in the bucket.

To learn more about scopes and collections, see Buckets, Scopes, and Collections.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager
  • Project Viewer
  • Database Data Reader/Writer
  • Database Data Reader

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

bucketId
required
string
Example: dGVzdA

The ID of the bucket. It is the URL-compatible base64 encoding of the bucket name.

Responses

Response samples

Content type
application/json
{
  • "scopes": [
    ]
}

Get Scope

Fetches the details of the given scope.

To learn more about scopes and collections, see Buckets, Scopes, and Collections.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager
  • Project Viewer
  • Database Data Reader/Writer
  • Database Data Reader

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

bucketId
required
string
Example: dGVzdA

The ID of the bucket. It is the URL-compatible base64 encoding of the bucket name.

scopeName
required
string
Example: inventory

The name of the scope.

Responses

Response samples

Content type
application/json
{
  • "name": "inventory",
  • "collections": [
    ]
}

Delete Scope

Deletes an existing scope.

To learn more about scopes and collections, see Buckets, Scopes, and Collections.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

bucketId
required
string
Example: dGVzdA

The ID of the bucket. It is the URL-compatible base64 encoding of the bucket name.

scopeName
required
string
Example: inventory

The name of the scope.

Responses

Response samples

Content type
application/json
{
  • "httpStatusCode": 400,
  • "code": 6007,
  • "message": "The request was malformed or invalid.",
  • "hint": "The request was malformed or invalid."
}

Create Collection

Creates a new collection in a scope.

To learn more about scopes and collections, see Buckets, Scopes, and Collections.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

bucketId
required
string
Example: dGVzdA

The ID of the bucket. It is the URL-compatible base64 encoding of the bucket name.

scopeName
required
string
Example: inventory

The name of the scope.

Request Body schema: application/json
name
required
string

The name of the collection. The name should adhere to the following rules:

  1. The name must be between 1 and 251 characters in length.

  2. The name can contain only the characters A-Z, a-z, 0-9, and the symbols _, -, and %.

  3. The name cannot start with _ or %.

Note that scope and collection names are case-sensitive.

maxTTL
integer

Specify the time to live (TTL) value in seconds. Defines the duration (Seconds) for which the documents in a collection are kept before automatic removal from the database. - For server versions < 7.6.0, this is a non-negative value. Set to 0 to use the bucket's maxTTL value. - For server versions >= 7.6.0, this value should be >= -1. Set to -1 to disable expiry for that collection. Set to 0 to use the bucket's maxTTL value. - The maximum value that can be set for maxTTL is 2147483647.

Responses

Request samples

Content type
application/json
{
  • "name": "my-collection",
  • "maxTTL": 100
}

Response samples

Content type
application/json
{
  • "httpStatusCode": 400,
  • "code": 6007,
  • "message": "The request was malformed or invalid.",
  • "hint": "The request was malformed or invalid."
}

List Collections

Lists all the collections in a scope.

To learn more about scopes and collections, see Buckets, Scopes, and Collections.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager
  • Project Viewer
  • Database Data Reader/Writer
  • Database Data Reader

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

bucketId
required
string
Example: dGVzdA

The ID of the bucket. It is the URL-compatible base64 encoding of the bucket name.

scopeName
required
string
Example: inventory

The name of the scope.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get Collection

Fetches the details of the given collection.

To learn more about scopes and collections, see Buckets, Scopes, and Collections.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager
  • Project Viewer
  • Database Data Reader/Writer
  • Database Data Reader

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

bucketId
required
string
Example: dGVzdA

The ID of the bucket. It is the URL-compatible base64 encoding of the bucket name.

scopeName
required
string
Example: inventory

The name of the scope.

collectionName
required
string
Example: airline

The name of the collection.

Responses

Response samples

Content type
application/json
{
  • "name": "airport",
  • "maxTTL": 0
}

Update Collection

Updates an existing collection.

This operation is only allowed for a cluster with server version >= 7.6.0. A collection cannot be updated for the server versions lower than this.

This allows to update the maxTTL of the given collection.

To learn more about scopes and collections, see Buckets, Scopes, and Collections.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

bucketId
required
string
Example: dGVzdA

The ID of the bucket. It is the URL-compatible base64 encoding of the bucket name.

scopeName
required
string
Example: inventory

The name of the scope.

collectionName
required
string
Example: airline

The name of the collection.

Request Body schema: application/json
maxTTL
required
integer

Specify the new time to live (TTL) value in seconds.

  • This value should be >= -1. Set to -1 to disable expiry for that collection.
  • Set to 0 to use the bucket's maxTTL value.
  • The maximum value that can be set for maxTTL is 2147483647.

Responses

Request samples

Content type
application/json
{
  • "maxTTL": 100
}

Response samples

Content type
application/json
{
  • "httpStatusCode": 403,
  • "code": 1002,
  • "message": "Access Denied.",
  • "hint": "Your access to the requested resource is denied. Please make sure you have the necessary permissions to access the resource."
}

Delete Collection

Deletes an existing collection.

To learn more about scopes and collections, see Buckets, Scopes, and Collections.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

bucketId
required
string
Example: dGVzdA

The ID of the bucket. It is the URL-compatible base64 encoding of the bucket name.

scopeName
required
string
Example: inventory

The name of the scope.

collectionName
required
string
Example: airline

The name of the collection.

Responses

Response samples

Content type
application/json
{
  • "httpStatusCode": 400,
  • "code": 6007,
  • "message": "The request was malformed or invalid.",
  • "hint": "The request was malformed or invalid."
}

organizations

Couchbase Capella uses an ordered hierarchy to help you keep all of your data organized and securely accessible. The entity at the top of the hierarchy is called an organization. Everything you do in Capella, whether it's creating a cluster or managing billing, happens within the scope of an organization.

Get Organization

Fetches the details of an organization by ID.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Creator
  • Organization Member

To learn more, see Organization Roles.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

Responses

Response samples

Content type
application/json
{
  • "id": "ffffffff-aaaa-1414-eeee-000000000000",
  • "name": "My-Organization",
  • "description": "The description of the organization.",
  • "preferences": {
    },
  • "audit": {
    }
}

List Organizations

Returns a list of all organizations the user has access to.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Creator
  • Organization Member

To learn more, see Organization Roles.

Authorizations:
token

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

certificates

Couchbase Capella supports the use of x.509 certificates, for clients and servers. This ensures that only approved users, applications, machines, and endpoints have access to system resources. Consequently, the mechanism can be used by Couchbase SDK clients to access Couchbase Services, and by source clusters that use XDCR to replicate data to target clusters. Clients can verify the identity of Couchbase Capella, thereby ensuring that they are not exchanging data with a rogue entity.

Get Certificate

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager
  • Project Viewer
  • Database Data Reader/Writer
  • Database Data Reader

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

Responses

Response samples

Content type
application/json
{
  • "certificate": "-----BEGIN CERTIFICATE-----\nMIIDFTCCAf2gAwIBAgI[...]CSYBWaK0ofivA==\n-----END CERTIFICATE-----\n"
}

backups & restore

Couchbase supports a robust scheduled backup and retention time policy as part of an overall disaster recovery plan for production data. Couchbase Capella supports scheduled and on-demand backups of bucket data. A backup can be restored to the same database where it was created or another database in the same organization. An on-demand backup of a bucket is always a Full backup. Capella schedules on-demand backup to start immediately.

Create Backup

Creates an on-demand backup for a bucket.

To learn more about backup and restore, see Backup and Restore Data.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

bucketId
required
string
Example: dGVzdA

The ID of the bucket. It is the URL-compatible base64 encoding of the bucket name.

Responses

Response samples

Content type
application/json
{
  • "httpStatusCode": 403,
  • "code": 1002,
  • "message": "Access Denied.",
  • "hint": "Your access to the requested resource is denied. Please make sure you have the necessary permissions to access the resource."
}

List Cluster Backups

Lists the latest backup for all buckets in a cluster.

Note: This endpoint doesn’t return queued backups and only returns ones that are actively being processed or are completed/failed.

To learn more about backup and restore, see Backup and Restore Data.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get Backup

Fetches the details of an existing backup.

To learn more about backup and restore, see Backup and Restore Data.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

backupId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the backup.

Responses

Response samples

Content type
application/json
{
  • "id": "ffffffff-aaaa-1414-eeee-000000000000",
  • "clusterID": "ffffffff-aaaa-1414-eeee-000000000000",
  • "tenantID": "ffffffff-aaaa-1414-eeee-000000000000",
  • "projectID": "ffffffff-aaaa-1414-eeee-000000000000",
  • "cycleID": "string",
  • "date": "2021-09-01T12:34:56Z",
  • "restoreBefore": "2021-09-02T12:34:56Z",
  • "status": "pending",
  • "method": "incremental",
  • "bucketName": "My-First-Bucket",
  • "bucketID": "dGVzdA",
  • "source": "scheduled",
  • "provider": "aws",
  • "stats": {
    },
  • "elapsedTimeInSeconds": 30,
  • "scheduleInfo": {
    }
}

Delete Backup Cycle

Deletes the backup records that belong to the same cycle from the DB by using the backup ID.

To learn more about backup and restore, see Backup and Restore Data.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

backupId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the backup.

Responses

Response samples

Content type
application/json
{
  • "httpStatusCode": 403,
  • "code": 1002,
  • "message": "Access Denied.",
  • "hint": "Your access to the requested resource is denied. Please make sure you have the necessary permissions to access the resource."
}

Restore Backup

Creates an on-demand restore job for a backup immediately.

To learn more about backup and restore, see Backup and Restore Data.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

backupId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the backup.

Request Body schema: application/json
targetClusterID
required
string <uuid>

The ID of the target cluster to restore to.

sourceClusterID
required
string <uuid>

The ID of the source cluster the restore is based on.

backupID
required
string <uuid>

The backup record ID that contains the backup to restore from.

services
required
Array of strings (Services)
Items Enum: "data" "query"
forceUpdates
boolean

Forces data in the Couchbase cluster to be overwritten even if the data in the cluster is newer.

autoRemoveCollections
boolean

Automatically delete scopes/collections which are known to be deleted in the backup.

filterKeys
string

Only restore data where the key matches a particular regular expression.

filterValues
string

Only restore data where the value matches a particular regular expression.

includeData
string

Restores only the data specified here.

excludeData
string

Skips restoring the data specified here.

mapData
string

Specified when you want to restore source data into a different location.

replaceTTL
string
Enum: "none" "all" "expired"

Sets a new expiration (time-to-live) value for the specified keys.

replaceTTLWith
string

Updates the expiration for the keys.

Responses

Request samples

Content type
application/json
{
  • "targetClusterID": "ffffffff-aaaa-1414-eeee-000000000000",
  • "sourceClusterID": "ffffffff-aaaa-1414-eeee-000000000000",
  • "backupID": "ffffffff-aaaa-1414-eeee-000000000000",
  • "services": [
    ],
  • "forceUpdates": true,
  • "autoRemoveCollections": true,
  • "filterKeys": "",
  • "filterValues": "",
  • "includeData": "bucket-1.scope1",
  • "excludeData": "bucket-1.scope1.coll1",
  • "mapData": "bucket1=new1",
  • "replaceTTL": "all",
  • "replaceTTLWith": "2021-09-01T12:34:56Z"
}

Response samples

Content type
application/json
{
  • "httpStatusCode": 403,
  • "code": 1002,
  • "message": "Access Denied.",
  • "hint": "Your access to the requested resource is denied. Please make sure you have the necessary permissions to access the resource."
}

backup schedule

Couchbase supports a robust scheduled backup and retention time policy as part of an overall disaster recovery plan for production data. Couchbase Capella supports scheduled and on-demand backups of bucket data. A backup can be restored to the same database where it was created or another database in the same organization. On setting up a backup schedule, the bucket automatically backs up the bucket based on the chosen schedule.

Create Backup Schedule

Creates a scheduled backup for a bucket.

To learn more about backup and restore, see Backup and Restore Data.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

bucketId
required
string
Example: dGVzdA

The ID of the bucket. It is the URL-compatible base64 encoding of the bucket name.

Request Body schema: application/json
type
string
Value: "weekly"
object

Schedule a full backup once a week with regular incrementals.

Responses

Request samples

Content type
application/json
{
  • "type": "weekly",
  • "weeklySchedule": {
    }
}

Response samples

Content type
application/json
{
  • "httpStatusCode": 400,
  • "code": 6007,
  • "message": "The request was malformed or invalid.",
  • "hint": "The request was malformed or invalid."
}

Get Backup Schedule

Fetched the backup schedule for a bucket in a cluster.

To learn more about backup and restore, see Backup and Restore Data.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

bucketId
required
string
Example: dGVzdA

The ID of the bucket. It is the URL-compatible base64 encoding of the bucket name.

Responses

Response samples

Content type
application/json
{
  • "type": "weekly",
  • "clusterID": "ffffffff-aaaa-1414-eeee-000000000000",
  • "bucketId": "dGVzdA",
  • "weeklySchedule": {
    }
}

Update Backup Schedule

Updates an existing backup schedule.

To learn more about backup and restore, see Backup and Restore Data.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

bucketId
required
string
Example: dGVzdA

The ID of the bucket. It is the URL-compatible base64 encoding of the bucket name.

Request Body schema: application/json
type
string
Value: "weekly"
object

Schedule a full backup once a week with regular incrementals.

Responses

Request samples

Content type
application/json
{
  • "type": "weekly",
  • "weeklySchedule": {
    }
}

Response samples

Content type
application/json
{
  • "httpStatusCode": 400,
  • "code": 6007,
  • "message": "The request was malformed or invalid.",
  • "hint": "The request was malformed or invalid."
}

Delete Backup Schedule

Deletes an existing backup schedule

To learn more about backup and restore, see Backup and Restore Data.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

bucketId
required
string
Example: dGVzdA

The ID of the bucket. It is the URL-compatible base64 encoding of the bucket name.

Responses

Response samples

Content type
application/json
{
  • "httpStatusCode": 400,
  • "code": 6007,
  • "message": "The request was malformed or invalid.",
  • "hint": "The request was malformed or invalid."
}

List Cycles

Lists the cycles for a bucket in a cluster.

To learn more about backup and restore, see Backup and Restore Data.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

bucketId
required
string
Example: dGVzdA

The ID of the bucket. It is the URL-compatible base64 encoding of the bucket name.

query Parameters
startDate
string <date>
Example: startDate=2023-07-19

Filters bucket backups beginning from the start date. Specify the start date to retrieve relevant bucket backups from start date.

endDate
string <date>
Example: endDate=2023-07-21

Filters bucket backups till the end date. Specify the end date to retrieve relevant bucket backups till end date.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

List Backups

Lists the backups for a cycle in a bucket.

To learn more about backup and restore, see Backup and Restore Data.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

bucketId
required
string
Example: dGVzdA

The ID of the bucket. It is the URL-compatible base64 encoding of the bucket name.

cycleId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cycle.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

appServices

App Services synchronizes data between the Couchbase Capella database and your apps running on mobile applications. App Services is a fully managed application backend designed to provide data synchronization for mobile/IoT applications and the Capella Cloud Service.

Create App Service

Creates a new App Service.

In order to access this endpoint, the provided API key must have at least one of the roles referenced below:

  • Organization Owner
  • Project Owner
  • Project Manager

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

Request Body schema: application/json
name
required
string <= 256 characters

Name of the cluster (up to 256 characters).

description
string

A short description of the App Service.

nodes
integer

Number of nodes configured for the App Service. Number of nodes configured for the App Service. The number of nodes can range from 2 to 12.

object (AppServiceCompute)

The CPU and RAM configuration of the App Service. The supported combinations are:

CPU (cores) RAM (GB)
2 4
4 8
8 16
16 32
36 72
version
string

The version of the App Service server. If left empty, it will be defaulted to the latest available version.

Responses

Request samples

Content type
application/json
{
  • "name": "MyAppSyncService",
  • "description": "My app sync service.",
  • "nodes": 2,
  • "compute": {
    },
  • "version": "3.0"
}

Response samples

Content type
application/json
{
  • "id": "ffffffff-aaaa-1414-eeee-000000000000"
}

List AppServices

Lists all the clusters under the organization.

In order to access this endpoint, the provided API key must have at least one of the roles referenced below:

  • Organization Owner
  • Project Owner
  • Project Manager
  • Project Viewer
  • Database Data Reader/Writer
  • Database Data Reader

Returned set of clusters is reduced to what the caller has access to view. To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

query Parameters
page
integer

Sets the page you would like to view.

perPage
integer

Sets the number of results you would like to have on each page.

sortBy
Array of strings
Example: sortBy=name

Sets the order of how you would like to sort the results and the key you would like to order by. Valid fields to sort the results are: name, id, description.

sortDirection
string
Enum: "asc" "desc"
Example: sortDirection=asc

The order in which the items will be sorted.

projectId
string <uuid>
Example: projectId=ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

Responses

Response samples

Content type
application/json
{}

Get App Service

Fetches the details of the given App Service.

In order to access this endpoint, the provided API key must have at least one of the roles referenced below:

  • Organization Owner
  • Project Owner
  • Project Manager
  • Project Viewer
  • Database Data Reader/Writer
  • Database Data Reader

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

appServiceId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the appService.

Responses

Response samples

Content type
application/json
{
  • "id": "ffffffff-aaaa-1414-eeee-000000000000",
  • "name": "My App Service",
  • "description": "Description of the App Service.",
  • "cloudProvider": "aws",
  • "nodes": 2,
  • "compute": {
    },
  • "clusterId": "ffffffff-aaaa-1414-eeee-000000000000",
  • "currentState": "deploying",
  • "version": "3.141.5",
  • "audit": {
    }
}

Update App Service

Updates an existing App Service.

In order to access this endpoint, the provided API key must have at least one of the roles referenced below:

  • Organization Owner
  • Project Owner
  • Project Manager

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

appServiceId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the appService.

header Parameters
If-Match
string
Example: 12

A precondition header that specifies the entity tag of a resource.

Request Body schema: application/json
nodes
required
integer

Number of nodes configured for the App Service. The number of nodes can range from 2 to 12.

required
object (AppServiceCompute)

The CPU and RAM configuration of the App Service. The supported combinations are:

CPU (cores) RAM (GB)
2 4
4 8
8 16
16 32
36 72

Responses

Request samples

Content type
application/json
{
  • "nodes": 2,
  • "compute": {
    }
}

Response samples

Content type
application/json
{
  • "httpStatusCode": 403,
  • "code": 1002,
  • "message": "Access Denied.",
  • "hint": "Your access to the requested resource is denied. Please make sure you have the necessary permissions to access the resource."
}

Delete App Service

Deletes an existing App Service.

In order to access this endpoint, the provided API key must have at least one of the roles referenced below:

  • Organization Owner
  • Project Owner
  • Project Manager

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

appServiceId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the appService.

Responses

Response samples

Content type
application/json
{
  • "httpStatusCode": 403,
  • "code": 1002,
  • "message": "Access Denied.",
  • "hint": "Your access to the requested resource is denied. Please make sure you have the necessary permissions to access the resource."
}

Turn On App Service

Turn app service on.

In order to access this endpoint, the provided API key must have at least one of the roles referenced below:

  • Organization Owner
  • Project Owner
  • Project Manager

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

appServiceId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the appService.

Responses

Response samples

Content type
application/json
{
  • "httpStatusCode": 403,
  • "code": 1002,
  • "message": "Access Denied.",
  • "hint": "Your access to the requested resource is denied. Please make sure you have the necessary permissions to access the resource."
}

Turn Off App Service

Turn app service off.

Turn off an App Service to temporarily deactivate it and reduce its consumption of compute resources. The App Service itself and its related infrastructure will be removed once turned off.

In order to access this endpoint, the provided API key must have at least one of the roles referenced below:

  • Organization Owner
  • Project Owner
  • Project Manager

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

appServiceId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the appService.

Responses

Response samples

Content type
application/json
{
  • "httpStatusCode": 403,
  • "code": 1002,
  • "message": "Access Denied.",
  • "hint": "Your access to the requested resource is denied. Please make sure you have the necessary permissions to access the resource."
}

sampleBucket

The sampleBucket endpoint lets users easily create a bucket filled with sample data. This is a quick way for users to try out features and learn how things work with ready-to-use data.

Load Sample Data

Loads predefined sample data into a cluster by selecting from three available options:

  • travel-sample
  • gamesim-sample
  • beer-sample

Upon a successful request, a new bucket is created within the cluster, and populated with the chosen sample data.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

Request Body schema: application/json
name
required
string
Enum: "travel-sample" "gamesim-sample" "beer-sample"

The name of the sample dataset to be loaded. The name has to be one of the following sample datasets.

  • travel-sample
  • gamesim-sample
  • beer-sample

Responses

Request samples

Content type
application/json
{
  • "name": "travel-sample"
}

Response samples

Content type
application/json
{
  • "bucketId": "dGVzdA",
  • "name": "travel-sample"
}

List Sample Data Import Buckets

Lists all the sample buckets under the organization.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager
  • Project Viewer
  • Database Data Reader/Writer
  • Database Data Reader

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get Sample Import Bucket

Fetches the configuration of the given bucket.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager
  • Project Viewer
  • Database Data Reader/Writer
  • Database Data Reader

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

bucketId
required
string
Example: dGVzdA

The ID of the bucket. It is the URL-compatible base64 encoding of the bucket name.

Responses

Response samples

Content type
application/json
{
  • "id": "dGVzdA",
  • "name": "My-First-Bucket",
  • "type": "string",
  • "storageBackend": "couchstore",
  • "memoryAllocationInMb": 100,
  • "bucketConflictResolution": "string",
  • "durabilityLevel": "string",
  • "replicas": 0,
  • "flush": false,
  • "timeToLiveInSeconds": 100,
  • "evictionPolicy": "fullEviction",
  • "stats": {
    },
  • "priority": 0
}

Delete Sample Import Bucket

Deletes an existing bucket which was loaded with sample data.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

bucketId
required
string
Example: dGVzdA

The ID of the bucket. It is the URL-compatible base64 encoding of the bucket name.

Responses

Response samples

Content type
application/json
{
  • "httpStatusCode": 403,
  • "code": 1002,
  • "message": "Access Denied.",
  • "hint": "Your access to the requested resource is denied. Please make sure you have the necessary permissions to access the resource."
}

cmek

The CMEK (Customer Managed Encryption Keys) endpoints facilitate the management of encryption keys used by clusters for data encryption. They allow organizations to register, list, retrieve, rotate, and delete the metadata associated with their own encryption keys within Capella. This suite of endpoints ensures that organizations have full control over the lifecycle of their keys, enhancing security and compliance by allowing encryption keys that are managed in external key management services like AWS KMS or GCP KMS to be used within the organization's clusters.

Get Cloud Accounts

Fetches the cloud account ID associated with the organization. Use this account ID when adding CMEK to other AWS databases in your organization.

To learn more, see CMEK at Rest.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Creator
  • Organization Member

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

Responses

Response samples

Content type
application/json
{
  • "gcp-capella-project": "MyApp-Prod-Project",
  • "aws-capella-account": "MyApp-Prod-Project",
  • "azure-capella-subscription": "MyApp-Prod-Project"
}

Create Key Metadata

Initializes the metadata record for a customer-managed encryption key stored in AWS or GCP, linking it to the organization.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

Request Body schema: application/json
name
required
string <= 128 characters

Name of the key (up to 256 characters).

description
string <= 512 characters

Description of the key (up to 1024 characters).

required
AWSConfig (object) or GCPConfig (object)

Responses

Request samples

Content type
application/json
{
  • "name": "Test Key",
  • "description": "Description of the Key",
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "id": "ffffffff-aaaa-1414-eeee-000000000000"
}

List Key Metadata

Retrieves detailed metadata for all customer-managed encryption keys associated with the organization.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Organization Member

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

query Parameters
page
integer

Sets the page you would like to view.

perPage
integer

Sets the number of results you would like to have on each page.

sortBy
Array of strings
Example: sortBy=name

Sets the order of how you would like to sort the results and the key you would like to order by.

sortDirection
string
Enum: "asc" "desc"
Example: sortDirection=asc

The order in which the items will be sorted.

Responses

Response samples

Content type
application/json
{}

Get Key Metadata

Retrieves the full metadata details for a specific customer-managed encryption key within the organization.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Organization Member

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

cmekId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the KMS Key metadata.

Responses

Response samples

Content type
application/json
{
  • "id": "ffffffff-aaaa-1414-eeee-000000000000",
  • "name": "Test Key",
  • "description": "Description of the cluster",
  • "config": {
    },
  • "audit": {
    }
}

Rotate Key

Initiates the process to rotate a customer-managed encryption key and update its associated metadata within the system.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

cmekId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the KMS Key metadata.

Request Body schema: application/json
required
AWSConfig (object) or GCPConfig (object)

Responses

Request samples

Content type
application/json
{
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "httpStatusCode": 403,
  • "code": 1002,
  • "message": "Access Denied.",
  • "hint": "Your access to the requested resource is denied. Please make sure you have the necessary permissions to access the resource."
}

Delete Key Metadata

Permanently removes the specified customer-managed encryption key's metadata from the organization's account.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

cmekId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the KMS Key metadata.

Responses

Response samples

Content type
application/json
{
  • "httpStatusCode": 403,
  • "code": 1002,
  • "message": "Access Denied.",
  • "hint": "Your access to the requested resource is denied. Please make sure you have the necessary permissions to access the resource."
}

Associate Key with Cluster

Redeploys the cluster and encrypts the disks with the newly associated customer-managed encryption key. Throws an error before redeploying the cluster if the customer-managed encryption key is inaccessible.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

cmekId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the KMS Key metadata.

Responses

Response samples

Content type
application/json
{
  • "httpStatusCode": 403,
  • "code": 1002,
  • "message": "Access Denied.",
  • "hint": "Your access to the requested resource is denied. Please make sure you have the necessary permissions to access the resource."
}

Unassociate Key from Cluster

Removes the customer-managed encryption key associated with the cluster, which redeploys the cluster and removes any encryption on the disks. This does not delete the customer-managed encryption key itself since the same key could be used across clusters.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

cmekId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the KMS Key metadata.

Responses

Response samples

Content type
application/json
{
  • "httpStatusCode": 403,
  • "code": 1002,
  • "message": "Access Denied.",
  • "hint": "Your access to the requested resource is denied. Please make sure you have the necessary permissions to access the resource."
}

alert integration

Couchbase Capella supports sending Capella alert notifications to the most common service like ServiceNow.

Create Alert Integration

Creates a new alert integration for a project.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

Request Body schema: application/json
kind
required
string
Value: "webhook"

Type of alert integration, currently supports only 'webhook'.

name
required
string <= 1024 characters

Name of the alert integration (up to 1024 characters).

required
object (RequestConfig)

Responses

Request samples

Content type
application/json
{
  • "kind": "webhook",
  • "name": "test alert 1",
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "id": "ffffffff-aaaa-1414-eeee-000000000000"
}

List Alert Integrations

Lists all the alert integrations under the project.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Organization Member
  • Project Owner
  • Project Manager
  • Project Viewer

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

query Parameters
page
integer

Sets the page you would like to view.

perPage
integer

Sets the number of results you would like to have on each page.

sortBy
Array of strings
Example: sortBy=name

Sets the order of how you would like to sort the results and the key you would like to order by. Valid fields to sort the results are: id, name.

sortDirection
string
Enum: "asc" "desc"
Example: sortDirection=asc

The order in which the items will be sorted.

Responses

Response samples

Content type
application/json
{}

Get Alert Integration

Fetches the details of the given alert integration.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Organization Member
  • Project Owner
  • Project Manager
  • Project Viewer

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

alertIntegrationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the alert integration.

Responses

Response samples

Content type
application/json
{
  • "id": "ffffffff-aaaa-1414-eeee-000000000000",
  • "name": "test alert 1",
  • "tenantId": "ffffffff-aaaa-1414-eeee-000000000000",
  • "projectId": "ffffffff-aaaa-1414-eeee-000000000000",
  • "kind": "webhook",
  • "configKey": "ffffffff-aaaa-1414-eeee-000000000000-alert-integration",
  • "status": "healthy",
  • "enabled": false,
  • "config": {
    },
  • "audit": {
    }
}

Update Alert Integration

Update the details of the given alert integration.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

alertIntegrationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the alert integration.

Request Body schema: application/json
name
string <= 1024 characters

Name of the alert integration (up to 1024 characters).

required
object (RequestConfig)

Responses

Request samples

Content type
application/json
{
  • "name": "test alert 1",
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "httpStatusCode": 400,
  • "code": 6007,
  • "message": "The request was malformed or invalid.",
  • "hint": "The request was malformed or invalid."
}

Delete Alert Integration

Deletes an existing alert integration.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

alertIntegrationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the alert integration.

Responses

Response samples

Content type
application/json
{
  • "httpStatusCode": 403,
  • "code": 1002,
  • "message": "Access Denied.",
  • "hint": "Your access to the requested resource is denied. Please make sure you have the necessary permissions to access the resource."
}

Test Alert Integration

Tests a new alert integration for a project.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

Request Body schema: application/json
kind
required
string
Value: "webhook"

Type of alert integration, currently supports only 'webhook'.

required
object (RequestConfig)

Responses

Request samples

Content type
application/json
{
  • "kind": "webhook",
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "httpStatusCode": 403,
  • "code": 1002,
  • "message": "Access Denied.",
  • "hint": "Your access to the requested resource is denied. Please make sure you have the necessary permissions to access the resource."
}

on/off schedule

Couchbase supports the feature where you can schedule when your provisioned database is on and off to save costs. Turning off your database turns off the compute for your cluster but the storage remains. All of your data, schema (buckets, scopes, and collections), and indexes remain, as well as your cluster configuration, including users and allow lists. When you turn your provisioned database off, you will be charged the OFF amount for the database. You can turn cluster and any linked app services on/off on demand using cluster API.

Create Cluster On/Off schedule

This provides the means to add a new cluster on/off schedule.

In order to access this endpoint, the provided API key must have at least one of the roles referenced below:

  • Organization Owner
  • Project Owner

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

Request Body schema: application/json
timezone
required
string
Enum: "Pacific/Midway" "US/Hawaii" "US/Alaska" "US/Pacific" "US/Mountain" "US/Central" "US/Eastern" "America/Puerto_Rico" "Canada/Newfoundland" "America/Argentina/Buenos_Aires" "Atlantic/Cape_Verde" "Europe/London" "Europe/Amsterdam" "Europe/Athens" "Africa/Nairobi" "Asia/Tehran" "Indian/Mauritius" "Asia/Karachi" "Asia/Calcutta" "Asia/Dhaka" "Asia/Bangkok" "Asia/Hong_Kong" "Asia/Tokyo" "Australia/North" "Australia/Sydney" "Pacific/Ponape" "Antarctica/South_Pole"

Timezone for the schedule

required
Array of objects (Days)

Responses

Request samples

Content type
application/json
Example
{
  • "timezone": "US/Pacific",
  • "days": [
    ]
}

Response samples

Content type
application/json
{
  • "httpStatusCode": 403,
  • "code": 1002,
  • "message": "Access Denied.",
  • "hint": "Your access to the requested resource is denied. Please make sure you have the necessary permissions to access the resource."
}

Get Cluster On/Off schedule

Fetches the details of the cluster on/off schedule for the given cluster.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

Responses

Response samples

Content type
application/json
{
  • "timezone": "US/Pacific",
  • "days": [
    ]
}

Update Cluster On/Off schedule

This provides the means to update an existing cluster on/off schedule.

In order to access this endpoint, the provided API key must have at least one of the roles referenced below:

  • Organization Owner
  • Project Owner

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

Request Body schema: application/json
timezone
required
string
Enum: "Pacific/Midway" "US/Hawaii" "US/Alaska" "US/Pacific" "US/Mountain" "US/Central" "US/Eastern" "America/Puerto_Rico" "Canada/Newfoundland" "America/Argentina/Buenos_Aires" "Atlantic/Cape_Verde" "Europe/London" "Europe/Amsterdam" "Europe/Athens" "Africa/Nairobi" "Asia/Tehran" "Indian/Mauritius" "Asia/Karachi" "Asia/Calcutta" "Asia/Dhaka" "Asia/Bangkok" "Asia/Hong_Kong" "Asia/Tokyo" "Australia/North" "Australia/Sydney" "Pacific/Ponape" "Antarctica/South_Pole"

Timezone for the schedule

required
Array of objects (Days)

Responses

Request samples

Content type
application/json
{
  • "timezone": "US/Pacific",
  • "days": [
    ]
}

Response samples

Content type
application/json
{
  • "httpStatusCode": 403,
  • "code": 1002,
  • "message": "Access Denied.",
  • "hint": "Your access to the requested resource is denied. Please make sure you have the necessary permissions to access the resource."
}

Delete Cluster On/Off schedule

Deletes the cluster on/off schedule for the given cluster.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

Responses

Response samples

Content type
application/json
{
  • "httpStatusCode": 403,
  • "code": 1002,
  • "message": "Access Denied.",
  • "hint": "Your access to the requested resource is denied. Please make sure you have the necessary permissions to access the resource."
}

Audit Logs

Users can configure audit log support on Capella database and can export audit logs from cloud blob storage to an AWS S3 bucket. Users can retrieve audit logs from a pre-signed download URL. Logs are retained for 30 days.

Update Cluster Audit Log Configuration

Updates the audit log configuration for the cluster.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

Request Body schema: application/json
auditEnabled
required
boolean

Determines whether audit logging is enabled or not on the cluster.

required
Array of objects (AuditSettingsDisabledUsers)

List of users whose filterable events will not be logged.

enabledEventIDs
required
Array of integers <int32> [ items <int32 > ]

List of enabled filterable audit events for the cluster.

Responses

Request samples

Content type
application/json
{
  • "auditEnabled": true,
  • "disabledUsers": [
    ],
  • "enabledEventIDs": [
    ]
}

Response samples

Content type
application/json
{
  • "httpStatusCode": 403,
  • "code": 1002,
  • "message": "Access Denied.",
  • "hint": "Your access to the requested resource is denied. Please make sure you have the necessary permissions to access the resource."
}

Get Cluster Audit Log Configuration

Fetches information on whether audit logging is enabled, and which event IDs are enabled.

To learn more about cluster audit logs, please refer to audit management.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager
  • Project Viewer
  • Database Data Reader/Writer
  • Database Data Reader

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

Responses

Response samples

Content type
application/json
{
  • "auditEnabled": true,
  • "disabledUsers": [
    ],
  • "enabledEventIDs": [
    ]
}

List Filterable Audit Log Events

Retrieves a list of audit event IDs. The list of filterable event IDs can be specified while configuring audit log for cluster.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager
  • Project Viewer
  • Database Data Reader/Writer
  • Database Data Reader

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

Responses

Response samples

Content type
application/json
{
  • "events": [
    ]
}

Create Cluster Audit Log Export job

Creates a new audit log export job.

Audit Logs for the last 30 days can be requested, otherwise they are purged. A pre-signed URL to a s3 bucket location is returned, which is used to download these audit logs.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

Request Body schema: application/json
start
required
string <date-time>

Specifies the audit log's start date and time.

end
required
string <date-time>

Specifies the audit log's end date and time.

Responses

Request samples

Content type
application/json
{
  • "start": "2022-09-04T00:56:07.000Z",
  • "end": "2022-09-05T04:56:07.000Z"
}

Response samples

Content type
application/json
{
  • "exportId": "ffffffff-aaaa-1414-eeee-000000000000"
}

List Cluster Audit Log Export Jobs

Lists all the audit log export jobs and shows the status for each job.

It will show the pre-signed URL if the export was successful, a failure error if it was unsuccessful or a message saying no audit logs available if there were no audit logs found.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager
  • Project Viewer
  • Database Data Reader/Writer
  • Database Data Reader

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

query Parameters
page
integer

Sets the page you would like to view.

perPage
integer

Sets the number of results you would like to have on each page.

Responses

Response samples

Content type
application/json
{}

Get Cluster Audit Log Export

Fetches the status of a single audit log export job.

It will show the pre-signed URL if the export was successful, a failure error if it was unsuccessful or a message saying no audit logs available if there were no audit logs found during the given timeframe.

In order to access this endpoint, the provided API key must have at least one of the following roles:

  • Organization Owner
  • Project Owner
  • Project Manager
  • Project Viewer
  • Database Data Reader/Writer
  • Database Data Reader

To learn more, see Organization, Project, and Database Access Overview.

Authorizations:
token
path Parameters
organizationId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the organization.

projectId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the project.

clusterId
required
string <uuid>
Example: ffffffff-aaaa-1414-eeee-000000000000

The GUID4 ID of the cluster.

auditLogExportId
required
string
Example: ffffffff-aaaa-1414-eeee-000000000000

The export ID of the audit log export job.

Responses

Response samples

Content type
application/json
Example
{
  • "createdAt": "2023-05-16T04:00:08.870Z",
  • "auditLogExportId": "40b9318a-cc93-458d-bc3e-7d4ffa778386",
  • "start": "2023-05-15T04:56:07.000Z",
  • "end": "2023-05-16T04:56:07.000Z",
  • "status": "In Progress"
}