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.
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