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",
"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
412

Content type

application/json

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

Get database audit configuration

Retrieve the audit 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

verbose	boolean Default: false Whether to show name and description with each audit event.
filterable	boolean Default: false Whether to show only filterable audit events.

Responses

Response samples

200
404

Content type

application/json

Example

Simple

{"enabled": true,
"events": {"audit_id1": true,
"audit_id2": true
},
"disabled_users": [{"domain": "cbs",
"name": "string"
}
],
"disabled_roles": [{"domain": "cbs",
"name": "string"
}
]
}

Replace database audit configuration

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

Unspecified audit events will be reset to their default enabled value. Use POST if you want upsert-style semantics.

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

The new database audit configuration to use

One of

enabled	boolean
	object
	Array of objects List of users for which audit logging is disabled.
	Array of objects List of roles for which audit logging is disabled. Either cbs or sgw.

Responses

Request samples

Payload

Content type

application/json

Example

Simple

{"enabled": true,
"events": {"audit_id1": true,
"audit_id2": true
},
"disabled_users": [{"domain": "cbs",
"name": "string"
}
],
"disabled_roles": [{"domain": "cbs",
"name": "string"
}
]
}

Response samples

400
404

Content type

application/json

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

Update database audit configuration

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

Unspecified audit events will be unaffected. Use PUT if you want to reset events to their default state.

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

verbose

boolean

Default: false

Whether to show name and description with each audit event.

Request Body schema: application/json

The database configuration fields to update

One of

enabled	boolean
	object
	Array of objects List of users for which audit logging is disabled.
	Array of objects List of roles for which audit logging is disabled. Either cbs or sgw.

Responses

Request samples

Payload

Content type

application/json

Example

Simple

{"enabled": true,
"events": {"audit_id1": true,
"audit_id2": true
},
"disabled_users": [{"domain": "cbs",
"name": "string"
}
],
"disabled_roles": [{"domain": "cbs",
"name": "string"
}
]
}

Response samples

400

Content type

application/json

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

Get database sync function

This returns the database's sync function.

Response will be blank if there has been no sync function set.

Required Sync Gateway RBAC roles:

Sync Gateway Architect

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

Response samples

200
404

Content type

application/javascript

function (doc, oldDoc) {
  channel(doc.channels);
}

Set database sync function

This will allow you to update the sync function.

Required Sync Gateway RBAC roles:

Sync Gateway Architect

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

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/javascript

The new sync function to use

string

Responses

Request samples

Payload

Content type

application/javascript

function (doc, oldDoc) {
  channel(doc.channels);
}

Response samples

400
404
412

Content type

application/json

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

Remove custom sync function

This will remove the custom sync function from the database configuration.

The default sync function is equivalent to:

function (doc) {
  channel(doc.channels);
}

Required Sync Gateway RBAC roles:

Sync Gateway Architect

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.

header Parameters

If-Match

string

The revision ID to target.

Responses

Response samples

404
412

Content type

application/json

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

Get database import filter

This returns the database's import filter that documents are ran through when importing.

Response will be blank if there has been no import filter set.

Required Sync Gateway RBAC roles:

Sync Gateway Architect

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

Response samples

404

Content type

application/json

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

Set database import filter

This will allow you to update the database's import filter.

Required Sync Gateway RBAC roles:

Sync Gateway Architect

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

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/javascript

The import filter to use

string

Responses

Response samples

400
404
412

Content type

application/json

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

Delete import filter

This will remove the custom import filter function from the database configuration so that Sync Gateway will not filter any documents during import.

Required Sync Gateway RBAC roles:

Sync Gateway Architect

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.

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.

Responses

Response samples

404
412

Content type

application/json

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

Database Security

Create and manage database users and roles

Get all the names of the users

Retrieves all the names of the users that are in the database.

Required Sync Gateway RBAC roles:

Sync Gateway Architect
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.

query Parameters

name_only	boolean Default: true Whether to return user names only, or more detailed information for each user.
limit	integer How many results to return. Using a value of `0` results in no limit.

Responses

Response samples

200
404

Content type

application/json

["Alice",
"Bob"
]

Create a new user

Create a new user using the request body to specify the properties on the user.

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.

Request Body schema: application/json

Properties associated with a user

name	string The name of the user. User names can only have alphanumeric ASCII characters and underscores.
password	string The password of the user. Mandatory. unless `allow_empty_password` is `true` in the database configs.
admin_channels	Array of strings A list of channels to explicitly grant to the user for the default collection.
	object A set of access grants by scope and collection.
email	string The email address of the user.
disabled	boolean If true, the user will not be able to login to the account as it is disabled.
admin_roles	Array of strings A list of roles to explicitly grant to the user.

Responses

Request samples

Payload

Content type

application/json

{"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"
]
}

Response samples

404
409

Content type

application/json

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

/{db}/_user/

Required Sync Gateway RBAC roles:

Sync Gateway Architect
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

404

Content type

application/json

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

Get a user

Retrieve a single users information.

Required Sync Gateway RBAC roles:

Sync Gateway Architect
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.
name required	string The name of the user.

Responses

Response samples

200
404

Content type

application/json

{"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"
}

Upsert a user

If the user does not exist, create a new user otherwise update the existing user.

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.
name required	string The name of the user.

Request Body schema: application/json

Properties associated with a user

name	string The name of the user. User names can only have alphanumeric ASCII characters and underscores.
password	string The password of the user. Mandatory. unless `allow_empty_password` is `true` in the database configs.
admin_channels	Array of strings A list of channels to explicitly grant to the user for the default collection.
	object A set of access grants by scope and collection.
email	string The email address of the user.
disabled	boolean If true, the user will not be able to login to the account as it is disabled.
admin_roles	Array of strings A list of roles to explicitly grant to the user.

Responses

Request samples

Payload

Content type

application/json

{"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"
]
}

Response samples

404

Content type

application/json

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

Delete a user

Delete a user from the database.

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.
name required	string The name of the user.

Responses

Response samples

404

Content type

application/json

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

Check if user exists

Check if the user exists by checking the status code.

Required Sync Gateway RBAC roles:

Sync Gateway Architect
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.
name required	string The name of the user.

Responses

Get all names of the roles

Retrieves all the roles that are in the database.

Required Sync Gateway RBAC roles:

Sync Gateway Architect
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.

query Parameters

deleted

boolean

Default: false

Enum: true false

Indicates that roles marked as deleted should be included in the result.

Responses

Response samples

200
404

Content type

application/json

["Administrator",
"Moderator"
]

Create a new role

Create a new role using the request body to specify the properties on the role.

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.

Request Body schema: application/json

Properties associated with a role

name	string The name of the role. Role names can only have alphanumeric ASCII characters and underscores.
admin_channels	Array of strings The channels that users in the role are able to access for the default collection.
	object A set of access grants by scope and collection.

Responses

Request samples

Payload

Content type

application/json

{"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"
]
}
}
}
}

Response samples

404
409

Content type

application/json

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

/{db}/_role/

Required Sync Gateway RBAC roles:

Sync Gateway Architect
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

404

Content type

application/json

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

Get a role

Retrieve a single roles properties.

Required Sync Gateway RBAC roles:

Sync Gateway Architect
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.
name required	string The name of the role.

Responses

Response samples

200
404

Content type

application/json

{"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"
}
}
}
}

Upsert a role

If the role does not exist, create a new role otherwise update the existing role.

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.
name required	string The name of the role.

Request Body schema: application/json

Properties associated with a role

name	string The name of the role. Role names can only have alphanumeric ASCII characters and underscores.
admin_channels	Array of strings The channels that users in the role are able to access for the default collection.
	object A set of access grants by scope and collection.

Responses

Request samples

Payload

Content type

application/json

{"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"
]
}
}
}
}

Response samples

404

Content type

application/json

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

Delete a role

Delete a role from the database.

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.
name required	string The name of the role.

Responses

Response samples

404

Content type

application/json

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

Check if role exists

Check if the role exists by checking the status code.

Required Sync Gateway RBAC roles:

Sync Gateway Architect
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.
name required	string The name of the role.

Responses

Response samples

404

Content type

application/json

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

Session

Manage user sessions

Get information about the current user

This will get the information about the current user.

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

{"authentication_handlers": ["string"
],
"ok": true,
"userCtx": {"channels": { },
"name": "string"
}
}

Create a new user session

Generates a login session for a user and returns the session ID and cookie name for that session. If no TTL is provided, then the default of 24 hours will be used.

A session cannot be generated for an non-existent user or the GUEST user.

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.

Request Body schema: application/json

The body can depend on if using the Public or Admin APIs.

name	string User name to generate the session for.
ttl	integer Time until the session expires. Uses default value of 24 hours if left blank.

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"ttl": 0
}

Response samples

200
400
404

Content type

application/json

{"session_id": "c5af80a039db4ed9d2b6865576b6999935282689",
"expires": "2022-01-21T15:24:44Z",
"cookie_name": "SyncGatewaySession"
}

/{db}/_session

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\""
}

Get session information

Retrieve session information such as the user the session belongs too and what channels that user can access.

Required Sync Gateway RBAC roles:

Sync Gateway Architect
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.
sessionid required	string The ID of the session to target.

Responses

Response samples

200
404

Content type

application/json

{"authentication_handlers": ["string"
],
"ok": true,
"userCtx": {"channels": { },
"name": "string"
}
}

Remove session

Invalidates the session provided so that anyone using it is logged out and is prevented from future use.

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.
sessionid required	string The ID of the session to target.

Responses

Response samples

404

Content type

application/json

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

Remove all of a users sessions

Invalidates all the sessions that a user has.

Will still return a 200 status code if the user has no sessions.

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.
name required	string The name of the user.

Responses

Response samples

404

Content type

application/json

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

Remove session with user validation

Invalidates the session only if it belongs to the user.

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.
name required	string The name of the user.
sessionid required	string The ID of the session to target.

Responses

Response samples

404

Content type

application/json

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

OpenID Connect

Manage OpenID Connect

Document

Create and manage documents and attachments

Get a document with the corresponding metadata

Returns the a documents latest revision with its metadata.

Note: The direct use of this endpoint is unsupported. The sync metadata is maintained internally by Sync Gateway and its structure can change. It should not be used to drive business logic of applications since the response to the /{db}/_raw/{id} endpoint can change at any time.

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.
docid required	string Example: doc1 The document ID to run the operation against.

query Parameters

include_doc	string Include the body associated with the document.
redact	boolean This redacts sensitive parts of the response. Cannot be used when `include_docs=true`

Responses

Response samples

200
400
404

Content type

application/json

{"_sync": {"rev": "string",
"sequence": 0,
"recent_sequences": [0
],
"history": {"revs": ["string"
],
"parents": [0
],
"channels": [["string"
]
]
},
"cas": "string",
"value_crc32c": "string",
"channel_set": [{"name": "string",
"start": "string",
"end": "string"
}
],
"channel_set_history": [{"name": "string",
"start": "string",
"end": "string"
}
],
"time_saved": "string"
}
}

/{keyspace}/_raw/{docid}

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.
docid required	string Example: doc1 The document ID to run the operation against.

Responses

Response samples

400
404

Content type

application/json

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

Purge a document

The purge command provides a way to remove a document from the database. The operation removes all revisions (active and tombstones) for the specified document(s). A common usage of this endpoint is to remove tombstone documents that are no longer needed, thus recovering storage space and reducing data replicated to clients. Other clients are not notified when a revision has been purged; so in order to purge a revision from the system it must be done from all databases (on Couchbase Lite and Sync Gateway).

When enable_shared_bucket_access is enabled, this endpoint removes the document and its associated extended attributes.

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

Purge request body

doc_id	Array of strings Items Value: "" The document ID to purge. The array must only be 1 element which is ``. All revisions will be permanently removed for that document.
property name* additional property	Array of strings Items Value: "*"

Responses

Request samples

Payload

Content type

application/json

Example

Single document

{"doc_id": ["*"
]
}

Response samples

200
400
404

Content type

application/json

Example

Single document

{"purged": {"doc_id": ["*"
]
}
}

Create a new document

Create a new document in the keyspace.

This will generate a random document ID unless specified in the body.

A document can have a maximum size of 20MB.

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

roundtrip

boolean

Block until document has been received by change cache

Request Body schema: application/json

_id	string The ID of the document.
_rev	string The revision of the document.
_exp	string Expiry time after which the document will be purged. The expiration time is set and managed on the Couchbase Server document. The value can be specified in two ways; in ISO-8601 format, for example the 6th of July 2022 at 17:00 in the BST timezone would be `2016-07-06T17:00:00+01:00`; it can also be specified as a numeric Couchbase Server expiry value. Couchbase Server expiry values are specified as Unix time, and if the desired TTL is below 30 days then it can also represent an interval in seconds from the current time (for example, a value of 5 will remove the document 5 seconds after it is written to Couchbase Server). The document expiration time is returned in the response of `GET /{db}/{doc}` when `show_exp=true` is included in the query. As with the existing explicit purge mechanism, this applies only to the local database; it has nothing to do with replication. This expiration time is not propagated when the document is replicated. The purge of the document does not cause it to be deleted on any other database.
_deleted	boolean Whether the document is a tombstone or not. If true, it is a tombstone.
	object
	object
property name* additional property	any

Responses

Request samples

Payload

Content type

application/json

{"_id": "string",
"_rev": "string",
"_exp": "string",
"_deleted": true,
"_revisions": {"start": 0,
"ids": ["string"
]
},
"_attachments": {"attachmentname1": {"content_type": "string",
"data": "string"
},
"attachmentname2": {"content_type": "string",
"data": "string"
}
}
}

Response samples

200
400
404
409
415

Content type

application/json

{"id": "string",
"ok": true,
"rev": "string"
}

Gets all the documents in the database with the given parameters

Returns all documents in the database based on the specified parameters.

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

include_docs	boolean Include the body associated with each document.
channels	boolean Include the channels each document is part of that the calling user also has access too.
access	boolean Include what user/roles that each document grants access too.
revs	boolean Include all the revisions for each document under the `_revisions` property.
update_seq	boolean Include the document sequence number `update_seq` property for each document.
keys	Array of strings An array of document ID strings to filter by.
startkey	string Return records starting with the specified key.
endkey	string Stop returning records when this key is reached.
limit	number This limits the number of result rows returned. Using a value of `0` has the same effect as the value `1`.

Responses

Response samples

200
400
404

Content type

application/json

{"rows": [{"key": "string",
"id": "string",
"value": {"rev": "string"
}
}
],
"total_rows": 0,
"update_seq": 0
}

Get all the documents in the database using a built-in view

Returns all documents in the database based on the specified parameters.

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

include_docs	boolean Include the body associated with each document.
channels	boolean Include the channels each document is part of that the calling user also has access too.
access	boolean Include what user/roles that each document grants access too.
revs	boolean Include all the revisions for each document under the `_revisions` property.
update_seq	boolean Include the document sequence number `update_seq` property for each document.
startkey	string Return records starting with the specified key.
endkey	string Stop returning records when this key is reached.
limit	number This limits the number of result rows returned. Using a value of `0` has the same effect as the value `1`.

Request Body schema: application/json

keys

required

Array of strings

List of the documents to retrieve.

Responses

Request samples

Payload

Content type

application/json

{"keys": ["string"
]
}

Response samples

200
400
404

Content type

application/json

{"rows": [{"key": "string",
"id": "string",
"value": {"rev": "string"
}
}
],
"total_rows": 0,
"update_seq": 0
}

/{db}/_all_docs

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

include_docs	boolean Include the body associated with each document.
channels	boolean Include the channels each document is part of that the calling user also has access too.
access	boolean Include what user/roles that each document grants access too.
revs	boolean Include all the revisions for each document under the `_revisions` property.
update_seq	boolean Include the document sequence number `update_seq` property for each document.
keys	Array of strings An array of document ID strings to filter by.
startkey	string Return records starting with the specified key.
endkey	string Stop returning records when this key is reached.
limit	number This limits the number of result rows returned. Using a value of `0` has the same effect as the value `1`.

Responses

Response samples

400
404

Content type

application/json

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

Bulk document operations

This will allow multiple documented to be created, updated or deleted in bulk.

To create a new document, simply add the body in an object under docs. A doc ID will be generated by Sync Gateway unless _id is specified.

To update an existing document, provide the document ID (_id) and revision ID (_rev) as well as the new body values.

To delete an existing document, provide the document ID (_id), revision ID (_rev), and set the deletion flag (_deleted) to true.

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

new_edits	boolean Default: true This controls whether to assign new revision identifiers to new edits (`true`) or use the existing ones (`false`).
required	Array of objects (Document)

Responses

Request samples

Payload

Content type

application/json

{"new_edits": true,
"docs": [{"_id": "FooBar",
"foo": "bar"
},
{"_id": "AliceSettings",
"_rev": "5-832a6db48ed130adadede928aee54576",
"FailedLoginAttempts": 7
},
{"_id": "BobSettings",
"_rev": "1-fa76ba41ee5fdfee1b91fc478ed09e59",
"_deleted": true
}
]
}

Response samples

201
400
404

Content type

application/json

Example

Success

[{"id": "FooBar",
"rev": "1-cd809becc169215072fd567eebd8b8de"
},
{"id": "AliceSettings",
"rev": "6-b3e8dcf825b71ccee112f3572ec4323c"
},
{"id": "BobSettings",
"rev": "2-5145e1086bb8d1d71a531e9f6b543c58"
}
]

Get multiple documents in a MIME multipart response

This request returns any number of documents, as individual bodies in a MIME multipart response.

Each enclosed body contains one requested document. The bodies appear in the same order as in the request, but can also be identified by their X-Doc-ID and X-Rev-ID headers (if the attachments query is true).

A body for a document with no attachments will have content type application/json and contain the document itself.

A body for a document that has attachments will be written as a nested multipart/related body.

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

attachments	boolean Default: "false" This is for whether to include attachments in each of the documents returned or not.
revs	boolean Include all the revisions for each document under the `_revisions` property.
revs_limit	integer The number of revisions to include in the response from the document history. This parameter only makes a different if the `revs` query parameter is set to `true`. The full revision history will be returned if `revs` is set but this is not.

header Parameters

X-Accept-Part-Encoding	string If this header includes `gzip` then the part HTTP compression encoding will be done.
Accept-Encoding	string If this header includes `gzip` then the the HTTP response will be compressed. This takes priority over `X-Accept-Part-Encoding`. Only part compression will be done if `X-Accept-Part-Encoding=gzip` and the `User-Agent` is below 1.2 due to clients not being able to handle full compression.

Request Body schema: application/json

required

Array of objects

Responses

Request samples

Payload

Content type

application/json

{"docs": [{"id": "FooBar"
},
{"id": "attachment"
},
{"id": "AliceSettings"
}
]
}

Response samples

404

Content type

application/json

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

Get local document

This request retrieves a local document.

Local document IDs begin with _local/. Local documents are not replicated or indexed, don't support attachments, and don't save revision histories. In practice they are almost only used by Couchbase Lite's replicator, as a place to store replication checkpoint data.

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.
docid required	string The name of the local document ID excluding the `_local/` prefix.

Responses

Response samples

400
404

Content type

application/json

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

Upsert a local document

This request creates or updates a local document. Updating a local document requires that the revision ID be put in the body under _rev.

Local document IDs are given a _local/ prefix. Local documents are not replicated or indexed, don't support attachments, and don't save revision histories. In practice they are almost only used by the client's replicator, as a place to store replication checkpoint data.

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.
docid required	string The name of the local document ID excluding the `_local/` prefix.

Request Body schema: application/json

The body of the document

_rev	string Revision to replace. Required if updating existing local document.

Responses

Request samples

Payload

Content type

application/json

{"_rev": "2-5145e1086bb8d1d71a531e9f6b543c58"
}

Response samples

201
400
404

Content type

application/json

{"id": "string",
"ok": true,
"rev": "string"
}

Delete a local document

This request deletes a local document.

Local document IDs begin with _local/. Local documents are not replicated or indexed, don't support attachments, and don't save revision histories. In practice they are almost only used by Couchbase Lite's replicator, as a place to store replication checkpoint data.

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.
docid required	string The name of the local document ID excluding the `_local/` prefix.

query Parameters

rev

required

string

The revision ID of the revision to delete.

Responses

Response samples

400
404

Content type

application/json

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

Check if local document exists

This request checks if a local document exists.

Local document IDs begin with _local/. Local documents are not replicated or indexed, don't support attachments, and don't save revision histories. In practice they are almost only used by Couchbase Lite's replicator, as a place to store replication checkpoint data.

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.
docid required	string The name of the local document ID excluding the `_local/` prefix.

Responses

Response samples

400
404

Content type

application/json

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

Get a document

Retrieve a document from the database by its doc ID.

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.
docid required	string Example: doc1 The document ID to run the operation against.

query Parameters

rev	string Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58 The document revision to target.
open_revs	Array of strings Option to fetch specified revisions of the document. The value can be all to fetch all leaf revisions or an array of revision numbers (i.e. open_revs=["rev1", "rev2"]). Only leaf revision bodies that haven't been pruned are guaranteed to be returned. If this option is specified the response will be in multipart format. Use the `Accept: application/json` request header to get the result as a JSON object.
show_exp	boolean Whether to show the expiry property (`_exp`) in the response.
revs_from	Array of strings Trim the revision history to stop at the first revision in the provided list. If no match is found, the revisions will be trimmed to the `revs_limit`.
atts_since	Array of strings Include attachments only since specified revisions. Excludes the attachments for the specified revisions. Only gets used if `attachments=true`.
revs_limit	integer Maximum amount of revisions to return for each document.
attachments	boolean Include attachment bodies in response.
replicator2	boolean Returns the document with the required properties for replication. This is an enterprise-edition only feature.

Responses

Response samples

200
400
404
501

Content type

application/json

{"FailedLoginAttempts": 5,
"Friends": ["Bob"
],
"_id": "AliceSettings",
"_rev": "1-64d4a1f179db5c1848fe52967b47c166"
}

Upsert a document

This will upsert a document meaning if it does not exist, then it will be created. Otherwise a new revision will be made for the existing document. A revision ID must be provided if targetting an existing document.

A document ID must be specified for this endpoint. To let Sync Gateway generate the ID, use the POST /{db}/ endpoint.

If a document does exist, then replace the document content with the request body. This means unspecified fields will be removed in the new revision.

The maximum size for a document is 20MB.

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.
docid required	string Example: doc1 The document ID to run the operation against.

query Parameters

roundtrip	boolean Block until document has been received by change cache
replicator2	boolean Returns the document with the required properties for replication. This is an enterprise-edition only feature.
new_edits	boolean Default: "true" Setting this to false indicates that the request body is an already-existing revision that should be directly inserted into the database, instead of a modification to apply to the current document. This mode is used for replication. This option must be used in conjunction with the `_revisions` property in the request body.
rev	string Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58 The document revision to target.

header Parameters

If-Match

string

The revision ID to target.

Request Body schema: application/json

_id	string The ID of the document.
_rev	string The revision of the document.
_exp	string Expiry time after which the document will be purged. The expiration time is set and managed on the Couchbase Server document. The value can be specified in two ways; in ISO-8601 format, for example the 6th of July 2022 at 17:00 in the BST timezone would be `2016-07-06T17:00:00+01:00`; it can also be specified as a numeric Couchbase Server expiry value. Couchbase Server expiry values are specified as Unix time, and if the desired TTL is below 30 days then it can also represent an interval in seconds from the current time (for example, a value of 5 will remove the document 5 seconds after it is written to Couchbase Server). The document expiration time is returned in the response of `GET /{db}/{doc}` when `show_exp=true` is included in the query. As with the existing explicit purge mechanism, this applies only to the local database; it has nothing to do with replication. This expiration time is not propagated when the document is replicated. The purge of the document does not cause it to be deleted on any other database.
_deleted	boolean Whether the document is a tombstone or not. If true, it is a tombstone.
	object
	object
property name* additional property	any

Responses

Request samples

Payload

Content type

application/json

{"_id": "string",
"_rev": "string",
"_exp": "string",
"_deleted": true,
"_revisions": {"start": 0,
"ids": ["string"
]
},
"_attachments": {"attachmentname1": {"content_type": "string",
"data": "string"
},
"attachmentname2": {"content_type": "string",
"data": "string"
}
}
}

Response samples

201
400
404
409
415

Content type

application/json

{"id": "string",
"ok": true,
"rev": "string"
}

Delete a document

Delete a document from the database. A new revision is created so the database can track the deletion in synchronized copies.

A revision ID either in the header or on the query parameters is required.

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.
docid required	string Example: doc1 The document ID to run the operation against.

query Parameters

rev	string Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58 The document revision to target.

header Parameters

If-Match

string

The revision ID to target.

Responses

Response samples

200
400
404

Content type

application/json

{"id": "string",
"ok": true,
"rev": "string"
}

Check if a document exists

Return a status code based on if the document exists or not.

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.
docid required	string Example: doc1 The document ID to run the operation against.

query Parameters

rev	string Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58 The document revision to target.
open_revs	Array of strings Option to fetch specified revisions of the document. The value can be all to fetch all leaf revisions or an array of revision numbers (i.e. open_revs=["rev1", "rev2"]). Only leaf revision bodies that haven't been pruned are guaranteed to be returned. If this option is specified the response will be in multipart format. Use the `Accept: application/json` request header to get the result as a JSON object.
show_exp	boolean Whether to show the expiry property (`_exp`) in the response.
revs_from	Array of strings Trim the revision history to stop at the first revision in the provided list. If no match is found, the revisions will be trimmed to the `revs_limit`.
atts_since	Array of strings Include attachments only since specified revisions. Excludes the attachments for the specified revisions. Only gets used if `attachments=true`.
revs_limit	integer Maximum amount of revisions to return for each document.
attachments	boolean Include attachment bodies in response.
replicator2	boolean Returns the document with the required properties for replication. This is an enterprise-edition only feature.

Responses

Response samples

400
404

Content type

application/json

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

Get an attachment from a document

This request retrieves a file attachment associated with the document.

The raw data of the associated attachment is returned (just as if you were accessing a static file). The Content-Type response header is the same content type set when the document attachment was added to the database. The Content-Disposition response header will be set if the content type is considered unsafe to display in a browser (unless overridden by by database config option serve_insecure_attachment_types) which will force the attachment to be downloaded.

If the meta query parameter is set then the response will be in JSON with the additional metadata tags.

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.
docid required	string Example: doc1 The document ID to run the operation against.
attach required	string The attachment name. This value must be URL encoded. For example, if the attachment name is `blob_/avatar`, the path component passed to the URL should be `blob_%2Favatar` (tested with URLEncoder).

query Parameters

rev	string Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58 The document revision to target.
content_encoding	boolean Default: "true" Set to false to disable the `Content-Encoding` response header.
meta	boolean Default: "false" Return only the metadata of the attachment in the response body.

header Parameters

Range

string

Example: bytes=123-456

RFC-2616 bytes range header.

Responses

Response samples

404

Content type

application/json

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

Create or update an attachment on a document

This request adds or updates an attachment associated with the document. If the document does not exist, it will be created and the attachment will be added to it.

If the attachment already exists, the data of the existing attachment will be replaced in the new revision.

The maximum content size of an attachment is 20MB. The Content-Type header of the request specifies the content type of the attachment.

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.
docid required	string Example: doc1 The document ID to run the operation against.
attach required	string The attachment name. This value must be URL encoded. For example, if the attachment name is `blob_/avatar`, the path component passed to the URL should be `blob_%2Favatar` (tested with URLEncoder).

query Parameters

rev	string The existing document revision ID to modify. Required only when modifying an existing document.

header Parameters

Content-Type	string Default: application/octet-stream The content type of the attachment.
If-Match	string An alternative way of specifying the document revision ID.

Request Body schema: Attachment content type

The attachment data

string

The content to store in the body

Responses

Response samples

201
404
409

Content type

application/json

{"id": "string",
"ok": true,
"rev": "string"
}

Check if attachment exists

This request check if the attachment exists on the specified document.

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.
docid required	string Example: doc1 The document ID to run the operation against.
attach required	string The attachment name. This value must be URL encoded. For example, if the attachment name is `blob_/avatar`, the path component passed to the URL should be `blob_%2Favatar` (tested with URLEncoder).

query Parameters

rev	string Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58 The document revision to target.

Responses

Response samples

404

Content type

application/json

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

Delete an attachment on a document

This request deletes an attachment associated with the document.

If the attachment exists, the attachment will be removed from the document.

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.
docid required	string Example: doc1 The document ID to run the operation against.
attach required	string The attachment name. This value must be URL encoded. For example, if the attachment name is `blob_/avatar`, the path component passed to the URL should be `blob_%2Favatar` (tested with URLEncoder).

query Parameters

rev	string The existing document revision ID to modify.

header Parameters

If-Match

string

An alternative way of specifying the document revision ID.

Responses

Response samples

200
404
409

Content type

application/json

{"id": "string",
"ok": true,
"rev": "string"
}

Replication

Create and manage inter-Sync Gateway replications

Get all replication configurations

This will retrieve all database replication definitions.

Required Sync Gateway RBAC roles:

Sync Gateway Replicator

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

{"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"
}
}

Upsert a replication

Create or update a replication in the database.

If an existing replication is being updated, that replication must be stopped first.

Required Sync Gateway RBAC roles:

Sync Gateway Replicator

path Parameters

db

required

string

Example: db1

The name of the database to run the operation against.

Request Body schema: application/json

If the replication_id matches an existing replication then the existing configuration will be updated. Only the specified fields in the request will be used to update the existing configuration. Unspecified fields will remain untouched.

replication_id	string This is the ID of the replication. When creating a new replication using a POST request, this will be set to a random UUID if not explicitly set. When the replication ID is specified in the URL, this must be set to the same replication ID if specifying it at all.
remote	string This is the endpoint of the database for the remote Sync Gateway that is the subject of this replication's `push`, `pull`, or `pushAndPull` action. Typically this would include the URI, port, and database name. For example, `http://localhost:4985/db`. How this remote is used depends on the `direction` of the replication: `pull` - this replicator pulls changes from the `remote` `push` - this replicator pushes changes to this `remote` `pushAndPull` - this replicator pushes changes to this `remote`, while also pulling receiving changes
username	string Deprecated This has been deprecated in favour of `remote_username`. This is the username to use to authenticate with the remote. This can only be used for a pull replication.
password	string Deprecated This has been deprecated in favour of `remote_password`. This is the password to use to authenticate with the remote. This password will be redacted in the replication config. This can only be used for a pull replication.
remote_username	string The username to use to authenticate with the remote. This can only be used for a pull replication.
remote_password	string The password to use to authenticate with the remote. This password will be redacted in the replication config. This can only be used for a pull replication.
direction required	string Enum: "push" "pull" "pushAndPull" This specifies which direction the replication will be replicating with the `remote` replicator. The directions are: `pull` - changes are pulled from the remote database `push` - changes are pushed to the remote database `pushAndPull` - changes are both push-to and pulled-from the remote database Replications created prior to Sync Gateway 2.8 derive their `direction` from the source/target URL of the replication.
conflict_resolution_type	string Default: "default" Enum: "default" "remoteWins" "localWins" "custom" This defines what conflict resolution policy Sync Gateway should use to apply when resolving conflicting revisions. Changing this is an Enterprise Edition only feature. Behaviour default - In priority order, this will cause Deletes to always win (the delete with the longest revision history wins if both revisions are deletes) The revision with the longest revision history to win. This means the the revision with the most changes and therefore the highest revision ID will win. localWins - This will result in local revisions always being the winner in any conflict. remoteWins - This will result in remote revisions always being the winner in any conflict. custom - This will result in conflicts going through your own custom conflict resolver. You must provide this logic as a Javascript function in the `custom_conflict_resolver` parameter. This is an Enterprise Edition only feature. Note: replications created prior to Sync Gateway 2.8 will default to `default`.
custom_conflict_resolver	string Default: "none" This specifies the Javascript function to use to resolve conflicts between conflicting revisions. This must be used when `conflict_resolution_type=custom`. This property will be ignored when `conflict_resolution_type` is not `custom`. The Javascript function to provide this property should be in backticks (like the sync function). The function takes 1 parameter which is a struct that represents the conflict. This struct has 2 properties: `LocalDocument` - The local document. This contains the document ID under the `_id` key. `RemoteDocument` - The remote document The function should return the new documents body. This can be the winning revision (for example, `return conflict.LocalDocument`), a new body, or `nil` to resolve as a delete. Example: "custom_conflict_resolver":\` function(conflict) { console.log("Doc ID: "+conflict.LocalDocument._id); console.log("Full remote doc: "+JSON.stringify(conflict.RemoteDocument)); return conflict.RemoteDocument; } \` Using complex `custom_conflict_resolver` functions can noticeably degrade performance. Use a built-in resolver whenever possible. This is an Enterprise Edition only feature.
purge_on_removal	boolean Default: false Specifies whether to purge a document if the remote user loses access to all of the channels on the document when attempting to pull it from the remote. If false, documents will not be replicated and not be purged when the user loses access.
enable_delta_sync	boolean Default: false This will turn on delta- sync for the replication. This works in conjunction with the database level setting `delta_sync.enabled` If set to true, delta-sync will be used as long as both databases involved in the replication have delta-sync enabled. If a database does not have delta-sync enabled, then the replication will run without delta-sync. Replications created prior to Sync Gateway 2.8 must have delta-sync disabled. Enabling this is an Enterprise Edition only feature.
max_backoff_time	integer Default: 5 Specifies the maximum time-period (in minutes) that Sync Gateway will attempt to reconnect to a lost or unreachable remote. When a disconnection happens, Sync Gateway will do an exponential backoff up to this specified value. When this value is met, it will attempt to reconnect indefinitely every `max_backoff_time` minutes. If this is set to 0, Sync Gateway will do the normal exponential backoff after the disconnect happens but then attempting 10 minutes and stop the replication. Note: this defaults to 5 minutes for replications created prior to Sync Gateway 2.8.
initial_state	string Default: "running" Enum: "running" "stopped" This is what state to start the replication in when creating a new replication. This allows you to control if the replication starts in a `stopped` start or `running` state. Replications prior to Sync Gateway 2.8 will run in the default state `running`.
continuous	boolean Default: false If true, changes will be immediately synced when they happen. This is known as a continuous replication. If false, all changes will be synced until they have been processed. The replication will then cease and not process any future changes (unless started again by the user). This is known as a one-shot replication.
filter	string Value: "sync_gateway/bychannel" This defines whether to filter documents by their channels or not. If set to `sync_gateway/bychannel` then a pull replication will be limited to a specific set of channels specified by the `query_params.channels` property. This only can be used with pull replications.
query_params	Array of strings This is a set of key/value pairs used in the query string of the replication. If `filters=sync_gateway/bychannel` then this can be used to set the channels to filter by in a pull replication. To do this, set the `channels` key to a string array of the channels to filter by. For example: `"filter":"sync_gateway/bychannel", "query_params": { "channels":["chanUser1"] },`
adhoc	boolean Default: false Set to true to run the replication as an adhoc replication instead of a persistent one. This means that the replication will only last the period of the replication until the status is changed to `stopped` and then it will be removed automatically. It will also be removed if Sync Gateway restarts or if removed due to user action.
batch_size	integer Default: 200 The amount of changes to be sent in one batch of replications. Changing this is an Enterprise Edition only feature.
run_as	string This is used if you want to specify a user to run the replication as. This means that the replication will only be able to replicate what the user access to what the user has access to.
collections_enabled	boolean Default: false If true, the replicator will run with collections, and will replicate all collections, unless otherwise limited by `keyspace_map`. If false, the replicator will only replicate the default collection.
collections_local	Array of strings Default: [] Limits the set of collections replicated to those listed in this array. The replication will use all collections defined on the database if this list is empty.
collections_remote	Array of strings Default: [] Remaps the local collection name to the one specified in this array when replicating with the remote. If only a subset of collections need remapping, elements in this array can be specified as `null` to preserve the local collection name. The same index is used for both `collections_remote` and `collections_local`, and both arrays must be the same length.

Responses

Request samples

Payload

Content type

application/json

{"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"
]
}

Response samples

400
404

Content type

application/json

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

/{db}/_replication/

Required Sync Gateway RBAC roles:

Sync Gateway Replicator

path Parameters

db

required

string

Example: db1

The name of the database to run the operation against.

Responses

Get a replication configuration

Retrieve a replication configuration from the database.

Required Sync Gateway RBAC roles:

Sync Gateway Replicator

path Parameters

db required	string Example: db1 The name of the database to run the operation against.
replicationid required	string What replication to target based on its replication ID.

Responses

Response samples

200
404

Content type

application/json

{"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"
}

Upsert a replication

Create or update a replication in the database.

The replication ID does not need to be set in the request body.

If an existing replication is being updated, that replication must be stopped first and, if the replication_id is specified in the request body, it must match the replication ID in the URI.

Required Sync Gateway RBAC roles:

Sync Gateway Replicator

path Parameters

db required	string Example: db1 The name of the database to run the operation against.
replicationid required	string What replication to target based on its replication ID.

Request Body schema: application/json

If the replication_id matches an existing replication then the existing configuration will be updated. Only the specified fields in the request will be used to update the existing configuration. Unspecified fields will remain untouched.

replication_id	string This is the ID of the replication. When creating a new replication using a POST request, this will be set to a random UUID if not explicitly set. When the replication ID is specified in the URL, this must be set to the same replication ID if specifying it at all.
remote	string This is the endpoint of the database for the remote Sync Gateway that is the subject of this replication's `push`, `pull`, or `pushAndPull` action. Typically this would include the URI, port, and database name. For example, `http://localhost:4985/db`. How this remote is used depends on the `direction` of the replication: `pull` - this replicator pulls changes from the `remote` `push` - this replicator pushes changes to this `remote` `pushAndPull` - this replicator pushes changes to this `remote`, while also pulling receiving changes
username	string Deprecated This has been deprecated in favour of `remote_username`. This is the username to use to authenticate with the remote. This can only be used for a pull replication.
password	string Deprecated This has been deprecated in favour of `remote_password`. This is the password to use to authenticate with the remote. This password will be redacted in the replication config. This can only be used for a pull replication.
remote_username	string The username to use to authenticate with the remote. This can only be used for a pull replication.
remote_password	string The password to use to authenticate with the remote. This password will be redacted in the replication config. This can only be used for a pull replication.
direction required	string Enum: "push" "pull" "pushAndPull" This specifies which direction the replication will be replicating with the `remote` replicator. The directions are: `pull` - changes are pulled from the remote database `push` - changes are pushed to the remote database `pushAndPull` - changes are both push-to and pulled-from the remote database Replications created prior to Sync Gateway 2.8 derive their `direction` from the source/target URL of the replication.
conflict_resolution_type	string Default: "default" Enum: "default" "remoteWins" "localWins" "custom" This defines what conflict resolution policy Sync Gateway should use to apply when resolving conflicting revisions. Changing this is an Enterprise Edition only feature. Behaviour default - In priority order, this will cause Deletes to always win (the delete with the longest revision history wins if both revisions are deletes) The revision with the longest revision history to win. This means the the revision with the most changes and therefore the highest revision ID will win. localWins - This will result in local revisions always being the winner in any conflict. remoteWins - This will result in remote revisions always being the winner in any conflict. custom - This will result in conflicts going through your own custom conflict resolver. You must provide this logic as a Javascript function in the `custom_conflict_resolver` parameter. This is an Enterprise Edition only feature. Note: replications created prior to Sync Gateway 2.8 will default to `default`.
custom_conflict_resolver	string Default: "none" This specifies the Javascript function to use to resolve conflicts between conflicting revisions. This must be used when `conflict_resolution_type=custom`. This property will be ignored when `conflict_resolution_type` is not `custom`. The Javascript function to provide this property should be in backticks (like the sync function). The function takes 1 parameter which is a struct that represents the conflict. This struct has 2 properties: `LocalDocument` - The local document. This contains the document ID under the `_id` key. `RemoteDocument` - The remote document The function should return the new documents body. This can be the winning revision (for example, `return conflict.LocalDocument`), a new body, or `nil` to resolve as a delete. Example: "custom_conflict_resolver":\` function(conflict) { console.log("Doc ID: "+conflict.LocalDocument._id); console.log("Full remote doc: "+JSON.stringify(conflict.RemoteDocument)); return conflict.RemoteDocument; } \` Using complex `custom_conflict_resolver` functions can noticeably degrade performance. Use a built-in resolver whenever possible. This is an Enterprise Edition only feature.
purge_on_removal	boolean Default: false Specifies whether to purge a document if the remote user loses access to all of the channels on the document when attempting to pull it from the remote. If false, documents will not be replicated and not be purged when the user loses access.
enable_delta_sync	boolean Default: false This will turn on delta- sync for the replication. This works in conjunction with the database level setting `delta_sync.enabled` If set to true, delta-sync will be used as long as both databases involved in the replication have delta-sync enabled. If a database does not have delta-sync enabled, then the replication will run without delta-sync. Replications created prior to Sync Gateway 2.8 must have delta-sync disabled. Enabling this is an Enterprise Edition only feature.
max_backoff_time	integer Default: 5 Specifies the maximum time-period (in minutes) that Sync Gateway will attempt to reconnect to a lost or unreachable remote. When a disconnection happens, Sync Gateway will do an exponential backoff up to this specified value. When this value is met, it will attempt to reconnect indefinitely every `max_backoff_time` minutes. If this is set to 0, Sync Gateway will do the normal exponential backoff after the disconnect happens but then attempting 10 minutes and stop the replication. Note: this defaults to 5 minutes for replications created prior to Sync Gateway 2.8.
initial_state	string Default: "running" Enum: "running" "stopped" This is what state to start the replication in when creating a new replication. This allows you to control if the replication starts in a `stopped` start or `running` state. Replications prior to Sync Gateway 2.8 will run in the default state `running`.
continuous	boolean Default: false If true, changes will be immediately synced when they happen. This is known as a continuous replication. If false, all changes will be synced until they have been processed. The replication will then cease and not process any future changes (unless started again by the user). This is known as a one-shot replication.
filter	string Value: "sync_gateway/bychannel" This defines whether to filter documents by their channels or not. If set to `sync_gateway/bychannel` then a pull replication will be limited to a specific set of channels specified by the `query_params.channels` property. This only can be used with pull replications.
query_params	Array of strings This is a set of key/value pairs used in the query string of the replication. If `filters=sync_gateway/bychannel` then this can be used to set the channels to filter by in a pull replication. To do this, set the `channels` key to a string array of the channels to filter by. For example: `"filter":"sync_gateway/bychannel", "query_params": { "channels":["chanUser1"] },`
adhoc	boolean Default: false Set to true to run the replication as an adhoc replication instead of a persistent one. This means that the replication will only last the period of the replication until the status is changed to `stopped` and then it will be removed automatically. It will also be removed if Sync Gateway restarts or if removed due to user action.
batch_size	integer Default: 200 The amount of changes to be sent in one batch of replications. Changing this is an Enterprise Edition only feature.
run_as	string This is used if you want to specify a user to run the replication as. This means that the replication will only be able to replicate what the user access to what the user has access to.
collections_enabled	boolean Default: false If true, the replicator will run with collections, and will replicate all collections, unless otherwise limited by `keyspace_map`. If false, the replicator will only replicate the default collection.
collections_local	Array of strings Default: [] Limits the set of collections replicated to those listed in this array. The replication will use all collections defined on the database if this list is empty.
collections_remote	Array of strings Default: [] Remaps the local collection name to the one specified in this array when replicating with the remote. If only a subset of collections need remapping, elements in this array can be specified as `null` to preserve the local collection name. The same index is used for both `collections_remote` and `collections_local`, and both arrays must be the same length.

Responses

Request samples

Payload

Content type

application/json

{"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"
]
}

Response samples

400
404

Content type

application/json

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

Stop and delete a replication

This will delete a replication causing it to stop and no longer exist.

Required Sync Gateway RBAC roles:

Sync Gateway Replicator

path Parameters

db required	string Example: db1 The name of the database to run the operation against.
replicationid required	string What replication to target based on its replication ID.

Responses

Response samples

400
404

Content type

application/json

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

Check if a replication exists

Check if a replication exists.

Required Sync Gateway RBAC roles:

Sync Gateway Replicator

path Parameters

db required	string Example: db1 The name of the database to run the operation against.
replicationid required	string What replication to target based on its replication ID.

Responses

Get all replication statuses

Retrieve all the replication statuses in the Sync Gateway node.

Required Sync Gateway RBAC roles:

Sync Gateway Replicator

path Parameters

db

required

string

Example: db1

The name of the database to run the operation against.

query Parameters

activeOnly	boolean Default: "false" Only return replications that are actively running (`state=running`).
localOnly	boolean Default: "false" Only return replications that were started on the current Sync Gateway node.
includeError	boolean Default: "true" Include replications that have stopped due to an error (`state=error`).
includeConfig	boolean Default: "false" Include the replication configuration with each replicator status in the response.

Responses

Response samples

200
400

Content type

application/json

[{"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
}
]

/{db}/_replicationStatus/

Required Sync Gateway RBAC roles:

Sync Gateway Replicator

path Parameters

db

required

string

Example: db1

The name of the database to run the operation against.

Responses

Get replication status

Retrieve the status of a replication.

Required Sync Gateway RBAC roles:

Sync Gateway Replicator

path Parameters

db required	string Example: db1 The name of the database to run the operation against.
replicationid required	string What replication to target based on its replication ID.

query Parameters

activeOnly	boolean Default: "false" Only return replications that are actively running (`state=running`).
localOnly	boolean Default: "false" Only return replications that were started on the current Sync Gateway node.
includeError	boolean Default: "true" Include replications that have stopped due to an error (`state=error`).
includeConfig	boolean Default: "false" Include the replication configuration with each replicator status in the response.

Responses

Response samples

200
400
404

Content type

application/json

{"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
}

Control a replication state

Control the replication by changing its state.

This is done through the action query parameter, which has 3 valid values:

start - starts a stopped replication
stop - stops an active replication
reset - resets the replication checkpoint to 0. For bidirectional replication, both push and pull checkpoints are reset to 0. The replication must be stopped to use this.

Required Sync Gateway RBAC roles:

Sync Gateway Replicator

path Parameters

db required	string Example: db1 The name of the database to run the operation against.
replicationid required	string What replication to target based on its replication ID.

query Parameters

action

required

string

Enum: "start" "stop" "reset"

The target state to put the replicator into.

Responses

Response samples

200
400
404

Content type

application/json

{"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
}

Check if replication exists

Check if a replication exists.

Required Sync Gateway RBAC roles:

Sync Gateway Replicator

path Parameters

db required	string Example: db1 The name of the database to run the operation against.
replicationid required	string What replication to target based on its replication ID.

query Parameters

activeOnly	boolean Default: "false" Only return replications that are actively running (`state=running`).
localOnly	boolean Default: "false" Only return replications that were started on the current Sync Gateway node.
includeError	boolean Default: "true" Include replications that have stopped due to an error (`state=error`).
includeConfig	boolean Default: "false" Include the replication configuration with each replicator status in the response.

Responses

Response samples

400
404

Content type

application/json

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

Handle incoming BLIP Sync web socket request

This handles incoming BLIP Sync requests from either Couchbase Lite or another Sync Gateway node. The connection has to be upgradable to a websocket connection or else the request will fail.

Required Sync Gateway RBAC roles:

Sync Gateway Application

path Parameters

db

required

string

Example: db1

The name of the database to run the operation against.

query Parameters

client

string

Default: "cbl2"

Enum: "cbl2" "sgr2"

This is the client type that is making the BLIP Sync request. Used to control client-type specific replication behaviour.

Responses

Response samples

404
426

Content type

application/json

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

Metrics

Get Sync Gateway statistics

Get memory statistics

This will return the current Sync Gateway nodes memory statistics such as current memory usage.

Required Sync Gateway RBAC roles:

Sync Gateway Architect
Sync Gateway Dev Ops
External Stats Reader

Responses

Response samples

200

Content type

application/json

{"memstats": { }
}

Get all Sync Gateway statistics

This returns a snapshot of all metrics in Sync Gateway for debugging and monitoring purposes.

This includes per database stats, replication stats, and server stats.

Required Sync Gateway RBAC roles:

Sync Gateway Architect
Sync Gateway Dev Ops
External Stats Reader

Responses

Profiling

Generate information to help debug and fine-tune Sync Gateway

Create point-in-time profile

This endpoint allows you to create a pprof snapshot of the given type.

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

path Parameters

profilename

required

string

Enum: "heap" "block" "threadcreate" "mutex" "goroutine"

The handler to use for profiling.

Request Body schema: application/json

file	string This is the file to output the pprof profile at.

Responses

Request samples

Payload

Content type

application/json

{"file": "string"
}

Response samples

400
404

Content type

application/json

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

Start or Stop continuous CPU profiling

This endpoint allows you to start and stop continuous CPU profiling.

To start profiling the CPU, call this endpoint and supply a file to output the pprof file to.

To stop profiling, call this endpoint but don't supply the file in the body.

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

Request Body schema: application/json

file	string This is the file to output the pprof profile at.

Responses

Request samples

Payload

Content type

application/json

{"file": "string"
}

Response samples

400

Content type

application/json

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

Dump heap profile

This endpoint will dump a pprof heap profile.

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

Request Body schema: application/json

file	string This is the file to output the pprof profile at.

Responses

Request samples

Payload

Content type

application/json

{"file": "string"
}

Response samples

400

Content type

application/json

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

Get goroutine profile

Stack traces of all current goroutines.

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

query Parameters

seconds

integer

If set, collect a delta profile for the given duration, instead of a snapshot.

Responses

Get goroutine profile

Stack traces of all current goroutines.

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

query Parameters

seconds

integer

If set, collect a delta profile for the given duration, instead of a snapshot.

Responses

Get passed in command line parameters

Gets the command line parameters that was passed in to Sync Gateway which will include the binary, flags (if any) and startup configuration.

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

Responses

Get passed in command line parameters

Gets the command line parameters that was passed in to Sync Gateway which will include the binary, flags (if any) and startup configuration.

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

Responses

Get symbol pprof debug information

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

Responses

Get symbol pprof debug information

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

Responses

Get the heap pprof debug file

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

query Parameters

seconds

integer

If set, collect a delta profile for the given duration, instead of a snapshot.

Responses

Get the heap pprof debug file

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

query Parameters

seconds

integer

If set, collect a delta profile for the given duration, instead of a snapshot.

Responses

Get the profile pprof debug file

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

query Parameters

seconds

integer

If set, collect a delta profile for the given duration, instead of a snapshot.

Responses

Get the profile pprof debug file

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

query Parameters

seconds

integer

If set, collect a delta profile for the given duration, instead of a snapshot.

Responses

Get block profile

Returns stack traces that led to blocking on synchronization primitives.

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

query Parameters

seconds

integer >= 0

Default: 30

The amount of seconds to run the profiler for.

Responses

Response samples

403

Content type

application/json

{"error": "forbidden",
"reason": "Can only run one mutex profile at a time"
}

Get block profile

Returns stack traces that led to blocking on synchronization primitives.

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

query Parameters

seconds

integer >= 0

Default: 30

The amount of seconds to run the profiler for.

Responses

Response samples

403

Content type

application/json

{"error": "forbidden",
"reason": "Can only run one mutex profile at a time"
}

Get the threadcreate pprof debug file

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

Responses

Get the threadcreate pprof debug file

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

Responses

Get mutex profile

Returns stack traces of holders of contended mutexes.

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

query Parameters

seconds

integer >= 0

Default: 30

The amount of seconds to run the profiler for.

Responses

Response samples

403

Content type

application/json

{"error": "forbidden",
"reason": "Can only run one mutex profile at a time"
}

Get mutex profile

Returns stack traces of holders of contended mutexes.

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

query Parameters

seconds

integer >= 0

Default: 30

The amount of seconds to run the profiler for.

Responses

Response samples

403

Content type

application/json

{"error": "forbidden",
"reason": "Can only run one mutex profile at a time"
}

Get trace profile

Responds with the execution trace in binary form.

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

query Parameters

seconds

integer

Default: 1

Responses

Get trace profile

Responds with the execution trace in binary form.

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

query Parameters

seconds

integer

Default: 1

Responses

Get fgprof profile

A sampling Go profiler that allows you to analyze On-CPU as well as Off-CPU (e.g. I/O) time together.

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

query Parameters

seconds

integer >= 0

Default: 30

The amount of seconds to run the profiler for.

Responses

Get fgprof profile

A sampling Go profiler that allows you to analyze On-CPU as well as Off-CPU (e.g. I/O) time together.

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

query Parameters

seconds

integer >= 0

Default: 30

The amount of seconds to run the profiler for.

Responses

Unsupported

Endpoints that are not supported by Sync Gateway

Revision tree structure in Graphviz Dot format | Unsupported

This returns the Dot syntax of the revision tree for the document so that it can be rendered in to a PNG image using the Graphviz CLI tool.

To use:

Install the Graphviz tool. Using Brew, this can be done by calling brew install graphviz.
Save the response text from this endpoint to a file (for example, revtree.dot).
Render the PNG by calling dot -Tpng revtree.dot > revtree.png.

Required Sync Gateway RBAC roles:

Sync Gateway Application
Sync Gateway Application Read Only

Note: This endpoint is useful for debugging purposes only. It is not officially supported.

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.
docid required	string Example: doc1 The document ID to run the operation against.

Responses

Response samples

200
404

Content type

application/json

"digraph graphname{\"1-d4d949b7feafc8c31215684baa45b6cd\" -> \"2-4f3f24143ea43d85a9a340ac016fdfc4\"; }"

Flush the entire database bucket | Unsupported

This is unsupported

This will purge all documents.

The bucket will only be flushed if the unsupported database configuration option enable_couchbase_bucket_flush is set.

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
503

Content type

application/json

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

Dump a view | Unsupported

This is unsupported

This queries the view and outputs it as HTML.

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.
view required	string The view to target.

Responses

Response samples

404
500

Content type

application/json

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

Query a view on the default design document | Unsupported

This is unsupported

Query a view on the default Sync Gateway design document.

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.
view required	string The view to target.

query Parameters

inclusive_end	boolean Indicates whether the specified end key should be included in the result.
descending	boolean Return documents in descending order.
include_docs	boolean Only works when using Couchbase Server 3.0 and earlier. Indicates whether to include the full content of the documents in the response.
reduce	boolean Whether to execute a reduce function on the response or not.
group	boolean Group the results using the reduce function to a group or single row.
skip	integer Skip the specified number of documents before starting to return results.
limit	integer Return only the specified number of documents
group_level	integer Specify the group level to be used.
startkey_docid	string Return documents starting with the specified document identifier.
endkey_docid	string Stop returning records when the specified document identifier is reached.
stale	string Enum: "ok" "update_after" Allow the results from a stale view to be used, without triggering a rebuild of all views within the encompassing design document.
startkey	string Return records starting with the specified key.
endkey	string Stop returning records when this key is reached.
key	string Return only the document that matches the specified key.
keys	Array of strings An array of document ID strings to filter by.

Responses

Response samples

200
404

Content type

application/json

{"total_rows": 0,
"rows": [{"id": "string",
"key": { },
"value": { },
"doc": { }
}
],
"errors": [{"From": "string",
"Reason": "string"
}
]
}

Dump all the documents in a channel | Unsupported

This is unsupported

This queries a channel and displays all the document IDs and revisions that are in that channel.

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.
channel required	string The channel to dump all the documents from.

query Parameters

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.

Responses

Response samples

404

Content type

application/json

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

Disabled endpoint

This endpoint is disabled.

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

Get views of a design document | Unsupported

This is unsupported

Query a design document.

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.
ddoc required	string The design document name.

Responses

Response samples

200
404

Content type

application/json

{"language": "string",
"views": {"viewname1": {"map": "string",
"reduce": "string"
},
"viewname2": {"map": "string",
"reduce": "string"
}
},
"options": {"local_seq": "string",
"include_design": "string",
"raw": "string",
"index_xattr_on_deleted_docs": "string"
}
}

Update views of a design document | Unsupported

This is unsupported

Update the views of a design document.

Required Sync Gateway RBAC roles:

Sync Gateway Application

path Parameters

db required	string Example: db1 The name of the database to run the operation against.
ddoc required	string The design document name.

Request Body schema: application/json

language	string
	object
	object

Responses

Request samples

Payload

Content type

application/json

{"language": "string",
"views": {"viewname1": {"map": "string",
"reduce": "string"
},
"viewname2": {"map": "string",
"reduce": "string"
}
},
"options": {"local_seq": "string",
"include_design": "string",
"raw": "string",
"index_xattr_on_deleted_docs": "string"
}
}

Response samples

404

Content type

application/json

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

Delete a design document | Unsupported

This is unsupported

Delete a design document.

Required Sync Gateway RBAC roles:

Sync Gateway Application

path Parameters

db required	string Example: db1 The name of the database to run the operation against.
ddoc required	string The design document name.

Responses

Response samples

404

Content type

application/json

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

Check if view of design document exists | Unsupported

This is unsupported

Check if a design document can be queried.

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.
ddoc required	string The design document name.

Responses

Response samples

404

Content type

application/json

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

Query a view on a design document | Unsupported

This is unsupported

Query a view on a design document.

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.
ddoc required	string The design document name.
view required	string The view to target.

query Parameters

inclusive_end	boolean Indicates whether the specified end key should be included in the result.
descending	boolean Return documents in descending order.
include_docs	boolean Only works when using Couchbase Server 3.0 and earlier. Indicates whether to include the full content of the documents in the response.
reduce	boolean Whether to execute a reduce function on the response or not.
group	boolean Group the results using the reduce function to a group or single row.
skip	integer Skip the specified number of documents before starting to return results.
limit	integer Return only the specified number of documents
group_level	integer Specify the group level to be used.
startkey_docid	string Return documents starting with the specified document identifier.
endkey_docid	string Stop returning records when the specified document identifier is reached.
stale	string Enum: "ok" "update_after" Allow the results from a stale view to be used, without triggering a rebuild of all views within the encompassing design document.
startkey	string Return records starting with the specified key.
endkey	string Stop returning records when this key is reached.
key	string Return only the document that matches the specified key.
keys	Array of strings An array of document ID strings to filter by.

Responses

Response samples

200
404

Content type

application/json

{"total_rows": 0,
"rows": [{"id": "string",
"key": { },
"value": { },
"doc": { }
}
],
"errors": [{"From": "string",
"Reason": "string"
}
]
}