Couchbase Clusters API

openapi: 3.2.0
info:
  title: Couchbase Capella Management Clusters API
  description: The Couchbase Capella Management API is a REST API for provisioning, deploying, and configuring Couchbase Capella database-as-a-service deployments across AWS, Azure, and Google Cloud. It enables programmatic management of clusters, buckets, users, and organizations using API key authentication. The API supports automation of cloud database operations including scaling, configuration changes, and access management, with requests limited to 100 per minute per API key.
  version: '4.0'
  contact:
    name: Couchbase Support
    url: https://support.couchbase.com
  termsOfService: https://www.couchbase.com/terms-of-use
servers:
- url: https://cloudapi.cloud.couchbase.com
  description: Couchbase Capella Cloud API
security:
- bearerAuth: []
tags:
- name: Clusters
  description: Endpoints for provisioning, managing, and scaling Capella database clusters.
paths:
  /v4/organizations/{organizationId}/projects/{projectId}/clusters:
    get:
      operationId: listClusters
      summary: List clusters
      description: Returns the list of database clusters within the specified project.
      tags:
      - Clusters
      parameters:
      - $ref: '#/components/parameters/organizationId'
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/perPage'
      responses:
        '200':
          description: Successful retrieval of clusters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
        '401':
          description: Unauthorized access
        '429':
          description: Rate limit exceeded
    post:
      operationId: createCluster
      summary: Create a cluster
      description: Provisions a new Couchbase Capella database cluster in the specified project. You can configure the cloud provider, region, instance type, storage, and services.
      tags:
      - Clusters
      parameters:
      - $ref: '#/components/parameters/organizationId'
      - $ref: '#/components/parameters/projectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClusterCreateRequest'
      responses:
        '202':
          description: Cluster creation initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cluster'
        '400':
          description: Invalid cluster configuration
        '401':
          description: Unauthorized access
        '429':
          description: Rate limit exceeded
  /v4/organizations/{organizationId}/projects/{projectId}/clusters/{clusterId}:
    get:
      operationId: getCluster
      summary: Get cluster details
      description: Returns detailed information about a specific cluster including its configuration, status, and connection string.
      tags:
      - Clusters
      parameters:
      - $ref: '#/components/parameters/organizationId'
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/clusterId'
      responses:
        '200':
          description: Successful retrieval of cluster details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cluster'
        '401':
          description: Unauthorized access
        '404':
          description: Cluster not found
        '429':
          description: Rate limit exceeded
    put:
      operationId: updateCluster
      summary: Update a cluster
      description: Updates the configuration of an existing cluster, such as scaling the number of nodes or changing the support plan.
      tags:
      - Clusters
      parameters:
      - $ref: '#/components/parameters/organizationId'
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/clusterId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClusterUpdateRequest'
      responses:
        '202':
          description: Cluster update initiated
        '400':
          description: Invalid cluster configuration
        '401':
          description: Unauthorized access
        '404':
          description: Cluster not found
        '429':
          description: Rate limit exceeded
    delete:
      operationId: deleteCluster
      summary: Delete a cluster
      description: Deletes the specified cluster and all its data. This action is irreversible.
      tags:
      - Clusters
      parameters:
      - $ref: '#/components/parameters/organizationId'
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/clusterId'
      responses:
        '202':
          description: Cluster deletion initiated
        '401':
          description: Unauthorized access
        '404':
          description: Cluster not found
        '429':
          description: Rate limit exceeded
components:
  schemas:
    ServiceGroup:
      type: object
      description: Service group within a cluster
      properties:
        node:
          type: object
          description: Node configuration
          properties:
            compute:
              type: object
              description: Compute instance configuration
              properties:
                cpu:
                  type: integer
                  description: Number of CPU cores
                ram:
                  type: integer
                  description: RAM in gigabytes
            disk:
              type: object
              description: Disk storage configuration
              properties:
                type:
                  type: string
                  description: Disk type
                  enum:
                  - gp3
                  - io2
                  - P6
                  - P10
                  - P15
                  - P20
                  - P30
                  - P40
                  - P50
                  - pd-ssd
                storage:
                  type: integer
                  description: Storage size in gigabytes
                iops:
                  type: integer
                  description: IOPS for the disk
        numOfNodes:
          type: integer
          description: Number of nodes in the service group
          minimum: 3
        services:
          type: array
          description: Services enabled on the nodes
          items:
            type: string
            enum:
            - data
            - index
            - query
            - search
            - analytics
            - eventing
    AuditInfo:
      type: object
      description: Audit timestamps
      properties:
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp
        modifiedAt:
          type: string
          format: date-time
          description: Last modification timestamp
        createdBy:
          type: string
          description: User who created the resource
        modifiedBy:
          type: string
          description: User who last modified the resource
        version:
          type: integer
          description: Resource version number
    Cluster:
      type: object
      description: Capella database cluster
      properties:
        id:
          type: string
          format: uuid
          description: Cluster UUID
        name:
          type: string
          description: Cluster name
        description:
          type: string
          description: Cluster description
        cloudProvider:
          type: object
          description: Cloud provider configuration
          properties:
            type:
              type: string
              description: Cloud provider type
              enum:
              - aws
              - azure
              - gcp
            region:
              type: string
              description: Cloud region
            cidr:
              type: string
              description: CIDR block for the cluster
        couchbaseServer:
          type: object
          description: Couchbase Server configuration
          properties:
            version:
              type: string
              description: Couchbase Server version
        serviceGroups:
          type: array
          description: Service group configurations
          items:
            $ref: '#/components/schemas/ServiceGroup'
        availability:
          type: object
          description: Availability configuration
          properties:
            type:
              type: string
              description: Availability type
              enum:
              - single
              - multi
        support:
          type: object
          description: Support plan
          properties:
            plan:
              type: string
              description: Support plan level
              enum:
              - basic
              - developer pro
              - enterprise
            timezone:
              type: string
              description: Support timezone
        currentState:
          type: string
          description: Current state of the cluster
          enum:
          - draft
          - deploying
          - healthy
          - degraded
          - destroying
          - peering
          - scaling
          - upgrading
          - rebalancing
          - turnedOff
        connectionString:
          type: string
          description: Connection string for the cluster
        audit:
          $ref: '#/components/schemas/AuditInfo'
    ClusterCreateRequest:
      type: object
      description: Request to create a new cluster
      required:
      - name
      - cloudProvider
      - serviceGroups
      - availability
      - support
      properties:
        name:
          type: string
          description: Cluster name
          maxLength: 256
        description:
          type: string
          description: Cluster description
        cloudProvider:
          type: object
          required:
          - type
          - region
          - cidr
          properties:
            type:
              type: string
              enum:
              - aws
              - azure
              - gcp
            region:
              type: string
              description: Cloud region identifier
            cidr:
              type: string
              description: CIDR block for the cluster
        couchbaseServer:
          type: object
          properties:
            version:
              type: string
              description: Desired Couchbase Server version
        serviceGroups:
          type: array
          items:
            $ref: '#/components/schemas/ServiceGroup'
        availability:
          type: object
          required:
          - type
          properties:
            type:
              type: string
              enum:
              - single
              - multi
        support:
          type: object
          required:
          - plan
          - timezone
          properties:
            plan:
              type: string
              enum:
              - basic
              - developer pro
              - enterprise
            timezone:
              type: string
    PaginatedResponse:
      type: object
      description: Paginated response wrapper
      properties:
        cursor:
          type: object
          description: Pagination cursor information
          properties:
            pages:
              type: object
              properties:
                page:
                  type: integer
                  description: Current page number
                next:
                  type: integer
                  description: Next page number
                previous:
                  type: integer
                  description: Previous page number
                last:
                  type: integer
                  description: Last page number
                perPage:
                  type: integer
                  description: Items per page
                totalItems:
                  type: integer
                  description: Total number of items
        data:
          type: array
          description: List of items
          items: {}
    ClusterUpdateRequest:
      type: object
      description: Request to update an existing cluster
      properties:
        name:
          type: string
          description: Cluster name
        description:
          type: string
          description: Cluster description
        serviceGroups:
          type: array
          items:
            $ref: '#/components/schemas/ServiceGroup'
        support:
          type: object
          properties:
            plan:
              type: string
              enum:
              - basic
              - developer pro
              - enterprise
            timezone:
              type: string
  parameters:
    page:
      name: page
      in: query
      required: false
      description: Page number for pagination
      schema:
        type: integer
        minimum: 1
        default: 1
    clusterId:
      name: clusterId
      in: path
      required: true
      description: The UUID of the cluster
      schema:
        type: string
        format: uuid
    organizationId:
      name: organizationId
      in: path
      required: true
      description: The UUID of the organization
      schema:
        type: string
        format: uuid
    perPage:
      name: perPage
      in: query
      required: false
      description: Number of items per page
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
    projectId:
      name: projectId
      in: path
      required: true
      description: The UUID of the project
      schema:
        type: string
        format: uuid
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication using a Capella API key secret.
externalDocs:
  description: Couchbase Capella Management API Documentation
  url: https://docs.couchbase.com/cloud/management-api-reference/index.html