Sync Gateway (3.2)

Download OpenAPI specification:Download

License: Business Source License 1.1 (BSL)

Sync Gateway manages access and synchronization between Couchbase Lite and Couchbase Server

Sync Gateway Quickstart | Couchbase Docs

Authentication

Manage authentication

Create a new Facebook-based session Deprecated

Creates a new session based on a Facebook user. On a successful session creation, a session cookie is stored to keep the user authenticated for future API calls.

If CORS is enabled, the origin must match an allowed login origin otherwise an error will be returned.

path Parameters

db

required

string

Example: db1

The name of the database to run the operation against.

Request Body schema: application/json

access_token

required

string

Facebook access token to base the new session on.

Responses

Request samples

Payload

Content type

application/json

{"access_token": "string"
}

Response samples

400
401
404
502
504

Content type

application/json

{"error": "string",
"reason": "string"
}

Create a new Google-based session Deprecated

Creates a new session based on a Google user. On a successful session creation, a session cookie is stored to keep the user authenticated for future API calls.

If CORS is enabled, the origin must match an allowed login origin otherwise an error will be returned.

path Parameters

db

required

string

Example: db1

The name of the database to run the operation against.

Request Body schema: application/json

id_token

required

string

Google ID token to base the new session on.

Responses

Request samples

Payload

Content type

application/json

{"id_token": "string"
}

Response samples

400
401
404
502

Content type

application/json

{"error": "string",
"reason": "string"
}

OpenID Connect authentication initiation via Location header redirect

Called by clients to initiate the OpenID Connect Authorization Code Flow. Redirects to the OpenID Connect provider if successful.

path Parameters

db

required

string

Example: db1

The name of the database to run the operation against.

query Parameters

provider	string The OpenID Connect provider to use for authentication. The list of providers are defined in the Sync Gateway config. If left empty, the default provider will be used.
offline	string If true, the OpenID Connect provider is requested to confirm with the user the permissions requested and refresh the OIDC token. To do this, access_type=offline and prompt=consent is set on the redirection link.

Responses

Response samples

404

Content type

application/json

{"error": "not_found",
"reason": "no such database \"invalid-db\""
}

OpenID Connect authentication initiation via WWW-Authenticate header

Called by clients to initiate the OpenID Connect Authorization Code Flow. This will establish a connection with the provider, then put the redirect URL in the WWW-Authenticate header.

path Parameters

db

required

string

Example: db1

The name of the database to run the operation against.

query Parameters

provider	string The OpenID Connect provider to use for authentication. The list of providers are defined in the Sync Gateway config. If left empty, the default provider will be used.
offline	string If true, the OpenID Connect provider is requested to confirm with the user the permissions requested and refresh the OIDC token. To do this, access_type=offline and prompt=consent is set on the redirection link.

Responses

Response samples

404

Content type

application/json

{"error": "not_found",
"reason": "no such database \"invalid-db\""
}

OpenID Connect authentication callback

The callback URL that the client is redirected to after authenticating with the OpenID Connect provider.

path Parameters

db

required

string

Example: db1

The name of the database to run the operation against.

query Parameters

error	string The OpenID Connect error, if any occurred.
code required	string The OpenID Connect authentication code.
provider	string The OpenID Connect provider to use for authentication. The list of providers are defined in the Sync Gateway config. If left empty, the default provider will be used.
state	string The OpenID Connect state to verify against the state cookie. This is used to prevent cross-site request forgery (CSRF). This is not required if `disable_callback_state=true` for the provider config (NOT recommended).

Responses

Response samples

200
404
500

Content type

application/json

{"id_token": "string",
"refresh_token": "string",
"session_id": "string",
"name": "string",
"access_token": "string",
"token_type": "string",
"expires_in": 0
}

OpenID Connect token refresh

Refresh the OpenID Connect token based on the provided refresh token.

path Parameters

db

required

string

Example: db1

The name of the database to run the operation against.

query Parameters

refresh_token required	string The OpenID Connect refresh token.
provider	string The OpenID Connect provider to use for authentication. The list of providers are defined in the Sync Gateway config. If left empty, the default provider will be used.

Responses

Response samples

200
404

Content type

application/json

{"id_token": "string",
"refresh_token": "string",
"session_id": "string",
"name": "string",
"access_token": "string",
"token_type": "string",
"expires_in": 0
}

OpenID Connect mock provider

Mock an OpenID Connect provider response for testing purposes. This returns a response that is the same structure as what Sync Gateway expects from an OIDC provider after initiating OIDC authentication.

path Parameters

db

required

string

Example: db1

The name of the database to run the operation against.

Responses

Response samples

200
404

Content type

application/json

{"issuer": "string",
"authorization_endpoint": "string",
"token_endpoint": "string",
"jwks_uri": "string",
"userinfo_endpoint": "string",
"id_token_signing_alg_values_supported": "string",
"response_types_supported": "string",
"subject_types_supported": "string",
"scopes_supported": "string",
"claims_supported": "string",
"token_endpoint_auth_methods_supported": "string"
}

OpenID Connect mock login page

Show a mock OpenID Connect login page for the client to log in to.

path Parameters

db

required

string

Example: db1

The name of the database to run the operation against.

query Parameters

scope

required

string

The OpenID Connect authentication scope.

Responses

Response samples

400
404
500

Content type

application/json

{"error": "string",
"reason": "string"
}

OpenID Connect mock login page

Show a mock OpenID Connect login page for the client to log in to.

path Parameters

db

required

string

Example: db1

The name of the database to run the operation against.

query Parameters

scope

required

string

The OpenID Connect authentication scope.

Responses

Response samples

400
404
500

Content type

application/json

{"error": "string",
"reason": "string"
}

OpenID Connect mock token

Return a mock OpenID Connect token for the OIDC authentication flow.

path Parameters

db

required

string

Example: db1

The name of the database to run the operation against.

Request Body schema: application/json

grant_type required	string The grant type of the token to request. Can either be an `authorization_code` or `refresh_token`.
code	string `grant_type=authorization_code` only: The OpenID Connect authentication token.
refresh_token	string `grant_type=refresh_token` only: The OpenID Connect refresh token.

Responses

Request samples

Payload

Content type

application/json

{"grant_type": "string",
"code": "string",
"refresh_token": "string"
}

Response samples

200
404

Content type

application/json

{"access_token": "string",
"token_type": "string",
"refresh_token": "string",
"expires_in": "string",
"id_token": "string"
}

OpenID Connect public certificates for signing keys

Return a mock OpenID Connect public key to be used as signing keys.

path Parameters

db

required

string

Example: db1

The name of the database to run the operation against.

Responses

Response samples

200
404
500

Content type

application/json

{"keys": [{"Key": { },
"KeyID": "string",
"Use": "string",
"Certificates": [{ }
],
"Algorithm": "string"
}
]
}

OpenID Connect mock login page handler

Used to handle the login page displayed for the GET /{db}/_oidc_testing/authorize endpoint.

path Parameters

db

required

string

Example: db1

The name of the database to run the operation against.

query Parameters

redirect_uri	string The Sync Gateway OpenID Connect callback URL.
scope required	string The OpenID Connect authentication scope.
username required	string
tokenttl required	integer
identity-token-formats required	string
authenticated required	string

Responses

Response samples

404

Content type

application/json

{"error": "not_found",
"reason": "no such database \"invalid-db\""
}

OpenID Connect mock login page handler

Used to handle the login page displayed for the GET /{db}/_oidc_testing/authorize endpoint.

path Parameters

db

required

string

Example: db1

The name of the database to run the operation against.

query Parameters

redirect_uri	string The Sync Gateway OpenID Connect callback URL.
scope required	string The OpenID Connect authentication scope.

Request Body schema: application/json

Properties passed from the OpenID Connect mock login page to the handler

username required	string
tokenttl required	string
identity-token-formats required	string
authenticated required	string

Responses

Request samples

Payload

Content type

application/json

{"username": "string",
"tokenttl": "string",
"identity-token-formats": "string",
"authenticated": "string"
}

Response samples

404

Content type

application/json

{"error": "not_found",
"reason": "no such database \"invalid-db\""
}

Server

Manage server activities

Get console logging settings Deprecated

Deprecated in favour of GET /_config This will return a map of the log keys being used for the console logging.

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

Responses

Response samples

200

Content type

application/json

{"HTTP": true,
"CRUD": false,
"Changes": true
}

Set console logging settings Deprecated

Deprecated in favour of PUT /_config Enable or disable console log keys and optionally change the console log level.

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

query Parameters

logLevel	string Enum: "none" "error" "warn" "info" "debug" "trace" The is what to set the console log level too.
level	integer [ 1 .. 3 ] Deprecated Deprecated: use log level instead. This sets the console log level depending on the value provide. 1 sets to `info`, 2 sets to `warn`, and 3 sets to `error`.'

Request Body schema: application/json

The map of log keys to use for console logging.

property name*

additional property

boolean

The log key and whether it is enabled or not.

Responses

Request samples

Payload

Content type

application/json

{"HTTP": true,
"CRUD": false,
"Changes": true
}

Response samples

400

Content type

application/json

{"error": "string",
"reason": "string"
}

Update console logging settings Deprecated

Deprecated in favour of PUT /_config This is for enabling the log keys provided and optionally changing the console log level.

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

query Parameters

logLevel	string Enum: "none" "error" "warn" "info" "debug" "trace" The is what to set the console log level too.
level	integer [ 1 .. 3 ] Deprecated Deprecated: use log level instead. This sets the console log level depending on the value provide. 1 sets to `info`, 2 sets to `warn`, and 3 sets to `error`.'

Request Body schema: application/json

The console log keys to upsert.

property name*

additional property

boolean

The log key and whether it is enabled or not.

Responses

Request samples

Payload

Content type

application/json

{"HTTP": true,
"CRUD": false,
"Changes": true
}

Response samples

400

Content type

application/json

{"error": "string",
"reason": "string"
}

Get server configuration

This will return the configuration that the Sync Gateway node was initially started up with, or the currently config if include_runtime is set.

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

query Parameters

redact	boolean Deprecated Default: "true" No longer supported field.
include_runtime	boolean Default: false Whether to include the values set after starting (at runtime), default values, and all loaded databases.

Responses

Response samples

200
400

Content type

application/json

{"bootstrap": {"group_id": "default",
"config_update_frequency": "10s",
"server": "string",
"username": "string",
"password": "string",
"ca_cert_path": "string",
"server_tls_skip_verify": false,
"x509_cert_path": "string",
"x509_key_path": "string",
"use_tls_server": true
},
"api": {"public_interface": ":4984",
"admin_interface": "127.0.0.1:4985",
"metrics_interface": "127.0.0.1:4986",
"profile_interface": "string",
"admin_interface_authentication": true,
"metrics_interface_authentication": true,
"enable_advanced_auth_dp": true,
"server_read_timeout": "string",
"server_write_timeout": "string",
"read_header_timeout": "5s",
"idle_timeout": "90s",
"pretty": true,
"max_connections": 0,
"compress_responses": true,
"hide_product_version": true,
"https": {"tls_minimum_version": "tlsv1.2",
"tls_cert_path": "string",
"tls_key_path": "string"
},
"cors": {"origin": ["string"
],
"login_origin": ["string"
],
"headers": ["string"
],
"max_age": 0
}
},
"logging": {"log_file_path": "string",
"redaction_level": "none",
"console": {"log_level": "none",
"log_keys": ["string"
],
"color_enabled": false,
"file_output": "string",
"enabled": false,
"rotation": {"max_size": 100,
"localtime": false,
"rotated_logs_size_limit": 1024,
"rotation_interval": 0,
"max_age": 0
},
"collation_buffer_size": 10
},
"error": {"enabled": true,
"rotation": {"max_size": 100,
"localtime": false,
"rotated_logs_size_limit": 1024,
"rotation_interval": 0,
"max_age": 360
},
"collation_buffer_size": 0
},
"warn": {"enabled": true,
"rotation": {"max_size": 100,
"localtime": false,
"rotated_logs_size_limit": 1024,
"rotation_interval": 0,
"max_age": 180
},
"collation_buffer_size": 0
},
"info": {"enabled": true,
"rotation": {"max_size": 100,
"localtime": false,
"rotated_logs_size_limit": 1024,
"rotation_interval": 0,
"max_age": 6
},
"collation_buffer_size": 0
},
"debug": {"enabled": false,
"rotation": {"max_size": 100,
"localtime": false,
"rotated_logs_size_limit": 1024,
"rotation_interval": 0,
"max_age": 2
},
"collation_buffer_size": 1000
},
"trace": {"enabled": false,
"rotation": {"max_size": 100,
"localtime": false,
"rotated_logs_size_limit": 1024,
"rotation_interval": 0,
"max_age": 2
},
"collation_buffer_size": 1000
},
"stats": {"enabled": true,
"rotation": {"max_size": 100,
"localtime": false,
"rotated_logs_size_limit": 1024,
"rotation_interval": 0,
"max_age": 6
},
"collation_buffer_size": 0
},
"audit": {"enabled": false,
"rotation": {"max_size": 100,
"localtime": false,
"rotated_logs_size_limit": 1024,
"rotation_interval": 0,
"max_age": 6
},
"audit_log_file_path": "string",
"enabled_events": [1234,
5678
]
}
},
"auth": {"bcrypt_cost": 10
},
"replicator": {"max_heartbeat": "string",
"blip_compression": 9,
"max_concurrent_replications": 0,
"max_concurrent_changes_batches": 2,
"max_concurrent_revs": 5
},
"unsupported": {"serverless": {"enabled": true,
"min_config_fetch_interval": "1s"
},
"use_xattr_config": false,
"stats_log_frequency": "1m",
"use_stdlib_json": false,
"http2": {"enabled": false
},
"allow_dbconfig_env_vars": true,
"diagnostic_interface": ""
},
"database_credentials": {"databasename1": {"username": "string",
"password": "string",
"x509_cert_path": "string",
"x509_key_path": "string"
},
"databasename2": {"username": "string",
"password": "string",
"x509_cert_path": "string",
"x509_key_path": "string"
}
},
"bucket_credentials": {"bucketname1": {"username": "string",
"password": "string",
"x509_cert_path": "string",
"x509_key_path": "string"
},
"bucketname2": {"username": "string",
"password": "string",
"x509_cert_path": "string",
"x509_key_path": "string"
}
},
"max_file_descriptors": 5000,
"couchbase_keepalive_interval": 0,
"heap_profile_collection_threshold": "max memory",
"heap_profile_disable_collection": false
}

Set runtime configuration

This endpoint is used to dynamically set runtime options, like logging without needing a restart.

These options are not persisted, and will not survive a restart of Sync Gateway.

The endpoint only accepts a limited number of options that can be changed at runtime. See request body schema for allowable options.

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

Request Body schema: application/json

	object (Logging-config)
max_concurrent_replications	integer Default: 0 Maximum number of concurrent replication connections allowed. If set to 0 this limit will be ignored.

Responses

Request samples

Payload

Content type

application/json

{"logging": {"console": {"log_level": "none",
"log_keys": ["string"
]
},
"error": {"enabled": true
},
"warn": {"enabled": true
},
"info": {"enabled": true
},
"debug": {"enabled": false
},
"trace": {"enabled": false
},
"stats": {"enabled": true
},
"audit": {"enabled": false
}
},
"max_concurrent_replications": 0
}

Response samples

400

Content type

application/json

{"error": "string",
"reason": "string"
}

Get the server status

This will retrieve the status of each database and the overall server status.

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

Responses

Response samples

200
400

Content type

application/json

{"databases": {"property1": {"seq": 0,
"server_uuid": "string",
"state": "Online",
"replication_status": [{"replication_id": "string",
"config": {"replication_id": "string",
"remote": "string",
"username": "string",
"password": "string",
"remote_username": "string",
"remote_password": "string",
"direction": "push",
"conflict_resolution_type": "default",
"custom_conflict_resolver": "none",
"purge_on_removal": false,
"enable_delta_sync": false,
"max_backoff_time": 5,
"initial_state": "running",
"continuous": false,
"filter": "sync_gateway/bychannel",
"query_params": ["string"
],
"adhoc": false,
"batch_size": 200,
"run_as": "string",
"collections_enabled": false,
"collections_local": ["scope1.collection1",
"scope1.collection3",
"scope1.collection6"
],
"collections_remote": ["scope1.collectionA",
null,
"scope1.collectionF"
]
},
"status": "stopped",
"error_message": "string",
"docs_read": 0,
"docs_checked_pull": 0,
"docs_purged": 0,
"rejected_by_local": 0,
"last_seq_pull": "string",
"deltas_recv": 0,
"deltas_requested": 0,
"docs_written": 0,
"docs_checked_push": 0,
"docs_write_failures": 0,
"docs_write_conflicts": 0,
"rejected_by_remote": 0,
"last_seq_push": "string",
"deltas_sent": 0
}
],
"cluster": {"replication": {"replication_id": {"replication_id": "string",
"remote": "string",
"username": "string",
"password": "string",
"remote_username": "string",
"remote_password": "string",
"direction": "push",
"conflict_resolution_type": "default",
"custom_conflict_resolver": "none",
"purge_on_removal": false,
"enable_delta_sync": false,
"max_backoff_time": 5,
"initial_state": "running",
"continuous": false,
"filter": "sync_gateway/bychannel",
"query_params": ["string"
],
"adhoc": false,
"batch_size": 200,
"run_as": "string",
"collections_enabled": false,
"collections_local": ["scope1.collection1",
"scope1.collection3",
"scope1.collection6"
],
"collections_remote": ["scope1.collectionA",
null,
"scope1.collectionF"
],
"assigned_node": "string",
"target_state": "running"
}
},
"nodes": {"node_uuid": {"uuid": "string",
"host": "string"
}
}
}
},
"property2": {"seq": 0,
"server_uuid": "string",
"state": "Online",
"replication_status": [{"replication_id": "string",
"config": {"replication_id": "string",
"remote": "string",
"username": "string",
"password": "string",
"remote_username": "string",
"remote_password": "string",
"direction": "push",
"conflict_resolution_type": "default",
"custom_conflict_resolver": "none",
"purge_on_removal": false,
"enable_delta_sync": false,
"max_backoff_time": 5,
"initial_state": "running",
"continuous": false,
"filter": "sync_gateway/bychannel",
"query_params": ["string"
],
"adhoc": false,
"batch_size": 200,
"run_as": "string",
"collections_enabled": false,
"collections_local": ["scope1.collection1",
"scope1.collection3",
"scope1.collection6"
],
"collections_remote": ["scope1.collectionA",
null,
"scope1.collectionF"
]
},
"status": "stopped",
"error_message": "string",
"docs_read": 0,
"docs_checked_pull": 0,
"docs_purged": 0,
"rejected_by_local": 0,
"last_seq_pull": "string",
"deltas_recv": 0,
"deltas_requested": 0,
"docs_written": 0,
"docs_checked_push": 0,
"docs_write_failures": 0,
"docs_write_conflicts": 0,
"rejected_by_remote": 0,
"last_seq_push": "string",
"deltas_sent": 0
}
],
"cluster": {"replication": {"replication_id": {"replication_id": "string",
"remote": "string",
"username": "string",
"password": "string",
"remote_username": "string",
"remote_password": "string",
"direction": "push",
"conflict_resolution_type": "default",
"custom_conflict_resolver": "none",
"purge_on_removal": false,
"enable_delta_sync": false,
"max_backoff_time": 5,
"initial_state": "running",
"continuous": false,
"filter": "sync_gateway/bychannel",
"query_params": ["string"
],
"adhoc": false,
"batch_size": 200,
"run_as": "string",
"collections_enabled": false,
"collections_local": ["scope1.collection1",
"scope1.collection3",
"scope1.collection6"
],
"collections_remote": ["scope1.collectionA",
null,
"scope1.collectionF"
],
"assigned_node": "string",
"target_state": "running"
}
},
"nodes": {"node_uuid": {"uuid": "string",
"host": "string"
}
}
}
}
},
"version": "string"
}

Get the status of the Sync Gateway Collect Info

This will return the status of whether Sync Gateway Collect Info (sgcollect_info) is currently running or not.

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

Responses

Response samples

200

Content type

application/json

{"status": "stopped"
}

Start Sync Gateway Collect Info

This endpoint is used to start a Sync Gateway Collect Info (sgcollect_info) job so that Sync Gateway diagnostic data can be outputted to a file.

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

Request Body schema: application/json

sgcollect_info options

redact_level	string Default: "partial" Enum: "partial" "none" The redaction level to use for redacting the collected logs.
redact_salt	string The salt to use for the log redactions.
output_dir	string Default: "The configured path set in the startup config `logging.log_file_path`" The directory to output the collected logs zip file at. This overrides the configured default output directory configured in the startup config `logging.log_file_path`.
upload	boolean If set, upload the logs to Couchbase Support. A customer name must be set if this is set.
upload_host	string Default: "https://uploads.couchbase.com" The host to send the logs too.
upload_proxy	string The proxy to use while uploading the logs.
customer	string The customer name to use when uploading the logs.
ticket	string [ 1 .. 7 ] characters The Zendesk ticket number to use when uploading logs.

Responses

Request samples

Payload

Content type

application/json

{"redact_level": "partial",
"redact_salt": "string",
"output_dir": "The configured path set in the startup config `logging.log_file_path`",
"upload": true,
"upload_host": "https://uploads.couchbase.com",
"upload_proxy": "string",
"customer": "string",
"ticket": "string"
}

Response samples

200
400
500

Content type

application/json

{"status": "started"
}

Cancel the Sync Gateway Collect Info job

This endpoint is used to cancel a current Sync Gateway Collect Info (sgcollect_info) job that is running.

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

Responses

Response samples

200
400

Content type

application/json

{"status": "cancelled"
}

Run the post upgrade process on all databases

The post upgrade process involves removing obsolete design documents and indexes when they are no longer needed.

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

query Parameters

preview

string

Default: "false"

If set, a dry-run will be done to return what would be removed.

Responses

Response samples

200

Content type

application/json

{"post_upgrade_results": {"db1": {"removed_design_docs": ["string"
],
"removed_indexes": ["string"
]
},
"db2": {"removed_design_docs": ["string"
],
"removed_indexes": ["string"
]
}
},
"preview": true
}

Get server information

Returns information about the Sync Gateway node.

Responses

Response samples

200

Content type

application/json

{"ADMIN": true,
"couchdb": "Welcome",
"vendor": {"name": "Couchbase Sync Gateway",
"version": 3.1
},
"version": "Couchbase Sync Gateway/3.1.0(1;a765231) EE",
"persistent_config": true
}

Check if server online

Check if the server is online by checking the status code of response.

Responses

Check if API is available

Returns OK status if API is available.

Responses

Response samples

200

Content type

text/plain

OK

Check if API is available

Returns OK status if API is available.

Responses

Database Management

Create and manage Sync Gateway databases

Get resync status

This will retrieve the status of last resync operation (whether it is running or not) in the Sync Gateway cluster.

Required Sync Gateway RBAC roles:

Sync Gateway Architect

path Parameters

db

required

string

Example: db1

The name of the database to run the operation against.

Responses

Response samples

200
404

Content type

application/json

{"status": "running",
"start_time": "string",
"last_error": "string",
"docs_changed": 0,
"docs_processed": 0,
"collections_processing": {"scopeName": {"collection1": null,
"collection2": null
}
}
}

Start or stop Resync

This can be used to start or stop a resync operation. A resync operation will cause all documents in the keyspace to be reprocessed through the sync function.

Generally, a resync operation might be wanted when the sync function has been modified in such a way that the channel or access mappings for any existing documents would change as a result.

A resync operation cannot be run if the database is online. The database can be taken offline by calling the POST /{db}/_offline endpoint.

In a multi-node cluster, the resync operation must be run on only a single node. Therefore, users should bring other nodes offline before initiating this action. Undefined system behaviour will happen if running resync on more than 1 node.

The requireUser() and requireRole() calls in the sync function will always return true.

action=start - This is an asynchronous operation, and will start resync in the background.
action=stop - This will stop the currently running resync operation.

Required Sync Gateway RBAC roles:

Sync Gateway Architect

path Parameters

db

required

string

Example: db1

The name of the database to run the operation against.

query Parameters

action	string Default: "start" Enum: "start" "stop" This is whether to start a new resync job or stop an existing one.
regenerate_sequences	boolean Use this only when requested to do so by the Couchbase support team This request will regenerate the sequence numbers for each document processed. If scopes parameter is specified, the principal sequence documents will not have their sequences updated.
reset	boolean Default: false This forces a fresh resync run instead of trying to resume the previous resync operation

Request Body schema: application/json

	object (ResyncScopesMap) scope name with one or more collection names for which resync will be triggered
regenerate_sequences	boolean Default: false This can be used as an alternative to query param `regenerate_sequences`. If either query param or this is set to true, then the request will regenerate the sequence numbers for each document processed.

Responses

Request samples

Payload

Content type

application/json

{"scopes": {"scopeName": {"collection1": null,
"collection2": null
}
},
"regenerate_sequences": false
}

Response samples

200
503

Content type

application/json

{"status": "running",
"start_time": "string",
"last_error": "string",
"docs_changed": 0,
"docs_processed": 0,
"collections_processing": {"scopeName": {"collection1": null,
"collection2": null
}
}
}

Bring the database online

This will bring the database online so the Public and full Admin REST API requests can be served.

Bringing a database online will:

Close the database connection to the backing Couchbase Server bucket.
Reload the database configuration, and connect to the backing Couchbase Server bucket.
Re-establish access to the database from the Public REST API and accept all Admin API requests.

A specific delay before bringing the database online may be wanted to:

Make the database available for Couchbase Lite clients at a specific time.
Make the databases on several Sync Gateway instances available at the same time.

Required Sync Gateway RBAC roles:

Sync Gateway Architect

path Parameters

db

required

string

Example: db1

The name of the database to run the operation against.

Request Body schema: application/json

Add an optional delay to wait before bringing the database online

delay

integer

Default: 0

The amount of seconds to delay bringing the database online.

Responses

Request samples

Payload

Content type

application/json

{"delay": 0
}

Response samples

404
503

Content type

application/json

{"error": "not_found",
"reason": "no such database \"invalid-db\""
}

Take the database offline

This will take the database offline meaning actions can be taken without disrupting current operations ungracefully or having the restart the Sync Gateway instance.

This will not take the backing Couchbase Server bucket offline.

Taking a database offline that is in the progress of coming online will take the database offline after it comes online.

Taking the database offline will:

Close all active _changes feeds for the database.
Reject all access to the database via the Public REST API (returning a 503 Service Unavailable code).
Reject most Admin API requests (by returning a 503 Service Unavailable code). The only endpoints to be available are: the resync endpoints, the configuration endpoints, DELETE, GET, HEAD /{db}/, POST /{db}/_offline, and POST /{db}/_online.
Stops webhook event handlers.

Required Sync Gateway RBAC roles:

Sync Gateway Architect

path Parameters

db

required

string

Example: db1

The name of the database to run the operation against.

Responses

Response samples

404
503

Content type

application/json

{"error": "not_found",
"reason": "no such database \"invalid-db\""
}

Get a list of all the databases

This retrieves all the databases that are in the current Sync Gateway node. If verbose, returns bucket and state information for each database, otherwise returns names only.

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

query Parameters

verbose

boolean

Responses

Response samples

200

Content type

application/json

Example

All DBs

[ ]

Manage a compact operation

This allows a new compact operation to be done on the database, or to stop an existing running compact operation.

The type of compaction that is done depends on what the type query parameter is set to. The 2 options will:

tombstone - purge the JSON bodies of non-leaf revisions. This is known as database compaction. Database compaction is done periodically automatically by the system. JSON bodies of leaf nodes (conflicting branches) are not removed therefore it is important to resolve conflicts in order to re-claim disk space.
attachment - purge all unlinked/unused legacy (pre 3.0) attachments. If the previous attachment compact operation failed, this will attempt to restart the compact_id at the appropriate phase (if possible).

Both types can each have a maximum of 1 compact operation running at any one point. This means that an attachment compaction can be running at the same time as a tombstone compaction but not 2 tombstone compactions.

Required Sync Gateway RBAC roles:

Sync Gateway Architect

path Parameters

db

required

string

Example: db1

The name of the database to run the operation against.

query Parameters

type	string Default: "tombstone" Enum: "attachment" "tombstone" This is the type of compaction to use. The type must be either: `attachment` for cleaning up legacy (pre-3.0) attachments `tombstone` for purging the JSON bodies of non-leaf revisions.'
action	string Default: "start" Enum: "start" "stop" Defines whether the a compact operation is being started or stopped.
reset	boolean Attachment compaction only This forces a fresh compact start instead of trying to resume the previous failed compact operation.
dry_run	boolean Attachment compaction only This will run through all 3 stages of attachment compact but will not purge any attachments. This can be used to check how many attachments will be purged.'

Responses

Response samples

400
404
503

Content type

application/json

{"error": "string",
"reason": "string"
}

Get the status of the most recent compact operation

This will retrieve the current status of the most recent compact operation.

Required Sync Gateway RBAC roles:

Sync Gateway Architect

path Parameters

db

required

string

Example: db1

The name of the database to run the operation against.

query Parameters

type	string Default: "tombstone" Enum: "attachment" "tombstone" This is the type of compaction to use. The type must be either: `attachment` for cleaning up legacy (pre-3.0) attachments `tombstone` for purging the JSON bodies of non-leaf revisions.'

Responses

Response samples

200
400
404

Content type

application/json

{"status": "string",
"start_time": "string",
"last_error": "string",
"docs_purged": "string",
"marked_attachments": "string",
"purged_attachments": "string",
"compact_id": "string",
"phase": "string",
"dry_run": "mark"
}

Get database information

Retrieve information about the database.

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

path Parameters

db

required

string

Example: db1

The name of the database to run the operation against.

Responses

Response samples

200
404

Content type

application/json

{"db_name": "db",
"update_seq": 123456,
"committed_update_seq": 123456,
"instance_start_time": 1644600082279583,
"compact_running": true,
"purge_seq": 0,
"disk_format_version": 0,
"state": "Online",
"server_uuid": "995618a6a6cc9ac79731bd13240e19b5",
"init_in_progress": true
}

Remove a database

Removes a database from the Sync Gateway cluster

Note: If running in legacy mode, this will only delete the database from the current node.

Required Sync Gateway RBAC roles:

Sync Gateway Architect

path Parameters

db

required

string

Example: db1

The name of the database to run the operation against.

Responses

Response samples

200
404
500

Content type

application/json

{ }

Check if database exists

Check if a database exists by using the response status code.

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

path Parameters

db

required

string

Example: db1

The name of the database to run the operation against.

Responses

Response samples

404

Content type

application/json

{"error": "not_found",
"reason": "no such database \"invalid-db\""
}

Create a new Sync Gateway database

This is to create a new database for Sync Gateway.

The new database name will be the name specified in the URL, not what is specified in the request body database configuration.

If the bucket is not provided in the database configuration, Sync Gateway will attempt to find and use the database name as the bucket.

By default, the new database will be brought online immediately. This can be avoided by including "offline": true in the configuration in the request body.

Required Sync Gateway RBAC roles:

Sync Gateway Architect

path Parameters

db

required

string

Example: db1

The name of the database to run the operation against.

query Parameters

disable_oidc_validation

boolean

Default: false

If set, will not attempt to validate the configured OpenID Connect providers are reachable.

Request Body schema: application/json

The configuration to use for the new database

server	string This is the Couchbase Server address or addresses that the database connect to.
pool	string Deprecated Default: "default" This field is unsupported and ignored.
bucket	string Default: "The database name" The Couchbase Server backing bucket for the database.
username	string The username for authenticating to the server.
password	string The password for authenticating to the server.
certpath	string The cert path (public key) for X.509 bucket auth.
keypath	string The key path (private key) for X.509 bucket auth
cacertpath	string The root CA cert path for X.509 bucket authentication.
kv_tls_port	integer Default: 11207 The Memcached TLS port.
max_concurrent_query_ops	integer Default: 1000 The maximum amount of query operations that can be running at any one point.
	object <= 1 properties An object keyed by scope name containing config for the specific collection.
name	string The name of the database.
sync	string Default: "function(doc){channel(doc.channels);}" The Javascript function that newly created documents are ran through for the default scope and collection. If `scopes` parameter is set, this is ignored.
	object
	object
revs_limit	number >= 0 Default: "100 if conflict allowed and 50 if not" The maximum depth a document's revision tree can grow too. The minimum is `20` if conflicts are allowed and 0 if not. It is not recommended to go below `100` when conflicts are allowed.
import_docs	boolean If true, documents will be imported in to Sync Gateway from the bucket when requested. Documents will be ran through the set `import_filter` if any is set. The default value depends on the edition of Sync Gateway being used. If the edition is the Community Edition, then this will default to `false` or else in the Enterprise Edition, it will default to `true`. This can also be set to the string `continuous` which maps to true.
import_partitions	number Default: 16 This is an Enterprise Edition feature only This is how many import partitions should be used for import sharding. Partitions are distributed among all Sync Gateway nodes participating in import processing (`import_docs=true`), and each process a subset of the server's vbuckets. Each partition is processed by an independent function that runs simultaneously to others, so `import_partitions` can be used to tune concurrency based on the number of Sync Gateway nodes, and the number of cores per node.
import_filter	string This is the function that all imported documents in the default scope and collection are ran through in order to filter out what to import and what not to import. This allows you to control what is made available to Couchbase Mobile clients. If it is not set, then no documents are filtered when imported. `import_docs` must be true to make this field applicable. If `scopes` parameter is set, this is ignored.
import_backup_old_rev	boolean Default: false This controls whether import should attempt to create a temporary backup of the previous revision body (if available) when the document is modified in the bucket.
	object These are the settings for webhooks.
feed_type	string Deprecated Default: "DCP" Value: "DCP" The type of feed to use to communicate with Couchbase Server. This will use DCP regardless of specification.
allow_empty_password	boolean Default: false This controls whether users that are created can have an empty password or not.
	object
rev_cache_size	number Deprecated Deprecated, please use the database setting `cache.rev_cache.size` instead The maximum number of revisions to store in the revision cache.
offline	boolean Default: false Start the database in an offline state.
	object These are unsupported options and therefore it is not recommended to use them.
	object Configuration for Local JWT authentication.
	object Configuration for OpenID Connect authentication.
old_rev_expiry_seconds	number Default: 300 The number of seconds before old revisions are removed from the Couchbase Server bucket.
view_query_timeout_secs	integer Default: 75 The number of seconds before a view query should timeout.
local_doc_expiry_secs	integer Default: 7776000 The number of seconds before a `_local` document should expire.
enable_shared_bucket_access	boolean Default: true Whether to use extended attributes to store Sync Gateway document (`_sync`) metadata.
session_cookie_secure	boolean Override the session cookie `secure` flag. If set, the cookie will have the `secure` flag. This will default to `true` if startup config `api.https.tls_cert_path` is set otherwise it will default to `false`.
session_cookie_name	string This can be used to define a custom per-database session cookie name.
session_cookie_http_only	boolean Default: false Make all session cookies for the database set the `HttpOnly` flag so they are inaccessible to JavaScript.
allow_conflicts	boolean Deprecated Default: true This controls whether to allow conflicting document revisions.
num_index_replicas	number Default: 1 This is the number of Global Secondary Indexes (GSI) to use for core indexes.
use_views	boolean Default: false Force the use of views instead of GSI.
send_www_authenticate_header	boolean Default: true Controls whether to send a `WWW-Authenticate` header in `401 Unauthorized` HTTP responses.
disable_password_auth	boolean Default: false Whether to disable username/password authentication and only allow OIDC and guest access.
bucket_op_timeout_ms	number This is the amount of milliseconds should pass before a bucket operation times out. An error will be returned if the bucket operation times out saying: `operation timed out`.
slow_query_warning_threshold	number Default: 500 The amount of milliseconds a N1QL query should run before logging a warning.
	object Delta sync configuration settings. This is an Enterprise Edition feature only
compact_interval_days	number Default: 1 The interval between scheduled tombstone compaction runs (in days). This can be a floating point number. If set to 0, compaction will not run automatically.
sgreplicate_enabled	boolean Default: true Whether the node should accept assign replications (`true`) or not (`false`).
sgreplicate_websocket_heartbeat_secs	integer Default: 300 Use a custom heartbeat interval (in seconds) for websocket ping frames.
	object
serve_insecure_attachment_types	boolean Default: false If set, always serve attachments with the `Content-Type` header set to the type of the attachment. When serving an attachment, usually the `Content-Type` header is set to the type of the attachment but the `Content-Disposition` response header will be set instead if the content type is vulnerable to a phishing attack, causing the browser to download the file instead of display it. This option will override that behaviour and always set the `Content-Type` header.
query_pagination_limit	integer Default: 5000 The query limit to be used during pagination of large queries.
user_xattr_key	string The key to use for the user xattr that will be accessible from the sync function. IF empty, the feature will be disabled.
client_partition_window_secs	integer Default: 2592000 How long (in seconds) clients can remain offline for without losing replication metadata. Defaults to 30 days (in seconds)
	object (User) Properties associated with a user
javascript_timeout_secs	number Default: 60 The maximum number of seconds the sync, import filter, and custom conflict resolver JavaScript functions are allowed to run for before timing out. Set to 0 to allow the JS functions to run uncapped.
suspendable	boolean Default: false Set to true to allow the database to be suspended. Defaults to true when running in serverless mode otherwise defaults to false.
	object CORS configuration for this database; if present, overrides server's config.
	object Per-database logging configuration.

Responses

Request samples

Payload

Content type

application/json

{"server": "string",
"pool": "default",
"bucket": "The database name",
"username": "string",
"password": "string",
"certpath": "string",
"keypath": "string",
"cacertpath": "string",
"kv_tls_port": 11207,
"max_concurrent_query_ops": 1000,
"scopes": {"scopename": {"collections": {"collectionname1": {"sync": "function(doc){channel(\"collection name\");}",
"import_filter": "function(doc) { if (doc.type != 'mobile') { return false; } return true; }"
},
"collectionname2": {"sync": "function(doc){channel(\"collection name\");}",
"import_filter": "function(doc) { if (doc.type != 'mobile') { return false; } return true; }"
}
}
}
},
"name": "string",
"sync": "function(doc){channel(doc.channels);}",
"users": {"username1": {"name": "string",
"password": "string",
"admin_channels": ["string"
],
"collection_access": {"scopename1": {"collectionname1": {"admin_channels": ["string"
]
},
"collectionname2": {"admin_channels": ["string"
]
}
},
"scopename2": {"collectionname1": {"admin_channels": ["string"
]
},
"collectionname2": {"admin_channels": ["string"
]
}
}
},
"email": "string",
"disabled": true,
"admin_roles": ["string"
]
},
"username2": {"name": "string",
"password": "string",
"admin_channels": ["string"
],
"collection_access": {"scopename1": {"collectionname1": {"admin_channels": ["string"
]
},
"collectionname2": {"admin_channels": ["string"
]
}
},
"scopename2": {"collectionname1": {"admin_channels": ["string"
]
},
"collectionname2": {"admin_channels": ["string"
]
}
}
},
"email": "string",
"disabled": true,
"admin_roles": ["string"
]
}
},
"roles": {"rolename1": {"name": "string",
"admin_channels": ["string"
],
"collection_access": {"scopename1": {"collectionname1": {"admin_channels": ["string"
]
},
"collectionname2": {"admin_channels": ["string"
]
}
},
"scopename2": {"collectionname1": {"admin_channels": ["string"
]
},
"collectionname2": {"admin_channels": ["string"
]
}
}
}
},
"rolename2": {"name": "string",
"admin_channels": ["string"
],
"collection_access": {"scopename1": {"collectionname1": {"admin_channels": ["string"
]
},
"collectionname2": {"admin_channels": ["string"
]
}
},
"scopename2": {"collectionname1": {"admin_channels": ["string"
]
},
"collectionname2": {"admin_channels": ["string"
]
}
}
}
}
},
"revs_limit": "100 if conflict allowed and 50 if not",
"import_docs": true,
"import_partitions": 16,
"import_filter": "function(doc) { if (doc.type != 'mobile') { return false; } return true; }",
"import_backup_old_rev": false,
"event_handlers": {"max_processes": "string",
"wait_for_process": "string",
"document_changed": {"handler": "webhook",
"url": "string",
"filter": "string",
"timeout": 0,
"options": {"property1": null,
"property2": null
}
},
"db_state_changed": {"handler": "webhook",
"url": "string",
"filter": "string",
"timeout": 0,
"options": {"property1": null,
"property2": null
}
}
},
"feed_type": "DCP",
"allow_empty_password": false,
"cache": {"rev_cache": {"size": 5000,
"max_memory_count_mb": 0,
"shard_count": 16
},
"channel_cache": {"max_number": 50000,
"compact_high_watermark_pct": 80,
"compact_low_watermark_pct": 60,
"max_wait_pending": 5000,
"max_num_pending": 10000,
"max_wait_skipped": 3600000,
"enable_star_channel": true,
"max_length": 500,
"min_length": 50,
"expiry_seconds": 60,
"query_limit": 5000
},
"max_wait_pending": 0,
"max_wait_skipped": 0,
"enable_star_channel": true,
"channel_cache_max_length": 0,
"channel_cache_min_length": 0,
"channel_cache_expiry": 0,
"max_num_pending": 0
},
"rev_cache_size": 0,
"offline": false,
"unsupported": {"user_views": {"enabled": true
},
"oidc_test_provider": {"enabled": true
},
"api_endpoints": {"enable_couchbase_bucket_flush": true
},
"warning_thresholds": {"xattr_size_bytes": 0,
"channels_per_doc": 0,
"access_and_role_grants_per_doc": 0,
"channels_per_user": 0,
"channel_name_size": 0
},
"oidc_tls_skip_verify": true,
"sgr_tls_skip_verify": true,
"remote_config_tls_skip_verify": true,
"guest_read_only": true,
"force_api_forbidden_errors": true,
"dcp_read_buffer": 0,
"kv_buffer": 0
},
"local_jwt": {"providername1": {"issuer": "string",
"register": true,
"client_id": "string",
"algorithms": ["string"
],
"keys": [{"kty": "RSA",
"use": "sig",
"alg": "string",
"kid": "string",
"crv": "P-256",
"x": "string",
"y": "string",
"n": "string",
"e": "string"
}
],
"disable_session": true,
"user_prefix": "string",
"username_claim": "string",
"roles_claim": "string",
"channels_claim": "string"
},
"providername2": {"issuer": "string",
"register": true,
"client_id": "string",
"algorithms": ["string"
],
"keys": [{"kty": "RSA",
"use": "sig",
"alg": "string",
"kid": "string",
"crv": "P-256",
"x": "string",
"y": "string",
"n": "string",
"e": "string"
}
],
"disable_session": true,
"user_prefix": "string",
"username_claim": "string",
"roles_claim": "string",
"channels_claim": "string"
}
},
"oidc": {"providers": {"providername1": {"issuer": "string",
"register": true,
"client_id": "string",
"validation_key": "string",
"callback_url": "string",
"disable_session": true,
"scope": ["string"
],
"include_access": true,
"user_prefix": "string",
"discovery_url": "string",
"disable_cfg_validation": false,
"disable_callback_state": false,
"username_claim": "string",
"roles_claim": "string",
"channels_claim": "string",
"allow_unsigned_provider_tokens": true,
"IsDefault": true,
"Name": "string",
"InsecureSkipVerify": false
},
"providername2": {"issuer": "string",
"register": true,
"client_id": "string",
"validation_key": "string",
"callback_url": "string",
"disable_session": true,
"scope": ["string"
],
"include_access": true,
"user_prefix": "string",
"discovery_url": "string",
"disable_cfg_validation": false,
"disable_callback_state": false,
"username_claim": "string",
"roles_claim": "string",
"channels_claim": "string",
"allow_unsigned_provider_tokens": true,
"IsDefault": true,
"Name": "string",
"InsecureSkipVerify": false
}
},
"default_provider": "string"
},
"old_rev_expiry_seconds": 300,
"view_query_timeout_secs": 75,
"local_doc_expiry_secs": 7776000,
"enable_shared_bucket_access": true,
"session_cookie_secure": true,
"session_cookie_name": "string",
"session_cookie_http_only": false,
"allow_conflicts": true,
"num_index_replicas": 1,
"use_views": false,
"send_www_authenticate_header": true,
"disable_password_auth": false,
"bucket_op_timeout_ms": 0,
"slow_query_warning_threshold": 500,
"delta_sync": {"enabled": false,
"rev_max_age_seconds": 86400
},
"compact_interval_days": 1,
"sgreplicate_enabled": true,
"sgreplicate_websocket_heartbeat_secs": 300,
"replications": {"replication_id": {"replication_id": "string",
"remote": "string",
"username": "string",
"password": "string",
"remote_username": "string",
"remote_password": "string",
"direction": "push",
"conflict_resolution_type": "default",
"custom_conflict_resolver": "none",
"purge_on_removal": false,
"enable_delta_sync": false,
"max_backoff_time": 5,
"initial_state": "running",
"continuous": false,
"filter": "sync_gateway/bychannel",
"query_params": ["string"
],
"adhoc": false,
"batch_size": 200,
"run_as": "string",
"collections_enabled": false,
"collections_local": ["scope1.collection1",
"scope1.collection3",
"scope1.collection6"
],
"collections_remote": ["scope1.collectionA",
null,
"scope1.collectionF"
]
}
},
"serve_insecure_attachment_types": false,
"query_pagination_limit": 5000,
"user_xattr_key": "string",
"client_partition_window_secs": 2592000,
"guest": {"name": "string",
"password": "string",
"admin_channels": ["string"
],
"collection_access": {"scopename1": {"collectionname1": {"admin_channels": ["string"
]
},
"collectionname2": {"admin_channels": ["string"
]
}
},
"scopename2": {"collectionname1": {"admin_channels": ["string"
]
},
"collectionname2": {"admin_channels": ["string"
]
}
}
},
"email": "string",
"disabled": true,
"admin_roles": ["string"
]
},
"javascript_timeout_secs": 60,
"suspendable": false,
"cors": {"origin": ["string"
],
"login_origin": ["string"
],
"headers": ["string"
]
},
"logging": {"console": {"log_level": "debug",
"log_keys": ["CRUD",
"HTTP",
"Query"
]
},
"audit": {"enabled": false,
"enabled_events": [[1234,
5678
]
],
"disabled_users": [{"domain": "cbs",
"name": "string"
}
],
"disabled_roles": [{"domain": "cbs",
"name": "string"
}
]
}
}
}

Response samples

400
403
409
412
500

Content type

application/json

{"error": "string",
"reason": "string"
}

Get changes list

This request retrieves a sorted list of changes made to documents in the database, in time order of application. Each document appears at most once, ordered by its most recent change, regardless of how many times it has been changed.

This request can be used to listen for update and modifications to the database for post processing or synchronization. A continuously connected changes feed is a reasonable approach for generating a real-time log for most applications.

Required Sync Gateway RBAC roles:

Sync Gateway Application
Sync Gateway Application Read Only

path Parameters

keyspace

required

string

Examples:

db1 - Default scope and collection
db1.collection1 - Named collection within the default scope
db1.scope1.collection1 - Fully-qualified scope and collection

The keyspace to run the operation against.

A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection.

query Parameters

limit	integer Maximum number of changes to return.
since	string Starts the results from the change immediately after the given sequence ID. Sequence IDs should be considered opaque; they come from the last_seq property of a prior response.
style	string Default: "main_only" Enum: "main_only" "all_docs" Controls whether to return the current winning revision (`main_only`) or all the leaf revision including conflicts and deleted former conflicts (`all_docs`).
active_only	boolean Default: "false" Set true to exclude deleted documents and notifications for documents the user no longer has access to from the changes feed.
include_docs	boolean Include the body associated with each document.
revocations	boolean If true, revocation messages will be sent on the changes feed.
filter	string Enum: "sync_gateway/bychannel" "_doc_ids" Set a filter to either filter by channels or document IDs.
channels	string A comma-separated list of channel names to filter the response to only the channels specified. To use this option, the `filter` query option must be set to `sync_gateway/bychannels`.
doc_ids	Array of strings A valid JSON array of document IDs to filter the documents in the response to only the documents specified. To use this option, the `filter` query option must be set to `_doc_ids` and the `feed` parameter must be `normal`. Also accepts a comma separated list of document IDs instead.
heartbeat	integer >= 25000 Default: 0 The interval (in milliseconds) to send an empty line (CRLF) in the response. This is to help prevent gateways from deciding the socket is idle and therefore closing it. This is only applicable to `feed=longpoll` or `feed=continuous`. This will override any timeouts to keep the feed alive indefinitely. Setting to 0 results in no heartbeat. The maximum heartbeat can be set in the server replication configuration.
timeout	integer [ 0 .. 900000 ] Default: 300000 This is the maximum period (in milliseconds) to wait for a change before the response is sent, even if there are no results. This is only applicable for `feed=longpoll` or `feed=continuous` changes feeds. Setting to 0 results in no timeout.
feed	string Default: "normal" Enum: "normal" "longpoll" "continuous" "websocket" The type of changes feed to use.
request_plus	boolean Default: "false" When true, ensures all valid documents written prior to the request being issued are included in the response. This is only applicable for non-continuous feeds.

Responses

Response samples

200
400
404

Content type

application/json

{"results": [{"seq": 0,
"id": "string",
"changes": [{"rev": "string"
}
]
}
],
"last_seq": "string"
}

Get changes list

This request retrieves a sorted list of changes made to documents in the database, in time order of application. Each document appears at most once, ordered by its most recent change, regardless of how many times it has been changed.

This request can be used to listen for update and modifications to the database for post processing or synchronization. A continuously connected changes feed is a reasonable approach for generating a real-time log for most applications.

Required Sync Gateway RBAC roles:

Sync Gateway Application
Sync Gateway Application Read Only

path Parameters

keyspace

required

string

Examples:

db1 - Default scope and collection
db1.collection1 - Named collection within the default scope
db1.scope1.collection1 - Fully-qualified scope and collection

The keyspace to run the operation against.

A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection.

Request Body schema: application/json

limit	string Maximum number of changes to return.
style	string Controls whether to return the current winning revision (`main_only`) or all the leaf revision including conflicts and deleted former conflicts (`all_docs`).
active_only	string Set true to exclude deleted documents and notifications for documents the user no longer has access to from the changes feed.
include_docs	string Include the body associated with each document.
revocations	string If true, revocation messages will be sent on the changes feed.
filter	string Set a filter to either filter by channels or document IDs.
channels	string A comma-separated list of channel names to filter the response to only the channels specified. To use this option, the `filter` query option must be set to `sync_gateway/bychannels`.
doc_ids	string A valid JSON array of document IDs to filter the documents in the response to only the documents specified. To use this option, the `filter` query option must be set to `_doc_ids` and the `feed` parameter must be `normal`.
heartbeat	string The interval (in milliseconds) to send an empty line (CRLF) in the response. This is to help prevent gateways from deciding the socket is idle and therefore closing it. This is only applicable to `feed=longpoll` or `feed=continuous`. This will override any timeouts to keep the feed alive indefinitely. Setting to 0 results in no heartbeat. The maximum heartbeat can be set in the server replication configuration.
timeout	string This is the maximum period (in milliseconds) to wait for a change before the response is sent, even if there are no results. This is only applicable for `feed=longpoll` or `feed=continuous` changes feeds. Setting to 0 results in no timeout.
feed	string The type of changes feed to use.
request_plus	string When true, ensures all valid documents written prior to the request being issued are included in the response. This is only applicable for non-continuous feeds.

Responses

Request samples

Payload

Content type

application/json

{"limit": "string",
"style": "string",
"active_only": "string",
"include_docs": "string",
"revocations": "string",
"filter": "string",
"channels": "string",
"doc_ids": "string",
"heartbeat": "string",
"timeout": "string",
"feed": "string",
"request_plus": "string"
}

Response samples

200
400
404

Content type

application/json

{"results": [{"seq": 0,
"id": "string",
"changes": [{"rev": "string"
}
]
}
],
"last_seq": "string"
}

/{db}/_changes

Required Sync Gateway RBAC roles:

Sync Gateway Application
Sync Gateway Application Read Only

path Parameters

keyspace

required

string

Examples:

db1 - Default scope and collection
db1.collection1 - Named collection within the default scope
db1.scope1.collection1 - Fully-qualified scope and collection

The keyspace to run the operation against.

A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection.

Responses

/{db}/_ensure_full_commit

This endpoint is non-functional but is present for CouchDB compatibility.

Required Sync Gateway RBAC roles:

Sync Gateway Application
Sync Gateway Application Read Only

path Parameters

db

required

string

Example: db1

The name of the database to run the operation against.

Responses

Response samples

201

Content type

application/json

{"instance_start_time": 1644600082279583,
"ok": true
}

Compare revisions to what is in the database

Takes a set of document IDs, each with a set of revision IDs. For each document, an array of unknown revisions are returned with an array of known revisions that may be recent ancestors.

Required Sync Gateway RBAC roles:

Sync Gateway Application

path Parameters

keyspace

required

string

Examples:

db1 - Default scope and collection
db1.collection1 - Named collection within the default scope
db1.scope1.collection1 - Fully-qualified scope and collection

The keyspace to run the operation against.

A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection.

Request Body schema: application/json

docid

Array of strings

The document ID with an array of revisions to use for the comparison.

Responses

Request samples

Payload

Content type

application/json

{"docid": ["string"
]
}

Response samples

200
404

Content type

application/json

{"docid": {"missing": ["string"
],
"possible_ancestors": ["string"
]
}
}

Database Configuration

Configure Sync Gateway databases

Get database configuration

Retrieve the full configuration for the database specified.

Required Sync Gateway RBAC roles:

Sync Gateway Architect

path Parameters

db

required

string

Example: db1

The name of the database to run the operation against.

query Parameters

redact	boolean Deprecated Default: "true" No longer supported field.
include_javascript	boolean Default: true Include the fields that have Javascript functions in the response. E.g. sync function, import filter, and event handlers.
include_runtime	boolean Default: false Whether to include the values set at runtime, and default values.
refresh_config	boolean Default: false Forces the configuration to be reloaded on the Sync Gateway node.

Responses

Response samples

200
404

Content type

application/json

{"server": "string",
"pool": "default",
"bucket": "The database name",
"username": "string",
"password": "string",
"certpath": "string",
"keypath": "string",
"cacertpath": "string",
"kv_tls_port": 11207,
"max_concurrent_query_ops": 1000,
"scopes": {"scopename": {"collections": {"collectionname1": {"sync": "function(doc){channel(\"collection name\");}",
"import_filter": "function(doc) { if (doc.type != 'mobile') { return false; } return true; }"
},
"collectionname2": {"sync": "function(doc){channel(\"collection name\");}",
"import_filter": "function(doc) { if (doc.type != 'mobile') { return false; } return true; }"
}
}
}
},
"name": "string",
"sync": "function(doc){channel(doc.channels);}",
"users": {"username1": {"name": "string",
"password": "string",
"admin_channels": ["string"
],
"all_channels": ["string"
],
"collection_access": {"scopename1": {"collectionname1": {"admin_channels": ["string"
],
"all_channels": ["string"
],
"jwt_channels": ["string"
],
"jwt_last_updated": "2019-08-24T14:15:22Z"
},
"collectionname2": {"admin_channels": ["string"
],
"all_channels": ["string"
],
"jwt_channels": ["string"
],
"jwt_last_updated": "2019-08-24T14:15:22Z"
}
},
"scopename2": {"collectionname1": {"admin_channels": ["string"
],
"all_channels": ["string"
],
"jwt_channels": ["string"
],
"jwt_last_updated": "2019-08-24T14:15:22Z"
},
"collectionname2": {"admin_channels": ["string"
],
"all_channels": ["string"
],
"jwt_channels": ["string"
],
"jwt_last_updated": "2019-08-24T14:15:22Z"
}
}
},
"email": "string",
"disabled": true,
"admin_roles": ["string"
],
"roles": ["string"
],
"jwt_roles": ["string"
],
"jwt_channels": ["string"
],
"jwt_issuer": "string",
"jwt_last_updated": "2019-08-24T14:15:22Z"
},
"username2": {"name": "string",
"password": "string",
"admin_channels": ["string"
],
"all_channels": ["string"
],
"collection_access": {"scopename1": {"collectionname1": {"admin_channels": ["string"
],
"all_channels": ["string"
],
"jwt_channels": ["string"
],
"jwt_last_updated": "2019-08-24T14:15:22Z"
},
"collectionname2": {"admin_channels": ["string"
],
"all_channels": ["string"
],
"jwt_channels": ["string"
],
"jwt_last_updated": "2019-08-24T14:15:22Z"
}
},
"scopename2": {"collectionname1": {"admin_channels": ["string"
],
"all_channels": ["string"
],
"jwt_channels": ["string"
],
"jwt_last_updated": "2019-08-24T14:15:22Z"
},
"collectionname2": {"admin_channels": ["string"
],
"all_channels": ["string"
],
"jwt_channels": ["string"
],
"jwt_last_updated": "2019-08-24T14:15:22Z"
}
}
},
"email": "string",
"disabled": true,
"admin_roles": ["string"
],
"roles": ["string"
],
"jwt_roles": ["string"
],
"jwt_channels": ["string"
],
"jwt_issuer": "string",
"jwt_last_updated": "2019-08-24T14:15:22Z"
}
},
"roles": {"rolename1": {"name": "string",
"admin_channels": ["string"
],
"all_channels": ["string"
],
"collection_access": {"scopename1": {"collectionname1": {"admin_channels": ["string"
],
"all_channels": ["string"
],
"jwt_channels": ["string"
],
"jwt_last_updated": "2019-08-24T14:15:22Z"
},
"collectionname2": {"admin_channels": ["string"
],
"all_channels": ["string"
],
"jwt_channels": ["string"
],
"jwt_last_updated": "2019-08-24T14:15:22Z"
}
},
"scopename2": {"collectionname1": {"admin_channels": ["string"
],
"all_channels": ["string"
],
"jwt_channels": ["string"
],
"jwt_last_updated": "2019-08-24T14:15:22Z"
},
"collectionname2": {"admin_channels": ["string"
],
"all_channels": ["string"
],
"jwt_channels": ["string"
],
"jwt_last_updated": "2019-08-24T14:15:22Z"
}
}
}
},
"rolename2": {"name": "string",
"admin_channels": ["string"
],
"all_channels": ["string"
],
"collection_access": {"scopename1": {"collectionname1": {"admin_channels": ["string"
],
"all_channels": ["string"
],
"jwt_channels": ["string"
],
"jwt_last_updated": "2019-08-24T14:15:22Z"
},
"collectionname2": {"admin_channels": ["string"
],
"all_channels": ["string"
],
"jwt_channels": ["string"
],
"jwt_last_updated": "2019-08-24T14:15:22Z"
}
},
"scopename2": {"collectionname1": {"admin_channels": ["string"
],
"all_channels": ["string"
],
"jwt_channels": ["string"
],
"jwt_last_updated": "2019-08-24T14:15:22Z"
},
"collectionname2": {"admin_channels": ["string"
],
"all_channels": ["string"
],
"jwt_channels": ["string"
],
"jwt_last_updated": "2019-08-24T14:15:22Z"
}
}
}
}
},
"revs_limit": "100 if conflict allowed and 50 if not",
"import_docs": true,
"import_partitions": 16,
"import_filter": "function(doc) { if (doc.type != 'mobile') { return false; } return true; }",
"import_backup_old_rev": false,
"event_handlers": {"max_processes": "string",
"wait_for_process": "string",
"document_changed": {"handler": "webhook",
"url": "string",
"filter": "string",
"timeout": 0,
"options": {"property1": null,
"property2": null
}
},
"db_state_changed": {"handler": "webhook",
"url": "string",
"filter": "string",
"timeout": 0,
"options": {"property1": null,
"property2": null
}
}
},
"feed_type": "DCP",
"allow_empty_password": false,
"cache": {"rev_cache": {"size": 5000,
"max_memory_count_mb": 0,
"shard_count": 16
},
"channel_cache": {"max_number": 50000,
"compact_high_watermark_pct": 80,
"compact_low_watermark_pct": 60,
"max_wait_pending": 5000,
"max_num_pending": 10000,
"max_wait_skipped": 3600000,
"enable_star_channel": true,
"max_length": 500,
"min_length": 50,
"expiry_seconds": 60,
"query_limit": 5000
},
"max_wait_pending": 0,
"max_wait_skipped": 0,
"enable_star_channel": true,
"channel_cache_max_length": 0,
"channel_cache_min_length": 0,
"channel_cache_expiry": 0,
"max_num_pending": 0
},
"rev_cache_size": 0,
"offline": false,
"unsupported": {"user_views": {"enabled": true
},
"oidc_test_provider": {"enabled": true
},
"api_endpoints": {"enable_couchbase_bucket_flush": true
},
"warning_thresholds": {"xattr_size_bytes": 0,
"channels_per_doc": 0,
"access_and_role_grants_per_doc": 0,
"channels_per_user": 0,
"channel_name_size": 0
},
"oidc_tls_skip_verify": true,
"sgr_tls_skip_verify": true,
"remote_config_tls_skip_verify": true,
"guest_read_only": true,
"force_api_forbidden_errors": true,
"dcp_read_buffer": 0,
"kv_buffer": 0
},
"local_jwt": {"providername1": {"issuer": "string",
"register": true,
"client_id": "string",
"algorithms": ["string"
],
"keys": [{"kty": "RSA",
"use": "sig",
"alg": "string",
"kid": "string",
"crv": "P-256",
"x": "string",
"y": "string",
"n": "string",
"e": "string"
}
],
"disable_session": true,
"user_prefix": "string",
"username_claim": "string",
"roles_claim": "string",
"channels_claim": "string"
},
"providername2": {"issuer": "string",
"register": true,
"client_id": "string",
"algorithms": ["string"
],
"keys": [{"kty": "RSA",
"use": "sig",
"alg": "string",
"kid": "string",
"crv": "P-256",
"x": "string",
"y": "string",
"n": "string",
"e": "string"
}
],
"disable_session": true,
"user_prefix": "string",
"username_claim": "string",
"roles_claim": "string",
"channels_claim": "string"
}
},
"oidc": {"providers": {"providername1": {"issuer": "string",
"register": true,
"client_id": "string",
"validation_key": "string",
"callback_url": "string",
"disable_session": true,
"scope": ["string"
],
"include_access": true,
"user_prefix": "string",
"discovery_url": "string",
"disable_cfg_validation": false,
"disable_callback_state": false,
"username_claim": "string",
"roles_claim": "string",
"channels_claim": "string",
"allow_unsigned_provider_tokens": true,
"IsDefault": true,
"Name": "string",
"InsecureSkipVerify": false
},
"providername2": {"issuer": "string",
"register": true,
"client_id": "string",
"validation_key": "string",
"callback_url": "string",
"disable_session": true,
"scope": ["string"
],
"include_access": true,
"user_prefix": "string",
"discovery_url": "string",
"disable_cfg_validation": false,
"disable_callback_state": false,
"username_claim": "string",
"roles_claim": "string",
"channels_claim": "string",
"allow_unsigned_provider_tokens": true,
"IsDefault": true,
"Name": "string",
"InsecureSkipVerify": false
}
},
"default_provider": "string"
},
"old_rev_expiry_seconds": 300,
"view_query_timeout_secs": 75,
"local_doc_expiry_secs": 7776000,
"enable_shared_bucket_access": true,
"session_cookie_secure": true,
"session_cookie_name": "string",
"session_cookie_http_only": false,
"allow_conflicts": true,
"num_index_replicas": 1,
"use_views": false,
"send_www_authenticate_header": true,
"disable_password_auth": false,
"bucket_op_timeout_ms": 0,
"slow_query_warning_threshold": 500,
"delta_sync": {"enabled": false,
"rev_max_age_seconds": 86400
},
"compact_interval_days": 1,
"sgreplicate_enabled": true,
"sgreplicate_websocket_heartbeat_secs": 300,
"replications": {"replication_id": {"replication_id": "string",
"remote": "string",
"username": "string",
"password": "string",
"remote_username": "string",
"remote_password": "string",
"direction": "push",
"conflict_resolution_type": "default",
"custom_conflict_resolver": "none",
"purge_on_removal": false,
"enable_delta_sync": false,
"max_backoff_time": 5,
"initial_state": "running",
"continuous": false,
"filter": "sync_gateway/bychannel",
"query_params": ["string"
],
"adhoc": false,
"batch_size": 200,
"run_as": "string",
"collections_enabled": false,
"collections_local": ["scope1.collection1",
"scope1.collection3",
"scope1.collection6"
],
"collections_remote": ["scope1.collectionA",
null,
"scope1.collectionF"
]
}
},
"serve_insecure_attachment_types": false,
"query_pagination_limit": 5000,
"user_xattr_key": "string",
"client_partition_window_secs": 2592000,
"guest": {"name": "string",
"password": "string",
"admin_channels": ["string"
],
"all_channels": ["string"
],
"collection_access": {"scopename1": {"collectionname1": {"admin_channels": ["string"
],
"all_channels": ["string"
],
"jwt_channels": ["string"
],
"jwt_last_updated": "2019-08-24T14:15:22Z"
},
"collectionname2": {"admin_channels": ["string"
],
"all_channels": ["string"
],
"jwt_channels": ["string"
],
"jwt_last_updated": "2019-08-24T14:15:22Z"
}
},
"scopename2": {"collectionname1": {"admin_channels": ["string"
],
"all_channels": ["string"
],
"jwt_channels": ["string"
],
"jwt_last_updated": "2019-08-24T14:15:22Z"
},
"collectionname2": {"admin_channels": ["string"
],
"all_channels": ["string"
],
"jwt_channels": ["string"
],
"jwt_last_updated": "2019-08-24T14:15:22Z"
}
}
},
"email": "string",
"disabled": true,
"admin_roles": ["string"
],
"roles": ["string"
],
"jwt_roles": ["string"
],
"jwt_channels": ["string"
],
"jwt_issuer": "string",
"jwt_last_updated": "2019-08-24T14:15:22Z"
},
"javascript_timeout_secs": 60,
"suspendable": false,
"cors": {"origin": ["string"
],
"login_origin": ["string"
],
"headers": ["string"
]
},
"logging": {"console": {"log_level": "debug",
"log_keys": ["CRUD",
"HTTP",
"Query"
]
},
"audit": {"enabled": false,
"enabled_events": [[1234,
5678
]
],
"disabled_users": [{"domain": "cbs",
"name": "string"
}
],
"disabled_roles": [{"domain": "cbs",
"name": "string"
}
]
}
}
}

Replace database configuration

Replaces the database configuration with the one sent in the request.

The bucket and database name cannot be changed. If these need to be changed, the database will need to be deleted then recreated with the new settings.

Required Sync Gateway RBAC roles:

Sync Gateway Architect
Sync Gateway Application

path Parameters

db

required

string

Example: db1

The name of the database to run the operation against.

query Parameters

disable_oidc_validation

boolean

Default: false

If set, will not attempt to validate the configured OpenID Connect providers are reachable.

header Parameters

If-Match

string

If set to a configuration's Etag value, enables optimistic concurrency control for the request. Returns HTTP 412 if another update happened underneath this one.

Request Body schema: application/json

The new database configuration to use

server	string This is the Couchbase Server address or addresses that the database connect to.
pool	string Deprecated Default: "default" This field is unsupported and ignored.
bucket	string Default: "The database name" The Couchbase Server backing bucket for the database.
username	string The username for authenticating to the server.
password	string The password for authenticating to the server.
certpath	string The cert path (public key) for X.509 bucket auth.
keypath	string The key path (private key) for X.509 bucket auth
cacertpath	string The root CA cert path for X.509 bucket authentication.
kv_tls_port	integer Default: 11207 The Memcached TLS port.
max_concurrent_query_ops	integer Default: 1000 The maximum amount of query operations that can be running at any one point.
	object <= 1 properties An object keyed by scope name containing config for the specific collection.
name	string The name of the database.
sync	string Default: "function(doc){channel(doc.channels);}" The Javascript function that newly created documents are ran through for the default scope and collection. If `scopes` parameter is set, this is ignored.
	object
	object
revs_limit	number >= 0 Default: "100 if conflict allowed and 50 if not" The maximum depth a document's revision tree can grow too. The minimum is `20` if conflicts are allowed and 0 if not. It is not recommended to go below `100` when conflicts are allowed.
import_docs	boolean If true, documents will be imported in to Sync Gateway from the bucket when requested. Documents will be ran through the set `import_filter` if any is set. The default value depends on the edition of Sync Gateway being used. If the edition is the Community Edition, then this will default to `false` or else in the Enterprise Edition, it will default to `true`. This can also be set to the string `continuous` which maps to true.
import_partitions	number Default: 16 This is an Enterprise Edition feature only This is how many import partitions should be used for import sharding. Partitions are distributed among all Sync Gateway nodes participating in import processing (`import_docs=true`), and each process a subset of the server's vbuckets. Each partition is processed by an independent function that runs simultaneously to others, so `import_partitions` can be used to tune concurrency based on the number of Sync Gateway nodes, and the number of cores per node.
import_filter	string This is the function that all imported documents in the default scope and collection are ran through in order to filter out what to import and what not to import. This allows you to control what is made available to Couchbase Mobile clients. If it is not set, then no documents are filtered when imported. `import_docs` must be true to make this field applicable. If `scopes` parameter is set, this is ignored.
import_backup_old_rev	boolean Default: false This controls whether import should attempt to create a temporary backup of the previous revision body (if available) when the document is modified in the bucket.
	object These are the settings for webhooks.
feed_type	string Deprecated Default: "DCP" Value: "DCP" The type of feed to use to communicate with Couchbase Server. This will use DCP regardless of specification.
allow_empty_password	boolean Default: false This controls whether users that are created can have an empty password or not.
	object
rev_cache_size	number Deprecated Deprecated, please use the database setting `cache.rev_cache.size` instead The maximum number of revisions to store in the revision cache.
offline	boolean Default: false Start the database in an offline state.
	object These are unsupported options and therefore it is not recommended to use them.
	object Configuration for Local JWT authentication.
	object Configuration for OpenID Connect authentication.
old_rev_expiry_seconds	number Default: 300 The number of seconds before old revisions are removed from the Couchbase Server bucket.
view_query_timeout_secs	integer Default: 75 The number of seconds before a view query should timeout.
local_doc_expiry_secs	integer Default: 7776000 The number of seconds before a `_local` document should expire.
enable_shared_bucket_access	boolean Default: true Whether to use extended attributes to store Sync Gateway document (`_sync`) metadata.
session_cookie_secure	boolean Override the session cookie `secure` flag. If set, the cookie will have the `secure` flag. This will default to `true` if startup config `api.https.tls_cert_path` is set otherwise it will default to `false`.
session_cookie_name	string This can be used to define a custom per-database session cookie name.
session_cookie_http_only	boolean Default: false Make all session cookies for the database set the `HttpOnly` flag so they are inaccessible to JavaScript.
allow_conflicts	boolean Deprecated Default: true This controls whether to allow conflicting document revisions.
num_index_replicas	number Default: 1 This is the number of Global Secondary Indexes (GSI) to use for core indexes.
use_views	boolean Default: false Force the use of views instead of GSI.
send_www_authenticate_header	boolean Default: true Controls whether to send a `WWW-Authenticate` header in `401 Unauthorized` HTTP responses.
disable_password_auth	boolean Default: false Whether to disable username/password authentication and only allow OIDC and guest access.
bucket_op_timeout_ms	number This is the amount of milliseconds should pass before a bucket operation times out. An error will be returned if the bucket operation times out saying: `operation timed out`.
slow_query_warning_threshold	number Default: 500 The amount of milliseconds a N1QL query should run before logging a warning.
	object Delta sync configuration settings. This is an Enterprise Edition feature only
compact_interval_days	number Default: 1 The interval between scheduled tombstone compaction runs (in days). This can be a floating point number. If set to 0, compaction will not run automatically.
sgreplicate_enabled	boolean Default: true Whether the node should accept assign replications (`true`) or not (`false`).
sgreplicate_websocket_heartbeat_secs	integer Default: 300 Use a custom heartbeat interval (in seconds) for websocket ping frames.
	object
serve_insecure_attachment_types	boolean Default: false If set, always serve attachments with the `Content-Type` header set to the type of the attachment. When serving an attachment, usually the `Content-Type` header is set to the type of the attachment but the `Content-Disposition` response header will be set instead if the content type is vulnerable to a phishing attack, causing the browser to download the file instead of display it. This option will override that behaviour and always set the `Content-Type` header.
query_pagination_limit	integer Default: 5000 The query limit to be used during pagination of large queries.
user_xattr_key	string The key to use for the user xattr that will be accessible from the sync function. IF empty, the feature will be disabled.
client_partition_window_secs	integer Default: 2592000 How long (in seconds) clients can remain offline for without losing replication metadata. Defaults to 30 days (in seconds)
	object (User) Properties associated with a user
javascript_timeout_secs	number Default: 60 The maximum number of seconds the sync, import filter, and custom conflict resolver JavaScript functions are allowed to run for before timing out. Set to 0 to allow the JS functions to run uncapped.
suspendable	boolean Default: false Set to true to allow the database to be suspended. Defaults to true when running in serverless mode otherwise defaults to false.
	object CORS configuration for this database; if present, overrides server's config.
	object Per-database logging configuration.

Responses

Request samples

Payload

Content type

application/json

{"server": "string",
"pool": "default",
"bucket": "The database name",
"username": "string",
"password": "string",
"certpath": "string",
"keypath": "string",
"cacertpath": "string",
"kv_tls_port": 11207,
"max_concurrent_query_ops": 1000,
"scopes": {"scopename": {"collections": {"collectionname1": {"sync": "function(doc){channel(\"collection name\");}",
"import_filter": "function(doc) { if (doc.type != 'mobile') { return false; } return true; }"
},
"collectionname2": {"sync": "function(doc){channel(\"collection name\");}",
"import_filter": "function(doc) { if (doc.type != 'mobile') { return false; } return true; }"
}
}
}
},
"name": "string",
"sync": "function(doc){channel(doc.channels);}",
"users": {"username1": {"name": "string",
"password": "string",
"admin_channels": ["string"
],
"collection_access": {"scopename1": {"collectionname1": {"admin_channels": ["string"
]
},
"collectionname2": {"admin_channels": ["string"
]
}
},
"scopename2": {"collectionname1": {"admin_channels": ["string"
]
},
"collectionname2": {"admin_channels": ["string"
]
}
}
},
"email": "string",
"disabled": true,
"admin_roles": ["string"
]
},
"username2": {"name": "string",
"password": "string",
"admin_channels": ["string"
],
"collection_access": {"scopename1": {"collectionname1": {"admin_channels": ["string"
]
},
"collectionname2": {"admin_channels": ["string"
]
}
},
"scopename2": {"collectionname1": {"admin_channels": ["string"
]
},
"collectionname2": {"admin_channels": ["string"
]
}
}
},
"email": "string",
"disabled": true,
"admin_roles": ["string"
]
}
},
"roles": {"rolename1": {"name": "string",
"admin_channels": ["string"
],
"collection_access": {"scopename1": {"collectionname1": {"admin_channels": ["string"
]
},
"collectionname2": {"admin_channels": ["string"
]
}
},
"scopename2": {"collectionname1": {"admin_channels": ["string"
]
},
"collectionname2": {"admin_channels": ["string"
]
}
}
}
},
"rolename2": {"name": "string",
"admin_channels": ["string"
],
"collection_access": {"scopename1": {"collectionname1": {"admin_channels": ["string"
]
},
"collectionname2": {"admin_channels": ["string"
]
}
},
"scopename2": {"collectionname1": {"admin_channels": ["string"
]
},
"collectionname2": {"admin_channels": ["string"
]
}
}
}
}
},
"revs_limit": "100 if conflict allowed and 50 if not",
"import_docs": true,
"import_partitions": 16,
"import_filter": "function(doc) { if (doc.type != 'mobile') { return false; } return true; }",
"import_backup_old_rev": false,
"event_handlers": {"max_processes": "string",
"wait_for_process": "string",
"document_changed": {"handler": "webhook",
"url": "string",
"filter": "string",
"timeout": 0,
"options": {"property1": null,
"property2": null
}
},
"db_state_changed": {"handler": "webhook",
"url": "string",
"filter": "string",
"timeout": 0,
"options": {"property1": null,
"property2": null
}
}
},
"feed_type": "DCP",
"allow_empty_password": false,
"cache": {"rev_cache": {"size": 5000,
"max_memory_count_mb": 0,
"shard_count": 16
},
"channel_cache": {"max_number": 50000,
"compact_high_watermark_pct": 80,
"compact_low_watermark_pct": 60,
"max_wait_pending": 5000,
"max_num_pending": 10000,
"max_wait_skipped": 3600000,
"enable_star_channel": true,
"max_length": 500,
"min_length": 50,
"expiry_seconds": 60,
"query_limit": 5000
},
"max_wait_pending": 0,
"max_wait_skipped": 0,
"enable_star_channel": true,
"channel_cache_max_length": 0,
"channel_cache_min_length": 0,
"channel_cache_expiry": 0,
"max_num_pending": 0
},
"rev_cache_size": 0,
"offline": false,
"unsupported": {"user_views": {"enabled": true
},
"oidc_test_provider": {"enabled": true
},
"api_endpoints": {"enable_couchbase_bucket_flush": true
},
"warning_thresholds": {"xattr_size_bytes": 0,
"channels_per_doc": 0,
"access_and_role_grants_per_doc": 0,
"channels_per_user": 0,
"channel_name_size": 0
},
"oidc_tls_skip_verify": true,
"sgr_tls_skip_verify": true,
"remote_config_tls_skip_verify": true,
"guest_read_only": true,
"force_api_forbidden_errors": true,
"dcp_read_buffer": 0,
"kv_buffer": 0
},
"local_jwt": {"providername1": {"issuer": "string",
"register": true,
"client_id": "string",
"algorithms": ["string"
],
"keys": [{"kty": "RSA",
"use": "sig",
"alg": "string",
"kid": "string",
"crv": "P-256",
"x": "string",
"y": "string",
"n": "string",
"e": "string"
}
],
"disable_session": true,
"user_prefix": "string",
"username_claim": "string",
"roles_claim": "string",
"channels_claim": "string"
},
"providername2": {"issuer": "string",
"register": true,
"client_id": "string",
"algorithms": ["string"
],
"keys": [{"kty": "RSA",
"use": "sig",
"alg": "string",
"kid": "string",
"crv": "P-256",
"x": "string",
"y": "string",
"n": "string",
"e": "string"
}
],
"disable_session": true,
"user_prefix": "string",
"username_claim": "string",
"roles_claim": "string",
"channels_claim": "string"
}
},
"oidc": {"providers": {"providername1": {"issuer": "string",
"register": true,
"client_id": "string",
"validation_key": "string",
"callback_url": "string",
"disable_session": true,
"scope": ["string"
],
"include_access": true,
"user_prefix": "string",
"discovery_url": "string",
"disable_cfg_validation": false,
"disable_callback_state": false,
"username_claim": "string",
"roles_claim": "string",
"channels_claim": "string",
"allow_unsigned_provider_tokens": true,
"IsDefault": true,
"Name": "string",
"InsecureSkipVerify": false
},
"providername2": {"issuer": "string",
"register": true,
"client_id": "string",
"validation_key": "string",
"callback_url": "string",
"disable_session": true,
"scope": ["string"
],
"include_access": true,
"user_prefix": "string",
"discovery_url": "string",
"disable_cfg_validation": false,
"disable_callback_state": false,
"username_claim": "string",
"roles_claim": "string",
"channels_claim": "string",
"allow_unsigned_provider_tokens": true,
"IsDefault": true,
"Name": "string",
"InsecureSkipVerify": false
}
},
"default_provider": "string"
},
"old_rev_expiry_seconds": 300,
"view_query_timeout_secs": 75,
"local_doc_expiry_secs": 7776000,
"enable_shared_bucket_access": true,
"session_cookie_secure": true,
"session_cookie_name": "string",
"session_cookie_http_only": false,
"allow_conflicts": true,
"num_index_replicas": 1,
"use_views": false,
"send_www_authenticate_header": true,
"disable_password_auth": false,
"bucket_op_timeout_ms": 0,
"slow_query_warning_threshold": 500,
"delta_sync": {"enabled": false,
"rev_max_age_seconds": 86400
},
"compact_interval_days": 1,
"sgreplicate_enabled": true,
"sgreplicate_websocket_heartbeat_secs": 300,
"replications": {"replication_id": {"replication_id": "string",
"remote": "string",
"username": "string",
"password": "string",
"remote_username": "string",
"remote_password": "string",
"direction": "push",
"conflict_resolution_type": "default",
"custom_conflict_resolver": "none",
"purge_on_removal": false,
"enable_delta_sync": false,
"max_backoff_time": 5,
"initial_state": "running",
"continuous": false,
"filter": "sync_gateway/bychannel",
"query_params": ["string"
],
"adhoc": false,
"batch_size": 200,
"run_as": "string",
"collections_enabled": false,
"collections_local": ["scope1.collection1",
"scope1.collection3",
"scope1.collection6"
],
"collections_remote": ["scope1.collectionA",
null,
"scope1.collectionF"
]
}
},
"serve_insecure_attachment_types": false,
"query_pagination_limit": 5000,
"user_xattr_key": "string",
"client_partition_window_secs": 2592000,
"guest": {"name": "string",
"password": "string",
"admin_channels": ["string"
],
"collection_access": {"scopename1": {"collectionname1": {"admin_channels": ["string"
]
},
"collectionname2": {"admin_channels": ["string"
]
}
},
"scopename2": {"collectionname1": {"admin_channels": ["string"
]
},
"collectionname2": {"admin_channels": ["string"
]
}
}
},
"email": "string",
"disabled": true,
"admin_roles": ["string"
]
},
"javascript_timeout_secs": 60,
"suspendable": false,
"cors": {"origin": ["string"
],
"login_origin": ["string"
],
"headers": ["string"
]
},
"logging": {"console": {"log_level": "debug",
"log_keys": ["CRUD",
"HTTP",
"Query"
]
},
"audit": {"enabled": false,
"enabled_events": [[1234,
5678
]
],
"disabled_users": [{"domain": "cbs",
"name": "string"
}
],
"disabled_roles": [{"domain": "cbs",
"name": "string"
}
]
}
}
}

Response samples

400
404
412

Content type

application/json

{"error": "string",
"reason": "string"
}

Update database configuration

This is used to update the database configuration fields specified. Only the fields specified in the request will have their values replaced.

The bucket and database name cannot be changed. If these need to be changed, the database will need to be deleted then recreated with the new settings.

Required Sync Gateway RBAC roles:

Sync Gateway Architect
Sync Gateway Application

path Parameters

db

required

string

Example: db1

The name of the database to run the operation against.

header Parameters

If-Match

string

If set to a configuration's Etag value, enables optimistic concurrency control for the request. Returns HTTP 412 if another update happened underneath this one.

Request Body schema: application/json

The database configuration fields to update

server	string This is the Couchbase Server address or addresses that the database connect to.
pool	string Deprecated Default: "default" This field is unsupported and ignored.
bucket	string Default: "The database name" The Couchbase Server backing bucket for the database.
username	string The username for authenticating to the server.
password	string The password for authenticating to the server.
certpath	string The cert path (public key) for X.509 bucket auth.
keypath	string The key path (private key) for X.509 bucket auth
cacertpath	string The root CA cert path for X.509 bucket authentication.
kv_tls_port	integer Default: 11207 The Memcached TLS port.
max_concurrent_query_ops	integer Default: 1000 The maximum amount of query operations that can be running at any one point.
	object <= 1 properties An object keyed by scope name containing config for the specific collection.
name	string The name of the database.
sync	string Default: "function(doc){channel(doc.channels);}" The Javascript function that newly created documents are ran through for the default scope and collection. If `scopes` parameter is set, this is ignored.
	object
	object
revs_limit	number >= 0 Default: "100 if conflict allowed and 50 if not" The maximum depth a document's revision tree can grow too. The minimum is `20` if conflicts are allowed and 0 if not. It is not recommended to go below `100` when conflicts are allowed.
import_docs	boolean If true, documents will be imported in to Sync Gateway from the bucket when requested. Documents will be ran through the set `import_filter` if any is set. The default value depends on the edition of Sync Gateway being used. If the edition is the Community Edition, then this will default to `false` or else in the Enterprise Edition, it will default to `true`. This can also be set to the string `continuous` which maps to true.
import_partitions	number Default: 16 This is an Enterprise Edition feature only This is how many import partitions should be used for import sharding. Partitions are distributed among all Sync Gateway nodes participating in import processing (`import_docs=true`), and each process a subset of the server's vbuckets. Each partition is processed by an independent function that runs simultaneously to others, so `import_partitions` can be used to tune concurrency based on the number of Sync Gateway nodes, and the number of cores per node.
import_filter	string This is the function that all imported documents in the default scope and collection are ran through in order to filter out what to import and what not to import. This allows you to control what is made available to Couchbase Mobile clients. If it is not set, then no documents are filtered when imported. `import_docs` must be true to make this field applicable. If `scopes` parameter is set, this is ignored.
import_backup_old_rev	boolean Default: false This controls whether import should attempt to create a temporary backup of the previous revision body (if available) when the document is modified in the bucket.
	object These are the settings for webhooks.
feed_type	string Deprecated Default: "DCP" Value: "DCP" The type of feed to use to communicate with Couchbase Server. This will use DCP regardless of specification.
allow_empty_password	boolean Default: false This controls whether users that are created can have an empty password or not.
	object
rev_cache_size	number Deprecated Deprecated, please use the database setting `cache.rev_cache.size` instead The maximum number of revisions to store in the revision cache.
offline	boolean Default: false Start the database in an offline state.
	object These are unsupported options and therefore it is not recommended to use them.
	object Configuration for Local JWT authentication.
	object Configuration for OpenID Connect authentication.
old_rev_expiry_seconds	number Default: 300 The number of seconds before old revisions are removed from the Couchbase Server bucket.
view_query_timeout_secs	integer Default: 75 The number of seconds before a view query should timeout.
local_doc_expiry_secs	integer Default: 7776000 The number of seconds before a `_local` document should expire.
enable_shared_bucket_access	boolean Default: true Whether to use extended attributes to store Sync Gateway document (`_sync`) metadata.
session_cookie_secure	boolean Override the session cookie `secure` flag. If set, the cookie will have the `secure` flag. This will default to `true` if startup config `api.https.tls_cert_path` is set otherwise it will default to `false`.
session_cookie_name	string This can be used to define a custom per-database session cookie name.
session_cookie_http_only	boolean Default: false Make all session cookies for the database set the `HttpOnly` flag so they are inaccessible to JavaScript.
allow_conflicts	boolean Deprecated Default: true This controls whether to allow conflicting document revisions.
num_index_replicas	number Default: 1 This is the number of Global Secondary Indexes (GSI) to use for core indexes.
use_views	boolean Default: false Force the use of views instead of GSI.
send_www_authenticate_header	boolean Default: true Controls whether to send a `WWW-Authenticate` header in `401 Unauthorized` HTTP responses.
disable_password_auth	boolean Default: false Whether to disable username/password authentication and only allow OIDC and guest access.
bucket_op_timeout_ms	number This is the amount of milliseconds should pass before a bucket operation times out. An error will be returned if the bucket operation times out saying: `operation timed out`.
slow_query_warning_threshold	number Default: 500 The amount of milliseconds a N1QL query should run before logging a warning.
	object Delta sync configuration settings. This is an Enterprise Edition feature only
compact_interval_days	number Default: 1 The interval between scheduled tombstone compaction runs (in days). This can be a floating point number. If set to 0, compaction will not run automatically.
sgreplicate_enabled	boolean Default: true Whether the node should accept assign replications (`true`) or not (`false`).
sgreplicate_websocket_heartbeat_secs	integer Default: 300 Use a custom heartbeat interval (in seconds) for websocket ping frames.
	object
serve_insecure_attachment_types	boolean Default: false If set, always serve attachments with the `Content-Type` header set to the type of the attachment. When serving an attachment, usually the `Content-Type` header is set to the type of the attachment but the `Content-Disposition` response header will be set instead if the content type is vulnerable to a phishing attack, causing the browser to download the file instead of display it. This option will override that behaviour and always set the `Content-Type` header.
query_pagination_limit	integer Default: 5000 The query limit to be used during pagination of large queries.
user_xattr_key	string The key to use for the user xattr that will be accessible from the sync function. IF empty, the feature will be disabled.
client_partition_window_secs	integer Default: 2592000 How long (in seconds) clients can remain offline for without losing replication metadata. Defaults to 30 days (in seconds)
	object (User) Properties associated with a user
javascript_timeout_secs	number Default: 60 The maximum number of seconds the sync, import filter, and custom conflict resolver JavaScript functions are allowed to run for before timing out. Set to 0 to allow the JS functions to run uncapped.
suspendable	boolean Default: false Set to true to allow the database to be suspended. Defaults to true when running in serverless mode otherwise defaults to false.
	object CORS configuration for this database; if present, overrides server's config.
	object Per-database logging configuration.

Responses

Request samples

Payload

Content type

application/json

{"server": "string",
"pool": "default",
"bucket": "The database name",
"username": "string",
"password": "string",
"certpath": "string",
"keypath": "string",
"cacertpath": "string",
"kv_tls_port": 11207,
"max_concurrent_query_ops": 1000,
"scopes": {"scopename": {"collections": {"collectionname1": {"sync": "function(doc){channel(\"collection name\");}",
"import_filter": "function(doc) { if (doc.type != 'mobile') { return false; } return true; }"
},
"collectionname2": {"sync": "function(doc){channel(\"collection name\");}",
"import_filter": "function(doc) { if (doc.type != 'mobile') { return false; } return true; }"
}
}
}
},
"name": "string",
"sync": "function(doc){channel(doc.channels);}",
"users": {"username1": {"name": "string",
"password": "string",
"admin_channels": ["string"
],
"collection_access": {"scopename1": {"collectionname1": {"admin_channels": ["string"
]
},
"collectionname2": {"admin_channels": ["string"
]
}
},
"scopename2": {"collectionname1": {"admin_channels": ["string"
]
},
"collectionname2": {"admin_channels": ["string"
]
}
}
},
"email": "string",
"disabled": true,
"admin_roles": ["string"
]
},
"username2": {"name": "string",
"password": "string",
"admin_channels": ["string"
],
"collection_access": {"scopename1": {"collectionname1": {"admin_channels": ["string"
]
},
"collectionname2": {"admin_channels": ["string"
]
}
},
"scopename2": {"collectionname1": {"admin_channels": ["string"
]
},
"collectionname2": {"admin_channels": ["string"
]
}
}
},
"email": "string",
"disabled": true,
"admin_roles": ["string"
]
}
},
"roles": {"rolename1": {"name": "string",
"admin_channels": ["string"
],
"collection_access": {"scopename1": {"collectionname1": {"admin_channels": ["string"
]
},
"collectionname2": {"admin_channels": ["string"
]
}
},
"scopename2": {"collectionname1": {"admin_channels": ["string"
]
},
"collectionname2": {"admin_channels": ["string"
]
}
}
}
},
"rolename2": {"name": "string",
"admin_channels": ["string"
],
"collection_access": {"scopename1": {"collectionname1": {"admin_channels": ["string"
]
},
"collectionname2": {"admin_channels": ["string"
]
}
},
"scopename2": {"collectionname1": {"admin_channels": ["string"
]
},
"collectionname2": {"admin_channels": ["string"
]
}
}
}
}
},
"revs_limit": "100 if conflict allowed and 50 if not",
"import_docs": true,
"import_partitions": 16,
"import_filter": "function(doc) { if (doc.type != 'mobile') { return false; } return true; }",
"import_backup_old_rev": false,
"event_handlers": {"max_processes": "string",
"wait_for_process": "string",
"document_changed": {"handler": "webhook",
"url": "string",
"filter": "string",
"timeout": 0,
"options": {"property1": null,
"property2": null
}
},
"db_state_changed": {"handler": "webhook",
"url": "string",
"filter": "string",
"timeout": 0,
"options": {"property1": null,
"property2": null
}
}
},
"feed_type": "DCP",
"allow_empty_password": false,
"cache": {"rev_cache": {"size": 5000,
"max_memory_count_mb": 0,
"shard_count": 16
},
"channel_cache": {"max_number": 50000,
"compact_high_watermark_pct": 80,
"compact_low_watermark_pct": 60,
"max_wait_pending": 5000,
"max_num_pending": 10000,
"max_wait_skipped": 3600000,
"enable_star_channel": true,
"max_length": 500,
"min_length": 50,
"expiry_seconds": 60,
"query_limit": 5000
},
"max_wait_pending": 0,
"max_wait_skipped": 0,
"enable_star_channel": true,
"channel_cache_max_length": 0,
"channel_cache_min_length": 0,
"channel_cache_expiry": 0,
"max_num_pending": 0
},
"rev_cache_size": 0,
"offline": false,
"unsupported": {"user_views": {"enabled": true
},
"oidc_test_provider": {"enabled": true
},
"api_endpoints": {"enable_couchbase_bucket_flush": true
},
"warning_thresholds": {"xattr_size_bytes": 0,
"channels_per_doc": 0,
"access_and_role_grants_per_doc": 0,
"channels_per_user": 0,
"channel_name_size": 0
},
"oidc_tls_skip_verify": true,
"sgr_tls_skip_verify": true,
"remote_config_tls_skip_verify": true,
"guest_read_only": true,
"force_api_forbidden_errors": true,
"dcp_read_buffer": 0,
"kv_buffer": 0
},
"local_jwt": {"providername1": {"issuer": "string",
"register": true,
"client_id": "string",
"algorithms": ["string"
],
"keys": [{"kty": "RSA",
"use": "sig",
"alg": "string",
"kid": "string",
"crv": "P-256",
"x": "string",
"y": "string",
"n": "string",
"e": "string"
}
],
"disable_session": true,
"user_prefix": "string",
"username_claim": "string",
"roles_claim": "string",
"channels_claim": "string"
},
"providername2": {"issuer": "string",
"register": true,
"client_id": "string",
"algorithms": ["string"
],
"keys": [{"kty": "RSA",
"use": "sig",
"alg": "string",
"kid": "string",
"crv": "P-256",
"x": "string",
"y": "string",
"n": "string",
"e": "string"
}
],
"disable_session": true,
"user_prefix": "string",
"username_claim": "string",
"roles_claim": "string",
"channels_claim": "string"
}
},
"oidc": {"providers": {"providername1": {"issuer": "string",
"register": true,
"client_id": "string",
"validation_key": "string"