openapi: 3.1.0
info:
  title: Couchbase Sync Gateway Admin REST 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
externalDocs:
  description: Couchbase Sync Gateway Admin REST API Documentation
  url: https://docs.couchbase.com/sync-gateway/current/rest-api-admin.html
servers:
  - url: https://localhost:4985
    description: Sync Gateway Admin REST API (default port)
tags:
  - name: Database Management
    description: >-
      Endpoints for creating, configuring, and managing databases.
  - name: Monitoring
    description: >-
      Endpoints for monitoring Sync Gateway health and performance.
  - name: Replication
    description: >-
      Endpoints for configuring inter-Sync Gateway replications.
  - name: Role Management
    description: >-
      Endpoints for managing roles and their channel assignments.
  - name: Server
    description: >-
      Endpoints for managing the Sync Gateway server instance.
  - name: User Management
    description: >-
      Endpoints for managing Sync Gateway users and their access permissions.
security:
  - basicAuth: []
paths:
  /_all_dbs:
    get:
      operationId: listDatabases
      summary: List all databases
      description: >-
        Returns the names of all databases configured on the Sync Gateway
        instance.
      tags:
        - Server
      responses:
        '200':
          description: Successful retrieval of database list
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '401':
          description: Unauthorized access
  /_config:
    get:
      operationId: getServerConfig
      summary: Get server configuration
      description: >-
        Returns the complete Sync Gateway server configuration.
      tags:
        - Server
      responses:
        '200':
          description: Successful retrieval of server configuration
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized access
  /{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
  /{db}/_user/:
    get:
      operationId: listUsers
      summary: List all users
      description: >-
        Returns the list of all users configured for the database.
      tags:
        - User Management
      parameters:
        - $ref: '#/components/parameters/db'
      responses:
        '200':
          description: Successful retrieval of user list
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '401':
          description: Unauthorized access
    post:
      operationId: createUser
      summary: Create a user
      description: >-
        Creates a new user with the specified credentials, roles, and
        channel assignments.
      tags:
        - User Management
      parameters:
        - $ref: '#/components/parameters/db'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserConfig'
      responses:
        '201':
          description: User created successfully
        '400':
          description: Invalid user configuration
        '401':
          description: Unauthorized access
        '409':
          description: User already exists
  /{db}/_user/{userName}:
    get:
      operationId: getUser
      summary: Get user details
      description: >-
        Returns detailed information about a user including their roles,
        channels, and admin channels.
      tags:
        - User Management
      parameters:
        - $ref: '#/components/parameters/db'
        - $ref: '#/components/parameters/userName'
      responses:
        '200':
          description: Successful retrieval of user details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInfo'
        '401':
          description: Unauthorized access
        '404':
          description: User not found
    put:
      operationId: updateUser
      summary: Update a user
      description: >-
        Updates a user's configuration including password, roles, and channels.
      tags:
        - User Management
      parameters:
        - $ref: '#/components/parameters/db'
        - $ref: '#/components/parameters/userName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserConfig'
      responses:
        '200':
          description: User updated successfully
        '401':
          description: Unauthorized access
        '404':
          description: User not found
    delete:
      operationId: deleteUser
      summary: Delete a user
      description: >-
        Deletes the specified user.
      tags:
        - User Management
      parameters:
        - $ref: '#/components/parameters/db'
        - $ref: '#/components/parameters/userName'
      responses:
        '200':
          description: User deleted successfully
        '401':
          description: Unauthorized access
        '404':
          description: User not found
  /{db}/_user/{userName}/_session:
    post:
      operationId: createUserSession
      summary: Create a session for a user
      description: >-
        Creates a new session for the specified user with an optional
        expiration time and channel override.
      tags:
        - User Management
      parameters:
        - $ref: '#/components/parameters/db'
        - $ref: '#/components/parameters/userName'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                ttl:
                  type: integer
                  description: Session time-to-live in seconds
      responses:
        '200':
          description: Session created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  session_id:
                    type: string
                  expires:
                    type: string
                    format: date-time
                  cookie_name:
                    type: string
        '401':
          description: Unauthorized access
        '404':
          description: User not found
  /{db}/_role/:
    get:
      operationId: listRoles
      summary: List all roles
      description: >-
        Returns the list of all roles configured for the database.
      tags:
        - Role Management
      parameters:
        - $ref: '#/components/parameters/db'
      responses:
        '200':
          description: Successful retrieval of role list
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '401':
          description: Unauthorized access
    post:
      operationId: createRole
      summary: Create a role
      description: >-
        Creates a new role with the specified channel assignments.
      tags:
        - Role Management
      parameters:
        - $ref: '#/components/parameters/db'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoleConfig'
      responses:
        '201':
          description: Role created successfully
        '400':
          description: Invalid role configuration
        '401':
          description: Unauthorized access
        '409':
          description: Role already exists
  /{db}/_role/{roleName}:
    get:
      operationId: getRole
      summary: Get role details
      description: >-
        Returns detailed information about a specific role.
      tags:
        - Role Management
      parameters:
        - $ref: '#/components/parameters/db'
        - $ref: '#/components/parameters/roleName'
      responses:
        '200':
          description: Successful retrieval of role details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleInfo'
        '401':
          description: Unauthorized access
        '404':
          description: Role not found
    put:
      operationId: updateRole
      summary: Update a role
      description: >-
        Updates a role's channel assignments.
      tags:
        - Role Management
      parameters:
        - $ref: '#/components/parameters/db'
        - $ref: '#/components/parameters/roleName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoleConfig'
      responses:
        '200':
          description: Role updated successfully
        '401':
          description: Unauthorized access
        '404':
          description: Role not found
    delete:
      operationId: deleteRole
      summary: Delete a role
      description: >-
        Deletes the specified role.
      tags:
        - Role Management
      parameters:
        - $ref: '#/components/parameters/db'
        - $ref: '#/components/parameters/roleName'
      responses:
        '200':
          description: Role deleted successfully
        '401':
          description: Unauthorized access
        '404':
          description: Role not found
  /{db}/_replication/:
    get:
      operationId: listReplications
      summary: List replications
      description: >-
        Returns all configured inter-Sync Gateway replications.
      tags:
        - Replication
      parameters:
        - $ref: '#/components/parameters/db'
      responses:
        '200':
          description: Successful retrieval of replications
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ReplicationConfig'
        '401':
          description: Unauthorized access
    post:
      operationId: createReplication
      summary: Create a replication
      description: >-
        Creates a new inter-Sync Gateway replication.
      tags:
        - Replication
      parameters:
        - $ref: '#/components/parameters/db'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReplicationConfig'
      responses:
        '201':
          description: Replication created successfully
        '400':
          description: Invalid replication configuration
        '401':
          description: Unauthorized access
  /{db}/_replication/{replicationId}:
    get:
      operationId: getReplication
      summary: Get replication details
      description: >-
        Returns the configuration and status of a specific replication.
      tags:
        - Replication
      parameters:
        - $ref: '#/components/parameters/db'
        - $ref: '#/components/parameters/replicationId'
      responses:
        '200':
          description: Successful retrieval of replication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReplicationConfig'
        '401':
          description: Unauthorized access
        '404':
          description: Replication not found
    put:
      operationId: updateReplication
      summary: Update a replication
      description: >-
        Updates the configuration of an existing replication.
      tags:
        - Replication
      parameters:
        - $ref: '#/components/parameters/db'
        - $ref: '#/components/parameters/replicationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReplicationConfig'
      responses:
        '200':
          description: Replication updated successfully
        '401':
          description: Unauthorized access
        '404':
          description: Replication not found
    delete:
      operationId: deleteReplication
      summary: Delete a replication
      description: >-
        Deletes the specified replication.
      tags:
        - Replication
      parameters:
        - $ref: '#/components/parameters/db'
        - $ref: '#/components/parameters/replicationId'
      responses:
        '200':
          description: Replication deleted successfully
        '401':
          description: Unauthorized access
        '404':
          description: Replication not found
  /_expvar:
    get:
      operationId: getExpvar
      summary: Get runtime statistics
      description: >-
        Returns runtime statistics for the Sync Gateway instance.
      tags:
        - Monitoring
      responses:
        '200':
          description: Successful retrieval of statistics
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized access
  /_status:
    get:
      operationId: getServerStatus
      summary: Get server status
      description: >-
        Returns the status of the Sync Gateway server and its databases.
      tags:
        - Monitoring
      responses:
        '200':
          description: Successful retrieval of server status
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    type: string
                  databases:
                    type: object
                    additionalProperties:
                      type: object
                      properties:
                        state:
                          type: string
                        name:
                          type: string
        '401':
          description: Unauthorized access
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic Authentication with admin credentials or RBAC user
        with appropriate roles.
  parameters:
    db:
      name: db
      in: path
      required: true
      description: The database name
      schema:
        type: string
    userName:
      name: userName
      in: path
      required: true
      description: The username
      schema:
        type: string
    roleName:
      name: roleName
      in: path
      required: true
      description: The role name
      schema:
        type: string
    replicationId:
      name: replicationId
      in: path
      required: true
      description: The replication identifier
      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
    UserConfig:
      type: object
      description: User configuration
      required:
        - name
      properties:
        name:
          type: string
          description: Username
        password:
          type: string
          description: User password
        admin_channels:
          type: array
          description: Admin-assigned channels
          items:
            type: string
        admin_roles:
          type: array
          description: Admin-assigned roles
          items:
            type: string
        email:
          type: string
          format: email
          description: User email
        disabled:
          type: boolean
          description: Whether the user is disabled
    UserInfo:
      type: object
      description: User information
      properties:
        name:
          type: string
        admin_channels:
          type: array
          items:
            type: string
        admin_roles:
          type: array
          items:
            type: string
        all_channels:
          type: array
          items:
            type: string
        roles:
          type: array
          items:
            type: string
        email:
          type: string
        disabled:
          type: boolean
    RoleConfig:
      type: object
      description: Role configuration
      required:
        - name
      properties:
        name:
          type: string
          description: Role name
        admin_channels:
          type: array
          description: Admin-assigned channels
          items:
            type: string
    RoleInfo:
      type: object
      description: Role information
      properties:
        name:
          type: string
        admin_channels:
          type: array
          items:
            type: string
        all_channels:
          type: array
          items:
            type: string
    ReplicationConfig:
      type: object
      description: Inter-Sync Gateway replication
      properties:
        replication_id:
          type: string
          description: Replication identifier
        remote:
          type: string
          description: URL of the remote Sync Gateway
        direction:
          type: string
          enum:
            - push
            - pull
            - pushAndPull
        continuous:
          type: boolean
          description: Whether the replication runs continuously
        filter:
          type: string
          description: Filter function
        query_params:
          type: object
          properties:
            channels:
              type: array
              items:
                type: string
        conflict_resolution_type:
          type: string
          enum:
            - default
            - localWins
            - remoteWins
            - custom
        custom_conflict_resolver:
          type: string
          description: Custom conflict resolver function
        initial_state:
          type: string
          enum:
            - running
            - stopped
        state:
          type: string
          enum:
            - running
            - stopped
            - error
            - reconnecting