openapi: 3.1.0
info:
  title: Couchbase Backup Service REST API
  description: >-
    The Couchbase Backup Service REST API supports management of the Backup
    Service for Couchbase Server, providing endpoints for cluster
    configuration, repository management, backup plans, task scheduling, and
    data operations. It enables automated backup and restore workflows for
    Couchbase data, allowing administrators to define backup policies, monitor
    backup tasks, and manage backup repositories programmatically.
  version: '7.6'
  contact:
    name: Couchbase Support
    url: https://support.couchbase.com
  termsOfService: https://www.couchbase.com/terms-of-use
externalDocs:
  description: Couchbase Backup Service REST API Documentation
  url: https://docs.couchbase.com/server/current/rest-api/backup-rest-api.html
servers:
  - url: https://localhost:8097
    description: Backup Service (default port)
  - url: https://localhost:18097
    description: Backup Service (SSL)
tags:
  - name: Cluster
    description: >-
      Endpoints for managing cluster-level backup configuration.
  - name: Data
    description: >-
      Endpoints for triggering backup and restore data operations.
  - name: Plans
    description: >-
      Endpoints for managing backup plans that define backup schedules and
      data retention policies.
  - name: Repositories
    description: >-
      Endpoints for creating, managing, and querying backup repositories.
  - name: Tasks
    description: >-
      Endpoints for monitoring and managing backup and restore tasks.
security:
  - basicAuth: []
paths:
  /api/v1/cluster/self:
    get:
      operationId: getBackupClusterInfo
      summary: Get backup cluster information
      description: >-
        Returns information about the current cluster from the perspective
        of the Backup Service, including the list of repositories and plans.
      tags:
        - Cluster
      responses:
        '200':
          description: Successful retrieval of cluster backup information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackupClusterInfo'
        '401':
          description: Unauthorized access
  /api/v1/cluster/self/repository/active:
    get:
      operationId: listActiveRepositories
      summary: List active backup repositories
      description: >-
        Returns the list of active backup repositories configured for the
        cluster.
      tags:
        - Repositories
      responses:
        '200':
          description: Successful retrieval of active repositories
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BackupRepository'
        '401':
          description: Unauthorized access
  /api/v1/cluster/self/repository/active/{repositoryId}:
    get:
      operationId: getActiveRepository
      summary: Get active repository details
      description: >-
        Returns detailed information about a specific active backup repository
        including backup names, dates, buckets, items, and mutations.
      tags:
        - Repositories
      parameters:
        - $ref: '#/components/parameters/repositoryId'
      responses:
        '200':
          description: Successful retrieval of repository details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackupRepository'
        '401':
          description: Unauthorized access
        '404':
          description: Repository not found
    post:
      operationId: createActiveRepository
      summary: Create an active backup repository
      description: >-
        Creates a new active backup repository with the specified
        configuration including the backup plan and storage location.
      tags:
        - Repositories
      parameters:
        - $ref: '#/components/parameters/repositoryId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BackupRepositoryCreateRequest'
      responses:
        '200':
          description: Repository created successfully
        '400':
          description: Invalid repository configuration
        '401':
          description: Unauthorized access
    delete:
      operationId: deleteActiveRepository
      summary: Delete an active repository
      description: >-
        Deletes the specified active backup repository. The repository must
        not have any running tasks.
      tags:
        - Repositories
      parameters:
        - $ref: '#/components/parameters/repositoryId'
      responses:
        '200':
          description: Repository deleted successfully
        '401':
          description: Unauthorized access
        '404':
          description: Repository not found
  /api/v1/cluster/self/repository/imported:
    get:
      operationId: listImportedRepositories
      summary: List imported backup repositories
      description: >-
        Returns the list of imported backup repositories.
      tags:
        - Repositories
      responses:
        '200':
          description: Successful retrieval of imported repositories
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BackupRepository'
        '401':
          description: Unauthorized access
  /api/v1/cluster/self/repository/archived:
    get:
      operationId: listArchivedRepositories
      summary: List archived backup repositories
      description: >-
        Returns the list of archived backup repositories.
      tags:
        - Repositories
      responses:
        '200':
          description: Successful retrieval of archived repositories
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BackupRepository'
        '401':
          description: Unauthorized access
  /api/v1/plan:
    get:
      operationId: listBackupPlans
      summary: List backup plans
      description: >-
        Returns the list of all backup plans configured for the cluster.
      tags:
        - Plans
      responses:
        '200':
          description: Successful retrieval of backup plans
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BackupPlan'
        '401':
          description: Unauthorized access
  /api/v1/plan/{planName}:
    get:
      operationId: getBackupPlan
      summary: Get backup plan details
      description: >-
        Returns information about a specific backup plan including the
        services for which data is backed up, and the scheduled tasks.
      tags:
        - Plans
      parameters:
        - $ref: '#/components/parameters/planName'
      responses:
        '200':
          description: Successful retrieval of backup plan details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackupPlan'
        '401':
          description: Unauthorized access
        '404':
          description: Plan not found
    post:
      operationId: createOrUpdateBackupPlan
      summary: Create or update a backup plan
      description: >-
        Creates a new backup plan or updates an existing one with the
        specified schedule, services, and retention settings.
      tags:
        - Plans
      parameters:
        - $ref: '#/components/parameters/planName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BackupPlan'
      responses:
        '200':
          description: Plan created or updated successfully
        '400':
          description: Invalid plan configuration
        '401':
          description: Unauthorized access
    delete:
      operationId: deleteBackupPlan
      summary: Delete a backup plan
      description: >-
        Deletes the specified backup plan. The plan must not be in use by
        any active repository.
      tags:
        - Plans
      parameters:
        - $ref: '#/components/parameters/planName'
      responses:
        '200':
          description: Plan deleted successfully
        '401':
          description: Unauthorized access
        '404':
          description: Plan not found
  /api/v1/cluster/self/repository/active/{repositoryId}/taskHistory:
    get:
      operationId: getRepositoryTaskHistory
      summary: Get repository task history
      description: >-
        Returns the history of backup and restore tasks for the specified
        active repository, including task types, statuses, and timing.
      tags:
        - Tasks
      parameters:
        - $ref: '#/components/parameters/repositoryId'
        - name: offset
          in: query
          required: false
          description: The earliest date for returned tasks
          schema:
            type: string
            format: date-time
        - name: limit
          in: query
          required: false
          description: Maximum number of tasks to return
          schema:
            type: integer
        - name: task_name
          in: query
          required: false
          description: Filter by task name
          schema:
            type: string
      responses:
        '200':
          description: Successful retrieval of task history
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BackupTask'
        '401':
          description: Unauthorized access
        '404':
          description: Repository not found
  /api/v1/cluster/self/repository/active/{repositoryId}/backup:
    post:
      operationId: triggerImmediateBackup
      summary: Trigger an immediate backup
      description: >-
        Triggers an immediate one-off backup for the specified active
        repository, independent of the scheduled backup plan.
      tags:
        - Data
      parameters:
        - $ref: '#/components/parameters/repositoryId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                full_backup:
                  type: boolean
                  description: Whether to perform a full backup instead of incremental
      responses:
        '200':
          description: Backup triggered successfully
        '401':
          description: Unauthorized access
        '404':
          description: Repository not found
  /api/v1/cluster/self/repository/active/{repositoryId}/restore:
    post:
      operationId: restoreFromBackup
      summary: Restore from a backup
      description: >-
        Initiates a restore operation from the specified backup repository,
        allowing you to restore specific buckets or all data.
      tags:
        - Data
      parameters:
        - $ref: '#/components/parameters/repositoryId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RestoreRequest'
      responses:
        '200':
          description: Restore operation initiated
        '400':
          description: Invalid restore configuration
        '401':
          description: Unauthorized access
        '404':
          description: Repository not found
  /api/v1/cluster/self/repository/active/{repositoryId}/pause:
    post:
      operationId: pauseRepositoryTasks
      summary: Pause repository tasks
      description: >-
        Pauses all scheduled tasks for the specified active repository.
      tags:
        - Tasks
      parameters:
        - $ref: '#/components/parameters/repositoryId'
      responses:
        '200':
          description: Repository tasks paused successfully
        '401':
          description: Unauthorized access
        '404':
          description: Repository not found
  /api/v1/cluster/self/repository/active/{repositoryId}/resume:
    post:
      operationId: resumeRepositoryTasks
      summary: Resume repository tasks
      description: >-
        Resumes all paused tasks for the specified active repository.
      tags:
        - Tasks
      parameters:
        - $ref: '#/components/parameters/repositoryId'
      responses:
        '200':
          description: Repository tasks resumed successfully
        '401':
          description: Unauthorized access
        '404':
          description: Repository not found
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic Authentication. Requires the Full Admin role.
  parameters:
    repositoryId:
      name: repositoryId
      in: path
      required: true
      description: The name of the backup repository
      schema:
        type: string
    planName:
      name: planName
      in: path
      required: true
      description: The name of the backup plan
      schema:
        type: string
  schemas:
    BackupClusterInfo:
      type: object
      description: Cluster backup information
      properties:
        name:
          type: string
          description: Cluster name
        repositories:
          type: array
          description: List of repository names
          items:
            type: string
        plans:
          type: array
          description: List of plan names
          items:
            type: string
    BackupRepository:
      type: object
      description: Backup repository configuration and status
      properties:
        id:
          type: string
          description: Repository identifier
        plan_name:
          type: string
          description: Name of the associated backup plan
        state:
          type: string
          description: Current state of the repository
          enum:
            - active
            - paused
            - archived
            - imported
        archive:
          type: string
          description: Path to the backup archive location
        bucket:
          type: object
          description: Cloud storage bucket configuration
          properties:
            name:
              type: string
              description: Bucket name
            provider:
              type: string
              description: Cloud provider
        backups:
          type: array
          description: List of backups in the repository
          items:
            type: object
            properties:
              date:
                type: string
                format: date-time
                description: Date the backup was taken
              type:
                type: string
                description: Type of backup
                enum:
                  - FULL
                  - INCR
              complete:
                type: boolean
                description: Whether the backup completed successfully
              buckets:
                type: array
                description: Buckets included in the backup
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      description: Bucket name
                    items:
                      type: integer
                      description: Number of items backed up
                    mutations:
                      type: integer
                      description: Number of mutations backed up
    BackupRepositoryCreateRequest:
      type: object
      description: Request to create a backup repository
      required:
        - plan
        - archive
      properties:
        plan:
          type: string
          description: Name of the backup plan to use
        archive:
          type: string
          description: Path to the backup archive location
        bucket_name:
          type: string
          description: Cloud storage bucket name (for cloud backups)
    BackupPlan:
      type: object
      description: Backup plan definition
      properties:
        name:
          type: string
          description: Name of the backup plan
        description:
          type: string
          description: Description of the backup plan
        services:
          type: array
          description: Services to back up
          items:
            type: string
            enum:
              - data
              - gsi
              - views
              - ft
              - eventing
              - cbas
        default:
          type: boolean
          description: Whether this is the default plan
        tasks:
          type: array
          description: Scheduled tasks in the plan
          items:
            type: object
            properties:
              name:
                type: string
                description: Task name
              task_type:
                type: string
                description: Type of task
                enum:
                  - BACKUP
                  - MERGE
              full_backup:
                type: boolean
                description: Whether to perform a full backup
              schedule:
                type: object
                description: Task schedule configuration
                properties:
                  job_type:
                    type: string
                    description: Schedule type
                  frequency:
                    type: integer
                    description: Frequency value
                  period:
                    type: string
                    description: Frequency period
                    enum:
                      - MINUTES
                      - HOURS
                      - DAYS
                      - WEEKS
                      - MONDAY
                      - TUESDAY
                      - WEDNESDAY
                      - THURSDAY
                      - FRIDAY
                      - SATURDAY
                      - SUNDAY
    BackupTask:
      type: object
      description: Backup or restore task record
      properties:
        task_name:
          type: string
          description: Name of the task
        status:
          type: string
          description: Task execution status
          enum:
            - done
            - running
            - failed
            - cancelled
        start:
          type: string
          format: date-time
          description: Task start time
        end:
          type: string
          format: date-time
          description: Task end time
        type:
          type: string
          description: Type of task
          enum:
            - BACKUP
            - MERGE
            - RESTORE
        node_runs:
          type: array
          description: Per-node execution details
          items:
            type: object
    RestoreRequest:
      type: object
      description: Restore operation request
      properties:
        target:
          type: string
          description: Target cluster for the restore
        start:
          type: string
          format: date-time
          description: Start date for the restore range
        end:
          type: string
          format: date-time
          description: End date for the restore range
        include_buckets:
          type: array
          description: Buckets to include in the restore
          items:
            type: string
        exclude_buckets:
          type: array
          description: Buckets to exclude from the restore
          items:
            type: string
        map_data:
          type: string
          description: Bucket mapping for restoring to a different bucket name
        auto_create_buckets:
          type: boolean
          description: Whether to auto-create buckets that do not exist
        auto_remove_collections:
          type: boolean
          description: Whether to remove collections not in the backup