Admin REST API (Static Page)

500

A problem occurred in regards to the token

GetDbOidcTestingWellKnownOpenidConfiguration200Response

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.

Produces

application/json

Parameters

Path Parameters

Name	Description	Schema
db required	The name of the database to run the operation against.	String

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Query Parameters

Name	Description	Schema
provider optional	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 optional	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

Name

Description

Schema

provider
optional

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
optional

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	HTTPError
500	Unable to connect and validate with the OpenID Connect provider requested

OpenID Connect token refresh

GET /{db}/_oidc_refresh

Description

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

Produces

application/json

Parameters

Path Parameters

Name	Description	Schema
db required	The name of the database to run the operation against.	String

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Query Parameters

Name	Description	Schema
refresh_token required	The OpenID Connect refresh token.	String
provider optional	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

Name

Description

Schema

refresh_token
required

The OpenID Connect refresh token.

String

provider
optional

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

Responses

HTTP Code	Description	Schema
200	Successfully authenticated with OpenID Connect.	OpenIDConnectCallbackProperties
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	HTTPError
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.

Produces

application/json

Parameters

Path Parameters

Name	Description	Schema
db required	The name of the database to run the operation against.	String

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Responses

HTTP Code Description Schema

HTTP Code	Description	Schema
200	Successfully generated OpenID Connect provider mock response.	GetDbOidcTestingWellKnownOpenidConfiguration200Response
403	The OpenID Connect unsupported config option `oidc_test_provider` is not enabled. To use this endpoint, this option must be enabled.
404	Resource could not be found	HTTPError

200

Successfully generated OpenID Connect provider mock response.

403

The OpenID Connect unsupported config option oidc_test_provider is not enabled. To use this endpoint, this option must be enabled.

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.

Produces

application/json

Parameters

Path Parameters

Name	Description	Schema
db required	The name of the database to run the operation against.	String

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Query Parameters

Name	Description	Schema
redirect_uri optional	The Sync Gateway OpenID Connect callback URL.	String
scope required	The OpenID Connect authentication scope.	String
username required		String
tokenttl required		Integer
identity-token-formats required		String
authenticated required		String

Name

Description

Schema

redirect_uri
optional

The Sync Gateway OpenID Connect callback URL.

String

scope
required

The OpenID Connect authentication scope.

String

username
required

String

tokenttl
required

Integer

identity-token-formats
required

String

authenticated
required

String

Responses

HTTP Code	Description	Schema
302	Redirecting to Sync Gateway OpenID Connect callback URL
403	The OpenID Connect unsupported config option `oidc_test_provider` is not enabled. To use this endpoint, this option must be enabled.
404	Resource could not be found	HTTPError

OpenID Connect mock login page

GET /{db}/_oidc_testing/authorize

Description

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

Produces

application/json

Parameters

Path Parameters

Name	Description	Schema
db required	The name of the database to run the operation against.	String

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Query Parameters

Name	Description	Schema
scope required	The OpenID Connect authentication scope.	String

Name

Description

Schema

scope
required

The OpenID Connect authentication scope.

String

Responses

HTTP Code Description Schema

200

400

A validation error occurred with the scope.

403

The OpenID Connect unsupported config option oidc_test_provider is not enabled. To use this endpoint, this option must be enabled.

404

Resource could not be found

500

An error occurred.

GetDbOidcTestingCerts200Response

OpenID Connect public certificates for signing keys

GET /{db}/_oidc_testing/certs

Description

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

Produces

application/json

Parameters

Path Parameters

Name	Description	Schema
db required	The name of the database to run the operation against.	String

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Responses

HTTP Code Description Schema

HTTP Code	Description	Schema
200	Returned public key successfully	GetDbOidcTestingCerts200Response
403	The OpenID Connect unsupported config option `oidc_test_provider` is not enabled. To use this endpoint, this option must be enabled.
404	Resource could not be found	HTTPError
500	An error occurred while getting the private RSA key	PostDbFacebook401Response

200

Returned public key successfully

403

The OpenID Connect unsupported config option oidc_test_provider is not enabled. To use this endpoint, this option must be enabled.

404

Resource could not be found

500

An error occurred while getting the private RSA key

Create a new Facebook-based session

POST /{db}/_facebook

This operation is deprecated, and will be removed in a future release.

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.

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name	Description	Schema
db required	The name of the database to run the operation against.	String

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Body Parameter

Name	Description	Schema
Body optional		PostDbFacebookRequest

Name

Description

Schema

Body
optional

PostDbFacebookRequest

Responses

HTTP Code	Description	Schema
200	Session created successfully
400	Origin is not in the approved list of allowed origins	HTTPError
401	Received error from Facebook verifier	PostDbFacebook401Response
404	Resource could not be found	HTTPError
502	Received invalid response from the Facebook verifier	PostDbFacebook401Response
504	Unable to send request to Facebook API	PostDbFacebook401Response

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

This operation is deprecated, and will be removed in a future release.

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.

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name	Description	Schema
db required	The name of the database to run the operation against.	String

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Body Parameter

Name	Description	Schema
Body optional		PostDbGoogleRequest

Name

Description

Schema

Body
optional

PostDbGoogleRequest

Responses

HTTP Code	Description	Schema
200	Session created successfully
400	Origin is not in the approved list of allowed origins	HTTPError
401	Received error from Google token verifier or invalid application ID in the config	PostDbFacebook401Response
404	Resource could not be found	HTTPError
502	Received invalid response from the Google token verifier	PostDbFacebook401Response
504	Unable to send request to the Google token verifier

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

PostDbOidcTestingAuthenticateRequest

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.

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name	Description	Schema
db required	The name of the database to run the operation against.	String

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Query Parameters

Name	Description	Schema
redirect_uri optional	The Sync Gateway OpenID Connect callback URL.	String
scope required	The OpenID Connect authentication scope.	String

Name

Description

Schema

redirect_uri
optional

The Sync Gateway OpenID Connect callback URL.

String

scope
required

The OpenID Connect authentication scope.

String

Body Parameter

Name	Description	Schema
Body optional	Properties passed from the OpenID Connect mock login page to the handler	PostDbOidcTestingAuthenticateRequest

Name

Description

Schema

Body
optional

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

Responses

HTTP Code	Description	Schema
302	Redirecting to Sync Gateway OpenID Connect callback URL
403	The OpenID Connect unsupported config option `oidc_test_provider` is not enabled. To use this endpoint, this option must be enabled.
404	Resource could not be found	HTTPError

OpenID Connect mock login page

POST /{db}/_oidc_testing/authorize

Description

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

Produces

application/json

Parameters

Path Parameters

Name	Description	Schema
db required	The name of the database to run the operation against.	String

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Query Parameters

Name	Description	Schema
scope required	The OpenID Connect authentication scope.	String

Name

Description

Schema

scope
required

The OpenID Connect authentication scope.

String

Responses

HTTP Code Description Schema

200

400

A validation error occurred with the scope.

403

The OpenID Connect unsupported config option oidc_test_provider is not enabled. To use this endpoint, this option must be enabled.

404

Resource could not be found

500

An error occurred.

PostDbOidcTestingTokenRequest

OpenID Connect mock token

POST /{db}/_oidc_testing/token

Description

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

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name	Description	Schema
db required	The name of the database to run the operation against.	String

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Body Parameter

Name	Description	Schema
Body optional		PostDbOidcTestingTokenRequest

Name

Description

Schema

Body
optional

Responses

HTTP Code	Description	Schema
200	Properties expected back from an OpenID Connect provider after successful authentication	OIDCToken
400	Invalid token provided
403	The OpenID Connect unsupported config option `oidc_test_provider` is not enabled. To use this endpoint, this option must be enabled.
404	Resource could not be found	HTTPError

Database Configuration

Table of Contents

Delete import filter
Remove custom sync function
Get database configuration
Get database import filter
Get database sync function
Update database configuration
Replace database configuration
Set database import filter
Set database sync function

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

Produces

application/json

Parameters

Path Parameters

Name	Description	Schema
keyspace required	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

Name

Description

Schema

keyspace
required

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

Header Parameters

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

Name

Description

Schema

If-Match
optional

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

String

Responses

HTTP Code	Description	Schema
200	Successfully deleted the import filter
404	Resource could not be found	HTTPError
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.	HTTPError

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

Produces

application/json

Parameters

Path Parameters

Name	Description	Schema
keyspace required	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

Name

Description

Schema

keyspace
required

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

Header Parameters

Name	Description	Schema
If-Match optional	The revision ID to target.	String

Name

Description

Schema

If-Match
optional

The revision ID to target.

String

Responses

HTTP Code	Description	Schema
200	Successfully reset the sync function
404	Resource could not be found	HTTPError
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.	HTTPError

HTTP Code

Description

Schema

200

Successfully reset the sync function

404

Resource could not be found

412

Get database configuration

GET /{db}/_config

Description

Retrieve the full configuration for the database specified.

Required Sync Gateway RBAC roles:

Sync Gateway Architect

Produces

application/json

Parameters

Path Parameters

Name	Description	Schema
db required	The name of the database to run the operation against.	String

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Query Parameters

Name	Description	Schema
redact optional	No longer supported field.	Boolean
include_javascript optional	Include the fields that have Javascript functions in the response. E.g. sync function, import filter, and event handlers.	Boolean
include_runtime optional	Whether to include the values set at runtime, and default values.	Boolean
refresh_config optional	Forces the configuration to be reloaded on the Sync Gateway node.	Boolean

Name

Description

Schema

redact
optional

No longer supported field.

Boolean

include_javascript
optional

Include the fields that have Javascript functions in the response. E.g. sync function, import filter, and event handlers.

Boolean

include_runtime
optional

Whether to include the values set at runtime, and default values.

Boolean

refresh_config
optional

Forces the configuration to be reloaded on the Sync Gateway node.

Boolean

Responses

HTTP Code	Description	Schema
200	Successfully retrieved database configuration	DatabaseConfig
404	Resource could not be found	HTTPError

HTTP Code

Description

Schema

200

Successfully retrieved database configuration

404

Resource could not be found

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

Produces

application/javascript
application/json

Parameters

Path Parameters

Name

Description

Schema

keyspace
required

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

Successfully retrieved the import filter

String

404

Resource could not be found

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

Produces

application/javascript
application/json

Parameters

Path Parameters

Name

Description

Schema

keyspace
required

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

Successfully retrieved the sync function

String

404

Resource could not be found

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

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Header Parameters

Name

Description

Schema

If-Match
optional

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

String

Body Parameter

Name

Description

Schema

Body
optional

The database configuration fields to update

Responses

HTTP Code	Description	Schema
201	Database configuration successfully updated
400	There was a problem with your request	HTTPError
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.	HTTPError

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

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Query Parameters

Name

Description

Schema

disable_oidc_validation
optional

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

Boolean

Header Parameters

Name

Description

Schema

If-Match
optional

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

String

Body Parameter

Name

Description

Schema

Body
optional

The new database configuration to use

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

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

Consumes

application/javascript

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

keyspace
required

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

disable_oidc_validation
optional

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

Boolean

Header Parameters

Name

Description

Schema

If-Match
optional

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

String

Body Parameter

Name

Description

Schema

Body
optional

The import filter to use

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

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

Consumes

application/javascript

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

keyspace
required

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

disable_oidc_validation
optional

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

Boolean

Header Parameters

Name

Description

Schema

If-Match
optional

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

String

Body Parameter

Name

Description

Schema

Body
optional

The new sync function to use

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

Remove a database
Get a list of all the databases
Get database information
Get the status of the most recent compact operation
Get resync status
Get changes list
Check if database exists
/{db}/_changes
Manage a compact operation
/{db}/_ensure_full_commit
Take the database offline
Bring the database online
Start or stop Resync
Get changes list
Compare revisions to what is in the database
Create a new Sync Gateway database

Database Management

Table of Contents

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

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Responses

HTTP Code

Description

Schema

200

Successfully removed the database

Object

404

Resource could not be found

500

Cannot remove database from bucket

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

Produces

application/json

Parameters

Query Parameters

Name

Description

Schema

verbose
optional

Boolean

Responses

HTTP Code

Description

Schema

200

Successfully retrieved all database names

GetAllDbs200Response

Get database information

GET /{db}/

Description

Retrieve information about the database.

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Responses

HTTP Code

Description

Schema

200

Successfully returned database information

GetDb200Response

404

Resource could not be found

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

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Query Parameters

Name Description Schema

type
optional

This is the type of compaction to use. The type must be either:

attachment for cleaning up legacy (pre-3.0) attachments
tombstone for purging the JSON bodies of non-leaf revisions.'

Values: "attachment", "tombstone"

String

Responses

HTTP Code

Description

Schema

200

Compaction status retrieved successfully

CompactStatus

400

There was a problem with your request

404

Resource could not be found

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

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Responses

HTTP Code

Description

Schema

200

successfully retrieved the most recent resync operation status

ResyncStatus

404

Resource could not be found

GetKeyspaceChanges200Response

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

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

keyspace
required

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
optional

Maximum number of changes to return.

Integer

since
optional

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
optional

Controls whether to return the current winning revision (main_only) or all the leaf revision including conflicts and deleted former conflicts (all_docs).

Values: "main_only", "all_docs"

String

active_only
optional

Set true to exclude deleted documents and notifications for documents the user no longer has access to from the changes feed.

Boolean

include_docs
optional

Include the body associated with each document.

Boolean

revocations
optional

If true, revocation messages will be sent on the changes feed.

Boolean

filter
optional

Set a filter to either filter by channels or document IDs.

Values: "sync_gateway/bychannel", "_doc_ids"

String

channels
optional

A comma-separated list of channel names to filter the response to only the channels specified. To use this option, the filter query option must be set to sync_gateway/bychannels.

String

doc_ids
optional

A valid JSON array of document IDs to filter the documents in the response to only the documents specified. To use this option, the filter query option must be set to _doc_ids and the feed parameter must be normal. Also accepts a comma separated list of document IDs instead.

String array

heartbeat
optional

The interval (in milliseconds) to send an empty line (CRLF) in the response. This is to help prevent gateways from deciding the socket is idle and therefore closing it. This is only applicable to feed=longpoll or feed=continuous. This will override any timeouts to keep the feed alive indefinitely. Setting to 0 results in no heartbeat. The maximum heartbeat can be set in the server replication configuration.

Minimum: 25000

Integer

timeout
optional

This is the maximum period (in milliseconds) to wait for a change before the response is sent, even if there are no results. This is only applicable for feed=longpoll or feed=continuous changes feeds. Setting to 0 results in no timeout.

Minimum: 0
Maximum: 900000

Integer

feed
optional

The type of changes feed to use.

Values: "normal", "longpoll", "continuous", "websocket"

String

request_plus
optional

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.

Boolean

Responses

HTTP Code

Description

Schema

200

Successfully returned the changes feed

400

There was a problem with your request

404

Resource could not be found

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

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Responses

HTTP Code	Description	Schema
200	Database exists
404	Resource could not be found	HTTPError

/{db}/_changes

HEAD /{keyspace}/_changes

Description

Required Sync Gateway RBAC roles:

Sync Gateway Application
Sync Gateway Application Read Only

Parameters

Path Parameters

Name

Description

Schema

keyspace
required

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	OK
400	Bad Request
404	Not Found

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 the compact_id at the appropriate phase (if possible).

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

Required Sync Gateway RBAC roles:

Sync Gateway Architect

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Query Parameters

Name Description Schema

type
optional

This is the type of compaction to use. The type must be either:

attachment for cleaning up legacy (pre-3.0) attachments
tombstone for purging the JSON bodies of non-leaf revisions.'

Values: "attachment", "tombstone"

String

action
optional

Defines whether the a compact operation is being started or stopped.

Values: "start", "stop"

String

reset
optional

Attachment compaction only

This forces a fresh compact start instead of trying to resume the previous failed compact operation.

Boolean

dry_run
optional

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

Responses

HTTP Code

Description

Schema

200

Started or stopped compact operation successfully

400

There was a problem with your request

404

Resource could not be found

503

Cannot start compaction due to another compaction operation still running.

PostDbEnsureFullCommit201Response

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

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Responses

HTTP Code

Description

Schema

201

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

Required Sync Gateway RBAC roles:

Sync Gateway Architect

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Responses

HTTP Code

Description

Schema

200

Database has been taken offline successfully

404

Resource could not be found

503

An error occurred while trying to take the database offline

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

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Body Parameter

Name

Description

Schema

Body
optional

Add an optional delay to wait before bringing the database online

PostDbOnlineRequest

Responses

HTTP Code

Description

Schema

200

Database will be brought online immediately or with the specified delay

404

Resource could not be found

503

An error occurred

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

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Query Parameters

Name Description Schema

action
optional

This is whether to start a new resync job or stop an existing one.

Values: "start", "stop"

String

regenerate_sequences
optional

Use this only when requested to do so by the Couchbase support team This request will regenerate the sequence numbers for each document processed. If scopes parameter is specified, the principal sequence documents will not have their sequences updated.

Boolean

reset
optional

This forces a fresh resync run instead of trying to resume the previous resync operation

Boolean

Body Parameter

Name

Description

Schema

Body
optional

PostDbResyncRequest

Responses

HTTP Code

Description

Schema

200

successfully changed the status of the resync operation

ResyncStatus

503

Service Unavailable

PostKeyspaceChangesRequest

Get changes list

POST /{keyspace}/_changes

Description

Required Sync Gateway RBAC roles:

Sync Gateway Application
Sync Gateway Application Read Only

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

keyspace
required

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
optional

Responses

HTTP Code

Description

Schema

200

Successfully returned the changes feed

GetKeyspaceChanges200Response

400

There was a problem with your request

404

Resource could not be found

PostKeyspaceRevsDiffRequest

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

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

keyspace
required

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
optional

Responses

HTTP Code

Description

Schema

200

Comparisons successful

PostKeyspaceRevsDiff200Response

404

Resource could not be found

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

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Query Parameters

Name

Description

Schema

disable_oidc_validation
optional

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

Boolean

Body Parameter

Name

Description

Schema

Body
optional

The configuration to use for the new database

Responses

HTTP Code

Description

Schema

201

Database created successfully

400

There was a problem with your request

403

An authentication failure occurred

409

A database already exists for this bucket

412

A database under that name already exists

500

A server error occurred

Delete a role
Delete a user
Get all names of the roles
Get a role
Get all the names of the users
Get a user
/{db}/_role/
Check if role exists
/{db}/_user/
Check if user exists
Create a new role
Create a new user
Upsert a role
Upsert a user

Database Security

Table of Contents

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

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

name
required

The name of the role.

String

Responses

HTTP Code	Description	Schema
200	OK
404	Resource could not be found	HTTPError

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

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

name
required

The name of the user.

String

Responses

HTTP Code	Description	Schema
200	User deleted successfully
404	Resource could not be found	HTTPError

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

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Query Parameters

Name

Description

Schema

deleted
optional

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

Boolean

Responses

HTTP Code

Description

Schema

200

Roles retrieved successfully

String array

404

Resource could not be found

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

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

name
required

The name of the role.

String

Responses

HTTP Code

Description

Schema

200

Properties associated with a role

Role1

404

Resource could not be found

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

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Query Parameters

Name Description Schema

name_only
optional

Whether to return user names only, or more detailed information for each user.

Boolean

limit
optional

How many results to return. Using a value of 0 results in no limit.

Integer

Responses

HTTP Code

Description

Schema

200

Users retrieved successfully

String array

404

Resource could not be found

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

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

name
required

The name of the user.

String

Responses

HTTP Code

Description

Schema

200

Properties associated with a user

404

Resource could not be found

/{db}/_role/

HEAD /{db}/_role/

Description

Required Sync Gateway RBAC roles:

Sync Gateway Architect
Sync Gateway Application
Sync Gateway Application Read Only

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Responses

HTTP Code	Description	Schema
200	OK
404	Resource could not be found	HTTPError

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

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

name
required

The name of the role.

String

Responses

HTTP Code	Description	Schema
200	Role exists
404	Resource could not be found	HTTPError

/{db}/_user/

HEAD /{db}/_user/

Description

Required Sync Gateway RBAC roles:

Sync Gateway Architect
Sync Gateway Application
Sync Gateway Application Read Only

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Responses

HTTP Code	Description	Schema
200	OK
404	Resource could not be found	HTTPError

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

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

name
required

The name of the user.

String

Responses

HTTP Code	Description	Schema
200	User exists
404	Not Found

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

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Body Parameter

Name

Description

Schema

Body
optional

Properties associated with a role

Role1

Responses

HTTP Code

Description

Schema

201

New role created successfully

404

Resource could not be found

409

Resource already exists under that name

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

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Body Parameter

Name

Description

Schema

Body
optional

Properties associated with a user

Responses

HTTP Code

Description

Schema

201

New user created successfully

404

Resource could not be found

409

Resource already exists under that name

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

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

name
required

The name of the role.

String

Body Parameter

Name

Description

Schema

Body
optional

Properties associated with a role

Role1

Responses

HTTP Code	Description	Schema
200	OK
201	Created
404	Resource could not be found	HTTPError

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

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

name
required

The name of the user.

String

Body Parameter

Name

Description

Schema

Body
optional

Properties associated with a user

Responses

HTTP Code	Description	Schema
200	Existing user modified successfully
201	New user created
404	Resource could not be found	HTTPError

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

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

keyspace
required

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
required

The document ID to run the operation against.

String

Query Parameters

Name

Description

Schema

rev
optional

The document revision to target.

String

Header Parameters

Name

Description

Schema

If-Match
optional

The revision ID to target.

String

Responses

HTTP Code

Description

Schema

200

New revision created successfully

400

There was a problem with your request

404

Resource could not be found

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.

Produces

application/json

Parameters

Path Parameters

Name Description Schema

keyspace
required

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
required

The document ID to run the operation against.

String

attach
required

The attachment name. This value must be URL encoded. For example, if the attachment name is blob_/avatar, the path component passed to the URL should be blob_%2Favatar (tested with URLEncoder).

String

Query Parameters

Name

Description

Schema

rev
optional

The existing document revision ID to modify.

String

Header Parameters

Name

Description

Schema

If-Match
optional

An alternative way of specifying the document revision ID.

String

Responses

HTTP Code

Description

Schema

200

Attachment removed from the document successfully

404

Resource could not be found

409

Resource already exists under that name

GetKeyspaceAllDocs200Response

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

Produces

application/json

Parameters

Path Parameters

Name Description Schema

keyspace
required

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
required

The name of the local document ID excluding the _local/ prefix.

String

Query Parameters

Name

Description

Schema

rev
required

The revision ID of the revision to delete.

String

Responses

HTTP Code	Description	Schema
200	Successfully removed the local document.
400	There was a problem with your request	HTTPError
404	Resource could not be found	HTTPError
409	A revision ID conflict would result from deleting this document revision.

Gets all the documents in the database with the given parameters

GET /{keyspace}/_all_docs

Description

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

Required Sync Gateway RBAC roles:

Sync Gateway Application
Sync Gateway Application Read Only

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

keyspace
required

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
optional

Include the body associated with each document.

Boolean

channels
optional

Include the channels each document is part of that the calling user also has access too.

Boolean

access
optional

Include what user/roles that each document grants access too.

Boolean

revs
optional

Include all the revisions for each document under the _revisions property.

Boolean

update_seq
optional

Include the document sequence number update_seq property for each document.

Boolean

keys
optional

An array of document ID strings to filter by.

String array

startkey
optional

Return records starting with the specified key.

String

endkey
optional

Stop returning records when this key is reached.

String

limit
optional

This limits the number of result rows returned. Using a value of 0 has the same effect as the value 1.

Big Decimal

Responses

HTTP Code

Description

Schema

200

Operation ran successfully

400

There was a problem with your request

404

Resource could not be found

GetKeyspaceDocid200Response

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

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

keyspace
required

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
required

The document ID to run the operation against.

String

Query Parameters

Name Description Schema

rev
optional

The document revision to target.

String

open_revs
optional

Option to fetch specified revisions of the document. The value can be all to fetch all leaf revisions or an array of revision numbers (i.e. open_revs=["rev1", "rev2"]). Only leaf revision bodies that haven't been pruned are guaranteed to be returned. If this option is specified the response will be in multipart format. Use the Accept: application/json request header to get the result as a JSON object.

String array

show_exp
optional

Whether to show the expiry property (_exp) in the response.

Boolean

revs_from
optional

Trim the revision history to stop at the first revision in the provided list. If no match is found, the revisions will be trimmed to the revs_limit.

String array

atts_since
optional

Include attachments only since specified revisions. Excludes the attachments for the specified revisions. Only gets used if attachments=true.

String array

revs_limit
optional

Maximum amount of revisions to return for each document.

Integer

attachments
optional

Include attachment bodies in response.

Boolean

replicator2
optional

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

Produces

application/json

Parameters

Path Parameters

Name Description Schema

keyspace
required

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
required

The document ID to run the operation against.

String

attach
required

The attachment name. This value must be URL encoded. For example, if the attachment name is blob_/avatar, the path component passed to the URL should be blob_%2Favatar (tested with URLEncoder).

String

Query Parameters

Name Description Schema

rev
optional

The document revision to target.

String

content_encoding
optional

Set to false to disable the Content-Encoding response header.

Boolean

meta
optional

Return only the metadata of the attachment in the response body.

Boolean

Header Parameters

Name

Description

Schema

Range
optional

RFC-2616 bytes range header.

String

Responses

HTTP Code	Description	Schema
200	Found attachment successfully.
206	Partial attachment content returned
404	Resource could not be found	HTTPError
416	Requested range exceeds content length

Get local document

GET /{keyspace}/_local/{docid}

Description

This request retrieves a local document.

Required Sync Gateway RBAC roles:

Sync Gateway Application
Sync Gateway Application Read Only

Produces

application/json

Parameters

Path Parameters

Name Description Schema

keyspace
required

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
required

The name of the local document ID excluding the _local/ prefix.

String

Responses

HTTP Code

Description

Schema

200

Successfully found local document

400

There was a problem with your request

404

Resource could not be found

GetKeyspaceRawDocid200Response

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

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

keyspace
required

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
required

The document ID to run the operation against.

String

Query Parameters

Name Description Schema

include_doc
optional

Include the body associated with the document.

String

redact
optional

This redacts sensitive parts of the response. Cannot be used when include_docs=true

Boolean

Responses

HTTP Code

Description

Schema

200

Document found successfully

400

There was a problem with your request

404

Resource could not be found

/{db}/_all_docs

HEAD /{keyspace}/_all_docs

Description

Required Sync Gateway RBAC roles:

Sync Gateway Application
Sync Gateway Application Read Only

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

keyspace
required

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
optional

Include the body associated with each document.

Boolean

channels
optional

Include the channels each document is part of that the calling user also has access too.

Boolean

access
optional

Include what user/roles that each document grants access too.

Boolean

revs
optional

Include all the revisions for each document under the _revisions property.

Boolean

update_seq
optional

Include the document sequence number update_seq property for each document.

Boolean

keys
optional

An array of document ID strings to filter by.

String array

startkey
optional

Return records starting with the specified key.

String

endkey
optional

Stop returning records when this key is reached.

String

limit
optional

This limits the number of result rows returned. Using a value of 0 has the same effect as the value 1.

Big Decimal

Responses

HTTP Code

Description

Schema

200

400

There was a problem with your request

404

Resource could not be found

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

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

keyspace
required

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
required

The document ID to run the operation against.

String

Query Parameters

Name Description Schema

rev
optional

The document revision to target.

String

open_revs
optional

String array

show_exp
optional

Whether to show the expiry property (_exp) in the response.

Boolean

revs_from
optional

Trim the revision history to stop at the first revision in the provided list. If no match is found, the revisions will be trimmed to the revs_limit.

String array

atts_since
optional

Include attachments only since specified revisions. Excludes the attachments for the specified revisions. Only gets used if attachments=true.

String array

revs_limit
optional

Maximum amount of revisions to return for each document.

Integer

attachments
optional

Include attachment bodies in response.

Boolean

replicator2
optional

Returns the document with the required properties for replication. This is an enterprise-edition only feature.

Boolean

Responses

HTTP Code

Description

Schema

200

Document exists

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

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

Produces

application/json

Parameters

Path Parameters

Name Description Schema

keyspace
required

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
required

The document ID to run the operation against.

String

attach
required

The attachment name. This value must be URL encoded. For example, if the attachment name is blob_/avatar, the path component passed to the URL should be blob_%2Favatar (tested with URLEncoder).

String

Query Parameters

Name

Description

Schema

rev
optional

The document revision to target.

String

Responses

HTTP Code	Description	Schema
200	The document exists and the attachment exists on the document.
404	Resource could not be found	HTTPError

Check if local document exists

HEAD /{keyspace}/_local/{docid}

Description

This request checks if a local document exists.

Required Sync Gateway RBAC roles:

Sync Gateway Application
Sync Gateway Application Read Only

Produces

application/json

Parameters

Path Parameters

Name Description Schema

keyspace
required

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
required

The name of the local document ID excluding the _local/ prefix.

String

Responses

HTTP Code

Description

Schema

200

Document exists

400

There was a problem with your request

404

Resource could not be found

/{keyspace}/_raw/{docid}

HEAD /{keyspace}/_raw/{docid}

Description

Required Sync Gateway RBAC roles:

Sync Gateway Application
Sync Gateway Application Read Only

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

keyspace
required

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
required

The document ID to run the operation against.

String

Responses

HTTP Code

Description

Schema

200

Document exists

400

There was a problem with your request

404

Resource could not be found

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.

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

keyspace
required

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

roundtrip
optional

Block until document has been received by change cache

Boolean

Body Parameter

Name

Description

Schema

Body
optional

PostKeyspaceRequest

Responses

HTTP Code

Description

Schema

200

New document revision created successfully.

400

There was a problem with your request

404

Resource could not be found

409

Resource already exists under that name

415

Invalid content type

PostKeyspaceAllDocsRequest

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

POST /{keyspace}/_all_docs

Description

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

Required Sync Gateway RBAC roles:

Sync Gateway Application
Sync Gateway Application Read Only

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

keyspace
required

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
optional

Include the body associated with each document.

Boolean

channels
optional

Include the channels each document is part of that the calling user also has access too.

Boolean

access
optional

Include what user/roles that each document grants access too.

Boolean

revs
optional

Include all the revisions for each document under the _revisions property.

Boolean

update_seq
optional

Include the document sequence number update_seq property for each document.

Boolean

startkey
optional

Return records starting with the specified key.

String

endkey
optional

Stop returning records when this key is reached.

String

limit
optional

This limits the number of result rows returned. Using a value of 0 has the same effect as the value 1.

Big Decimal

Body Parameter

Name

Description

Schema

Body
optional

Responses

HTTP Code

Description

Schema

200

Operation ran successfully

GetKeyspaceAllDocs200Response

400

There was a problem with your request

404

Resource could not be found

PostKeyspaceBulkDocsRequest

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

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

keyspace
required

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
optional

Responses

HTTP Code

Description

Schema

201

Executed all operations. Each object in the returned array represents a document. Each document should be checked to make sure it was successfully added to the database.

PostKeyspaceBulkDocs201ResponseInner array

400

There was a problem with your request

404

Resource could not be found

PostKeyspaceBulkGetRequest

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

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

keyspace
required

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

attachments
optional

This is for whether to include attachments in each of the documents returned or not.

Boolean

revs
optional

Include all the revisions for each document under the _revisions property.

Boolean

revs_limit
optional

The number of revisions to include in the response from the document history. This parameter only makes a different if the revs query parameter is set to true. The full revision history will be returned if revs is set but this is not.

Integer

Header Parameters

Name Description Schema

X-Accept-Part-Encoding
optional

If this header includes gzip then the part HTTP compression encoding will be done.

String

Accept-Encoding
optional

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

String

Body Parameter

Name

Description

Schema

Body
optional

Responses

HTTP Code	Description	Schema
200	Returned the requested docs as `multipart/mixed` response type
400	Bad Request
404	Resource could not be found	HTTPError

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

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

keyspace
required

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
optional

Purge request body

PostKeyspacePurgeRequest

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

PostKeyspacePurge200Response

400

Bad request. This could be due to the documents listed in the request body not having the [\"*\"] value for each document ID.

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

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

keyspace
required

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
required

The document ID to run the operation against.

String

Query Parameters

Name Description Schema

roundtrip
optional

Block until document has been received by change cache

Boolean

replicator2
optional

Returns the document with the required properties for replication. This is an enterprise-edition only feature.

Boolean

new_edits
optional

Setting this to false indicates that the request body is an already-existing revision that should be directly inserted into the database, instead of a modification to apply to the current document. This mode is used for replication. This option must be used in conjunction with the _revisions property in the request body.

Boolean

rev
optional

The document revision to target.

String

Header Parameters

Name

Description

Schema

If-Match
optional

The revision ID to target.

String

Body Parameter

Name

Description

Schema

Body
optional

PostKeyspaceRequest

Responses

HTTP Code

Description

Schema

201

Created

400

There was a problem with your request

404

Resource could not be found

409

Resource already exists under that name

415

Invalid content type

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

Consumes

Attachment content type

Produces

application/json

Parameters

Path Parameters

Name Description Schema

keyspace
required

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
required

The document ID to run the operation against.

String

attach
required

The attachment name. This value must be URL encoded. For example, if the attachment name is blob_/avatar, the path component passed to the URL should be blob_%2Favatar (tested with URLEncoder).

String

Query Parameters

Name

Description

Schema

rev
optional

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

String

Header Parameters

Name

Description

Schema

Content-Type
optional

The content type of the attachment.

String

If-Match
optional

An alternative way of specifying the document revision ID.

String

Body Parameter

Name

Description

Schema

Body
optional

The attachment data

String

Responses

HTTP Code

Description

Schema

201

Attachment added to new or existing document successfully

404

Resource could not be found

409

Resource already exists under that name

PutKeyspaceLocalDocidRequest

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

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name Description Schema

keyspace
required

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
required

The name of the local document ID excluding the _local/ prefix.

String

Body Parameter

Name

Description

Schema

Body
optional

The body of the document

Responses

HTTP Code Description Schema

201

Document successfully written. The document ID will be prefixed with _local/.

400

There was a problem with your request

404

Resource could not be found

Get all Sync Gateway statistics
Get memory statistics

409

A revision ID conflict would result from updating this document revision.

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

Produces

application/javascript

Responses

HTTP Code

Description

Schema

200

Returned statistics

GetExpvar200Response

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

Produces

application/json

Responses

HTTP Code

Description

Schema

200

Returned memory usage statistics

GetStats200Response

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

Produces

application/x-gzip

Parameters

Query Parameters

Name Description Schema

seconds
optional

The amount of seconds to run the profiler for.

Minimum: 0

Integer

Responses

HTTP Code

Description

Schema

200

String

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

Produces

application/octet-stream
application/json

Parameters

Query Parameters

Name Description Schema

seconds
optional

The amount of seconds to run the profiler for.

Minimum: 0

Integer

Responses

HTTP Code

Description

Schema

200

String

403

Forbidden

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

Produces

text/plain

Responses

HTTP Code

Description

Schema

200

String

Get goroutine profile

GET /_debug/pprof/goroutine

Description

Stack traces of all current goroutines.

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

Produces

application/octet-stream

Parameters

Query Parameters

Name

Description

Schema

seconds
optional

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

Integer

Responses

HTTP Code

Description

Schema

200

String

Get the heap pprof debug file

GET /_debug/pprof/heap

Description

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

Produces

application/octet-stream

Parameters

Query Parameters

Name

Description

Schema

seconds
optional

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

Integer

Responses

HTTP Code

Description

Schema

200

String

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

Produces

application/octet-stream
application/json

Parameters

Query Parameters

Name Description Schema

seconds
optional

The amount of seconds to run the profiler for.

Minimum: 0

Integer

Responses

HTTP Code

Description

Schema

200

String

403

Forbidden

Get the profile pprof debug file

GET /_debug/pprof/profile

Description

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

Produces

application/octet-stream

Parameters

Query Parameters

Name

Description

Schema

seconds
optional

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

Integer

Responses

HTTP Code

Description

Schema

200

String

Get symbol pprof debug information

GET /_debug/pprof/symbol

Description

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

Produces

text/plain

Responses

HTTP Code

Description

Schema

200

String

Get the threadcreate pprof debug file

GET /_debug/pprof/threadcreate

Description

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

Produces

application/octet-stream

Responses

HTTP Code

Description

Schema

200

String

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

Produces

application/octet-stream

Parameters

Query Parameters

Name

Description

Schema

seconds
optional

Integer

Responses

HTTP Code

Description

Schema

200

String

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

Produces

application/x-gzip

Parameters

Query Parameters

Name Description Schema

seconds
optional

The amount of seconds to run the profiler for.

Minimum: 0

Integer

Responses

HTTP Code

Description

Schema

200

String

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

Produces

application/octet-stream
application/json

Parameters

Query Parameters

Name Description Schema

seconds
optional

The amount of seconds to run the profiler for.

Minimum: 0

Integer

Responses

HTTP Code

Description

Schema

200

String

403

Forbidden

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

Produces

text/plain

Responses

HTTP Code

Description

Schema

200

String

Get goroutine profile

POST /_debug/pprof/goroutine

Description

Stack traces of all current goroutines.

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

Produces

application/octet-stream

Parameters

Query Parameters

Name

Description

Schema

seconds
optional

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

Integer

Responses

HTTP Code

Description

Schema

200

String

Get the heap pprof debug file

POST /_debug/pprof/heap

Description

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

Produces

application/octet-stream

Parameters

Query Parameters

Name

Description

Schema

seconds
optional

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

Integer

Responses

HTTP Code

Description

Schema

200

String

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

Produces

application/octet-stream
application/json

Parameters

Query Parameters

Name Description Schema

seconds
optional

The amount of seconds to run the profiler for.

Minimum: 0

Integer

Responses

HTTP Code

Description

Schema

200

String

403

Forbidden

PostProfileProfilenameRequest

Get the profile pprof debug file

POST /_debug/pprof/profile

Description

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

Produces

application/octet-stream

Parameters

Query Parameters

Name

Description

Schema

seconds
optional

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

Integer

Responses

HTTP Code

Description

Schema

200

String

Get symbol pprof debug information

POST /_debug/pprof/symbol

Description

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

Produces

text/plain

Responses

HTTP Code

Description

Schema

200

String

Get the threadcreate pprof debug file

POST /_debug/pprof/threadcreate

Description

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

Produces

application/octet-stream

Responses

HTTP Code

Description

Schema

200

String

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

Produces

application/octet-stream

Parameters

Query Parameters

Name

Description

Schema

seconds
optional

Integer

Responses

HTTP Code

Description

Schema

200

String

Dump heap profile

POST /_heap

Description

This endpoint will dump a pprof heap profile.

Required Sync Gateway RBAC roles:

Sync Gateway Dev Ops

Consumes

application/json

Produces

application/json

Parameters

Body Parameter

Name

Description

Schema

Body
optional

Responses

HTTP Code	Description	Schema
200	Successfully dumped heap profile
400	There was a problem with your request	HTTPError

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

Consumes

application/json

Produces

application/json

Parameters

Body Parameter

Name

Description

Schema

Body
optional

PostProfileProfilenameRequest

Responses

HTTP Code	Description	Schema
200	Successfully started or stopped CPU profiling
400	There was a problem with your request	HTTPError

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

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name Description Schema

profilename
required

The handler to use for profiling.

Values: "heap", "block", "threadcreate", "mutex", "goroutine"

String

Body Parameter

Name

Description

Schema

Body
optional

PostProfileProfilenameRequest

Responses

HTTP Code

Description

Schema

200

Successfully created profile

400

There was a problem with your request

404

Resource could not be found

Stop and delete a replication
Handle incoming BLIP Sync web socket request
Get all replication configurations
Get a replication configuration
Get all replication statuses
Get replication status
/{db}/_replication/
Check if a replication exists
/{db}/_replicationStatus/
Check if replication exists
Upsert a replication
Upsert a replication
Control a replication state

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

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

replicationid
required

What replication to target based on its replication ID.

String

Responses

HTTP Code

Description

Schema

200

Replication successfully deleted

400

There was a problem with your request

404

Resource could not be found

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

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Query Parameters

Name Description Schema

client
optional

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

Values: "cbl2", "sgr2"

String

Responses

HTTP Code

Description

Schema

101

Upgraded to a web socket connection

404

Resource could not be found

426

Cannot upgrade connection to a web socket connection

Get all replication configurations

GET /{db}/_replication/

Description

This will retrieve all database replication definitions.

Required Sync Gateway RBAC roles:

Sync Gateway Replicator

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Responses

HTTP Code Description Schema

200

Retrieved replication configurations successfully. The assigned_node fields will end with (local) or (non-local) depending on if the replication is running on this Sync Gateway node.

AllReplications

404

Resource could not be found

Get a replication configuration

GET /{db}/_replication/{replicationid}

Description

Retrieve a replication configuration from the database.

Required Sync Gateway RBAC roles:

Sync Gateway Replicator

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

replicationid
required

What replication to target based on its replication ID.

String

Responses

HTTP Code

Description

Schema

200

Successfully retrieved the replication configuration

Replication1

404

Resource could not be found

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

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Query Parameters

Name Description Schema

activeOnly
optional

Only return replications that are actively running (state=running).

Boolean

localOnly
optional

Only return replications that were started on the current Sync Gateway node.

Boolean

includeError
optional

Include replications that have stopped due to an error (state=error).

Boolean

includeConfig
optional

Include the replication configuration with each replicator status in the response.

Boolean

Responses

HTTP Code

Description

Schema

200

Successfully retrieved all replication statuses.

ReplicationStatus array

400

There was a problem with your request

Get replication status

GET /{db}/_replicationStatus/{replicationid}

Description

Retrieve the status of a replication.

Required Sync Gateway RBAC roles:

Sync Gateway Replicator

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

replicationid
required

What replication to target based on its replication ID.

String

Query Parameters

Name Description Schema

activeOnly
optional

Only return replications that are actively running (state=running).

Boolean

localOnly
optional

Only return replications that were started on the current Sync Gateway node.

Boolean

includeError
optional

Include replications that have stopped due to an error (state=error).

Boolean

includeConfig
optional

Include the replication configuration with each replicator status in the response.

Boolean

Responses

HTTP Code

Description

Schema

200

Successfully retrieved replication status

ReplicationStatus

400

There was a problem with your request

404

Could not find replication

/{db}/_replication/

HEAD /{db}/_replication/

Description

Required Sync Gateway RBAC roles:

Sync Gateway Replicator

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Responses

HTTP Code	Description	Schema
200	OK
404	Not Found

Check if a replication exists

HEAD /{db}/_replication/{replicationid}

Description

Check if a replication exists.

Required Sync Gateway RBAC roles:

Sync Gateway Replicator

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

replicationid
required

What replication to target based on its replication ID.

String

Responses

HTTP Code	Description	Schema
200	Replication exists
404	Replication does not exist

/{db}/_replicationStatus/

HEAD /{db}/_replicationStatus/

Description

Required Sync Gateway RBAC roles:

Sync Gateway Replicator

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Responses

HTTP Code	Description	Schema
200	OK
400	Bad Request

Check if replication exists

HEAD /{db}/_replicationStatus/{replicationid}

Description

Check if a replication exists.

Required Sync Gateway RBAC roles:

Sync Gateway Replicator

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

replicationid
required

What replication to target based on its replication ID.

String

Query Parameters

Name Description Schema

activeOnly
optional

Only return replications that are actively running (state=running).

Boolean

localOnly
optional

Only return replications that were started on the current Sync Gateway node.

Boolean

includeError
optional

Include replications that have stopped due to an error (state=error).

Boolean

includeConfig
optional

Include the replication configuration with each replicator status in the response.

Boolean

Responses

HTTP Code

Description

Schema

200

Replication exists

400

There was a problem with your request

404

Resource could not be found

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

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Body Parameter

Name Description Schema

Body
optional

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

Responses

HTTP Code	Description	Schema
200	Updated existing configuration successfully
201	Created new replication successfully
400	There was a problem with your request	HTTPError
404	Resource could not be found	HTTPError

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

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

replicationid
required

What replication to target based on its replication ID.

String

Body Parameter

Name Description Schema

Body
optional

Responses

HTTP Code	Description	Schema
200	Updated existing configuration successfully
201	Created new replication successfully
400	There was a problem with your request	HTTPError
404	Resource could not be found	HTTPError

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 replication
stop - stops an active replication
reset - resets the replication checkpoint to 0. For bidirectional replication, both push and pull checkpoints are reset to 0. The replication must be stopped to use this.

Required Sync Gateway RBAC roles:

Sync Gateway Replicator

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

replicationid
required

What replication to target based on its replication ID.

String

Query Parameters

Name Description Schema

action
required

The target state to put the replicator into.

Values: "start", "stop", "reset"

String

Responses

HTTP Code

Description

Schema

200

Successfully changed target state of replicator

ReplicationStatus

400

There was a problem with your request

404

Resource could not be found

Cancel the Sync Gateway Collect Info job
Get server information
Get server configuration
Get console logging settings
Check if API is available
Get the status of the Sync Gateway Collect Info
Get the server status
Check if server online
Check if API is available
Update console logging settings
Run the post upgrade process on all databases
Start Sync Gateway Collect Info
Set runtime configuration
Set console logging settings

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

Produces

application/json

Responses

HTTP Code

Description

Schema

200

Job cancelled successfully

DeleteSgcollectInfo200Response

400

There was a problem with your request

Get server information

GET /

Description

Returns information about the Sync Gateway node.

Produces

application/json

Responses

HTTP Code

Description

Schema

200

Returned server information

Get200Response

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

Produces

application/json

Parameters

Query Parameters

Name

Description

Schema

redact
optional

No longer supported field.

Boolean

include_runtime
optional

Whether to include the values set after starting (at runtime), default values, and all loaded databases.

Boolean

Responses

HTTP Code

Description

Schema

200

Successfully returned server configuration

StartupConfig

400

There was a problem with your request

Get console logging settings

GET /_logging

This operation is deprecated, and will be removed in a future release.

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

Produces

application/json

Responses

HTTP Code

Description

Schema

200

Returned map of console log keys

GetSgcollectInfo200Response

Check if API is available

GET /_ping

Description

Returns OK status if API is available.

Produces

text/plain

Responses

HTTP Code

Description

Schema

200

Returned status

String

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

Produces

application/json

Responses

HTTP Code

Description

Schema

200

Returned sgcollect_info status

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

Produces

application/json

Responses

HTTP Code

Description

Schema

200

Returned the status successfully

Status1

400

There was a problem with your request

Check if server online

HEAD /

Description

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

Responses

HTTP Code

Description

Schema

200

Server is online

Check if API is available

HEAD /_ping

Description

Returns OK status if API is available.

Responses

HTTP Code

Description

Schema

200

Server is available

Update console logging settings

POST /_logging

This operation is deprecated, and will be removed in a future release.

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

Consumes

application/json

Produces

application/json

Parameters

Query Parameters

Name Description Schema

logLevel
optional

The is what to set the console log level too.

Values: "none", "error", "warn", "info", "debug", "trace"

String

level
optional

Deprecated: use log level instead.

This sets the console log level depending on the value provide. 1 sets to info, 2 sets to warn, and 3 sets to error.'

Minimum: 1
Maximum: 3

Integer

Body Parameter

Name

Description

Schema

Body
optional

The console log keys to upsert.

PostPostUpgrade200Response

Responses

HTTP Code	Description	Schema
200	Log keys successfully updated.
400	There was a problem with your request	HTTPError

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

Produces

application/json

Parameters

Query Parameters

Name

Description

Schema

preview
optional

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

String

Responses

HTTP Code

Description

Schema

200

Returned results

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

Consumes

application/json

Produces

application/json

Parameters

Body Parameter

Name

Description

Schema

Body
optional

sgcollect_info options

PostSgcollectInfoRequest

Responses

HTTP Code

Description

Schema

200

Successfully started sgcollect_info

PostSgcollectInfo200Response

400

There was a problem with your request

500

An error occurred while trying to run sgcollect_info

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

Consumes

application/json

Produces

application/json

Parameters

Body Parameter

Name

Description

Schema

Body
optional

RuntimeConfig

Responses

HTTP Code	Description	Schema
200	Successfully set runtime options
400	There was a problem with your request	HTTPError

Set console logging settings

PUT /_logging

This operation is deprecated, and will be removed in a future release.

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

Consumes

application/json

Produces

application/json

Parameters

Query Parameters

Name Description Schema

logLevel
optional

The is what to set the console log level too.

Values: "none", "error", "warn", "info", "debug", "trace"

String

level
optional

Deprecated: use log level instead.

This sets the console log level depending on the value provide. 1 sets to info, 2 sets to warn, and 3 sets to error.'

Minimum: 1
Maximum: 3

Integer

Body Parameter

Name

Description

Schema

Body
optional

The map of log keys to use for console logging.

Remove session
Remove all of a users sessions
Remove session with user validation
Get information about the current user
Get session information
/{db}/_session
Create a new user session

Responses

HTTP Code	Description	Schema
200	Log keys successfully replaced.
400	There was a problem with your request	HTTPError

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

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

sessionid
required

The ID of the session to target.

String

Responses

HTTP Code	Description	Schema
200	Successfully removed the user session
404	Resource could not be found	HTTPError

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

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

name
required

The name of the user.

String

Responses

HTTP Code	Description	Schema
200	User now has no sessions
404	Resource could not be found	HTTPError

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

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

name
required

The name of the user.

String

sessionid
required

The ID of the session to target.

String

Responses

HTTP Code	Description	Schema
200	Session has been successfully removed as the user was associated with the session
404	Resource could not be found	HTTPError

Get information about the current user

GET /{db}/_session

Description

This will get the information about the current user.

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Responses

HTTP Code

Description

Schema

200

Properties associated with a user session

UserSessionInformation

404

Resource could not be found

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

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

sessionid
required

The ID of the session to target.

String

Responses

HTTP Code

Description

Schema

200

Properties associated with a user session

UserSessionInformation

404

Resource could not be found

/{db}/_session

HEAD /{db}/_session

Description

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Responses

HTTP Code	Description	Schema
200	OK
404	Resource could not be found	HTTPError

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

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Body Parameter

Name

Description

Schema

Body
optional

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

PostDbSessionRequest

Responses

HTTP Code

Description

Schema

200

Session created successfully. Returned body is dependant on if using Public or Admin APIs.

PostDbSession200Response

400

Origin is not in the approved list of allowed origins

404

Resource could not be found

Delete a design document | Unsupported
Get views of a design document | Unsupported
Query a view on a design document | Unsupported
Dump a view | Unsupported
Query a view on the default design document | Unsupported
Dump all the documents in a channel | Unsupported
Revision tree structure in Graphviz Dot format | Unsupported
Check if view of design document exists | Unsupported
Flush the entire database bucket | Unsupported
Disabled endpoint
Update views of a design document | Unsupported

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

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

ddoc
required

The design document name.

String

Responses

HTTP Code	Description	Schema
200	Design document deleted successfully
403	Forbidden access possibly due to not using the Admin API or the design document is a built-in Sync Gateway one.
404	Resource could not be found	HTTPError

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

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

ddoc
required

The design document name.

String

Responses

HTTP Code

Description

Schema

200

Successfully returned design document.

GetDbDesignDdoc200Response

403

Forbidden access possibly due to not using the Admin API or the design document is a built-in Sync Gateway one.

404

Resource could not be found

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

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

ddoc
required

The design document name.

String

view
required

The view to target.

String

Query Parameters

Name Description Schema

inclusive_end
optional

Indicates whether the specified end key should be included in the result.

Boolean

descending
optional

Return documents in descending order.

Boolean

include_docs
optional

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
optional

Whether to execute a reduce function on the response or not.

Boolean

group
optional

Group the results using the reduce function to a group or single row.

Boolean

skip
optional

Skip the specified number of documents before starting to return results.

Integer

limit
optional

Return only the specified number of documents

Integer

group_level
optional

Specify the group level to be used.

Integer

startkey_docid
optional

Return documents starting with the specified document identifier.

String

endkey_docid
optional

Stop returning records when the specified document identifier is reached.

String

stale
optional

Allow the results from a stale view to be used, without triggering a rebuild of all views within the encompassing design document.

Values: "ok", "update_after"

String

startkey
optional

Return records starting with the specified key.

String

endkey
optional

Stop returning records when this key is reached.

String

key
optional

Return only the document that matches the specified key.

String

keys
optional

An array of document ID strings to filter by.

String array

Responses

HTTP Code

Description

Schema

200

Returned view successfully

GetDbViewView200Response

403

Forbidden

404

Resource could not be found

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

Produces

text/html
application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

view
required

The view to target.

String

Responses

HTTP Code

Description

Schema

200

Retrieved view successfully

String

404

Resource could not be found

500

Internal Server Error

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

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

view
required

The view to target.

String

Query Parameters

Name Description Schema

inclusive_end
optional

Indicates whether the specified end key should be included in the result.

Boolean

descending
optional

Return documents in descending order.

Boolean

include_docs
optional

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
optional

Whether to execute a reduce function on the response or not.

Boolean

group
optional

Group the results using the reduce function to a group or single row.

Boolean

skip
optional

Skip the specified number of documents before starting to return results.

Integer

limit
optional

Return only the specified number of documents

Integer

group_level
optional

Specify the group level to be used.

Integer

startkey_docid
optional

Return documents starting with the specified document identifier.

String

endkey_docid
optional

Stop returning records when the specified document identifier is reached.

String

stale
optional

Allow the results from a stale view to be used, without triggering a rebuild of all views within the encompassing design document.

Values: "ok", "update_after"

String

startkey
optional

Return records starting with the specified key.

String

endkey
optional

Stop returning records when this key is reached.

String

key
optional

Return only the document that matches the specified key.

String

keys
optional

An array of document ID strings to filter by.

String array

Responses

HTTP Code

Description

Schema

200

Returned view successfully

GetDbViewView200Response

403

Forbidden

404

Resource could not be found

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

Produces

text/html
application/json

Parameters

Path Parameters

Name

Description

Schema

keyspace
required

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

channel
required

The channel to dump all the documents from.

String

Query Parameters

Name

Description

Schema

since
optional

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

Responses

HTTP Code

Description

Schema

200

Successfully got all documents in the channel

String

404

Resource could not be found

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.

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

keyspace
required

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
required

The document ID to run the operation against.

String

Responses

HTTP Code

Description

Schema

200

Found document

String

404

Resource could not be found

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

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

ddoc
required

The design document name.

String

Responses

HTTP Code	Description	Schema
200	Design document exists
403	Forbidden access possibly due to not using the Admin API or the design document is a built-in Sync Gateway one.
404	Resource could not be found	HTTPError

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

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Responses

HTTP Code

Description

Schema

200

Successfully flushed the bucket

404

Resource could not be found

503

The bucket does not support flush or delete

GetDbDesignDdoc200Response

Disabled endpoint

POST /{db}/_repair

Description

This endpoint is disabled.

Required Sync Gateway RBAC roles:

Sync Gateway Architect

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Responses

HTTP Code

Description

Schema

500

This endpoint is disabled

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

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

ddoc
required

The design document name.

String

Body Parameter

Name

Description

Schema

Body
optional

Responses

HTTP Code	Description	Schema
200	Design document changes successfully
403	Forbidden access possibly due to not using the Admin API or the design document is a built-in Sync Gateway one.
404	Resource could not be found	HTTPError

Definitions

This section describes the properties consumed and returned by this REST API.

All replications

Object

Property

Schema

replication_id
optional

Properties of a replication

Replication1

ChangesFeed

Object

Property Schema

results
optional

Unique items: true

GetKeyspaceChanges200ResponseResultsInner array

last_seq
optional

The last change sequence number.

String

CollectionAccessConfig

Object

Property Schema

admin_channels
optional

A list of channels to explicitly grant to the user.

String array

all_channels
optional

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

String array

jwt_channels
optional

The channels that the user has been granted access to through channels_claim.

String array

jwt_last_updated
optional

The last time that the user's JWT roles/channels were updated.

Date (date-time)

Collection config

Object

Property Schema

sync
optional

The Javascript function that newly created documents in this collection are ran through.

String

import_filter
optional

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.

import_docs in the database config must be true to make this field applicable.

String

Compact-status

Object

Property Schema

status
required

The status of the current operation.

String

start_time
required

The ISO-8601 date and time the compact operation was started.

String

last_error
required

The last error that occurred in the compact operation (if any).

String

docs_purged
optional

Applicable to tombstone compaction only

This is the amount of documents that have been purged so far.

String

marked_attachments
optional

Applicable to attachment compaction only

This is the number of references there are to legacy attachments.

String

purged_attachments
optional

Applicable to attachment compaction only

This is the amount of attachments that have been purged so far.

String

compact_id
optional

Applicable to attachment compaction only

This is the ID of the compaction.

String

phase
optional

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
optional

Applicable to attachment compaction only

Values: "mark", "sweep", "cleanup"

String

Console-logging-config

Object

Property Schema

log_level
optional

Log Level for the console output

Values: "none", "error", "warn", "info", "debug", "trace"

String

log_keys
optional

Log Keys for the console output

String array

color_enabled
optional

Log with color for the console output

Boolean

file_output
optional

Override the default stderr output, and write to the file specified instead

String

enabled
optional

Toggle for this log output

Boolean

rotation
optional

LogRotationConfig

collation_buffer_size
optional

The size of the log collation buffer. The default is 10 if the output is stderr, or 1000 if to a file.

Integer

Credentials config

Object

Property

Schema

username
optional

Username for authenticating to the bucket

String

password
optional

Password for authenticating to the bucket. This value is always redacted.

String

x509_cert_path
optional

Cert path (public key) for X.509 bucket auth

String

x509_key_path
optional

Key path (private key) for X.509 bucket auth

String

Credentials config

Object

Property

Schema

username
optional

Username for authenticating to the bucket

String

password
optional

Password for authenticating to the bucket. This value is always redacted.

String

x509_cert_path
optional

Cert path (public key) for X.509 bucket auth

String

x509_key_path
optional

Key path (private key) for X.509 bucket auth

String

Database-config

Object

Property Schema

server
optional

This is the Couchbase Server address or addresses that the database connect to.

String

pool
optional

This field is unsupported and ignored.

String

bucket
optional

The Couchbase Server backing bucket for the database.

String

username
optional

The username for authenticating to the server.

String

password
optional

The password for authenticating to the server.

String

certpath
optional

The cert path (public key) for X.509 bucket auth.

String

keypath
optional

The key path (private key) for X.509 bucket auth

String

cacertpath
optional

The root CA cert path for X.509 bucket authentication.

String

kv_tls_port
optional

The Memcached TLS port.

Integer

max_concurrent_query_ops
optional

The maximum amount of query operations that can be running at any one point.

Integer

scopes
optional

An object keyed by scope name containing config for the specific collection.

Maximum items: 1

name
optional

The name of the database.

String

sync
optional

The Javascript function that newly created documents are ran through for the default scope and collection. If scopes parameter is set, this is ignored.

String

users
optional

roles
optional

DatabaseConfigEventHandlers

revs_limit
optional

The maximum depth a document's revision tree can grow too.

The minimum is 20 if conflicts are allowed and 0 if not. It is not recommended to go below 100 when conflicts are allowed.

Minimum: 0

Big Decimal

import_docs
optional

If true, documents will be imported in to Sync Gateway from the bucket when requested. Documents will be ran through the set import_filter if any is set.

The default value depends on the edition of Sync Gateway being used. If the edition is the community-edition, then this will default to false or else in the enterprise-edition, it will default to true.

This can also be set to the string continuous which maps to true.

Boolean

import_partitions
optional

** This is an enterprise-edition feature only**

This is how many import partitions should be used for import sharding.

Partitions are distributed among all Sync Gateway nodes participating in import processing (import_docs=true), and each process a subset of the server's vbuckets.

Each partition is processed by an independent function that runs simultaneously to others, so import_partitions can be used to tune concurrency based on the number of Sync Gateway nodes, and the number of cores per node.

Big Decimal

import_filter
optional

This is the function that all imported documents in the default scope and collection are ran through in order to filter out what to import and what not to import. This allows you to control what is made available to Couchbase Mobile clients. If it is not set, then no documents are filtered when imported.

import_docs must be true to make this field applicable.

If scopes parameter is set, this is ignored.

String

import_backup_old_rev
optional

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.

Boolean

event_handlers
optional

These are the settings for webhooks.

feed_type
optional

The type of feed to use to communicate with Couchbase Server. This will use DCP regardless of specification.

Values: "DCP"

String

allow_empty_password
optional

This controls whether users that are created can have an empty password or not.

Boolean

cache
optional

DatabaseConfigCache

rev_cache_size
optional

Deprecated, please use the database setting cache.rev_cache.size instead

The maximum number of revisions to store in the revision cache.

Big Decimal

offline
optional

Start the database in an offline state.

Boolean

unsupported
optional

These are unsupported options and therefore it is not recommended to use them.

DatabaseConfigUnsupported

local_jwt
optional

Configuration for Local JWT authentication.

DatabaseConfigReplications

oidc
optional

Configuration for OpenID Connect authentication.

DatabaseConfigOidc

old_rev_expiry_seconds
optional

The number of seconds before old revisions are removed from the Couchbase Server bucket.

Big Decimal

view_query_timeout_secs
optional

The number of seconds before a view query should timeout.

Integer

local_doc_expiry_secs
optional

The number of seconds before a _local document should expire.

Integer

enable_shared_bucket_access
optional

Whether to use extended attributes to store Sync Gateway document (_sync) metadata.

Boolean

session_cookie_secure
optional

Override the session cookie secure flag. If set, the cookie will have the secure flag.

This will default to true if startup config api.https.tls_cert_path is set otherwise it will default to false.

Boolean

session_cookie_name
optional

This can be used to define a custom per-database session cookie name.

String

session_cookie_http_only
optional

Make all session cookies for the database set the HttpOnly flag so they are inaccessible to JavaScript.

Boolean

allow_conflicts
optional

This controls whether to allow conflicting document revisions.

Boolean

num_index_replicas
optional

This is the number of Global Secondary Indexes (GSI) to use for core indexes.

Big Decimal

use_views
optional

Force the use of views instead of GSI.

Boolean

send_www_authenticate_header
optional

Controls whether to send a WWW-Authenticate header in 401 Unauthorized HTTP responses.

Boolean

disable_password_auth
optional

Whether to disable username/password authentication and only allow OIDC and guest access.

Boolean

bucket_op_timeout_ms
optional

This is the amount of milliseconds should pass before a bucket operation times out. An error will be returned if the bucket operation times out saying: operation timed out.

Big Decimal

slow_query_warning_threshold
optional

The amount of milliseconds a N1QL query should run before logging a warning.

Big Decimal

delta_sync
optional

Delta sync configuration settings.

This is an enterprise-edition feature only

DatabaseConfigDeltaSync

compact_interval_days
optional

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.

Big Decimal

sgreplicate_enabled
optional

Whether the node should accept assign replications (true) or not (false).

Boolean

sgreplicate_websocket_heartbeat_secs
optional

Use a custom heartbeat interval (in seconds) for websocket ping frames.

Integer

replications
optional

serve_insecure_attachment_types
optional

If set, always serve attachments with the Content-Type header set to the type of the attachment.

When serving an attachment, usually the Content-Type header is set to the type of the attachment but the Content-Disposition response header will be set instead if the content type is vulnerable to a phishing attack, causing the browser to download the file instead of display it. This option will override that behaviour and always set the Content-Type header.

Boolean

query_pagination_limit
optional

The query limit to be used during pagination of large queries.

Integer

user_xattr_key
optional

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
optional

How long (in seconds) clients can remain offline for without losing replication metadata.

Defaults to 30 days (in seconds)

Integer

guest
optional

Properties associated with a user

javascript_timeout_secs
optional

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.

Big Decimal

suspendable
optional

Set to true to allow the database to be suspended.

Defaults to true when running in serverless mode otherwise defaults to false.

Boolean

cors
optional

CORS configuration for this database; if present, overrides server's config.

DatabaseConfigCors

logging
optional

Per-database logging configuration.

DatabaseConfigLogging

Database-config

Object

Property Schema

server
optional

This is the Couchbase Server address or addresses that the database connect to.

String

pool
optional

This field is unsupported and ignored.

String

bucket
optional

The Couchbase Server backing bucket for the database.

String

username
optional

The username for authenticating to the server.

String

password
optional

The password for authenticating to the server.

String

certpath
optional

The cert path (public key) for X.509 bucket auth.

String

keypath
optional

The key path (private key) for X.509 bucket auth

String

cacertpath
optional

The root CA cert path for X.509 bucket authentication.

String

kv_tls_port
optional

The Memcached TLS port.

Integer

max_concurrent_query_ops
optional

The maximum amount of query operations that can be running at any one point.

Integer

scopes
optional

An object keyed by scope name containing config for the specific collection.

Maximum items: 1

name
optional

The name of the database.

String

sync
optional

The Javascript function that newly created documents are ran through for the default scope and collection. If scopes parameter is set, this is ignored.

String

users
optional

roles
optional

DatabaseConfigEventHandlers

revs_limit
optional

The maximum depth a document's revision tree can grow too.

The minimum is 20 if conflicts are allowed and 0 if not. It is not recommended to go below 100 when conflicts are allowed.

Minimum: 0

Big Decimal

import_docs
optional

If true, documents will be imported in to Sync Gateway from the bucket when requested. Documents will be ran through the set import_filter if any is set.

This can also be set to the string continuous which maps to true.

Boolean

import_partitions
optional

** This is an enterprise-edition feature only**

This is how many import partitions should be used for import sharding.

Partitions are distributed among all Sync Gateway nodes participating in import processing (import_docs=true), and each process a subset of the server's vbuckets.

Big Decimal

import_filter
optional

import_docs must be true to make this field applicable.

If scopes parameter is set, this is ignored.

String

import_backup_old_rev
optional

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.

Boolean

event_handlers
optional

These are the settings for webhooks.

feed_type
optional

The type of feed to use to communicate with Couchbase Server. This will use DCP regardless of specification.

Values: "DCP"

String

allow_empty_password
optional

This controls whether users that are created can have an empty password or not.

Boolean

cache
optional

DatabaseConfigCache

rev_cache_size
optional

Deprecated, please use the database setting cache.rev_cache.size instead

The maximum number of revisions to store in the revision cache.

Big Decimal

offline
optional

Start the database in an offline state.

Boolean

unsupported
optional

These are unsupported options and therefore it is not recommended to use them.

DatabaseConfigUnsupported

local_jwt
optional

Configuration for Local JWT authentication.

DatabaseConfigReplications

oidc
optional

Configuration for OpenID Connect authentication.

DatabaseConfigOidc

old_rev_expiry_seconds
optional

The number of seconds before old revisions are removed from the Couchbase Server bucket.

Big Decimal

view_query_timeout_secs
optional

The number of seconds before a view query should timeout.

Integer

local_doc_expiry_secs
optional

The number of seconds before a _local document should expire.

Integer

enable_shared_bucket_access
optional

Whether to use extended attributes to store Sync Gateway document (_sync) metadata.

Boolean

session_cookie_secure
optional

Override the session cookie secure flag. If set, the cookie will have the secure flag.

This will default to true if startup config api.https.tls_cert_path is set otherwise it will default to false.

Boolean

session_cookie_name
optional

This can be used to define a custom per-database session cookie name.

String

session_cookie_http_only
optional

Make all session cookies for the database set the HttpOnly flag so they are inaccessible to JavaScript.

Boolean

allow_conflicts
optional

This controls whether to allow conflicting document revisions.

Boolean

num_index_replicas
optional

This is the number of Global Secondary Indexes (GSI) to use for core indexes.

Big Decimal

use_views
optional

Force the use of views instead of GSI.

Boolean

send_www_authenticate_header
optional

Controls whether to send a WWW-Authenticate header in 401 Unauthorized HTTP responses.

Boolean

disable_password_auth
optional

Whether to disable username/password authentication and only allow OIDC and guest access.

Boolean

bucket_op_timeout_ms
optional

This is the amount of milliseconds should pass before a bucket operation times out. An error will be returned if the bucket operation times out saying: operation timed out.

Big Decimal

slow_query_warning_threshold
optional

The amount of milliseconds a N1QL query should run before logging a warning.

Big Decimal

delta_sync
optional

Delta sync configuration settings.

This is an enterprise-edition feature only

DatabaseConfigDeltaSync

compact_interval_days
optional

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.

Big Decimal

sgreplicate_enabled
optional

Whether the node should accept assign replications (true) or not (false).

Boolean

sgreplicate_websocket_heartbeat_secs
optional

Use a custom heartbeat interval (in seconds) for websocket ping frames.

Integer

replications
optional

serve_insecure_attachment_types
optional

If set, always serve attachments with the Content-Type header set to the type of the attachment.

Boolean

query_pagination_limit
optional

The query limit to be used during pagination of large queries.

Integer

user_xattr_key
optional

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
optional

How long (in seconds) clients can remain offline for without losing replication metadata.

Defaults to 30 days (in seconds)

Integer

guest
optional

Properties associated with a user

DatabaseConfigCacheRevCache

javascript_timeout_secs
optional

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.

Big Decimal

suspendable
optional

Set to true to allow the database to be suspended.

Defaults to true when running in serverless mode otherwise defaults to false.

Boolean

cors
optional

CORS configuration for this database; if present, overrides server's config.

DatabaseConfigCors

logging
optional

Per-database logging configuration.

DatabaseConfigLogging

DatabaseConfigCache

Object

Property Schema

rev_cache
optional

The revision cache config settings.

channel_cache
optional

The channel cache config settings.

DatabaseConfigCacheChannelCache

max_wait_pending
optional

Deprecated, please use the database setting cache.channel_cache.max_wait_pending instead

The maximum time (in milliseconds) for waiting for a pending sequence before skipping it.

Big Decimal

max_wait_skipped
optional

Deprecated, please use the database setting cache.channel_cache.max_wait_skipped instead

The maximum time (in milliseconds) for waiting for pending sequences before skipping.

Big Decimal

enable_star_channel
optional

Deprecated, please use the database setting cache.channel_cache.enable_star_channel instead

Used to control whether Sync Gateway should use the all documents (*) channel.

Boolean

channel_cache_max_length
optional

Deprecated, please use the database setting cache.channel_cache.max_length instead

The maximum number of entries maintained in cache per channel.

Big Decimal

channel_cache_min_length
optional

Deprecated, please use the database setting cache.channel_cache.min_length instead

The minimum number of entries maintained in cache per channel.

Integer

channel_cache_expiry
optional

Deprecated, please use the database setting cache.channel_cache.expiry_seconds instead

The time (seconds) to keep entries in cache beyond the minimum retained.

Integer

max_num_pending
optional

Deprecated, please use the database setting cache.channel_cache.max_num_pending instead

The max number of pending sequences before skipping.

Integer

DatabaseConfigCacheChannelCache

Object

Property Schema

max_number
optional

The maximum number of channel caches which can exist at any one point.

Integer

compact_high_watermark_pct
optional

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 max_number, reaches the high watermark, the eviction process iterates through the cache, removing inactive channels.

Integer

compact_low_watermark_pct
optional

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 max_number returns to a value lower than the percentage of it set here, the cache eviction process is stopped.

Integer

max_wait_pending
optional

The maximum time (in milliseconds) for waiting for a pending sequence before skipping it.

Big Decimal

max_num_pending
optional

The maximum number of pending sequences before skipping sequences.

Integer

max_wait_skipped
optional

The maximum amount of time (in milliseconds) to wait for a skipped sequence before abandoning it.

Big Decimal

enable_star_channel
optional

Used to control whether Sync Gateway should use the all documents (*) channel.

Boolean

max_length
optional

The maximum number of entries to maintain in the cache per channel.

Integer

min_length
optional

The minimum number of entries to maintain in the cache per channel.

Integer

expiry_seconds
optional

The amount of time (in seconds) to keep entries in the cache beyond the minimum retained.

Integer

query_limit
optional

Deprecated in favour of the database setting query_pagination_limit

The limit used for channel queries.

Integer

DatabaseConfigCacheRevCache

Object

Property

Schema

size
optional

The maximum number of revisions that can be stored in the revision cache.

String

shard_count
optional

The number of shards the revision cache should be split into.

String

DatabaseConfigCors

Object

Property

Schema

origin
optional

List of allowed origins, use ['*'] to allow access from everywhere

String array

login_origin
optional

List of allowed login origins

String array

headers
optional

List of allowed headers

String array

DatabaseConfigDeltaSync

Object

Property

Schema

enabled
optional

Whether delta sync is enabled.

This is an enterprise-edition feature only

Boolean

rev_max_age_seconds
optional

The number of seconds deltas for old revisions are available for.

This defaults to 24 hours (in seconds).

Big Decimal

DatabaseConfigEventHandlers

Object

Property

Schema

max_processes
optional

The maximum amount of concurrent event handling independent functions that can be running at the same time.

String

wait_for_process
optional

The maximum amount of time (in milliseconds) to wait when the even queue is full.

String

document_changed
optional

EventConfig

db_state_changed
optional

EventConfig

DatabaseConfigLocalJwtValue

Object

Property Schema

issuer
required

The value to match against the "iss" claim of JWTs.

String

register
optional

If to register a new Sync Gateway user account when a user logs in with a JWT.

Boolean

client_id
required

The value to match against the "aud" claim of JWTs. Set to an empty string to disable audience validation.

String

algorithms
required

The JWT signing algorithms to accept for authentication.

String array

keys
required

The JSON Web Keys to use to validate JWTs.

DatabaseConfigLocalJwtValueKeysInner array

disable_session
optional

Disable Sync Gateway session creation on successful JWT authentication.

Boolean

user_prefix
optional

This is the username prefix for all users created through this provider.

String

username_claim
optional

Allows a different OpenID Connect field to be specified instead of the Subject (sub).

The field name to use can be specified here.

String

roles_claim
optional

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
optional

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

Object

Property Schema

kty
optional

The cryptographic algorithm family used with the key, such as "RSA" or "EC"

Values: "RSA", "EC"

String

use
optional

The intended use of the public key. Only 'sig' is accepted.

Values: "sig"

String

alg
optional

The algorithm intended for use with the key.

String

kid
optional

The Key ID, used to identify the key to use.

String

crv
optional

For Elliptic Curve keys, the name of the curve to use.

Values: "P-256", "P-384", "P-521"

String

x
optional

For Elliptic Curve keys, the X coordinate of the point, as a base64url string.

String

y
optional

For Elliptic Curve keys, the Y coordinate of the point, as a base64url string.

String

n
optional

For RSA keys, the modulus value of the key, as a Base64urlUInt-encoded value.

String

e
optional

For RSA keys, the exponent of the public key, as a Base64urlUInt-encoded value.

String

DatabaseConfigLogging

Object

Property

Schema

console
optional

Console logging configuration.

DatabaseConfigLoggingConsole

Object

Property Schema

log_level
optional

Log Level for the console output

Values: "none", "error", "warn", "info", "debug", "trace"

String

log_keys
optional

Log Keys for the console output

String array

DatabaseConfigOidc

Object

Property

Schema

providers
optional

List of OpenID Connect issuers.

default_provider
optional

The default provider to use when the provider is not specified in the client.

String

DatabaseConfigOidcProvidersValue

Object

Property Schema

issuer
optional

The URL for the OpenID Connect issuer.

String

register
optional

If to register a new Sync Gateway user account when a user logs in with OpenID Connect.

Boolean

client_id
optional

The OpenID Connect provider client ID.

String

validation_key
optional

The OpenID Connect provider client secret.

String

callback_url
optional

The URL that the OpenID Connect will redirect to after authentication.

If not provided, a callback URL will be generated.

String

disable_session
optional

Disable Sync Gateway session creation on successful OpenID Connect authentication.

Boolean

scope
optional

The scope sent for the OpenID Connect request.

String array

include_access
optional

This is whether the _oidc_callback response should include the OpenID Connect access token and associated fields (such as token_type, and expires_in).

Boolean

user_prefix
optional

This is the username prefix for all users created through this provider.

String

discovery_url
optional

The non-standard discovery endpoint.

String

disable_cfg_validation
optional

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.

Boolean

disable_callback_state
optional

Controls whether to maintain state between the auth request and callback endpoints (/_oidc and /_oidc_callback).

This is not recommended as it would cause OpenID Connect authentication to be vulnerable to Cross-Site Request Forgery (CSRF, XSRF).

Boolean

username_claim
optional

Allows a different OpenID Connect field to be specified instead of the Subject (sub).

The field name to use can be specified here.

String

roles_claim
optional

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
optional

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
optional

Allows users accept unsigned tokens from providers.

Boolean

IsDefault
optional

Indicates if this is the default OpenID Connect provider.

Boolean

Name
optional

The name of the OpenID Connect Provider.

String

InsecureSkipVerify
optional

Determines whether the TLS certificate verification should be disabled for this provider.

Boolean

DatabaseConfigReplications

Object

Property

Schema

replication_id
optional

Properties of a replication

DatabaseConfigUnsupportedUserViews

DatabaseConfigUnsupported

Object

Property

Schema

user_views
optional

oidc_test_provider
optional

DatabaseConfigUnsupportedOidcTestProvider

api_endpoints
optional

DatabaseConfigUnsupportedApiEndpoints

warning_thresholds
optional

DatabaseConfigUnsupportedWarningThresholds

oidc_tls_skip_verify
optional

Enable self-signed certificates for OIDC testing.

Boolean

sgr_tls_skip_verify
optional

Enable self-signed certificates for SG-replicate testing.

Boolean

remote_config_tls_skip_verify
optional

Enable self-signed certificates for external JavaScript load.

Boolean

guest_read_only
optional

Restrict GUEST document access to read-only.

Boolean

force_api_forbidden_errors
optional

Force REST API errors to return forbidden

Boolean

dcp_read_buffer
optional

Set the dcp feed to use a different read buffer size.

Big Decimal

kv_buffer
optional

Set the kv pool to use a different buffer size.

Big Decimal

DatabaseConfigUnsupportedApiEndpoints

Object

Property

Schema

enable_couchbase_bucket_flush
optional

Setting for test purposes only

Whether Couchbase buckets can be flushed via Admin REST API.

Boolean

DatabaseConfigUnsupportedOidcTestProvider

Object

Property Schema

enabled
optional

Whether the oidc_test_provider endpoints should be exposed on the public API.

Boolean

DatabaseConfigUnsupportedUserViews

Object

Property

Schema

enabled
optional

Whether pass-through view query is supported through public API.

Boolean

DatabaseConfigUnsupportedWarningThresholds

Object

Property

Schema

xattr_size_bytes
optional

The number of bytes to be used as a threshold for xattr size limit warnings.

Big Decimal

channels_per_doc
optional

The number of channels per document to be used as a threshold for the channel count warnings.

Big Decimal

access_and_role_grants_per_doc
optional

The number of access and role grants per document to be used as a threshold for grant count warnings.

Big Decimal

channels_per_user
optional

The number of channels per user to be used as a threshold for channel count warnings.

Big Decimal

channel_name_size
optional

The number of channel name characters to be used as a threshold for channel name warnings.

Big Decimal

DeleteSgcollectInfo200Response

Object

Property

Schema

status
optional

The new status of sgcollect_info.

String

DesignDoc

Object

Property

Schema

language
optional

String

views
optional

GetDbDesignDdoc200ResponseOptions

options
optional

Document

Object

Property Schema

_id
optional

The ID of the document.

String

_rev
optional

The revision of the document.

String

_exp
optional

Expiry time after which the document will be purged. The expiration time is set and managed on the Couchbase Server document. The value can be specified in two ways; in ISO-8601 format, for example the 6th of July 2022 at 17:00 in the BST timezone would be 2016-07-06T17:00:00+01:00; it can also be specified as a numeric Couchbase Server expiry value. Couchbase Server expiry values are specified as Unix time, and if the desired TTL is below 30 days then it can also represent an interval in seconds from the current time (for example, a value of 5 will remove the document 5 seconds after it is written to Couchbase Server). The document expiration time is returned in the response of GET /{db}/{doc} when show_exp=true is included in the query.

As with the existing explicit purge mechanism, this applies only to the local database; it has nothing to do with replication. This expiration time is not propagated when the document is replicated. The purge of the document does not cause it to be deleted on any other database.

String

_deleted
optional

Whether the document is a tombstone or not. If true, it is a tombstone.

Boolean

_revisions
optional

PostKeyspaceRequestRevisions

_attachments
optional

additional
property

Any Type

Event-config

Object

Property Schema

handler
optional

The handler type.

Values: "webhook"

String

url
optional

The URL of the webhook.

String

filter
optional

The Javascript function to use to filter the webhook events.

String

timeout
optional

The amount of time (in seconds) to attempt connect to the webhook before giving up.

Big Decimal

options
optional

The options for the event.

GetExpvar200ResponseSyncGatewayChangeCache

ExpVars

Object

Property

Schema

cmdline
optional

Built-in variables from the Go runtime, lists the command-line arguments

Object

memstats
optional

Dumps a large amount of information about the memory heap and garbage collector

Object

cb
optional

Variables reported by the Couchbase SDK (go_couchbase package)

Object

mc
optional

Variables reported by the low-level memcached API (gomemcached package)

Object

syncGateway_changeCache
optional

syncGateway_db
optional

GetExpvar200ResponseSyncGatewayDb

syncgateway
optional

Monitoring stats

GetExpvar200ResponseSyncgateway

Get200Response

Object

Property Schema

ADMIN
optional

true if the request is from the Admin API - otherwise omitted.

Boolean

couchdb
required

CouchDB welcome

String

vendor
required

Product vendor

Get200ResponseVendor

version
optional

Product version, including the build number and edition (i.e. EE or CE) Omitted if api.hide_product_version=true

String

persistent_config
optional

Indication for whether sync gateway is running in persistent config mode or legacy config mode. true if the sync gateway node is running in persistent config mode.

Boolean

Get200ResponseVendor

Object

Property Schema

name
required

Product name

String

version
optional

API version. Omitted if api.hide_product_version=true

String

GetAllDbs200Response

Composite Schema

One of the following:

String array
GetAllDbs200ResponseOneOfInner array

GetAllDbs200ResponseOneOfInner

Object

Property Schema

db_name
optional

The name of the database.

String

bucket
optional

The Couchbase Server backing bucket for the database.

String

state
optional

The database state.

Values: "Online", "Offline", "Starting", "Stopping", "Resyncing"

String

require_resync
optional

Indicates whether the database requires resync before it can be brought online.

Boolean

init_in_progress
optional

Indicates whether database initialization is in progress.

Boolean

GetDb200Response

Object

Property Schema

db_name
optional

Database name

String

update_seq
optional

The last sequence number that was committed to the database.

Will return 0 if the database is offline.

Integer

committed_update_seq
optional

The last sequence number that was committed to the database.

Will return 0 if the database is offline.

Integer

instance_start_time
optional

Timestamp of when the database opened, in microseconds since the Unix epoch.

Integer

compact_running
optional

Indicates whether database compaction is currently taking place or not.

Boolean

purge_seq
optional

Unused field.

Big Decimal

disk_format_version
optional

Unused field.

Big Decimal

state
optional

The database state. Change using the /{db}/_offline and /{db}/_online endpoints.

Values: "Online", "Offline"

String

server_uuid
optional

Unique server identifier.

String

init_in_progress
optional

Indicates whether database initialization is in progress.

Boolean

GetDbDesignDdoc200Response

Object

Property

Schema

language
optional

String

views
optional

GetDbDesignDdoc200ResponseOptions

options
optional

Object

Property

Schema

local_seq
optional

String

include_design
optional

String

raw
optional

String

index_xattr_on_deleted_docs
optional

String

GetDbDesignDdoc200ResponseViewsValue

Object

Property

Schema

map
optional

String

reduce
optional

String

GetDbOidcTestingCerts200Response

Object

Property

Schema

keys
required

GetDbOidcTestingCerts200ResponseKeysInner array

GetDbOidcTestingCerts200ResponseKeysInner

Object

Property

Schema

Key
required

Object

KeyID
required

String

Use
required

String

Certificates
optional

Object array

Algorithm
optional

String

GetDbOidcTestingWellKnownOpenidConfiguration200Response

Object

Property

Schema

issuer
optional

String

authorization_endpoint
optional

String

token_endpoint
optional

String

jwks_uri
optional

String

userinfo_endpoint
optional

String

id_token_signing_alg_values_supported
optional

String

response_types_supported
optional

String

subject_types_supported
optional

String

scopes_supported
optional

String

claims_supported
optional

String

token_endpoint_auth_methods_supported
optional

String

GetDbViewView200Response

Object

Property

Schema

total_rows
required

Integer

rows
required

GetDbViewView200ResponseRowsInner array

errors
optional

GetDbViewView200ResponseErrorsInner array

GetDbViewView200ResponseErrorsInner

Object

Property

Schema

From
optional

String

Reason
optional

String

GetDbViewView200ResponseRowsInner

Object

Property

Schema

id
optional

String

key
optional

Object

value
optional

Object

doc
optional

Object

GetExpvar200Response

Object

Property

Schema

cmdline
optional

Built-in variables from the Go runtime, lists the command-line arguments

Object

memstats
optional

Dumps a large amount of information about the memory heap and garbage collector

Object

cb
optional

Variables reported by the Couchbase SDK (go_couchbase package)

Object

mc
optional

Variables reported by the low-level memcached API (gomemcached package)

Object

syncGateway_changeCache
optional

GetExpvar200ResponseSyncGatewayChangeCache

syncGateway_db
optional

GetExpvar200ResponseSyncGatewayDb

syncgateway
optional

Monitoring stats

GetExpvar200ResponseSyncgateway

GetExpvar200ResponseSyncGatewayChangeCache

Object

Property

Schema

maxPending
optional

Max number of sequences waiting on a missing earlier sequence number

Object

lag-tap-0000ms
optional

Histogram of delay from doc save till it shows up in Tap feed

Object

lag-queue-0000ms
optional

Histogram of delay from Tap feed till doc is posted to changes feed

Object

lag-total-0000ms
optional

Histogram of total delay from doc save till posted to changes feed

Object

outOfOrder
optional

Number of out-of-order sequences posted

Object

view_queries
optional

Number of queries to channels view

Object

GetExpvar200ResponseSyncGatewayDb

Object

Property

Schema

channelChangesFeeds
optional

Number of calls to db.changesFeed, i.e. generating a changes feed for a single channel.

Object

channelLogAdds
optional

Number of entries added to channel logs

Object

channelLogAppends
optional

Number of times entries were written to channel logs using an APPEND operation

Object

channelLogCacheHits
optional

Number of requests for channel-logs that were fulfilled from the in-memory cache

Object

channelLogRewrites
optional

Number of times entries were written to channel logs using a SET operation (rewriting the entire log)

Object

channelLogRewriteCollisions
optional

Number of collisions while attempting to rewrite channel logs using SET

Object

document_gets
optional

Number of times a document was read from the database

Object

revisionCache_adds
optional

Number of revisions added to the revision cache

Object

revisionCache_hits
optional

Number of times a revision-cache lookup succeeded

Object

revisionCache_misses
optional

Number of times a revision-cache lookup failed

Object

revs_added
optional

Number of revisions added to the database (including deletions)

Object

sequence_gets
optional

Number of times the database's lastSequence was read

Object

sequence_reserves
optional

Number of times the database's lastSequence was incremented

Object

GetExpvar200ResponseSyncgateway

Object

Property Schema

global
optional

Global Sync Gateway stats

GetExpvar200ResponseSyncgatewayGlobal

per_db
optional

This array contains stats for all databases declared in the config file -- see the Sync Gateway Statistics Schema 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 replication_id

GetExpvar200ResponseSyncgatewayPerDbInner array

per_replication
optional

An array of stats for each replication declared in the config file Deprecated @ 2.8: used only by inter-sync-gateway replications version 1.

GetExpvar200ResponseSyncgatewayPerReplicationInner array

GetExpvar200ResponseSyncgatewayGlobal

Object

Property

Schema

resource_utilization
optional

Resource utilization stats

GetExpvar200ResponseSyncgatewayGlobalResourceUtilization

Object

Property

Schema

admin_net_bytes_recv
optional

The total number of bytes received (since node start-up) on the network interface to which the Sync Gateway api.admin_interface is bound.

Integer

admin_net_bytes_sent
optional

The total number of bytes sent (since node start-up) on the network interface to which the Sync Gateway api.admin_interface is bound.

Integer

error_count
optional

The total number of errors logged.

Integer

go_memstats_heapalloc
optional

HeapAlloc is bytes of allocated heap objects. Allocated heap objects include all reachable objects, as well as unreachable objects that the garbage collector has not yet freed. Specifically, HeapAlloc increases as heap objects are allocated and decreases as the heap is swept and unreachable objects are freed. Sweeping occurs incrementally between GC cycles, so these two processes occur simultaneously, and as a result HeapAlloc tends to change smoothly (in contrast with the sawtooth that is typical of stop-the-world garbage collectors).

Integer

go_memstats_heapidle
optional

HeapIdle is bytes in idle (unused) spans. Idle spans have no objects in them. These spans could be (and may already have been) returned to the OS, or they can be reused for heap allocations, or they can be reused as stack memory. HeapIdle minus HeapReleased estimates the amount of memory that could be returned to the OS, but is being retained by the runtime so it can grow the heap without requesting more memory from the OS. If this difference is significantly larger than the heap size, it indicates there was a recent transient spike in live heap size.

Integer

go_memstats_heapinuse
optional

HeapInuse is bytes in in-use spans. In-use spans have at least one object in them. These spans an only be used for other objects of roughly the same size. HeapInuse minus HeapAlloc estimates the amount of memory that has been dedicated to particular size classes, but is not currently being used. This is an upper bound on fragmentation, but in general this memory can be reused efficiently.

Integer

go_memstats_heapreleased
optional

HeapReleased is bytes of physical memory returned to the OS. This counts heap memory from idle spans that was returned to the OS and has not yet been reacquired for the heap.

Integer

go_memstats_pausetotalns
optional

PauseTotalNs is the cumulative nanoseconds in GC stop-the-world pauses since the program started. During a stop-the-world pause, all goroutines are paused and only the garbage collector can run.

Integer

go_memstats_stackinuse
optional

StackInuse is bytes in stack spans. In-use stack spans have at least one stack in them. These spans can only be used for other stacks of the same size. There is no StackIdle because unused stack spans are returned to the heap (and hence counted toward HeapIdle).

Integer

go_memstats_stacksys
optional

StackSys is bytes of stack memory obtained from the OS. StackSys is StackInuse, plus any memory obtained directly from the OS for OS thread stacks (which should be minimal).

Integer

go_memstats_sys
optional

Sys is the total bytes of memory obtained from the OS. Sys is the sum of the XSys fields below. Sys measures the virtual address space reserved by the Go runtime for the heap, stacks, and other internal data structures. It's likely that not all of the virtual address space is backed by physical memory at any given moment, though in general it all was at some point.

Integer

goroutines_high_watermark
optional

Peak number of go routines since process start.

Integer

num_goroutines
optional

The total number of goroutines.

Integer

num_idle_kv_ops
optional

The total number of idle kv operations.

Integer

process_cpu_percent_utilization
optional

The CPU utilization as percentage value * 10. The extra 10 multiplier is a mistake left for backwards compatibility. Please consider using node_cpu_percent_utilization as of version 3.2. The CPU usage calculation is performed based on user and system CPU time, but it does not include components such as iowait. The derivation means that the values of process_cpu_percent_utilization and %Cpu, returned when running the top command, will differ.

Float (float)

node_cpu_percent_utilization
optional

The node CPU utilization as percentage value, since the last time this stat was called. The CPU usage calculation is performed based on user and system CPU time, but it does not include components such as iowait.

Float (float)

process_memory_resident
optional

The memory utilization (Resident Set Size) for the process, in bytes.

Integer

pub_net_bytes_recv
optional

The total number of bytes received (since node start-up) on the network interface to which the Sync Gateway api.public_interface is bound. By default, that is the number of bytes received on 127.0.0.1:4984 since node start-up

Integer

pub_net_bytes_sent
optional

The total number of bytes sent (since node start-up) on the network interface to which Sync Gateway api.public_interface is bound. By default, that is the number of bytes sent on 127.0.0.1:4984 since node start-up.

Integer

system_memory_total
optional

The total memory available on the system in bytes.

Integer

warn_count
optional

The total number of warnings logged.

Integer

uptime
optional

The total uptime.

Integer

GetExpvar200ResponseSyncgatewayPerDbInner

Object

Property

Schema

cache
optional

Object

database
optional

Object

per_replication
optional

Object

collections
optional

Object

security
optional

Object

GetExpvar200ResponseSyncgatewayPerReplicationInner

Object

Property

Schema

$replication_id
optional

GetExpvar200ResponseSyncgatewayPerReplicationInnerReplicationId

Object

Property

Schema

sgr_active
optional

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
optional

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
optional

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
optional

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
optional

The total number of documents that failed to be pushed since replication started. Used by versions 1 and 2.

Integer

sgr_num_docs_pushed
optional

The total number of documents that were pushed since replication started. Used by versions 1 and 2.

Integer

GetKeyspaceAllDocs200Response

Object

Property Schema

rows
required

Unique items: true

GetKeyspaceAllDocs200ResponseRowsInner array

total_rows
required

Big Decimal

update_seq
required

Big Decimal

GetKeyspaceAllDocs200ResponseRowsInner

Object

Property

Schema

key
optional

String

id
optional

String

value
optional

GetKeyspaceAllDocs200ResponseRowsInnerValue

Object

Property

Schema

rev
optional

String

GetKeyspaceChanges200Response

Object

Property Schema

results
optional

Unique items: true

GetKeyspaceChanges200ResponseResultsInner array

last_seq
optional

The last change sequence number.

String

GetKeyspaceChanges200ResponseResultsInner

Object

Property Schema

seq
optional

The change sequence number.

Big Decimal

id
optional

The document ID the change happened on.

String

changes
optional

List of document leafs with each leaf containing only a rev field.

Unique items: true

GetKeyspaceChanges200ResponseResultsInnerChangesInner array

GetKeyspaceChanges200ResponseResultsInnerChangesInner

Object

Property

Schema

rev
optional

The new revision that was caused by that change.

String

GetKeyspaceDocid200Response

Object

Property

Schema

_id
optional

The ID of the document.

String

_rev
optional

The revision ID of the document.

String

additional
property

Any Type

GetKeyspaceRawDocid200Response

Object

Property

Schema

_sync
optional

GetKeyspaceRawDocid200ResponseSync

Object

Property

Schema

rev
optional

The current document revision ID.

String

sequence
optional

The most recent sequence number of the document.

Big Decimal

recent_sequences
optional

The previous sequence numbers of the document.

Big Decimal array

history
optional

GetKeyspaceRawDocid200ResponseSyncHistory

cas
optional

The document CAS (Concurrent Document Mutations) number used for document locking.

String

value_crc32c
optional

The documents CRC32 number.

String

channel_set
optional

The channels the document has been in.

GetKeyspaceRawDocid200ResponseSyncChannelSetInner array

channel_set_history
optional

GetKeyspaceRawDocid200ResponseSyncChannelSetHistoryInner array

time_saved
optional

The time and date the document was most recently changed.

String

GetKeyspaceRawDocid200ResponseSyncChannelSetHistoryInner

Object

Property

Schema

name
optional

String

start
optional

String

end
optional

String

GetKeyspaceRawDocid200ResponseSyncChannelSetInner

Object

Property

Schema

name
optional

The name of the channel.

String

start
optional

The sequence number that document was added to the channel.

String

end
optional

The sequence number the document was removed from the channel. Omitted if not removed.

String

GetKeyspaceRawDocid200ResponseSyncHistory

Object

Property

Schema

revs
optional

The past revision IDs.

String array

parents
optional

Big Decimal array

channels
optional

The past channel history. Can contain string arrays, strings, or be null depending on if and how the channels where set.

List array

GetSgcollectInfo200Response

Object

Property Schema

status
required

The status of sgcollect_info.

Values: "stopped", "running"

String

GetStats200Response

Object

Property

Schema

memstats
optional

A set of Go runtime memory statistics.

StartupConfigLoggingError

HTTP-Error

Object

Property

Schema

error
required

The error name.

String

reason
required

The error description.

String

Log-rotation-config

Object

Property Schema

max_size
optional

The maximum size in MB of the log file before it gets rotated.

Integer

localtime
optional

If true, it uses the computer's local time to format the backup timestamp.

Boolean

rotated_logs_size_limit
optional

Max Size (in mb) of log files before deletion

Integer

rotation_interval
optional

If set, the interval at which log files are rotated, even if max_size is not reached.

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

String

max_age
optional

The maximum number of days to retain old log files. By default, there is no rotation, max_age=0.

Integer

LoggingConfig

Object

Property Schema

log_file_path
optional

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
optional

Redaction level to apply to log output.

Values: "none", "partial", "full", "unset"

String

console
optional

ConsoleLoggingConfig

error
optional

Error logging configuration.

warn
optional

Warning logging configuration.

StartupConfigLoggingWarn

info
optional

Info logging configuration.

StartupConfigLoggingInfo

debug
optional

Debug logging configuration.

StartupConfigLoggingDebug

trace
optional

Trace logging configuration.

StartupConfigLoggingTrace

stats
optional

Trace logging configuration.

StartupConfigLoggingStats

New-revision

Object

Property

Schema

id
required

The ID of the document.

String

ok
required

Whether the request completed successfully.

Boolean

rev
required

The revision of the document.

String

NodeInfo

Object

Property Schema

ADMIN
optional

true if the request is from the Admin API - otherwise omitted.

Boolean

couchdb
required

CouchDB welcome

String

vendor
required

Product vendor

Get200ResponseVendor

version
optional

Product version, including the build number and edition (i.e. EE or CE) Omitted if api.hide_product_version=true

String

persistent_config
optional

Indication for whether sync gateway is running in persistent config mode or legacy config mode. true if the sync gateway node is running in persistent config mode.

Boolean

OpenID Connect callback properties

Object

Property

Schema

id_token
optional

The OpenID Connect ID token

String

refresh_token
optional

The OpenID Connect ID refresh token

String

session_id
optional

The Sync Gateway session token

String

name
optional

The Sync Gateway user

String

access_token
optional

The OpenID Connect access token

String

token_type
optional

The OpenID Connect ID token type

String

expires_in
optional

The time until the id_token expires (TTL).

Big Decimal

Object

Property

Schema

username
required

String

tokenttl
required

String

identity-token-formats
required

String

authenticated
required

String

OIDC-token

Object

Property

Schema

access_token
optional

String

token_type
optional

String

refresh_token
optional

String

expires_in
optional

String

id_token
optional

String

OpenID Connect callback properties

Object

Property

Schema

id_token
optional

The OpenID Connect ID token

String

refresh_token
optional

The OpenID Connect ID refresh token

String

session_id
optional

The Sync Gateway session token

String

name
optional

The Sync Gateway user

String

access_token
optional

The OpenID Connect access token

String

token_type
optional

The OpenID Connect ID token type

String

expires_in
optional

The time until the id_token expires (TTL).

Big Decimal

PostDbEnsureFullCommit201Response

Object

Property

Schema

instance_start_time
optional

Timestamp of when the database opened, in microseconds since the Unix epoch.

Integer

ok
optional

Boolean

PostDbFacebook401Response

Object

Property

Schema

error
optional

String

reason
optional

String

PostDbFacebookRequest

Object

Property

Schema

access_token
required

Facebook access token to base the new session on.

String

PostDbGoogleRequest

Object

Property

Schema

id_token
required

Google ID token to base the new session on.

String

PostDbOidcTestingAuthenticateRequest

Object

Property

Schema

username
required

String

tokenttl
required

String

identity-token-formats
required

String

authenticated
required

String

PostDbOidcTestingTokenRequest

Object

Property Schema

grant_type
required

The grant type of the token to request. Can either be an authorization_code or refresh_token.

String

code
optional

grant_type=authorization_code only: The OpenID Connect authentication token.

String

refresh_token
optional

grant_type=refresh_token only: The OpenID Connect refresh token.

String

PostDbOnlineRequest

Object

Property

Schema

delay
optional

The amount of seconds to delay bringing the database online.

Integer

PostDbResyncRequest

Object

Property Schema

scopes
optional

This controls for which collections resync will run

regenerate_sequences
optional

This can be used as an alternative to query param regenerate_sequences. If either query param or this is set to true, then the request will regenerate the sequence numbers for each document processed.

Boolean

PostDbSession200Response

Object

Property

Schema

session_id
optional

The ID of the session. This is the value that would be put in to the cookie to keep the user authenticated.

String

expires
optional

The date and time the cookie expires.

String

cookie_name
optional

The name of the cookie that would be used to store the users session.

String

PostDbSessionRequest

Object

Property

Schema

name
optional

User name to generate the session for.

String

ttl
optional

Time until the session expires. Uses default value of 24 hours if left blank.

Integer

PostKeyspaceAllDocsRequest

Object

Property

Schema

keys
required

List of the documents to retrieve.

String array

PostKeyspaceBulkDocs201ResponseInner

Object

Property

Schema

id
required

The ID of the document that the operation was performed on.

String

rev
optional

The new revision of the document if the operation was a success.

String

error
optional

The error type if the operation of the document failed.

String

reason
optional

The reason the operation failed.

String

status
optional

The HTTP status code for why the operation failed.

Integer

PostKeyspaceBulkDocsRequest

Object

Property Schema

new_edits
optional

This controls whether to assign new revision identifiers to new edits (true) or use the existing ones (false).

Boolean

docs
required

PostKeyspaceRequest array

PostKeyspaceBulkGetRequest

Object

Property

Schema

docs
required

PostKeyspaceBulkGetRequestDocsInner array

PostKeyspaceBulkGetRequestDocsInner

Object

Property

Schema

id
required

ID of the document to retrieve.

String

PostKeyspaceChangesRequest

Object

Property Schema

limit
optional

Maximum number of changes to return.

String

style
optional

Controls whether to return the current winning revision (main_only) or all the leaf revision including conflicts and deleted former conflicts (all_docs).

String

active_only
optional

Set true to exclude deleted documents and notifications for documents the user no longer has access to from the changes feed.

String

include_docs
optional

Include the body associated with each document.

String

revocations
optional

If true, revocation messages will be sent on the changes feed.

String

filter
optional

Set a filter to either filter by channels or document IDs.

String

channels
optional

A comma-separated list of channel names to filter the response to only the channels specified. To use this option, the filter query option must be set to sync_gateway/bychannels.

String

doc_ids
optional

String

heartbeat
optional

String

timeout
optional

String

feed
optional

The type of changes feed to use.

String

request_plus
optional

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

PostKeyspacePurge200Response

Object

Property Schema

purged
required

Values: *

PostKeyspaceRequestRevisions

PostKeyspacePurgeRequest

Object

Property Schema

doc_id
optional

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 array

additional
property

Values: *

String array

PostKeyspaceRequest

Object

Property Schema

_id
optional

The ID of the document.

String

_rev
optional

The revision of the document.

String

_exp
optional

String

_deleted
optional

Whether the document is a tombstone or not. If true, it is a tombstone.

Boolean

_revisions
optional

_attachments
optional

PostKeyspaceRevsDiff200ResponseDocid

additional
property

Any Type

PostKeyspaceRequestAttachmentsValue

Object

Property

Schema

content_type
optional

Content type of the attachment.

String

data
optional

The data in the attachment in base64.

String

PostKeyspaceRequestRevisions

Object

Property

Schema

start
optional

Prefix number for the latest revision.

Big Decimal

ids
optional

Array of valid revision IDs, in reverse order (latest first).

String array

PostKeyspaceRevsDiff200Response

Object

Property

Schema

docid
optional

The document ID.

Object

Property Schema

missing
optional

The revisions that are not in the database (and therefore missing).

String array

possible_ancestors
optional

An array of known revisions that might be the recent ancestors.

String array

PostKeyspaceRevsDiffRequest

Object

Property

Schema

docid
optional

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

String array

PostPostUpgrade200Response

Object

Property Schema

post_upgrade_results
required

A map of databases.

preview
optional

If set, nothing in the database was changed as this was a dry-run. This can be controlled by the preview query parameter in the request.

Boolean

PostPostUpgrade200ResponsePostUpgradeResultsValue

Object

Property

Schema

removed_design_docs
required

The design documents that have or will be removed.

String array

removed_indexes
required

The indexes that have or will be removed.

String array

PostProfileProfilenameRequest

Object

Property

Schema

file
optional

This is the file to output the pprof profile at.

String

PostSgcollectInfo200Response

Object

Property

Schema

status
optional

The new sgcollect_info status.

String

PostSgcollectInfoRequest

Object

Property Schema

redact_level
optional

The redaction level to use for redacting the collected logs.

Values: "partial", "none"

String

redact_salt
optional

The salt to use for the log redactions.

String

output_dir
optional

The directory to output the collected logs zip file at.

This overrides the configured default output directory configured in the startup config logging.log_file_path.

String

upload
optional

If set, upload the logs to Couchbase Support.

A customer name must be set if this is set.

Boolean

upload_host
optional

The host to send the logs too.

String

upload_proxy
optional

The proxy to use while uploading the logs.

String

customer
optional

The customer name to use when uploading the logs.

String

ticket
optional

The Zendesk ticket number to use when uploading logs.

Minimum length: 1
Maximum length: 7

String

PutKeyspaceLocalDocidRequest

Object

Property

Schema

_rev
optional

Revision to replace. Required if updating existing local document.

String

User configurable replication properties

Object

Property Schema

replication_id
optional

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
optional

This is the endpoint of the database for the remote Sync Gateway that is the subject of this replication's push, pull, or pushAndPull action.

Typically this would include the URI, port, and database name. For example, http://localhost:4985/db.

How this remote is used depends on the direction of the replication:

pull - this replicator pulls changes from the remote
push - this replicator pushes changes to this remote
pushAndPull - this replicator pushes changes to this remote, while also pulling receiving changes

String

username
optional

This has been deprecated in favour of remote_username.

This is the username to use to authenticate with the remote.

This can only be used for a pull replication.

String

password
optional

This has been deprecated in favour of remote_password.

This is the password to use to authenticate with the remote.

This password will be redacted in the replication config.

This can only be used for a pull replication.

String

remote_username
optional

The username to use to authenticate with the remote.

This can only be used for a pull replication.

String

remote_password
optional

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
required

This specifies which direction the replication will be replicating with the remote replicator.

The directions are:

pull - changes are pulled from the remote database
push - changes are pushed to the remote database
pushAndPull - changes are both push-to and pulled-from the remote database

Replications created prior to Sync Gateway 2.8 derive their direction from the source/target URL of the replication.

Values: "push", "pull", "pushAndPull"

String

conflict_resolution_type
optional

This defines what conflict resolution policy Sync Gateway should use to apply when resolving conflicting revisions.

Changing this is an enterprise-edition only feature.

Behaviour

default - In priority order, this will cause
- Deletes to always win (the delete with the longest revision history wins if both revisions are deletes)
- The revision with the longest revision history to win. This means the the revision with the most changes and therefore the highest revision ID will win.
localWins - This will result in local revisions always being the winner in any conflict.
remoteWins - This will result in remote revisions always being the winner in any conflict.
custom - This will result in conflicts going through your own custom conflict resolver. You must provide this logic as a Javascript function in the custom_conflict_resolver parameter. This is an enterprise-edition only feature.

Note: replications created prior to Sync Gateway 2.8 will default to default.

Values: "default", "remoteWins", "localWins", "custom"

String

custom_conflict_resolver
optional

This specifies the Javascript function to use to resolve conflicts between conflicting revisions.

This must be used when conflict_resolution_type=custom. This property will be ignored when conflict_resolution_type is not custom.

The Javascript function to provide this property should be in backticks (like the sync function). The function takes 1 parameter which is a struct that represents the conflict. This struct has 2 properties:

LocalDocument - The local document. This contains the document ID under the _id key.
RemoteDocument - The remote document The function should return the new documents body. This can be the winning revision (for example, return conflict.LocalDocument), a new body, or nil to resolve as a delete.

Example:

"custom_conflict_resolver":\`
	function(conflict) {
		console.log("Doc ID: "+conflict.LocalDocument._id);
		console.log("Full remote doc: "+JSON.stringify(conflict.RemoteDocument));
		return conflict.RemoteDocument;
	}
\`

Using complex custom_conflict_resolver functions can noticeably degrade performance. Use a built-in resolver whenever possible.

This is an enterprise-edition only feature.

String

purge_on_removal
optional

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.

Boolean

enable_delta_sync
optional

This will turn on delta- sync for the replication. This works in conjunction with the database level setting delta_sync.enabled

If set to true, delta-sync will be used as long as both databases involved in the replication have delta-sync enabled. If a database does not have delta-sync enabled, then the replication will run without delta-sync.

Replications created prior to Sync Gateway 2.8 must have delta-sync disabled.

Enabling this is an enterprise-edition only feature.

Boolean

max_backoff_time
optional

Specifies the maximum time-period (in minutes) that Sync Gateway will attempt to reconnect to a lost or unreachable remote.

When a disconnection happens, Sync Gateway will do an exponential backoff up to this specified value. When this value is met, it will attempt to reconnect indefinitely every max_backoff_time minutes.

If this is set to 0, Sync Gateway will do the normal exponential backoff after the disconnect happens but then attempting 10 minutes and stop the replication.

Note: this defaults to 5 minutes for replications created prior to Sync Gateway 2.8.

Integer

initial_state
optional

This is what state to start the replication in when creating a new replication.

This allows you to control if the replication starts in a stopped start or running state.

Replications prior to Sync Gateway 2.8 will run in the default state running.

Values: "running", "stopped"

String

continuous
optional

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.

Boolean

filter
optional

This defines whether to filter documents by their channels or not.

If set to sync_gateway/bychannel then a pull replication will be limited to a specific set of channels specified by the query_params.channels property.

This only can be used with pull replications.

Values: "sync_gateway/bychannel"

String

query_params
optional

This is a set of key/value pairs used in the query string of the replication.

If filters=sync_gateway/bychannel then this can be used to set the channels to filter by in a pull replication. To do this, set the channels key to a string array of the channels to filter by. For example:

"filter":"sync_gateway/bychannel",
"query_params": {
  "channels":["chanUser1"]
},

String array

adhoc
optional

Set to true to run the replication as an adhoc replication instead of a persistent one.

This means that the replication will only last the period of the replication until the status is changed to stopped and then it will be removed automatically. It will also be removed if Sync Gateway restarts or if removed due to user action.

Boolean

batch_size
optional

The amount of changes to be sent in one batch of replications. Changing this is an enterprise-edition only feature.

Integer

run_as
optional

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
optional

If true, the replicator will run with collections, and will replicate all collections, unless otherwise limited by keyspace_map.

If false, the replicator will only replicate the default collection.

Boolean

collections_local
optional

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.

String array

collections_remote
optional

Remaps the local collection name to the one specified in this array when replicating with the remote.

If only a subset of collections need remapping, elements in this array can be specified as null to preserve the local collection name.

The same index is used for both collections_remote and collections_local, and both arrays must be the same length.

String array

Replication

Object

Property Schema

replication_id
optional

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
optional

This is the endpoint of the database for the remote Sync Gateway that is the subject of this replication's push, pull, or pushAndPull action.

Typically this would include the URI, port, and database name. For example, http://localhost:4985/db.

How this remote is used depends on the direction of the replication:

pull - this replicator pulls changes from the remote
push - this replicator pushes changes to this remote
pushAndPull - this replicator pushes changes to this remote, while also pulling receiving changes

String

username
optional

This has been deprecated in favour of remote_username.

This is the username to use to authenticate with the remote.

This can only be used for a pull replication.

String

password
optional

This has been deprecated in favour of remote_password.

This is the password to use to authenticate with the remote.

This password will be redacted in the replication config.

This can only be used for a pull replication.

String

remote_username
optional

The username to use to authenticate with the remote.

This can only be used for a pull replication.

String

remote_password
optional

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
optional

This specifies which direction the replication will be replicating with the remote replicator.

The directions are:

pull - changes are pulled from the remote database
push - changes are pushed to the remote database
pushAndPull - changes are both push-to and pulled-from the remote database

Replications created prior to Sync Gateway 2.8 derive their direction from the source/target URL of the replication.

Values: "push", "pull", "pushAndPull"

String

conflict_resolution_type
optional

This defines what conflict resolution policy Sync Gateway should use to apply when resolving conflicting revisions.

Changing this is an enterprise-edition only feature.

Behaviour

default - In priority order, this will cause
- Deletes to always win (the delete with the longest revision history wins if both revisions are deletes)
- The revision with the longest revision history to win. This means the the revision with the most changes and therefore the highest revision ID will win.
localWins - This will result in local revisions always being the winner in any conflict.
remoteWins - This will result in remote revisions always being the winner in any conflict.
custom - This will result in conflicts going through your own custom conflict resolver. You must provide this logic as a Javascript function in the custom_conflict_resolver parameter. This is an enterprise-edition only feature.

Note: replications created prior to Sync Gateway 2.8 will default to default.

Values: "default", "remoteWins", "localWins", "custom"

String

custom_conflict_resolver
optional

This specifies the Javascript function to use to resolve conflicts between conflicting revisions.

This must be used when conflict_resolution_type=custom. This property will be ignored when conflict_resolution_type is not custom.

LocalDocument - The local document. This contains the document ID under the _id key.
RemoteDocument - The remote document The function should return the new documents body. This can be the winning revision (for example, return conflict.LocalDocument), a new body, or nil to resolve as a delete.

Example:

"custom_conflict_resolver":\`
	function(conflict) {
		console.log("Doc ID: "+conflict.LocalDocument._id);
		console.log("Full remote doc: "+JSON.stringify(conflict.RemoteDocument));
		return conflict.RemoteDocument;
	}
\`

Using complex custom_conflict_resolver functions can noticeably degrade performance. Use a built-in resolver whenever possible.

This is an enterprise-edition only feature.

String

purge_on_removal
optional

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.

Boolean

enable_delta_sync
optional

This will turn on delta- sync for the replication. This works in conjunction with the database level setting delta_sync.enabled

Replications created prior to Sync Gateway 2.8 must have delta-sync disabled.

Enabling this is an enterprise-edition only feature.

Boolean

max_backoff_time
optional

Specifies the maximum time-period (in minutes) that Sync Gateway will attempt to reconnect to a lost or unreachable remote.

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.

Integer

initial_state
optional

This is what state to start the replication in when creating a new replication.

This allows you to control if the replication starts in a stopped start or running state.

Replications prior to Sync Gateway 2.8 will run in the default state running.

Values: "running", "stopped"

String

continuous
optional

If true, changes will be immediately synced when they happen. This is known as a continuous replication.

Boolean

filter
optional

This defines whether to filter documents by their channels or not.

If set to sync_gateway/bychannel then a pull replication will be limited to a specific set of channels specified by the query_params.channels property.

This only can be used with pull replications.

Values: "sync_gateway/bychannel"

String

query_params
optional

This is a set of key/value pairs used in the query string of the replication.

"filter":"sync_gateway/bychannel",
"query_params": {
  "channels":["chanUser1"]
},

String array

adhoc
optional

Set to true to run the replication as an adhoc replication instead of a persistent one.

Boolean

batch_size
optional

The amount of changes to be sent in one batch of replications. Changing this is an enterprise-edition only feature.

Integer

run_as
optional

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
optional

If true, the replicator will run with collections, and will replicate all collections, unless otherwise limited by keyspace_map.

If false, the replicator will only replicate the default collection.

Boolean

collections_local
optional

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.

String array

collections_remote
optional

Remaps the local collection name to the one specified in this array when replicating with the remote.

If only a subset of collections need remapping, elements in this array can be specified as null to preserve the local collection name.

The same index is used for both collections_remote and collections_local, and both arrays must be the same length.

String array

assigned_node
optional

The unique ID of the node assigned to the replication.

String

target_state
optional

This is the state that the replicator is in or that trying to transition in to.

Values: "running", "stopped", "resetting", "error", "starting", "reconnecting"

String

Replication-status

Object

Property Schema

replication_id
required

The ID of the replication.

String

config
optional

Properties of a replication

status
optional

The status of the replication.

Values: "stopped", "running", "reconnecting", "resetting", "error", "starting"

String

error_message
optional

The error message of the replication if an error has occurred.

String

docs_read
optional

The number of documents that have been read (fetched) from the source database.

Integer

docs_checked_pull
optional

Integer

docs_purged
optional

The number of documents that have been purged.

Integer

rejected_by_local
optional

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
optional

The last changes sequence number that was pulled from the remote.

String

deltas_recv
optional

The number of deltas that have been received from the remote.

Integer

deltas_requested
optional

Integer

docs_written
optional

The number of documents that have been wrote (pushed) to the target database.

Integer

docs_checked_push
optional

Integer

docs_write_failures
optional

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
optional

The number of documents that had a conflict.

Integer

rejected_by_remote
optional

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
optional

The last changes sequence number that was pushed to the remote.

String

deltas_sent
optional

The number of deltas that have been sent to the remote.

Integer

Resync-status

Object

Property Schema

status
required

The status of the current operation.

Values: "running", "completed", "stopping", "stopped", "error"

String

start_time
required

The ISO-8601 date and time the resync operation was started.

String

last_error
required

The last error that occurred in the resync operation (if any).

String

docs_changed
required

The amount of documents that have been changed as a result of the resync operation.

Integer

docs_processed
required

The amount of docs that have been processed so far in the resync operation.

Integer

collections_processing
optional

The collections that the resync operation is running on.

Replication

Object

Property Schema

replication_id
optional

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
optional

This is the endpoint of the database for the remote Sync Gateway that is the subject of this replication's push, pull, or pushAndPull action.

Typically this would include the URI, port, and database name. For example, http://localhost:4985/db.

How this remote is used depends on the direction of the replication:

pull - this replicator pulls changes from the remote
push - this replicator pushes changes to this remote
pushAndPull - this replicator pushes changes to this remote, while also pulling receiving changes

String

username
optional

This has been deprecated in favour of remote_username.

This is the username to use to authenticate with the remote.

This can only be used for a pull replication.

String

password
optional

This has been deprecated in favour of remote_password.

This is the password to use to authenticate with the remote.

This password will be redacted in the replication config.

This can only be used for a pull replication.

String

remote_username
optional

The username to use to authenticate with the remote.

This can only be used for a pull replication.

String

remote_password
optional

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
optional

This specifies which direction the replication will be replicating with the remote replicator.

The directions are:

pull - changes are pulled from the remote database
push - changes are pushed to the remote database
pushAndPull - changes are both push-to and pulled-from the remote database

Replications created prior to Sync Gateway 2.8 derive their direction from the source/target URL of the replication.

Values: "push", "pull", "pushAndPull"

String

conflict_resolution_type
optional

This defines what conflict resolution policy Sync Gateway should use to apply when resolving conflicting revisions.

Changing this is an enterprise-edition only feature.

Behaviour

default - In priority order, this will cause
- Deletes to always win (the delete with the longest revision history wins if both revisions are deletes)
- The revision with the longest revision history to win. This means the the revision with the most changes and therefore the highest revision ID will win.
localWins - This will result in local revisions always being the winner in any conflict.
remoteWins - This will result in remote revisions always being the winner in any conflict.
custom - This will result in conflicts going through your own custom conflict resolver. You must provide this logic as a Javascript function in the custom_conflict_resolver parameter. This is an enterprise-edition only feature.

Note: replications created prior to Sync Gateway 2.8 will default to default.

Values: "default", "remoteWins", "localWins", "custom"

String

custom_conflict_resolver
optional

This specifies the Javascript function to use to resolve conflicts between conflicting revisions.

This must be used when conflict_resolution_type=custom. This property will be ignored when conflict_resolution_type is not custom.

LocalDocument - The local document. This contains the document ID under the _id key.
RemoteDocument - The remote document The function should return the new documents body. This can be the winning revision (for example, return conflict.LocalDocument), a new body, or nil to resolve as a delete.

Example:

"custom_conflict_resolver":\`
	function(conflict) {
		console.log("Doc ID: "+conflict.LocalDocument._id);
		console.log("Full remote doc: "+JSON.stringify(conflict.RemoteDocument));
		return conflict.RemoteDocument;
	}
\`

Using complex custom_conflict_resolver functions can noticeably degrade performance. Use a built-in resolver whenever possible.

This is an enterprise-edition only feature.

String

purge_on_removal
optional

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.

Boolean

enable_delta_sync
optional

This will turn on delta- sync for the replication. This works in conjunction with the database level setting delta_sync.enabled

Replications created prior to Sync Gateway 2.8 must have delta-sync disabled.

Enabling this is an enterprise-edition only feature.

Boolean

max_backoff_time
optional

Specifies the maximum time-period (in minutes) that Sync Gateway will attempt to reconnect to a lost or unreachable remote.

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.

Integer

initial_state
optional

This is what state to start the replication in when creating a new replication.

This allows you to control if the replication starts in a stopped start or running state.

Replications prior to Sync Gateway 2.8 will run in the default state running.

Values: "running", "stopped"

String

continuous
optional

If true, changes will be immediately synced when they happen. This is known as a continuous replication.

Boolean

filter
optional

This defines whether to filter documents by their channels or not.

If set to sync_gateway/bychannel then a pull replication will be limited to a specific set of channels specified by the query_params.channels property.

This only can be used with pull replications.

Values: "sync_gateway/bychannel"

String

query_params
optional

This is a set of key/value pairs used in the query string of the replication.

"filter":"sync_gateway/bychannel",
"query_params": {
  "channels":["chanUser1"]
},

String array

adhoc
optional

Set to true to run the replication as an adhoc replication instead of a persistent one.

Boolean

batch_size
optional

The amount of changes to be sent in one batch of replications. Changing this is an enterprise-edition only feature.

Integer

run_as
optional

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
optional

If true, the replicator will run with collections, and will replicate all collections, unless otherwise limited by keyspace_map.

If false, the replicator will only replicate the default collection.

Boolean

collections_local
optional

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.

String array

collections_remote
optional

Remaps the local collection name to the one specified in this array when replicating with the remote.

If only a subset of collections need remapping, elements in this array can be specified as null to preserve the local collection name.

The same index is used for both collections_remote and collections_local, and both arrays must be the same length.

String array

assigned_node
optional

The unique ID of the node assigned to the replication.

String

target_state
optional

This is the state that the replicator is in or that trying to transition in to.

Values: "running", "stopped", "resetting", "error", "starting", "reconnecting"

String

Role

Object

Property Schema

name
optional

The name of the role.

Role names can only have alphanumeric ASCII characters and underscores.

String

admin_channels
optional

The channels that users in the role are able to access for the default collection.

String array

all_channels
optional

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

String array

collection_access
optional

A set of access grants by scope and collection.

Role

Object

Property Schema

name
optional

The name of the role.

Role names can only have alphanumeric ASCII characters and underscores.

String

admin_channels
optional

The channels that users in the role are able to access for the default collection.

String array

all_channels
optional

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

String array

collection_access
optional

A set of access grants by scope and collection.

Role

Object

Property Schema

name
optional

The name of the role.

Role names can only have alphanumeric ASCII characters and underscores.

String

admin_channels
optional

The channels that users in the role are able to access for the default collection.

String array

all_channels
optional

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

String array

collection_access
optional

A set of access grants by scope and collection.

StartupConfigLoggingError

Runtime-config

Object

Property

Schema

logging
optional

RuntimeConfigLogging

max_concurrent_replications
optional

Maximum number of concurrent replication connections allowed. If set to 0 this limit will be ignored.

Integer

RuntimeConfigLogging

Object

Property Schema

log_file_path
optional

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
optional

Redaction level to apply to log output.

Values: "none", "partial", "full", "unset"

String

console
optional

ConsoleLoggingConfig

error
optional

Error logging configuration.

warn
optional

Warning logging configuration.

StartupConfigLoggingWarn

info
optional

Info logging configuration.

StartupConfigLoggingInfo

debug
optional

Debug logging configuration.

StartupConfigLoggingDebug

trace
optional

Trace logging configuration.

StartupConfigLoggingTrace

stats
optional

Trace logging configuration.

StartupConfigLoggingStats

Scopes

Object

Property

Schema

collections
optional

An object keyed by collection name containing config for the specific collection.

Scopes

Object

Property

Schema

collections
optional

An object keyed by collection name containing config for the specific collection.

Serverless

Object

Property Schema

enabled
optional

Run SG in to serverless mode

Boolean

min_config_fetch_interval
optional

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

String

Startup-config

Object

Property Schema

bootstrap
optional

Configuration settings for interacting with Couchbase Server.

StartupConfigBootstrap

api
optional

Configuration settings for modifying how the REST API is interacted with.

StartupConfigApi

logging
optional

The configuration settings for modifying Sync Gateway logging.

StartupConfigLogging

auth
optional

StartupConfigAuth

replicator
optional

StartupConfigReplicator

unsupported
optional

Settings that are not officially supported. It is highly recommended these are not used.

StartupConfigUnsupported

database_credentials
optional

A map of database name to credentials, that can be used instead of the bootstrap ones.

bucket_credentials
optional

A map of bucket names to credentials, that can be used instead of the bootstrap ones.

StartupConfigLoggingError

max_file_descriptors
optional

Max of open file descriptors (RLIMIT_NOFILE)

Minimum: 0

Big Decimal

couchbase_keepalive_interval
optional

TCP keep-alive interval between SG and Couchbase server. This is unused.

Integer

heap_profile_collection_threshold
optional

Threshold in bytes for automatic collection of heap profiles. If not specified, defaults to 85% of the lesser of cgroup or system memory.

Integer

heap_profile_disable_collection
optional

Disables automatic heap profile collection.

Boolean

StartupConfigApi

Object

Property Schema

public_interface
optional

Network interface to bind public API to

String

admin_interface
optional

Network interface to bind admin API to.

By default, this will only be accessible to the localhost.

String

metrics_interface
optional

Network interface to bind metrics API to.

By default, this will only be accessible to the localhost.

String

profile_interface
optional

Network interface to bind profiling API to

String

admin_interface_authentication
optional

Whether the admin API requires authentication

Boolean

metrics_interface_authentication
optional

Whether the metrics API requires authentication

Boolean

enable_advanced_auth_dp
optional

Whether to enable the DP permissions check feature of admin auth.

Defaults to true if using enterprise-edition or false if using community-edition.

Boolean

server_read_timeout
optional

Maximum duration 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 5h20m30s.

String

server_write_timeout
optional

Maximum duration 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 5h20m30s.

String

read_header_timeout
optional

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

String

idle_timeout
optional

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

String

pretty
optional

Pretty-print JSON responses. This property is deprecated.

Boolean

max_connections
optional

Max of incoming HTTP connections to accept

Big Decimal

compress_responses
optional

If false, disables compression of HTTP responses

Boolean

hide_product_version
optional

Whether product versions removed from Server headers and REST API responses

Boolean

https
optional

StartupConfigApiHttps

cors
optional

StartupConfigApiCors

Object

Property

Schema

origin
optional

List of allowed origins, use ['*'] to allow access from everywhere

String array

login_origin
optional

List of allowed login origins

String array

headers
optional

List of allowed headers

String array

max_age
optional

Maximum age of the CORS Options request

Integer

StartupConfigApiHttps

Object

Property

Schema

tls_minimum_version
optional

The minimum allowable TLS version for the REST APIs

String

tls_cert_path
optional

The TLS cert file to use for the REST APIs

String

tls_key_path
optional

The TLS key file to use for the REST APIs

String

StartupConfigAuth

Object

Property Schema

bcrypt_cost
optional

Cost to use for bcrypt password hashes

Minimum: 10
Maximum: 31

Integer

StartupConfigBootstrap

Object

Property Schema

group_id
optional

The config group ID to use when discovering databases. Allows for non-homogenous configuration.

String

config_update_frequency
optional

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

String

server
required

Couchbase Server connection string/URL.

String

username
required

Username for authenticating to server.

String

password
required

Password for authenticating to server

String

ca_cert_path
optional

Root CA cert path for TLS connection

String

server_tls_skip_verify
optional

Allow empty server CA Cert Path without attempting to use system root pool

Boolean

x509_cert_path
optional

Cert path (public key) for X.509 bucket auth

String

x509_key_path
optional

Key path (private key) for X.509 bucket auth

String

use_tls_server
optional

Enforces a secure or non-secure server scheme

Boolean

StartupConfigLogging

Object

Property Schema

log_file_path
optional

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
optional

Redaction level to apply to log output.

Values: "none", "partial", "full", "unset"

String

console
optional

ConsoleLoggingConfig

error
optional

Error logging configuration.

warn
optional

Warning logging configuration.

StartupConfigLoggingWarn

info
optional

Info logging configuration.

StartupConfigLoggingInfo

debug
optional

Debug logging configuration.

StartupConfigLoggingDebug

trace
optional

Trace logging configuration.

StartupConfigLoggingTrace

stats
optional

Trace logging configuration.

StartupConfigLoggingStats

StartupConfigLoggingDebug

Object

Property

Schema

enabled
optional

Toggle for this log output

Boolean

rotation
optional

StartupConfigLoggingDebugRotation

collation_buffer_size
optional

The size of the log collation buffer

Integer

StartupConfigLoggingDebugRotation

Object

Property Schema

max_size
optional

The maximum size in MB of the log file before it gets rotated.

Integer

localtime
optional

If true, it uses the computer's local time to format the backup timestamp.

Boolean

rotated_logs_size_limit
optional

Max Size (in mb) of log files before deletion

Integer

rotation_interval
optional

If set, the interval at which log files are rotated, even if max_size is not reached.

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

String

max_age
optional

The maximum number of days to retain old log files.

Integer

StartupConfigLoggingError

Object

Property

Schema

enabled
optional

Toggle for this log output

Boolean

rotation
optional

StartupConfigLoggingErrorRotation

collation_buffer_size
optional

The size of the log collation buffer.

Integer

StartupConfigLoggingErrorRotation

Object

Property Schema

max_size
optional

The maximum size in MB of the log file before it gets rotated.

Integer

localtime
optional

If true, it uses the computer's local time to format the backup timestamp.

Boolean

rotated_logs_size_limit
optional

Max Size (in mb) of log files before deletion

Integer

rotation_interval
optional

If set, the interval at which log files are rotated, even if max_size is not reached.

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

String

max_age
optional

The maximum number of days to retain old log files.

Integer

StartupConfigLoggingInfo

Object

Property

Schema

enabled
optional

Toggle for this log output

Boolean

rotation
optional

StartupConfigLoggingInfoRotation

collation_buffer_size
optional

The size of the log collation buffer

Integer

StartupConfigLoggingInfoRotation

Object

Property Schema

max_size
optional

The maximum size in MB of the log file before it gets rotated.

Integer

localtime
optional

If true, it uses the computer's local time to format the backup timestamp.

Boolean

rotated_logs_size_limit
optional

Max Size (in mb) of log files before deletion

Integer

rotation_interval
optional

If set, the interval at which log files are rotated, even if max_size is not reached.

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

String

max_age
optional

The maximum number of days to retain old log files.

Integer

StartupConfigLoggingStats

Object

Property

Schema

enabled
optional

Toggle for this log output

Boolean

rotation
optional

StartupConfigLoggingInfoRotation

collation_buffer_size
optional

The size of the log collation buffer

Integer

StartupConfigLoggingTrace

Object

Property

Schema

enabled
optional

Toggle for this log output

Boolean

rotation
optional

StartupConfigLoggingDebugRotation

collation_buffer_size
optional

The size of the log collation buffer

Integer

StartupConfigLoggingWarn

Object

Property

Schema

enabled
optional

Toggle for this log output

Boolean

rotation
optional

StartupConfigLoggingWarnRotation

collation_buffer_size
optional

The size of the log collation buffer

Integer

StartupConfigLoggingWarnRotation

Object

Property Schema

max_size
optional

The maximum size in MB of the log file before it gets rotated.

Integer

localtime
optional

If true, it uses the computer's local time to format the backup timestamp.

Boolean

rotated_logs_size_limit
optional

Max Size (in mb) of log files before deletion

Integer

rotation_interval
optional

If set, the interval at which log files are rotated, even if max_size is not reached.

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

String

max_age
optional

The maximum number of days to retain old log files.

Integer

StartupConfigReplicator

Object

Property Schema

max_heartbeat
optional

Max heartbeat value for _changes 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 5h20m30s.

String

blip_compression
optional

BLIP data compression level (0-9)

Minimum: 0
Maximum: 9

Integer

max_concurrent_replications
optional

Maximum number of concurrent replication connections allowed. If set to 0 this limit will be ignored.

Integer

max_concurrent_changes_batches
optional

Maximum number of changes batches to process concurrently per replication (1-5)"

Minimum: 1
Maximum: 5

Integer

max_concurrent_revs
optional

Maximum number of revs to process concurrently per replication (5-200)

Minimum: 5
Maximum: 200

Integer

StartupConfigUnsupported

Object

Property Schema

serverless
optional

Configuration for when SG is running in serverless mode

StartupConfigUnsupportedServerless

use_xattr_config
optional

Store database configurations in system xattrs

Boolean

stats_log_frequency
optional

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

String

use_stdlib_json
optional

Bypass the jsoniter package and use Go's stdlib instead

Boolean

http2
optional

StartupConfigUnsupportedHttp2

allow_dbconfig_env_vars
optional

Can be set to false to skip environment variable expansion in database configs

Boolean

StartupConfigUnsupportedHttp2

Object

Property

Schema

enabled
optional

Whether HTTP2 support is enabled

Boolean

StartupConfigUnsupportedServerless

Object

Property Schema

enabled
optional

Run SG in to serverless mode

Boolean

min_config_fetch_interval
optional

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

String

Status

Object

Property Schema

databases
optional

Contains a map of all the databases in the node along with their status.

version
optional

The product version including the build number and edition (ie. EE or CE).

Blank if api.hide_product_version=true in the startup configuration.

String

Status

Object

Property Schema

databases
optional

Contains a map of all the databases in the node along with their status.

Status1DatabasesValueCluster

version
optional

The product version including the build number and edition (ie. EE or CE).

Blank if api.hide_product_version=true in the startup configuration.

String

Status1DatabasesValue

Object

Property Schema

seq
optional

The latest sequence number in the database.

Minimum: 0

Big Decimal

server_uuid
optional

The server unique identifier.

String

state
optional

Whether the database is online or offline.

Values: "Online", "Offline", "Starting", "Stopping", "Resyncing"

String

replication_status
optional

ReplicationStatus array

cluster
optional

Object

Property

Schema

replication
optional

Map of replication configs defined for the cluster.

Status1DatabasesValueClusterReplication

nodes
optional

Map of all Sync Gateway nodes in the cluster.

Status1DatabasesValueClusterNodes

Object

Property

Schema

node_uuid
optional

The nodes unique identifier.

Status1DatabasesValueClusterNodesNodeUuid

Object

Property

Schema

uuid
optional

The nodes unique identifier.

String

host
optional

The nodes host name.

String

Status1DatabasesValueClusterReplication

Object

Property

Schema

replication_id
optional

Properties of a replication

Replication1

User

Object

Property Schema

name
optional

The name of the user.

User names can only have alphanumeric ASCII characters and underscores.

String

password
optional

The password of the user.

Mandatory. unless allow_empty_password is true in the database configs.

String

admin_channels
optional

A list of channels to explicitly grant to the user for the default collection.

String array

all_channels
optional

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

String array

collection_access
optional

A set of access grants by scope and collection.

email
optional

The email address of the user.

String

disabled
optional

If true, the user will not be able to login to the account as it is disabled.

Boolean

admin_roles
optional

A list of roles to explicitly grant to the user.

String array

roles
optional

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

String array

jwt_roles
optional

The roles that the user has been added to through roles_claim.

String array

jwt_channels
optional

The channels that the user has been granted access to through channels_claim.

String array

jwt_issuer
optional

The issuer of the last JSON Web Token that the user last used to sign in.

String

jwt_last_updated
optional

The last time that the user's JWT roles/channels were updated.

Date (date-time)

User

Object

Property Schema

name
optional

The name of the user.

User names can only have alphanumeric ASCII characters and underscores.

String

password
optional

The password of the user.

Mandatory. unless allow_empty_password is true in the database configs.

String

admin_channels
optional

A list of channels to explicitly grant to the user for the default collection.

String array

all_channels
optional

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

String array

collection_access
optional

A set of access grants by scope and collection.

email
optional

The email address of the user.

String

disabled
optional

If true, the user will not be able to login to the account as it is disabled.

Boolean

admin_roles
optional

A list of roles to explicitly grant to the user.

String array

roles
optional

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

String array

jwt_roles
optional

The roles that the user has been added to through roles_claim.

String array

jwt_channels
optional

The channels that the user has been granted access to through channels_claim.

String array

jwt_issuer
optional

The issuer of the last JSON Web Token that the user last used to sign in.

String

jwt_last_updated
optional

The last time that the user's JWT roles/channels were updated.

Date (date-time)

User1CollectionAccessValueValue

Object

Property Schema

admin_channels
optional

A list of channels to explicitly grant to the user.

String array

all_channels
optional

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

String array

jwt_channels
optional

The channels that the user has been granted access to through channels_claim.

String array

jwt_last_updated
optional

The last time that the user's JWT roles/channels were updated.

Date (date-time)

User

Object

Property Schema

name
optional

The name of the user.

User names can only have alphanumeric ASCII characters and underscores.

String

password
optional

The password of the user.

Mandatory. unless allow_empty_password is true in the database configs.

String

admin_channels
optional

A list of channels to explicitly grant to the user for the default collection.

String array

all_channels
optional

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

String array

collection_access
optional

A set of access grants by scope and collection.