Couchbase Nodes API

openapi: 3.2.0
info:
  title: Couchbase Server REST Nodes API
  description: The Couchbase Server REST API provides programmatic access to manage and configure Couchbase Server clusters. It includes endpoints for cluster management, bucket operations, node administration, security settings, and server configuration. The API enables automation of deployment, monitoring, and maintenance tasks for Couchbase Server instances across distributed environments.
  version: '7.6'
  contact:
    name: Couchbase Support
    url: https://support.couchbase.com
  termsOfService: https://www.couchbase.com/terms-of-use
servers:
- url: https://localhost:8091
  description: Couchbase Server (default port)
- url: https://localhost:18091
  description: Couchbase Server (SSL)
security:
- basicAuth: []
tags:
- name: Nodes
  description: Endpoints for managing individual server nodes, including adding nodes, failover, recovery, and rebalance operations.
paths:
  /pools/nodes:
    get:
      operationId: getNodes
      summary: Get nodes information
      description: Returns information about all nodes in the cluster, including their services, status, and system resources.
      tags:
      - Nodes
      responses:
        '200':
          description: Successful retrieval of node information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NodesInfo'
        '401':
          description: Unauthorized access
  /controller/addNode:
    post:
      operationId: addNode
      summary: Add a node to the cluster
      description: Adds a new node to the cluster. The node must be configured and reachable before it can be added.
      tags:
      - Nodes
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - hostname
              properties:
                hostname:
                  type: string
                  description: The hostname or IP address of the node to add
                services:
                  type: string
                  description: Comma-separated list of services to enable on the node (kv, n1ql, index, fts, cbas, eventing, backup)
                user:
                  type: string
                  description: Administrator username for the node
                password:
                  type: string
                  description: Administrator password for the node
      responses:
        '200':
          description: Node added successfully
        '400':
          description: Invalid node configuration
        '401':
          description: Unauthorized access
  /controller/rebalance:
    post:
      operationId: rebalanceCluster
      summary: Rebalance the cluster
      description: Initiates a rebalance operation to redistribute data across the cluster nodes after adding or removing nodes.
      tags:
      - Nodes
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                knownNodes:
                  type: string
                  description: Comma-separated list of known node OTP names
                ejectedNodes:
                  type: string
                  description: Comma-separated list of node OTP names to eject
      responses:
        '200':
          description: Rebalance initiated successfully
        '400':
          description: Invalid rebalance configuration
        '401':
          description: Unauthorized access
  /controller/failOver:
    post:
      operationId: failOverNode
      summary: Fail over a node
      description: Initiates a hard failover for the specified node, removing it from the cluster immediately.
      tags:
      - Nodes
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - otpNode
              properties:
                otpNode:
                  type: string
                  description: The OTP name of the node to fail over
      responses:
        '200':
          description: Failover initiated successfully
        '400':
          description: Invalid failover request
        '401':
          description: Unauthorized access
components:
  schemas:
    NodesInfo:
      type: object
      description: Information about cluster nodes
      properties:
        nodes:
          type: array
          description: List of nodes
          items:
            $ref: '#/components/schemas/Node'
    Node:
      type: object
      description: Information about a cluster node
      properties:
        hostname:
          type: string
          description: Node hostname and port
        status:
          type: string
          description: Node status
          enum:
          - healthy
          - unhealthy
          - warmup
        clusterMembership:
          type: string
          description: Cluster membership status
          enum:
          - active
          - inactiveAdded
          - inactiveFailed
        services:
          type: array
          description: List of services running on the node
          items:
            type: string
            enum:
            - kv
            - n1ql
            - index
            - fts
            - cbas
            - eventing
            - backup
        os:
          type: string
          description: Operating system of the node
        version:
          type: string
          description: Couchbase Server version on the node
        memoryTotal:
          type: integer
          description: Total memory on the node in bytes
        memoryFree:
          type: integer
          description: Free memory on the node in bytes
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication using Couchbase Server administrator credentials.
externalDocs:
  description: Couchbase Server REST API Documentation
  url: https://docs.couchbase.com/server/current/rest-api/rest-intro.html