Admin REST API (Static Page)
Description of the Sync Gateway Admin REST API, alternative representation as a static page
Related REST API topics: Public REST API (Static Page) | Metrics REST API (Static Page)
Resources
This section describes the operations available with this REST API. The operations are grouped in the following categories.
Authentication
Manage authentication
OpenID Connect authentication initiation via Location header redirect
GET /{db}/_oidc
Description
Called by clients to initiate the OpenID Connect Authorization Code Flow. Redirects to the OpenID Connect provider if successful.
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
db |
The name of the database to run the operation against. |
String |
Query Parameters
| Name | Description | Schema |
|---|---|---|
provider |
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. |
String |
offline |
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. |
String |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
302 |
Successfully connected with the OpenID Connect provider so now redirecting to the requested OIDC provider for authentication. |
|
400 |
The provider provided is not defined in the Sync Gateway config. If no provided was specified then there is no default provider set. |
|
404 |
Resource could not be found |
|
500 |
Unable to connect and validate with the OpenID Connect provider requested |
OpenID Connect authentication callback
GET /{db}/_oidc_callback
Description
The callback URL that the client is redirected to after authenticating with the OpenID Connect provider.
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
db |
The name of the database to run the operation against. |
String |
Query Parameters
| Name | Description | Schema |
|---|---|---|
error |
The OpenID Connect error, if any occurred. |
String |
code |
The OpenID Connect authentication code. |
String |
provider |
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. |
String |
state |
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 |
String |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
Successfully authenticated with OpenID Connect. |
|
400 |
A problem occurred when reading the callback request body |
|
401 |
An error was received from the OpenID Connect provider. This means the error query parameter was filled. |
|
404 |
Resource could not be found |
|
500 |
A problem occurred in regards to the token |
OpenID Connect authentication initiation via WWW-Authenticate header
GET /{db}/_oidc_challenge
Description
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.
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
db |
The name of the database to run the operation against. |
String |
Query Parameters
| Name | Description | Schema |
|---|---|---|
provider |
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. |
String |
offline |
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. |
String |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
400 |
The provider provided is not defined in the Sync Gateway config. If no provided was specified then there is no default provider set. |
|
401 |
Successfully connected with the OpenID Connect provider so now the client can login. |
|
404 |
Resource could not be found |
|
500 |
Unable to connect and validate with the OpenID Connect provider requested |
OpenID Connect token refresh
GET /{db}/_oidc_refresh
Parameters
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
Successfully authenticated with OpenID Connect. |
|
400 |
The provider provided is not defined in the Sync Gateway config. If no provided was specified then there is no default provider set. |
|
404 |
Resource could not be found |
|
500 |
Unable to connect and validate with the OpenID Connect provider requested |
OpenID Connect mock provider
GET /{db}/_oidc_testing/.well-known/openid-configuration
Description
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.
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
Successfully generated OpenID Connect provider mock response. |
get_db__oidc_testing__well_known_openid_configuration_200_response |
403 |
The OpenID Connect unsupported config option |
|
404 |
Resource could not be found |
OpenID Connect mock login page handler
GET /{db}/_oidc_testing/authenticate
Description
Used to handle the login page displayed for the GET /{db}/_oidc_testing/authorize endpoint.
Parameters
OpenID Connect mock login page
GET /{db}/_oidc_testing/authorize
Parameters
OpenID Connect public certificates for signing keys
GET /{db}/_oidc_testing/certs
Create a new Facebook-based session
POST /{db}/_facebook
Description
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.
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
db |
The name of the database to run the operation against. |
String |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
Session created successfully |
|
400 |
Origin is not in the approved list of allowed origins |
|
401 |
Received error from Facebook verifier |
|
404 |
Resource could not be found |
|
502 |
Received invalid response from the Facebook verifier |
|
504 |
Unable to send request to Facebook API |
Create a new Google-based session
POST /{db}/_google
Description
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.
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
db |
The name of the database to run the operation against. |
String |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
Session created successfully |
|
400 |
Origin is not in the approved list of allowed origins |
|
401 |
Received error from Google token verifier or invalid application ID in the config |
|
404 |
Resource could not be found |
|
502 |
Received invalid response from the Google token verifier |
|
504 |
Unable to send request to the Google token verifier |
OpenID Connect mock login page handler
POST /{db}/_oidc_testing/authenticate
Description
Used to handle the login page displayed for the GET /{db}/_oidc_testing/authorize endpoint.
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
db |
The name of the database to run the operation against. |
String |
OpenID Connect mock login page
POST /{db}/_oidc_testing/authorize
Parameters
OpenID Connect mock token
POST /{db}/_oidc_testing/token
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
db |
The name of the database to run the operation against. |
String |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
Properties expected back from an OpenID Connect provider after successful authentication |
|
400 |
Invalid token provided |
|
403 |
The OpenID Connect unsupported config option |
|
404 |
Resource could not be found |
Database Configuration
Configure Sync Gateway databases
Delete import filter
DELETE /{keyspace}/_config/import_filter
Description
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
Parameters
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
Successfully deleted the import filter |
|
404 |
Resource could not be found |
|
412 |
Precondition Failed The supplied If-Match header did not match the current version of the configuration. Returned when optimistic concurrency control is used, and there has been an update to the configuration in between this update. |
Remove custom sync function
DELETE /{keyspace}/_config/sync
Description
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
Parameters
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
Successfully reset the sync function |
|
404 |
Resource could not be found |
|
412 |
Precondition Failed The supplied If-Match header did not match the current version of the configuration. Returned when optimistic concurrency control is used, and there has been an update to the configuration in between this update. |
Get database configuration
GET /{db}/_config
Description
Retrieve the full configuration for the database specified.
Required Sync Gateway RBAC roles:
- Sync Gateway Architect
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
db |
The name of the database to run the operation against. |
String |
Query Parameters
| Name | Description | Schema |
|---|---|---|
redact |
No longer supported field. Default: |
Boolean |
include_javascript |
Include the fields that have Javascript functions in the response. E.g. sync function, import filter, and event handlers. Default: |
Boolean |
include_runtime |
Whether to include the values set at runtime, and default values. Default: |
Boolean |
refresh_config |
Forces the configuration to be reloaded on the Sync Gateway node. Default: |
Boolean |
Get database import filter
GET /{keyspace}/_config/import_filter
Description
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
Get database sync function
GET /{keyspace}/_config/sync
Description
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
Update database configuration
POST /{db}/_config
Description
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
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
db |
The name of the database to run the operation against. |
String |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
201 |
Database configuration successfully updated |
|
400 |
There was a problem with your request |
|
404 |
Not Found |
|
412 |
Precondition Failed The supplied If-Match header did not match the current version of the configuration. Returned when optimistic concurrency control is used, and there has been an update to the configuration in between this update. |
Replace database configuration
PUT /{db}/_config
Description
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
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
db |
The name of the database to run the operation against. |
String |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
201 |
Database configuration successfully updated |
|
400 |
There was a problem with your request |
|
404 |
Resource could not be found |
|
412 |
Precondition Failed The supplied If-Match header did not match the current version of the configuration. Returned when optimistic concurrency control is used, and there has been an update to the configuration in between this update. |
Set database import filter
PUT /{keyspace}/_config/import_filter
Description
This will allow you to update the database's import filter.
Required Sync Gateway RBAC roles:
- Sync Gateway Architect
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
keyspace |
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. |
String |
Body Parameter
| Name | Description | Schema |
|---|---|---|
Body |
The import filter to use Example: |
String |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
Updated import filter successfully |
|
400 |
There was a problem with your request |
|
404 |
Resource could not be found |
|
412 |
Precondition Failed The supplied If-Match header did not match the current version of the configuration. Returned when optimistic concurrency control is used, and there has been an update to the configuration in between this update. |
Set database sync function
PUT /{keyspace}/_config/sync
Description
This will allow you to update the sync function.
Required Sync Gateway RBAC roles:
- Sync Gateway Architect
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
keyspace |
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. |
String |
Body Parameter
| Name | Description | Schema |
|---|---|---|
Body |
The new sync function to use ifeval::["function (doc, oldDoc) { |
String |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
Updated sync function successfully |
|
400 |
There was a problem with your request |
|
404 |
Resource could not be found |
|
412 |
Precondition Failed The supplied If-Match header did not match the current version of the configuration. Returned when optimistic concurrency control is used, and there has been an update to the configuration in between this update. |
Database Management
Create and manage Sync Gateway databases
Remove a database
DELETE /{db}/
Description
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
Get a list of all the databases
GET /_all_dbs
Description
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
Get database information
GET /{db}/
Description
Retrieve information about the database.
Required Sync Gateway RBAC roles:
- Sync Gateway Dev Ops
Get the status of the most recent compact operation
GET /{db}/_compact
Description
This will retrieve the current status of the most recent compact operation.
Required Sync Gateway RBAC roles:
- Sync Gateway Architect
Parameters
Get resync status
GET /{db}/_resync
Description
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
Get changes list
GET /{keyspace}/_changes
Description
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
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
keyspace |
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. |
String |
Query Parameters
| Name | Description | Schema |
|---|---|---|
limit |
Maximum number of changes to return. |
Integer |
since |
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. |
String |
style |
Controls whether to return the current winning revision ( Values: |
String |
active_only |
Set true to exclude deleted documents and notifications for documents the user no longer has access to from the changes feed. Default: |
Boolean |
include_docs |
Include the body associated with each document. |
String |
revocations |
If true, revocation messages will be sent on the changes feed. |
Boolean |
filter |
Set a filter to either filter by channels or document IDs. Values: |
String |
channels |
A comma-separated list of channel names to filter the response to only the channels specified. To use this option, the |
String |
doc_ids |
A valid JSON array of document IDs to filter the documents in the response to only the documents specified. To use this option, the |
String List |
heartbeat |
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 Default: |
Integer |
timeout |
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 Default: |
Integer |
feed |
The type of changes feed to use. Values: |
String |
request_plus |
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. Default: |
Boolean |
Check if database exists
HEAD /{db}/
Description
Check if a database exists by using the response status code.
Required Sync Gateway RBAC roles:
- Sync Gateway Dev Ops
/{db}/_changes
HEAD /{keyspace}/_changes
Description
Required Sync Gateway RBAC roles:
- Sync Gateway Application
- Sync Gateway Application Read Only
Manage a compact operation
POST /{db}/_compact
Description
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 thecompact_idat 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
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
db |
The name of the database to run the operation against. |
String |
Query Parameters
| Name | Description | Schema |
|---|---|---|
type |
This is the type of compaction to use. The type must be either:
Values: |
String |
action |
Defines whether the a compact operation is being started or stopped. Values: |
String |
reset |
Attachment compaction only This forces a fresh compact start instead of trying to resume the previous failed compact operation. |
Boolean |
dry_run |
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.' |
Boolean |
/{db}/_ensure_full_commit
POST /{db}/_ensure_full_commit
Description
This endpoint is non-functional but is present for CouchDB compatibility.
Required Sync Gateway RBAC roles:
- Sync Gateway Application
- Sync Gateway Application Read Only
Take the database offline
POST /{db}/_offline
Description
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
_changesfeeds 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, andPOST /{db}/_online. - Stops webhook event handlers.
Required Sync Gateway RBAC roles:
- Sync Gateway Architect
Bring the database online
POST /{db}/_online
Description
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
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
db |
The name of the database to run the operation against. |
String |
Start or stop Resync
POST /{db}/_resync
Description
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
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
db |
The name of the database to run the operation against. |
String |
Query Parameters
| Name | Description | Schema |
|---|---|---|
action |
This is whether to start a new resync job or stop an existing one. Values: |
String |
regenerate_sequences |
Use this only when requested to do so by the Couchbase support team This request will regenerate the sequence numbers for each document processed. |
Boolean |
reset |
This forces a fresh resync run instead of trying to resume the previous resync operation Default: |
Boolean |
Get changes list
POST /{keyspace}/_changes
Description
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
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
keyspace |
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. |
String |
Compare revisions to what is in the database
POST /{keyspace}/_revs_diff
Description
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
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
keyspace |
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. |
String |
Create a new Sync Gateway database
PUT /{db}/
Description
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
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
db |
The name of the database to run the operation against. |
String |
Database Security
Create and manage database users and roles
Delete a role
DELETE /{db}/_role/{name}
Description
Delete a role from the database.
Required Sync Gateway RBAC roles:
- Sync Gateway Architect
- Sync Gateway Application
Delete a user
DELETE /{db}/_user/{name}
Description
Delete a user from the database.
Required Sync Gateway RBAC roles:
- Sync Gateway Architect
- Sync Gateway Application
Get all names of the roles
GET /{db}/_role/
Description
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
Parameters
Get a role
GET /{db}/_role/{name}
Description
Retrieve a single roles properties.
Required Sync Gateway RBAC roles:
- Sync Gateway Architect
- Sync Gateway Application
- Sync Gateway Application Read Only
Get all the names of the users
GET /{db}/_user/
Description
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
Parameters
Get a user
GET /{db}/_user/{name}
Description
Retrieve a single users information.
Required Sync Gateway RBAC roles:
- Sync Gateway Architect
- Sync Gateway Application
- Sync Gateway Application Read Only
/{db}/_role/
HEAD /{db}/_role/
Description
Required Sync Gateway RBAC roles:
- Sync Gateway Architect
- Sync Gateway Application
- Sync Gateway Application Read Only
Check if role exists
HEAD /{db}/_role/{name}
Description
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
/{db}/_user/
HEAD /{db}/_user/
Description
Required Sync Gateway RBAC roles:
- Sync Gateway Architect
- Sync Gateway Application
- Sync Gateway Application Read Only
Check if user exists
HEAD /{db}/_user/{name}
Description
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
Create a new role
POST /{db}/_role/
Description
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
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
db |
The name of the database to run the operation against. |
String |
Create a new user
POST /{db}/_user/
Description
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
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
db |
The name of the database to run the operation against. |
String |
Upsert a role
PUT /{db}/_role/{name}
Description
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
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
db |
The name of the database to run the operation against. |
String |
name |
The name of the role. |
String |
Upsert a user
PUT /{db}/_user/{name}
Description
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
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
db |
The name of the database to run the operation against. |
String |
name |
The name of the user. |
String |
Document
Create and manage documents and attachments
Delete a document
DELETE /{keyspace}/{docid}
Description
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
Parameters
Delete an attachment on a document
DELETE /{keyspace}/{docid}/{attach}
Description
This request deletes an attachment associated with the document.
If the attachment exists, the attachment will be removed from the document.
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
keyspace |
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. |
String |
docid |
The document ID to run the operation against. |
String |
attach |
The attachment name. This value must be URL encoded. For example, if the attachment name is |
String |
Delete a local document
DELETE /{keyspace}/_local/{docid}
Description
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
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
keyspace |
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. |
String |
docid |
The name of the local document ID excluding the |
String |
Gets all the documents in the database with the given parameters
GET /{keyspace}/_all_docs
Description
Returns all documents in the databased based on the specified parameters.
Required Sync Gateway RBAC roles:
- Sync Gateway Application
- Sync Gateway Application Read Only
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
keyspace |
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. |
String |
Query Parameters
| Name | Description | Schema |
|---|---|---|
include_docs |
Include the body associated with each document. |
String |
channels |
Include the channels each document is part of that the calling user also has access too. |
String |
access |
Include what user/roles that each document grants access too. |
String |
revs |
Include all the revisions for each document under the |
String |
update_seq |
Include the document sequence number |
String |
keys |
An array of document ID strings to filter by. |
String List |
startkey |
Return records starting with the specified key. |
String |
endkey |
Stop returning records when this key is reached. |
String |
limit |
This limits the number of result rows returned. Using a value of |
BigDecimal |
Get a document
GET /{keyspace}/{docid}
Description
Retrieve a document from the database by its doc ID.
Required Sync Gateway RBAC roles:
- Sync Gateway Application
- Sync Gateway Application Read Only
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
keyspace |
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. |
String |
docid |
The document ID to run the operation against. |
String |
Query Parameters
| Name | Description | Schema |
|---|---|---|
rev |
The document revision to target. |
String |
open_revs |
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 |
String List |
show_exp |
Whether to show the expiry property ( |
Boolean |
revs_from |
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 |
String List |
atts_since |
Include attachments only since specified revisions. Excludes the attachments for the specified revisions. Only gets used if |
String List |
revs_limit |
Maximum amount of revisions to return for each document. |
Integer |
attachments |
Include attachment bodies in response. |
Boolean |
replicator2 |
Returns the document with the required properties for replication. This is an enterprise-edition only feature. |
Boolean |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
Document found and returned successfully |
|
400 |
Document ID is not in an allowed format therefore is invalid. This could be because it is over 250 characters or is prefixed with an underscore (\"_\"). |
|
404 |
Resource could not be found |
|
501 |
Not Implemented. It is likely this error was caused due to trying to use an enterprise-only feature on the community edition. |
Get an attachment from a document
GET /{keyspace}/{docid}/{attach}
Description
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
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
keyspace |
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. |
String |
docid |
The document ID to run the operation against. |
String |
attach |
The attachment name. This value must be URL encoded. For example, if the attachment name is |
String |
Query Parameters
| Name | Description | Schema |
|---|---|---|
rev |
The document revision to target. |
String |
content_encoding |
Set to false to disable the Default: |
Boolean |
meta |
Return only the metadata of the attachment in the response body. Default: |
Boolean |
Get local document
GET /{keyspace}/_local/{docid}
Description
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
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
keyspace |
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. |
String |
docid |
The name of the local document ID excluding the |
String |
Get a document with the corresponding metadata
GET /{keyspace}/_raw/{docid}
Description
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
Parameters
/{db}/_all_docs
HEAD /{keyspace}/_all_docs
Description
Required Sync Gateway RBAC roles:
- Sync Gateway Application
- Sync Gateway Application Read Only
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
keyspace |
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. |
String |
Query Parameters
| Name | Description | Schema |
|---|---|---|
include_docs |
Include the body associated with each document. |
String |
channels |
Include the channels each document is part of that the calling user also has access too. |
String |
access |
Include what user/roles that each document grants access too. |
String |
revs |
Include all the revisions for each document under the |
String |
update_seq |
Include the document sequence number |
String |
keys |
An array of document ID strings to filter by. |
String List |
startkey |
Return records starting with the specified key. |
String |
endkey |
Stop returning records when this key is reached. |
String |
limit |
This limits the number of result rows returned. Using a value of |
BigDecimal |
Check if a document exists
HEAD /{keyspace}/{docid}
Description
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
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
keyspace |
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. |
String |
docid |
The document ID to run the operation against. |
String |
Query Parameters
| Name | Description | Schema |
|---|---|---|
rev |
The document revision to target. |
String |
open_revs |
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 |
String List |
show_exp |
Whether to show the expiry property ( |
Boolean |
revs_from |
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 |
String List |
atts_since |
Include attachments only since specified revisions. Excludes the attachments for the specified revisions. Only gets used if |
String List |
revs_limit |
Maximum amount of revisions to return for each document. |
Integer |
attachments |
Include attachment bodies in response. |
Boolean |
replicator2 |
Returns the document with the required properties for replication. This is an enterprise-edition only feature. |
Boolean |
Check if attachment exists
HEAD /{keyspace}/{docid}/{attach}
Description
This request check if the attachment exists on the specified document.
Required Sync Gateway RBAC roles:
- Sync Gateway Application
- Sync Gateway Application Read Only
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
keyspace |
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. |
String |
docid |
The document ID to run the operation against. |
String |
attach |
The attachment name. This value must be URL encoded. For example, if the attachment name is |
String |
Check if local document exists
HEAD /{keyspace}/_local/{docid}
Description
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
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
keyspace |
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. |
String |
docid |
The name of the local document ID excluding the |
String |
/{keyspace}/_raw/{docid}
HEAD /{keyspace}/_raw/{docid}
Description
Required Sync Gateway RBAC roles:
- Sync Gateway Application
- Sync Gateway Application Read Only
Create a new document
POST /{keyspace}/
Description
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.
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
keyspace |
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. |
String |
Get all the documents in the database using a built-in view
POST /{keyspace}/_all_docs
Description
Get a built-in view of all the documents in the database.
Required Sync Gateway RBAC roles:
- Sync Gateway Application
- Sync Gateway Application Read Only
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
keyspace |
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. |
String |
Query Parameters
| Name | Description | Schema |
|---|---|---|
include_docs |
Include the body associated with each document. |
String |
channels |
Include the channels each document is part of that the calling user also has access too. |
String |
access |
Include what user/roles that each document grants access too. |
String |
revs |
Include all the revisions for each document under the |
String |
update_seq |
Include the document sequence number |
String |
startkey |
Return records starting with the specified key. |
String |
endkey |
Stop returning records when this key is reached. |
String |
limit |
This limits the number of result rows returned. Using a value of |
BigDecimal |
Bulk document operations
POST /{keyspace}/_bulk_docs
Description
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
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
keyspace |
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. |
String |
Get multiple documents in a MIME multipart response
POST /{keyspace}/_bulk_get
Description
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
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
keyspace |
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. |
String |
Body Parameter
| Name | Description | Schema |
|---|---|---|
Body |
Example: |
Header Parameters
| Name | Description | Schema |
|---|---|---|
X-Accept-Part-Encoding |
If this header includes |
String |
Accept-Encoding |
If this header includes |
String |
Query Parameters
| Name | Description | Schema |
|---|---|---|
attachments |
This is for whether to include attachments in each of the documents returned or not. Default: |
Boolean |
revs |
Include all the revisions for each document under the |
String |
revs_limit |
The number of revisions to include in the response from the document history. This parameter only makes a different if the |
Integer |
Purge a document
POST /{keyspace}/_purge
Description
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
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
keyspace |
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. |
String |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
Attempted documents purge. Check output to verify the documents that were purged. The document IDs will not be listed if they have not been purged (for example, due to no existing). |
|
400 |
Bad request. This could be due to the documents listed in the request body not having the |
|
404 |
Resource could not be found |
Upsert a document
PUT /{keyspace}/{docid}
Description
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
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
keyspace |
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. |
String |
docid |
The document ID to run the operation against. |
String |
Query Parameters
| Name | Description | Schema |
|---|---|---|
roundtrip |
Block until document has been received by change cache |
Boolean |
replicator2 |
Returns the document with the required properties for replication. This is an enterprise-edition only feature. |
Boolean |
new_edits |
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 Default: |
Boolean |
rev |
The document revision to target. |
String |
Create or update an attachment on a document
PUT /{keyspace}/{docid}/{attach}
Description
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
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
keyspace |
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. |
String |
docid |
The document ID to run the operation against. |
String |
attach |
The attachment name. This value must be URL encoded. For example, if the attachment name is |
String |
Body Parameter
| Name | Description | Schema |
|---|---|---|
Body |
The attachment data Example: |
String |
Upsert a local document
PUT /{keyspace}/_local/{docid}
Description
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
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
keyspace |
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. |
String |
docid |
The name of the local document ID excluding the |
String |
Metrics
Get Sync Gateway statistics
Get all Sync Gateway statistics
GET /_expvar
Description
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
Get memory statistics
GET /_stats
Description
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
Profiling
Generate information to help debug and fine-tune Sync Gateway
Get fgprof profile
GET /_debug/fgprof
Description
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
Get block profile
GET /_debug/pprof/block
Description
Returns stack traces that led to blocking on synchronization primitives.
Required Sync Gateway RBAC roles:
- Sync Gateway Dev Ops
Get passed in command line parameters
GET /_debug/pprof/cmdline
Description
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
Get goroutine profile
GET /_debug/pprof/goroutine
Description
Stack traces of all current goroutines.
Required Sync Gateway RBAC roles:
- Sync Gateway Dev Ops
Get the heap pprof debug file
GET /_debug/pprof/heap
Get mutex profile
GET /_debug/pprof/mutex
Description
Returns stack traces of holders of contended mutexes.
Required Sync Gateway RBAC roles:
- Sync Gateway Dev Ops
Get the profile pprof debug file
GET /_debug/pprof/profile
Get symbol pprof debug information
GET /_debug/pprof/symbol
Get the threadcreate pprof debug file
GET /_debug/pprof/threadcreate
Get trace profile
GET /_debug/pprof/trace
Description
Responds with the execution trace in binary form.
Required Sync Gateway RBAC roles:
- Sync Gateway Dev Ops
Get fgprof profile
POST /_debug/fgprof
Description
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
Get block profile
POST /_debug/pprof/block
Description
Returns stack traces that led to blocking on synchronization primitives.
Required Sync Gateway RBAC roles:
- Sync Gateway Dev Ops
Get passed in command line parameters
POST /_debug/pprof/cmdline
Description
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
Get goroutine profile
POST /_debug/pprof/goroutine
Description
Stack traces of all current goroutines.
Required Sync Gateway RBAC roles:
- Sync Gateway Dev Ops
Get the heap pprof debug file
POST /_debug/pprof/heap
Get mutex profile
POST /_debug/pprof/mutex
Description
Returns stack traces of holders of contended mutexes.
Required Sync Gateway RBAC roles:
- Sync Gateway Dev Ops
Get the profile pprof debug file
POST /_debug/pprof/profile
Get symbol pprof debug information
POST /_debug/pprof/symbol
Get the threadcreate pprof debug file
POST /_debug/pprof/threadcreate
Get trace profile
POST /_debug/pprof/trace
Description
Responds with the execution trace in binary form.
Required Sync Gateway RBAC roles:
- Sync Gateway Dev Ops
Dump heap profile
POST /_heap
Description
This endpoint will dump a pprof heap profile.
Required Sync Gateway RBAC roles:
- Sync Gateway Dev Ops
Start or Stop continuous CPU profiling
POST /_profile
Description
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
Create point-in-time profile
POST /_profile/{profilename}
Description
This endpoint allows you to create a pprof snapshot of the given type.
Required Sync Gateway RBAC roles:
- Sync Gateway Dev Ops
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
profilename |
The handler to use for profiling. Values: |
String |
Replication
Create and manage inter-Sync Gateway replications
Stop and delete a replication
DELETE /{db}/_replication/{replicationid}
Description
This will delete a replication causing it to stop and no longer exist.
Required Sync Gateway RBAC roles:
- Sync Gateway Replicator
Handle incoming BLIP Sync web socket request
GET /{db}/_blipsync
Description
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
Parameters
Get all replication configurations
GET /{db}/_replication/
Description
This will retrieve all database replication definitions.
Required Sync Gateway RBAC roles:
- Sync Gateway Replicator
Get a replication configuration
GET /{db}/_replication/{replicationid}
Description
Retrieve a replication configuration from the database.
Required Sync Gateway RBAC roles:
- Sync Gateway Replicator
Get all replication statuses
GET /{db}/_replicationStatus/
Description
Retrieve all the replication statuses in the Sync Gateway node.
Required Sync Gateway RBAC roles:
- Sync Gateway Replicator
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
db |
The name of the database to run the operation against. |
String |
Query Parameters
| Name | Description | Schema |
|---|---|---|
activeOnly |
Only return replications that are actively running ( Default: |
Boolean |
localOnly |
Only return replications that were started on the current Sync Gateway node. Default: |
Boolean |
includeError |
Include replications that have stopped due to an error ( Default: |
Boolean |
includeConfig |
Include the replication configuration with each replicator status in the response. Default: |
Boolean |
Get replication status
GET /{db}/_replicationStatus/{replicationid}
Description
Retrieve the status of a replication.
Required Sync Gateway RBAC roles:
- Sync Gateway Replicator
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
db |
The name of the database to run the operation against. |
String |
replicationid |
What replication to target based on its replication ID. |
String |
Query Parameters
| Name | Description | Schema |
|---|---|---|
activeOnly |
Only return replications that are actively running ( Default: |
Boolean |
localOnly |
Only return replications that were started on the current Sync Gateway node. Default: |
Boolean |
includeError |
Include replications that have stopped due to an error ( Default: |
Boolean |
includeConfig |
Include the replication configuration with each replicator status in the response. Default: |
Boolean |
Check if a replication exists
HEAD /{db}/_replication/{replicationid}
Description
Check if a replication exists.
Required Sync Gateway RBAC roles:
- Sync Gateway Replicator
Check if replication exists
HEAD /{db}/_replicationStatus/{replicationid}
Description
Check if a replication exists.
Required Sync Gateway RBAC roles:
- Sync Gateway Replicator
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
db |
The name of the database to run the operation against. |
String |
replicationid |
What replication to target based on its replication ID. |
String |
Query Parameters
| Name | Description | Schema |
|---|---|---|
activeOnly |
Only return replications that are actively running ( Default: |
Boolean |
localOnly |
Only return replications that were started on the current Sync Gateway node. Default: |
Boolean |
includeError |
Include replications that have stopped due to an error ( Default: |
Boolean |
includeConfig |
Include the replication configuration with each replicator status in the response. Default: |
Boolean |
Upsert a replication
POST /{db}/_replication/
Description
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
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
db |
The name of the database to run the operation against. |
String |
Upsert a replication
PUT /{db}/_replication/{replicationid}
Description
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
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
db |
The name of the database to run the operation against. |
String |
replicationid |
What replication to target based on its replication ID. |
String |
Control a replication state
PUT /{db}/_replicationStatus/{replicationid}
Description
Control the replication by changing its state.
This is done through the action query parameter, which has 3 valid values:
start- starts a stopped replicationstop- stops an active replicationreset- 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
Parameters
Server
Manage server activities
Cancel the Sync Gateway Collect Info job
DELETE /_sgcollect_info
Description
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
Get server configuration
GET /_config
Description
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
Get console logging settings
GET /_logging
Description
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
Get the status of the Sync Gateway Collect Info
GET /_sgcollect_info
Description
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
Get the server status
GET /_status
Description
This will retrieve the status of each database and the overall server status.
Required Sync Gateway RBAC roles:
- Sync Gateway Dev Ops
Update console logging settings
POST /_logging
Description
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
Parameters
Query Parameters
| Name | Description | Schema |
|---|---|---|
logLevel |
The is what to set the console log level too. Values: |
String |
level |
Deprecated: use log level instead. This sets the console log level depending on the value provide. 1 sets to Minimum: |
Integer |
Run the post upgrade process on all databases
POST /_post_upgrade
Description
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
Start Sync Gateway Collect Info
POST /_sgcollect_info
Description
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
Set runtime configuration
PUT /_config
Description
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
Set console logging settings
PUT /_logging
Description
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
Parameters
Body Parameter
| Name | Description | Schema |
|---|---|---|
Body |
The map of log keys to use for console logging. |
Boolean Map |
Query Parameters
| Name | Description | Schema |
|---|---|---|
logLevel |
The is what to set the console log level too. Values: |
String |
level |
Deprecated: use log level instead. This sets the console log level depending on the value provide. 1 sets to Minimum: |
Integer |
Session
Manage user sessions
Remove session
DELETE /{db}/_session/{sessionid}
Description
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
Remove all of a users sessions
DELETE /{db}/_user/{name}/_session
Description
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
Remove session with user validation
DELETE /{db}/_user/{name}/_session/{sessionid}
Description
Invalidates the session only if it belongs to the user.
Required Sync Gateway RBAC roles:
- Sync Gateway Architect
- Sync Gateway Application
Get information about the current user
GET /{db}/_session
Get session information
GET /{db}/_session/{sessionid}
Description
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
/{db}/_session
HEAD /{db}/_session
Create a new user session
POST /{db}/_session
Description
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
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
db |
The name of the database to run the operation against. |
String |
Unsupported
Endpoints that are not supported by Sync Gateway
Delete a design document | Unsupported
DELETE /{db}/_design/{ddoc}
Description
This is unsupported
Delete a design document.
Required Sync Gateway RBAC roles:
- Sync Gateway Application
Get views of a design document | Unsupported
GET /{db}/_design/{ddoc}
Description
This is unsupported
Query a design document.
Required Sync Gateway RBAC roles:
- Sync Gateway Application
- Sync Gateway Application Read Only
Query a view on a design document | Unsupported
GET /{db}/_design/{ddoc}/_view/{view}
Description
This is unsupported
Query a view on a design document.
Required Sync Gateway RBAC roles:
- Sync Gateway Application
- Sync Gateway Application Read Only
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
db |
The name of the database to run the operation against. |
String |
ddoc |
The design document name. |
String |
view |
The view to target. |
String |
Query Parameters
| Name | Description | Schema |
|---|---|---|
inclusive_end |
Indicates whether the specified end key should be included in the result. |
Boolean |
descending |
Return documents in descending order. |
Boolean |
include_docs |
Only works when using Couchbase Server 3.0 and earlier. Indicates whether to include the full content of the documents in the response. |
Boolean |
reduce |
Whether to execute a reduce function on the response or not. |
Boolean |
group |
Group the results using the reduce function to a group or single row. |
Boolean |
skip |
Skip the specified number of documents before starting to return results. |
Integer |
limit |
Return only the specified number of documents |
Integer |
group_level |
Specify the group level to be used. |
Integer |
startkey_docid |
Return documents starting with the specified document identifier. |
String |
endkey_docid |
Stop returning records when the specified document identifier is reached. |
String |
stale |
Allow the results from a stale view to be used, without triggering a rebuild of all views within the encompassing design document. Values: |
String |
startkey |
Return records starting with the specified key. |
String |
endkey |
Stop returning records when this key is reached. |
String |
key |
Return only the document that matches the specified key. |
String |
keys |
An array of document ID strings to filter by. |
String List |
Dump a view | Unsupported
GET /{db}/_dump/{view}
Description
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
Query a view on the default design document | Unsupported
GET /{db}/_view/{view}
Description
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
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
db |
The name of the database to run the operation against. |
String |
view |
The view to target. |
String |
Query Parameters
| Name | Description | Schema |
|---|---|---|
inclusive_end |
Indicates whether the specified end key should be included in the result. |
Boolean |
descending |
Return documents in descending order. |
Boolean |
include_docs |
Only works when using Couchbase Server 3.0 and earlier. Indicates whether to include the full content of the documents in the response. |
Boolean |
reduce |
Whether to execute a reduce function on the response or not. |
Boolean |
group |
Group the results using the reduce function to a group or single row. |
Boolean |
skip |
Skip the specified number of documents before starting to return results. |
Integer |
limit |
Return only the specified number of documents |
Integer |
group_level |
Specify the group level to be used. |
Integer |
startkey_docid |
Return documents starting with the specified document identifier. |
String |
endkey_docid |
Stop returning records when the specified document identifier is reached. |
String |
stale |
Allow the results from a stale view to be used, without triggering a rebuild of all views within the encompassing design document. Values: |
String |
startkey |
Return records starting with the specified key. |
String |
endkey |
Stop returning records when this key is reached. |
String |
key |
Return only the document that matches the specified key. |
String |
keys |
An array of document ID strings to filter by. |
String List |
Dump all the documents in a channel | Unsupported
GET /{keyspace}/_dumpchannel/{channel}
Description
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
Parameters
Revision tree structure in Graphviz Dot format | Unsupported
GET /{keyspace}/_revtree/{docid}
Description
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.
Check if view of design document exists | Unsupported
HEAD /{db}/_design/{ddoc}
Description
This is unsupported
Check if a design document can be queried.
Required Sync Gateway RBAC roles:
- Sync Gateway Application
- Sync Gateway Application Read Only
Flush the entire database bucket | Unsupported
POST /{db}/_flush
Description
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
Update views of a design document | Unsupported
PUT /{db}/_design/{ddoc}
Description
This is unsupported
Update the views of a design document.
Required Sync Gateway RBAC roles:
- Sync Gateway Application
Parameters
Path Parameters
| Name | Description | Schema |
|---|---|---|
db |
The name of the database to run the operation against. |
String |
ddoc |
The design document name. |
String |
Definitions
This section describes the properties consumed and returned by this REST API.
ChangesFeed
| Name | Description | Schema |
|---|---|---|
results |
||
last_seq |
The last change sequence number. |
String |
CollectionAccessConfig
| Name | Description | Schema |
|---|---|---|
admin_channels |
A list of channels to explicitly grant to the user. |
String List |
all_channels |
All the channels that the user has been granted access to. Access could have been granted through the sync function, roles, or explicitly on the user under the |
String List |
jwt_channels |
The channels that the user has been granted access to through channels_claim. |
String List |
jwt_last_updated |
The last time that the user’s JWT roles/channels were updated. |
Date (date-time) |
Collection config
| Name | Description | Schema |
|---|---|---|
sync |
The Javascript function that newly created documents in this collection are ran through. Example: |
String |
import_filter |
This is the function that all imported documents in this 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.
|
String |
Compact-status
| Name | Description | Schema |
|---|---|---|
status |
The status of the current operation. |
String |
start_time |
The ISO-8601 date and time the compact operation was started. |
String |
last_error |
The last error that occurred in the compact operation (if any). |
String |
docs_purged |
Applicable to tombstone compaction only This is the amount of documents that have been purged so far. |
String |
marked_attachments |
Applicable to attachment compaction only This is the number of references there are to legacy attachments. |
String |
purged_attachments |
Applicable to attachment compaction only This is the amount of attachments that have been purged so far. |
String |
compact_id |
Applicable to attachment compaction only This is the ID of the compaction. |
String |
phase |
Applicable to attachment compaction only This indicates the current phase of running attachment compact processes. For failed processes, this indicates the phase at which a compact_id restart will commence (where relevant). |
String |
dry_run |
Applicable to attachment compaction only Values: |
String |
Console-logging-config
| Name | Description | Schema |
|---|---|---|
log_level |
Log Level for the console output Values: |
String |
log_keys |
Log Keys for the console output |
String List |
color_enabled |
Log with color for the console output |
Boolean |
file_output |
Override the default stderr output, and write to the file specified instead |
String |
enabled |
Toggle for this log output |
Boolean |
rotation |
||
collation_buffer_size |
The size of the log collation buffer. |
Integer |
Credentials config
| Name | Description | Schema |
|---|---|---|
username |
Username for authenticating to the bucket |
String |
password |
Password for authenticating to the bucket. This value is always redacted. |
String |
x509_cert_path |
Cert path (public key) for X.509 bucket auth |
String |
x509_key_path |
Key path (private key) for X.509 bucket auth |
String |
Database-config
| Name | Description | Schema |
|---|---|---|
server |
This is the Couchbase Server address or addresses that the database connect to. |
String |
pool |
This field is unsupported and ignored. Default: |
String |
bucket |
The Couchbase Server backing bucket for the database. Default: |
String |
username |
The username for authenticating to the server. |
String |
password |
The password for authenticating to the server. |
String |
certpath |
The cert path (public key) for X.509 bucket auth. |
String |
keypath |
The key path (private key) for X.509 bucket auth |
String |
cacertpath |
The root CA cert path for X.509 bucket authentication. |
String |
kv_tls_port |
The Memcached TLS port. Default: |
Integer |
max_concurrent_query_ops |
The maximum amount of query operations that can be running at any one point. Default: |
Integer |
scopes |
An object keyed by scope name containing config for the specific collection. |
|
name |
The name of the database. |
String |
sync |
The Javascript function that newly created documents are ran through for the default scope and collection.
If Default: |
String |
users |
||
roles |
||
revs_limit |
The maximum depth a document’s revision tree can grow too. The minimum is Minimum: |
BigDecimal |
import_docs |
If true, documents will be imported in to Sync Gateway from the bucket when requested. Documents will be ran through the 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 This can also be set to the string |
Boolean |
import_partitions |
This is how many import partitions should be used for import sharding. Partitions are distributed among all Sync Gateway nodes participating in import processing ( Each partition is processed by an independent function that runs simultaneously to others, so Default: |
BigDecimal |
import_filter |
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.
If |
String |
import_backup_old_rev |
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. Default: |
Boolean |
event_handlers |
These are the settings for webhooks. |
|
feed_type |
The type of feed to use to communicate with Couchbase Server. Values: |
String |
allow_empty_password |
This controls whether users that are created can have an empty password or not. Default: |
Boolean |
cache |
||
rev_cache_size |
Deprecated, please use the database setting The maximum number of revisions to store in the revision cache. |
BigDecimal |
offline |
Start the database in an offline state. Default: |
Boolean |
unsupported |
These are unsupported options and therefore it is not recommended to use them. |
|
local_jwt |
Configuration for Local JWT authentication. |
|
oidc |
Configuration for OpenID Connect authentication. |
|
old_rev_expiry_seconds |
The number of seconds before old revisions are removed from the Couchbase Server bucket. Default: |
BigDecimal |
view_query_timeout_secs |
The number of seconds before a view query should timeout. Default: |
Integer |
local_doc_expiry_secs |
The number of seconds before a Default: |
Integer |
enable_shared_bucket_access |
Whether to use extended attributes to store Sync Gateway document ( Default: |
Boolean |
session_cookie_secure |
Override the session cookie This will default to |
Boolean |
session_cookie_name |
This can be used to define a custom per-database session cookie name. |
String |
session_cookie_http_only |
Make all session cookies for the database set the Default: |
Boolean |
allow_conflicts |
This controls whether to allow conflicting document revisions. Default: |
Boolean |
num_index_replicas |
This is the number of Global Secondary Indexes (GSI) to use for core indexes. Default: |
BigDecimal |
use_views |
Force the use of views instead of GSI. Default: |
Boolean |
send_www_authentice_header |
Controls whether to send a Default: |
Boolean |
disable_password_auth |
Whether to disable username/password authentication and only allow OIDC and guest access. Default: |
Boolean |
bucket_op_timeout_ms |
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: |
BigDecimal |
slow_query_warning_threshold |
The amount of milliseconds a N1QL query should run before logging a warning. Default: |
BigDecimal |
delta_sync |
Delta sync configuration settings. **This is an enterprise-edition feature only** |
|
compact_interval_days |
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. Default: |
BigDecimal |
sgreplicate_enabled |
Whether the node should accept assign replications ( Default: |
Boolean |
sgreplicate_websocket_heartbeat_secs |
Use a custom heartbeat interval (in seconds) for websocket ping frames. Default: |
Integer |
replications |
||
serve_insecure_attachment_types |
If set, always serve attachments with the When serving an attachment, usually the Default: |
Boolean |
query_pagination_limit |
The query limit to be used during pagination of large queries. Default: |
Integer |
user_xattr_key |
The key to use for the user xattr that will be accessible from the sync function. IF empty, the feature will be disabled. |
String |
client_partition_window_secs |
How long (in seconds) clients can remain offline for without losing replication metadata. Defaults to 30 days (in seconds) Default: |
Integer |
guest |
Properties associated with a user |
|
javascript_timeout_secs |
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. Default: |
BigDecimal |
suspendable |
Set to true to allow the database to be suspended. Defaults to true when running in serverless mode otherwise defaults to false. Default: |
Boolean |
cors |
CORS configuration for this database; if present, overrides server's config. |
|
logging |
Per-database logging configuration. |
Database-config
| Name | Description | Schema |
|---|---|---|
server |
This is the Couchbase Server address or addresses that the database connect to. |
String |
pool |
This field is unsupported and ignored. Default: |
String |
bucket |
The Couchbase Server backing bucket for the database. Default: |
String |
username |
The username for authenticating to the server. |
String |
password |
The password for authenticating to the server. |
String |
certpath |
The cert path (public key) for X.509 bucket auth. |
String |
keypath |
The key path (private key) for X.509 bucket auth |
String |
cacertpath |
The root CA cert path for X.509 bucket authentication. |
String |
kv_tls_port |
The Memcached TLS port. Default: |
Integer |
max_concurrent_query_ops |
The maximum amount of query operations that can be running at any one point. Default: |
Integer |
scopes |
An object keyed by scope name containing config for the specific collection. |
|
name |
The name of the database. |
String |
sync |
The Javascript function that newly created documents are ran through for the default scope and collection.
If Default: |
String |
users |
||
roles |
||
revs_limit |
The maximum depth a document’s revision tree can grow too. The minimum is Minimum: |
BigDecimal |
import_docs |
If true, documents will be imported in to Sync Gateway from the bucket when requested. Documents will be ran through the 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 This can also be set to the string |
Boolean |
import_partitions |
This is how many import partitions should be used for import sharding. Partitions are distributed among all Sync Gateway nodes participating in import processing ( Each partition is processed by an independent function that runs simultaneously to others, so Default: |
BigDecimal |
import_filter |
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.
If |
String |
import_backup_old_rev |
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. Default: |
Boolean |
event_handlers |
These are the settings for webhooks. |
|
feed_type |
The type of feed to use to communicate with Couchbase Server. Values: |
String |
allow_empty_password |
This controls whether users that are created can have an empty password or not. Default: |
Boolean |
cache |
||
rev_cache_size |
Deprecated, please use the database setting The maximum number of revisions to store in the revision cache. |
BigDecimal |
offline |
Start the database in an offline state. Default: |
Boolean |
unsupported |
These are unsupported options and therefore it is not recommended to use them. |
|
local_jwt |
Configuration for Local JWT authentication. |
|
oidc |
Configuration for OpenID Connect authentication. |
|
old_rev_expiry_seconds |
The number of seconds before old revisions are removed from the Couchbase Server bucket. Default: |
BigDecimal |
view_query_timeout_secs |
The number of seconds before a view query should timeout. Default: |
Integer |
local_doc_expiry_secs |
The number of seconds before a Default: |
Integer |
enable_shared_bucket_access |
Whether to use extended attributes to store Sync Gateway document ( Default: |
Boolean |
session_cookie_secure |
Override the session cookie This will default to |
Boolean |
session_cookie_name |
This can be used to define a custom per-database session cookie name. |
String |
session_cookie_http_only |
Make all session cookies for the database set the Default: |
Boolean |
allow_conflicts |
This controls whether to allow conflicting document revisions. Default: |
Boolean |
num_index_replicas |
This is the number of Global Secondary Indexes (GSI) to use for core indexes. Default: |
BigDecimal |
use_views |
Force the use of views instead of GSI. Default: |
Boolean |
send_www_authentice_header |
Controls whether to send a Default: |
Boolean |
disable_password_auth |
Whether to disable username/password authentication and only allow OIDC and guest access. Default: |
Boolean |
bucket_op_timeout_ms |
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: |
BigDecimal |
slow_query_warning_threshold |
The amount of milliseconds a N1QL query should run before logging a warning. Default: |
BigDecimal |
delta_sync |
Delta sync configuration settings. **This is an enterprise-edition feature only** |
|
compact_interval_days |
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. Default: |
BigDecimal |
sgreplicate_enabled |
Whether the node should accept assign replications ( Default: |
Boolean |
sgreplicate_websocket_heartbeat_secs |
Use a custom heartbeat interval (in seconds) for websocket ping frames. Default: |
Integer |
replications |
||
serve_insecure_attachment_types |
If set, always serve attachments with the When serving an attachment, usually the Default: |
Boolean |
query_pagination_limit |
The query limit to be used during pagination of large queries. Default: |
Integer |
user_xattr_key |
The key to use for the user xattr that will be accessible from the sync function. IF empty, the feature will be disabled. |
String |
client_partition_window_secs |
How long (in seconds) clients can remain offline for without losing replication metadata. Defaults to 30 days (in seconds) Default: |
Integer |
guest |
Properties associated with a user |
|
javascript_timeout_secs |
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. Default: |
BigDecimal |
suspendable |
Set to true to allow the database to be suspended. Defaults to true when running in serverless mode otherwise defaults to false. Default: |
Boolean |
cors |
CORS configuration for this database; if present, overrides server's config. |
|
logging |
Per-database logging configuration. |
DatabaseConfigCache
| Name | Description | Schema |
|---|---|---|
rev_cache |
The revision cache config settings. |
|
channel_cache |
The channel cache config settings. |
|
max_wait_pending |
Deprecated, please use the database setting The maximum time (in milliseconds) for waiting for a pending sequence before skipping it. |
BigDecimal |
max_wait_skipped |
Deprecated, please use the database setting The maximum time (in milliseconds) for waiting for pending sequences before skipping. |
BigDecimal |
enable_star_channel |
Deprecated, please use the database setting Used to control whether Sync Gateway should use the all documents (*) channel. |
Boolean |
channel_cache_max_length |
Deprecated, please use the database setting The maximum number of entries maintained in cache per channel. |
BigDecimal |
channel_cache_min_length |
Deprecated, please use the database setting The minimum number of entries maintained in cache per channel. |
Integer |
channel_cache_expiry |
Deprecated, please use the database setting The time (seconds) to keep entries in cache beyond the minimum retained. |
Integer |
max_num_pending |
Deprecated, please use the database setting The max number of pending sequences before skipping. |
Integer |
DatabaseConfigCacheChannelCache
| Name | Description | Schema |
|---|---|---|
max_number |
The maximum number of channel caches which can exist at any one point. Default: |
Integer |
compact_high_watermark_pct |
The trigger value for starting the channel cache eviction process. Specify this as a percentage which will be the percentage used on `max_number). When the cache size, determined by Default: |
Integer |
compact_low_watermark_pct |
The trigger value for stopping the channel cache eviction process. Specify this as a percentage which will be the percentage used on `max_number). When the cache size, determined by Default: |
Integer |
max_wait_pending |
The maximum time (in milliseconds) for waiting for a pending sequence before skipping it. Default: |
BigDecimal |
max_num_pending |
The maximum number of pending sequences before skipping sequences. Default: |
Integer |
max_wait_skipped |
The maximum amount of time (in milliseconds) to wait for a skipped sequence before abandoning it. Default: |
BigDecimal |
enable_star_channel |
Used to control whether Sync Gateway should use the all documents (*) channel. Default: |
Boolean |
max_length |
The maximum number of entries to maintain in the cache per channel. Default: |
Integer |
min_length |
The minimum number of entries to maintain in the cache per channel. Default: |
Integer |
expiry_seconds |
The amount of time (in seconds) to keep entries in the cache beyond the minimum retained. Default: |
Integer |
query_limit |
Deprecated in favour of the database setting The limit used for channel queries. Default: |
Integer |
DatabaseConfigCacheRevCache
| Name | Description | Schema |
|---|---|---|
size |
The maximum number of revisions that can be stored in the revision cache. Default: |
String |
shard_count |
The number of shards the revision cache should be split into. Default: |
String |
DatabaseConfigCors
| Name | Description | Schema |
|---|---|---|
origin |
List of allowed origins, use ['*'] to allow access from everywhere |
String List |
login_origin |
List of allowed login origins |
String List |
headers |
List of allowed headers |
String List |
DatabaseConfigDeltaSync
| Name | Description | Schema |
|---|---|---|
enabled |
Whether delta sync is enabled. This is an enterprise-edition feature only Default: |
Boolean |
rev_max_age_seconds |
The number of seconds deltas for old revisions are available for. This defaults to 24 hours (in seconds). Default: |
BigDecimal |
DatabaseConfigEventHandlers
| Name | Description | Schema |
|---|---|---|
max_processes |
The maximum amount of concurrent event handling independent functions that can be running at the same time. |
String |
wait_for_process |
The maximum amount of time (in milliseconds) to wait when the even queue is full. |
String |
document_changed |
||
db_state_changed |
DatabaseConfigLocalJwtValue
| Name | Description | Schema |
|---|---|---|
issuer |
The value to match against the "iss" claim of JWTs. |
String |
register |
If to register a new Sync Gateway user account when a user logs in with a JWT. |
Boolean |
client_id |
The value to match against the "aud" claim of JWTs. Set to an empty string to disable audience validation. |
String |
algorithms |
The JWT signing algorithms to accept for authentication. |
String List |
keys |
The JSON Web Keys to use to validate JWTs. |
|
disable_session |
Disable Sync Gateway session creation on successful JWT authentication. |
Boolean |
user_prefix |
This is the username prefix for all users created through this provider. |
String |
username_claim |
Allows a different OpenID Connect field to be specified instead of the Subject ( The field name to use can be specified here. |
String |
roles_claim |
If set, the value(s) of the given JSON Web Token claim will be added to the user’s roles. The value of this claim must be either a string or an array of strings, any other type will result in an error. |
String |
channels_claim |
If set, the value(s) of the given JSON Web Token claim will be added to the user’s channels. The value of this claim must be either a string or an array of strings, any other type will result in an error. |
String |
DatabaseConfigLocalJwtValueKeysInner
| Name | Description | Schema |
|---|---|---|
kty |
The cryptographic algorithm family used with the key, such as "RSA" or "EC" Values: |
String |
use |
The intended use of the public key. Only 'sig' is accepted. Values: |
String |
alg |
The algorithm intended for use with the key. |
String |
kid |
The Key ID, used to identify the key to use. |
String |
crv |
For Elliptic Curve keys, the name of the curve to use. Values: |
String |
x |
For Elliptic Curve keys, the X coordinate of the point, as a base64url string. |
String |
y |
For Elliptic Curve keys, the Y coordinate of the point, as a base64url string. |
String |
n |
For RSA keys, the modulus value of the key, as a Base64urlUInt-encoded value. |
String |
e |
For RSA keys, the exponent of the public key, as a Base64urlUInt-encoded value. |
String |
DatabaseConfigLoggingConsole
| Name | Description | Schema |
|---|---|---|
log_level |
Log Level for the console output Values: |
String |
log_keys |
Log Keys for the console output Example: |
String List |
DatabaseConfigOidc
| Name | Description | Schema |
|---|---|---|
providers |
List of OpenID Connect issuers. |
|
default_provider |
The default provider to use when the provider is not specified in the client. |
String |
DatabaseConfigOidcProvidersValue
| Name | Description | Schema |
|---|---|---|
issuer |
The URL for the OpenID Connect issuer. |
String |
register |
If to register a new Sync Gateway user account when a user logs in with OpenID Connect. |
Boolean |
client_id |
The OpenID Connect provider client ID. |
String |
validation_key |
The OpenID Connect provider client secret. |
String |
callback_url |
The URL that the OpenID Connect will redirect to after authentication. If not provided, a callback URL will be generated. |
String |
disable_session |
Disable Sync Gateway session creation on successful OpenID Connect authentication. |
Boolean |
scope |
The scope sent for the OpenID Connect request. |
String List |
include_access |
This is whether the |
Boolean |
user_prefix |
This is the username prefix for all users created through this provider. |
String |
discovery_url |
The non-standard discovery endpoint. |
String |
disable_cfg_validation |
This bypasses the configuration validation based on the OpenID Connect specifications. This may be required for some OpenID providers that don’t strictly adhere to the specifications. Default: |
Boolean |
disable_callback_state |
Controls whether to maintain state between the auth request and callback endpoints ( This is not recommended as it would cause OpenID Connect authentication to be vulnerable to Cross-Site Request Forgery (CSRF, XSRF). Default: |
Boolean |
username_claim |
Allows a different OpenID Connect field to be specified instead of the Subject ( The field name to use can be specified here. |
String |
roles_claim |
If set, the value(s) of the given OpenID Connect authentication token claim will be added to the user’s roles. The value of this claim must be either a string or an array of strings, any other type will result in an error. |
String |
channels_claim |
If set, the value(s) of the given OpenID Connect authentication token claim will be added to the user’s channels. The value of this claim must be either a string or an array of strings, any other type will result in an error. |
String |
allow_unsigned_provider_tokens |
Allows users accept unsigned tokens from providers. |
Boolean |
IsDefault |
Indicates if this is the default OpenID Connect provider. |
Boolean |
Name |
The name of the OpenID Connect Provider. |
String |
InsecureSkipVerify |
Determines whether the TLS certificate verification should be disabled for this provider. Default: |
Boolean |
DatabaseConfigReplications
| Name | Description | Schema |
|---|---|---|
replication_id |
Properties of a replication |
Role
| Name | Description | Schema |
|---|---|---|
name |
The name of the role. Role names can only have alphanumeric ASCII characters and underscores. |
String |
admin_channels |
The channels that users in the role are able to access for the default collection. |
String List |
all_channels |
The channels that the role grants access to for the default collection. These channels could have been assigned by the Sync function or using the |
String List |
collection_access |
A set of access grants by scope and collection. |
Map Map |
Scopes
| Name | Description | Schema |
|---|---|---|
collections |
An object keyed by collection name containing config for the specific collection. |
Collection config
| Name | Description | Schema |
|---|---|---|
sync |
The Javascript function that newly created documents in this collection are ran through. Example: |
String |
import_filter |
This is the function that all imported documents in this 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.
|
String |
DatabaseConfigUnsupported
| Name | Description | Schema |
|---|---|---|
user_views |
||
oidc_test_provider |
||
api_endpoints |
||
warning_thresholds |
||
oidc_tls_skip_verify |
Enable self-signed certificates for OIDC testing. |
Boolean |
sgr_tls_skip_verify |
Enable self-signed certificates for SG-replicate testing. |
Boolean |
remote_config_tls_skip_verify |
Enable self-signed certificates for external JavaScript load. |
Boolean |
guest_read_only |
Restrict GUEST document access to read-only. |
Boolean |
force_api_forbidden_errors |
Force REST API errors to return forbidden |
Boolean |
dcp_read_buffer |
Set the dcp feed to use a different read buffer size. |
BigDecimal |
kv_buffer |
Set the kv pool to use a different buffer size. |
BigDecimal |
DatabaseConfigUnsupportedApiEndpoints
| Name | Description | Schema |
|---|---|---|
enable_couchbase_bucket_flush |
Setting for test purposes only Whether Couchbase buckets can be flushed via Admin REST API. |
Boolean |
DatabaseConfigUnsupportedOidcTestProvider
| Name | Description | Schema |
|---|---|---|
enabled |
Whether the |
Boolean |
DatabaseConfigUnsupportedUserViews
| Name | Description | Schema |
|---|---|---|
enabled |
Whether pass-through view query is supported through public API. |
Boolean |
DatabaseConfigUnsupportedWarningThresholds
| Name | Description | Schema |
|---|---|---|
xattr_size_bytes |
The number of bytes to be used as a threshold for xattr size limit warnings. |
BigDecimal |
channels_per_doc |
The number of channels per document to be used as a threshold for the channel count warnings. |
BigDecimal |
access_and_role_grants_per_doc |
The number of access and role grants per document to be used as a threshold for grant count warnings. |
BigDecimal |
channels_per_user |
The number of channels per user to be used as a threshold for channel count warnings. |
BigDecimal |
channel_name_size |
The number of channel name characters to be used as a threshold for channel name warnings. |
BigDecimal |
User
| Name | Description | Schema |
|---|---|---|
name |
The name of the user. User names can only have alphanumeric ASCII characters and underscores. |
String |
password |
The password of the user. Mandatory. unless |
String |
admin_channels |
A list of channels to explicitly grant to the user for the default collection. |
String List |
all_channels |
All the channels that the user has been granted access to for the default collection. Access could have been granted through the sync function, roles, or explicitly on the user under the |
String List |
collection_access |
A set of access grants by scope and collection. |
Map Map |
email |
The email address of the user. |
String |
disabled |
If true, the user will not be able to login to the account as it is disabled. |
Boolean |
admin_roles |
A list of roles to explicitly grant to the user. |
String List |
roles |
All the roles that the user has been granted access to. Access could have been granted through the sync function, roles_claim, or explicitly on the user under the |
String List |
jwt_roles |
The roles that the user has been added to through roles_claim. |
String List |
jwt_channels |
The channels that the user has been granted access to through channels_claim. |
String List |
jwt_issuer |
The issuer of the last JSON Web Token that the user last used to sign in. |
String |
jwt_last_updated |
The last time that the user’s JWT roles/channels were updated. |
Date (date-time) |
DeleteSgcollectInfo200Response
| Name | Description | Schema |
|---|---|---|
status |
The new status of sgcollect_info. Default: |
String |
Document
| Name | Description | Schema |
|---|---|---|
_id |
The ID of the document. |
String |
_rev |
The revision of the document. |
String |
_exp |
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 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. |
String |
_deleted |
Whether the document is a tombstone or not. If true, it is a tombstone. |
Boolean |
_revisions |
||
_attachments |
Event-config
| Name | Description | Schema |
|---|---|---|
handler |
The handler type. Values: |
String |
url |
The URL of the webhook. |
String |
filter |
The Javascript function to use to filter the webhook events. |
String |
timeout |
The amount of time (in seconds) to attempt connect to the webhook before giving up. |
BigDecimal |
options |
The options for the event. |
oas_any_type_not_mapped Map |
ExpVars
| Name | Description | Schema |
|---|---|---|
cmdline |
Built-in variables from the Go runtime, lists the command-line arguments |
Object |
memstats |
Dumps a large amount of information about the memory heap and garbage collector |
Object |
cb |
Variables reported by the Couchbase SDK (go_couchbase package) |
Object |
mc |
Variables reported by the low-level memcached API (gomemcached package) |
Object |
syncGateway_changeCache |
||
syncGateway_db |
||
syncgateway |
Monitoring stats |
File-logging-config
| Name | Description | Schema |
|---|---|---|
enabled |
Toggle for this log output |
Boolean |
rotation |
||
collation_buffer_size |
The size of the log collation buffer |
Integer |
Get200Response
| Name | Description | Schema |
|---|---|---|
ADMIN |
Example: |
Boolean |
couchdb |
CouchDB welcome Example: |
String |
vendor |
Product vendor |
|
version |
Product version, including the build number and edition (i.e. Example: |
String |
persistent_config |
Indication for whether sync gateway is running in persistent config mode or legacy config mode.
Example: |
Boolean |
Get200ResponseVendor
| Name | Description | Schema |
|---|---|---|
name |
Product name Example: |
String |
version |
API version.
Omitted if Example: |
String |
GetAllDbs200ResponseOneOfInner
| Name | Description | Schema |
|---|---|---|
db_name |
The name of the database. |
String |
bucket |
The Couchbase Server backing bucket for the database. |
String |
state |
The database state. Values: |
String |
GetDb200Response
| Name | Description | Schema |
|---|---|---|
db_name |
Database name Example: |
String |
update_seq |
The last sequence number that was committed to the database. Will return 0 if the database is offline. Example: |
Integer |
committed_update_seq |
The last sequence number that was committed to the database. Will return 0 if the database is offline. Example: |
Integer |
instance_start_time |
Timestamp of when the database opened, in microseconds since the Unix epoch. Example: |
Integer |
compact_running |
Indicates whether database compaction is currently taking place or not. |
Boolean |
purge_seq |
Unused field. Default: |
BigDecimal |
disk_format_version |
Unused field. Default: |
BigDecimal |
state |
The database state. Change using the Values: |
String |
server_uuid |
Unique server identifier. Example: |
String |
scopes |
Scopes that are used by the database. Example: |
GetDb200ResponseScopesValue
| Name | Description | Schema |
|---|---|---|
collections |
The set of collections within the scope. |
GetDb200ResponseScopesValueCollectionsValue
| Name | Description | Schema |
|---|---|---|
update_seq |
The last sequence number that was committed to the collection. Example: |
Integer |
GetDbDesignDdoc200Response
| Name | Description | Schema |
|---|---|---|
language |
String |
|
views |
||
options |
GetDbDesignDdoc200ResponseOptions
| Name | Description | Schema |
|---|---|---|
local_seq |
String |
|
include_design |
String |
|
raw |
String |
|
index_xattr_on_deleted_docs |
String |
GetDbDesignDdoc200ResponseViewsValue
| Name | Description | Schema |
|---|---|---|
map |
String |
|
reduce |
String |
GetDbOidcTestingCerts200ResponseKeysInner
| Name | Description | Schema |
|---|---|---|
Key |
Object |
|
KeyID |
String |
|
Use |
String |
|
Certificates |
Object List |
|
Algorithm |
String |
GetDbOidcTestingWellKnownOpenidConfiguration200Response
| Name | Description | Schema |
|---|---|---|
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 |
GetDbViewView200Response
| Name | Description | Schema |
|---|---|---|
total_rows |
Integer |
|
rows |
||
errors |
GetDbViewView200ResponseErrorsInner
| Name | Description | Schema |
|---|---|---|
From |
String |
|
Reason |
String |
GetDbViewView200ResponseRowsInner
| Name | Description | Schema |
|---|---|---|
id |
String |
|
key |
Object |
|
value |
Object |
|
doc |
Object |
GetExpvar200Response
| Name | Description | Schema |
|---|---|---|
cmdline |
Built-in variables from the Go runtime, lists the command-line arguments |
Object |
memstats |
Dumps a large amount of information about the memory heap and garbage collector |
Object |
cb |
Variables reported by the Couchbase SDK (go_couchbase package) |
Object |
mc |
Variables reported by the low-level memcached API (gomemcached package) |
Object |
syncGateway_changeCache |
||
syncGateway_db |
||
syncgateway |
Monitoring stats |
GetExpvar200ResponseSyncGatewayChangeCache
| Name | Description | Schema |
|---|---|---|
maxPending |
Max number of sequences waiting on a missing earlier sequence number |
Object |
lag-tap-0000ms |
Histogram of delay from doc save till it shows up in Tap feed |
Object |
lag-queue-0000ms |
Histogram of delay from Tap feed till doc is posted to changes feed |
Object |
lag-total-0000ms |
Histogram of total delay from doc save till posted to changes feed |
Object |
outOfOrder |
Number of out-of-order sequences posted |
Object |
view_queries |
Number of queries to channels view |
Object |
GetExpvar200ResponseSyncGatewayDb
| Name | Description | Schema |
|---|---|---|
channelChangesFeeds |
Number of calls to db.changesFeed, i.e. generating a changes feed for a single channel. |
Object |
channelLogAdds |
Number of entries added to channel logs |
Object |
channelLogAppends |
Number of times entries were written to channel logs using an APPEND operation |
Object |
channelLogCacheHits |
Number of requests for channel-logs that were fulfilled from the in-memory cache |
Object |
channelLogRewrites |
Number of times entries were written to channel logs using a SET operation (rewriting the entire log) |
Object |
channelLogRewriteCollisions |
Number of collisions while attempting to rewrite channel logs using SET |
Object |
document_gets |
Number of times a document was read from the database |
Object |
revisionCache_adds |
Number of revisions added to the revision cache |
Object |
revisionCache_hits |
Number of times a revision-cache lookup succeeded |
Object |
revisionCache_misses |
Number of times a revision-cache lookup failed |
Object |
revs_added |
Number of revisions added to the database (including deletions) |
Object |
sequence_gets |
Number of times the database’s lastSequence was read |
Object |
sequence_reserves |
Number of times the database’s lastSequence was incremented |
Object |
GetExpvar200ResponseSyncgateway
| Name | Description | Schema |
|---|---|---|
global |
Global Sync Gateway stats |
|
per_db |
This array contains stats for all databases declared in the config file — see the [Sync Gateway Statistics Schema](./../stats-monitoring.html) for more details on the metrics collected and reported by Sync Gateway.
The statistics for each {$db_name} database are grouped into:
- cache related statistics
- collections statistics
- cbl_replication_push
- cbl_replication_pull
- database_related_statistics
- delta_sync
- gsi_views
- security_related_statistics
- shared_bucket_import
- per_replication statistics for each |
|
per_replication |
An array of stats for each replication declared in the config file Deprecated @ 2.8: used only by inter-sync-gateway replications version 1. |
get__expvar_200_response_syncgateway_per_replication_inner List |
GetExpvar200ResponseSyncgatewayGlobal
| Name | Description | Schema |
|---|---|---|
resource_utilization |
Resource utilization stats |
get__expvar_200_response_syncgateway_global_resource_utilization |
GetExpvar200ResponseSyncgatewayGlobalResourceUtilization
| Name | Description | Schema |
|---|---|---|
admin_net_bytes_recv |
Integer |
|
admin_net_bytes_sent |
Integer |
|
error_count |
Integer |
|
go_memstats_heapalloc |
Integer |
|
go_memstats_heapidle |
Integer |
|
go_memstats_heapinuse |
Integer |
|
go_memstats_heapreleased |
Integer |
|
go_memstats_pausetotalns |
Integer |
|
go_memstats_stackinuse |
Integer |
|
go_memstats_stacksys |
Integer |
|
go_memstats_sys |
Integer |
|
goroutines_high_watermark |
Integer |
|
num_goroutines |
Integer |
|
process_cpu_percent_utilization |
Integer |
|
process_memory_resident |
Integer |
|
pub_net_bytes_recv |
Integer |
|
pub_net_bytes_sent |
Integer |
|
system_memory_total |
Integer |
|
warn_count |
Integer |
GetExpvar200ResponseSyncgatewayPerDbInner
| Name | Description | Schema |
|---|---|---|
cache |
Object |
|
database |
Object |
|
per_replication |
Object |
|
collections |
Object |
|
security |
Object |
GetExpvar200ResponseSyncgatewayPerReplicationInner
| Name | Description | Schema |
|---|---|---|
$replication_id |
get__expvar_200_response_syncgateway_per_replication_inner__replication_id |
GetExpvar200ResponseSyncgatewayPerReplicationInnerReplicationId
| Name | Description | Schema |
|---|---|---|
sgr_active |
Whether the replication is active at this time. Deprecated @ 2.8: used only by inter-sync-gateway replications version 1. |
Boolean |
sgr_docs_checked_sent |
The total number of documents checked for changes since replication started. This represents the number of potential change notifications pushed by Sync Gateway. Constraints This is not necessarily the number of documents pushed, as a given target might already have the change. Used by versions 1 and 2. |
Integer |
sgr_num_attachments_transferred |
The total number of attachments transferred since replication started. Deprecated @ 2.8: used only by inter-sync-gateway replications version 1. |
Integer |
sgr_num_attachment_bytes_transferred |
The total number of attachment bytes transferred since replication started. Deprecated @ 2.8: used only by inter-sync-gateway replications version 1. |
Integer |
sgr_num_docs_failed_to_push |
The total number of documents that failed to be pushed since replication started. Used by versions 1 and 2. |
Integer |
sgr_num_docs_pushed |
The total number of documents that were pushed since replication started. Used by versions 1 and 2. |
Integer |
GetKeyspaceAllDocs200Response
| Name | Description | Schema |
|---|---|---|
rows |
||
total_rows |
BigDecimal |
|
update_seq |
BigDecimal |
GetKeyspaceAllDocs200ResponseRowsInner
| Name | Description | Schema |
|---|---|---|
key |
String |
|
id |
String |
|
value |
GetKeyspaceChanges200Response
| Name | Description | Schema |
|---|---|---|
results |
||
last_seq |
The last change sequence number. |
String |
GetKeyspaceChanges200ResponseResultsInner
| Name | Description | Schema |
|---|---|---|
seq |
The change sequence number. |
BigDecimal |
id |
The document ID the change happened on. |
String |
changes |
List of document leafs with each leaf containing only a |
get_keyspace__changes_200_response_results_inner_changes_inner Set |
GetKeyspaceChanges200ResponseResultsInnerChangesInner
| Name | Description | Schema |
|---|---|---|
rev |
The new revision that was caused by that change. |
String |
GetKeyspaceDocid200Response
| Name | Description | Schema |
|---|---|---|
_id |
The ID of the document. |
String |
_rev |
The revision ID of the document. |
String |
GetKeyspaceRawDocid200ResponseSync
| Name | Description | Schema |
|---|---|---|
rev |
The current document revision ID. |
String |
sequence |
The most recent sequence number of the document. |
BigDecimal |
recent_sequences |
The previous sequence numbers of the document. |
BigDecimal List |
history |
||
cas |
The document CAS (Concurrent Document Mutations) number used for document locking. |
String |
value_crc32c |
The documents CRC32 number. |
String |
channel_set |
The channels the document has been in. |
get_keyspace__raw_docid_200_response__sync_channel_set_inner List |
channel_set_history |
get_keyspace__raw_docid_200_response__sync_channel_set_history_inner List |
|
time_saved |
The time and date the document was most recently changed. |
String |
GetKeyspaceRawDocid200ResponseSyncChannelSetHistoryInner
| Name | Description | Schema |
|---|---|---|
name |
String |
|
start |
String |
|
end |
String |
GetKeyspaceRawDocid200ResponseSyncChannelSetInner
| Name | Description | Schema |
|---|---|---|
name |
The name of the channel. |
String |
start |
The sequence number that document was added to the channel. |
String |
end |
The sequence number the document was removed from the channel. Omitted if not removed. |
String |
GetKeyspaceRawDocid200ResponseSyncHistory
| Name | Description | Schema |
|---|---|---|
revs |
The past revision IDs. |
String List |
parents |
BigDecimal List |
|
channels |
The past channel history. Can contain string arrays, strings, or be null depending on if and how the channels where set. |
List List |
GetSgcollectInfo200Response
| Name | Description | Schema |
|---|---|---|
status |
The status of sgcollect_info. Values: |
String |
GetStats200Response
| Name | Description | Schema |
|---|---|---|
memstats |
A set of Go runtime memory statistics. |
oas_any_type_not_mapped Map |
HTTP-Error
| Name | Description | Schema |
|---|---|---|
error |
The error name. |
String |
reason |
The error description. |
String |
Log-rotation-config
| Name | Description | Schema |
|---|---|---|
max_size |
The maximum size in MB of the log file before it gets rotated. |
Integer |
max_age |
The maximum number of days to retain old log files. |
Integer |
localtime |
If true, it uses the computer’s local time to format the backup timestamp. |
Boolean |
rotated_logs_size |
Max Size (in mb) of log files before deletion |
Integer |
Log-rotation-config
| Name | Description | Schema |
|---|---|---|
max_size |
The maximum size in MB of the log file before it gets rotated. |
Integer |
max_age |
The maximum number of days to retain old log files. |
Integer |
localtime |
If true, it uses the computer’s local time to format the backup timestamp. |
Boolean |
rotated_logs_size |
Max Size (in mb) of log files before deletion |
Integer |
New-revision
| Name | Description | Schema |
|---|---|---|
id |
The ID of the document. |
String |
ok |
Whether the request completed successfully. |
Boolean |
rev |
The revision of the document. |
String |
NodeInfo
| Name | Description | Schema |
|---|---|---|
ADMIN |
Example: |
Boolean |
couchdb |
CouchDB welcome Example: |
String |
vendor |
Product vendor |
|
version |
Product version, including the build number and edition (i.e. Example: |
String |
persistent_config |
Indication for whether sync gateway is running in persistent config mode or legacy config mode.
Example: |
Boolean |
OpenID Connect callback properties
| Name | Description | Schema |
|---|---|---|
id_token |
The OpenID Connect ID token |
String |
refresh_token |
The OpenID Connect ID refresh token |
String |
session_id |
The Sync Gateway session token |
String |
name |
The Sync Gateway user |
String |
access_token |
The OpenID Connect access token |
String |
token_type |
The OpenID Connect ID token type |
String |
expires_in |
The time until the id_token expires (TTL). |
BigDecimal |
OIDCLoginPageHandler
| Name | Description | Schema |
|---|---|---|
username |
String |
|
tokenttl |
String |
|
identity-token-formats |
String |
|
authenticated |
String |
OIDC-token
| Name | Description | Schema |
|---|---|---|
access_token |
String |
|
token_type |
String |
|
refresh_token |
String |
|
expires_in |
String |
|
id_token |
String |
OpenID Connect callback properties
| Name | Description | Schema |
|---|---|---|
id_token |
The OpenID Connect ID token |
String |
refresh_token |
The OpenID Connect ID refresh token |
String |
session_id |
The Sync Gateway session token |
String |
name |
The Sync Gateway user |
String |
access_token |
The OpenID Connect access token |
String |
token_type |
The OpenID Connect ID token type |
String |
expires_in |
The time until the id_token expires (TTL). |
BigDecimal |
PostDbEnsureFullCommit201Response
| Name | Description | Schema |
|---|---|---|
instance_start_time |
Timestamp of when the database opened, in microseconds since the Unix epoch. Example: |
Integer |
ok |
Default: |
Boolean |
PostDbFacebookRequest
| Name | Description | Schema |
|---|---|---|
access_token |
Facebook access token to base the new session on. |
String |
PostDbGoogleRequest
| Name | Description | Schema |
|---|---|---|
id_token |
Google ID token to base the new session on. |
String |
PostDbOidcTestingAuthenticateRequest
| Name | Description | Schema |
|---|---|---|
username |
String |
|
tokenttl |
String |
|
identity-token-formats |
String |
|
authenticated |
String |
PostDbOidcTestingTokenRequest
| Name | Description | Schema |
|---|---|---|
grant_type |
The grant type of the token to request. Can either be an |
String |
code |
|
String |
refresh_token |
|
String |
PostDbOnlineRequest
| Name | Description | Schema |
|---|---|---|
delay |
The amount of seconds to delay bringing the database online. Default: |
Integer |
PostDbResyncRequest
| Name | Description | Schema |
|---|---|---|
scopes |
This controls for which collections resync will run |
List Map |
regenerate_sequences |
This can be used as an alternative to query param Default: |
Boolean |
PostDbSession200Response
| Name | Description | Schema |
|---|---|---|
session_id |
The ID of the session. This is the value that would be put in to the cookie to keep the user authenticated. |
String |
expires |
The date and time the cookie expires. |
String |
cookie_name |
The name of the cookie that would be used to store the users session. |
String |
PostDbSessionRequest
| Name | Description | Schema |
|---|---|---|
name |
User name to generate the session for. |
String |
ttl |
Time until the session expires. Uses default value of 24 hours if left blank. |
Integer |
PostKeyspaceAllDocsRequest
| Name | Description | Schema |
|---|---|---|
keys |
List of the documents to retrieve. |
String List |
PostKeyspaceBulkDocs201ResponseInner
| Name | Description | Schema |
|---|---|---|
id |
The ID of the document that the operation was performed on. |
String |
rev |
The new revision of the document if the operation was a success. |
String |
error |
The error type if the operation of the document failed. |
String |
reason |
The reason the operation failed. |
String |
status |
The HTTP status code for why the operation failed. |
Integer |
PostKeyspaceBulkDocsRequest
| Name | Description | Schema |
|---|---|---|
new_edits |
This controls whether to assign new revision identifiers to new edits ( Default: |
Boolean |
docs |
post_keyspace__request List |
PostKeyspaceBulkGetRequestDocsInner
| Name | Description | Schema |
|---|---|---|
id |
ID of the document to retrieve. |
String |
PostKeyspaceChangesRequest
| Name | Description | Schema |
|---|---|---|
limit |
Maximum number of changes to return. |
String |
style |
Controls whether to return the current winning revision ( |
String |
active_only |
Set true to exclude deleted documents and notifications for documents the user no longer has access to from the changes feed. |
String |
include_docs |
Include the body associated with each document. |
String |
revocations |
If true, revocation messages will be sent on the changes feed. |
String |
filter |
Set a filter to either filter by channels or document IDs. |
String |
channels |
A comma-separated list of channel names to filter the response to only the channels specified. To use this option, the |
String |
doc_ids |
A valid JSON array of document IDs to filter the documents in the response to only the documents specified. To use this option, the |
String |
heartbeat |
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 |
String |
timeout |
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 |
String |
feed |
The type of changes feed to use. |
String |
request_plus |
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. |
String |
PostKeyspacePurgeRequest
| Name | Description | Schema |
|---|---|---|
doc_id |
The document ID to purge. The array must only be 1 element which is All revisions will be permanently removed for that document. Values: |
String List |
PostKeyspaceRequest
| Name | Description | Schema |
|---|---|---|
_id |
The ID of the document. |
String |
_rev |
The revision of the document. |
String |
_exp |
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 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. |
String |
_deleted |
Whether the document is a tombstone or not. If true, it is a tombstone. |
Boolean |
_revisions |
||
_attachments |
PostKeyspaceRequestAttachmentsValue
| Name | Description | Schema |
|---|---|---|
content_type |
Content type of the attachment. |
String |
data |
The data in the attachment in base64. |
String |
PostKeyspaceRequestRevisions
| Name | Description | Schema |
|---|---|---|
start |
Prefix number for the latest revision. |
BigDecimal |
ids |
Array of valid revision IDs, in reverse order (latest first). |
String List |
PostKeyspaceRevsDiff200ResponseDocid
| Name | Description | Schema |
|---|---|---|
missing |
The revisions that are not in the database (and therefore |
String List |
possible_ancestors |
An array of known revisions that might be the recent ancestors. |
String List |
PostKeyspaceRevsDiffRequest
| Name | Description | Schema |
|---|---|---|
docid |
The document ID with an array of revisions to use for the comparison. |
String List |
PostPostUpgrade200Response
| Name | Description | Schema |
|---|---|---|
post_upgrade_results |
A map of databases. |
post__post_upgrade_200_response_post_upgrade_results_value Map |
preview |
If set, nothing in the database was changed as this was a dry-run. This can be controlled by the |
Boolean |
PostPostUpgrade200ResponsePostUpgradeResultsValue
| Name | Description | Schema |
|---|---|---|
removed_design_docs |
The design documents that have or will be removed. |
String List |
removed_indexes |
The indexes that have or will be removed. |
String List |
PostProfileProfilenameRequest
| Name | Description | Schema |
|---|---|---|
file |
This is the file to output the pprof profile at. |
String |
PostSgcollectInfo200Response
| Name | Description | Schema |
|---|---|---|
status |
The new sgcollect_info status. Default: |
String |
PostSgcollectInfoRequest
| Name | Description | Schema |
|---|---|---|
redact_level |
The redaction level to use for redacting the collected logs. Values: |
String |
redact_salt |
The salt to use for the log redactions. |
String |
output_dir |
The directory to output the collected logs zip file at. This overrides the configured default output directory configured in the startup config Default: |
String |
upload |
If set, upload the logs to Couchbase Support. A customer name must be set if this is set. |
Boolean |
upload_host |
The host to send the logs too. Default: |
String |
upload_proxy |
The proxy to use while uploading the logs. |
String |
customer |
The customer name to use when uploading the logs. |
String |
ticket |
The Zendesk ticket number to use when uploading logs. |
String |
PutKeyspaceLocalDocidRequest
| Name | Description | Schema |
|---|---|---|
_rev |
Revision to replace. Required if updating existing local document. Example: |
String |
User configurable replication properties
| Name | Description | Schema |
|---|---|---|
replication_id |
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. |
String |
remote |
This is the endpoint of the database for the remote Sync Gateway that is the subject of this replication’s Typically this would include the URI, port, and database name. For example, How this remote is used depends on the |
String |
username |
This has been deprecated in favour of This is the username to use to authenticate with the remote. This can only be used for a pull replication. |
String |
password |
This has been deprecated in favour of 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. |
String |
remote_username |
The username to use to authenticate with the remote. This can only be used for a pull replication. |
String |
remote_password |
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. |
String |
direction |
This specifies which direction the replication will be replicating with the The directions are:
* Replications created prior to Sync Gateway 2.8 derive their Values: |
String |
conflict_resolution_type |
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 logest 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 Note: replications created prior to Sync Gateway 2.8 will default to Values: |
String |
custom_conflict_resolver |
This specifies the Javascript function to use to resolve conflicts between conflicting revisions. This must be used when 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:
* Example: Using complex This is an enterprise-edition only feature. Default: |
String |
purge_on_removal |
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. Default: |
Boolean |
enable_delta_sync |
This will turn on delta- sync for the replication. This works in conjunction with the database level setting 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. Default: |
Boolean |
max_backoff_time |
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 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. Default: |
Integer |
initial_state |
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 Replications prior to Sync Gateway 2.8 will run in the default state Values: |
String |
continuous |
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. Default: |
Boolean |
filter |
This defines whether to filter documents by their channels or not. If set to This only can be used with pull replications. Values: |
String |
query_params |
This is a set of key/value pairs used in the query string of the replication. If |
String List |
adhoc |
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 Default: |
Boolean |
batch_size |
The amount of changes to be sent in one batch of replications. Changing this is an enterprise-edition only feature. Default: |
Integer |
run_as |
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. |
String |
collections_enabled |
If true, the replicator will run with collections, and will replicate all collections, unless otherwise limited by If false, the replicator will only replicate the default collection. Default: |
Boolean |
collections_local |
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. Default: |
String List |
collections_remote |
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 The same index is used for both Default: |
String List |
Replication
| Name | Description | Schema |
|---|---|---|
replication_id |
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. |
String |
remote |
This is the endpoint of the database for the remote Sync Gateway that is the subject of this replication’s Typically this would include the URI, port, and database name. For example, How this remote is used depends on the |
String |
username |
This has been deprecated in favour of This is the username to use to authenticate with the remote. This can only be used for a pull replication. |
String |
password |
This has been deprecated in favour of 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. |
String |
remote_username |
The username to use to authenticate with the remote. This can only be used for a pull replication. |
String |
remote_password |
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. |
String |
direction |
This specifies which direction the replication will be replicating with the The directions are:
* Replications created prior to Sync Gateway 2.8 derive their Values: |
String |
conflict_resolution_type |
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 logest 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 Note: replications created prior to Sync Gateway 2.8 will default to Values: |
String |
custom_conflict_resolver |
This specifies the Javascript function to use to resolve conflicts between conflicting revisions. This must be used when 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:
* Example: Using complex This is an enterprise-edition only feature. Default: |
String |
purge_on_removal |
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. Default: |
Boolean |
enable_delta_sync |
This will turn on delta- sync for the replication. This works in conjunction with the database level setting 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. Default: |
Boolean |
max_backoff_time |
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 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. Default: |
Integer |
initial_state |
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 Replications prior to Sync Gateway 2.8 will run in the default state Values: |
String |
continuous |
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. Default: |
Boolean |
filter |
This defines whether to filter documents by their channels or not. If set to This only can be used with pull replications. Values: |
String |
query_params |
This is a set of key/value pairs used in the query string of the replication. If |
String List |
adhoc |
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 Default: |
Boolean |
batch_size |
The amount of changes to be sent in one batch of replications. Changing this is an enterprise-edition only feature. Default: |
Integer |
run_as |
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. |
String |
collections_enabled |
If true, the replicator will run with collections, and will replicate all collections, unless otherwise limited by If false, the replicator will only replicate the default collection. Default: |
Boolean |
collections_local |
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. Default: |
String List |
collections_remote |
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 The same index is used for both Default: |
String List |
assigned_node |
The unique ID of the node assigned to the replication. |
String |
target_state |
This is the state that the replicator is in or that trying to transition in to. Values: |
String |
Replication-status
| Name | Description | Schema |
|---|---|---|
replication_id |
The ID of the replication. |
String |
config |
Properties of a replication |
|
status |
The status of the replication. Values: |
String |
error_message |
The error message of the replication if an error has occurred. |
String |
docs_read |
The number of documents that have been read (fetched) from the source database. |
Integer |
docs_checked_pull |
Integer |
|
docs_purged |
The number of documents that have been purged. |
Integer |
rejected_by_local |
The number of documents that were received by the local but did not get replicated due to getting rejected by the sync function on the local. |
Integer |
last_seq_pull |
The last changes sequence number that was pulled from the remote. |
String |
deltas_recv |
The number of deltas that have been received from the remote. |
Integer |
deltas_requested |
Integer |
|
docs_written |
The number of documents that have been wrote (pushed) to the target database. |
Integer |
docs_checked_push |
Integer |
|
docs_write_failures |
The number of documents that have failed to be wrote (pushed) to the target database. There will be no attempt to try to push these docs again. |
Integer |
docs_write_conflicts |
The number of documents that had a conflict. |
Integer |
rejected_by_remote |
The number of documents that were received by the remote but did not get replicated due to getting rejected by the sync function on the remote. |
Integer |
last_seq_push |
The last changes sequence number that was pushed to the remote. |
String |
deltas_sent |
The number of deltas that have been sent to the remote. |
Integer |
Resync-status
| Name | Description | Schema |
|---|---|---|
status |
The status of the current operation. Values: |
String |
start_time |
The ISO-8601 date and time the resync operation was started. |
String |
last_error |
The last error that occurred in the resync operation (if any). |
String |
docs_changed |
The amount of documents that have been changed as a result of the resync operation. |
Integer |
docs_processed |
The amount of docs that have been processed so far in the resync operation. |
Integer |
Replication
| Name | Description | Schema |
|---|---|---|
replication_id |
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. |
String |
remote |
This is the endpoint of the database for the remote Sync Gateway that is the subject of this replication’s Typically this would include the URI, port, and database name. For example, How this remote is used depends on the |
String |
username |
This has been deprecated in favour of This is the username to use to authenticate with the remote. This can only be used for a pull replication. |
String |
password |
This has been deprecated in favour of 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. |
String |
remote_username |
The username to use to authenticate with the remote. This can only be used for a pull replication. |
String |
remote_password |
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. |
String |
direction |
This specifies which direction the replication will be replicating with the The directions are:
* Replications created prior to Sync Gateway 2.8 derive their Values: |
String |
conflict_resolution_type |
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 logest 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 Note: replications created prior to Sync Gateway 2.8 will default to Values: |
String |
custom_conflict_resolver |
This specifies the Javascript function to use to resolve conflicts between conflicting revisions. This must be used when 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:
* Example: Using complex This is an enterprise-edition only feature. Default: |
String |
purge_on_removal |
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. Default: |
Boolean |
enable_delta_sync |
This will turn on delta- sync for the replication. This works in conjunction with the database level setting 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. Default: |
Boolean |
max_backoff_time |
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 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. Default: |
Integer |
initial_state |
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 Replications prior to Sync Gateway 2.8 will run in the default state Values: |
String |
continuous |
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. Default: |
Boolean |
filter |
This defines whether to filter documents by their channels or not. If set to This only can be used with pull replications. Values: |
String |
query_params |
This is a set of key/value pairs used in the query string of the replication. If |
String List |
adhoc |
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 Default: |
Boolean |
batch_size |
The amount of changes to be sent in one batch of replications. Changing this is an enterprise-edition only feature. Default: |
Integer |
run_as |
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. |
String |
collections_enabled |
If true, the replicator will run with collections, and will replicate all collections, unless otherwise limited by If false, the replicator will only replicate the default collection. Default: |
Boolean |
collections_local |
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. Default: |
String List |
collections_remote |
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 The same index is used for both Default: |
String List |
assigned_node |
The unique ID of the node assigned to the replication. |
String |
target_state |
This is the state that the replicator is in or that trying to transition in to. Values: |
String |
Role
| Name | Description | Schema |
|---|---|---|
name |
The name of the role. Role names can only have alphanumeric ASCII characters and underscores. |
String |
admin_channels |
The channels that users in the role are able to access for the default collection. |
String List |
all_channels |
The channels that the role grants access to for the default collection. These channels could have been assigned by the Sync function or using the |
String List |
collection_access |
A set of access grants by scope and collection. |
Map Map |
Role
| Name | Description | Schema |
|---|---|---|
name |
The name of the role. Role names can only have alphanumeric ASCII characters and underscores. |
String |
admin_channels |
The channels that users in the role are able to access for the default collection. |
String List |
all_channels |
The channels that the role grants access to for the default collection. These channels could have been assigned by the Sync function or using the |
String List |
collection_access |
A set of access grants by scope and collection. |
Map Map |
Scopes
| Name | Description | Schema |
|---|---|---|
collections |
An object keyed by collection name containing config for the specific collection. |
Serverless
| Name | Description | Schema |
|---|---|---|
enabled |
Run SG in to serverless mode |
Boolean |
min_config_fetch_interval |
How long database configs should be kept for in Sync Gateway before refreshing. Set to 0 to fetch configs everytime. This is used for requested databases that SG does not know about. This is a duration and therefore can be provided with units "h", "m", "s", "ms", "us", and "ns". For example, 5 hours, 20 minutes, and 30 seconds would be Default: |
String |
Startup-config
| Name | Description | Schema |
|---|---|---|
bootstrap |
Configuration settings for interacting with Couchbase Server. |
|
api |
Configuration settings for modifying how the REST API is interacted with. |
|
logging |
The configuration settings for modifying Sync Gateway logging. |
|
auth |
||
replicator |
||
unsupported |
Settings that are not officially supported. It is highly recommended these are **not** used. |
|
database_credentials |
A map of database name to credentials, that can be used instead of the bootstrap ones. |
|
bucket_credentials |
A map of bucket names to credentials, that can be used instead of the bootstrap ones. |
|
max_file_descriptors |
Max of open file descriptors (RLIMIT_NOFILE) Default: |
BigDecimal |
couchbase_keepalive_interval |
TCP keep-alive interval between SG and Couchbase server |
Integer |
StartupConfigApi
| Name | Description | Schema |
|---|---|---|
public_interface |
Network interface to bind public API to Default: |
String |
admin_interface |
Network interface to bind admin API to. By default, this will only be accessible to the localhost. Default: |
String |
metric_interface |
Network interface to bind metrics API to. By default, this will only be accessible to the localhost. Default: |
String |
profile_interface |
Network interface to bind profiling API to |
String |
admin_interface_authentication |
Whether the admin API requires authentication Default: |
Boolean |
metrics_interface_authentication |
Whether the metrics API requires authentication Default: |
Boolean |
enable_advanced_auth_dp |
Whether to enable the DP permissions check feature of admin auth. Defaults to |
Boolean |
server_read_timeout |
Maximum duration.Second before timing out read of the HTTP(S) request. This is a duration and therefore can be provided with units "h", "m", "s", "ms", "us", and "ns". For example, 5 hours, 20 minutes, and 30 seconds would be |
String |
server_write_timeout |
Maximum duration.Second before timing out write of the HTTP(S) response. This is a duration and therefore can be provided with units "h", "m", "s", "ms", "us", and "ns". For example, 5 hours, 20 minutes, and 30 seconds would be |
String |
read_header_timeout |
The amount of time allowed to read request headers. This is a duration and therefore can be provided with units "h", "m", "s", "ms", "us", and "ns". For example, 5 hours, 20 minutes, and 30 seconds would be Default: |
String |
idle_timeout |
The maximum amount of time to wait for the next request when keep-alives are enabled. This is a duration and therefore can be provided with units "h", "m", "s", "ms", "us", and "ns". For example, 5 hours, 20 minutes, and 30 seconds would be Default: |
String |
pretty |
Pretty-print JSON responses |
Boolean |
max_connections |
Max of incoming HTTP connections to accept Default: |
BigDecimal |
compress_responses |
If false, disables compression of HTTP responses Default: |
Boolean |
hide_product_version |
Whether product versions removed from Server headers and REST API responses |
Boolean |
https |
||
cors |
StartupConfigApiCors
| Name | Description | Schema |
|---|---|---|
origin |
List of allowed origins, use ['*'] to allow access from everywhere |
String List |
login_origin |
List of allowed login origins |
String List |
headers |
List of allowed headers |
String List |
max_age |
Maximum age of the CORS Options request |
Integer |
StartupConfigApiHttps
| Name | Description | Schema |
|---|---|---|
tls_minimum_version |
The minimum allowable TLS version for the REST APIs Default: |
String |
tls_cert_path |
The TLS cert file to use for the REST APIs |
String |
tls_key_path |
The TLS key file to use for the REST APIs |
String |
StartupConfigAuth
| Name | Description | Schema |
|---|---|---|
bcrypt_cost |
Cost to use for bcrypt password hashes Default: |
Integer |
StartupConfigBootstrap
| Name | Description | Schema |
|---|---|---|
group_id |
The config group ID to use when discovering databases. Allows for non-homogenous configuration. Default: |
String |
config_update_frequency |
How often to poll Couchbase Server for new config changes. This is a duration and therefore can be provided with units "h", "m", "s", "ms", "us", and "ns". For example, 5 hours, 20 minutes, and 30 seconds would be Default: |
String |
server |
Couchbase Server connection string/URL. |
String |
username |
Username for authenticating to server. |
String |
password |
Password for authenticating to server |
String |
ca_cert_path |
Root CA cert path for TLS connection |
String |
server_tls_skip_verify |
Allow empty server CA Cert Path without attempting to use system root pool Default: |
Boolean |
x509_cert_path |
Cert path (public key) for X.509 bucket auth |
String |
x509_key_path |
Key path (private key) for X.509 bucket auth |
String |
use_tls_server |
Enforces a secure or non-secure server scheme Default: |
Boolean |
Credentials config
| Name | Description | Schema |
|---|---|---|
username |
Username for authenticating to the bucket |
String |
password |
Password for authenticating to the bucket. This value is always redacted. |
String |
x509_cert_path |
Cert path (public key) for X.509 bucket auth |
String |
x509_key_path |
Key path (private key) for X.509 bucket auth |
String |
Credentials config
| Name | Description | Schema |
|---|---|---|
username |
Username for authenticating to the bucket |
String |
password |
Password for authenticating to the bucket. This value is always redacted. |
String |
x509_cert_path |
Cert path (public key) for X.509 bucket auth |
String |
x509_key_path |
Key path (private key) for X.509 bucket auth |
String |
StartupConfigLogging
| Name | Description | Schema |
|---|---|---|
log_file_path |
Absolute or relative path on the filesystem to the log file directory. A relative path is from the directory that contains the Sync Gateway executable file. |
String |
redaction_level |
Redaction level to apply to log output. Values: |
String |
console |
||
error |
||
warn |
||
info |
||
debug |
||
trace |
||
stats |
StartupConfigReplicator
| Name | Description | Schema |
|---|---|---|
max_heartbeat |
Max heartbeat value for This is a duration and therefore can be provided with units "h", "m", "s", "ms", "us", and "ns". For example, 5 hours, 20 minutes, and 30 seconds would be |
String |
blip_compression |
BLIP data compression level (0-9) Minimum: |
Integer |
StartupConfigUnsupported
| Name | Description | Schema |
|---|---|---|
serverless |
Configuration for when SG is running in serverless mode |
|
use_xattr_config |
Store database configurations in system xattrs |
Boolean |
stats_log_frequency |
How often should stats be written to stats logs. This is a duration and therefore can be provided with units "h", "m", "s", "ms", "us", and "ns". For example, 5 hours, 20 minutes, and 30 seconds would be Default: |
String |
use_stdlib_json |
Bypass the jsoniter package and use Go’s stdlib instead |
Boolean |
http2 |
StartupConfigUnsupportedHttp2
| Name | Description | Schema |
|---|---|---|
enabled |
Whether HTTP2 support is enabled |
Boolean |
StartupConfigUnsupportedServerless
| Name | Description | Schema |
|---|---|---|
enabled |
Run SG in to serverless mode |
Boolean |
min_config_fetch_interval |
How long database configs should be kept for in Sync Gateway before refreshing. Set to 0 to fetch configs everytime. This is used for requested databases that SG does not know about. This is a duration and therefore can be provided with units "h", "m", "s", "ms", "us", and "ns". For example, 5 hours, 20 minutes, and 30 seconds would be Default: |
String |
Status
| Name | Description | Schema |
|---|---|---|
databases |
Contains a map of all the databases in the node along with their status. |
|
version |
The product version including the build number and edition (ie. Blank if |
String |
Status
| Name | Description | Schema |
|---|---|---|
databases |
Contains a map of all the databases in the node along with their status. |
|
version |
The product version including the build number and edition (ie. Blank if |
String |
Status1DatabasesValue
| Name | Description | Schema |
|---|---|---|
seq |
The latest sequence number in the database. Minimum: |
BigDecimal |
server_uuid |
The server unique identifier. |
String |
state |
Whether the database is online or offline. Values: |
String |
replication_status |
Replication_status List |
|
cluster |
Status1DatabasesValueCluster
| Name | Description | Schema |
|---|---|---|
replication |
Map of replication configs defined for the cluster. |
|
nodes |
Map of all Sync Gateway nodes in the cluster. |
Status1DatabasesValueClusterNodes
| Name | Description | Schema |
|---|---|---|
node_uuid |
The nodes unique identifier. |
Status1DatabasesValueClusterNodesNodeUuid
| Name | Description | Schema |
|---|---|---|
uuid |
The nodes unique identifier. |
String |
host |
The nodes host name. |
String |
Status1DatabasesValueClusterReplication
| Name | Description | Schema |
|---|---|---|
replication_id |
Properties of a replication |
User
| Name | Description | Schema |
|---|---|---|
name |
The name of the user. User names can only have alphanumeric ASCII characters and underscores. |
String |
password |
The password of the user. Mandatory. unless |
String |
admin_channels |
A list of channels to explicitly grant to the user for the default collection. |
String List |
all_channels |
All the channels that the user has been granted access to for the default collection. Access could have been granted through the sync function, roles, or explicitly on the user under the |
String List |
collection_access |
A set of access grants by scope and collection. |
Map Map |
email |
The email address of the user. |
String |
disabled |
If true, the user will not be able to login to the account as it is disabled. |
Boolean |
admin_roles |
A list of roles to explicitly grant to the user. |
String List |
roles |
All the roles that the user has been granted access to. Access could have been granted through the sync function, roles_claim, or explicitly on the user under the |
String List |
jwt_roles |
The roles that the user has been added to through roles_claim. |
String List |
jwt_channels |
The channels that the user has been granted access to through channels_claim. |
String List |
jwt_issuer |
The issuer of the last JSON Web Token that the user last used to sign in. |
String |
jwt_last_updated |
The last time that the user’s JWT roles/channels were updated. |
Date (date-time) |
User
| Name | Description | Schema |
|---|---|---|
name |
The name of the user. User names can only have alphanumeric ASCII characters and underscores. |
String |
password |
The password of the user. Mandatory. unless |
String |
admin_channels |
A list of channels to explicitly grant to the user for the default collection. |
String List |
all_channels |
All the channels that the user has been granted access to for the default collection. Access could have been granted through the sync function, roles, or explicitly on the user under the |
String List |
collection_access |
A set of access grants by scope and collection. |
Map Map |
email |
The email address of the user. |
String |
disabled |
If true, the user will not be able to login to the account as it is disabled. |
Boolean |
admin_roles |
A list of roles to explicitly grant to the user. |
String List |
roles |
All the roles that the user has been granted access to. Access could have been granted through the sync function, roles_claim, or explicitly on the user under the |
String List |
jwt_roles |
The roles that the user has been added to through roles_claim. |
String List |
jwt_channels |
The channels that the user has been granted access to through channels_claim. |
String List |
jwt_issuer |
The issuer of the last JSON Web Token that the user last used to sign in. |
String |
jwt_last_updated |
The last time that the user’s JWT roles/channels were updated. |
Date (date-time) |
User1CollectionAccessValueValue
| Name | Description | Schema |
|---|---|---|
admin_channels |
A list of channels to explicitly grant to the user. |
String List |
all_channels |
All the channels that the user has been granted access to. Access could have been granted through the sync function, roles, or explicitly on the user under the |
String List |
jwt_channels |
The channels that the user has been granted access to through channels_claim. |
String List |
jwt_last_updated |
The last time that the user’s JWT roles/channels were updated. |
Date (date-time) |
User configurable replication properties
| Name | Description | Schema |
|---|---|---|
replication_id |
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. |
String |
remote |
This is the endpoint of the database for the remote Sync Gateway that is the subject of this replication’s Typically this would include the URI, port, and database name. For example, How this remote is used depends on the |
String |
username |
This has been deprecated in favour of This is the username to use to authenticate with the remote. This can only be used for a pull replication. |
String |
password |
This has been deprecated in favour of 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. |
String |
remote_username |
The username to use to authenticate with the remote. This can only be used for a pull replication. |
String |
remote_password |
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. |
String |
direction |
This specifies which direction the replication will be replicating with the The directions are:
* Replications created prior to Sync Gateway 2.8 derive their Values: |
String |
conflict_resolution_type |
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 logest 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 Note: replications created prior to Sync Gateway 2.8 will default to Values: |
String |
custom_conflict_resolver |
This specifies the Javascript function to use to resolve conflicts between conflicting revisions. This must be used when 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:
* Example: Using complex This is an enterprise-edition only feature. Default: |
String |
purge_on_removal |
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. Default: |
Boolean |
enable_delta_sync |
This will turn on delta- sync for the replication. This works in conjunction with the database level setting 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. Default: |
Boolean |
max_backoff_time |
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 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. Default: |
Integer |
initial_state |
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 Replications prior to Sync Gateway 2.8 will run in the default state Values: |
String |
continuous |
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. Default: |
Boolean |
filter |
This defines whether to filter documents by their channels or not. If set to This only can be used with pull replications. Values: |
String |
query_params |
This is a set of key/value pairs used in the query string of the replication. If |
String List |
adhoc |
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 Default: |
Boolean |
batch_size |
The amount of changes to be sent in one batch of replications. Changing this is an enterprise-edition only feature. Default: |
Integer |
run_as |
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. |
String |
collections_enabled |
If true, the replicator will run with collections, and will replicate all collections, unless otherwise limited by If false, the replicator will only replicate the default collection. Default: |
Boolean |
collections_local |
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. Default: |
String List |
collections_remote |
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 The same index is used for both Default: |
String List |