openapi: 3.1.0
info:
  title: Couchbase Capella App Services Admin API
  description: >-
    The Couchbase Capella App Services Admin API provides administrative REST
    endpoints for managing Sync Gateway configurations within Couchbase
    Capella. It enables administrators to manage databases, users, roles,
    sync functions, and replication settings for mobile data synchronization.
    The API supports full administrative control over App Services
    deployments, including user provisioning, access control, and monitoring
    of sync operations.
  version: '3.0'
  contact:
    name: Couchbase Support
    url: https://support.couchbase.com
  termsOfService: https://www.couchbase.com/terms-of-use
externalDocs:
  description: Couchbase Capella App Services Admin API Documentation
  url: https://docs.couchbase.com/cloud/app-services/references/rest_api_admin.html
servers:
  - url: https://{appEndpoint}:4985
    description: Capella App Services Admin endpoint
    variables:
      appEndpoint:
        default: example.apps.cloud.couchbase.com
        description: The App Services admin endpoint URL
tags:
  - name: Database Administration
    description: >-
      Endpoints for managing database configurations within App Services.
  - name: Monitoring
    description: >-
      Endpoints for monitoring App Services health and performance.
  - name: Replication
    description: >-
      Endpoints for managing inter-Sync Gateway replications.
  - name: Role Management
    description: >-
      Endpoints for managing roles and their channel assignments.
  - name: User Management
    description: >-
      Endpoints for managing users and their access permissions.
security:
  - basicAuth: []
paths:
  /{db}/_config:
    get:
      operationId: getDatabaseConfig
      summary: Get database configuration
      description: >-
        Returns the full configuration of the specified database including
        sync function, import filter, and other settings.
      tags:
        - Database Administration
      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. This can include
        changes to the sync function, import filter, and other settings.
      tags:
        - Database Administration
      parameters:
        - $ref: '#/components/parameters/db'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatabaseConfig'
      responses:
        '200':
          description: Database configuration updated successfully
        '400':
          description: Invalid configuration
        '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 specified database.
      tags:
        - Database Administration
      parameters:
        - $ref: '#/components/parameters/db'
      responses:
        '200':
          description: Successful retrieval of sync function
          content:
            text/plain:
              schema:
                type: string
        '401':
          description: Unauthorized access
        '404':
          description: Database not found
    put:
      operationId: updateSyncFunction
      summary: Update sync function
      description: >-
        Updates the sync function for the specified database. The sync
        function controls document routing to channels and access grants.
      tags:
        - Database Administration
      parameters:
        - $ref: '#/components/parameters/db'
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              type: string
              description: JavaScript sync function code
      responses:
        '200':
          description: Sync function updated successfully
        '400':
          description: Invalid sync function
        '401':
          description: Unauthorized access
        '404':
          description: Database not found
  /{db}/_offline:
    post:
      operationId: takeDatabaseOffline
      summary: Take database offline
      description: >-
        Takes the specified database offline, preventing any client access.
      tags:
        - Database Administration
      parameters:
        - $ref: '#/components/parameters/db'
      responses:
        '200':
          description: Database taken offline successfully
        '401':
          description: Unauthorized access
        '404':
          description: Database not found
  /{db}/_online:
    post:
      operationId: bringDatabaseOnline
      summary: Bring database online
      description: >-
        Brings the specified database back online after being taken offline.
      tags:
        - Database Administration
      parameters:
        - $ref: '#/components/parameters/db'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                delay:
                  type: integer
                  description: Delay in seconds before bringing the database online
      responses:
        '200':
          description: Database brought online successfully
        '401':
          description: Unauthorized access
        '404':
          description: Database not found
  /{db}/_resync:
    post:
      operationId: resyncDatabase
      summary: Resync database
      description: >-
        Reprocesses all documents through the sync function. This is required
        after updating the sync function to apply changes to existing
        documents.
      tags:
        - Database Administration
      parameters:
        - $ref: '#/components/parameters/db'
      responses:
        '200':
          description: Resync completed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  changes_processed:
                    type: integer
                    description: Number of documents reprocessed
        '401':
          description: Unauthorized access
        '404':
          description: Database not found
  /{db}/_user/:
    get:
      operationId: listUsers
      summary: List all users
      description: >-
        Returns the list of all users configured for the specified 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 for the specified database with the given
        credentials 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 specific 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 the configuration of an existing user including their
        password, roles, and channel assignments.
      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
        '400':
          description: Invalid user configuration
        '401':
          description: Unauthorized access
        '404':
          description: User not found
    delete:
      operationId: deleteUser
      summary: Delete a user
      description: >-
        Deletes the specified user from the database.
      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}/_role/:
    get:
      operationId: listRoles
      summary: List all roles
      description: >-
        Returns the list of all roles configured for the specified 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 for the specified database with the given
        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 including its
        channel assignments.
      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 the configuration of an existing role including its 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
        '400':
          description: Invalid role configuration
        '401':
          description: Unauthorized access
        '404':
          description: Role not found
    delete:
      operationId: deleteRole
      summary: Delete a role
      description: >-
        Deletes the specified role from the database.
      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 the list of all inter-Sync Gateway replications configured
        for the specified database.
      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 for the specified
        database.
      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 detailed information about a specific replication.
      tags:
        - Replication
      parameters:
        - $ref: '#/components/parameters/db'
        - $ref: '#/components/parameters/replicationId'
      responses:
        '200':
          description: Successful retrieval of replication details
          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
        '400':
          description: Invalid replication configuration
        '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 expvar statistics for the Sync Gateway instance
        including memory usage, goroutine counts, and database statistics.
      tags:
        - Monitoring
      responses:
        '200':
          description: Successful retrieval of runtime statistics
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized access
  /_status:
    get:
      operationId: getStatus
      summary: Get server status
      description: >-
        Returns the status of the Sync Gateway server including version
        information and database states.
      tags:
        - Monitoring
      responses:
        '200':
          description: Successful retrieval of server status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerStatus'
        '401':
          description: Unauthorized access
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic Authentication using App Services admin credentials.
  parameters:
    db:
      name: db
      in: path
      required: true
      description: The name of the database
      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 code
        import_filter:
          type: string
          description: JavaScript import filter function code
        enable_shared_bucket_access:
          type: boolean
          description: Whether to enable shared bucket access with SDKs
        import_docs:
          type: boolean
          description: Whether to auto-import documents from the bucket
        num_index_replicas:
          type: integer
          description: Number of GSI index replicas
        delta_sync:
          type: object
          description: Delta sync configuration
          properties:
            enabled:
              type: boolean
              description: Whether delta sync is enabled
            rev_max_age_seconds:
              type: integer
              description: Maximum age for revision deltas in seconds
        guest:
          type: object
          description: Guest (unauthenticated) user configuration
          properties:
            disabled:
              type: boolean
              description: Whether the guest user is disabled
            admin_channels:
              type: array
              description: Admin channels for the guest user
              items:
                type: string
    UserConfig:
      type: object
      description: User configuration for creation or update
      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 address
        disabled:
          type: boolean
          description: Whether the user account is disabled
    UserInfo:
      type: object
      description: User information
      properties:
        name:
          type: string
          description: Username
        admin_channels:
          type: array
          description: Admin-assigned channels
          items:
            type: string
        admin_roles:
          type: array
          description: Admin-assigned roles
          items:
            type: string
        all_channels:
          type: array
          description: All channels accessible by the user
          items:
            type: string
        roles:
          type: array
          description: All roles assigned to the user
          items:
            type: string
        email:
          type: string
          description: User email address
        disabled:
          type: boolean
          description: Whether the user account is disabled
    RoleConfig:
      type: object
      description: Role configuration
      required:
        - name
      properties:
        name:
          type: string
          description: Role name
        admin_channels:
          type: array
          description: Admin-assigned channels for this role
          items:
            type: string
    RoleInfo:
      type: object
      description: Role information
      properties:
        name:
          type: string
          description: Role name
        admin_channels:
          type: array
          description: Admin-assigned channels
          items:
            type: string
        all_channels:
          type: array
          description: All channels accessible through this role
          items:
            type: string
    ReplicationConfig:
      type: object
      description: Inter-Sync Gateway replication configuration
      properties:
        replication_id:
          type: string
          description: Replication identifier
        remote:
          type: string
          description: URL of the remote Sync Gateway
        direction:
          type: string
          description: Replication direction
          enum:
            - push
            - pull
            - pushAndPull
        continuous:
          type: boolean
          description: Whether the replication runs continuously
        filter:
          type: string
          description: Filter function for the replication
          enum:
            - sync_gateway/bychannel
        query_params:
          type: object
          description: Parameters for the filter function
          properties:
            channels:
              type: array
              description: Channel names to replicate
              items:
                type: string
        conflict_resolution_type:
          type: string
          description: Conflict resolution strategy
          enum:
            - default
            - localWins
            - remoteWins
            - custom
        custom_conflict_resolver:
          type: string
          description: JavaScript custom conflict resolver function
        max_backoff_time:
          type: integer
          description: Maximum backoff time for retries in minutes
        initial_state:
          type: string
          description: Initial state of the replication
          enum:
            - running
            - stopped
        state:
          type: string
          description: Current state of the replication
          enum:
            - running
            - stopped
            - error
            - reconnecting
            - starting
    ServerStatus:
      type: object
      description: Sync Gateway server status
      properties:
        couchdb:
          type: string
          description: CouchDB compatibility string
        vendor:
          type: object
          description: Vendor information
          properties:
            name:
              type: string
              description: Vendor name
            version:
              type: string
              description: Sync Gateway version
        version:
          type: string
          description: Full version string
        databases:
          type: object
          description: Database states
          additionalProperties:
            type: object
            properties:
              state:
                type: string
                description: Database state
                enum:
                  - Online
                  - Offline
              name:
                type: string
                description: Database name