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