Couchbase Capella Management API

openapi: 3.1.0
info:
  title: Couchbase Capella Management 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
externalDocs:
  description: Couchbase Capella Management API Documentation
  url: https://docs.couchbase.com/cloud/management-api-reference/index.html
servers:
  - url: https://cloudapi.cloud.couchbase.com
    description: Couchbase Capella Cloud API
tags:
  - name: Allowed CIDRs
    description: >-
      Endpoints for managing allowed IP addresses and CIDR ranges for
      cluster access.
  - name: API Keys
    description: >-
      Endpoints for managing API keys used to authenticate with the
      Management API.
  - name: Buckets
    description: >-
      Endpoints for managing buckets within Capella clusters.
  - name: Clusters
    description: >-
      Endpoints for provisioning, managing, and scaling Capella database
      clusters.
  - name: Database Credentials
    description: >-
      Endpoints for managing database access credentials for clusters.
  - name: Organizations
    description: >-
      Endpoints for managing Capella organizations.
  - name: Projects
    description: >-
      Endpoints for creating, listing, updating, and deleting projects within
      an organization.
  - name: Scopes and Collections
    description: >-
      Endpoints for managing scopes and collections within Capella buckets.
  - name: Users
    description: >-
      Endpoints for managing users within a Capella organization.
security:
  - bearerAuth: []
paths:
  /v4/organizations:
    get:
      operationId: listOrganizations
      summary: List organizations
      description: >-
        Returns the list of organizations the authenticated API key has
        access to.
      tags:
        - Organizations
      responses:
        '200':
          description: Successful retrieval of organizations
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Organization'
        '401':
          description: Unauthorized access
        '429':
          description: Rate limit exceeded
  /v4/organizations/{organizationId}:
    get:
      operationId: getOrganization
      summary: Get organization details
      description: >-
        Returns detailed information about a specific organization.
      tags:
        - Organizations
      parameters:
        - $ref: '#/components/parameters/organizationId'
      responses:
        '200':
          description: Successful retrieval of organization details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
        '401':
          description: Unauthorized access
        '404':
          description: Organization not found
        '429':
          description: Rate limit exceeded
  /v4/organizations/{organizationId}/projects:
    get:
      operationId: listProjects
      summary: List projects
      description: >-
        Returns the list of projects within the specified organization.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/organizationId'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/perPage'
      responses:
        '200':
          description: Successful retrieval of projects
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
        '401':
          description: Unauthorized access
        '429':
          description: Rate limit exceeded
    post:
      operationId: createProject
      summary: Create a project
      description: >-
        Creates a new project within the specified organization.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/organizationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectCreateRequest'
      responses:
        '201':
          description: Project created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: Invalid project configuration
        '401':
          description: Unauthorized access
        '429':
          description: Rate limit exceeded
  /v4/organizations/{organizationId}/projects/{projectId}:
    get:
      operationId: getProject
      summary: Get project details
      description: >-
        Returns detailed information about a specific project.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/organizationId'
        - $ref: '#/components/parameters/projectId'
      responses:
        '200':
          description: Successful retrieval of project details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          description: Unauthorized access
        '404':
          description: Project not found
        '429':
          description: Rate limit exceeded
    put:
      operationId: updateProject
      summary: Update a project
      description: >-
        Updates the configuration of an existing project.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/organizationId'
        - $ref: '#/components/parameters/projectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectCreateRequest'
      responses:
        '204':
          description: Project updated successfully
        '400':
          description: Invalid project configuration
        '401':
          description: Unauthorized access
        '404':
          description: Project not found
        '429':
          description: Rate limit exceeded
    delete:
      operationId: deleteProject
      summary: Delete a project
      description: >-
        Deletes the specified project. All resources within the project must
        be deleted first.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/organizationId'
        - $ref: '#/components/parameters/projectId'
      responses:
        '204':
          description: Project deleted successfully
        '401':
          description: Unauthorized access
        '404':
          description: Project not found
        '422':
          description: Project contains active resources
        '429':
          description: Rate limit exceeded
  /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
  /v4/organizations/{organizationId}/projects/{projectId}/clusters/{clusterId}/buckets:
    get:
      operationId: listCapellaBuckets
      summary: List buckets in a cluster
      description: >-
        Returns the list of buckets within the specified Capella cluster.
      tags:
        - Buckets
      parameters:
        - $ref: '#/components/parameters/organizationId'
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/clusterId'
      responses:
        '200':
          description: Successful retrieval of buckets
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CapellaBucket'
        '401':
          description: Unauthorized access
        '404':
          description: Cluster not found
        '429':
          description: Rate limit exceeded
    post:
      operationId: createCapellaBucket
      summary: Create a bucket
      description: >-
        Creates a new bucket within the specified Capella cluster.
      tags:
        - Buckets
      parameters:
        - $ref: '#/components/parameters/organizationId'
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/clusterId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CapellaBucketCreateRequest'
      responses:
        '201':
          description: Bucket created successfully
        '400':
          description: Invalid bucket configuration
        '401':
          description: Unauthorized access
        '404':
          description: Cluster not found
        '429':
          description: Rate limit exceeded
  /v4/organizations/{organizationId}/projects/{projectId}/clusters/{clusterId}/buckets/{bucketId}:
    get:
      operationId: getCapellaBucket
      summary: Get bucket details
      description: >-
        Returns detailed information about a specific bucket in a Capella
        cluster.
      tags:
        - Buckets
      parameters:
        - $ref: '#/components/parameters/organizationId'
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/clusterId'
        - $ref: '#/components/parameters/bucketId'
      responses:
        '200':
          description: Successful retrieval of bucket details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CapellaBucket'
        '401':
          description: Unauthorized access
        '404':
          description: Bucket not found
        '429':
          description: Rate limit exceeded
    put:
      operationId: updateCapellaBucket
      summary: Update a bucket
      description: >-
        Updates the configuration of an existing bucket in a Capella cluster.
      tags:
        - Buckets
      parameters:
        - $ref: '#/components/parameters/organizationId'
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/clusterId'
        - $ref: '#/components/parameters/bucketId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CapellaBucketUpdateRequest'
      responses:
        '204':
          description: Bucket updated successfully
        '400':
          description: Invalid bucket configuration
        '401':
          description: Unauthorized access
        '404':
          description: Bucket not found
        '429':
          description: Rate limit exceeded
    delete:
      operationId: deleteCapellaBucket
      summary: Delete a bucket
      description: >-
        Deletes the specified bucket and all its data from the Capella cluster.
      tags:
        - Buckets
      parameters:
        - $ref: '#/components/parameters/organizationId'
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/clusterId'
        - $ref: '#/components/parameters/bucketId'
      responses:
        '204':
          description: Bucket deleted successfully
        '401':
          description: Unauthorized access
        '404':
          description: Bucket not found
        '429':
          description: Rate limit exceeded
  /v4/organizations/{organizationId}/projects/{projectId}/clusters/{clusterId}/buckets/{bucketId}/scopes:
    get:
      operationId: listCapellaScopes
      summary: List scopes in a bucket
      description: >-
        Returns the list of scopes within the specified bucket.
      tags:
        - Scopes and Collections
      parameters:
        - $ref: '#/components/parameters/organizationId'
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/clusterId'
        - $ref: '#/components/parameters/bucketId'
      responses:
        '200':
          description: Successful retrieval of scopes
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CapellaScope'
        '401':
          description: Unauthorized access
        '404':
          description: Bucket not found
        '429':
          description: Rate limit exceeded
    post:
      operationId: createCapellaScope
      summary: Create a scope
      description: >-
        Creates a new scope within the specified bucket.
      tags:
        - Scopes and Collections
      parameters:
        - $ref: '#/components/parameters/organizationId'
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/clusterId'
        - $ref: '#/components/parameters/bucketId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  description: The name of the scope to create
      responses:
        '201':
          description: Scope created successfully
        '400':
          description: Invalid scope configuration
        '401':
          description: Unauthorized access
        '429':
          description: Rate limit exceeded
  /v4/organizations/{organizationId}/projects/{projectId}/clusters/{clusterId}/allowedCIDRs:
    get:
      operationId: listAllowedCIDRs
      summary: List allowed CIDRs
      description: >-
        Returns the list of allowed IP addresses and CIDR ranges for
        the specified cluster.
      tags:
        - Allowed CIDRs
      parameters:
        - $ref: '#/components/parameters/organizationId'
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/clusterId'
      responses:
        '200':
          description: Successful retrieval of allowed CIDRs
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AllowedCIDR'
        '401':
          description: Unauthorized access
        '429':
          description: Rate limit exceeded
    post:
      operationId: addAllowedCIDR
      summary: Add an allowed CIDR
      description: >-
        Adds an allowed IP address or CIDR range for the specified cluster.
      tags:
        - Allowed CIDRs
      parameters:
        - $ref: '#/components/parameters/organizationId'
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/clusterId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AllowedCIDRCreateRequest'
      responses:
        '201':
          description: Allowed CIDR added successfully
        '400':
          description: Invalid CIDR configuration
        '401':
          description: Unauthorized access
        '429':
          description: Rate limit exceeded
  /v4/organizations/{organizationId}/projects/{projectId}/clusters/{clusterId}/allowedCIDRs/{allowedCIDRId}:
    delete:
      operationId: deleteAllowedCIDR
      summary: Delete an allowed CIDR
      description: >-
        Removes an allowed IP address or CIDR range from the specified cluster.
      tags:
        - Allowed CIDRs
      parameters:
        - $ref: '#/components/parameters/organizationId'
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/clusterId'
        - name: allowedCIDRId
          in: path
          required: true
          description: The ID of the allowed CIDR to delete
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Allowed CIDR deleted successfully
        '401':
          description: Unauthorized access
        '404':
          description: Allowed CIDR not found
        '429':
          description: Rate limit exceeded
  /v4/organizations/{organizationId}/projects/{projectId}/clusters/{clusterId}/users:
    get:
      operationId: listDatabaseCredentials
      summary: List database credentials
      description: >-
        Returns the list of database access credentials configured for the
        specified cluster.
      tags:
        - Database Credentials
      parameters:
        - $ref: '#/components/parameters/organizationId'
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/clusterId'
      responses:
        '200':
          description: Successful retrieval of database credentials
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/DatabaseCredential'
        '401':
          description: Unauthorized access
        '429':
          description: Rate limit exceeded
    post:
      operationId: createDatabaseCredential
      summary: Create database credentials
      description: >-
        Creates new database access credentials for the specified cluster.
      tags:
        - Database Credentials
      parameters:
        - $ref: '#/components/parameters/organizationId'
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/clusterId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatabaseCredentialCreateRequest'
      responses:
        '201':
          description: Database credentials created successfully
        '400':
          description: Invalid credentials configuration
        '401':
          description: Unauthorized access
        '429':
          description: Rate limit exceeded
  /v4/organizations/{organizationId}/apikeys:
    get:
      operationId: listApiKeys
      summary: List API keys
      description: >-
        Returns the list of API keys configured for the organization.
      tags:
        - API Keys
      parameters:
        - $ref: '#/components/parameters/organizationId'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/perPage'
      responses:
        '200':
          description: Successful retrieval of API keys
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
        '401':
          description: Unauthorized access
        '429':
          description: Rate limit exceeded
    post:
      operationId: createApiKey
      summary: Create an API key
      description: >-
        Creates a new API key for authenticating with the Management API.
      tags:
        - API Keys
      parameters:
        - $ref: '#/components/parameters/organizationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiKeyCreateRequest'
      responses:
        '201':
          description: API key created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyCreateResponse'
        '400':
          description: Invalid API key configuration
        '401':
          description: Unauthorized access
        '429':
          description: Rate limit exceeded
  /v4/organizations/{organizationId}/users:
    get:
      operationId: listCapellaUsers
      summary: List organization users
      description: >-
        Returns the list of users in the specified organization.
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/organizationId'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/perPage'
      responses:
        '200':
          description: Successful retrieval of users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
        '401':
          description: Unauthorized access
        '429':
          description: Rate limit exceeded
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer token authentication using a Capella API key secret.
  parameters:
    organizationId:
      name: organizationId
      in: path
      required: true
      description: The UUID of the organization
      schema:
        type: string
        format: uuid
    projectId:
      name: projectId
      in: path
      required: true
      description: The UUID of the project
      schema:
        type: string
        format: uuid
    clusterId:
      name: clusterId
      in: path
      required: true
      description: The UUID of the cluster
      schema:
        type: string
        format: uuid
    bucketId:
      name: bucketId
      in: path
      required: true
      description: The ID of the bucket
      schema:
        type: string
    page:
      name: page
      in: query
      required: false
      description: Page number for pagination
      schema:
        type: integer
        minimum: 1
        default: 1
    perPage:
      name: perPage
      in: query
      required: false
      description: Number of items per page
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
  schemas:
    Organization:
      type: object
      description: Capella organization
      properties:
        id:
          type: string
          format: uuid
          description: Organization UUID
        name:
          type: string
          description: Organization name
        description:
          type: string
          description: Organization description
        preferences:
          type: object
          description: Organization preferences
        audit:
          $ref: '#/components/schemas/AuditInfo'
    Project:
      type: object
      description: Capella project within an organization
      properties:
        id:
          type: string
          format: uuid
          description: Project UUID
        name:
          type: string
          description: Project name
        description:
          type: string
          description: Project description
        audit:
          $ref: '#/components/schemas/AuditInfo'
    ProjectCreateRequest:
      type: object
      description: Request to create or update a project
      required:
        - name
      properties:
        name:
          type: string
          description: Project name
          maxLength: 128
        description:
          type: string
          description: Project description
          maxLength: 1024
    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
    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
    ServiceGr

# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/couchbase/refs/heads/main/openapi/couchbase-capella-management-api-openapi.yml