Couchbase Database Management API

openapi: 3.2.0
info:
  title: Couchbase Sync Gateway Admin REST Database Management API
  description: The Couchbase Sync Gateway Admin REST API provides administrative endpoints for configuring and managing Sync Gateway instances. It supports database management, user and role administration, sync function configuration, and replication setup. The API is intended for server-side administration and is typically bound to localhost for security, enabling full control over Sync Gateway behavior, access control policies, and data synchronization rules.
  version: '3.1'
  contact:
    name: Couchbase Support
    url: https://support.couchbase.com
  termsOfService: https://www.couchbase.com/terms-of-use
servers:
- url: https://localhost:4985
  description: Sync Gateway Admin REST API (default port)
security:
- basicAuth: []
tags:
- name: Database Management
  description: Endpoints for creating, configuring, and managing databases.
paths:
  /{db}/_config:
    get:
      operationId: getDatabaseConfig
      summary: Get database configuration
      description: Returns the complete configuration of the specified database including sync function, import filter, and security settings.
      tags:
      - Database Management
      parameters:
      - $ref: '#/components/parameters/db'
      responses:
        '200':
          description: Successful retrieval of database configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatabaseConfig'
        '401':
          description: Unauthorized access
        '404':
          description: Database not found
    put:
      operationId: updateDatabaseConfig
      summary: Update database configuration
      description: Updates the configuration of the specified database.
      tags:
      - Database Management
      parameters:
      - $ref: '#/components/parameters/db'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatabaseConfig'
      responses:
        '200':
          description: Database configuration updated
        '400':
          description: Invalid configuration
        '401':
          description: Unauthorized access
    post:
      operationId: createDatabase
      summary: Create a database
      description: Creates a new database with the specified configuration. The database name is taken from the URL path.
      tags:
      - Database Management
      parameters:
      - $ref: '#/components/parameters/db'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatabaseConfig'
      responses:
        '201':
          description: Database created successfully
        '400':
          description: Invalid configuration
        '401':
          description: Unauthorized access
        '412':
          description: Database already exists
    delete:
      operationId: deleteDatabase
      summary: Delete a database
      description: Deletes the specified database configuration from Sync Gateway.
      tags:
      - Database Management
      parameters:
      - $ref: '#/components/parameters/db'
      responses:
        '200':
          description: Database deleted successfully
        '401':
          description: Unauthorized access
        '404':
          description: Database not found
  /{db}/_config/sync:
    get:
      operationId: getSyncFunction
      summary: Get sync function
      description: Returns the current sync function for the database.
      tags:
      - Database Management
      parameters:
      - $ref: '#/components/parameters/db'
      responses:
        '200':
          description: Successful retrieval of sync function
          content:
            text/plain:
              schema:
                type: string
        '401':
          description: Unauthorized access
    put:
      operationId: updateSyncFunction
      summary: Update sync function
      description: Updates the sync function for the database. The sync function controls channel routing and access grants for documents.
      tags:
      - Database Management
      parameters:
      - $ref: '#/components/parameters/db'
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              type: string
      responses:
        '200':
          description: Sync function updated
        '400':
          description: Invalid sync function
        '401':
          description: Unauthorized access
  /{db}/_offline:
    post:
      operationId: takeDatabaseOffline
      summary: Take database offline
      description: Takes the specified database offline, preventing client access.
      tags:
      - Database Management
      parameters:
      - $ref: '#/components/parameters/db'
      responses:
        '200':
          description: Database taken offline
        '401':
          description: Unauthorized access
  /{db}/_online:
    post:
      operationId: bringDatabaseOnline
      summary: Bring database online
      description: Brings the specified database back online.
      tags:
      - Database Management
      parameters:
      - $ref: '#/components/parameters/db'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                delay:
                  type: integer
                  description: Delay in seconds before coming online
      responses:
        '200':
          description: Database brought online
        '401':
          description: Unauthorized access
  /{db}/_resync:
    post:
      operationId: resyncDatabase
      summary: Resync database
      description: Reprocesses all documents through the sync function. Required after sync function changes to apply to existing documents.
      tags:
      - Database Management
      parameters:
      - $ref: '#/components/parameters/db'
      responses:
        '200':
          description: Resync completed
          content:
            application/json:
              schema:
                type: object
                properties:
                  changes_processed:
                    type: integer
        '401':
          description: Unauthorized access
  /{db}/_compact:
    post:
      operationId: compactDatabase
      summary: Compact database
      description: Removes obsolete revision bodies and attachment data from the database to reclaim storage space.
      tags:
      - Database Management
      parameters:
      - $ref: '#/components/parameters/db'
      responses:
        '200':
          description: Compaction started
        '401':
          description: Unauthorized access
  /{db}/_purge:
    post:
      operationId: purgeDocuments
      summary: Purge documents
      description: Permanently removes documents from the database. Unlike deletion, purged documents leave no tombstone and are not replicated.
      tags:
      - Database Management
      parameters:
      - $ref: '#/components/parameters/db'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Map of document IDs to arrays of revision IDs to purge
              additionalProperties:
                type: array
                items:
                  type: string
      responses:
        '200':
          description: Documents purged successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  purged:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
        '401':
          description: Unauthorized access
components:
  parameters:
    db:
      name: db
      in: path
      required: true
      description: The database name
      schema:
        type: string
  schemas:
    DatabaseConfig:
      type: object
      description: Database configuration
      properties:
        name:
          type: string
          description: Database name
        bucket:
          type: string
          description: Couchbase Server bucket name
        sync:
          type: string
          description: JavaScript sync function
        import_filter:
          type: string
          description: JavaScript import filter function
        enable_shared_bucket_access:
          type: boolean
          description: Whether shared bucket access is enabled
        import_docs:
          type: boolean
          description: Whether to auto-import documents
        num_index_replicas:
          type: integer
          description: Number of GSI index replicas
        delta_sync:
          type: object
          properties:
            enabled:
              type: boolean
            rev_max_age_seconds:
              type: integer
        guest:
          type: object
          properties:
            disabled:
              type: boolean
            admin_channels:
              type: array
              items:
                type: string
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication with admin credentials or RBAC user with appropriate roles.
externalDocs:
  description: Couchbase Sync Gateway Admin REST API Documentation
  url: https://docs.couchbase.com/sync-gateway/current/rest-api-admin.html