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