diff --git a/modules/ROOT/assets/attachments/bundled-admin.yaml b/modules/ROOT/assets/attachments/bundled-admin.yaml index 24035a29..bb1e1304 100644 --- a/modules/ROOT/assets/attachments/bundled-admin.yaml +++ b/modules/ROOT/assets/attachments/bundled-admin.yaml @@ -1,8 +1,11 @@ openapi: 3.0.3 info: - title: Sync Gateway - description: Sync Gateway manages access and synchronization between Couchbase Lite and Couchbase Server version: '3.2' + title: Sync Gateway Admin REST API + description: |- + # Introduction + + The Sync Gateway Admin REST API is used to administer user accounts and roles, and to run administrative tasks in superuser mode. license: name: Business Source License 1.1 (BSL) url: https://github.com/couchbase/sync_gateway/blob/master/LICENSE @@ -45,8 +48,8 @@ tags: - name: Unsupported description: Endpoints that are not supported by Sync Gateway externalDocs: - description: Sync Gateway Quickstart | Couchbase Docs - url: https://docs.couchbase.com/sync-gateway/current/index.html + description: ⬆️ Admin REST API Overview + url: rest-api-admin.html paths: /{db}/_session: parameters: @@ -3935,12 +3938,16 @@ paths: type: object properties: size: - description: The maximum number of revisions that can be stored in the revision cache. + description: |- + The maximum number of revisions that can be stored in the revision cache. + Note when running with greater than 1 shard count we add 10% capacity overall to avoid early eviction when some shards fill up before others, so + you may find that the capacity stat (revision_cache_num_items) will climb to the defined rev cache size + 10%. type: string default: 5000 max_memory_count_mb: description: |- The maximum amount of memory the revision cache should take up in MB, setting to 0 will disable any eviction based on memory at rev cache. + There is a minimum value of 50 (50MB) for this config option. When set this memory limit will work in in hand with revision cache size parameter. So you will potentially get eviction at revision cache both based off memory footprint and number of items in the cache. **This is an Enterprise Edition feature only** type: integer @@ -6389,7 +6396,7 @@ paths: operationId: post_keyspace- /_expvar: get: - summary: Get all Sync Gateway statistics + summary: Get all Sync Gateway statistics in JSON format description: |- This returns a snapshot of all metrics in Sync Gateway for debugging and monitoring purposes. @@ -6400,11 +6407,15 @@ paths: * Sync Gateway Architect * Sync Gateway Dev Ops * External Stats Reader + tags: + - JSON responses: '200': - description: Returned statistics + description: |- + Successfully returned statistics. + For details, see [JSON Metrics](stats-monitoring-json.html). content: - application/javascript: + application/json: schema: type: object properties: &ref_126 @@ -6537,6 +6548,9 @@ paths: num_idle_kv_ops: type: integer description: The total number of idle kv operations. + num_idle_query_ops: + type: integer + description: The total number of idle query operations. process_cpu_percent_utilization: type: number format: float @@ -6565,8 +6579,9 @@ paths: description: The total uptime. per_db: description: |- - This array contains stats for all databases declared in the config file -- see the [Sync Gateway Statistics Schema](./../stats-monitoring.html) for more details on the metrics collected and reported by Sync Gateway. - The statistics for each {$db_name} database are grouped into: + This array contains stats for all databases declared in the config file — see [View Statistics and Metrics](stats-monitoring.html) for more details on the metrics collected and reported by Sync Gateway. + + The statistics for each database are grouped into: - cache related statistics - collections statistics - cbl_replication_push @@ -6637,8 +6652,6 @@ paths: Used by versions 1 and 2. type: integer deprecated: true - tags: - - Metrics operationId: get__expvar /: get: diff --git a/modules/ROOT/assets/attachments/bundled-metric.yaml b/modules/ROOT/assets/attachments/bundled-metric.yaml index 48bafef4..f5959dcb 100644 --- a/modules/ROOT/assets/attachments/bundled-metric.yaml +++ b/modules/ROOT/assets/attachments/bundled-metric.yaml @@ -1,8 +1,12 @@ openapi: 3.0.3 info: - title: Sync Gateway - description: Sync Gateway manages access and synchronization between Couchbase Lite and Couchbase Server version: '3.2' + title: Sync Gateway Metrics REST API + description: |- + # Introduction + + Sync Gateway manages access and synchronization between Couchbase Lite and Couchbase Server. + The Sync Gateway Metrics REST API returns Sync Gateway metrics, in JSON or Prometheus-compatible formats, for performance monitoring and diagnostic purposes. license: name: Business Source License 1.1 (BSL) url: https://github.com/couchbase/sync_gateway/blob/master/LICENSE @@ -22,9 +26,13 @@ servers: tags: - name: Prometheus description: Endpoints for use with Prometheus + - name: JSON + description: Endpoints for use with JSON metrics + - name: Server + description: Endpoints for managing the REST API externalDocs: - description: Sync Gateway Quickstart | Couchbase Docs - url: https://docs.couchbase.com/sync-gateway/current/index.html + description: ⬆️ Metrics REST API Overview + url: rest-api-metrics.html paths: /_ping: get: @@ -50,9 +58,9 @@ paths: summary: Check if API is available description: Returns OK status if API is available. operationId: head__ping - /_metrics: - get: &ref_0 - summary: Debugging/monitoring runtime stats in Prometheus Exposition format + /metrics: + get: + summary: Get debugging and monitoring runtime stats in Prometheus Exposition format description: |- Returns Sync Gateway statistics and other runtime variables in Prometheus Exposition format. @@ -63,19 +71,15 @@ paths: * External Stats Reader responses: '200': - description: Successfully returned stats - content: - text/plain: - schema: - type: string + description: |- + Successfully returned statistics. + For details, see [Prometheus Metrics](stats-monitoring-prometheus.html). tags: - Prometheus operationId: get_metrics - /metrics: - get: *ref_0 /_expvar: get: - summary: Get all Sync Gateway statistics + summary: Get all Sync Gateway statistics in JSON format description: |- This returns a snapshot of all metrics in Sync Gateway for debugging and monitoring purposes. @@ -86,14 +90,18 @@ paths: * Sync Gateway Architect * Sync Gateway Dev Ops * External Stats Reader + tags: + - JSON responses: '200': - description: Returned statistics + description: |- + Successfully returned statistics. + For details, see [JSON Metrics](stats-monitoring-json.html). content: - application/javascript: + application/json: schema: type: object - properties: &ref_1 + properties: &ref_0 cmdline: description: Built-in variables from the Go runtime, lists the command-line arguments type: object @@ -223,6 +231,9 @@ paths: num_idle_kv_ops: type: integer description: The total number of idle kv operations. + num_idle_query_ops: + type: integer + description: The total number of idle query operations. process_cpu_percent_utilization: type: number format: float @@ -251,8 +262,9 @@ paths: description: The total uptime. per_db: description: |- - This array contains stats for all databases declared in the config file -- see the [Sync Gateway Statistics Schema](./../stats-monitoring.html) for more details on the metrics collected and reported by Sync Gateway. - The statistics for each {$db_name} database are grouped into: + This array contains stats for all databases declared in the config file — see [View Statistics and Metrics](stats-monitoring.html) for more details on the metrics collected and reported by Sync Gateway. + + The statistics for each database are grouped into: - cache related statistics - collections statistics - cbl_replication_push @@ -328,4 +340,4 @@ components: schemas: ExpVars: type: object - properties: *ref_1 + properties: *ref_0 diff --git a/modules/ROOT/assets/attachments/bundled-public.yaml b/modules/ROOT/assets/attachments/bundled-public.yaml index 379e97e1..42fc1fee 100644 --- a/modules/ROOT/assets/attachments/bundled-public.yaml +++ b/modules/ROOT/assets/attachments/bundled-public.yaml @@ -1,8 +1,12 @@ openapi: 3.0.3 info: - title: Sync Gateway - description: Sync Gateway manages access and synchronization between Couchbase Lite and Couchbase Server version: '3.2' + title: Sync Gateway Public REST API + description: |- + # Introduction + + Sync Gateway manages access and synchronization between Couchbase Lite and Couchbase Server. + The Sync Gateway Public REST API is used for client replication. license: name: Business Source License 1.1 (BSL) url: https://github.com/couchbase/sync_gateway/blob/master/LICENSE @@ -39,8 +43,8 @@ tags: description: Endpoints that are not supported by Sync Gateway x-capella: false externalDocs: - description: Sync Gateway Quickstart | Couchbase Docs - url: https://docs.couchbase.com/sync-gateway/current/index.html + description: ⬆️ Public REST API Overview + url: rest-api.html paths: /{db}/_session: parameters: diff --git a/modules/ROOT/assets/overlays/admin.yaml b/modules/ROOT/assets/overlays/admin.yaml index 66c09763..89ca6b92 100644 --- a/modules/ROOT/assets/overlays/admin.yaml +++ b/modules/ROOT/assets/overlays/admin.yaml @@ -10,19 +10,12 @@ info: extends: ../attachments/bundled-admin.yaml actions: - - description: Update title and introduction - target: $.info - update: - title: Sync Gateway Admin REST API - description: |- - # Introduction - - Sync Gateway manages access and synchronization between Couchbase Lite and Couchbase Server. - The Sync Gateway Admin REST API is used to administer user accounts and roles, and to run administrative tasks in superuser mode. + - description: Remove existing tags from the _expvar endpoint + target: $.paths['/_expvar'].get.tags + remove: true - - description: Update link to external docs - target: '$' + - description: Add the Metrics tag to the _expvar endpoint + target: $.paths['/_expvar'].get update: - externalDocs: - description: ⬆️ Admin REST API Overview - url: rest-api-admin.html + tags: + - Metrics diff --git a/modules/ROOT/assets/overlays/metric.yaml b/modules/ROOT/assets/overlays/metric.yaml index c3110d4f..dd6c186f 100644 --- a/modules/ROOT/assets/overlays/metric.yaml +++ b/modules/ROOT/assets/overlays/metric.yaml @@ -10,88 +10,11 @@ info: extends: ../attachments/bundled-metric.yaml actions: - - description: Update title and introduction - target: $.info - update: - title: Sync Gateway Metrics REST API - description: |- - # Introduction - - Sync Gateway manages access and synchronization between Couchbase Lite and Couchbase Server. - The Sync Gateway Metrics REST API returns Sync Gateway metrics, in JSON or Prometheus-compatible formats, for performance monitoring and diagnostic purposes. - - - description: Update link to external docs - target: '$' - update: - externalDocs: - description: ⬆️ Metrics REST API Overview - url: rest-api-metrics.html - - - description: Add a tag for JSON metrics and description for the Server tag - target: '$' - update: - tags: - - name: JSON - description: Endpoints for use with JSON metrics - - name: Server - description: Endpoints for managing the REST API - - - description: Add the JSON tag to the _expvar endpoint - target: $.paths['/_expvar'].get - update: - tags: - - JSON - - - description: Update summary of the _expvar endpoint - target: $.paths['/_expvar'].get - update: - summary: Get all Sync Gateway statistics in JSON format - - - description: Update description for the JSON metrics endpoint - target: $.paths['/_expvar'].get.responses.200 - update: - description: |- - Successfully returned statistics. - For details, see [JSON Metrics](stats-monitoring-json.html). - - - description: Remove the duplicate metrics endpoint - target: $.paths['/_metrics'] - remove: true - - - description: Update the description for the Sync Gateway `per_db` response - target: $.paths['/_expvar'].get.responses.200.content['application/javascript'].schema.properties.syncgateway.properties.per_db - update: - description: |- - This array contains stats for all databases declared in the config file — see [View Statistics and Metrics](stats-monitoring.html) for more details on the metrics collected and reported by Sync Gateway. - The statistics for each 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` - - - description: Fix name of Prometheus method - target: $.paths['/metrics'].get - update: - summary: Get debugging and monitoring runtime stats in Prometheus Exposition format - - description: Add Prometheus metrics target: $.paths['/metrics'].get.responses update: '200': - description: |- - Successfully returned statistics. - For details, see [Prometheus Metrics](stats-monitoring-prometheus.html). content: application/json: schema: $ref: metrics_metadata.json - - - description: Remove the plain text Prometheus response. - target: $.paths['/metrics'].get.responses.200.content['text/plain'] - remove: true \ No newline at end of file diff --git a/modules/ROOT/assets/overlays/public.yaml b/modules/ROOT/assets/overlays/public.yaml index ee6e6b69..ddb4d297 100644 --- a/modules/ROOT/assets/overlays/public.yaml +++ b/modules/ROOT/assets/overlays/public.yaml @@ -10,19 +10,7 @@ info: extends: ../attachments/bundled-public.yaml actions: - - description: Update introduction - target: $.info - update: - title: Sync Gateway Public REST API - description: |- - # Introduction - - Sync Gateway manages access and synchronization between Couchbase Lite and Couchbase Server. - The Sync Gateway Public REST API is used for client replication. - - - description: Update link to external docs + - description: Dummy action (no changes required) target: '$' update: - externalDocs: - description: ⬆️ Public REST API Overview - url: rest-api.html + x-overlaid: false diff --git a/modules/ROOT/generate-docs.sh b/modules/ROOT/generate-docs.sh index 42e1823a..815c7081 100755 --- a/modules/ROOT/generate-docs.sh +++ b/modules/ROOT/generate-docs.sh @@ -26,12 +26,11 @@ git fetch --tags git reset --hard ${tag} cd .. -PATH_TO_SYNC_GATEWAY=${PATH_TO_SYNC_GATEWAY:-${GIT_ROOT}/sync_gateway} -PATH_TO_SPECS="${PATH_TO_SYNC_GATEWAY}/docs/api/" +PATH_TO_SYNC_GATEWAY="${GIT_ROOT}/sync_gateway" -PATH_TO_BUNDLE=${PATH_TO_BUNDLE:-${GIT_ROOT}/modules/ROOT/assets/attachments} -PATH_TO_OVERLAY=${PATH_TO_OVERLAY:-${GIT_ROOT}/modules/ROOT/assets/overlays} -PATH_TO_TEMP=${PATH_TO_TEMP:-${GIT_ROOT}/modules/ROOT/assets/bld} +PATH_TO_BUNDLE="${GIT_ROOT}/modules/ROOT/assets/attachments" +PATH_TO_OVERLAY="${GIT_ROOT}/modules/ROOT/assets/overlays" +PATH_TO_TEMP="${GIT_ROOT}/modules/ROOT/assets/bld" # Create a bld directory to hold temporary files, if it doesn't already exist [[ -d "${PATH_TO_TEMP}" ]] || mkdir "${PATH_TO_TEMP}" diff --git a/modules/ROOT/partials/sgw-openapi-admin.html b/modules/ROOT/partials/sgw-openapi-admin.html index 2ec60718..94f9d66f 100644 --- a/modules/ROOT/partials/sgw-openapi-admin.html +++ b/modules/ROOT/partials/sgw-openapi-admin.html @@ -1,401 +1,425 @@ - -
API docs by Redocly
API docs by Redocly

Sync Gateway Admin REST API (3.2)

Download OpenAPI specification:Download

License: Business Source License 1.1 (BSL)
⬆️ Admin REST API Overview

Introduction

Sync Gateway manages access and synchronization between Couchbase Lite and Couchbase Server. -The Sync Gateway Admin REST API is used to administer user accounts and roles, and to run administrative tasks in superuser mode.

-

Authentication

Sync Gateway Admin REST API (3.2)

Download OpenAPI specification:

License: Business Source License 1.1 (BSL)
⬆️ Admin REST API Overview

Introduction

The Sync Gateway Admin REST API is used to administer user accounts and roles, and to run administrative tasks in superuser mode.

+

Authentication

Manage authentication

-

Create a new Facebook-based session Deprecated

Create a new Facebook-based session Deprecated

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

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

-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
Request Body schema: application/json
access_token
required
string

Facebook access token to base the new session on.

-

Responses

Request samples

Content type
application/json
{
  • "access_token": "string"
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "reason": "string"
}

Create a new Google-based session Deprecated

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
Request Body schema: application/json
access_token
required
string

Facebook access token to base the new session on.

+

Responses

Request samples

Content type
application/json
{
  • "access_token": "string"
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "reason": "string"
}

Create a new Google-based session Deprecated

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

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

-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
Request Body schema: application/json
id_token
required
string

Google ID token to base the new session on.

-

Responses

Request samples

Content type
application/json
{
  • "id_token": "string"
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "reason": "string"
}

OpenID Connect authentication initiation via Location header redirect

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

-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
query Parameters
provider
string

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

-
offline
string

If true, the OpenID Connect provider is requested to confirm with the user the permissions requested and refresh the OIDC token. To do this, access_type=offline and prompt=consent is set on the redirection link.

-

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

OpenID Connect authentication initiation via WWW-Authenticate header

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

-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
query Parameters
provider
string

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

-
offline
string

If true, the OpenID Connect provider is requested to confirm with the user the permissions requested and refresh the OIDC token. To do this, access_type=offline and prompt=consent is set on the redirection link.

-

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

OpenID Connect authentication callback

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

-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
query Parameters
error
string

The OpenID Connect error, if any occurred.

-
code
required
string

The OpenID Connect authentication code.

-
provider
string

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

-
state
string

The OpenID Connect state to verify against the state cookie. This is used to prevent cross-site request forgery (CSRF). This is not required if disable_callback_state=true for the provider config (NOT recommended).

-

Responses

Response samples

Content type
application/json
{
  • "id_token": "string",
  • "refresh_token": "string",
  • "session_id": "string",
  • "name": "string",
  • "access_token": "string",
  • "token_type": "string",
  • "expires_in": 0
}

OpenID Connect token refresh

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

-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
query Parameters
refresh_token
required
string

The OpenID Connect refresh token.

-
provider
string

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

-

Responses

Response samples

Content type
application/json
{
  • "id_token": "string",
  • "refresh_token": "string",
  • "session_id": "string",
  • "name": "string",
  • "access_token": "string",
  • "token_type": "string",
  • "expires_in": 0
}

OpenID Connect mock provider

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

-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-

Responses

Response samples

Content type
application/json
{
  • "issuer": "string",
  • "authorization_endpoint": "string",
  • "token_endpoint": "string",
  • "jwks_uri": "string",
  • "userinfo_endpoint": "string",
  • "id_token_signing_alg_values_supported": "string",
  • "response_types_supported": "string",
  • "subject_types_supported": "string",
  • "scopes_supported": "string",
  • "claims_supported": "string",
  • "token_endpoint_auth_methods_supported": "string"
}

OpenID Connect mock login page

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

-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
query Parameters
scope
required
string

The OpenID Connect authentication scope.

-

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "reason": "string"
}

OpenID Connect mock login page

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

-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
query Parameters
scope
required
string

The OpenID Connect authentication scope.

-

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "reason": "string"
}

OpenID Connect mock token

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

-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
Request Body schema: application/json
grant_type
required
string

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

-
code
string

grant_type=authorization_code only: The OpenID Connect authentication token.

-
refresh_token
string

grant_type=refresh_token only: The OpenID Connect refresh token.

-

Responses

Request samples

Content type
application/json
{
  • "grant_type": "string",
  • "code": "string",
  • "refresh_token": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "string",
  • "refresh_token": "string",
  • "expires_in": "string",
  • "id_token": "string"
}

OpenID Connect public certificates for signing keys

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

-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-

Responses

Response samples

Content type
application/json
{
  • "keys": [
    ]
}

OpenID Connect mock login page handler

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

-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
query Parameters
redirect_uri
string

The Sync Gateway OpenID Connect callback URL.

-
scope
required
string

The OpenID Connect authentication scope.

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

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

OpenID Connect mock login page handler

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

-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
query Parameters
redirect_uri
string

The Sync Gateway OpenID Connect callback URL.

-
scope
required
string

The OpenID Connect authentication scope.

-
Request Body schema: application/json

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

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

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "tokenttl": "string",
  • "identity-token-formats": "string",
  • "authenticated": "string"
}

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Server

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
Request Body schema: application/json
id_token
required
string

Google ID token to base the new session on.

+

Responses

Request samples

Content type
application/json
{
  • "id_token": "string"
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "reason": "string"
}

OpenID Connect authentication initiation via Location header redirect

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

+
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
query Parameters
provider
string

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

+
offline
string

If true, the OpenID Connect provider is requested to confirm with the user the permissions requested and refresh the OIDC token. To do this, access_type=offline and prompt=consent is set on the redirection link.

+

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

OpenID Connect authentication initiation via WWW-Authenticate header

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

+
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
query Parameters
provider
string

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

+
offline
string

If true, the OpenID Connect provider is requested to confirm with the user the permissions requested and refresh the OIDC token. To do this, access_type=offline and prompt=consent is set on the redirection link.

+

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

OpenID Connect authentication callback

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

+
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
query Parameters
error
string

The OpenID Connect error, if any occurred.

+
code
required
string

The OpenID Connect authentication code.

+
provider
string

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

+
state
string

The OpenID Connect state to verify against the state cookie. This is used to prevent cross-site request forgery (CSRF). This is not required if disable_callback_state=true for the provider config (NOT recommended).

+

Responses

Response samples

Content type
application/json
{
  • "id_token": "string",
  • "refresh_token": "string",
  • "session_id": "string",
  • "name": "string",
  • "access_token": "string",
  • "token_type": "string",
  • "expires_in": 0
}

OpenID Connect token refresh

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

+
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
query Parameters
refresh_token
required
string

The OpenID Connect refresh token.

+
provider
string

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

+

Responses

Response samples

Content type
application/json
{
  • "id_token": "string",
  • "refresh_token": "string",
  • "session_id": "string",
  • "name": "string",
  • "access_token": "string",
  • "token_type": "string",
  • "expires_in": 0
}

OpenID Connect mock provider

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

+
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+

Responses

Response samples

Content type
application/json
{
  • "issuer": "string",
  • "authorization_endpoint": "string",
  • "token_endpoint": "string",
  • "jwks_uri": "string",
  • "userinfo_endpoint": "string",
  • "id_token_signing_alg_values_supported": "string",
  • "response_types_supported": "string",
  • "subject_types_supported": "string",
  • "scopes_supported": "string",
  • "claims_supported": "string",
  • "token_endpoint_auth_methods_supported": "string"
}

OpenID Connect mock login page

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

+
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
query Parameters
scope
required
string

The OpenID Connect authentication scope.

+

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "reason": "string"
}

OpenID Connect mock login page

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

+
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
query Parameters
scope
required
string

The OpenID Connect authentication scope.

+

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "reason": "string"
}

OpenID Connect mock token

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

+
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
Request Body schema: application/json
grant_type
required
string

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

+
code
string

grant_type=authorization_code only: The OpenID Connect authentication token.

+
refresh_token
string

grant_type=refresh_token only: The OpenID Connect refresh token.

+

Responses

Request samples

Content type
application/json
{
  • "grant_type": "string",
  • "code": "string",
  • "refresh_token": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "string",
  • "refresh_token": "string",
  • "expires_in": "string",
  • "id_token": "string"
}

OpenID Connect public certificates for signing keys

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

+
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+

Responses

Response samples

Content type
application/json
{
  • "keys": [
    ]
}

OpenID Connect mock login page handler

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

+
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
query Parameters
redirect_uri
string

The Sync Gateway OpenID Connect callback URL.

+
scope
required
string

The OpenID Connect authentication scope.

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

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

OpenID Connect mock login page handler

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

+
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
query Parameters
redirect_uri
string

The Sync Gateway OpenID Connect callback URL.

+
scope
required
string

The OpenID Connect authentication scope.

+
Request Body schema: application/json

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

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

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "tokenttl": "string",
  • "identity-token-formats": "string",
  • "authenticated": "string"
}

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Server

Manage server activities

-

Get console logging settings Deprecated

Get console logging settings Deprecated

Deprecated in favour of GET /_config +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Dev Ops
-

Responses

Response samples

Content type
application/json
{
  • "HTTP": true,
  • "CRUD": false,
  • "Changes": true
}

Set console logging settings Deprecated

Responses

Response samples

Content type
application/json
{
  • "HTTP": true,
  • "CRUD": false,
  • "Changes": true
}

Set console logging settings Deprecated

Deprecated in favour of PUT /_config +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Dev Ops
-
query Parameters
logLevel
string
Enum: "none" "error" "warn" "info" "debug" "trace"

The is what to set the console log level too.

-
level
integer [ 1 .. 3 ]
Deprecated
query Parameters
logLevel
string
Enum: "none" "error" "warn" "info" "debug" "trace"

The is what to set the console log level too.

+
level
integer [ 1 .. 3 ]
Deprecated

Deprecated: use log level instead.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

Deprecated: use log level instead.

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

-
Request Body schema: application/json

The map of log keys to use for console logging.

-
property name*
additional property
boolean

The log key and whether it is enabled or not.

-

Responses

Request samples

Content type
application/json
{
  • "HTTP": true,
  • "CRUD": false,
  • "Changes": true
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "reason": "string"
}

Update console logging settings Deprecated

Request Body schema: application/json

The map of log keys to use for console logging.

+
property name*
additional property
boolean

The log key and whether it is enabled or not.

+

Responses

Request samples

Content type
application/json
{
  • "HTTP": true,
  • "CRUD": false,
  • "Changes": true
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "reason": "string"
}

Update console logging settings Deprecated

Deprecated in favour of PUT /_config +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Dev Ops
-
query Parameters
logLevel
string
Enum: "none" "error" "warn" "info" "debug" "trace"

The is what to set the console log level too.

-
level
integer [ 1 .. 3 ]
Deprecated
query Parameters
logLevel
string
Enum: "none" "error" "warn" "info" "debug" "trace"

The is what to set the console log level too.

+
level
integer [ 1 .. 3 ]
Deprecated

Deprecated: use log level instead.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

Deprecated: use log level instead.

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

-
Request Body schema: application/json

The console log keys to upsert.

-
property name*
additional property
boolean

The log key and whether it is enabled or not.

-

Responses

Request samples

Content type
application/json
{
  • "HTTP": true,
  • "CRUD": false,
  • "Changes": true
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "reason": "string"
}

Get server configuration

Request Body schema: application/json

The console log keys to upsert.

+
property name*
additional property
boolean

The log key and whether it is enabled or not.

+

Responses

Request samples

Content type
application/json
{
  • "HTTP": true,
  • "CRUD": false,
  • "Changes": true
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "reason": "string"
}

Get server configuration

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Dev Ops
-
query Parameters
redact
boolean
Deprecated
Default: "true"

No longer supported field.

-
include_runtime
boolean
Default: false

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

-

Responses

Response samples

Content type
application/json
{
  • "bootstrap": {
    },
  • "api": {
    },
  • "logging": {
    },
  • "auth": {
    },
  • "replicator": {
    },
  • "unsupported": {
    },
  • "database_credentials": {
    },
  • "bucket_credentials": {
    },
  • "max_file_descriptors": 5000,
  • "couchbase_keepalive_interval": 0,
  • "heap_profile_collection_threshold": "max memory",
  • "heap_profile_disable_collection": false
}

Set runtime configuration

query Parameters
redact
boolean
Deprecated
Default: "true"

No longer supported field.

+
include_runtime
boolean
Default: false

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

+

Responses

Response samples

Content type
application/json
{
  • "bootstrap": {
    },
  • "api": {
    },
  • "logging": {
    },
  • "auth": {
    },
  • "replicator": {
    },
  • "unsupported": {
    },
  • "database_credentials": {
    },
  • "bucket_credentials": {
    },
  • "max_file_descriptors": 5000,
  • "couchbase_keepalive_interval": 0,
  • "heap_profile_collection_threshold": "max memory",
  • "heap_profile_disable_collection": false
}

Set runtime configuration

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

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

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Dev Ops
-
Request Body schema: application/json
object
max_concurrent_replications
integer
Default: 0

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

-

Responses

Request samples

Content type
application/json
{
  • "logging": {
    },
  • "max_concurrent_replications": 0
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "reason": "string"
}

Get the server status

Request Body schema: application/json
object
max_concurrent_replications
integer
Default: 0

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

+

Responses

Request samples

Content type
application/json
{
  • "logging": {
    },
  • "max_concurrent_replications": 0
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "reason": "string"
}

Get the server status

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Dev Ops
-

Responses

Response samples

Content type
application/json
{
  • "databases": {
    },
  • "version": "string"
}

Get the status of the Sync Gateway Collect Info

Responses

Response samples

Content type
application/json
{
  • "databases": {
    },
  • "version": "string"
}

Get the status of the Sync Gateway Collect Info

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Dev Ops
-

Responses

Response samples

Content type
application/json
{
  • "status": "stopped"
}

Start Sync Gateway Collect Info

Responses

Response samples

Content type
application/json
{
  • "status": "stopped"
}

Start Sync Gateway Collect Info

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Dev Ops
-
Request Body schema: application/json

sgcollect_info options

-
redact_level
string
Default: "partial"
Enum: "partial" "none"

The redaction level to use for redacting the collected logs.

-
redact_salt
string

The salt to use for the log redactions.

-
output_dir
string
Default: "The configured path set in the startup config `logging.log_file_path`"
Request Body schema: application/json

sgcollect_info options

+
redact_level
string
Default: "partial"
Enum: "partial" "none"

The redaction level to use for redacting the collected logs.

+
redact_salt
string

The salt to use for the log redactions.

+
output_dir
string
Default: "The configured path set in the startup config `logging.log_file_path`"

The directory to output the collected logs zip file at.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

The directory to output the collected logs zip file at.

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

-
upload
boolean
upload
boolean

If set, upload the logs to Couchbase Support.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

If set, upload the logs to Couchbase Support.

A customer name must be set if this is set.

-
upload_host
string
Default: "https://uploads.couchbase.com"

The host to send the logs too.

-
upload_proxy
string

The proxy to use while uploading the logs.

-
customer
string

The customer name to use when uploading the logs.

-
ticket
string [ 1 .. 7 ] characters

The Zendesk ticket number to use when uploading logs.

-

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "status": "started"
}

Cancel the Sync Gateway Collect Info job

upload_host
string
Default: "https://uploads.couchbase.com"

The host to send the logs too.

+
upload_proxy
string

The proxy to use while uploading the logs.

+
customer
string

The customer name to use when uploading the logs.

+
ticket
string [ 1 .. 7 ] characters

The Zendesk ticket number to use when uploading logs.

+

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "status": "started"
}

Cancel the Sync Gateway Collect Info job

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Dev Ops
-

Responses

Response samples

Content type
application/json
{
  • "status": "cancelled"
}

Run the post upgrade process on all databases

Responses

Response samples

Content type
application/json
{
  • "status": "cancelled"
}

Run the post upgrade process on all databases

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Dev Ops
-
query Parameters
preview
string
Default: "false"

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

-

Responses

Response samples

Content type
application/json
{
  • "post_upgrade_results": {
    },
  • "preview": true
}

Get server information

Returns information about the Sync Gateway node.

-

Responses

Response samples

Content type
application/json
{
  • "ADMIN": true,
  • "couchdb": "Welcome",
  • "vendor": {
    },
  • "version": "Couchbase Sync Gateway/3.1.0(1;a765231) EE",
  • "persistent_config": true
}

Check if server online

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

-

Responses

Check if API is available

Returns OK status if API is available.

-

Responses

Response samples

Content type
text/plain
OK

Check if API is available

Returns OK status if API is available.

-

Responses

Database Management

query Parameters
preview
string
Default: "false"

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

+

Responses

Response samples

Content type
application/json
{
  • "post_upgrade_results": {
    },
  • "preview": true
}

Get server information

Returns information about the Sync Gateway node.

+

Responses

Response samples

Content type
application/json
{
  • "ADMIN": true,
  • "couchdb": "Welcome",
  • "vendor": {
    },
  • "version": "Couchbase Sync Gateway/3.1.0(1;a765231) EE",
  • "persistent_config": true
}

Check if server online

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

+

Responses

Check if API is available

Returns OK status if API is available.

+

Responses

Response samples

Content type
text/plain
OK

Check if API is available

Returns OK status if API is available.

+

Responses

Database Management

Create and manage Sync Gateway databases

-

Get resync status

Get resync status

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Architect
-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-

Responses

Response samples

Content type
application/json
{
  • "status": "running",
  • "start_time": "string",
  • "last_error": "string",
  • "docs_changed": 0,
  • "docs_processed": 0,
  • "collections_processing": {
    }
}

Start or stop Resync

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+

Responses

Response samples

Content type
application/json
{
  • "status": "running",
  • "start_time": "string",
  • "last_error": "string",
  • "docs_changed": 0,
  • "docs_processed": 0,
  • "collections_processing": {
    }
}

Start or stop Resync

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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.

@@ -945,25 +967,25 @@
  • Sync Gateway Architect
-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
query Parameters
action
string
Default: "start"
Enum: "start" "stop"

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

-
regenerate_sequences
boolean

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

-
reset
boolean
Default: false

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

-
Request Body schema: application/json
object

This controls for which collections resync will run

-
regenerate_sequences
boolean
Default: false

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

-

Responses

Request samples

Content type
application/json
{
  • "scopes": {
    },
  • "regenerate_sequences": false
}

Response samples

Content type
application/json
{
  • "status": "running",
  • "start_time": "string",
  • "last_error": "string",
  • "docs_changed": 0,
  • "docs_processed": 0,
  • "collections_processing": {
    }
}

Bring the database online

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
query Parameters
action
string
Default: "start"
Enum: "start" "stop"

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

+
regenerate_sequences
boolean

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

+
reset
boolean
Default: false

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

+
Request Body schema: application/json
object

This controls for which collections resync will run

+
regenerate_sequences
boolean
Default: false

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

+

Responses

Request samples

Content type
application/json
{
  • "scopes": {
    },
  • "regenerate_sequences": false
}

Response samples

Content type
application/json
{
  • "status": "running",
  • "start_time": "string",
  • "last_error": "string",
  • "docs_changed": 0,
  • "docs_processed": 0,
  • "collections_processing": {
    }
}

Bring the database online

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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.
    • @@ -995,21 +1017,21 @@
    • Sync Gateway Architect
    -
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
Request Body schema: application/json

Add an optional delay to wait before bringing the database online

-
delay
integer
Default: 0

The amount of seconds to delay bringing the database online.

-

Responses

Request samples

Content type
application/json
{
  • "delay": 0
}

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Take the database offline

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
Request Body schema: application/json

Add an optional delay to wait before bringing the database online

+
delay
integer
Default: 0

The amount of seconds to delay bringing the database online.

+

Responses

Request samples

Content type
application/json
{
  • "delay": 0
}

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Take the database offline

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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:

@@ -1037,31 +1059,31 @@
  • Sync Gateway Architect
-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Get a list of all the databases

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Get a list of all the databases

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Dev Ops
-
query Parameters
verbose
boolean

Responses

Response samples

Content type
application/json
[ ]

Manage a compact operation

query Parameters
verbose
boolean

Responses

Response samples

Content type
application/json
[ ]

Manage a compact operation

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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.
    • @@ -1083,127 +1105,127 @@
    • Sync Gateway Architect
    -
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
query Parameters
type
string
Default: "tombstone"
Enum: "attachment" "tombstone"
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
query Parameters
type
string
Default: "tombstone"
Enum: "attachment" "tombstone"

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

  • attachment for cleaning up legacy (pre-3.0) attachments
  • tombstone for purging the JSON bodies of non-leaf revisions.'
-
action
string
Default: "start"
Enum: "start" "stop"

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

-
reset
boolean
action
string
Default: "start"
Enum: "start" "stop"

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

+
reset
boolean

Attachment compaction only

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

Attachment compaction only

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

-
dry_run
boolean
dry_run
boolean

Attachment compaction only

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

Attachment compaction only

This will run through all 3 stages of attachment compact but will not purge any attachments. This can be used to check how many attachments will be purged.'

-

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "reason": "string"
}

Get the status of the most recent compact operation

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "reason": "string"
}

Get the status of the most recent compact operation

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Architect
-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
query Parameters
type
string
Default: "tombstone"
Enum: "attachment" "tombstone"
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
query Parameters
type
string
Default: "tombstone"
Enum: "attachment" "tombstone"

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

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

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "start_time": "string",
  • "last_error": "string",
  • "docs_purged": "string",
  • "marked_attachments": "string",
  • "purged_attachments": "string",
  • "compact_id": "string",
  • "phase": "string",
  • "dry_run": "mark"
}

Get database information

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "start_time": "string",
  • "last_error": "string",
  • "docs_purged": "string",
  • "marked_attachments": "string",
  • "purged_attachments": "string",
  • "compact_id": "string",
  • "phase": "string",
  • "dry_run": "mark"
}

Get database information

Retrieve information about the database.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

Retrieve information about the database.

Required Sync Gateway RBAC roles:

  • Sync Gateway Dev Ops
-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-

Responses

Response samples

Content type
application/json
{
  • "db_name": "db",
  • "update_seq": 123456,
  • "committed_update_seq": 123456,
  • "instance_start_time": 1644600082279583,
  • "compact_running": true,
  • "purge_seq": 0,
  • "disk_format_version": 0,
  • "state": "Online",
  • "server_uuid": "995618a6a6cc9ac79731bd13240e19b5",
  • "init_in_progress": true
}

Remove a database

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+

Responses

Response samples

Content type
application/json
{
  • "db_name": "db",
  • "update_seq": 123456,
  • "committed_update_seq": 123456,
  • "instance_start_time": 1644600082279583,
  • "compact_running": true,
  • "purge_seq": 0,
  • "disk_format_version": 0,
  • "state": "Online",
  • "server_uuid": "995618a6a6cc9ac79731bd13240e19b5",
  • "init_in_progress": true
}

Remove a database

Removes a database from the Sync Gateway cluster

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

Removes a database from the Sync Gateway cluster

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Architect
-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-

Responses

Response samples

Content type
application/json
{ }

Check if database exists

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+

Responses

Response samples

Content type
application/json
{ }

Check if database exists

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Dev Ops
-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Create a new Sync Gateway database

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Create a new Sync Gateway database

This is to create a new database for Sync Gateway.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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.

@@ -1219,843 +1241,843 @@
  • Sync Gateway Architect
-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
query Parameters
disable_oidc_validation
boolean
Default: false

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

-
Request Body schema: application/json

The configuration to use for the new database

-
server
string

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

-
pool
string
Deprecated
Default: "default"

This field is unsupported and ignored.

-
bucket
string
Default: "The database name"

The Couchbase Server backing bucket for the database.

-
username
string

The username for authenticating to the server.

-
password
string

The password for authenticating to the server.

-
certpath
string

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

-
keypath
string

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

-
cacertpath
string

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

-
kv_tls_port
integer
Default: 11207

The Memcached TLS port.

-
max_concurrent_query_ops
integer
Default: 1000

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

-
object <= 1 properties

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

-
name
string

The name of the database.

-
sync
string
Default: "function(doc){channel(doc.channels);}"
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
query Parameters
disable_oidc_validation
boolean
Default: false

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

+
Request Body schema: application/json

The configuration to use for the new database

+
server
string

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

+
pool
string
Deprecated
Default: "default"

This field is unsupported and ignored.

+
bucket
string
Default: "The database name"

The Couchbase Server backing bucket for the database.

+
username
string

The username for authenticating to the server.

+
password
string

The password for authenticating to the server.

+
certpath
string

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

+
keypath
string

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

+
cacertpath
string

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

+
kv_tls_port
integer
Default: 11207

The Memcached TLS port.

+
max_concurrent_query_ops
integer
Default: 1000

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

+
object <= 1 properties

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

+
name
string

The name of the database.

+
sync
string
Default: "function(doc){channel(doc.channels);}"

The Javascript function that newly created documents are ran through for the default scope and collection. +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

-
object
object
revs_limit
number >= 0
Default: "100 if conflict allowed and 50 if not"
object
object
revs_limit
number >= 0
Default: "100 if conflict allowed and 50 if not"

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

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

-
import_docs
boolean
import_docs
boolean

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

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

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

-
import_partitions
number
Default: 16
import_partitions
number
Default: 16

** This is an Enterprise Edition feature only**

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

** This is an Enterprise Edition feature only**

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

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

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

-
import_filter
string
import_filter
string

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

import_docs must be true to make this field applicable.

If scopes parameter is set, this is ignored.

-
import_backup_old_rev
boolean
Default: false

This controls whether import should attempt to create a temporary backup of the previous revision body (if available) when the document is modified in the bucket.

-
object

These are the settings for webhooks.

-
feed_type
string
Deprecated
Default: "DCP"
Value: "DCP"

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

-
allow_empty_password
boolean
Default: false

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

-
object
rev_cache_size
number
Deprecated
import_backup_old_rev
boolean
Default: false

This controls whether import should attempt to create a temporary backup of the previous revision body (if available) when the document is modified in the bucket.

+
object

These are the settings for webhooks.

+
feed_type
string
Deprecated
Default: "DCP"
Value: "DCP"

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

+
allow_empty_password
boolean
Default: false

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

+
object
rev_cache_size
number
Deprecated

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

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

-
offline
boolean
Default: false

Start the database in an offline state.

-
object

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

-
object

Configuration for Local JWT authentication.

-
object

Configuration for OpenID Connect authentication.

-
old_rev_expiry_seconds
number
Default: 300

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

-
view_query_timeout_secs
integer
Default: 75

The number of seconds before a view query should timeout.

-
local_doc_expiry_secs
integer
Default: 7776000

The number of seconds before a _local document should expire.

-
enable_shared_bucket_access
boolean
Default: true

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

-
session_cookie_secure
boolean
offline
boolean
Default: false

Start the database in an offline state.

+
object

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

+
object

Configuration for Local JWT authentication.

+
object

Configuration for OpenID Connect authentication.

+
old_rev_expiry_seconds
number
Default: 300

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

+
view_query_timeout_secs
integer
Default: 75

The number of seconds before a view query should timeout.

+
local_doc_expiry_secs
integer
Default: 7776000

The number of seconds before a _local document should expire.

+
enable_shared_bucket_access
boolean
Default: true

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

+
session_cookie_secure
boolean

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

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

-
session_cookie_name
string

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

-
session_cookie_http_only
boolean
Default: false

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

-
allow_conflicts
boolean
Deprecated
Default: true

This controls whether to allow conflicting document revisions.

-
num_index_replicas
number
Default: 1

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

-
use_views
boolean
Default: false

Force the use of views instead of GSI.

-
send_www_authenticate_header
boolean
Default: true

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

-
disable_password_auth
boolean
Default: false

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

-
bucket_op_timeout_ms
number

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

-
slow_query_warning_threshold
number
Default: 500

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

-
object
session_cookie_name
string

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

+
session_cookie_http_only
boolean
Default: false

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

+
allow_conflicts
boolean
Deprecated
Default: true

This controls whether to allow conflicting document revisions.

+
num_index_replicas
number
Default: 1

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

+
use_views
boolean
Default: false

Force the use of views instead of GSI.

+
send_www_authenticate_header
boolean
Default: true

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

+
disable_password_auth
boolean
Default: false

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

+
bucket_op_timeout_ms
number

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

+
slow_query_warning_threshold
number
Default: 500

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

+
object

Delta sync configuration settings.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

Delta sync configuration settings.

This is an Enterprise Edition feature only

-
compact_interval_days
number
Default: 1
compact_interval_days
number
Default: 1

The interval between scheduled tombstone compaction runs (in days). This can be a floating point number.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

The interval between scheduled tombstone compaction runs (in days). This can be a floating point number.

If set to 0, compaction will not run automatically.

-
sgreplicate_enabled
boolean
Default: true

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

-
sgreplicate_websocket_heartbeat_secs
integer
Default: 300

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

-
object
serve_insecure_attachment_types
boolean
Default: false
sgreplicate_enabled
boolean
Default: true

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

+
sgreplicate_websocket_heartbeat_secs
integer
Default: 300

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

+
object
serve_insecure_attachment_types
boolean
Default: false

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

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

-
query_pagination_limit
integer
Default: 5000

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

-
user_xattr_key
string

The key to use for the user xattr that will be accessible from the sync function. IF empty, the feature will be disabled.

-
client_partition_window_secs
integer
Default: 2592000
query_pagination_limit
integer
Default: 5000

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

+
user_xattr_key
string

The key to use for the user xattr that will be accessible from the sync function. IF empty, the feature will be disabled.

+
client_partition_window_secs
integer
Default: 2592000

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

Defaults to 30 days (in seconds)

-
object (User)

Properties associated with a user

-
javascript_timeout_secs
number
Default: 60

The maximum number of seconds the sync, import filter, and custom conflict resolver JavaScript functions are allowed to run for before timing out. Set to 0 to allow the JS functions to run uncapped.

-
suspendable
boolean
Default: false
object (User)

Properties associated with a user

+
javascript_timeout_secs
number
Default: 60

The maximum number of seconds the sync, import filter, and custom conflict resolver JavaScript functions are allowed to run for before timing out. Set to 0 to allow the JS functions to run uncapped.

+
suspendable
boolean
Default: false

Set to true to allow the database to be suspended.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

Set to true to allow the database to be suspended.

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

-
object

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

-
object

Per-database logging configuration.

-

Responses

Request samples

Content type
application/json
{
  • "server": "string",
  • "pool": "default",
  • "bucket": "The database name",
  • "username": "string",
  • "password": "string",
  • "certpath": "string",
  • "keypath": "string",
  • "cacertpath": "string",
  • "kv_tls_port": 11207,
  • "max_concurrent_query_ops": 1000,
  • "scopes": {
    },
  • "name": "string",
  • "sync": "function(doc){channel(doc.channels);}",
  • "users": {
    },
  • "roles": {
    },
  • "revs_limit": "100 if conflict allowed and 50 if not",
  • "import_docs": true,
  • "import_partitions": 16,
  • "import_filter": "function(doc) { if (doc.type != 'mobile') { return false; } return true; }",
  • "import_backup_old_rev": false,
  • "event_handlers": {
    },
  • "feed_type": "DCP",
  • "allow_empty_password": false,
  • "cache": {
    },
  • "rev_cache_size": 0,
  • "offline": false,
  • "unsupported": {
    },
  • "local_jwt": {
    },
  • "oidc": {
    },
  • "old_rev_expiry_seconds": 300,
  • "view_query_timeout_secs": 75,
  • "local_doc_expiry_secs": 7776000,
  • "enable_shared_bucket_access": true,
  • "session_cookie_secure": true,
  • "session_cookie_name": "string",
  • "session_cookie_http_only": false,
  • "allow_conflicts": true,
  • "num_index_replicas": 1,
  • "use_views": false,
  • "send_www_authenticate_header": true,
  • "disable_password_auth": false,
  • "bucket_op_timeout_ms": 0,
  • "slow_query_warning_threshold": 500,
  • "delta_sync": {
    },
  • "compact_interval_days": 1,
  • "sgreplicate_enabled": true,
  • "sgreplicate_websocket_heartbeat_secs": 300,
  • "replications": {
    },
  • "serve_insecure_attachment_types": false,
  • "query_pagination_limit": 5000,
  • "user_xattr_key": "string",
  • "client_partition_window_secs": 2592000,
  • "guest": {
    },
  • "javascript_timeout_secs": 60,
  • "suspendable": false,
  • "cors": {
    },
  • "logging": {
    }
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "reason": "string"
}

Get changes list

object

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

+
object

Per-database logging configuration.

+

Responses

Request samples

Content type
application/json
{
  • "server": "string",
  • "pool": "default",
  • "bucket": "The database name",
  • "username": "string",
  • "password": "string",
  • "certpath": "string",
  • "keypath": "string",
  • "cacertpath": "string",
  • "kv_tls_port": 11207,
  • "max_concurrent_query_ops": 1000,
  • "scopes": {
    },
  • "name": "string",
  • "sync": "function(doc){channel(doc.channels);}",
  • "users": {
    },
  • "roles": {
    },
  • "revs_limit": "100 if conflict allowed and 50 if not",
  • "import_docs": true,
  • "import_partitions": 16,
  • "import_filter": "function(doc) { if (doc.type != 'mobile') { return false; } return true; }",
  • "import_backup_old_rev": false,
  • "event_handlers": {
    },
  • "feed_type": "DCP",
  • "allow_empty_password": false,
  • "cache": {
    },
  • "rev_cache_size": 0,
  • "offline": false,
  • "unsupported": {
    },
  • "local_jwt": {
    },
  • "oidc": {
    },
  • "old_rev_expiry_seconds": 300,
  • "view_query_timeout_secs": 75,
  • "local_doc_expiry_secs": 7776000,
  • "enable_shared_bucket_access": true,
  • "session_cookie_secure": true,
  • "session_cookie_name": "string",
  • "session_cookie_http_only": false,
  • "allow_conflicts": true,
  • "num_index_replicas": 1,
  • "use_views": false,
  • "send_www_authenticate_header": true,
  • "disable_password_auth": false,
  • "bucket_op_timeout_ms": 0,
  • "slow_query_warning_threshold": 500,
  • "delta_sync": {
    },
  • "compact_interval_days": 1,
  • "sgreplicate_enabled": true,
  • "sgreplicate_websocket_heartbeat_secs": 300,
  • "replications": {
    },
  • "serve_insecure_attachment_types": false,
  • "query_pagination_limit": 5000,
  • "user_xattr_key": "string",
  • "client_partition_window_secs": 2592000,
  • "guest": {
    },
  • "javascript_timeout_secs": 60,
  • "suspendable": false,
  • "cors": {
    },
  • "logging": {
    }
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "reason": "string"
}

Get changes list

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Application
  • Sync Gateway Application Read Only
-
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection

The keyspace to run the operation against.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

The keyspace to run the operation against.

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

-
query Parameters
limit
integer

Maximum number of changes to return.

-
since
string

Starts the results from the change immediately after the given sequence ID. Sequence IDs should be considered opaque; they come from the last_seq property of a prior response.

-
style
string
Default: "main_only"
Enum: "main_only" "all_docs"

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

-
active_only
boolean
Default: "false"

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

-
include_docs
boolean

Include the body associated with each document.

-
revocations
boolean

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

-
filter
string
Enum: "sync_gateway/bychannel" "_doc_ids"

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

-
channels
string

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

-
doc_ids
Array of strings

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

-
heartbeat
integer >= 25000
Default: 0

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

-
timeout
integer [ 0 .. 900000 ]
Default: 300000

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

-
feed
string
Default: "normal"
Enum: "normal" "longpoll" "continuous" "websocket"

The type of changes feed to use.

-
request_plus
boolean
Default: "false"

When true, ensures all valid documents written prior to the request being issued are included in the response. This is only applicable for non-continuous feeds.

-

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "last_seq": "string"
}

Get changes list

query Parameters
limit
integer

Maximum number of changes to return.

+
since
string

Starts the results from the change immediately after the given sequence ID. Sequence IDs should be considered opaque; they come from the last_seq property of a prior response.

+
style
string
Default: "main_only"
Enum: "main_only" "all_docs"

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

+
active_only
boolean
Default: "false"

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

+
include_docs
boolean

Include the body associated with each document.

+
revocations
boolean

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

+
filter
string
Enum: "sync_gateway/bychannel" "_doc_ids"

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

+
channels
string

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

+
doc_ids
Array of strings

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

+
heartbeat
integer >= 25000
Default: 0

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

+
timeout
integer [ 0 .. 900000 ]
Default: 300000

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

+
feed
string
Default: "normal"
Enum: "normal" "longpoll" "continuous" "websocket"

The type of changes feed to use.

+
request_plus
boolean
Default: "false"

When true, ensures all valid documents written prior to the request being issued are included in the response. This is only applicable for non-continuous feeds.

+

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "last_seq": "string"
}

Get changes list

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Application
  • Sync Gateway Application Read Only
-
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection

The keyspace to run the operation against.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

The keyspace to run the operation against.

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

-
Request Body schema: application/json
limit
string

Maximum number of changes to return.

-
style
string

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

-
active_only
string

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

-
include_docs
string

Include the body associated with each document.

-
revocations
string

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

-
filter
string

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

-
channels
string

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

-
doc_ids
string

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

-
heartbeat
string

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

-
timeout
string

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

-
feed
string

The type of changes feed to use.

-
request_plus
string

When true, ensures all valid documents written prior to the request being issued are included in the response. This is only applicable for non-continuous feeds.

-

Responses

Request samples

Content type
application/json
{
  • "limit": "string",
  • "style": "string",
  • "active_only": "string",
  • "include_docs": "string",
  • "revocations": "string",
  • "filter": "string",
  • "channels": "string",
  • "doc_ids": "string",
  • "heartbeat": "string",
  • "timeout": "string",
  • "feed": "string",
  • "request_plus": "string"
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "last_seq": "string"
}

/{db}/_changes

Request Body schema: application/json
limit
string

Maximum number of changes to return.

+
style
string

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

+
active_only
string

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

+
include_docs
string

Include the body associated with each document.

+
revocations
string

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

+
filter
string

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

+
channels
string

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

+
doc_ids
string

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

+
heartbeat
string

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

+
timeout
string

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

+
feed
string

The type of changes feed to use.

+
request_plus
string

When true, ensures all valid documents written prior to the request being issued are included in the response. This is only applicable for non-continuous feeds.

+

Responses

Request samples

Content type
application/json
{
  • "limit": "string",
  • "style": "string",
  • "active_only": "string",
  • "include_docs": "string",
  • "revocations": "string",
  • "filter": "string",
  • "channels": "string",
  • "doc_ids": "string",
  • "heartbeat": "string",
  • "timeout": "string",
  • "feed": "string",
  • "request_plus": "string"
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "last_seq": "string"
}

/{db}/_changes

Required Sync Gateway RBAC roles:

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

Required Sync Gateway RBAC roles:

  • Sync Gateway Application
  • Sync Gateway Application Read Only
-
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection

The keyspace to run the operation against.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

The keyspace to run the operation against.

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

-

Responses

/{db}/_ensure_full_commit

Responses

/{db}/_ensure_full_commit

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Application
  • Sync Gateway Application Read Only
-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-

Responses

Response samples

Content type
application/json
{
  • "instance_start_time": 1644600082279583,
  • "ok": true
}

Compare revisions to what is in the database

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+

Responses

Response samples

Content type
application/json
{
  • "instance_start_time": 1644600082279583,
  • "ok": true
}

Compare revisions to what is in the database

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Application
-
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection

The keyspace to run the operation against.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

The keyspace to run the operation against.

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

-
Request Body schema: application/json
docid
Array of strings

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

-

Responses

Request samples

Content type
application/json
{
  • "docid": [
    ]
}

Response samples

Content type
application/json
{
  • "docid": {
    }
}

Database Configuration

Request Body schema: application/json
docid
Array of strings

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

+

Responses

Request samples

Content type
application/json
{
  • "docid": [
    ]
}

Response samples

Content type
application/json
{
  • "docid": {
    }
}

Database Configuration

Configure Sync Gateway databases

-

Get database configuration

Get database configuration

Retrieve the full configuration for the database specified.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

Retrieve the full configuration for the database specified.

Required Sync Gateway RBAC roles:

  • Sync Gateway Architect
-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
query Parameters
redact
boolean
Deprecated
Default: "true"

No longer supported field.

-
include_javascript
boolean
Default: true

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

-
include_runtime
boolean
Default: false

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

-
refresh_config
boolean
Default: false

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

-

Responses

Response samples

Content type
application/json
{
  • "server": "string",
  • "pool": "default",
  • "bucket": "The database name",
  • "username": "string",
  • "password": "string",
  • "certpath": "string",
  • "keypath": "string",
  • "cacertpath": "string",
  • "kv_tls_port": 11207,
  • "max_concurrent_query_ops": 1000,
  • "scopes": {
    },
  • "name": "string",
  • "sync": "function(doc){channel(doc.channels);}",
  • "users": {
    },
  • "roles": {
    },
  • "revs_limit": "100 if conflict allowed and 50 if not",
  • "import_docs": true,
  • "import_partitions": 16,
  • "import_filter": "function(doc) { if (doc.type != 'mobile') { return false; } return true; }",
  • "import_backup_old_rev": false,
  • "event_handlers": {
    },
  • "feed_type": "DCP",
  • "allow_empty_password": false,
  • "cache": {
    },
  • "rev_cache_size": 0,
  • "offline": false,
  • "unsupported": {
    },
  • "local_jwt": {
    },
  • "oidc": {
    },
  • "old_rev_expiry_seconds": 300,
  • "view_query_timeout_secs": 75,
  • "local_doc_expiry_secs": 7776000,
  • "enable_shared_bucket_access": true,
  • "session_cookie_secure": true,
  • "session_cookie_name": "string",
  • "session_cookie_http_only": false,
  • "allow_conflicts": true,
  • "num_index_replicas": 1,
  • "use_views": false,
  • "send_www_authenticate_header": true,
  • "disable_password_auth": false,
  • "bucket_op_timeout_ms": 0,
  • "slow_query_warning_threshold": 500,
  • "delta_sync": {
    },
  • "compact_interval_days": 1,
  • "sgreplicate_enabled": true,
  • "sgreplicate_websocket_heartbeat_secs": 300,
  • "replications": {
    },
  • "serve_insecure_attachment_types": false,
  • "query_pagination_limit": 5000,
  • "user_xattr_key": "string",
  • "client_partition_window_secs": 2592000,
  • "guest": {
    },
  • "javascript_timeout_secs": 60,
  • "suspendable": false,
  • "cors": {
    },
  • "logging": {
    }
}

Replace database configuration

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
query Parameters
redact
boolean
Deprecated
Default: "true"

No longer supported field.

+
include_javascript
boolean
Default: true

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

+
include_runtime
boolean
Default: false

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

+
refresh_config
boolean
Default: false

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

+

Responses

Response samples

Content type
application/json
{
  • "server": "string",
  • "pool": "default",
  • "bucket": "The database name",
  • "username": "string",
  • "password": "string",
  • "certpath": "string",
  • "keypath": "string",
  • "cacertpath": "string",
  • "kv_tls_port": 11207,
  • "max_concurrent_query_ops": 1000,
  • "scopes": {
    },
  • "name": "string",
  • "sync": "function(doc){channel(doc.channels);}",
  • "users": {
    },
  • "roles": {
    },
  • "revs_limit": "100 if conflict allowed and 50 if not",
  • "import_docs": true,
  • "import_partitions": 16,
  • "import_filter": "function(doc) { if (doc.type != 'mobile') { return false; } return true; }",
  • "import_backup_old_rev": false,
  • "event_handlers": {
    },
  • "feed_type": "DCP",
  • "allow_empty_password": false,
  • "cache": {
    },
  • "rev_cache_size": 0,
  • "offline": false,
  • "unsupported": {
    },
  • "local_jwt": {
    },
  • "oidc": {
    },
  • "old_rev_expiry_seconds": 300,
  • "view_query_timeout_secs": 75,
  • "local_doc_expiry_secs": 7776000,
  • "enable_shared_bucket_access": true,
  • "session_cookie_secure": true,
  • "session_cookie_name": "string",
  • "session_cookie_http_only": false,
  • "allow_conflicts": true,
  • "num_index_replicas": 1,
  • "use_views": false,
  • "send_www_authenticate_header": true,
  • "disable_password_auth": false,
  • "bucket_op_timeout_ms": 0,
  • "slow_query_warning_threshold": 500,
  • "delta_sync": {
    },
  • "compact_interval_days": 1,
  • "sgreplicate_enabled": true,
  • "sgreplicate_websocket_heartbeat_secs": 300,
  • "replications": {
    },
  • "serve_insecure_attachment_types": false,
  • "query_pagination_limit": 5000,
  • "user_xattr_key": "string",
  • "client_partition_window_secs": 2592000,
  • "guest": {
    },
  • "javascript_timeout_secs": 60,
  • "suspendable": false,
  • "cors": {
    },
  • "logging": {
    }
}

Replace database configuration

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Architect
  • Sync Gateway Application
-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
query Parameters
disable_oidc_validation
boolean
Default: false

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

-
header Parameters
If-Match
string

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

-
Request Body schema: application/json

The new database configuration to use

-
server
string

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

-
pool
string
Deprecated
Default: "default"

This field is unsupported and ignored.

-
bucket
string
Default: "The database name"

The Couchbase Server backing bucket for the database.

-
username
string

The username for authenticating to the server.

-
password
string

The password for authenticating to the server.

-
certpath
string

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

-
keypath
string

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

-
cacertpath
string

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

-
kv_tls_port
integer
Default: 11207

The Memcached TLS port.

-
max_concurrent_query_ops
integer
Default: 1000

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

-
object <= 1 properties

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

-
name
string

The name of the database.

-
sync
string
Default: "function(doc){channel(doc.channels);}"
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
query Parameters
disable_oidc_validation
boolean
Default: false

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

+
header Parameters
If-Match
string

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

+
Request Body schema: application/json

The new database configuration to use

+
server
string

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

+
pool
string
Deprecated
Default: "default"

This field is unsupported and ignored.

+
bucket
string
Default: "The database name"

The Couchbase Server backing bucket for the database.

+
username
string

The username for authenticating to the server.

+
password
string

The password for authenticating to the server.

+
certpath
string

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

+
keypath
string

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

+
cacertpath
string

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

+
kv_tls_port
integer
Default: 11207

The Memcached TLS port.

+
max_concurrent_query_ops
integer
Default: 1000

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

+
object <= 1 properties

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

+
name
string

The name of the database.

+
sync
string
Default: "function(doc){channel(doc.channels);}"

The Javascript function that newly created documents are ran through for the default scope and collection. +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

-
object
object
revs_limit
number >= 0
Default: "100 if conflict allowed and 50 if not"
object
object
revs_limit
number >= 0
Default: "100 if conflict allowed and 50 if not"

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

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

-
import_docs
boolean
import_docs
boolean

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

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

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

-
import_partitions
number
Default: 16
import_partitions
number
Default: 16

** This is an Enterprise Edition feature only**

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

** This is an Enterprise Edition feature only**

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

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

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

-
import_filter
string
import_filter
string

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

import_docs must be true to make this field applicable.

If scopes parameter is set, this is ignored.

-
import_backup_old_rev
boolean
Default: false

This controls whether import should attempt to create a temporary backup of the previous revision body (if available) when the document is modified in the bucket.

-
object

These are the settings for webhooks.

-
feed_type
string
Deprecated
Default: "DCP"
Value: "DCP"

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

-
allow_empty_password
boolean
Default: false

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

-
object
rev_cache_size
number
Deprecated
import_backup_old_rev
boolean
Default: false

This controls whether import should attempt to create a temporary backup of the previous revision body (if available) when the document is modified in the bucket.

+
object

These are the settings for webhooks.

+
feed_type
string
Deprecated
Default: "DCP"
Value: "DCP"

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

+
allow_empty_password
boolean
Default: false

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

+
object
rev_cache_size
number
Deprecated

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

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

-
offline
boolean
Default: false

Start the database in an offline state.

-
object

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

-
object

Configuration for Local JWT authentication.

-
object

Configuration for OpenID Connect authentication.

-
old_rev_expiry_seconds
number
Default: 300

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

-
view_query_timeout_secs
integer
Default: 75

The number of seconds before a view query should timeout.

-
local_doc_expiry_secs
integer
Default: 7776000

The number of seconds before a _local document should expire.

-
enable_shared_bucket_access
boolean
Default: true

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

-
session_cookie_secure
boolean
offline
boolean
Default: false

Start the database in an offline state.

+
object

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

+
object

Configuration for Local JWT authentication.

+
object

Configuration for OpenID Connect authentication.

+
old_rev_expiry_seconds
number
Default: 300

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

+
view_query_timeout_secs
integer
Default: 75

The number of seconds before a view query should timeout.

+
local_doc_expiry_secs
integer
Default: 7776000

The number of seconds before a _local document should expire.

+
enable_shared_bucket_access
boolean
Default: true

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

+
session_cookie_secure
boolean

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

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

-
session_cookie_name
string

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

-
session_cookie_http_only
boolean
Default: false

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

-
allow_conflicts
boolean
Deprecated
Default: true

This controls whether to allow conflicting document revisions.

-
num_index_replicas
number
Default: 1

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

-
use_views
boolean
Default: false

Force the use of views instead of GSI.

-
send_www_authenticate_header
boolean
Default: true

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

-
disable_password_auth
boolean
Default: false

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

-
bucket_op_timeout_ms
number

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

-
slow_query_warning_threshold
number
Default: 500

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

-
object
session_cookie_name
string

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

+
session_cookie_http_only
boolean
Default: false

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

+
allow_conflicts
boolean
Deprecated
Default: true

This controls whether to allow conflicting document revisions.

+
num_index_replicas
number
Default: 1

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

+
use_views
boolean
Default: false

Force the use of views instead of GSI.

+
send_www_authenticate_header
boolean
Default: true

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

+
disable_password_auth
boolean
Default: false

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

+
bucket_op_timeout_ms
number

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

+
slow_query_warning_threshold
number
Default: 500

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

+
object

Delta sync configuration settings.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

Delta sync configuration settings.

This is an Enterprise Edition feature only

-
compact_interval_days
number
Default: 1
compact_interval_days
number
Default: 1

The interval between scheduled tombstone compaction runs (in days). This can be a floating point number.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

The interval between scheduled tombstone compaction runs (in days). This can be a floating point number.

If set to 0, compaction will not run automatically.

-
sgreplicate_enabled
boolean
Default: true

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

-
sgreplicate_websocket_heartbeat_secs
integer
Default: 300

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

-
object
serve_insecure_attachment_types
boolean
Default: false
sgreplicate_enabled
boolean
Default: true

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

+
sgreplicate_websocket_heartbeat_secs
integer
Default: 300

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

+
object
serve_insecure_attachment_types
boolean
Default: false

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

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

-
query_pagination_limit
integer
Default: 5000

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

-
user_xattr_key
string

The key to use for the user xattr that will be accessible from the sync function. IF empty, the feature will be disabled.

-
client_partition_window_secs
integer
Default: 2592000
query_pagination_limit
integer
Default: 5000

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

+
user_xattr_key
string

The key to use for the user xattr that will be accessible from the sync function. IF empty, the feature will be disabled.

+
client_partition_window_secs
integer
Default: 2592000

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

Defaults to 30 days (in seconds)

-
object (User)

Properties associated with a user

-
javascript_timeout_secs
number
Default: 60

The maximum number of seconds the sync, import filter, and custom conflict resolver JavaScript functions are allowed to run for before timing out. Set to 0 to allow the JS functions to run uncapped.

-
suspendable
boolean
Default: false
object (User)

Properties associated with a user

+
javascript_timeout_secs
number
Default: 60

The maximum number of seconds the sync, import filter, and custom conflict resolver JavaScript functions are allowed to run for before timing out. Set to 0 to allow the JS functions to run uncapped.

+
suspendable
boolean
Default: false

Set to true to allow the database to be suspended.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

Set to true to allow the database to be suspended.

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

-
object

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

-
object

Per-database logging configuration.

-

Responses

object

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

+
object

Per-database logging configuration.

+

Responses

Request samples

Content type
application/json
{
  • "server": "string",
  • "pool": "default",
  • "bucket": "The database name",
  • "username": "string",
  • "password": "string",
  • "certpath": "string",
  • "keypath": "string",
  • "cacertpath": "string",
  • "kv_tls_port": 11207,
  • "max_concurrent_query_ops": 1000,
  • "scopes": {
    },
  • "name": "string",
  • "sync": "function(doc){channel(doc.channels);}",
  • "users": {
    },
  • "roles": {
    },
  • "revs_limit": "100 if conflict allowed and 50 if not",
  • "import_docs": true,
  • "import_partitions": 16,
  • "import_filter": "function(doc) { if (doc.type != 'mobile') { return false; } return true; }",
  • "import_backup_old_rev": false,
  • "event_handlers": {
    },
  • "feed_type": "DCP",
  • "allow_empty_password": false,
  • "cache": {
    },
  • "rev_cache_size": 0,
  • "offline": false,
  • "unsupported": {
    },
  • "local_jwt": {
    },
  • "oidc": {
    },
  • "old_rev_expiry_seconds": 300,
  • "view_query_timeout_secs": 75,
  • "local_doc_expiry_secs": 7776000,
  • "enable_shared_bucket_access": true,
  • "session_cookie_secure": true,
  • "session_cookie_name": "string",
  • "session_cookie_http_only": false,
  • "allow_conflicts": true,
  • "num_index_replicas": 1,
  • "use_views": false,
  • "send_www_authenticate_header": true,
  • "disable_password_auth": false,
  • "bucket_op_timeout_ms": 0,
  • "slow_query_warning_threshold": 500,
  • "delta_sync": {
    },
  • "compact_interval_days": 1,
  • "sgreplicate_enabled": true,
  • "sgreplicate_websocket_heartbeat_secs": 300,
  • "replications": {
    },
  • "serve_insecure_attachment_types": false,
  • "query_pagination_limit": 5000,
  • "user_xattr_key": "string",
  • "client_partition_window_secs": 2592000,
  • "guest": {
    },
  • "javascript_timeout_secs": 60,
  • "suspendable": false,
  • "cors": {
    },
  • "logging": {
    }
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "reason": "string"
}

Update database configuration

Request samples

Content type
application/json
{
  • "server": "string",
  • "pool": "default",
  • "bucket": "The database name",
  • "username": "string",
  • "password": "string",
  • "certpath": "string",
  • "keypath": "string",
  • "cacertpath": "string",
  • "kv_tls_port": 11207,
  • "max_concurrent_query_ops": 1000,
  • "scopes": {
    },
  • "name": "string",
  • "sync": "function(doc){channel(doc.channels);}",
  • "users": {
    },
  • "roles": {
    },
  • "revs_limit": "100 if conflict allowed and 50 if not",
  • "import_docs": true,
  • "import_partitions": 16,
  • "import_filter": "function(doc) { if (doc.type != 'mobile') { return false; } return true; }",
  • "import_backup_old_rev": false,
  • "event_handlers": {
    },
  • "feed_type": "DCP",
  • "allow_empty_password": false,
  • "cache": {
    },
  • "rev_cache_size": 0,
  • "offline": false,
  • "unsupported": {
    },
  • "local_jwt": {
    },
  • "oidc": {
    },
  • "old_rev_expiry_seconds": 300,
  • "view_query_timeout_secs": 75,
  • "local_doc_expiry_secs": 7776000,
  • "enable_shared_bucket_access": true,
  • "session_cookie_secure": true,
  • "session_cookie_name": "string",
  • "session_cookie_http_only": false,
  • "allow_conflicts": true,
  • "num_index_replicas": 1,
  • "use_views": false,
  • "send_www_authenticate_header": true,
  • "disable_password_auth": false,
  • "bucket_op_timeout_ms": 0,
  • "slow_query_warning_threshold": 500,
  • "delta_sync": {
    },
  • "compact_interval_days": 1,
  • "sgreplicate_enabled": true,
  • "sgreplicate_websocket_heartbeat_secs": 300,
  • "replications": {
    },
  • "serve_insecure_attachment_types": false,
  • "query_pagination_limit": 5000,
  • "user_xattr_key": "string",
  • "client_partition_window_secs": 2592000,
  • "guest": {
    },
  • "javascript_timeout_secs": 60,
  • "suspendable": false,
  • "cors": {
    },
  • "logging": {
    }
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "reason": "string"
}

Update database configuration

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Architect
  • Sync Gateway Application
-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
header Parameters
If-Match
string

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

-
Request Body schema: application/json

The database configuration fields to update

-
server
string

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

-
pool
string
Deprecated
Default: "default"

This field is unsupported and ignored.

-
bucket
string
Default: "The database name"

The Couchbase Server backing bucket for the database.

-
username
string

The username for authenticating to the server.

-
password
string

The password for authenticating to the server.

-
certpath
string

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

-
keypath
string

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

-
cacertpath
string

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

-
kv_tls_port
integer
Default: 11207

The Memcached TLS port.

-
max_concurrent_query_ops
integer
Default: 1000

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

-
object <= 1 properties

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

-
name
string

The name of the database.

-
sync
string
Default: "function(doc){channel(doc.channels);}"
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
header Parameters
If-Match
string

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

+
Request Body schema: application/json

The database configuration fields to update

+
server
string

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

+
pool
string
Deprecated
Default: "default"

This field is unsupported and ignored.

+
bucket
string
Default: "The database name"

The Couchbase Server backing bucket for the database.

+
username
string

The username for authenticating to the server.

+
password
string

The password for authenticating to the server.

+
certpath
string

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

+
keypath
string

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

+
cacertpath
string

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

+
kv_tls_port
integer
Default: 11207

The Memcached TLS port.

+
max_concurrent_query_ops
integer
Default: 1000

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

+
object <= 1 properties

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

+
name
string

The name of the database.

+
sync
string
Default: "function(doc){channel(doc.channels);}"

The Javascript function that newly created documents are ran through for the default scope and collection. +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

-
object
object
revs_limit
number >= 0
Default: "100 if conflict allowed and 50 if not"
object
object
revs_limit
number >= 0
Default: "100 if conflict allowed and 50 if not"

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

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

-
import_docs
boolean
import_docs
boolean

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

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

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

-
import_partitions
number
Default: 16
import_partitions
number
Default: 16

** This is an Enterprise Edition feature only**

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

** This is an Enterprise Edition feature only**

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

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

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

-
import_filter
string
import_filter
string

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

import_docs must be true to make this field applicable.

If scopes parameter is set, this is ignored.

-
import_backup_old_rev
boolean
Default: false

This controls whether import should attempt to create a temporary backup of the previous revision body (if available) when the document is modified in the bucket.

-
object

These are the settings for webhooks.

-
feed_type
string
Deprecated
Default: "DCP"
Value: "DCP"

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

-
allow_empty_password
boolean
Default: false

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

-
object
rev_cache_size
number
Deprecated
import_backup_old_rev
boolean
Default: false

This controls whether import should attempt to create a temporary backup of the previous revision body (if available) when the document is modified in the bucket.

+
object

These are the settings for webhooks.

+
feed_type
string
Deprecated
Default: "DCP"
Value: "DCP"

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

+
allow_empty_password
boolean
Default: false

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

+
object
rev_cache_size
number
Deprecated

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

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

-
offline
boolean
Default: false

Start the database in an offline state.

-
object

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

-
object

Configuration for Local JWT authentication.

-
object

Configuration for OpenID Connect authentication.

-
old_rev_expiry_seconds
number
Default: 300

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

-
view_query_timeout_secs
integer
Default: 75

The number of seconds before a view query should timeout.

-
local_doc_expiry_secs
integer
Default: 7776000

The number of seconds before a _local document should expire.

-
enable_shared_bucket_access
boolean
Default: true

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

-
session_cookie_secure
boolean
offline
boolean
Default: false

Start the database in an offline state.

+
object

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

+
object

Configuration for Local JWT authentication.

+
object

Configuration for OpenID Connect authentication.

+
old_rev_expiry_seconds
number
Default: 300

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

+
view_query_timeout_secs
integer
Default: 75

The number of seconds before a view query should timeout.

+
local_doc_expiry_secs
integer
Default: 7776000

The number of seconds before a _local document should expire.

+
enable_shared_bucket_access
boolean
Default: true

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

+
session_cookie_secure
boolean

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

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

-
session_cookie_name
string

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

-
session_cookie_http_only
boolean
Default: false

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

-
allow_conflicts
boolean
Deprecated
Default: true

This controls whether to allow conflicting document revisions.

-
num_index_replicas
number
Default: 1

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

-
use_views
boolean
Default: false

Force the use of views instead of GSI.

-
send_www_authenticate_header
boolean
Default: true

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

-
disable_password_auth
boolean
Default: false

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

-
bucket_op_timeout_ms
number

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

-
slow_query_warning_threshold
number
Default: 500

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

-
object
session_cookie_name
string

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

+
session_cookie_http_only
boolean
Default: false

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

+
allow_conflicts
boolean
Deprecated
Default: true

This controls whether to allow conflicting document revisions.

+
num_index_replicas
number
Default: 1

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

+
use_views
boolean
Default: false

Force the use of views instead of GSI.

+
send_www_authenticate_header
boolean
Default: true

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

+
disable_password_auth
boolean
Default: false

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

+
bucket_op_timeout_ms
number

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

+
slow_query_warning_threshold
number
Default: 500

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

+
object

Delta sync configuration settings.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

Delta sync configuration settings.

This is an Enterprise Edition feature only

-
compact_interval_days
number
Default: 1
compact_interval_days
number
Default: 1

The interval between scheduled tombstone compaction runs (in days). This can be a floating point number.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

The interval between scheduled tombstone compaction runs (in days). This can be a floating point number.

If set to 0, compaction will not run automatically.

-
sgreplicate_enabled
boolean
Default: true

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

-
sgreplicate_websocket_heartbeat_secs
integer
Default: 300

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

-
object
serve_insecure_attachment_types
boolean
Default: false
sgreplicate_enabled
boolean
Default: true

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

+
sgreplicate_websocket_heartbeat_secs
integer
Default: 300

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

+
object
serve_insecure_attachment_types
boolean
Default: false

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

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

-
query_pagination_limit
integer
Default: 5000

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

-
user_xattr_key
string

The key to use for the user xattr that will be accessible from the sync function. IF empty, the feature will be disabled.

-
client_partition_window_secs
integer
Default: 2592000
query_pagination_limit
integer
Default: 5000

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

+
user_xattr_key
string

The key to use for the user xattr that will be accessible from the sync function. IF empty, the feature will be disabled.

+
client_partition_window_secs
integer
Default: 2592000

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

Defaults to 30 days (in seconds)

-
object (User)

Properties associated with a user

-
javascript_timeout_secs
number
Default: 60

The maximum number of seconds the sync, import filter, and custom conflict resolver JavaScript functions are allowed to run for before timing out. Set to 0 to allow the JS functions to run uncapped.

-
suspendable
boolean
Default: false
object (User)

Properties associated with a user

+
javascript_timeout_secs
number
Default: 60

The maximum number of seconds the sync, import filter, and custom conflict resolver JavaScript functions are allowed to run for before timing out. Set to 0 to allow the JS functions to run uncapped.

+
suspendable
boolean
Default: false

Set to true to allow the database to be suspended.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

Set to true to allow the database to be suspended.

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

-
object

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

-
object

Per-database logging configuration.

-

Responses

object

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

+
object

Per-database logging configuration.

+

Responses

Request samples

Content type
application/json
{
  • "server": "string",
  • "pool": "default",
  • "bucket": "The database name",
  • "username": "string",
  • "password": "string",
  • "certpath": "string",
  • "keypath": "string",
  • "cacertpath": "string",
  • "kv_tls_port": 11207,
  • "max_concurrent_query_ops": 1000,
  • "scopes": {
    },
  • "name": "string",
  • "sync": "function(doc){channel(doc.channels);}",
  • "users": {
    },
  • "roles": {
    },
  • "revs_limit": "100 if conflict allowed and 50 if not",
  • "import_docs": true,
  • "import_partitions": 16,
  • "import_filter": "function(doc) { if (doc.type != 'mobile') { return false; } return true; }",
  • "import_backup_old_rev": false,
  • "event_handlers": {
    },
  • "feed_type": "DCP",
  • "allow_empty_password": false,
  • "cache": {
    },
  • "rev_cache_size": 0,
  • "offline": false,
  • "unsupported": {
    },
  • "local_jwt": {
    },
  • "oidc": {
    },
  • "old_rev_expiry_seconds": 300,
  • "view_query_timeout_secs": 75,
  • "local_doc_expiry_secs": 7776000,
  • "enable_shared_bucket_access": true,
  • "session_cookie_secure": true,
  • "session_cookie_name": "string",
  • "session_cookie_http_only": false,
  • "allow_conflicts": true,
  • "num_index_replicas": 1,
  • "use_views": false,
  • "send_www_authenticate_header": true,
  • "disable_password_auth": false,
  • "bucket_op_timeout_ms": 0,
  • "slow_query_warning_threshold": 500,
  • "delta_sync": {
    },
  • "compact_interval_days": 1,
  • "sgreplicate_enabled": true,
  • "sgreplicate_websocket_heartbeat_secs": 300,
  • "replications": {
    },
  • "serve_insecure_attachment_types": false,
  • "query_pagination_limit": 5000,
  • "user_xattr_key": "string",
  • "client_partition_window_secs": 2592000,
  • "guest": {
    },
  • "javascript_timeout_secs": 60,
  • "suspendable": false,
  • "cors": {
    },
  • "logging": {
    }
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "reason": "string"
}

Get database audit configuration

Request samples

Content type
application/json
{
  • "server": "string",
  • "pool": "default",
  • "bucket": "The database name",
  • "username": "string",
  • "password": "string",
  • "certpath": "string",
  • "keypath": "string",
  • "cacertpath": "string",
  • "kv_tls_port": 11207,
  • "max_concurrent_query_ops": 1000,
  • "scopes": {
    },
  • "name": "string",
  • "sync": "function(doc){channel(doc.channels);}",
  • "users": {
    },
  • "roles": {
    },
  • "revs_limit": "100 if conflict allowed and 50 if not",
  • "import_docs": true,
  • "import_partitions": 16,
  • "import_filter": "function(doc) { if (doc.type != 'mobile') { return false; } return true; }",
  • "import_backup_old_rev": false,
  • "event_handlers": {
    },
  • "feed_type": "DCP",
  • "allow_empty_password": false,
  • "cache": {
    },
  • "rev_cache_size": 0,
  • "offline": false,
  • "unsupported": {
    },
  • "local_jwt": {
    },
  • "oidc": {
    },
  • "old_rev_expiry_seconds": 300,
  • "view_query_timeout_secs": 75,
  • "local_doc_expiry_secs": 7776000,
  • "enable_shared_bucket_access": true,
  • "session_cookie_secure": true,
  • "session_cookie_name": "string",
  • "session_cookie_http_only": false,
  • "allow_conflicts": true,
  • "num_index_replicas": 1,
  • "use_views": false,
  • "send_www_authenticate_header": true,
  • "disable_password_auth": false,
  • "bucket_op_timeout_ms": 0,
  • "slow_query_warning_threshold": 500,
  • "delta_sync": {
    },
  • "compact_interval_days": 1,
  • "sgreplicate_enabled": true,
  • "sgreplicate_websocket_heartbeat_secs": 300,
  • "replications": {
    },
  • "serve_insecure_attachment_types": false,
  • "query_pagination_limit": 5000,
  • "user_xattr_key": "string",
  • "client_partition_window_secs": 2592000,
  • "guest": {
    },
  • "javascript_timeout_secs": 60,
  • "suspendable": false,
  • "cors": {
    },
  • "logging": {
    }
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "reason": "string"
}

Get database audit configuration

Retrieve the audit configuration for the database specified.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

Retrieve the audit configuration for the database specified.

Required Sync Gateway RBAC roles:

  • Sync Gateway Architect
-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
query Parameters
verbose
boolean
Default: false

Whether to show name and description with each audit event.

-
filterable
boolean
Default: false

Whether to show only filterable audit events.

-

Responses

Response samples

Content type
application/json
Example
{
  • "enabled": true,
  • "events": {
    },
  • "disabled_users": [
    ],
  • "disabled_roles": [
    ]
}

Replace database audit configuration

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
query Parameters
verbose
boolean
Default: false

Whether to show name and description with each audit event.

+
filterable
boolean
Default: false

Whether to show only filterable audit events.

+

Responses

Response samples

Content type
application/json
Example
{
  • "enabled": true,
  • "events": {
    },
  • "disabled_users": [
    ],
  • "disabled_roles": [
    ]
}

Replace database audit configuration

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Architect
-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
Request Body schema: application/json

The new database audit configuration to use

-
One of
enabled
boolean
object
Array of objects

List of users for which audit logging is disabled.

-
Array of objects

List of roles for which audit logging is disabled. Either cbs or sgw.

-

Responses

Request samples

Content type
application/json
Example
{
  • "enabled": true,
  • "events": {
    },
  • "disabled_users": [
    ],
  • "disabled_roles": [
    ]
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "reason": "string"
}

Update database audit configuration

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
Request Body schema: application/json

The new database audit configuration to use

+
One of
enabled
boolean
object
Array of objects

List of users for which audit logging is disabled.

+
Array of objects

List of roles for which audit logging is disabled. Either cbs or sgw.

+

Responses

Request samples

Content type
application/json
Example
{
  • "enabled": true,
  • "events": {
    },
  • "disabled_users": [
    ],
  • "disabled_roles": [
    ]
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "reason": "string"
}

Update database audit configuration

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Architect
-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
query Parameters
verbose
boolean
Default: false

Whether to show name and description with each audit event.

-
Request Body schema: application/json

The database configuration fields to update

-
One of
enabled
boolean
object
Array of objects

List of users for which audit logging is disabled.

-
Array of objects

List of roles for which audit logging is disabled. Either cbs or sgw.

-

Responses

Request samples

Content type
application/json
Example
{
  • "enabled": true,
  • "events": {
    },
  • "disabled_users": [
    ],
  • "disabled_roles": [
    ]
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "reason": "string"
}

Get database sync function

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
query Parameters
verbose
boolean
Default: false

Whether to show name and description with each audit event.

+
Request Body schema: application/json

The database configuration fields to update

+
One of
enabled
boolean
object
Array of objects

List of users for which audit logging is disabled.

+
Array of objects

List of roles for which audit logging is disabled. Either cbs or sgw.

+

Responses

Request samples

Content type
application/json
Example
{
  • "enabled": true,
  • "events": {
    },
  • "disabled_users": [
    ],
  • "disabled_roles": [
    ]
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "reason": "string"
}

Get database sync function

This returns the database's sync function.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

This returns the database's sync function.

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Architect
-
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection

The keyspace to run the operation against.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

The keyspace to run the operation against.

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

-

Responses

Response samples

Content type
application/javascript
function (doc, oldDoc) {
+

Responses

Response samples

Content type
application/javascript
function (doc, oldDoc) {
   channel(doc.channels);
-}

Set database sync function

}

Set database sync function

This will allow you to update the sync function.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

This will allow you to update the sync function.

Required Sync Gateway RBAC roles:

  • Sync Gateway Architect
-
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection

The keyspace to run the operation against.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

The keyspace to run the operation against.

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

-
query Parameters
disable_oidc_validation
boolean
Default: false

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

-
header Parameters
If-Match
string

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

-
Request Body schema: application/javascript

The new sync function to use

-
string

Responses

Request samples

Content type
application/javascript
function (doc, oldDoc) {
+

Request samples

Content type
application/javascript
function (doc, oldDoc) {
   channel(doc.channels);
-}

Response samples

Content type
application/json
{
  • "error": "string",
  • "reason": "string"
}

Remove custom sync function

}

Response samples

Content type
application/json
{
  • "error": "string",
  • "reason": "string"
}

Remove custom sync function

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

The default sync function is equivalent to:

function (doc) {
   channel(doc.channels);
@@ -2075,885 +2097,885 @@
 
    
 
  • Sync Gateway Architect
    • 
 

-
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection

The keyspace to run the operation against.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

The keyspace to run the operation against.

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

-
header Parameters
If-Match
string

The revision ID to target.

-

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Get database import filter

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Get database import filter

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Architect
-
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection

The keyspace to run the operation against.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

The keyspace to run the operation against.

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

-

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Set database import filter

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Set database import filter

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Architect
-
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection

The keyspace to run the operation against.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

The keyspace to run the operation against.

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

-
query Parameters
disable_oidc_validation
boolean
Default: false

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

-
header Parameters
If-Match
string

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

-
Request Body schema: application/javascript

The import filter to use

-
string

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "reason": "string"
}

Delete import filter

Response samples

Content type
application/json
{
  • "error": "string",
  • "reason": "string"
}

Delete import filter

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Architect
-
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection

The keyspace to run the operation against.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

The keyspace to run the operation against.

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

-
header Parameters
If-Match
string

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

-

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Database Security

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Database Security

Create and manage database users and roles

-

Get all the names of the users

Get all the names of the users

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Architect
  • Sync Gateway Application
  • Sync Gateway Application Read Only
-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
query Parameters
name_only
boolean
Default: true

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

-
limit
integer

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

-

Responses

Response samples

Content type
application/json
[
  • "Alice",
  • "Bob"
]

Create a new user

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
query Parameters
name_only
boolean
Default: true

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

+
limit
integer

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

+

Responses

Response samples

Content type
application/json
[
  • "Alice",
  • "Bob"
]

Create a new user

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Architect
  • Sync Gateway Application
-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
Request Body schema: application/json

Properties associated with a user

-
name
string
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
Request Body schema: application/json

Properties associated with a user

+
name
string

The name of the user.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

The name of the user.

User names can only have alphanumeric ASCII characters and underscores.

-
password
string
password
string

The password of the user.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

The password of the user.

Mandatory. unless allow_empty_password is true in the database configs.

-
admin_channels
Array of strings

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

-
object

A set of access grants by scope and collection.

-
email
string

The email address of the user.

-
disabled
boolean

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

-
admin_roles
Array of strings

A list of roles to explicitly grant to the user.

-

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "password": "string",
  • "admin_channels": [
    ],
  • "collection_access": {
    },
  • "email": "string",
  • "disabled": true,
  • "admin_roles": [
    ]
}

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

/{db}/_user/

admin_channels
Array of strings

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

+
object

A set of access grants by scope and collection.

+
email
string

The email address of the user.

+
disabled
boolean

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

+
admin_roles
Array of strings

A list of roles to explicitly grant to the user.

+

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "password": "string",
  • "admin_channels": [
    ],
  • "collection_access": {
    },
  • "email": "string",
  • "disabled": true,
  • "admin_roles": [
    ]
}

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

/{db}/_user/

Required Sync Gateway RBAC roles:

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

Required Sync Gateway RBAC roles:

  • Sync Gateway Architect
  • Sync Gateway Application
  • Sync Gateway Application Read Only
-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Get a user

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Get a user

Retrieve a single users information.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

Retrieve a single users information.

Required Sync Gateway RBAC roles:

  • Sync Gateway Architect
  • Sync Gateway Application
  • Sync Gateway Application Read Only
-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
name
required
string

The name of the user.

-

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "password": "string",
  • "admin_channels": [
    ],
  • "all_channels": [
    ],
  • "collection_access": {
    },
  • "email": "string",
  • "disabled": true,
  • "admin_roles": [
    ],
  • "roles": [
    ],
  • "jwt_roles": [
    ],
  • "jwt_channels": [
    ],
  • "jwt_issuer": "string",
  • "jwt_last_updated": "2019-08-24T14:15:22Z"
}

Upsert a user

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
name
required
string

The name of the user.

+

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "password": "string",
  • "admin_channels": [
    ],
  • "all_channels": [
    ],
  • "collection_access": {
    },
  • "email": "string",
  • "disabled": true,
  • "admin_roles": [
    ],
  • "roles": [
    ],
  • "jwt_roles": [
    ],
  • "jwt_channels": [
    ],
  • "jwt_issuer": "string",
  • "jwt_last_updated": "2019-08-24T14:15:22Z"
}

Upsert a user

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Architect
  • Sync Gateway Application
-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
name
required
string

The name of the user.

-
Request Body schema: application/json

Properties associated with a user

-
name
string
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
name
required
string

The name of the user.

+
Request Body schema: application/json

Properties associated with a user

+
name
string

The name of the user.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

The name of the user.

User names can only have alphanumeric ASCII characters and underscores.

-
password
string
password
string

The password of the user.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

The password of the user.

Mandatory. unless allow_empty_password is true in the database configs.

-
admin_channels
Array of strings

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

-
object

A set of access grants by scope and collection.

-
email
string

The email address of the user.

-
disabled
boolean

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

-
admin_roles
Array of strings

A list of roles to explicitly grant to the user.

-

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "password": "string",
  • "admin_channels": [
    ],
  • "collection_access": {
    },
  • "email": "string",
  • "disabled": true,
  • "admin_roles": [
    ]
}

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Delete a user

admin_channels
Array of strings

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

+
object

A set of access grants by scope and collection.

+
email
string

The email address of the user.

+
disabled
boolean

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

+
admin_roles
Array of strings

A list of roles to explicitly grant to the user.

+

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "password": "string",
  • "admin_channels": [
    ],
  • "collection_access": {
    },
  • "email": "string",
  • "disabled": true,
  • "admin_roles": [
    ]
}

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Delete a user

Delete a user from the database.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

Delete a user from the database.

Required Sync Gateway RBAC roles:

  • Sync Gateway Architect
  • Sync Gateway Application
-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
name
required
string

The name of the user.

-

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Check if user exists

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
name
required
string

The name of the user.

+

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Check if user exists

Check if the user exists by checking the status code.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

Check if the user exists by checking the status code.

Required Sync Gateway RBAC roles:

  • Sync Gateway Architect
  • Sync Gateway Application
  • Sync Gateway Application Read Only
-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
name
required
string

The name of the user.

-

Responses

Get all names of the roles

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
name
required
string

The name of the user.

+

Responses

Get all names of the roles

Retrieves all the roles that are in the database.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

Retrieves all the roles that are in the database.

Required Sync Gateway RBAC roles:

  • Sync Gateway Architect
  • Sync Gateway Application
  • Sync Gateway Application Read Only
-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
query Parameters
deleted
boolean
Default: false
Enum: true false

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

-

Responses

Response samples

Content type
application/json
[
  • "Administrator",
  • "Moderator"
]

Create a new role

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
query Parameters
deleted
boolean
Default: false
Enum: true false

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

+

Responses

Response samples

Content type
application/json
[
  • "Administrator",
  • "Moderator"
]

Create a new role

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Architect
  • Sync Gateway Application
-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
Request Body schema: application/json

Properties associated with a role

-
name
string
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
Request Body schema: application/json

Properties associated with a role

+
name
string

The name of the role.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

The name of the role.

Role names can only have alphanumeric ASCII characters and underscores.

-
admin_channels
Array of strings

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

-
object

A set of access grants by scope and collection.

-

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "admin_channels": [
    ],
  • "collection_access": {
    }
}

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

/{db}/_role/

admin_channels
Array of strings

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

+
object

A set of access grants by scope and collection.

+

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "admin_channels": [
    ],
  • "collection_access": {
    }
}

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

/{db}/_role/

Required Sync Gateway RBAC roles:

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

Required Sync Gateway RBAC roles:

  • Sync Gateway Architect
  • Sync Gateway Application
  • Sync Gateway Application Read Only
-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Get a role

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Get a role

Retrieve a single roles properties.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

Retrieve a single roles properties.

Required Sync Gateway RBAC roles:

  • Sync Gateway Architect
  • Sync Gateway Application
  • Sync Gateway Application Read Only
-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
name
required
string

The name of the role.

-

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "admin_channels": [
    ],
  • "all_channels": [
    ],
  • "collection_access": {
    }
}

Upsert a role

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
name
required
string

The name of the role.

+

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "admin_channels": [
    ],
  • "all_channels": [
    ],
  • "collection_access": {
    }
}

Upsert a role

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Architect
  • Sync Gateway Application
-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
name
required
string

The name of the role.

-
Request Body schema: application/json

Properties associated with a role

-
name
string
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
name
required
string

The name of the role.

+
Request Body schema: application/json

Properties associated with a role

+
name
string

The name of the role.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

The name of the role.

Role names can only have alphanumeric ASCII characters and underscores.

-
admin_channels
Array of strings

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

-
object

A set of access grants by scope and collection.

-

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "admin_channels": [
    ],
  • "collection_access": {
    }
}

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Delete a role

admin_channels
Array of strings

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

+
object

A set of access grants by scope and collection.

+

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "admin_channels": [
    ],
  • "collection_access": {
    }
}

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Delete a role

Delete a role from the database.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

Delete a role from the database.

Required Sync Gateway RBAC roles:

  • Sync Gateway Architect
  • Sync Gateway Application
-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
name
required
string

The name of the role.

-

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Check if role exists

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
name
required
string

The name of the role.

+

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Check if role exists

Check if the role exists by checking the status code.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

Check if the role exists by checking the status code.

Required Sync Gateway RBAC roles:

  • Sync Gateway Architect
  • Sync Gateway Application
  • Sync Gateway Application Read Only
-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
name
required
string

The name of the role.

-

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Session

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
name
required
string

The name of the role.

+

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Session

Manage user sessions

-

Get information about the current user

This will get the information about the current user.

-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-

Responses

Response samples

Content type
application/json
{
  • "authentication_handlers": [
    ],
  • "ok": true,
  • "userCtx": {
    }
}

Create a new user session

Get information about the current user

This will get the information about the current user.

+
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+

Responses

Response samples

Content type
application/json
{
  • "authentication_handlers": [
    ],
  • "ok": true,
  • "userCtx": {
    }
}

Create a new user session

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Architect
  • Sync Gateway Application
-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
Request Body schema: application/json

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

-
name
string

User name to generate the session for.

-
ttl
integer

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

-

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "ttl": 0
}

Response samples

Content type
application/json
{
  • "session_id": "c5af80a039db4ed9d2b6865576b6999935282689",
  • "expires": "2022-01-21T15:24:44Z",
  • "cookie_name": "SyncGatewaySession"
}

/{db}/_session

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Get session information

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
Request Body schema: application/json

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

+
name
string

User name to generate the session for.

+
ttl
integer

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

+

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "ttl": 0
}

Response samples

Content type
application/json
{
  • "session_id": "c5af80a039db4ed9d2b6865576b6999935282689",
  • "expires": "2022-01-21T15:24:44Z",
  • "cookie_name": "SyncGatewaySession"
}

/{db}/_session

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Get session information

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Architect
  • Sync Gateway Application
  • Sync Gateway Application Read Only
-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
sessionid
required
string

The ID of the session to target.

-

Responses

Response samples

Content type
application/json
{
  • "authentication_handlers": [
    ],
  • "ok": true,
  • "userCtx": {
    }
}

Remove session

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
sessionid
required
string

The ID of the session to target.

+

Responses

Response samples

Content type
application/json
{
  • "authentication_handlers": [
    ],
  • "ok": true,
  • "userCtx": {
    }
}

Remove session

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Architect
  • Sync Gateway Application
-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
sessionid
required
string

The ID of the session to target.

-

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Remove all of a users sessions

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
sessionid
required
string

The ID of the session to target.

+

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Remove all of a users sessions

Invalidates all the sessions that a user has.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

Invalidates all the sessions that a user has.

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Architect
  • Sync Gateway Application
-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
name
required
string

The name of the user.

-

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Remove session with user validation

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
name
required
string

The name of the user.

+

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Remove session with user validation

Invalidates the session only if it belongs to the user.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

Invalidates the session only if it belongs to the user.

Required Sync Gateway RBAC roles:

  • Sync Gateway Architect
  • Sync Gateway Application
-
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

-
name
required
string

The name of the user.

-
sessionid
required
string

The ID of the session to target.

-

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

OpenID Connect

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

+
name
required
string

The name of the user.

+
sessionid
required
string

The ID of the session to target.

+

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

OpenID Connect

Manage OpenID Connect

-

Document

Document

Create and manage documents and attachments

-

Get a document with the corresponding metadata

Get a document with the corresponding metadata

Returns the a documents latest revision with its metadata.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

Returns the a documents latest revision with its metadata.

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Application
  • Sync Gateway Application Read Only
-
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection

The keyspace to run the operation against.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

The keyspace to run the operation against.

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

-
docid
required
string
Example: doc1

The document ID to run the operation against.

-
query Parameters
include_doc
string

Include the body associated with the document.

-
redact
boolean

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

-

Responses

Response samples

Content type
application/json
{
  • "_sync": {
    }
}

/{keyspace}/_raw/{docid}

docid
required
string
Example: doc1

The document ID to run the operation against.

+
query Parameters
include_doc
string

Include the body associated with the document.

+
redact
boolean

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

+

Responses

Response samples

Content type
application/json
{
  • "_sync": {
    }
}

/{keyspace}/_raw/{docid}

Required Sync Gateway RBAC roles:

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

Required Sync Gateway RBAC roles:

  • Sync Gateway Application
  • Sync Gateway Application Read Only
-
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection

The keyspace to run the operation against.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

The keyspace to run the operation against.

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

-
docid
required
string
Example: doc1

The document ID to run the operation against.

-

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "reason": "string"
}

Purge a document

docid
required
string
Example: doc1

The document ID to run the operation against.

+

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "reason": "string"
}

Purge a document

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Application
-
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection

The keyspace to run the operation against.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

The keyspace to run the operation against.

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

-
Request Body schema: application/json

Purge request body

-
doc_id
Array of strings
Items Value: "*"
Request Body schema: application/json

Purge request body

+
doc_id
Array of strings
Items Value: "*"

The document ID to purge. The array must only be 1 element which is *.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

The document ID to purge. The array must only be 1 element which is *.

All revisions will be permanently removed for that document.

-
property name*
additional property
Array of strings
Items Value: "*"

Responses

Request samples

Content type
application/json
Example
{
  • "doc_id": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "purged": {
    }
}

Create a new document

property name*
additional property
Array of strings
Items Value: "*"

Responses

Request samples

Content type
application/json
Example
{
  • "doc_id": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "purged": {
    }
}

Create a new document

Create a new document in the keyspace.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

Create a new document in the keyspace.

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

A document can have a maximum size of 20MB.

-
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection

The keyspace to run the operation against.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

The keyspace to run the operation against.

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

-
query Parameters
roundtrip
boolean

Block until document has been received by change cache

-
Request Body schema: application/json
_id
string

The ID of the document.

-
_rev
string

The revision of the document.

-
_exp
string
query Parameters
roundtrip
boolean

Block until document has been received by change cache

+
Request Body schema: application/json
_id
string

The ID of the document.

+
_rev
string

The revision of the document.

+
_exp
string

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

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

-
_deleted
boolean

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

-
object
object
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "_id": "string",
  • "_rev": "string",
  • "_exp": "string",
  • "_deleted": true,
  • "_revisions": {
    },
  • "_attachments": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "ok": true,
  • "rev": "string"
}

Gets all the documents in the database with the given parameters

_deleted
boolean

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

+
object
object
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "_id": "string",
  • "_rev": "string",
  • "_exp": "string",
  • "_deleted": true,
  • "_revisions": {
    },
  • "_attachments": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "ok": true,
  • "rev": "string"
}

Gets all the documents in the database with the given parameters

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Application
  • Sync Gateway Application Read Only
-
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection

The keyspace to run the operation against.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

The keyspace to run the operation against.

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

-
query Parameters
include_docs
boolean

Include the body associated with each document.

-
channels
boolean

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

-
access
boolean

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

-
revs
boolean

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

-
update_seq
boolean

Include the document sequence number update_seq property for each document.

-
keys
Array of strings

An array of document ID strings to filter by.

-
startkey
string

Return records starting with the specified key.

-
endkey
string

Stop returning records when this key is reached.

-
limit
number

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

-

Responses

Response samples

Content type
application/json
{
  • "rows": [
    ],
  • "total_rows": 0,
  • "update_seq": 0
}

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

query Parameters
include_docs
boolean

Include the body associated with each document.

+
channels
boolean

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

+
access
boolean

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

+
revs
boolean

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

+
update_seq
boolean

Include the document sequence number update_seq property for each document.

+
keys
Array of strings

An array of document ID strings to filter by.

+
startkey
string

Return records starting with the specified key.

+
endkey
string

Stop returning records when this key is reached.

+
limit
number

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

+

Responses

Response samples

Content type
application/json
{
  • "rows": [
    ],
  • "total_rows": 0,
  • "update_seq": 0
}

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

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

Required Sync Gateway RBAC roles:

  • Sync Gateway Application
  • Sync Gateway Application Read Only
-
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection

The keyspace to run the operation against.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

The keyspace to run the operation against.

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

-
query Parameters
include_docs
boolean

Include the body associated with each document.

-
channels
boolean

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

-
access
boolean

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

-
revs
boolean

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

-
update_seq
boolean

Include the document sequence number update_seq property for each document.

-
startkey
string

Return records starting with the specified key.

-
endkey
string

Stop returning records when this key is reached.

-
limit
number

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

-
Request Body schema: application/json
keys
required
Array of strings

List of the documents to retrieve.

-

Responses

Request samples

Content type
application/json
{
  • "keys": [
    ]
}

Response samples

Content type
application/json
{
  • "rows": [
    ],
  • "total_rows": 0,
  • "update_seq": 0
}

/{db}/_all_docs

query Parameters
include_docs
boolean

Include the body associated with each document.

+
channels
boolean

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

+
access
boolean

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

+
revs
boolean

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

+
update_seq
boolean

Include the document sequence number update_seq property for each document.

+
startkey
string

Return records starting with the specified key.

+
endkey
string

Stop returning records when this key is reached.

+
limit
number

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

+
Request Body schema: application/json
keys
required
Array of strings

List of the documents to retrieve.

+

Responses

Request samples

Content type
application/json
{
  • "keys": [
    ]
}

Response samples

Content type
application/json
{
  • "rows": [
    ],
  • "total_rows": 0,
  • "update_seq": 0
}

/{db}/_all_docs

Required Sync Gateway RBAC roles:

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

Required Sync Gateway RBAC roles:

  • Sync Gateway Application
  • Sync Gateway Application Read Only
-
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection

The keyspace to run the operation against.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

The keyspace to run the operation against.

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

-
query Parameters
include_docs
boolean

Include the body associated with each document.

-
channels
boolean

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

-
access
boolean

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

-
revs
boolean

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

-
update_seq
boolean

Include the document sequence number update_seq property for each document.

-
keys
Array of strings

An array of document ID strings to filter by.

-
startkey
string

Return records starting with the specified key.

-
endkey
string

Stop returning records when this key is reached.

-
limit
number

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

-

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "reason": "string"
}

Bulk document operations

query Parameters
include_docs
boolean

Include the body associated with each document.

+
channels
boolean

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

+
access
boolean

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

+
revs
boolean

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

+
update_seq
boolean

Include the document sequence number update_seq property for each document.

+
keys
Array of strings

An array of document ID strings to filter by.

+
startkey
string

Return records starting with the specified key.

+
endkey
string

Stop returning records when this key is reached.

+
limit
number

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

+

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "reason": "string"
}

Bulk document operations

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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.

@@ -2969,23 +2991,23 @@
  • Sync Gateway Application
-
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection
path Parameters
keyspace
required
string
Examples:
  • db1 - Default scope and collection
  • db1.collection1 - Named collection within the default scope
  • db1.scope1.collection1 - Fully-qualified scope and collection

The keyspace to run the operation against.

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

The keyspace to run the operation against.

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

-
Request Body schema: application/json
new_edits
boolean
Default: true

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

-
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "new_edits": true,
  • "docs": [
    ]
}

Response samples

Content type
application/json
Example
[
  • {
    },
  • {
    },
  • {
    }
]

Get multiple documents in a MIME multipart response

400

There was a problem with your request

+

Request samples

Content type
application/json
{
  • "new_edits": true,
  • "docs": [
    ]
}

Response samples

Content type
application/json
Example
[
  • {
    },
  • {
    },
  • {
    }
]

Get multiple documents in a MIME multipart response

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

+" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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.

@@ -3003,193 +3025,193 @@
  • Sync Gateway Application
  • Sync Gateway Application Read Only
    • -
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

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

    -
    query Parameters
    attachments
    boolean
    Default: "false"

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

    -
    revs
    boolean

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

    -
    revs_limit
    integer

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

    -
    header Parameters
    X-Accept-Part-Encoding
    string

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

    -
    Accept-Encoding
    string

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

    -
    Request Body schema: application/json
    required
    Array of objects

    Responses

    Request samples

    Content type
    application/json
    {
    • "docs": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Get local document

    query Parameters
    attachments
    boolean
    Default: "false"

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

    +
    revs
    boolean

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

    +
    revs_limit
    integer

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

    +
    header Parameters
    X-Accept-Part-Encoding
    string

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

    +
    Accept-Encoding
    string

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

    +
    Request Body schema: application/json
    required
    Array of objects

    Responses

    Request samples

    Content type
    application/json
    {
    • "docs": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Get local document

    This request retrieves a local document.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    This request retrieves a local document.

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

    Required Sync Gateway RBAC roles:

    • Sync Gateway Application
    • Sync Gateway Application Read Only
    -
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

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

    -
    docid
    required
    string

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

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    Upsert a local document

    		docid
    required
    string

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

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    Upsert a local document

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

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

    Required Sync Gateway RBAC roles:

    • Sync Gateway Application
    -
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

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

    -
    docid
    required
    string

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

    -
    Request Body schema: application/json

    The body of the document

    -
    _rev
    string

    Revision to replace. Required if updating existing local document.

    -

    Responses

    Request samples

    Content type
    application/json
    {
    • "_rev": "2-5145e1086bb8d1d71a531e9f6b543c58"
    }

    Response samples

    Content type
    application/json
    {
    • "id": "string",
    • "ok": true,
    • "rev": "string"
    }

    Delete a local document

    		docid
    required
    string

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

    +
    Request Body schema: application/json

    The body of the document

    +
    _rev
    string

    Revision to replace. Required if updating existing local document.

    +

    Responses

    Request samples

    Content type
    application/json
    {
    • "_rev": "2-5145e1086bb8d1d71a531e9f6b543c58"
    }

    Response samples

    Content type
    application/json
    {
    • "id": "string",
    • "ok": true,
    • "rev": "string"
    }

    Delete a local document

    This request deletes a local document.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    This request deletes a local document.

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

    Required Sync Gateway RBAC roles:

    • Sync Gateway Application
    -
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

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

    -
    docid
    required
    string

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

    -
    query Parameters
    rev
    required
    string

    The revision ID of the revision to delete.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    Check if local document exists

    		docid
    required
    string

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

    +
    query Parameters
    rev
    required
    string

    The revision ID of the revision to delete.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    Check if local document exists

    This request checks if a local document exists.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    This request checks if a local document exists.

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

    Required Sync Gateway RBAC roles:

    • Sync Gateway Application
    • Sync Gateway Application Read Only
    -
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

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

    -
    docid
    required
    string

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

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    Get a document

    		docid
    required
    string

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

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    Get a document

    Retrieve a document from the database by its doc ID.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    Retrieve a document from the database by its doc ID.

    Required Sync Gateway RBAC roles:

    • Sync Gateway Application
    • Sync Gateway Application Read Only
    -
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

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

    -
    docid
    required
    string
    Example: doc1

    The document ID to run the operation against.

    -
    query Parameters
    rev
    string
    Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58

    The document revision to target.

    -
    open_revs
    Array of strings

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

    -
    show_exp
    boolean

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

    -
    revs_from
    Array of strings

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

    -
    atts_since
    Array of strings

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

    -
    revs_limit
    integer

    Maximum amount of revisions to return for each document.

    -
    attachments
    boolean

    Include attachment bodies in response.

    -
    replicator2
    boolean

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

    -

    Responses

    		docid
    required
    string
    Example: doc1

    The document ID to run the operation against.

    +
    query Parameters
    rev
    string
    Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58

    The document revision to target.

    +
    open_revs
    Array of strings

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

    +
    show_exp
    boolean

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

    +
    revs_from
    Array of strings

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

    +
    atts_since
    Array of strings

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

    +
    revs_limit
    integer

    Maximum amount of revisions to return for each document.

    +
    attachments
    boolean

    Include attachment bodies in response.

    +
    replicator2
    boolean

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

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "FailedLoginAttempts": 5,
    • "Friends": [
      ],
    • "_id": "AliceSettings",
    • "_rev": "1-64d4a1f179db5c1848fe52967b47c166"
    }

    Upsert a document

    404

    Resource could not be found

    +

    Response samples

    Content type
    application/json
    {
    • "FailedLoginAttempts": 5,
    • "Friends": [
      ],
    • "_id": "AliceSettings",
    • "_rev": "1-64d4a1f179db5c1848fe52967b47c166"
    }

    Upsert a document

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    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.

    @@ -3205,119 +3227,119 @@
    • Sync Gateway Application
    -
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

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

    -
    docid
    required
    string
    Example: doc1

    The document ID to run the operation against.

    -
    query Parameters
    roundtrip
    boolean

    Block until document has been received by change cache

    -
    replicator2
    boolean

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

    -
    new_edits
    boolean
    Default: "true"

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

    -
    rev
    string
    Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58

    The document revision to target.

    -
    header Parameters
    If-Match
    string

    The revision ID to target.

    -
    Request Body schema: application/json
    _id
    string

    The ID of the document.

    -
    _rev
    string

    The revision of the document.

    -
    _exp
    string
    		docid
    required
    string
    Example: doc1

    The document ID to run the operation against.

    +
    query Parameters
    roundtrip
    boolean

    Block until document has been received by change cache

    +
    replicator2
    boolean

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

    +
    new_edits
    boolean
    Default: "true"

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

    +
    rev
    string
    Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58

    The document revision to target.

    +
    header Parameters
    If-Match
    string

    The revision ID to target.

    +
    Request Body schema: application/json
    _id
    string

    The ID of the document.

    +
    _rev
    string

    The revision of the document.

    +
    _exp
    string

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

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

    -
    _deleted
    boolean

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

    -
    object
    object
    property name*
    additional property
    any

    Responses

    Request samples

    Content type
    application/json
    {
    • "_id": "string",
    • "_rev": "string",
    • "_exp": "string",
    • "_deleted": true,
    • "_revisions": {
      },
    • "_attachments": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "string",
    • "ok": true,
    • "rev": "string"
    }

    Delete a document

    		_deleted
    boolean

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

    +
    object
    object
    property name*
    additional property
    any

    Responses

    Request samples

    Content type
    application/json
    {
    • "_id": "string",
    • "_rev": "string",
    • "_exp": "string",
    • "_deleted": true,
    • "_revisions": {
      },
    • "_attachments": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "string",
    • "ok": true,
    • "rev": "string"
    }

    Delete a document

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

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

    Required Sync Gateway RBAC roles:

    • Sync Gateway Application
    -
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

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

    -
    docid
    required
    string
    Example: doc1

    The document ID to run the operation against.

    -
    query Parameters
    rev
    string
    Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58

    The document revision to target.

    -
    header Parameters
    If-Match
    string

    The revision ID to target.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": "string",
    • "ok": true,
    • "rev": "string"
    }

    Check if a document exists

    		docid
    required
    string
    Example: doc1

    The document ID to run the operation against.

    +
    query Parameters
    rev
    string
    Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58

    The document revision to target.

    +
    header Parameters
    If-Match
    string

    The revision ID to target.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": "string",
    • "ok": true,
    • "rev": "string"
    }

    Check if a document exists

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

    Required Sync Gateway RBAC roles:

    • Sync Gateway Application
    • Sync Gateway Application Read Only
    -
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

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

    -
    docid
    required
    string
    Example: doc1

    The document ID to run the operation against.

    -
    query Parameters
    rev
    string
    Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58

    The document revision to target.

    -
    open_revs
    Array of strings

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

    -
    show_exp
    boolean

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

    -
    revs_from
    Array of strings

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

    -
    atts_since
    Array of strings

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

    -
    revs_limit
    integer

    Maximum amount of revisions to return for each document.

    -
    attachments
    boolean

    Include attachment bodies in response.

    -
    replicator2
    boolean

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

    -

    Responses

    		docid
    required
    string
    Example: doc1

    The document ID to run the operation against.

    +
    query Parameters
    rev
    string
    Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58

    The document revision to target.

    +
    open_revs
    Array of strings

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

    +
    show_exp
    boolean

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

    +
    revs_from
    Array of strings

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

    +
    atts_since
    Array of strings

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

    +
    revs_limit
    integer

    Maximum amount of revisions to return for each document.

    +
    attachments
    boolean

    Include attachment bodies in response.

    +
    replicator2
    boolean

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

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    Get an attachment from a document

    404

    Resource could not be found

    +

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    Get an attachment from a document

    This request retrieves a file attachment associated with the document.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    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:

    @@ -3333,169 +3355,169 @@
  • Sync Gateway Application
  • Sync Gateway Application Read Only
    • -
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

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

    -
    docid
    required
    string
    Example: doc1

    The document ID to run the operation against.

    -
    attach
    required
    string

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

    -
    query Parameters
    rev
    string
    Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58

    The document revision to target.

    -
    content_encoding
    boolean
    Default: "true"

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

    -
    meta
    boolean
    Default: "false"

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

    -
    header Parameters
    Range
    string
    Example: bytes=123-456

    RFC-2616 bytes range header.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Create or update an attachment on a document

    		docid
    required
    string
    Example: doc1

    The document ID to run the operation against.

    +
    attach
    required
    string

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

    +
    query Parameters
    rev
    string
    Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58

    The document revision to target.

    +
    content_encoding
    boolean
    Default: "true"

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

    +
    meta
    boolean
    Default: "false"

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

    +
    header Parameters
    Range
    string
    Example: bytes=123-456

    RFC-2616 bytes range header.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Create or update an attachment on a document

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

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

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

    Required Sync Gateway RBAC roles:

    • Sync Gateway Application
    -
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

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

    -
    docid
    required
    string
    Example: doc1

    The document ID to run the operation against.

    -
    attach
    required
    string

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

    -
    query Parameters
    rev
    string

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

    -
    header Parameters
    Content-Type
    string
    Default: application/octet-stream

    The content type of the attachment.

    -
    If-Match
    string

    An alternative way of specifying the document revision ID.

    -
    Request Body schema: Attachment content type

    The attachment data

    -
    string

    The content to store in the body

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": "string",
    • "ok": true,
    • "rev": "string"
    }

    Check if attachment exists

    		docid
    required
    string
    Example: doc1

    The document ID to run the operation against.

    +
    attach
    required
    string

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

    +
    query Parameters
    rev
    string

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

    +
    header Parameters
    Content-Type
    string
    Default: application/octet-stream

    The content type of the attachment.

    +
    If-Match
    string

    An alternative way of specifying the document revision ID.

    +
    Request Body schema: Attachment content type

    The attachment data

    +
    string

    The content to store in the body

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": "string",
    • "ok": true,
    • "rev": "string"
    }

    Check if attachment exists

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

    Required Sync Gateway RBAC roles:

    • Sync Gateway Application
    • Sync Gateway Application Read Only
    -
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

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

    -
    docid
    required
    string
    Example: doc1

    The document ID to run the operation against.

    -
    attach
    required
    string

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

    -
    query Parameters
    rev
    string
    Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58

    The document revision to target.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Delete an attachment on a document

    		docid
    required
    string
    Example: doc1

    The document ID to run the operation against.

    +
    attach
    required
    string

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

    +
    query Parameters
    rev
    string
    Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58

    The document revision to target.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Delete an attachment on a document

    This request deletes an attachment associated with the document.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    This request deletes an attachment associated with the document.

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

    -
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

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

    -
    docid
    required
    string
    Example: doc1

    The document ID to run the operation against.

    -
    attach
    required
    string

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

    -
    query Parameters
    rev
    string

    The existing document revision ID to modify.

    -
    header Parameters
    If-Match
    string

    An alternative way of specifying the document revision ID.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": "string",
    • "ok": true,
    • "rev": "string"
    }

    Replication

    		docid
    required
    string
    Example: doc1

    The document ID to run the operation against.

    +
    attach
    required
    string

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

    +
    query Parameters
    rev
    string

    The existing document revision ID to modify.

    +
    header Parameters
    If-Match
    string

    An alternative way of specifying the document revision ID.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": "string",
    • "ok": true,
    • "rev": "string"
    }

    Replication

    Create and manage inter-Sync Gateway replications

    -

    Get all replication configurations

    Get all replication configurations

    This will retrieve all database replication definitions.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    This will retrieve all database replication definitions.

    Required Sync Gateway RBAC roles:

    • Sync Gateway Replicator
    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "replication_id": {
      }
    }

    Upsert a replication

    404

    Resource could not be found

    +

    Response samples

    Content type
    application/json
    {
    • "replication_id": {
      }
    }

    Upsert a replication

    Create or update a replication in the database.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    Create or update a replication in the database.

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

    Required Sync Gateway RBAC roles:

    • Sync Gateway Replicator
    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -
    Request Body schema: application/json

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

    -
    replication_id
    string
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +
    Request Body schema: application/json

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

    +
    replication_id
    string

    This is the ID of the replication.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    This is the ID of the replication.

    When creating a new replication using a POST request, this will be set to a random UUID if not explicitly set.

    When the replication ID is specified in the URL, this must be set to the same replication ID if specifying it at all.

    -
    remote
    string
    		remote
    string

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    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:

      @@ -3511,31 +3533,31 @@
    • push - this replicator pushes changes to this remote
    • pushAndPull - this replicator pushes changes to this remote, while also pulling receiving changes
    -
    username
    string
    Deprecated
    		username
    string
    Deprecated

    This has been deprecated in favour of remote_username.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    This has been deprecated in favour of remote_username.

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

    This can only be used for a pull replication.

    -
    password
    string
    Deprecated
    		password
    string
    Deprecated

    This has been deprecated in favour of remote_password.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    This has been deprecated in favour of remote_password.

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

    This password will be redacted in the replication config.

    This can only be used for a pull replication.

    -
    remote_username
    string
    		remote_username
    string

    The username to use to authenticate with the remote.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The username to use to authenticate with the remote.

    This can only be used for a pull replication.

    -
    remote_password
    string
    		remote_password
    string

    The password to use to authenticate with the remote.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The password to use to authenticate with the remote.

    This password will be redacted in the replication config.

    This can only be used for a pull replication.

    -
    direction
    required
    string
    Enum: "push" "pull" "pushAndPull"
    		direction
    required
    string
    Enum: "push" "pull" "pushAndPull"

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

    The directions are:

    • pull - changes are pulled from the remote database
      • @@ -3551,7 +3573,7 @@
    • pushAndPull - changes are both push-to and pulled-from the remote database

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

    -
    conflict_resolution_type
    string
    Default: "default"
    Enum: "default" "remoteWins" "localWins" "custom"
    		conflict_resolution_type
    string
    Default: "default"
    Enum: "default" "remoteWins" "localWins" "custom"

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    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

      @@ -3579,7 +3601,7 @@
    • custom - This will result in conflicts going through your own custom conflict resolver. You must provide this logic as a Javascript function in the custom_conflict_resolver parameter. This is an Enterprise Edition only feature.

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

    -
    custom_conflict_resolver
    string
    Default: "none"
    		custom_conflict_resolver
    string
    Default: "none"

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    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:

      @@ -3617,151 +3639,151 @@

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

      This is an Enterprise Edition only feature.

      -
    purge_on_removal
    boolean
    Default: false
    		purge_on_removal
    boolean
    Default: false

    Specifies whether to purge a document if the remote user loses access to all of the channels on the document when attempting to pull it from the remote.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    Specifies whether to purge a document if the remote user loses access to all of the channels on the document when attempting to pull it from the remote.

    If false, documents will not be replicated and not be purged when the user loses access.

    -
    enable_delta_sync
    boolean
    Default: false
    		enable_delta_sync
    boolean
    Default: false

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

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

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

    Enabling this is an Enterprise Edition only feature.

    -
    max_backoff_time
    integer
    Default: 5
    		max_backoff_time
    integer
    Default: 5

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

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

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

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

    -
    initial_state
    string
    Default: "running"
    Enum: "running" "stopped"
    		initial_state
    string
    Default: "running"
    Enum: "running" "stopped"

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

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

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

    -
    continuous
    boolean
    Default: false
    		continuous
    boolean
    Default: false

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

    If false, all changes will be synced until they have been processed. The replication will then cease and not process any future changes (unless started again by the user). This is known as a one-shot replication.

    -
    filter
    string
    Value: "sync_gateway/bychannel"
    		filter
    string
    Value: "sync_gateway/bychannel"

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

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

    This only can be used with pull replications.

    -
    query_params
    Array of strings
    		query_params
    Array of strings

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

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

    "filter":"sync_gateway/bychannel",
 "query_params": {
   "channels":["chanUser1"]
 },
    -
    adhoc
    boolean
    Default: false
    		adhoc
    boolean
    Default: false

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

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

    -
    batch_size
    integer
    Default: 200

    The amount of changes to be sent in one batch of replications. Changing this is an Enterprise Edition only feature.

    -
    run_as
    string

    This is used if you want to specify a user to run the replication as. This means that the replication will only be able to replicate what the user access to what the user has access to.

    -
    collections_enabled
    boolean
    Default: false
    		batch_size
    integer
    Default: 200

    The amount of changes to be sent in one batch of replications. Changing this is an Enterprise Edition only feature.

    +
    run_as
    string

    This is used if you want to specify a user to run the replication as. This means that the replication will only be able to replicate what the user access to what the user has access to.

    +
    collections_enabled
    boolean
    Default: false

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

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

    -
    collections_local
    Array of strings
    Default: []
    		collections_local
    Array of strings
    Default: []

    Limits the set of collections replicated to those listed in this array.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    Limits the set of collections replicated to those listed in this array.

    The replication will use all collections defined on the database if this list is empty.

    -
    collections_remote
    Array of strings
    Default: []
    		collections_remote
    Array of strings
    Default: []

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

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

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

    -

    Responses

    Request samples

    Content type
    application/json
    {
    • "replication_id": "string",
    • "remote": "string",
    • "username": "string",
    • "password": "string",
    • "remote_username": "string",
    • "remote_password": "string",
    • "direction": "push",
    • "conflict_resolution_type": "default",
    • "custom_conflict_resolver": "none",
    • "purge_on_removal": false,
    • "enable_delta_sync": false,
    • "max_backoff_time": 5,
    • "initial_state": "running",
    • "continuous": false,
    • "filter": "sync_gateway/bychannel",
    • "query_params": [
      ],
    • "adhoc": false,
    • "batch_size": 200,
    • "run_as": "string",
    • "collections_enabled": false,
    • "collections_local": [
      ],
    • "collections_remote": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    /{db}/_replication/

    Responses

    Request samples

    Content type
    application/json
    {
    • "replication_id": "string",
    • "remote": "string",
    • "username": "string",
    • "password": "string",
    • "remote_username": "string",
    • "remote_password": "string",
    • "direction": "push",
    • "conflict_resolution_type": "default",
    • "custom_conflict_resolver": "none",
    • "purge_on_removal": false,
    • "enable_delta_sync": false,
    • "max_backoff_time": 5,
    • "initial_state": "running",
    • "continuous": false,
    • "filter": "sync_gateway/bychannel",
    • "query_params": [
      ],
    • "adhoc": false,
    • "batch_size": 200,
    • "run_as": "string",
    • "collections_enabled": false,
    • "collections_local": [
      ],
    • "collections_remote": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    /{db}/_replication/

    Required Sync Gateway RBAC roles:

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    Required Sync Gateway RBAC roles:

    • Sync Gateway Replicator
    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -

    Responses

    Get a replication configuration

    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +

    Responses

    Get a replication configuration

    Retrieve a replication configuration from the database.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    Retrieve a replication configuration from the database.

    Required Sync Gateway RBAC roles:

    • Sync Gateway Replicator
    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -
    replicationid
    required
    string

    What replication to target based on its replication ID.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "replication_id": "string",
    • "remote": "string",
    • "username": "string",
    • "password": "string",
    • "remote_username": "string",
    • "remote_password": "string",
    • "direction": "push",
    • "conflict_resolution_type": "default",
    • "custom_conflict_resolver": "none",
    • "purge_on_removal": false,
    • "enable_delta_sync": false,
    • "max_backoff_time": 5,
    • "initial_state": "running",
    • "continuous": false,
    • "filter": "sync_gateway/bychannel",
    • "query_params": [
      ],
    • "adhoc": false,
    • "batch_size": 200,
    • "run_as": "string",
    • "collections_enabled": false,
    • "collections_local": [
      ],
    • "collections_remote": [
      ],
    • "assigned_node": "string",
    • "target_state": "running"
    }

    Upsert a replication

    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +
    replicationid
    required
    string

    What replication to target based on its replication ID.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "replication_id": "string",
    • "remote": "string",
    • "username": "string",
    • "password": "string",
    • "remote_username": "string",
    • "remote_password": "string",
    • "direction": "push",
    • "conflict_resolution_type": "default",
    • "custom_conflict_resolver": "none",
    • "purge_on_removal": false,
    • "enable_delta_sync": false,
    • "max_backoff_time": 5,
    • "initial_state": "running",
    • "continuous": false,
    • "filter": "sync_gateway/bychannel",
    • "query_params": [
      ],
    • "adhoc": false,
    • "batch_size": 200,
    • "run_as": "string",
    • "collections_enabled": false,
    • "collections_local": [
      ],
    • "collections_remote": [
      ],
    • "assigned_node": "string",
    • "target_state": "running"
    }

    Upsert a replication

    Create or update a replication in the database.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    Create or update a replication in the database.

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

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

    Required Sync Gateway RBAC roles:

    • Sync Gateway Replicator
    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -
    replicationid
    required
    string

    What replication to target based on its replication ID.

    -
    Request Body schema: application/json

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

    -
    replication_id
    string
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +
    replicationid
    required
    string

    What replication to target based on its replication ID.

    +
    Request Body schema: application/json

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

    +
    replication_id
    string

    This is the ID of the replication.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    This is the ID of the replication.

    When creating a new replication using a POST request, this will be set to a random UUID if not explicitly set.

    When the replication ID is specified in the URL, this must be set to the same replication ID if specifying it at all.

    -
    remote
    string
    		remote
    string

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    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:

      @@ -3777,31 +3799,31 @@
    • push - this replicator pushes changes to this remote
    • pushAndPull - this replicator pushes changes to this remote, while also pulling receiving changes
    -
    username
    string
    Deprecated
    		username
    string
    Deprecated

    This has been deprecated in favour of remote_username.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    This has been deprecated in favour of remote_username.

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

    This can only be used for a pull replication.

    -
    password
    string
    Deprecated
    		password
    string
    Deprecated

    This has been deprecated in favour of remote_password.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    This has been deprecated in favour of remote_password.

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

    This password will be redacted in the replication config.

    This can only be used for a pull replication.

    -
    remote_username
    string
    		remote_username
    string

    The username to use to authenticate with the remote.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The username to use to authenticate with the remote.

    This can only be used for a pull replication.

    -
    remote_password
    string
    		remote_password
    string

    The password to use to authenticate with the remote.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The password to use to authenticate with the remote.

    This password will be redacted in the replication config.

    This can only be used for a pull replication.

    -
    direction
    required
    string
    Enum: "push" "pull" "pushAndPull"
    		direction
    required
    string
    Enum: "push" "pull" "pushAndPull"

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

    The directions are:

    • pull - changes are pulled from the remote database
      • @@ -3817,7 +3839,7 @@
    • pushAndPull - changes are both push-to and pulled-from the remote database

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

    -
    conflict_resolution_type
    string
    Default: "default"
    Enum: "default" "remoteWins" "localWins" "custom"
    		conflict_resolution_type
    string
    Default: "default"
    Enum: "default" "remoteWins" "localWins" "custom"

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    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

      @@ -3845,7 +3867,7 @@
    • custom - This will result in conflicts going through your own custom conflict resolver. You must provide this logic as a Javascript function in the custom_conflict_resolver parameter. This is an Enterprise Edition only feature.

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

    -
    custom_conflict_resolver
    string
    Default: "none"
    		custom_conflict_resolver
    string
    Default: "none"

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    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:

      @@ -3883,203 +3905,203 @@

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

      This is an Enterprise Edition only feature.

      -
    purge_on_removal
    boolean
    Default: false
    		purge_on_removal
    boolean
    Default: false

    Specifies whether to purge a document if the remote user loses access to all of the channels on the document when attempting to pull it from the remote.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    Specifies whether to purge a document if the remote user loses access to all of the channels on the document when attempting to pull it from the remote.

    If false, documents will not be replicated and not be purged when the user loses access.

    -
    enable_delta_sync
    boolean
    Default: false
    		enable_delta_sync
    boolean
    Default: false

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

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

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

    Enabling this is an Enterprise Edition only feature.

    -
    max_backoff_time
    integer
    Default: 5
    		max_backoff_time
    integer
    Default: 5

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

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

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

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

    -
    initial_state
    string
    Default: "running"
    Enum: "running" "stopped"
    		initial_state
    string
    Default: "running"
    Enum: "running" "stopped"

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

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

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

    -
    continuous
    boolean
    Default: false
    		continuous
    boolean
    Default: false

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

    If false, all changes will be synced until they have been processed. The replication will then cease and not process any future changes (unless started again by the user). This is known as a one-shot replication.

    -
    filter
    string
    Value: "sync_gateway/bychannel"
    		filter
    string
    Value: "sync_gateway/bychannel"

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

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

    This only can be used with pull replications.

    -
    query_params
    Array of strings
    		query_params
    Array of strings

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

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

    "filter":"sync_gateway/bychannel",
 "query_params": {
   "channels":["chanUser1"]
 },
    -
    adhoc
    boolean
    Default: false
    		adhoc
    boolean
    Default: false

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

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

    -
    batch_size
    integer
    Default: 200

    The amount of changes to be sent in one batch of replications. Changing this is an Enterprise Edition only feature.

    -
    run_as
    string

    This is used if you want to specify a user to run the replication as. This means that the replication will only be able to replicate what the user access to what the user has access to.

    -
    collections_enabled
    boolean
    Default: false
    		batch_size
    integer
    Default: 200

    The amount of changes to be sent in one batch of replications. Changing this is an Enterprise Edition only feature.

    +
    run_as
    string

    This is used if you want to specify a user to run the replication as. This means that the replication will only be able to replicate what the user access to what the user has access to.

    +
    collections_enabled
    boolean
    Default: false

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

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

    -
    collections_local
    Array of strings
    Default: []
    		collections_local
    Array of strings
    Default: []

    Limits the set of collections replicated to those listed in this array.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    Limits the set of collections replicated to those listed in this array.

    The replication will use all collections defined on the database if this list is empty.

    -
    collections_remote
    Array of strings
    Default: []
    		collections_remote
    Array of strings
    Default: []

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

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

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

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

    -

    Responses

    Request samples

    Content type
    application/json
    {
    • "replication_id": "string",
    • "remote": "string",
    • "username": "string",
    • "password": "string",
    • "remote_username": "string",
    • "remote_password": "string",
    • "direction": "push",
    • "conflict_resolution_type": "default",
    • "custom_conflict_resolver": "none",
    • "purge_on_removal": false,
    • "enable_delta_sync": false,
    • "max_backoff_time": 5,
    • "initial_state": "running",
    • "continuous": false,
    • "filter": "sync_gateway/bychannel",
    • "query_params": [
      ],
    • "adhoc": false,
    • "batch_size": 200,
    • "run_as": "string",
    • "collections_enabled": false,
    • "collections_local": [
      ],
    • "collections_remote": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    Stop and delete a replication

    Responses

    Request samples

    Content type
    application/json
    {
    • "replication_id": "string",
    • "remote": "string",
    • "username": "string",
    • "password": "string",
    • "remote_username": "string",
    • "remote_password": "string",
    • "direction": "push",
    • "conflict_resolution_type": "default",
    • "custom_conflict_resolver": "none",
    • "purge_on_removal": false,
    • "enable_delta_sync": false,
    • "max_backoff_time": 5,
    • "initial_state": "running",
    • "continuous": false,
    • "filter": "sync_gateway/bychannel",
    • "query_params": [
      ],
    • "adhoc": false,
    • "batch_size": 200,
    • "run_as": "string",
    • "collections_enabled": false,
    • "collections_local": [
      ],
    • "collections_remote": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    Stop and delete a replication

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

    Required Sync Gateway RBAC roles:

    • Sync Gateway Replicator
    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -
    replicationid
    required
    string

    What replication to target based on its replication ID.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    Check if a replication exists

    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +
    replicationid
    required
    string

    What replication to target based on its replication ID.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    Check if a replication exists

    Check if a replication exists.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    Check if a replication exists.

    Required Sync Gateway RBAC roles:

    • Sync Gateway Replicator
    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -
    replicationid
    required
    string

    What replication to target based on its replication ID.

    -

    Responses

    Get all replication statuses

    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +
    replicationid
    required
    string

    What replication to target based on its replication ID.

    +

    Responses

    Get all replication statuses

    Retrieve all the replication statuses in the Sync Gateway node.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    Retrieve all the replication statuses in the Sync Gateway node.

    Required Sync Gateway RBAC roles:

    • Sync Gateway Replicator
    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -
    query Parameters
    activeOnly
    boolean
    Default: "false"

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

    -
    localOnly
    boolean
    Default: "false"

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

    -
    includeError
    boolean
    Default: "true"

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

    -
    includeConfig
    boolean
    Default: "false"

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

    -

    Responses

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    /{db}/_replicationStatus/

    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +
    query Parameters
    activeOnly
    boolean
    Default: "false"

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

    +
    localOnly
    boolean
    Default: "false"

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

    +
    includeError
    boolean
    Default: "true"

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

    +
    includeConfig
    boolean
    Default: "false"

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

    +

    Responses

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    /{db}/_replicationStatus/

    Required Sync Gateway RBAC roles:

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    Required Sync Gateway RBAC roles:

    • Sync Gateway Replicator
    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -

    Responses

    Get replication status

    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +

    Responses

    Get replication status

    Retrieve the status of a replication.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    Retrieve the status of a replication.

    Required Sync Gateway RBAC roles:

    • Sync Gateway Replicator
    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -
    replicationid
    required
    string

    What replication to target based on its replication ID.

    -
    query Parameters
    activeOnly
    boolean
    Default: "false"

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

    -
    localOnly
    boolean
    Default: "false"

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

    -
    includeError
    boolean
    Default: "true"

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

    -
    includeConfig
    boolean
    Default: "false"

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

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "replication_id": "string",
    • "config": {
      },
    • "status": "stopped",
    • "error_message": "string",
    • "docs_read": 0,
    • "docs_checked_pull": 0,
    • "docs_purged": 0,
    • "rejected_by_local": 0,
    • "last_seq_pull": "string",
    • "deltas_recv": 0,
    • "deltas_requested": 0,
    • "docs_written": 0,
    • "docs_checked_push": 0,
    • "docs_write_failures": 0,
    • "docs_write_conflicts": 0,
    • "rejected_by_remote": 0,
    • "last_seq_push": "string",
    • "deltas_sent": 0
    }

    Control a replication state

    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +
    replicationid
    required
    string

    What replication to target based on its replication ID.

    +
    query Parameters
    activeOnly
    boolean
    Default: "false"

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

    +
    localOnly
    boolean
    Default: "false"

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

    +
    includeError
    boolean
    Default: "true"

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

    +
    includeConfig
    boolean
    Default: "false"

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

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "replication_id": "string",
    • "config": {
      },
    • "status": "stopped",
    • "error_message": "string",
    • "docs_read": 0,
    • "docs_checked_pull": 0,
    • "docs_purged": 0,
    • "rejected_by_local": 0,
    • "last_seq_pull": "string",
    • "deltas_recv": 0,
    • "deltas_requested": 0,
    • "docs_written": 0,
    • "docs_checked_push": 0,
    • "docs_write_failures": 0,
    • "docs_write_conflicts": 0,
    • "rejected_by_remote": 0,
    • "last_seq_push": "string",
    • "deltas_sent": 0
    }

    Control a replication state

    Control the replication by changing its state.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    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
      • @@ -4101,93 +4123,93 @@
      • Sync Gateway Replicator
      -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -
    replicationid
    required
    string

    What replication to target based on its replication ID.

    -
    query Parameters
    action
    required
    string
    Enum: "start" "stop" "reset"

    The target state to put the replicator into.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "replication_id": "string",
    • "config": {
      },
    • "status": "stopped",
    • "error_message": "string",
    • "docs_read": 0,
    • "docs_checked_pull": 0,
    • "docs_purged": 0,
    • "rejected_by_local": 0,
    • "last_seq_pull": "string",
    • "deltas_recv": 0,
    • "deltas_requested": 0,
    • "docs_written": 0,
    • "docs_checked_push": 0,
    • "docs_write_failures": 0,
    • "docs_write_conflicts": 0,
    • "rejected_by_remote": 0,
    • "last_seq_push": "string",
    • "deltas_sent": 0
    }

    Check if replication exists

    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +
    replicationid
    required
    string

    What replication to target based on its replication ID.

    +
    query Parameters
    action
    required
    string
    Enum: "start" "stop" "reset"

    The target state to put the replicator into.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "replication_id": "string",
    • "config": {
      },
    • "status": "stopped",
    • "error_message": "string",
    • "docs_read": 0,
    • "docs_checked_pull": 0,
    • "docs_purged": 0,
    • "rejected_by_local": 0,
    • "last_seq_pull": "string",
    • "deltas_recv": 0,
    • "deltas_requested": 0,
    • "docs_written": 0,
    • "docs_checked_push": 0,
    • "docs_write_failures": 0,
    • "docs_write_conflicts": 0,
    • "rejected_by_remote": 0,
    • "last_seq_push": "string",
    • "deltas_sent": 0
    }

    Check if replication exists

    Check if a replication exists.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    Check if a replication exists.

    Required Sync Gateway RBAC roles:

    • Sync Gateway Replicator
    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -
    replicationid
    required
    string

    What replication to target based on its replication ID.

    -
    query Parameters
    activeOnly
    boolean
    Default: "false"

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

    -
    localOnly
    boolean
    Default: "false"

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

    -
    includeError
    boolean
    Default: "true"

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

    -
    includeConfig
    boolean
    Default: "false"

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

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    Handle incoming BLIP Sync web socket request

    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +
    replicationid
    required
    string

    What replication to target based on its replication ID.

    +
    query Parameters
    activeOnly
    boolean
    Default: "false"

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

    +
    localOnly
    boolean
    Default: "false"

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

    +
    includeError
    boolean
    Default: "true"

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

    +
    includeConfig
    boolean
    Default: "false"

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

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    Handle incoming BLIP Sync web socket request

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

    Required Sync Gateway RBAC roles:

    • Sync Gateway Application
    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -
    query Parameters
    client
    string
    Default: "cbl2"
    Enum: "cbl2" "sgr2"

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

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Metrics

    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +
    query Parameters
    client
    string
    Default: "cbl2"
    Enum: "cbl2" "sgr2"

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

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Metrics

    Get Sync Gateway statistics

    -

    Get memory statistics

    Get memory statistics

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

    Required Sync Gateway RBAC roles:

    • Sync Gateway Architect
    • Sync Gateway Dev Ops
    • External Stats Reader
    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "memstats": { }
    }

    Get all Sync Gateway statistics

    Responses

    Response samples

    Content type
    application/json
    {
    • "memstats": { }
    }

    Get all Sync Gateway statistics in JSON format

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    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:

      @@ -4203,373 +4225,375 @@
    • Sync Gateway Dev Ops
    • External Stats Reader
    -

    Responses

    Profiling

    Responses

    Response samples

    Content type
    application/json
    {
    • "cmdline": { },
    • "memstats": { },
    • "cb": { },
    • "mc": { },
    • "syncGateway_changeCache": {
      },
    • "syncGateway_db": {
      },
    • "syncgateway": {
      }
    }

    Profiling

    Generate information to help debug and fine-tune Sync Gateway

    -

    Create point-in-time profile

    Create point-in-time profile

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

    Required Sync Gateway RBAC roles:

    • Sync Gateway Dev Ops
    -
    path Parameters
    profilename
    required
    string
    Enum: "heap" "block" "threadcreate" "mutex" "goroutine"

    The handler to use for profiling.

    -
    Request Body schema: application/json
    file
    string

    This is the file to output the pprof profile at.

    -

    Responses

    Request samples

    Content type
    application/json
    {
    • "file": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    Start or Stop continuous CPU profiling

    path Parameters
    profilename
    required
    string
    Enum: "heap" "block" "threadcreate" "mutex" "goroutine"

    The handler to use for profiling.

    +
    Request Body schema: application/json
    file
    string

    This is the file to output the pprof profile at.

    +

    Responses

    Request samples

    Content type
    application/json
    {
    • "file": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    Start or Stop continuous CPU profiling

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

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

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

    Required Sync Gateway RBAC roles:

    • Sync Gateway Dev Ops
    -
    Request Body schema: application/json
    file
    string

    This is the file to output the pprof profile at.

    -

    Responses

    Request samples

    Content type
    application/json
    {
    • "file": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    Dump heap profile

    Request Body schema: application/json
    file
    string

    This is the file to output the pprof profile at.

    +

    Responses

    Request samples

    Content type
    application/json
    {
    • "file": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    Dump heap profile

    This endpoint will dump a pprof heap profile.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    This endpoint will dump a pprof heap profile.

    Required Sync Gateway RBAC roles:

    • Sync Gateway Dev Ops
    -
    Request Body schema: application/json
    file
    string

    This is the file to output the pprof profile at.

    -

    Responses

    Request samples

    Content type
    application/json
    {
    • "file": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    Get goroutine profile

    Request Body schema: application/json
    file
    string

    This is the file to output the pprof profile at.

    +

    Responses

    Request samples

    Content type
    application/json
    {
    • "file": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    Get goroutine profile

    Stack traces of all current goroutines.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    Stack traces of all current goroutines.

    Required Sync Gateway RBAC roles:

    • Sync Gateway Dev Ops
    -
    query Parameters
    seconds
    integer

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

    -

    Responses

    Get goroutine profile

    query Parameters
    seconds
    integer

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

    +

    Responses

    Get goroutine profile

    Stack traces of all current goroutines.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    Stack traces of all current goroutines.

    Required Sync Gateway RBAC roles:

    • Sync Gateway Dev Ops
    -
    query Parameters
    seconds
    integer

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

    -

    Responses

    Get passed in command line parameters

    query Parameters
    seconds
    integer

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

    +

    Responses

    Get passed in command line parameters

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

    Required Sync Gateway RBAC roles:

    • Sync Gateway Dev Ops
    -

    Responses

    Get passed in command line parameters

    Responses

    Get passed in command line parameters

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

    Required Sync Gateway RBAC roles:

    • Sync Gateway Dev Ops
    -

    Responses

    Get symbol pprof debug information

    Responses

    Get symbol pprof debug information

    Required Sync Gateway RBAC roles:

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    Required Sync Gateway RBAC roles:

    • Sync Gateway Dev Ops
    -

    Responses

    Get symbol pprof debug information

    Responses

    Get symbol pprof debug information

    Required Sync Gateway RBAC roles:

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    Required Sync Gateway RBAC roles:

    • Sync Gateway Dev Ops
    -

    Responses

    Get the heap pprof debug file

    Responses

    Get the heap pprof debug file

    Required Sync Gateway RBAC roles:

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    Required Sync Gateway RBAC roles:

    • Sync Gateway Dev Ops
    -
    query Parameters
    seconds
    integer

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

    -

    Responses

    Get the heap pprof debug file

    query Parameters
    seconds
    integer

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

    +

    Responses

    Get the heap pprof debug file

    Required Sync Gateway RBAC roles:

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    Required Sync Gateway RBAC roles:

    • Sync Gateway Dev Ops
    -
    query Parameters
    seconds
    integer

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

    -

    Responses

    Get the profile pprof debug file

    query Parameters
    seconds
    integer

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

    +

    Responses

    Get the profile pprof debug file

    Required Sync Gateway RBAC roles:

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    Required Sync Gateway RBAC roles:

    • Sync Gateway Dev Ops
    -
    query Parameters
    seconds
    integer

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

    -

    Responses

    Get the profile pprof debug file

    query Parameters
    seconds
    integer

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

    +

    Responses

    Get the profile pprof debug file

    Required Sync Gateway RBAC roles:

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    Required Sync Gateway RBAC roles:

    • Sync Gateway Dev Ops
    -
    query Parameters
    seconds
    integer

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

    -

    Responses

    Get block profile

    query Parameters
    seconds
    integer

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

    +

    Responses

    Get block profile

    Returns stack traces that led to blocking on synchronization primitives.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    Returns stack traces that led to blocking on synchronization primitives.

    Required Sync Gateway RBAC roles:

    • Sync Gateway Dev Ops
    -
    query Parameters
    seconds
    integer >= 0
    Default: 30

    The amount of seconds to run the profiler for.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "forbidden",
    • "reason": "Can only run one mutex profile at a time"
    }

    Get block profile

    query Parameters
    seconds
    integer >= 0
    Default: 30

    The amount of seconds to run the profiler for.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "forbidden",
    • "reason": "Can only run one mutex profile at a time"
    }

    Get block profile

    Returns stack traces that led to blocking on synchronization primitives.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    Returns stack traces that led to blocking on synchronization primitives.

    Required Sync Gateway RBAC roles:

    • Sync Gateway Dev Ops
    -
    query Parameters
    seconds
    integer >= 0
    Default: 30

    The amount of seconds to run the profiler for.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "forbidden",
    • "reason": "Can only run one mutex profile at a time"
    }

    Get the threadcreate pprof debug file

    query Parameters
    seconds
    integer >= 0
    Default: 30

    The amount of seconds to run the profiler for.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "forbidden",
    • "reason": "Can only run one mutex profile at a time"
    }

    Get the threadcreate pprof debug file

    Required Sync Gateway RBAC roles:

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    Required Sync Gateway RBAC roles:

    • Sync Gateway Dev Ops
    -

    Responses

    Get the threadcreate pprof debug file

    Responses

    Get the threadcreate pprof debug file

    Required Sync Gateway RBAC roles:

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    Required Sync Gateway RBAC roles:

    • Sync Gateway Dev Ops
    -

    Responses

    Get mutex profile

    Responses

    Get mutex profile

    Returns stack traces of holders of contended mutexes.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    Returns stack traces of holders of contended mutexes.

    Required Sync Gateway RBAC roles:

    • Sync Gateway Dev Ops
    -
    query Parameters
    seconds
    integer >= 0
    Default: 30

    The amount of seconds to run the profiler for.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "forbidden",
    • "reason": "Can only run one mutex profile at a time"
    }

    Get mutex profile

    query Parameters
    seconds
    integer >= 0
    Default: 30

    The amount of seconds to run the profiler for.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "forbidden",
    • "reason": "Can only run one mutex profile at a time"
    }

    Get mutex profile

    Returns stack traces of holders of contended mutexes.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    Returns stack traces of holders of contended mutexes.

    Required Sync Gateway RBAC roles:

    • Sync Gateway Dev Ops
    -
    query Parameters
    seconds
    integer >= 0
    Default: 30

    The amount of seconds to run the profiler for.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "forbidden",
    • "reason": "Can only run one mutex profile at a time"
    }

    Get trace profile

    query Parameters
    seconds
    integer >= 0
    Default: 30

    The amount of seconds to run the profiler for.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "forbidden",
    • "reason": "Can only run one mutex profile at a time"
    }

    Get trace profile

    Responds with the execution trace in binary form.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    Responds with the execution trace in binary form.

    Required Sync Gateway RBAC roles:

    • Sync Gateway Dev Ops
    -
    query Parameters
    seconds
    integer
    Default: 1

    Responses

    Get trace profile

    query Parameters
    seconds
    integer
    Default: 1

    Responses

    Get trace profile

    Responds with the execution trace in binary form.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    Responds with the execution trace in binary form.

    Required Sync Gateway RBAC roles:

    • Sync Gateway Dev Ops
    -
    query Parameters
    seconds
    integer
    Default: 1

    Responses

    Get fgprof profile

    query Parameters
    seconds
    integer
    Default: 1

    Responses

    Get fgprof profile

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

    Required Sync Gateway RBAC roles:

    • Sync Gateway Dev Ops
    -
    query Parameters
    seconds
    integer >= 0
    Default: 30

    The amount of seconds to run the profiler for.

    -

    Responses

    Get fgprof profile

    query Parameters
    seconds
    integer >= 0
    Default: 30

    The amount of seconds to run the profiler for.

    +

    Responses

    Get fgprof profile

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

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

    Required Sync Gateway RBAC roles:

    • Sync Gateway Dev Ops
    -
    query Parameters
    seconds
    integer >= 0
    Default: 30

    The amount of seconds to run the profiler for.

    -

    Responses

    Unsupported

    query Parameters
    seconds
    integer >= 0
    Default: 30

    The amount of seconds to run the profiler for.

    +

    Responses

    Unsupported

    Endpoints that are not supported by Sync Gateway

    -

    Revision tree structure in Graphviz Dot format | Unsupported

    Revision tree structure in Graphviz Dot format | Unsupported

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    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:

    1. Install the Graphviz tool. Using Brew, this can be done by calling brew install graphviz.
      2. @@ -4595,329 +4619,329 @@
    2. Sync Gateway Application Read Only

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

      -
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

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

    -
    docid
    required
    string
    Example: doc1

    The document ID to run the operation against.

    -

    Responses

    Response samples

    Content type
    application/json
    "digraph graphname{\"1-d4d949b7feafc8c31215684baa45b6cd\" -> \"2-4f3f24143ea43d85a9a340ac016fdfc4\"; }"

    Flush the entire database bucket | Unsupported

    		docid
    required
    string
    Example: doc1

    The document ID to run the operation against.

    +

    Responses

    Response samples

    Content type
    application/json
    "digraph graphname{\"1-d4d949b7feafc8c31215684baa45b6cd\" -> \"2-4f3f24143ea43d85a9a340ac016fdfc4\"; }"

    Flush the entire database bucket | Unsupported

    This is unsupported

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    This is unsupported

    This will purge all documents.

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

    Required Sync Gateway RBAC roles:

    • Sync Gateway Dev Ops
    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Dump a view | Unsupported

    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Dump a view | Unsupported

    This is unsupported

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    This is unsupported

    This queries the view and outputs it as HTML.

    Required Sync Gateway RBAC roles:

    • Sync Gateway Application
    • Sync Gateway Application Read Only
    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -
    view
    required
    string

    The view to target.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Query a view on the default design document | Unsupported

    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +
    view
    required
    string

    The view to target.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Query a view on the default design document | Unsupported

    This is unsupported

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    This is unsupported

    Query a view on the default Sync Gateway design document.

    Required Sync Gateway RBAC roles:

    • Sync Gateway Application
    • Sync Gateway Application Read Only
    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -
    view
    required
    string

    The view to target.

    -
    query Parameters
    inclusive_end
    boolean

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

    -
    descending
    boolean

    Return documents in descending order.

    -
    include_docs
    boolean

    Only works when using Couchbase Server 3.0 and earlier. Indicates whether to include the full content of the documents in the response.

    -
    reduce
    boolean

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

    -
    group
    boolean

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

    -
    skip
    integer

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

    -
    limit
    integer

    Return only the specified number of documents

    -
    group_level
    integer

    Specify the group level to be used.

    -
    startkey_docid
    string

    Return documents starting with the specified document identifier.

    -
    endkey_docid
    string

    Stop returning records when the specified document identifier is reached.

    -
    stale
    string
    Enum: "ok" "update_after"

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

    -
    startkey
    string

    Return records starting with the specified key.

    -
    endkey
    string

    Stop returning records when this key is reached.

    -
    key
    string

    Return only the document that matches the specified key.

    -
    keys
    Array of strings

    An array of document ID strings to filter by.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "total_rows": 0,
    • "rows": [
      ],
    • "errors": [
      ]
    }

    Dump all the documents in a channel | Unsupported

    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +
    view
    required
    string

    The view to target.

    +
    query Parameters
    inclusive_end
    boolean

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

    +
    descending
    boolean

    Return documents in descending order.

    +
    include_docs
    boolean

    Only works when using Couchbase Server 3.0 and earlier. Indicates whether to include the full content of the documents in the response.

    +
    reduce
    boolean

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

    +
    group
    boolean

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

    +
    skip
    integer

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

    +
    limit
    integer

    Return only the specified number of documents

    +
    group_level
    integer

    Specify the group level to be used.

    +
    startkey_docid
    string

    Return documents starting with the specified document identifier.

    +
    endkey_docid
    string

    Stop returning records when the specified document identifier is reached.

    +
    stale
    string
    Enum: "ok" "update_after"

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

    +
    startkey
    string

    Return records starting with the specified key.

    +
    endkey
    string

    Stop returning records when this key is reached.

    +
    key
    string

    Return only the document that matches the specified key.

    +
    keys
    Array of strings

    An array of document ID strings to filter by.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "total_rows": 0,
    • "rows": [
      ],
    • "errors": [
      ]
    }

    Dump all the documents in a channel | Unsupported

    This is unsupported

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    This is unsupported

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

    Required Sync Gateway RBAC roles:

    • Sync Gateway Application
    • Sync Gateway Application Read Only
    -
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

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

    -
    channel
    required
    string

    The channel to dump all the documents from.

    -
    query Parameters
    since
    string

    Starts the results from the change immediately after the given sequence ID. Sequence IDs should be considered opaque; they come from the last_seq property of a prior response.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Disabled endpoint

    		channel
    required
    string

    The channel to dump all the documents from.

    +
    query Parameters
    since
    string

    Starts the results from the change immediately after the given sequence ID. Sequence IDs should be considered opaque; they come from the last_seq property of a prior response.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Disabled endpoint

    This endpoint is disabled.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    This endpoint is disabled.

    Required Sync Gateway RBAC roles:

    • Sync Gateway Architect
    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -

    Responses

    Get views of a design document | Unsupported

    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +

    Responses

    Get views of a design document | Unsupported

    This is unsupported

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    This is unsupported

    Query a design document.

    Required Sync Gateway RBAC roles:

    • Sync Gateway Application
    • Sync Gateway Application Read Only
    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -
    ddoc
    required
    string

    The design document name.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "language": "string",
    • "views": {
      },
    • "options": {
      }
    }

    Update views of a design document | Unsupported

    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +
    ddoc
    required
    string

    The design document name.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "language": "string",
    • "views": {
      },
    • "options": {
      }
    }

    Update views of a design document | Unsupported

    This is unsupported

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    This is unsupported

    Update the views of a design document.

    Required Sync Gateway RBAC roles:

    • Sync Gateway Application
    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -
    ddoc
    required
    string

    The design document name.

    -
    Request Body schema: application/json
    language
    string
    object
    object

    Responses

    Request samples

    Content type
    application/json
    {
    • "language": "string",
    • "views": {
      },
    • "options": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Delete a design document | Unsupported

    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +
    ddoc
    required
    string

    The design document name.

    +
    Request Body schema: application/json
    language
    string
    object
    object

    Responses

    Request samples

    Content type
    application/json
    {
    • "language": "string",
    • "views": {
      },
    • "options": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Delete a design document | Unsupported

    This is unsupported

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    This is unsupported

    Delete a design document.

    Required Sync Gateway RBAC roles:

    • Sync Gateway Application
    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -
    ddoc
    required
    string

    The design document name.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Check if view of design document exists | Unsupported

    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +
    ddoc
    required
    string

    The design document name.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Check if view of design document exists | Unsupported

    This is unsupported

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    This is unsupported

    Check if a design document can be queried.

    Required Sync Gateway RBAC roles:

    • Sync Gateway Application
    • Sync Gateway Application Read Only
    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -
    ddoc
    required
    string

    The design document name.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Query a view on a design document | Unsupported

    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +
    ddoc
    required
    string

    The design document name.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Query a view on a design document | Unsupported

    This is unsupported

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    This is unsupported

    Query a view on a design document.

    Required Sync Gateway RBAC roles:

    • Sync Gateway Application
    • Sync Gateway Application Read Only
    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -
    ddoc
    required
    string

    The design document name.

    -
    view
    required
    string

    The view to target.

    -
    query Parameters
    inclusive_end
    boolean

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

    -
    descending
    boolean

    Return documents in descending order.

    -
    include_docs
    boolean

    Only works when using Couchbase Server 3.0 and earlier. Indicates whether to include the full content of the documents in the response.

    -
    reduce
    boolean

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

    -
    group
    boolean

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

    -
    skip
    integer

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

    -
    limit
    integer

    Return only the specified number of documents

    -
    group_level
    integer

    Specify the group level to be used.

    -
    startkey_docid
    string

    Return documents starting with the specified document identifier.

    -
    endkey_docid
    string

    Stop returning records when the specified document identifier is reached.

    -
    stale
    string
    Enum: "ok" "update_after"

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

    -
    startkey
    string

    Return records starting with the specified key.

    -
    endkey
    string

    Stop returning records when this key is reached.

    -
    key
    string

    Return only the document that matches the specified key.

    -
    keys
    Array of strings

    An array of document ID strings to filter by.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "total_rows": 0,
    • "rows": [
      ],
    • "errors": [
      ]
    }
    +
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +
    ddoc
    required
    string

    The design document name.

    +
    view
    required
    string

    The view to target.

    +
    query Parameters
    inclusive_end
    boolean

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

    +
    descending
    boolean

    Return documents in descending order.

    +
    include_docs
    boolean

    Only works when using Couchbase Server 3.0 and earlier. Indicates whether to include the full content of the documents in the response.

    +
    reduce
    boolean

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

    +
    group
    boolean

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

    +
    skip
    integer

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

    +
    limit
    integer

    Return only the specified number of documents

    +
    group_level
    integer

    Specify the group level to be used.

    +
    startkey_docid
    string

    Return documents starting with the specified document identifier.

    +
    endkey_docid
    string

    Stop returning records when the specified document identifier is reached.

    +
    stale
    string
    Enum: "ok" "update_after"

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

    +
    startkey
    string

    Return records starting with the specified key.

    +
    endkey
    string

    Stop returning records when this key is reached.

    +
    key
    string

    Return only the document that matches the specified key.

    +
    keys
    Array of strings

    An array of document ID strings to filter by.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "total_rows": 0,
    • "rows": [
      ],
    • "errors": [
      ]
    }
    -
    API docs by Redocly
    API docs by Redocly

    Sync Gateway Metrics REST API (3.2)

    Download OpenAPI specification:Download

    License: Business Source License 1.1 (BSL)
    ⬆️ Metrics REST API Overview

    Introduction

    Sync Gateway Metrics REST API (3.2)

    Download OpenAPI specification:

    License: Business Source License 1.1 (BSL)
    ⬆️ Metrics REST API Overview

    Introduction

    Sync Gateway manages access and synchronization between Couchbase Lite and Couchbase Server. The Sync Gateway Metrics REST API returns Sync Gateway metrics, in JSON or Prometheus-compatible formats, for performance monitoring and diagnostic purposes.

    -

    Prometheus

    Prometheus

    Endpoints for use with Prometheus

    -

    Get debugging and monitoring runtime stats in Prometheus Exposition format

    Get debugging and monitoring runtime stats in Prometheus Exposition format

    Returns Sync Gateway statistics and other runtime variables in Prometheus Exposition format.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    Returns Sync Gateway statistics and other runtime variables in Prometheus Exposition format.

    Required Sync Gateway RBAC roles:

    • Sync Gateway Architect
    • Sync Gateway Dev Ops
    • External Stats Reader
    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "sgw_audit_num_audits_filtered_by_role": 0,
    • "sgw_audit_num_audits_filtered_by_user": 0,
    • "sgw_audit_num_audits_logged": 0,
    • "sgw_cache_abandoned_seqs": 0,
    • "sgw_cache_chan_cache_active_revs": 0,
    • "sgw_cache_chan_cache_bypass_count": 0,
    • "sgw_cache_chan_cache_channels_added": 0,
    • "sgw_cache_chan_cache_channels_evicted_inactive": 0,
    • "sgw_cache_chan_cache_channels_evicted_nru": 0,
    • "sgw_cache_chan_cache_compact_count": 0,
    • "sgw_cache_chan_cache_compact_time": 0,
    • "sgw_cache_chan_cache_hits": 0,
    • "sgw_cache_chan_cache_max_entries": 0,
    • "sgw_cache_chan_cache_misses": 0,
    • "sgw_cache_chan_cache_num_channels": 0,
    • "sgw_cache_chan_cache_pending_queries": 0,
    • "sgw_cache_chan_cache_removal_revs": 0,
    • "sgw_cache_chan_cache_tombstone_revs": 0,
    • "sgw_cache_current_skipped_seq_count": 0,
    • "sgw_cache_high_seq_cached": 0,
    • "sgw_cache_high_seq_stable": 0,
    • "sgw_cache_non_mobile_ignored_count": 0,
    • "sgw_cache_num_active_channels": 0,
    • "sgw_cache_num_skipped_seqs": 0,
    • "sgw_cache_pending_seq_len": 0,
    • "sgw_cache_rev_cache_bypass": 0,
    • "sgw_cache_rev_cache_hits": 0,
    • "sgw_cache_rev_cache_misses": 0,
    • "sgw_cache_revision_cache_num_items": 0,
    • "sgw_cache_revision_cache_total_memory": 0,
    • "sgw_cache_skipped_seq_cap": 0,
    • "sgw_cache_skipped_seq_len": 0,
    • "sgw_cache_view_queries": 0,
    • "sgw_collection_doc_reads_bytes": 0,
    • "sgw_collection_doc_writes_bytes": 0,
    • "sgw_collection_import_count": 0,
    • "sgw_collection_num_doc_reads": 0,
    • "sgw_collection_num_doc_writes": 0,
    • "sgw_collection_sync_function_count": 0,
    • "sgw_collection_sync_function_exception_count": 0,
    • "sgw_collection_sync_function_reject_access_count": 0,
    • "sgw_collection_sync_function_reject_count": 0,
    • "sgw_collection_sync_function_time": 0,
    • "sgw_config_database_config_bucket_mismatches": 0,
    • "sgw_config_database_config_collection_conflicts": 0,
    • "sgw_database_compaction_attachment_start_time": 0,
    • "sgw_database_compaction_tombstone_start_time": 0,
    • "sgw_database_conflict_write_count": 0,
    • "sgw_database_crc32c_match_count": 0,
    • "sgw_database_dcp_caching_count": 0,
    • "sgw_database_dcp_caching_time": 0,
    • "sgw_database_dcp_received_count": 0,
    • "sgw_database_dcp_received_time": 0,
    • "sgw_database_doc_reads_bytes_blip": 0,
    • "sgw_database_doc_writes_bytes": 0,
    • "sgw_database_doc_writes_bytes_blip": 0,
    • "sgw_database_doc_writes_xattr_bytes": 0,
    • "sgw_database_high_seq_feed": 0,
    • "sgw_database_http_bytes_written": 0,
    • "sgw_database_num_attachments_compacted": 0,
    • "sgw_database_num_doc_reads_blip": 0,
    • "sgw_database_num_doc_reads_rest": 0,
    • "sgw_database_num_doc_writes": 0,
    • "sgw_database_num_idle_kv_ops": 0,
    • "sgw_database_num_public_rest_requests": 0,
    • "sgw_database_num_replications_active": 0,
    • "sgw_database_num_replications_rejected_limit": 0,
    • "sgw_database_num_replications_total": 0,
    • "sgw_database_num_tombstones_compacted": 0,
    • "sgw_database_public_rest_bytes_read": 0,
    • "sgw_database_replication_bytes_received": 0,
    • "sgw_database_replication_bytes_sent": 0,
    • "sgw_database_sequence_assigned_count": 0,
    • "sgw_database_sequence_get_count": 0,
    • "sgw_database_sequence_incr_count": 0,
    • "sgw_database_sequence_released_count": 0,
    • "sgw_database_sequence_reserved_count": 0,
    • "sgw_database_sync_function_count": 0,
    • "sgw_database_sync_function_exception_count": 0,
    • "sgw_database_sync_function_time": 0,
    • "sgw_database_total_sync_time": 0,
    • "sgw_database_warn_channel_name_size_count": 0,
    • "sgw_database_warn_channels_per_doc_count": 0,
    • "sgw_database_warn_grants_per_doc_count": 0,
    • "sgw_database_warn_xattr_size_count": 0,
    • "sgw_delta_sync_delta_cache_hit": 0,
    • "sgw_delta_sync_delta_pull_replication_count": 0,
    • "sgw_delta_sync_delta_push_doc_count": 0,
    • "sgw_delta_sync_delta_sync_miss": 0,
    • "sgw_delta_sync_deltas_requested": 0,
    • "sgw_delta_sync_deltas_sent": 0,
    • "sgw_gsi_views__count": 0,
    • "sgw_gsi_views__error_count": 0,
    • "sgw_gsi_views__time": 0,
    • "sgw_replication_expected_sequence_len": 0,
    • "sgw_replication_expected_sequence_len_post_cleanup": 0,
    • "sgw_replication_processed_sequence_len": 0,
    • "sgw_replication_processed_sequence_len_post_cleanup": 0,
    • "sgw_replication_pull_attachment_pull_bytes": 0,
    • "sgw_replication_pull_attachment_pull_count": 0,
    • "sgw_replication_pull_max_pending": 0,
    • "sgw_replication_pull_norev_send_count": 0,
    • "sgw_replication_pull_num_pull_repl_active_continuous": 0,
    • "sgw_replication_pull_num_pull_repl_active_one_shot": 0,
    • "sgw_replication_pull_num_pull_repl_caught_up": 0,
    • "sgw_replication_pull_num_pull_repl_since_zero": 0,
    • "sgw_replication_pull_num_pull_repl_total_caught_up": 0,
    • "sgw_replication_pull_num_pull_repl_total_continuous": 0,
    • "sgw_replication_pull_num_pull_repl_total_one_shot": 0,
    • "sgw_replication_pull_num_replications_active": 0,
    • "sgw_replication_pull_replacement_rev_send_count": 0,
    • "sgw_replication_pull_request_changes_count": 0,
    • "sgw_replication_pull_request_changes_time": 0,
    • "sgw_replication_pull_rev_error_count": 0,
    • "sgw_replication_pull_rev_processing_time": 0,
    • "sgw_replication_pull_rev_send_count": 0,
    • "sgw_replication_pull_rev_send_latency": 0,
    • "sgw_replication_push_attachment_push_bytes": 0,
    • "sgw_replication_push_attachment_push_count": 0,
    • "sgw_replication_push_doc_push_count": 0,
    • "sgw_replication_push_doc_push_error_count": 0,
    • "sgw_replication_push_propose_change_count": 0,
    • "sgw_replication_push_propose_change_time": 0,
    • "sgw_replication_push_write_processing_time": 0,
    • "sgw_replication_push_write_throttled_count": 0,
    • "sgw_replication_push_write_throttled_time": 0,
    • "sgw_replication_sgr_conflict_resolved_local_count": 0,
    • "sgw_replication_sgr_conflict_resolved_merge_count": 0,
    • "sgw_replication_sgr_conflict_resolved_remote_count": 0,
    • "sgw_replication_sgr_deltas_recv": 0,
    • "sgw_replication_sgr_deltas_requested": 0,
    • "sgw_replication_sgr_deltas_sent": 0,
    • "sgw_replication_sgr_docs_checked_recv": 0,
    • "sgw_replication_sgr_docs_checked_sent": 0,
    • "sgw_replication_sgr_num_attachment_bytes_pulled": 0,
    • "sgw_replication_sgr_num_attachment_bytes_pushed": 0,
    • "sgw_replication_sgr_num_attachments_pulled": 0,
    • "sgw_replication_sgr_num_attachments_pushed": 0,
    • "sgw_replication_sgr_num_connect_attempts_pull": 0,
    • "sgw_replication_sgr_num_connect_attempts_push": 0,
    • "sgw_replication_sgr_num_docs_failed_to_pull": 0,
    • "sgw_replication_sgr_num_docs_failed_to_push": 0,
    • "sgw_replication_sgr_num_docs_pulled": 0,
    • "sgw_replication_sgr_num_docs_purged": 0,
    • "sgw_replication_sgr_num_docs_pushed": 0,
    • "sgw_replication_sgr_num_handlers_panicked": 0,
    • "sgw_replication_sgr_num_reconnects_aborted_pull": 0,
    • "sgw_replication_sgr_num_reconnects_aborted_push": 0,
    • "sgw_replication_sgr_push_conflict_count": 0,
    • "sgw_replication_sgr_push_rejected_count": 0,
    • "sgw_resource_utilization_admin_net_bytes_recv": 0,
    • "sgw_resource_utilization_admin_net_bytes_sent": 0,
    • "sgw_resource_utilization_error_count": 0,
    • "sgw_resource_utilization_go_memstats_heapalloc": 0,
    • "sgw_resource_utilization_go_memstats_heapidle": 0,
    • "sgw_resource_utilization_go_memstats_heapinuse": 0,
    • "sgw_resource_utilization_go_memstats_heapreleased": 0,
    • "sgw_resource_utilization_go_memstats_pausetotalns": 0,
    • "sgw_resource_utilization_go_memstats_stackinuse": 0,
    • "sgw_resource_utilization_go_memstats_stacksys": 0,
    • "sgw_resource_utilization_go_memstats_sys": 0,
    • "sgw_resource_utilization_goroutines_high_watermark": 0,
    • "sgw_resource_utilization_node_cpu_percent_utilization": 0,
    • "sgw_resource_utilization_num_goroutines": 0,
    • "sgw_resource_utilization_process_cpu_percent_utilization": 0,
    • "sgw_resource_utilization_process_memory_resident": 0,
    • "sgw_resource_utilization_pub_net_bytes_recv": 0,
    • "sgw_resource_utilization_pub_net_bytes_sent": 0,
    • "sgw_resource_utilization_system_memory_total": 0,
    • "sgw_resource_utilization_uptime": 0,
    • "sgw_resource_utilization_warn_count": 0,
    • "sgw_security_auth_failed_count": 0,
    • "sgw_security_auth_success_count": 0,
    • "sgw_security_num_access_errors": 0,
    • "sgw_security_num_docs_rejected": 0,
    • "sgw_security_total_auth_time": 0,
    • "sgw_shared_bucket_import_import_cancel_cas": 0,
    • "sgw_shared_bucket_import_import_count": 0,
    • "sgw_shared_bucket_import_import_error_count": 0,
    • "sgw_shared_bucket_import_import_high_seq": 0,
    • "sgw_shared_bucket_import_import_partitions": 0,
    • "sgw_shared_bucket_import_import_processing_time": 0
    }

    JSON

    Response samples

    Content type
    application/json
    {
    • "sgw_audit_num_audits_filtered_by_role": 0,
    • "sgw_audit_num_audits_filtered_by_user": 0,
    • "sgw_audit_num_audits_logged": 0,
    • "sgw_cache_abandoned_seqs": 0,
    • "sgw_cache_chan_cache_active_revs": 0,
    • "sgw_cache_chan_cache_bypass_count": 0,
    • "sgw_cache_chan_cache_channels_added": 0,
    • "sgw_cache_chan_cache_channels_evicted_inactive": 0,
    • "sgw_cache_chan_cache_channels_evicted_nru": 0,
    • "sgw_cache_chan_cache_compact_count": 0,
    • "sgw_cache_chan_cache_compact_time": 0,
    • "sgw_cache_chan_cache_hits": 0,
    • "sgw_cache_chan_cache_max_entries": 0,
    • "sgw_cache_chan_cache_misses": 0,
    • "sgw_cache_chan_cache_num_channels": 0,
    • "sgw_cache_chan_cache_pending_queries": 0,
    • "sgw_cache_chan_cache_removal_revs": 0,
    • "sgw_cache_chan_cache_tombstone_revs": 0,
    • "sgw_cache_current_skipped_seq_count": 0,
    • "sgw_cache_high_seq_cached": 0,
    • "sgw_cache_high_seq_stable": 0,
    • "sgw_cache_non_mobile_ignored_count": 0,
    • "sgw_cache_num_active_channels": 0,
    • "sgw_cache_num_skipped_seqs": 0,
    • "sgw_cache_pending_seq_len": 0,
    • "sgw_cache_rev_cache_bypass": 0,
    • "sgw_cache_rev_cache_hits": 0,
    • "sgw_cache_rev_cache_misses": 0,
    • "sgw_cache_revision_cache_num_items": 0,
    • "sgw_cache_revision_cache_total_memory": 0,
    • "sgw_cache_skipped_seq_cap": 0,
    • "sgw_cache_skipped_seq_len": 0,
    • "sgw_cache_view_queries": 0,
    • "sgw_collection_doc_reads_bytes": 0,
    • "sgw_collection_doc_writes_bytes": 0,
    • "sgw_collection_import_count": 0,
    • "sgw_collection_num_doc_reads": 0,
    • "sgw_collection_num_doc_writes": 0,
    • "sgw_collection_sync_function_count": 0,
    • "sgw_collection_sync_function_exception_count": 0,
    • "sgw_collection_sync_function_reject_access_count": 0,
    • "sgw_collection_sync_function_reject_count": 0,
    • "sgw_collection_sync_function_time": 0,
    • "sgw_config_database_config_bucket_mismatches": 0,
    • "sgw_config_database_config_collection_conflicts": 0,
    • "sgw_database_compaction_attachment_start_time": 0,
    • "sgw_database_compaction_tombstone_start_time": 0,
    • "sgw_database_conflict_write_count": 0,
    • "sgw_database_crc32c_match_count": 0,
    • "sgw_database_dcp_caching_count": 0,
    • "sgw_database_dcp_caching_time": 0,
    • "sgw_database_dcp_received_count": 0,
    • "sgw_database_dcp_received_time": 0,
    • "sgw_database_doc_reads_bytes_blip": 0,
    • "sgw_database_doc_writes_bytes": 0,
    • "sgw_database_doc_writes_bytes_blip": 0,
    • "sgw_database_doc_writes_xattr_bytes": 0,
    • "sgw_database_high_seq_feed": 0,
    • "sgw_database_http_bytes_written": 0,
    • "sgw_database_num_attachments_compacted": 0,
    • "sgw_database_num_doc_reads_blip": 0,
    • "sgw_database_num_doc_reads_rest": 0,
    • "sgw_database_num_doc_writes": 0,
    • "sgw_database_num_idle_kv_ops": 0,
    • "sgw_database_num_public_rest_requests": 0,
    • "sgw_database_num_replications_active": 0,
    • "sgw_database_num_replications_rejected_limit": 0,
    • "sgw_database_num_replications_total": 0,
    • "sgw_database_num_tombstones_compacted": 0,
    • "sgw_database_public_rest_bytes_read": 0,
    • "sgw_database_replication_bytes_received": 0,
    • "sgw_database_replication_bytes_sent": 0,
    • "sgw_database_sequence_assigned_count": 0,
    • "sgw_database_sequence_get_count": 0,
    • "sgw_database_sequence_incr_count": 0,
    • "sgw_database_sequence_released_count": 0,
    • "sgw_database_sequence_reserved_count": 0,
    • "sgw_database_sync_function_count": 0,
    • "sgw_database_sync_function_exception_count": 0,
    • "sgw_database_sync_function_time": 0,
    • "sgw_database_total_sync_time": 0,
    • "sgw_database_warn_channel_name_size_count": 0,
    • "sgw_database_warn_channels_per_doc_count": 0,
    • "sgw_database_warn_grants_per_doc_count": 0,
    • "sgw_database_warn_xattr_size_count": 0,
    • "sgw_delta_sync_delta_cache_hit": 0,
    • "sgw_delta_sync_delta_pull_replication_count": 0,
    • "sgw_delta_sync_delta_push_doc_count": 0,
    • "sgw_delta_sync_delta_sync_miss": 0,
    • "sgw_delta_sync_deltas_requested": 0,
    • "sgw_delta_sync_deltas_sent": 0,
    • "sgw_gsi_views__count": 0,
    • "sgw_gsi_views__error_count": 0,
    • "sgw_gsi_views__time": 0,
    • "sgw_replication_expected_sequence_len": 0,
    • "sgw_replication_expected_sequence_len_post_cleanup": 0,
    • "sgw_replication_processed_sequence_len": 0,
    • "sgw_replication_processed_sequence_len_post_cleanup": 0,
    • "sgw_replication_pull_attachment_pull_bytes": 0,
    • "sgw_replication_pull_attachment_pull_count": 0,
    • "sgw_replication_pull_max_pending": 0,
    • "sgw_replication_pull_norev_send_count": 0,
    • "sgw_replication_pull_num_pull_repl_active_continuous": 0,
    • "sgw_replication_pull_num_pull_repl_active_one_shot": 0,
    • "sgw_replication_pull_num_pull_repl_caught_up": 0,
    • "sgw_replication_pull_num_pull_repl_since_zero": 0,
    • "sgw_replication_pull_num_pull_repl_total_caught_up": 0,
    • "sgw_replication_pull_num_pull_repl_total_continuous": 0,
    • "sgw_replication_pull_num_pull_repl_total_one_shot": 0,
    • "sgw_replication_pull_num_replications_active": 0,
    • "sgw_replication_pull_replacement_rev_send_count": 0,
    • "sgw_replication_pull_request_changes_count": 0,
    • "sgw_replication_pull_request_changes_time": 0,
    • "sgw_replication_pull_rev_error_count": 0,
    • "sgw_replication_pull_rev_processing_time": 0,
    • "sgw_replication_pull_rev_send_count": 0,
    • "sgw_replication_pull_rev_send_latency": 0,
    • "sgw_replication_push_attachment_push_bytes": 0,
    • "sgw_replication_push_attachment_push_count": 0,
    • "sgw_replication_push_doc_push_count": 0,
    • "sgw_replication_push_doc_push_error_count": 0,
    • "sgw_replication_push_propose_change_count": 0,
    • "sgw_replication_push_propose_change_time": 0,
    • "sgw_replication_push_write_processing_time": 0,
    • "sgw_replication_push_write_throttled_count": 0,
    • "sgw_replication_push_write_throttled_time": 0,
    • "sgw_replication_sgr_conflict_resolved_local_count": 0,
    • "sgw_replication_sgr_conflict_resolved_merge_count": 0,
    • "sgw_replication_sgr_conflict_resolved_remote_count": 0,
    • "sgw_replication_sgr_deltas_recv": 0,
    • "sgw_replication_sgr_deltas_requested": 0,
    • "sgw_replication_sgr_deltas_sent": 0,
    • "sgw_replication_sgr_docs_checked_recv": 0,
    • "sgw_replication_sgr_docs_checked_sent": 0,
    • "sgw_replication_sgr_num_attachment_bytes_pulled": 0,
    • "sgw_replication_sgr_num_attachment_bytes_pushed": 0,
    • "sgw_replication_sgr_num_attachments_pulled": 0,
    • "sgw_replication_sgr_num_attachments_pushed": 0,
    • "sgw_replication_sgr_num_connect_attempts_pull": 0,
    • "sgw_replication_sgr_num_connect_attempts_push": 0,
    • "sgw_replication_sgr_num_docs_failed_to_pull": 0,
    • "sgw_replication_sgr_num_docs_failed_to_push": 0,
    • "sgw_replication_sgr_num_docs_pulled": 0,
    • "sgw_replication_sgr_num_docs_purged": 0,
    • "sgw_replication_sgr_num_docs_pushed": 0,
    • "sgw_replication_sgr_num_handlers_panicked": 0,
    • "sgw_replication_sgr_num_reconnects_aborted_pull": 0,
    • "sgw_replication_sgr_num_reconnects_aborted_push": 0,
    • "sgw_replication_sgr_push_conflict_count": 0,
    • "sgw_replication_sgr_push_rejected_count": 0,
    • "sgw_resource_utilization_admin_net_bytes_recv": 0,
    • "sgw_resource_utilization_admin_net_bytes_sent": 0,
    • "sgw_resource_utilization_error_count": 0,
    • "sgw_resource_utilization_go_memstats_heapalloc": 0,
    • "sgw_resource_utilization_go_memstats_heapidle": 0,
    • "sgw_resource_utilization_go_memstats_heapinuse": 0,
    • "sgw_resource_utilization_go_memstats_heapreleased": 0,
    • "sgw_resource_utilization_go_memstats_pausetotalns": 0,
    • "sgw_resource_utilization_go_memstats_stackinuse": 0,
    • "sgw_resource_utilization_go_memstats_stacksys": 0,
    • "sgw_resource_utilization_go_memstats_sys": 0,
    • "sgw_resource_utilization_goroutines_high_watermark": 0,
    • "sgw_resource_utilization_node_cpu_percent_utilization": 0,
    • "sgw_resource_utilization_num_goroutines": 0,
    • "sgw_resource_utilization_process_cpu_percent_utilization": 0,
    • "sgw_resource_utilization_process_memory_resident": 0,
    • "sgw_resource_utilization_pub_net_bytes_recv": 0,
    • "sgw_resource_utilization_pub_net_bytes_sent": 0,
    • "sgw_resource_utilization_system_memory_total": 0,
    • "sgw_resource_utilization_uptime": 0,
    • "sgw_resource_utilization_warn_count": 0,
    • "sgw_security_auth_failed_count": 0,
    • "sgw_security_auth_success_count": 0,
    • "sgw_security_num_access_errors": 0,
    • "sgw_security_num_docs_rejected": 0,
    • "sgw_security_total_auth_time": 0,
    • "sgw_shared_bucket_import_import_cancel_cas": 0,
    • "sgw_shared_bucket_import_import_count": 0,
    • "sgw_shared_bucket_import_import_error_count": 0,
    • "sgw_shared_bucket_import_import_high_seq": 0,
    • "sgw_shared_bucket_import_import_partitions": 0,
    • "sgw_shared_bucket_import_import_processing_time": 0
    }

    JSON

    Endpoints for use with JSON metrics

    -

    Get all Sync Gateway statistics in JSON format

    Get all Sync Gateway statistics in JSON format

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    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:

      @@ -340,29 +364,29 @@
    • Sync Gateway Dev Ops
    • External Stats Reader
    -

    Responses

    Server

    Response samples

    Content type
    application/json
    {
    • "cmdline": { },
    • "memstats": { },
    • "cb": { },
    • "mc": { },
    • "syncGateway_changeCache": {
      },
    • "syncGateway_db": {
      },
    • "syncgateway": {
      }
    }

    Server

    Endpoints for managing the REST API

    -

    Check if API is available

    Returns OK status if API is available.

    -

    Responses

    Response samples

    Content type
    text/plain
    OK

    Check if API is available

    Returns OK status if API is available.

    -

    Responses

    +

    Check if API is available

    Returns OK status if API is available.

    +

    Responses

    Response samples

    Content type
    text/plain
    OK

    Check if API is available

    Returns OK status if API is available.

    +

    Responses

    -
    API docs by Redocly
    API docs by Redocly

    Sync Gateway Public REST API (3.2)

    Download OpenAPI specification:Download

    License: Business Source License 1.1 (BSL)
    ⬆️ Public REST API Overview

    Introduction

    Sync Gateway Public REST API (3.2)

    Download OpenAPI specification:

    License: Business Source License 1.1 (BSL)
    ⬆️ Public REST API Overview

    Introduction

    Sync Gateway manages access and synchronization between Couchbase Lite and Couchbase Server. The Sync Gateway Public REST API is used for client replication.

    -

    Server

    Server

    Manage server activities

    -

    Get server information

    Returns information about the Sync Gateway node.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "ADMIN": true,
    • "couchdb": "Welcome",
    • "vendor": {
      },
    • "version": "Couchbase Sync Gateway/3.1.0(1;a765231) EE",
    • "persistent_config": true
    }

    Check if server online

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

    -

    Responses

    Check if API is available

    Returns OK status if API is available.

    -

    Responses

    Response samples

    Content type
    text/plain
    OK

    Check if API is available

    Returns OK status if API is available.

    -

    Responses

    Database Management

    Get server information

    Returns information about the Sync Gateway node.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "ADMIN": true,
    • "couchdb": "Welcome",
    • "vendor": {
      },
    • "version": "Couchbase Sync Gateway/3.1.0(1;a765231) EE",
    • "persistent_config": true
    }

    Check if server online

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

    +

    Responses

    Check if API is available

    Returns OK status if API is available.

    +

    Responses

    Response samples

    Content type
    text/plain
    OK

    Check if API is available

    Returns OK status if API is available.

    +

    Responses

    Database Management

    Create and manage Sync Gateway databases

    -

    Create DB public API stub

    A stub that always returns an error on the Public API, for createTarget/CouchDB compatibility.

    -
    path Parameters
    targetdb
    required
    string

    The database name to target.

    -

    Responses

    Get database information

    Retrieve information about the database.

    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "db_name": "db",
    • "update_seq": 123456,
    • "committed_update_seq": 123456,
    • "instance_start_time": 1644600082279583,
    • "compact_running": true,
    • "purge_seq": 0,
    • "disk_format_version": 0,
    • "state": "Online",
    • "server_uuid": "995618a6a6cc9ac79731bd13240e19b5"
    }

    Check if database exists

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

    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Get changes list

    Create DB public API stub

    A stub that always returns an error on the Public API, for createTarget/CouchDB compatibility.

    +
    path Parameters
    targetdb
    required
    string

    The database name to target.

    +

    Responses

    Get database information

    Retrieve information about the database.

    +
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "db_name": "db",
    • "update_seq": 123456,
    • "committed_update_seq": 123456,
    • "instance_start_time": 1644600082279583,
    • "compact_running": true,
    • "purge_seq": 0,
    • "disk_format_version": 0,
    • "state": "Online",
    • "server_uuid": "995618a6a6cc9ac79731bd13240e19b5"
    }

    Check if database exists

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

    +
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Get changes list

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    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.

    -
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

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

    -
    query Parameters
    limit
    integer

    Maximum number of changes to return.

    -
    since
    string

    Starts the results from the change immediately after the given sequence ID. Sequence IDs should be considered opaque; they come from the last_seq property of a prior response.

    -
    style
    string
    Default: "main_only"
    Enum: "main_only" "all_docs"

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

    -
    active_only
    boolean
    Default: "false"

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

    -
    include_docs
    boolean

    Include the body associated with each document.

    -
    revocations
    boolean

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

    -
    filter
    string
    Enum: "sync_gateway/bychannel" "_doc_ids"

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

    -
    channels
    string

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

    -
    doc_ids
    Array of strings

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

    -
    heartbeat
    integer >= 25000
    Default: 0

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

    -
    timeout
    integer [ 0 .. 900000 ]
    Default: 300000

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

    -
    feed
    string
    Default: "normal"
    Enum: "normal" "longpoll" "continuous" "websocket"

    The type of changes feed to use.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "results": [
      ],
    • "last_seq": "string"
    }

    Get changes list

    query Parameters
    limit
    integer

    Maximum number of changes to return.

    +
    since
    string

    Starts the results from the change immediately after the given sequence ID. Sequence IDs should be considered opaque; they come from the last_seq property of a prior response.

    +
    style
    string
    Default: "main_only"
    Enum: "main_only" "all_docs"

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

    +
    active_only
    boolean
    Default: "false"

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

    +
    include_docs
    boolean

    Include the body associated with each document.

    +
    revocations
    boolean

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

    +
    filter
    string
    Enum: "sync_gateway/bychannel" "_doc_ids"

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

    +
    channels
    string

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

    +
    doc_ids
    Array of strings

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

    +
    heartbeat
    integer >= 25000
    Default: 0

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

    +
    timeout
    integer [ 0 .. 900000 ]
    Default: 300000

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

    +
    feed
    string
    Default: "normal"
    Enum: "normal" "longpoll" "continuous" "websocket"

    The type of changes feed to use.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "results": [
      ],
    • "last_seq": "string"
    }

    Get changes list

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

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    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.

    -
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

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

    -
    Request Body schema: application/json
    limit
    string

    Maximum number of changes to return.

    -
    style
    string

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

    -
    active_only
    string

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

    -
    include_docs
    boolean

    Include the body associated with each document.

    -
    revocations
    string

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

    -
    filter
    string

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

    -
    channels
    string

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

    -
    doc_ids
    string

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

    -
    heartbeat
    string

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

    -
    timeout
    string

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

    -
    feed
    string

    The type of changes feed to use.

    -

    Responses

    Request samples

    Content type
    application/json
    {
    • "limit": "string",
    • "style": "string",
    • "active_only": "string",
    • "include_docs": true,
    • "revocations": "string",
    • "filter": "string",
    • "channels": "string",
    • "doc_ids": "string",
    • "heartbeat": "string",
    • "timeout": "string",
    • "feed": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "results": [
      ],
    • "last_seq": "string"
    }

    /{db}/_changes

    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    Request Body schema: application/json
    limit
    string

    Maximum number of changes to return.

    +
    style
    string

    Controls whether to return the current winning revision (main_only) or all the leaf revision including conflicts and deleted former conflicts (all_docs).

    +
    active_only
    string

    Set true to exclude deleted documents and notifications for documents the user no longer has access to from the changes feed.

    +
    include_docs
    boolean

    Include the body associated with each document.

    +
    revocations
    string

    If true, revocation messages will be sent on the changes feed.

    +
    filter
    string

    Set a filter to either filter by channels or document IDs.

    +
    channels
    string

    A comma-separated list of channel names to filter the response to only the channels specified. To use this option, the filter query option must be set to sync_gateway/bychannels.

    +
    doc_ids
    string

    A valid JSON array of document IDs to filter the documents in the response to only the documents specified. To use this option, the filter query option must be set to _doc_ids and the feed parameter must be normal.

    +
    heartbeat
    string

    The interval (in milliseconds) to send an empty line (CRLF) in the response. This is to help prevent gateways from deciding the socket is idle and therefore closing it. This is only applicable to feed=longpoll or feed=continuous. This will override any timeouts to keep the feed alive indefinitely. Setting to 0 results in no heartbeat. The maximum heartbeat can be set in the server replication configuration.

    +
    timeout
    string

    This is the maximum period (in milliseconds) to wait for a change before the response is sent, even if there are no results. This is only applicable for feed=longpoll or feed=continuous changes feeds. Setting to 0 results in no timeout.

    +
    feed
    string

    The type of changes feed to use.

    +

    Responses

    Request samples

    Content type
    application/json
    {
    • "limit": "string",
    • "style": "string",
    • "active_only": "string",
    • "include_docs": true,
    • "revocations": "string",
    • "filter": "string",
    • "channels": "string",
    • "doc_ids": "string",
    • "heartbeat": "string",
    • "timeout": "string",
    • "feed": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "results": [
      ],
    • "last_seq": "string"
    }

    /{db}/_changes

    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

    A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection.

    -

    Responses

    /{db}/_ensure_full_commit

    This endpoint is non-functional but is present for CouchDB compatibility.

    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "instance_start_time": 1644600082279583,
    • "ok": true
    }

    Compare revisions to what is in the database

    Takes a set of document IDs, each with a set of revision IDs. For each document, an array of unknown revisions are returned with an array of known revisions that may be recent ancestors.

    -
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    Responses

    /{db}/_ensure_full_commit

    This endpoint is non-functional but is present for CouchDB compatibility.

    +
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "instance_start_time": 1644600082279583,
    • "ok": true
    }

    Compare revisions to what is in the database

    Takes a set of document IDs, each with a set of revision IDs. For each document, an array of unknown revisions are returned with an array of known revisions that may be recent ancestors.

    +
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

    A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection.

    -
    Request Body schema: application/json
    docid
    Array of strings

    The document ID with an array of revisions to use for the comparison.

    -

    Responses

    Request samples

    Content type
    application/json
    {
    • "docid": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "docid": {
      }
    }

    Session

    Request Body schema: application/json
    docid
    Array of strings

    The document ID with an array of revisions to use for the comparison.

    +

    Responses

    Request samples

    Content type
    application/json
    {
    • "docid": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "docid": {
      }
    }

    Session

    Manage user sessions

    -

    Get information about the current user

    This will get the information about the current user.

    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "authentication_handlers": [
      ],
    • "ok": true,
    • "userCtx": {
      }
    }

    Create a new user session

    Get information about the current user

    This will get the information about the current user.

    +
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "authentication_handlers": [
      ],
    • "ok": true,
    • "userCtx": {
      }
    }

    Create a new user session

    Generates a login session for the user based on the credentials provided in the request body or if that fails (due to invalid credentials or none provided at all), generates the new session for the currently authenticated user instead. On a successful session creation, a session cookie is stored to keep the user authenticated for future API calls.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    Generates a login session for the user based on the credentials provided in the request body or if that fails (due to invalid credentials or none provided at all), generates the new session for the currently authenticated user instead. On a successful session creation, a session cookie is stored to keep the user authenticated for future API calls.

    If CORS is enabled, the origin must match an allowed login origin otherwise an error will be returned.

    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -
    Request Body schema: application/json

    The body can depend on if using the Public or Admin APIs.

    -
    name
    string

    User name to generate the session for.

    -
    password
    string

    Password of the user to generate the session for.

    -

    Responses

    Request samples

    Content type
    application/json
    {
    • "name": "string",
    • "password": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "authentication_handlers": [
      ],
    • "ok": true,
    • "userCtx": {
      }
    }

    Log out

    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +
    Request Body schema: application/json

    The body can depend on if using the Public or Admin APIs.

    +
    name
    string

    User name to generate the session for.

    +
    password
    string

    Password of the user to generate the session for.

    +

    Responses

    Request samples

    Content type
    application/json
    {
    • "name": "string",
    • "password": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "authentication_handlers": [
      ],
    • "ok": true,
    • "userCtx": {
      }
    }

    Log out

    Invalidates the session for the currently authenticated user and removes their session cookie.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    Invalidates the session for the currently authenticated user and removes their session cookie.

    If CORS is enabled, the origin must match an allowed login origin otherwise an error will be returned.

    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    /{db}/_session

    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Authentication

    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    /{db}/_session

    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Authentication

    Manage OpenID Connect Authentication

    -

    Create a new Facebook-based session Deprecated

    Create a new Facebook-based session Deprecated

    Creates a new session based on a Facebook user. On a successful session creation, a session cookie is stored to keep the user authenticated for future API calls.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    Creates a new session based on a Facebook user. On a successful session creation, a session cookie is stored to keep the user authenticated for future API calls.

    If CORS is enabled, the origin must match an allowed login origin otherwise an error will be returned.

    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -
    Request Body schema: application/json
    access_token
    required
    string

    Facebook access token to base the new session on.

    -

    Responses

    Request samples

    Content type
    application/json
    {
    • "access_token": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    Create a new Google-based session Deprecated

    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +
    Request Body schema: application/json
    access_token
    required
    string

    Facebook access token to base the new session on.

    +

    Responses

    Request samples

    Content type
    application/json
    {
    • "access_token": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    Create a new Google-based session Deprecated

    Creates a new session based on a Google user. On a successful session creation, a session cookie is stored to keep the user authenticated for future API calls.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    Creates a new session based on a Google user. On a successful session creation, a session cookie is stored to keep the user authenticated for future API calls.

    If CORS is enabled, the origin must match an allowed login origin otherwise an error will be returned.

    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -
    Request Body schema: application/json
    id_token
    required
    string

    Google ID token to base the new session on.

    -

    Responses

    Request samples

    Content type
    application/json
    {
    • "id_token": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    OpenID Connect authentication initiation via Location header redirect

    Called by clients to initiate the OpenID Connect Authorization Code Flow. Redirects to the OpenID Connect provider if successful.

    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -
    query Parameters
    provider
    string

    The OpenID Connect provider to use for authentication. The list of providers are defined in the Sync Gateway config. If left empty, the default provider will be used.

    -
    offline
    string

    If true, the OpenID Connect provider is requested to confirm with the user the permissions requested and refresh the OIDC token. To do this, access_type=offline and prompt=consent is set on the redirection link.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    OpenID Connect authentication initiation via WWW-Authenticate header

    Called by clients to initiate the OpenID Connect Authorization Code Flow. This will establish a connection with the provider, then put the redirect URL in the WWW-Authenticate header.

    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -
    query Parameters
    provider
    string

    The OpenID Connect provider to use for authentication. The list of providers are defined in the Sync Gateway config. If left empty, the default provider will be used.

    -
    offline
    string

    If true, the OpenID Connect provider is requested to confirm with the user the permissions requested and refresh the OIDC token. To do this, access_type=offline and prompt=consent is set on the redirection link.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    OpenID Connect authentication callback

    The callback URL that the client is redirected to after authenticating with the OpenID Connect provider.

    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -
    query Parameters
    error
    string

    The OpenID Connect error, if any occurred.

    -
    code
    required
    string

    The OpenID Connect authentication code.

    -
    provider
    string

    The OpenID Connect provider to use for authentication. The list of providers are defined in the Sync Gateway config. If left empty, the default provider will be used.

    -
    state
    string

    The OpenID Connect state to verify against the state cookie. This is used to prevent cross-site request forgery (CSRF). This is not required if disable_callback_state=true for the provider config (NOT recommended).

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "id_token": "string",
    • "refresh_token": "string",
    • "session_id": "string",
    • "name": "string",
    • "access_token": "string",
    • "token_type": "string",
    • "expires_in": 0
    }

    OpenID Connect token refresh

    Refresh the OpenID Connect token based on the provided refresh token.

    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -
    query Parameters
    refresh_token
    required
    string

    The OpenID Connect refresh token.

    -
    provider
    string

    The OpenID Connect provider to use for authentication. The list of providers are defined in the Sync Gateway config. If left empty, the default provider will be used.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "id_token": "string",
    • "refresh_token": "string",
    • "session_id": "string",
    • "name": "string",
    • "access_token": "string",
    • "token_type": "string",
    • "expires_in": 0
    }

    OpenID Connect mock provider

    Mock an OpenID Connect provider response for testing purposes. This returns a response that is the same structure as what Sync Gateway expects from an OIDC provider after initiating OIDC authentication.

    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "issuer": "string",
    • "authorization_endpoint": "string",
    • "token_endpoint": "string",
    • "jwks_uri": "string",
    • "userinfo_endpoint": "string",
    • "id_token_signing_alg_values_supported": "string",
    • "response_types_supported": "string",
    • "subject_types_supported": "string",
    • "scopes_supported": "string",
    • "claims_supported": "string",
    • "token_endpoint_auth_methods_supported": "string"
    }

    OpenID Connect mock login page

    Show a mock OpenID Connect login page for the client to log in to.

    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -
    query Parameters
    scope
    required
    string

    The OpenID Connect authentication scope.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    OpenID Connect mock login page

    Show a mock OpenID Connect login page for the client to log in to.

    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -
    query Parameters
    scope
    required
    string

    The OpenID Connect authentication scope.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    OpenID Connect mock token

    Return a mock OpenID Connect token for the OIDC authentication flow.

    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -
    Request Body schema: application/json
    grant_type
    required
    string

    The grant type of the token to request. Can either be an authorization_code or refresh_token.

    -
    code
    string

    grant_type=authorization_code only: The OpenID Connect authentication token.

    -
    refresh_token
    string

    grant_type=refresh_token only: The OpenID Connect refresh token.

    -

    Responses

    Request samples

    Content type
    application/json
    {
    • "grant_type": "string",
    • "code": "string",
    • "refresh_token": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "access_token": "string",
    • "token_type": "string",
    • "refresh_token": "string",
    • "expires_in": "string",
    • "id_token": "string"
    }

    OpenID Connect public certificates for signing keys

    Return a mock OpenID Connect public key to be used as signing keys.

    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "keys": [
      ]
    }

    OpenID Connect mock login page handler

    Used to handle the login page displayed for the GET /{db}/_oidc_testing/authorize endpoint.

    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -
    query Parameters
    redirect_uri
    string

    The Sync Gateway OpenID Connect callback URL.

    -
    scope
    required
    string

    The OpenID Connect authentication scope.

    -
    username
    required
    string
    tokenttl
    required
    integer
    identity-token-formats
    required
    string
    authenticated
    required
    string

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    OpenID Connect mock login page handler

    Used to handle the login page displayed for the GET /{db}/_oidc_testing/authorize endpoint.

    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -
    query Parameters
    redirect_uri
    string

    The Sync Gateway OpenID Connect callback URL.

    -
    scope
    required
    string

    The OpenID Connect authentication scope.

    -
    Request Body schema: application/json

    Properties passed from the OpenID Connect mock login page to the handler

    -
    username
    required
    string
    tokenttl
    required
    string
    identity-token-formats
    required
    string
    authenticated
    required
    string

    Responses

    Request samples

    Content type
    application/json
    {
    • "username": "string",
    • "tokenttl": "string",
    • "identity-token-formats": "string",
    • "authenticated": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Document

    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +
    Request Body schema: application/json
    id_token
    required
    string

    Google ID token to base the new session on.

    +

    Responses

    Request samples

    Content type
    application/json
    {
    • "id_token": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    OpenID Connect authentication initiation via Location header redirect

    Called by clients to initiate the OpenID Connect Authorization Code Flow. Redirects to the OpenID Connect provider if successful.

    +
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +
    query Parameters
    provider
    string

    The OpenID Connect provider to use for authentication. The list of providers are defined in the Sync Gateway config. If left empty, the default provider will be used.

    +
    offline
    string

    If true, the OpenID Connect provider is requested to confirm with the user the permissions requested and refresh the OIDC token. To do this, access_type=offline and prompt=consent is set on the redirection link.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    OpenID Connect authentication initiation via WWW-Authenticate header

    Called by clients to initiate the OpenID Connect Authorization Code Flow. This will establish a connection with the provider, then put the redirect URL in the WWW-Authenticate header.

    +
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +
    query Parameters
    provider
    string

    The OpenID Connect provider to use for authentication. The list of providers are defined in the Sync Gateway config. If left empty, the default provider will be used.

    +
    offline
    string

    If true, the OpenID Connect provider is requested to confirm with the user the permissions requested and refresh the OIDC token. To do this, access_type=offline and prompt=consent is set on the redirection link.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    OpenID Connect authentication callback

    The callback URL that the client is redirected to after authenticating with the OpenID Connect provider.

    +
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +
    query Parameters
    error
    string

    The OpenID Connect error, if any occurred.

    +
    code
    required
    string

    The OpenID Connect authentication code.

    +
    provider
    string

    The OpenID Connect provider to use for authentication. The list of providers are defined in the Sync Gateway config. If left empty, the default provider will be used.

    +
    state
    string

    The OpenID Connect state to verify against the state cookie. This is used to prevent cross-site request forgery (CSRF). This is not required if disable_callback_state=true for the provider config (NOT recommended).

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "id_token": "string",
    • "refresh_token": "string",
    • "session_id": "string",
    • "name": "string",
    • "access_token": "string",
    • "token_type": "string",
    • "expires_in": 0
    }

    OpenID Connect token refresh

    Refresh the OpenID Connect token based on the provided refresh token.

    +
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +
    query Parameters
    refresh_token
    required
    string

    The OpenID Connect refresh token.

    +
    provider
    string

    The OpenID Connect provider to use for authentication. The list of providers are defined in the Sync Gateway config. If left empty, the default provider will be used.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "id_token": "string",
    • "refresh_token": "string",
    • "session_id": "string",
    • "name": "string",
    • "access_token": "string",
    • "token_type": "string",
    • "expires_in": 0
    }

    OpenID Connect mock provider

    Mock an OpenID Connect provider response for testing purposes. This returns a response that is the same structure as what Sync Gateway expects from an OIDC provider after initiating OIDC authentication.

    +
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "issuer": "string",
    • "authorization_endpoint": "string",
    • "token_endpoint": "string",
    • "jwks_uri": "string",
    • "userinfo_endpoint": "string",
    • "id_token_signing_alg_values_supported": "string",
    • "response_types_supported": "string",
    • "subject_types_supported": "string",
    • "scopes_supported": "string",
    • "claims_supported": "string",
    • "token_endpoint_auth_methods_supported": "string"
    }

    OpenID Connect mock login page

    Show a mock OpenID Connect login page for the client to log in to.

    +
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +
    query Parameters
    scope
    required
    string

    The OpenID Connect authentication scope.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    OpenID Connect mock login page

    Show a mock OpenID Connect login page for the client to log in to.

    +
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +
    query Parameters
    scope
    required
    string

    The OpenID Connect authentication scope.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    OpenID Connect mock token

    Return a mock OpenID Connect token for the OIDC authentication flow.

    +
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +
    Request Body schema: application/json
    grant_type
    required
    string

    The grant type of the token to request. Can either be an authorization_code or refresh_token.

    +
    code
    string

    grant_type=authorization_code only: The OpenID Connect authentication token.

    +
    refresh_token
    string

    grant_type=refresh_token only: The OpenID Connect refresh token.

    +

    Responses

    Request samples

    Content type
    application/json
    {
    • "grant_type": "string",
    • "code": "string",
    • "refresh_token": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "access_token": "string",
    • "token_type": "string",
    • "refresh_token": "string",
    • "expires_in": "string",
    • "id_token": "string"
    }

    OpenID Connect public certificates for signing keys

    Return a mock OpenID Connect public key to be used as signing keys.

    +
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "keys": [
      ]
    }

    OpenID Connect mock login page handler

    Used to handle the login page displayed for the GET /{db}/_oidc_testing/authorize endpoint.

    +
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +
    query Parameters
    redirect_uri
    string

    The Sync Gateway OpenID Connect callback URL.

    +
    scope
    required
    string

    The OpenID Connect authentication scope.

    +
    username
    required
    string
    tokenttl
    required
    integer
    identity-token-formats
    required
    string
    authenticated
    required
    string

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    OpenID Connect mock login page handler

    Used to handle the login page displayed for the GET /{db}/_oidc_testing/authorize endpoint.

    +
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +
    query Parameters
    redirect_uri
    string

    The Sync Gateway OpenID Connect callback URL.

    +
    scope
    required
    string

    The OpenID Connect authentication scope.

    +
    Request Body schema: application/json

    Properties passed from the OpenID Connect mock login page to the handler

    +
    username
    required
    string
    tokenttl
    required
    string
    identity-token-formats
    required
    string
    authenticated
    required
    string

    Responses

    Request samples

    Content type
    application/json
    {
    • "username": "string",
    • "tokenttl": "string",
    • "identity-token-formats": "string",
    • "authenticated": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Document

    Create and manage documents

    -

    Create a new document

    Create a new document

    Create a new document in the keyspace.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    Create a new document in the keyspace.

    This will generate a random document ID unless specified in the body.

    A document can have a maximum size of 20MB.

    -
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

    A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection.

    -
    query Parameters
    roundtrip
    boolean

    Block until document has been received by change cache

    -
    Request Body schema: application/json
    _id
    string

    The ID of the document.

    -
    _rev
    string

    The revision of the document.

    -
    _exp
    string
    query Parameters
    roundtrip
    boolean

    Block until document has been received by change cache

    +
    Request Body schema: application/json
    _id
    string

    The ID of the document.

    +
    _rev
    string

    The revision of the document.

    +
    _exp
    string

    Expiry time after which the document will be purged. The expiration time is set and managed on the Couchbase Server document. The value can be specified in two ways; in ISO-8601 format, for example the 6th of July 2022 at 17:00 in the BST timezone would be 2016-07-06T17:00:00+01:00; it can also be specified as a numeric Couchbase Server expiry value. Couchbase Server expiry values are specified as Unix time, and if the desired TTL is below 30 days then it can also represent an interval in seconds from the current time (for example, a value of 5 will remove the document 5 seconds after it is written to Couchbase Server). The document expiration time is returned in the response of GET /{db}/{doc} when show_exp=true is included in the query.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    Expiry time after which the document will be purged. The expiration time is set and managed on the Couchbase Server document. The value can be specified in two ways; in ISO-8601 format, for example the 6th of July 2022 at 17:00 in the BST timezone would be 2016-07-06T17:00:00+01:00; it can also be specified as a numeric Couchbase Server expiry value. Couchbase Server expiry values are specified as Unix time, and if the desired TTL is below 30 days then it can also represent an interval in seconds from the current time (for example, a value of 5 will remove the document 5 seconds after it is written to Couchbase Server). The document expiration time is returned in the response of GET /{db}/{doc} when show_exp=true is included in the query.

    As with the existing explicit purge mechanism, this applies only to the local database; it has nothing to do with replication. This expiration time is not propagated when the document is replicated. The purge of the document does not cause it to be deleted on any other database.

    -
    _deleted
    boolean

    Whether the document is a tombstone or not. If true, it is a tombstone.

    -
    object
    object
    property name*
    additional property
    any

    Responses

    Request samples

    Content type
    application/json
    {
    • "_id": "string",
    • "_rev": "string",
    • "_exp": "string",
    • "_deleted": true,
    • "_revisions": {
      },
    • "_attachments": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "string",
    • "ok": true,
    • "rev": "string"
    }

    Gets all the documents in the database with the given parameters

    Returns all documents in the database based on the specified parameters.

    -
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    		_deleted
    boolean

    Whether the document is a tombstone or not. If true, it is a tombstone.

    +
    object
    object
    property name*
    additional property
    any

    Responses

    Request samples

    Content type
    application/json
    {
    • "_id": "string",
    • "_rev": "string",
    • "_exp": "string",
    • "_deleted": true,
    • "_revisions": {
      },
    • "_attachments": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "string",
    • "ok": true,
    • "rev": "string"
    }

    Gets all the documents in the database with the given parameters

    Returns all documents in the database based on the specified parameters.

    +
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

    A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection.

    -
    query Parameters
    include_docs
    boolean

    Include the body associated with each document.

    -
    channels
    boolean

    Include the channels each document is part of that the calling user also has access too.

    -
    access
    boolean

    Include what user/roles that each document grants access too.

    -
    revs
    boolean

    Include all the revisions for each document under the _revisions property.

    -
    update_seq
    boolean

    Include the document sequence number update_seq property for each document.

    -
    keys
    Array of strings

    An array of document ID strings to filter by.

    -
    startkey
    string

    Return records starting with the specified key.

    -
    endkey
    string

    Stop returning records when this key is reached.

    -
    limit
    number

    This limits the number of result rows returned. Using a value of 0 has the same effect as the value 1.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "rows": [
      ],
    • "total_rows": 0,
    • "update_seq": 0
    }

    Get all the documents in the database using a built-in view

    Returns all documents in the database based on the specified parameters.

    -
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    query Parameters
    include_docs
    boolean

    Include the body associated with each document.

    +
    channels
    boolean

    Include the channels each document is part of that the calling user also has access too.

    +
    access
    boolean

    Include what user/roles that each document grants access too.

    +
    revs
    boolean

    Include all the revisions for each document under the _revisions property.

    +
    update_seq
    boolean

    Include the document sequence number update_seq property for each document.

    +
    keys
    Array of strings

    An array of document ID strings to filter by.

    +
    startkey
    string

    Return records starting with the specified key.

    +
    endkey
    string

    Stop returning records when this key is reached.

    +
    limit
    number

    This limits the number of result rows returned. Using a value of 0 has the same effect as the value 1.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "rows": [
      ],
    • "total_rows": 0,
    • "update_seq": 0
    }

    Get all the documents in the database using a built-in view

    Returns all documents in the database based on the specified parameters.

    +
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

    A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection.

    -
    query Parameters
    include_docs
    boolean

    Include the body associated with each document.

    -
    channels
    boolean

    Include the channels each document is part of that the calling user also has access too.

    -
    access
    boolean

    Include what user/roles that each document grants access too.

    -
    revs
    boolean

    Include all the revisions for each document under the _revisions property.

    -
    update_seq
    boolean

    Include the document sequence number update_seq property for each document.

    -
    startkey
    string

    Return records starting with the specified key.

    -
    endkey
    string

    Stop returning records when this key is reached.

    -
    limit
    number

    This limits the number of result rows returned. Using a value of 0 has the same effect as the value 1.

    -
    Request Body schema: application/json
    keys
    required
    Array of strings

    List of the documents to retrieve.

    -

    Responses

    Request samples

    Content type
    application/json
    {
    • "keys": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "rows": [
      ],
    • "total_rows": 0,
    • "update_seq": 0
    }

    /{db}/_all_docs

    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    query Parameters
    include_docs
    boolean

    Include the body associated with each document.

    +
    channels
    boolean

    Include the channels each document is part of that the calling user also has access too.

    +
    access
    boolean

    Include what user/roles that each document grants access too.

    +
    revs
    boolean

    Include all the revisions for each document under the _revisions property.

    +
    update_seq
    boolean

    Include the document sequence number update_seq property for each document.

    +
    startkey
    string

    Return records starting with the specified key.

    +
    endkey
    string

    Stop returning records when this key is reached.

    +
    limit
    number

    This limits the number of result rows returned. Using a value of 0 has the same effect as the value 1.

    +
    Request Body schema: application/json
    keys
    required
    Array of strings

    List of the documents to retrieve.

    +

    Responses

    Request samples

    Content type
    application/json
    {
    • "keys": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "rows": [
      ],
    • "total_rows": 0,
    • "update_seq": 0
    }

    /{db}/_all_docs

    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

    A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection.

    -
    query Parameters
    include_docs
    boolean

    Include the body associated with each document.

    -
    channels
    boolean

    Include the channels each document is part of that the calling user also has access too.

    -
    access
    boolean

    Include what user/roles that each document grants access too.

    -
    revs
    boolean

    Include all the revisions for each document under the _revisions property.

    -
    update_seq
    boolean

    Include the document sequence number update_seq property for each document.

    -
    keys
    Array of strings

    An array of document ID strings to filter by.

    -
    startkey
    string

    Return records starting with the specified key.

    -
    endkey
    string

    Stop returning records when this key is reached.

    -
    limit
    number

    This limits the number of result rows returned. Using a value of 0 has the same effect as the value 1.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    Bulk document operations

    query Parameters
    include_docs
    boolean

    Include the body associated with each document.

    +
    channels
    boolean

    Include the channels each document is part of that the calling user also has access too.

    +
    access
    boolean

    Include what user/roles that each document grants access too.

    +
    revs
    boolean

    Include all the revisions for each document under the _revisions property.

    +
    update_seq
    boolean

    Include the document sequence number update_seq property for each document.

    +
    keys
    Array of strings

    An array of document ID strings to filter by.

    +
    startkey
    string

    Return records starting with the specified key.

    +
    endkey
    string

    Stop returning records when this key is reached.

    +
    limit
    number

    This limits the number of result rows returned. Using a value of 0 has the same effect as the value 1.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    Bulk document operations

    This will allow multiple documented to be created, updated or deleted in bulk.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    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.

    -
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

    A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection.

    -
    Request Body schema: application/json
    new_edits
    boolean
    Default: true

    This controls whether to assign new revision identifiers to new edits (true) or use the existing ones (false).

    -
    required
    Array of objects

    Responses

    Request samples

    Content type
    application/json
    {
    • "new_edits": true,
    • "docs": [
      ]
    }

    Response samples

    Content type
    application/json
    Example
    [
    • {
      },
    • {
      },
    • {
      }
    ]

    Get multiple documents in a MIME multipart response

    400

    There was a problem with your request

    +

    Request samples

    Content type
    application/json
    {
    • "new_edits": true,
    • "docs": [
      ]
    }

    Response samples

    Content type
    application/json
    Example
    [
    • {
      },
    • {
      },
    • {
      }
    ]

    Get multiple documents in a MIME multipart response

    This request returns any number of documents, as individual bodies in a MIME multipart response.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    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.

    -
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

    A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection.

    -
    query Parameters
    attachments
    boolean
    Default: "false"

    This is for whether to include attachments in each of the documents returned or not.

    -
    revs
    boolean

    Include all the revisions for each document under the _revisions property.

    -
    revs_limit
    integer

    The number of revisions to include in the response from the document history. This parameter only makes a different if the revs query parameter is set to true. The full revision history will be returned if revs is set but this is not.

    -
    header Parameters
    X-Accept-Part-Encoding
    string

    If this header includes gzip then the part HTTP compression encoding will be done.

    -
    Accept-Encoding
    string

    If this header includes gzip then the the HTTP response will be compressed. This takes priority over X-Accept-Part-Encoding. Only part compression will be done if X-Accept-Part-Encoding=gzip and the User-Agent is below 1.2 due to clients not being able to handle full compression.

    -
    Request Body schema: application/json
    required
    Array of objects

    Responses

    Request samples

    Content type
    application/json
    {
    • "docs": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Get local document

    query Parameters
    attachments
    boolean
    Default: "false"

    This is for whether to include attachments in each of the documents returned or not.

    +
    revs
    boolean

    Include all the revisions for each document under the _revisions property.

    +
    revs_limit
    integer

    The number of revisions to include in the response from the document history. This parameter only makes a different if the revs query parameter is set to true. The full revision history will be returned if revs is set but this is not.

    +
    header Parameters
    X-Accept-Part-Encoding
    string

    If this header includes gzip then the part HTTP compression encoding will be done.

    +
    Accept-Encoding
    string

    If this header includes gzip then the the HTTP response will be compressed. This takes priority over X-Accept-Part-Encoding. Only part compression will be done if X-Accept-Part-Encoding=gzip and the User-Agent is below 1.2 due to clients not being able to handle full compression.

    +
    Request Body schema: application/json
    required
    Array of objects

    Responses

    Request samples

    Content type
    application/json
    {
    • "docs": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Get local document

    This request retrieves a local document.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    This request retrieves a local document.

    Local document IDs begin with _local/. Local documents are not replicated or indexed, don't support attachments, and don't save revision histories. In practice they are almost only used by Couchbase Lite's replicator, as a place to store replication checkpoint data.

    -
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

    A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection.

    -
    docid
    required
    string

    The name of the local document ID excluding the _local/ prefix.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    Upsert a local document

    		docid
    required
    string

    The name of the local document ID excluding the _local/ prefix.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    Upsert a local document

    This request creates or updates a local document. Updating a local document requires that the revision ID be put in the body under _rev.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    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.

    -
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

    A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection.

    -
    docid
    required
    string

    The name of the local document ID excluding the _local/ prefix.

    -
    Request Body schema: application/json

    The body of the document

    -
    _rev
    string

    Revision to replace. Required if updating existing local document.

    -

    Responses

    Request samples

    Content type
    application/json
    {
    • "_rev": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "id": "string",
    • "ok": true,
    • "rev": "string"
    }

    Delete a local document

    		docid
    required
    string

    The name of the local document ID excluding the _local/ prefix.

    +
    Request Body schema: application/json

    The body of the document

    +
    _rev
    string

    Revision to replace. Required if updating existing local document.

    +

    Responses

    Request samples

    Content type
    application/json
    {
    • "_rev": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "id": "string",
    • "ok": true,
    • "rev": "string"
    }

    Delete a local document

    This request deletes a local document.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    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.

    -
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

    A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection.

    -
    docid
    required
    string

    The name of the local document ID excluding the _local/ prefix.

    -
    query Parameters
    rev
    required
    string

    The revision ID of the revision to delete.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    Check if local document exists

    		docid
    required
    string

    The name of the local document ID excluding the _local/ prefix.

    +
    query Parameters
    rev
    required
    string

    The revision ID of the revision to delete.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    Check if local document exists

    This request checks if a local document exists.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    This request checks if a local document exists.

    Local document IDs begin with _local/. Local documents are not replicated or indexed, don't support attachments, and don't save revision histories. In practice they are almost only used by Couchbase Lite's replicator, as a place to store replication checkpoint data.

    -
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

    A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection.

    -
    docid
    required
    string

    The name of the local document ID excluding the _local/ prefix.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    Get a document

    Retrieve a document from the database by its doc ID.

    -
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    		docid
    required
    string

    The name of the local document ID excluding the _local/ prefix.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    Get a document

    Retrieve a document from the database by its doc ID.

    +
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

    A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection.

    -
    docid
    required
    string
    Example: doc1

    The document ID to run the operation against.

    -
    query Parameters
    rev
    string
    Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58

    The document revision to target.

    -
    open_revs
    Array of strings

    Option to fetch specified revisions of the document. The value can be all to fetch all leaf revisions or an array of revision numbers (i.e. open_revs=["rev1", "rev2"]). Only leaf revision bodies that haven't been pruned are guaranteed to be returned. If this option is specified the response will be in multipart format. Use the Accept: application/json request header to get the result as a JSON object.

    -
    show_exp
    boolean

    Whether to show the expiry property (_exp) in the response.

    -
    revs_from
    Array of strings

    Trim the revision history to stop at the first revision in the provided list. If no match is found, the revisions will be trimmed to the revs_limit.

    -
    atts_since
    Array of strings

    Include attachments only since specified revisions. Excludes the attachments for the specified revisions. Only gets used if attachments=true.

    -
    revs_limit
    integer

    Maximum amount of revisions to return for each document.

    -
    attachments
    boolean

    Include attachment bodies in response.

    -
    replicator2
    boolean

    Returns the document with the required properties for replication. This is an enterprise-edition only feature.

    -

    Responses

    		docid
    required
    string
    Example: doc1

    The document ID to run the operation against.

    +
    query Parameters
    rev
    string
    Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58

    The document revision to target.

    +
    open_revs
    Array of strings

    Option to fetch specified revisions of the document. The value can be all to fetch all leaf revisions or an array of revision numbers (i.e. open_revs=["rev1", "rev2"]). Only leaf revision bodies that haven't been pruned are guaranteed to be returned. If this option is specified the response will be in multipart format. Use the Accept: application/json request header to get the result as a JSON object.

    +
    show_exp
    boolean

    Whether to show the expiry property (_exp) in the response.

    +
    revs_from
    Array of strings

    Trim the revision history to stop at the first revision in the provided list. If no match is found, the revisions will be trimmed to the revs_limit.

    +
    atts_since
    Array of strings

    Include attachments only since specified revisions. Excludes the attachments for the specified revisions. Only gets used if attachments=true.

    +
    revs_limit
    integer

    Maximum amount of revisions to return for each document.

    +
    attachments
    boolean

    Include attachment bodies in response.

    +
    replicator2
    boolean

    Returns the document with the required properties for replication. This is an enterprise-edition only feature.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "FailedLoginAttempts": 5,
    • "Friends": [
      ],
    • "_id": "AliceSettings",
    • "_rev": "1-64d4a1f179db5c1848fe52967b47c166"
    }

    Upsert a document

    404

    Resource could not be found

    +

    Response samples

    Content type
    application/json
    {
    • "FailedLoginAttempts": 5,
    • "Friends": [
      ],
    • "_id": "AliceSettings",
    • "_rev": "1-64d4a1f179db5c1848fe52967b47c166"
    }

    Upsert a document

    This will upsert a document meaning if it does not exist, then it will be created. Otherwise a new revision will be made for the existing document. A revision ID must be provided if targetting an existing document.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    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.

    -
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

    A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection.

    -
    docid
    required
    string
    Example: doc1

    The document ID to run the operation against.

    -
    query Parameters
    roundtrip
    boolean

    Block until document has been received by change cache

    -
    replicator2
    boolean

    Returns the document with the required properties for replication. This is an enterprise-edition only feature.

    -
    new_edits
    boolean
    Default: "true"

    Setting this to false indicates that the request body is an already-existing revision that should be directly inserted into the database, instead of a modification to apply to the current document. This mode is used for replication. This option must be used in conjunction with the _revisions property in the request body.

    -
    rev
    string
    Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58

    The document revision to target.

    -
    header Parameters
    If-Match
    string

    The revision ID to target.

    -
    Request Body schema: application/json
    _id
    string

    The ID of the document.

    -
    _rev
    string

    The revision of the document.

    -
    _exp
    string
    		docid
    required
    string
    Example: doc1

    The document ID to run the operation against.

    +
    query Parameters
    roundtrip
    boolean

    Block until document has been received by change cache

    +
    replicator2
    boolean

    Returns the document with the required properties for replication. This is an enterprise-edition only feature.

    +
    new_edits
    boolean
    Default: "true"

    Setting this to false indicates that the request body is an already-existing revision that should be directly inserted into the database, instead of a modification to apply to the current document. This mode is used for replication. This option must be used in conjunction with the _revisions property in the request body.

    +
    rev
    string
    Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58

    The document revision to target.

    +
    header Parameters
    If-Match
    string

    The revision ID to target.

    +
    Request Body schema: application/json
    _id
    string

    The ID of the document.

    +
    _rev
    string

    The revision of the document.

    +
    _exp
    string

    Expiry time after which the document will be purged. The expiration time is set and managed on the Couchbase Server document. The value can be specified in two ways; in ISO-8601 format, for example the 6th of July 2022 at 17:00 in the BST timezone would be 2016-07-06T17:00:00+01:00; it can also be specified as a numeric Couchbase Server expiry value. Couchbase Server expiry values are specified as Unix time, and if the desired TTL is below 30 days then it can also represent an interval in seconds from the current time (for example, a value of 5 will remove the document 5 seconds after it is written to Couchbase Server). The document expiration time is returned in the response of GET /{db}/{doc} when show_exp=true is included in the query.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    Expiry time after which the document will be purged. The expiration time is set and managed on the Couchbase Server document. The value can be specified in two ways; in ISO-8601 format, for example the 6th of July 2022 at 17:00 in the BST timezone would be 2016-07-06T17:00:00+01:00; it can also be specified as a numeric Couchbase Server expiry value. Couchbase Server expiry values are specified as Unix time, and if the desired TTL is below 30 days then it can also represent an interval in seconds from the current time (for example, a value of 5 will remove the document 5 seconds after it is written to Couchbase Server). The document expiration time is returned in the response of GET /{db}/{doc} when show_exp=true is included in the query.

    As with the existing explicit purge mechanism, this applies only to the local database; it has nothing to do with replication. This expiration time is not propagated when the document is replicated. The purge of the document does not cause it to be deleted on any other database.

    -
    _deleted
    boolean

    Whether the document is a tombstone or not. If true, it is a tombstone.

    -
    object
    object
    property name*
    additional property
    any

    Responses

    Request samples

    Content type
    application/json
    {
    • "_id": "string",
    • "_rev": "string",
    • "_exp": "string",
    • "_deleted": true,
    • "_revisions": {
      },
    • "_attachments": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "string",
    • "ok": true,
    • "rev": "string"
    }

    Delete a document

    		_deleted
    boolean

    Whether the document is a tombstone or not. If true, it is a tombstone.

    +
    object
    object
    property name*
    additional property
    any

    Responses

    Request samples

    Content type
    application/json
    {
    • "_id": "string",
    • "_rev": "string",
    • "_exp": "string",
    • "_deleted": true,
    • "_revisions": {
      },
    • "_attachments": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "string",
    • "ok": true,
    • "rev": "string"
    }

    Delete a document

    Delete a document from the database. A new revision is created so the database can track the deletion in synchronized copies.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    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.

    -
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

    A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection.

    -
    docid
    required
    string
    Example: doc1

    The document ID to run the operation against.

    -
    query Parameters
    rev
    string
    Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58

    The document revision to target.

    -
    header Parameters
    If-Match
    string

    The revision ID to target.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": "string",
    • "ok": true,
    • "rev": "string"
    }

    Check if a document exists

    Return a status code based on if the document exists or not.

    -
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    		docid
    required
    string
    Example: doc1

    The document ID to run the operation against.

    +
    query Parameters
    rev
    string
    Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58

    The document revision to target.

    +
    header Parameters
    If-Match
    string

    The revision ID to target.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": "string",
    • "ok": true,
    • "rev": "string"
    }

    Check if a document exists

    Return a status code based on if the document exists or not.

    +
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

    A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection.

    -
    docid
    required
    string
    Example: doc1

    The document ID to run the operation against.

    -
    query Parameters
    rev
    string
    Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58

    The document revision to target.

    -
    open_revs
    Array of strings

    Option to fetch specified revisions of the document. The value can be all to fetch all leaf revisions or an array of revision numbers (i.e. open_revs=["rev1", "rev2"]). Only leaf revision bodies that haven't been pruned are guaranteed to be returned. If this option is specified the response will be in multipart format. Use the Accept: application/json request header to get the result as a JSON object.

    -
    show_exp
    boolean

    Whether to show the expiry property (_exp) in the response.

    -
    revs_from
    Array of strings

    Trim the revision history to stop at the first revision in the provided list. If no match is found, the revisions will be trimmed to the revs_limit.

    -
    atts_since
    Array of strings

    Include attachments only since specified revisions. Excludes the attachments for the specified revisions. Only gets used if attachments=true.

    -
    revs_limit
    integer

    Maximum amount of revisions to return for each document.

    -
    attachments
    boolean

    Include attachment bodies in response.

    -
    replicator2
    boolean

    Returns the document with the required properties for replication. This is an enterprise-edition only feature.

    -

    Responses

    		docid
    required
    string
    Example: doc1

    The document ID to run the operation against.

    +
    query Parameters
    rev
    string
    Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58

    The document revision to target.

    +
    open_revs
    Array of strings

    Option to fetch specified revisions of the document. The value can be all to fetch all leaf revisions or an array of revision numbers (i.e. open_revs=["rev1", "rev2"]). Only leaf revision bodies that haven't been pruned are guaranteed to be returned. If this option is specified the response will be in multipart format. Use the Accept: application/json request header to get the result as a JSON object.

    +
    show_exp
    boolean

    Whether to show the expiry property (_exp) in the response.

    +
    revs_from
    Array of strings

    Trim the revision history to stop at the first revision in the provided list. If no match is found, the revisions will be trimmed to the revs_limit.

    +
    atts_since
    Array of strings

    Include attachments only since specified revisions. Excludes the attachments for the specified revisions. Only gets used if attachments=true.

    +
    revs_limit
    integer

    Maximum amount of revisions to return for each document.

    +
    attachments
    boolean

    Include attachment bodies in response.

    +
    replicator2
    boolean

    Returns the document with the required properties for replication. This is an enterprise-edition only feature.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    Document Attachment

    404

    Resource could not be found

    +

    Response samples

    Content type
    application/json
    {
    • "error": "string",
    • "reason": "string"
    }

    Document Attachment

    Create and manage document attachments

    -

    Get an attachment from a document

    Get an attachment from a document

    This request retrieves a file attachment associated with the document.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    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.

    -
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

    A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection.

    -
    docid
    required
    string
    Example: doc1

    The document ID to run the operation against.

    -
    attach
    required
    string

    The attachment name. This value must be URL encoded. For example, if the attachment name is blob_/avatar, the path component passed to the URL should be blob_%2Favatar (tested with URLEncoder).

    -
    query Parameters
    rev
    string
    Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58

    The document revision to target.

    -
    content_encoding
    boolean
    Default: "true"

    Set to false to disable the Content-Encoding response header.

    -
    meta
    boolean
    Default: "false"

    Return only the metadata of the attachment in the response body.

    -
    header Parameters
    Range
    string
    Example: bytes=123-456

    RFC-2616 bytes range header.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Create or update an attachment on a document

    		docid
    required
    string
    Example: doc1

    The document ID to run the operation against.

    +
    attach
    required
    string

    The attachment name. This value must be URL encoded. For example, if the attachment name is blob_/avatar, the path component passed to the URL should be blob_%2Favatar (tested with URLEncoder).

    +
    query Parameters
    rev
    string
    Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58

    The document revision to target.

    +
    content_encoding
    boolean
    Default: "true"

    Set to false to disable the Content-Encoding response header.

    +
    meta
    boolean
    Default: "false"

    Return only the metadata of the attachment in the response body.

    +
    header Parameters
    Range
    string
    Example: bytes=123-456

    RFC-2616 bytes range header.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Create or update an attachment on a document

    This request adds or updates an attachment associated with the document. If the document does not exist, it will be created and the attachment will be added to it.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    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.

    -
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

    A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection.

    -
    docid
    required
    string
    Example: doc1

    The document ID to run the operation against.

    -
    attach
    required
    string

    The attachment name. This value must be URL encoded. For example, if the attachment name is blob_/avatar, the path component passed to the URL should be blob_%2Favatar (tested with URLEncoder).

    -
    query Parameters
    rev
    string

    The existing document revision ID to modify. Required only when modifying an existing document.

    -
    header Parameters
    Content-Type
    string
    Default: application/octet-stream

    The content type of the attachment.

    -
    If-Match
    string

    An alternative way of specifying the document revision ID.

    -
    Request Body schema: Attachment content type

    The attachment data

    -
    string

    The content to store in the body

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": "string",
    • "ok": true,
    • "rev": "string"
    }

    Check if attachment exists

    This request check if the attachment exists on the specified document.

    -
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    		docid
    required
    string
    Example: doc1

    The document ID to run the operation against.

    +
    attach
    required
    string

    The attachment name. This value must be URL encoded. For example, if the attachment name is blob_/avatar, the path component passed to the URL should be blob_%2Favatar (tested with URLEncoder).

    +
    query Parameters
    rev
    string

    The existing document revision ID to modify. Required only when modifying an existing document.

    +
    header Parameters
    Content-Type
    string
    Default: application/octet-stream

    The content type of the attachment.

    +
    If-Match
    string

    An alternative way of specifying the document revision ID.

    +
    Request Body schema: Attachment content type

    The attachment data

    +
    string

    The content to store in the body

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": "string",
    • "ok": true,
    • "rev": "string"
    }

    Check if attachment exists

    This request check if the attachment exists on the specified document.

    +
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

    A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection.

    -
    docid
    required
    string
    Example: doc1

    The document ID to run the operation against.

    -
    attach
    required
    string

    The attachment name. This value must be URL encoded. For example, if the attachment name is blob_/avatar, the path component passed to the URL should be blob_%2Favatar (tested with URLEncoder).

    -
    query Parameters
    rev
    string
    Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58

    The document revision to target.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Delete an attachment on a document

    		docid
    required
    string
    Example: doc1

    The document ID to run the operation against.

    +
    attach
    required
    string

    The attachment name. This value must be URL encoded. For example, if the attachment name is blob_/avatar, the path component passed to the URL should be blob_%2Favatar (tested with URLEncoder).

    +
    query Parameters
    rev
    string
    Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58

    The document revision to target.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Delete an attachment on a document

    This request deletes an attachment associated with the document.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    This request deletes an attachment associated with the document.

    If the attachment exists, the attachment will be removed from the document.

    -
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection
    path Parameters
    keyspace
    required
    string
    Examples:
    • db1 - Default scope and collection
    • db1.collection1 - Named collection within the default scope
    • db1.scope1.collection1 - Fully-qualified scope and collection

    The keyspace to run the operation against.

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU gJXPeC">

    The keyspace to run the operation against.

    A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection.

    -
    docid
    required
    string
    Example: doc1

    The document ID to run the operation against.

    -
    attach
    required
    string

    The attachment name. This value must be URL encoded. For example, if the attachment name is blob_/avatar, the path component passed to the URL should be blob_%2Favatar (tested with URLEncoder).

    -
    query Parameters
    rev
    string

    The existing document revision ID to modify.

    -
    header Parameters
    If-Match
    string

    An alternative way of specifying the document revision ID.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": "string",
    • "ok": true,
    • "rev": "string"
    }

    Replication

    		docid
    required
    string
    Example: doc1

    The document ID to run the operation against.

    +
    attach
    required
    string

    The attachment name. This value must be URL encoded. For example, if the attachment name is blob_/avatar, the path component passed to the URL should be blob_%2Favatar (tested with URLEncoder).

    +
    query Parameters
    rev
    string

    The existing document revision ID to modify.

    +
    header Parameters
    If-Match
    string

    An alternative way of specifying the document revision ID.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": "string",
    • "ok": true,
    • "rev": "string"
    }

    Replication

    Create and manage inter-Sync Gateway replications

    -

    Handle incoming BLIP Sync web socket request

    This handles incoming BLIP Sync requests from either Couchbase Lite or another Sync Gateway node. The connection has to be upgradable to a websocket connection or else the request will fail.

    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -
    query Parameters
    client
    string
    Default: "cbl2"
    Enum: "cbl2" "sgr2"

    This is the client type that is making the BLIP Sync request. Used to control client-type specific replication behaviour.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Unsupported

    Handle incoming BLIP Sync web socket request

    This handles incoming BLIP Sync requests from either Couchbase Lite or another Sync Gateway node. The connection has to be upgradable to a websocket connection or else the request will fail.

    +
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +
    query Parameters
    client
    string
    Default: "cbl2"
    Enum: "cbl2" "sgr2"

    This is the client type that is making the BLIP Sync request. Used to control client-type specific replication behaviour.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Unsupported

    Endpoints that are not supported by Sync Gateway

    -

    Get views of a design document | Unsupported

    Get views of a design document | Unsupported

    This is unsupported

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    This is unsupported

    Query a design document.

    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -
    ddoc
    required
    string

    The design document name.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "language": "string",
    • "views": {
      },
    • "options": {
      }
    }

    Update views of a design document | Unsupported

    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +
    ddoc
    required
    string

    The design document name.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "language": "string",
    • "views": {
      },
    • "options": {
      }
    }

    Update views of a design document | Unsupported

    This is unsupported

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    This is unsupported

    Update the views of a design document.

    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -
    ddoc
    required
    string

    The design document name.

    -
    Request Body schema: application/json
    language
    string
    object
    object

    Responses

    Request samples

    Content type
    application/json
    {
    • "language": "string",
    • "views": {
      },
    • "options": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Delete a design document | Unsupported

    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +
    ddoc
    required
    string

    The design document name.

    +
    Request Body schema: application/json
    language
    string
    object
    object

    Responses

    Request samples

    Content type
    application/json
    {
    • "language": "string",
    • "views": {
      },
    • "options": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Delete a design document | Unsupported

    This is unsupported

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    This is unsupported

    Delete a design document.

    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -
    ddoc
    required
    string

    The design document name.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Check if view of design document exists | Unsupported

    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +
    ddoc
    required
    string

    The design document name.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Check if view of design document exists | Unsupported

    This is unsupported

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    This is unsupported

    Check if a design document can be queried.

    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -
    ddoc
    required
    string

    The design document name.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Query a view on a design document | Unsupported

    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +
    ddoc
    required
    string

    The design document name.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "not_found",
    • "reason": "no such database \"invalid-db\""
    }

    Query a view on a design document | Unsupported

    This is unsupported

    +" class="sc-dJkDXt sc-eXfTSZ eOvdyU cLsgdM">

    This is unsupported

    Query a view on a design document.

    -
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    -
    ddoc
    required
    string

    The design document name.

    -
    view
    required
    string

    The view to target.

    -
    query Parameters
    inclusive_end
    boolean

    Indicates whether the specified end key should be included in the result.

    -
    descending
    boolean

    Return documents in descending order.

    -
    include_docs
    boolean

    Only works when using Couchbase Server 3.0 and earlier. Indicates whether to include the full content of the documents in the response.

    -
    reduce
    boolean

    Whether to execute a reduce function on the response or not.

    -
    group
    boolean

    Group the results using the reduce function to a group or single row.

    -
    skip
    integer

    Skip the specified number of documents before starting to return results.

    -
    limit
    integer

    Return only the specified number of documents

    -
    group_level
    integer

    Specify the group level to be used.

    -
    startkey_docid
    string

    Return documents starting with the specified document identifier.

    -
    endkey_docid
    string

    Stop returning records when the specified document identifier is reached.

    -
    stale
    string
    Enum: "ok" "update_after"

    Allow the results from a stale view to be used, without triggering a rebuild of all views within the encompassing design document.

    -
    startkey
    string

    Return records starting with the specified key.

    -
    endkey
    string

    Stop returning records when this key is reached.

    -
    key
    string

    Return only the document that matches the specified key.

    -
    keys
    Array of strings

    An array of document ID strings to filter by.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "total_rows": 0,
    • "rows": [
      ],
    • "errors": [
      ]
    }
    +
    path Parameters
    db
    required
    string
    Example: db1

    The name of the database to run the operation against.

    +
    ddoc
    required
    string

    The design document name.

    +
    view
    required
    string

    The view to target.

    +
    query Parameters
    inclusive_end
    boolean

    Indicates whether the specified end key should be included in the result.

    +
    descending
    boolean

    Return documents in descending order.

    +
    include_docs
    boolean

    Only works when using Couchbase Server 3.0 and earlier. Indicates whether to include the full content of the documents in the response.

    +
    reduce
    boolean

    Whether to execute a reduce function on the response or not.

    +
    group
    boolean

    Group the results using the reduce function to a group or single row.

    +
    skip
    integer

    Skip the specified number of documents before starting to return results.

    +
    limit
    integer

    Return only the specified number of documents

    +
    group_level
    integer

    Specify the group level to be used.

    +
    startkey_docid
    string

    Return documents starting with the specified document identifier.

    +
    endkey_docid
    string

    Stop returning records when the specified document identifier is reached.

    +
    stale
    string
    Enum: "ok" "update_after"

    Allow the results from a stale view to be used, without triggering a rebuild of all views within the encompassing design document.

    +
    startkey
    string

    Return records starting with the specified key.

    +
    endkey
    string

    Stop returning records when this key is reached.

    +
    key
    string

    Return only the document that matches the specified key.

    +
    keys
    Array of strings

    An array of document ID strings to filter by.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "total_rows": 0,
    • "rows": [
      ],
    • "errors": [
      ]
    }