Public REST API (Static Page)

500

A problem occurred in regards to the token

GetDbOidcTestingWellKnownOpenidConfiguration200Response

OpenID Connect authentication initiation via WWW-Authenticate header

GET /{db}/_oidc_challenge

Description

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

Produces

application/json

Parameters

Path Parameters

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

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Query Parameters

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

Name

Description

Schema

provider
optional

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

String

offline
optional

String

Responses

HTTP Code	Description	Schema
400	The provider provided is not defined in the Sync Gateway config. If no provided was specified then there is no default provider set.
401	Successfully connected with the OpenID Connect provider so now the client can login.
404	Resource could not be found	HTTPError
500	Unable to connect and validate with the OpenID Connect provider requested

OpenID Connect token refresh

GET /{db}/_oidc_refresh

Description

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

Produces

application/json

Parameters

Path Parameters

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

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Query Parameters

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

Name

Description

Schema

refresh_token
required

The OpenID Connect refresh token.

String

provider
optional

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

String

Responses

HTTP Code	Description	Schema
200	Successfully authenticated with OpenID Connect.	OpenIDConnectCallbackProperties
400	The provider provided is not defined in the Sync Gateway config. If no provided was specified then there is no default provider set.
404	Resource could not be found	HTTPError
500	Unable to connect and validate with the OpenID Connect provider requested

OpenID Connect mock provider

GET /{db}/_oidc_testing/.well-known/openid-configuration

Description

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

Produces

application/json

Parameters

Path Parameters

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

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Responses

HTTP Code Description Schema

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

200

Successfully generated OpenID Connect provider mock response.

403

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

404

Resource could not be found

OpenID Connect mock login page handler

GET /{db}/_oidc_testing/authenticate

Description

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

Produces

application/json

Parameters

Path Parameters

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

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Query Parameters

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

Name

Description

Schema

redirect_uri
optional

The Sync Gateway OpenID Connect callback URL.

String

scope
required

The OpenID Connect authentication scope.

String

username
required

String

tokenttl
required

Integer

identity-token-formats
required

String

authenticated
required

String

Responses

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

OpenID Connect mock login page

GET /{db}/_oidc_testing/authorize

Description

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

Produces

application/json

Parameters

Path Parameters

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

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Query Parameters

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

Name

Description

Schema

scope
required

The OpenID Connect authentication scope.

String

Responses

HTTP Code Description Schema

200

400

A validation error occurred with the scope.

403

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

404

Resource could not be found

500

An error occurred.

GetDbOidcTestingCerts200Response

OpenID Connect public certificates for signing keys

GET /{db}/_oidc_testing/certs

Description

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

Produces

application/json

Parameters

Path Parameters

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

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Responses

HTTP Code Description Schema

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

200

Returned public key successfully

403

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

404

Resource could not be found

500

An error occurred while getting the private RSA key

Create a new Facebook-based session

POST /{db}/_facebook

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

Description

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

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

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

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

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Body Parameter

Name	Description	Schema
Body optional		PostDbFacebookRequest

Name

Description

Schema

Body
optional

PostDbFacebookRequest

Responses

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

HTTP Code

Description

Schema

200

Session created successfully

400

Origin is not in the approved list of allowed origins

401

Received error from Facebook verifier

404

Resource could not be found

502

Received invalid response from the Facebook verifier

504

Unable to send request to Facebook API

Create a new Google-based session

POST /{db}/_google

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

Description

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

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

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

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

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Body Parameter

Name	Description	Schema
Body optional		PostDbGoogleRequest

Name

Description

Schema

Body
optional

PostDbGoogleRequest

Responses

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

HTTP Code

Description

Schema

200

Session created successfully

400

Origin is not in the approved list of allowed origins

401

Received error from Google token verifier or invalid application ID in the config

404

Resource could not be found

502

Received invalid response from the Google token verifier

PostDbOidcTestingAuthenticateRequest

504

Unable to send request to the Google token verifier

OpenID Connect mock login page handler

POST /{db}/_oidc_testing/authenticate

Description

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

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

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

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Query Parameters

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

Name

Description

Schema

redirect_uri
optional

The Sync Gateway OpenID Connect callback URL.

String

scope
required

The OpenID Connect authentication scope.

String

Body Parameter

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

Name

Description

Schema

Body
optional

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

Responses

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

OpenID Connect mock login page

POST /{db}/_oidc_testing/authorize

Description

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

Produces

application/json

Parameters

Path Parameters

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

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Query Parameters

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

Name

Description

Schema

scope
required

The OpenID Connect authentication scope.

String

Responses

HTTP Code Description Schema

200

400

A validation error occurred with the scope.

403

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

404

Resource could not be found

500

An error occurred.

PostDbOidcTestingTokenRequest

OpenID Connect mock token

POST /{db}/_oidc_testing/token

Description

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

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

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

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Body Parameter

Name	Description	Schema
Body optional		PostDbOidcTestingTokenRequest

Name

Description

Schema

Body
optional

Responses

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

Database Management

Table of Contents

Get database information
Get changes list
Check if database exists
/{db}/_changes
/{db}/_ensure_full_commit
Get changes list
Compare revisions to what is in the database
Create DB public API stub

Get database information

GET /{db}/

Description

Retrieve information about the database.

Produces

application/json

Parameters

Path Parameters

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

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Responses

HTTP Code	Description	Schema
200	Successfully returned database information	GetDb200Response
404	Resource could not be found	HTTPError

HTTP Code

Description

Schema

200

Successfully returned database information

GetDb200Response

404

Resource could not be found

GetKeyspaceChanges200Response

Get changes list

GET /{keyspace}/_changes

Description

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

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

Produces

application/json

Parameters

Path Parameters

Name	Description	Schema
keyspace required	The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection.	String

Name

Description

Schema

keyspace
required

The keyspace to run the operation against.

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

String

Query Parameters

Name Description Schema

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

limit
optional

Maximum number of changes to return.

Integer

since
optional

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

String

style
optional

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

Values: "main_only", "all_docs"

String

active_only
optional

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

Boolean

include_docs
optional

Include the body associated with each document.

Boolean

revocations
optional

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

Boolean

filter
optional

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

Values: "sync_gateway/bychannel", "_doc_ids"

String

channels
optional

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

String

doc_ids
optional

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

String array

heartbeat
optional

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

Minimum: 25000

Integer

timeout
optional

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

Minimum: 0
Maximum: 900000

Integer

feed
optional

The type of changes feed to use.

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

String

Responses

HTTP Code	Description	Schema
200	Successfully returned the changes feed	GetKeyspaceChanges200Response
400	There was a problem with your request	HTTPError
404	Resource could not be found	HTTPError

HTTP Code

Description

Schema

200

Successfully returned the changes feed

400

There was a problem with your request

404

Resource could not be found

PostDbEnsureFullCommit201Response

Check if database exists

HEAD /{db}/

Description

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

Produces

application/json

Parameters

Path Parameters

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

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Responses

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

/{db}/_changes

HEAD /{keyspace}/_changes

Description

Parameters

Path Parameters

Name	Description	Schema
keyspace required	The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection.	String

Name

Description

Schema

keyspace
required

The keyspace to run the operation against.

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

String

Responses

HTTP Code	Description	Schema
200	OK
400	Bad Request
404	Not Found

/{db}/_ensure_full_commit

POST /{db}/_ensure_full_commit

Description

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

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Responses

HTTP Code

Description

Schema

201

Get changes list

POST /{keyspace}/_changes

Description

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

keyspace
required

The keyspace to run the operation against.

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

String

Body Parameter

Name

Description

Schema

Body
optional

PostKeyspaceChangesRequest

Responses

HTTP Code

Description

Schema

200

Successfully returned the changes feed

GetKeyspaceChanges200Response

400

There was a problem with your request

404

Resource could not be found

PostKeyspaceRevsDiffRequest

Compare revisions to what is in the database

POST /{keyspace}/_revs_diff

Description

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

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

keyspace
required

The keyspace to run the operation against.

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

String

Body Parameter

Name

Description

Schema

Body
optional

Responses

HTTP Code

Description

Schema

200

Comparisons successful

PostKeyspaceRevsDiff200Response

404

Resource could not be found

Delete a document
Delete a local document
Gets all the documents in the database with the given parameters
Get a document
Get local document
/{db}/_all_docs
Check if a document exists
Check if local document exists
Create a new document
Get all the documents in the database using a built-in view
Bulk document operations
Get multiple documents in a MIME multipart response
Upsert a document
Upsert a local document

Create DB public API stub

PUT /{targetdb}/

Description

A stub that always returns an error on the Public API, for createTarget/CouchDB compatibility.

Parameters

Path Parameters

Name

Description

Schema

targetdb
required

The database name to target.

String

Responses

HTTP Code	Description	Schema
403	Database does not exist and cannot be created over the public API
412	Database exists

Document

Create and manage documents

Delete a document

DELETE /{keyspace}/{docid}

Description

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

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

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

keyspace
required

The keyspace to run the operation against.

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

String

docid
required

The document ID to run the operation against.

String

Query Parameters

Name

Description

Schema

rev
optional

The document revision to target.

String

Header Parameters

Name

Description

Schema

If-Match
optional

The revision ID to target.

String

Responses

HTTP Code

Description

Schema

200

New revision created successfully

400

There was a problem with your request

404

Resource could not be found

GetKeyspaceAllDocs200Response

Delete a local document

DELETE /{keyspace}/_local/{docid}

Description

This request deletes a local document.

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

Produces

application/json

Parameters

Path Parameters

Name Description Schema

keyspace
required

The keyspace to run the operation against.

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

String

docid
required

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

String

Query Parameters

Name

Description

Schema

rev
required

The revision ID of the revision to delete.

String

Responses

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

Gets all the documents in the database with the given parameters

GET /{keyspace}/_all_docs

Description

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

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

keyspace
required

The keyspace to run the operation against.

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

String

Query Parameters

Name Description Schema

include_docs
optional

Include the body associated with each document.

Boolean

channels
optional

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

Boolean

access
optional

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

Boolean

revs
optional

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

Boolean

update_seq
optional

Include the document sequence number update_seq property for each document.

Boolean

keys
optional

An array of document ID strings to filter by.

String array

startkey
optional

Return records starting with the specified key.

String

endkey
optional

Stop returning records when this key is reached.

String

limit
optional

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

Big Decimal

Responses

HTTP Code

Description

Schema

200

Operation ran successfully

400

There was a problem with your request

404

Resource could not be found

GetKeyspaceDocid200Response

Get a document

GET /{keyspace}/{docid}

Description

Retrieve a document from the database by its doc ID.

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

keyspace
required

The keyspace to run the operation against.

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

String

docid
required

The document ID to run the operation against.

String

Query Parameters

Name Description Schema

rev
optional

The document revision to target.

String

open_revs
optional

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

String array

show_exp
optional

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

Boolean

revs_from
optional

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

String array

atts_since
optional

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

String array

revs_limit
optional

Maximum amount of revisions to return for each document.

Integer

attachments
optional

Include attachment bodies in response.

Boolean

replicator2
optional

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

Boolean

Responses

HTTP Code

Description

Schema

200

Document found and returned successfully

400

Document ID is not in an allowed format therefore is invalid. This could be because it is over 250 characters or is prefixed with an underscore ("_").

404

Resource could not be found

501

Not Implemented. It is likely this error was caused due to trying to use an enterprise-only feature on the community edition.

Get local document

GET /{keyspace}/_local/{docid}

Description

This request retrieves a local document.

Produces

application/json

Parameters

Path Parameters

Name Description Schema

keyspace
required

The keyspace to run the operation against.

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

String

docid
required

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

String

Responses

HTTP Code

Description

Schema

200

Successfully found local document

400

There was a problem with your request

404

Resource could not be found

/{db}/_all_docs

HEAD /{keyspace}/_all_docs

Description

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

keyspace
required

The keyspace to run the operation against.

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

String

Query Parameters

Name Description Schema

include_docs
optional

Include the body associated with each document.

Boolean

channels
optional

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

Boolean

access
optional

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

Boolean

revs
optional

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

Boolean

update_seq
optional

Include the document sequence number update_seq property for each document.

Boolean

keys
optional

An array of document ID strings to filter by.

String array

startkey
optional

Return records starting with the specified key.

String

endkey
optional

Stop returning records when this key is reached.

String

limit
optional

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

Big Decimal

Responses

HTTP Code

Description

Schema

200

400

There was a problem with your request

404

Resource could not be found

Check if a document exists

HEAD /{keyspace}/{docid}

Description

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

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

keyspace
required

The keyspace to run the operation against.

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

String

docid
required

The document ID to run the operation against.

String

Query Parameters

Name Description Schema

rev
optional

The document revision to target.

String

open_revs
optional

String array

show_exp
optional

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

Boolean

revs_from
optional

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

String array

atts_since
optional

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

String array

revs_limit
optional

Maximum amount of revisions to return for each document.

Integer

attachments
optional

Include attachment bodies in response.

Boolean

replicator2
optional

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

Boolean

Responses

HTTP Code

Description

Schema

200

Document exists

400

Document ID is not in an allowed format therefore is invalid. This could be because it is over 250 characters or is prefixed with an underscore ("_").

404

Resource could not be found

Check if local document exists

HEAD /{keyspace}/_local/{docid}

Description

This request checks if a local document exists.

Produces

application/json

Parameters

Path Parameters

Name Description Schema

keyspace
required

The keyspace to run the operation against.

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

String

docid
required

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

String

Responses

HTTP Code

Description

Schema

200

Document exists

400

There was a problem with your request

404

Resource could not be found

Create a new document

POST /{keyspace}/

Description

Create a new document in the keyspace.

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

A document can have a maximum size of 20MB.

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

keyspace
required

The keyspace to run the operation against.

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

String

Query Parameters

Name

Description

Schema

roundtrip
optional

Block until document has been received by change cache

Boolean

Body Parameter

Name

Description

Schema

Body
optional

PostKeyspaceRequest

Responses

HTTP Code

Description

Schema

200

New document revision created successfully.

400

There was a problem with your request

404

Resource could not be found

409

Resource already exists under that name

415

Invalid content type

PostKeyspaceAllDocsRequest

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

POST /{keyspace}/_all_docs

Description

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

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

keyspace
required

The keyspace to run the operation against.

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

String

Query Parameters

Name Description Schema

include_docs
optional

Include the body associated with each document.

Boolean

channels
optional

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

Boolean

access
optional

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

Boolean

revs
optional

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

Boolean

update_seq
optional

Include the document sequence number update_seq property for each document.

Boolean

startkey
optional

Return records starting with the specified key.

String

endkey
optional

Stop returning records when this key is reached.

String

limit
optional

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

Big Decimal

Body Parameter

Name

Description

Schema

Body
optional

Responses

HTTP Code

Description

Schema

200

Operation ran successfully

GetKeyspaceAllDocs200Response

400

There was a problem with your request

404

Resource could not be found

PostKeyspaceBulkDocsRequest

Bulk document operations

POST /{keyspace}/_bulk_docs

Description

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

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

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

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

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

keyspace
required

The keyspace to run the operation against.

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

String

Body Parameter

Name

Description

Schema

Body
optional

Responses

HTTP Code

Description

Schema

201

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

PostKeyspaceBulkDocs201ResponseInner array

400

There was a problem with your request

404

Resource could not be found

PostKeyspaceBulkGetRequest

Get multiple documents in a MIME multipart response

POST /{keyspace}/_bulk_get

Description

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

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

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

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

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

keyspace
required

The keyspace to run the operation against.

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

String

Query Parameters

Name Description Schema

attachments
optional

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

Boolean

revs
optional

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

Boolean

revs_limit
optional

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

Integer

Header Parameters

Name Description Schema

X-Accept-Part-Encoding
optional

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

String

Accept-Encoding
optional

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

String

Body Parameter

Name

Description

Schema

Body
optional

Responses

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

Upsert a document

PUT /{keyspace}/{docid}

Description

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

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

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

The maximum size for a document is 20MB.

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

keyspace
required

The keyspace to run the operation against.

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

String

docid
required

The document ID to run the operation against.

String

Query Parameters

Name Description Schema

roundtrip
optional

Block until document has been received by change cache

Boolean

replicator2
optional

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

Boolean

new_edits
optional

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

Boolean

rev
optional

The document revision to target.

String

Header Parameters

Name

Description

Schema

If-Match
optional

The revision ID to target.

String

Body Parameter

Name

Description

Schema

Body
optional

PostKeyspaceRequest

Responses

HTTP Code

Description

Schema

201

Created

400

There was a problem with your request

404

Resource could not be found

409

Resource already exists under that name

415

Invalid content type

PutKeyspaceLocalDocidRequest

Upsert a local document

PUT /{keyspace}/_local/{docid}

Description

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

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

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name Description Schema

keyspace
required

The keyspace to run the operation against.

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

String

docid
required

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

String

Body Parameter

Name

Description

Schema

Body
optional

The body of the document

Responses

HTTP Code Description Schema

201

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

400

There was a problem with your request

404

Resource could not be found

Delete an attachment on a document
Get an attachment from a document
Check if attachment exists
Create or update an attachment on a document

409

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

Document Attachment

Table of Contents

Delete an attachment on a document

DELETE /{keyspace}/{docid}/{attach}

Description

This request deletes an attachment associated with the document.

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

Produces

application/json

Parameters

Path Parameters

Name Description Schema

keyspace
required

The keyspace to run the operation against.

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

String

docid
required

The document ID to run the operation against.

String

attach
required

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

String

Query Parameters

Name

Description

Schema

rev
optional

The existing document revision ID to modify.

String

Header Parameters

Name

Description

Schema

If-Match
optional

An alternative way of specifying the document revision ID.

String

Responses

HTTP Code

Description

Schema

200

Attachment removed from the document successfully

404

Resource could not be found

409

Resource already exists under that name

Get an attachment from a document

GET /{keyspace}/{docid}/{attach}

Description

This request retrieves a file attachment associated with the document.

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

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

Produces

application/json

Parameters

Path Parameters

Name Description Schema

keyspace
required

The keyspace to run the operation against.

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

String

docid
required

The document ID to run the operation against.

String

attach
required

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

String

Query Parameters

Name Description Schema

rev
optional

The document revision to target.

String

content_encoding
optional

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

Boolean

meta
optional

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

Boolean

Header Parameters

Name

Description

Schema

Range
optional

RFC-2616 bytes range header.

String

Responses

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

Check if attachment exists

HEAD /{keyspace}/{docid}/{attach}

Description

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

Produces

application/json

Parameters

Path Parameters

Name Description Schema

keyspace
required

The keyspace to run the operation against.

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

String

docid
required

The document ID to run the operation against.

String

attach
required

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

String

Query Parameters

Name

Description

Schema

rev
optional

The document revision to target.

String

Responses

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

Create or update an attachment on a document

PUT /{keyspace}/{docid}/{attach}

Description

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

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

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

Consumes

Attachment content type

Produces

application/json

Parameters

Path Parameters

Name Description Schema

keyspace
required

The keyspace to run the operation against.

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

String

docid
required

The document ID to run the operation against.

String

attach
required

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

String

Query Parameters

Name

Description

Schema

rev
optional

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

String

Header Parameters

Name

Description

Schema

Content-Type
optional

The content type of the attachment.

String

If-Match
optional

An alternative way of specifying the document revision ID.

String

Body Parameter

Name

Description

Schema

Body
optional

The attachment data

String

Responses

HTTP Code

Description

Schema

201

Attachment added to new or existing document successfully

404

Resource could not be found

409

Resource already exists under that name

Handle incoming BLIP Sync web socket request

Replication

Create and manage inter-Sync Gateway replications

GET /{db}/_blipsync

Description

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

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Query Parameters

Name Description Schema

client
optional

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

Values: "cbl2", "sgr2"

String

Responses

HTTP Code

Description

Schema

101

Upgraded to a web socket connection

404

Resource could not be found

426

Cannot upgrade connection to a web socket connection

Get server information
Check if API is available
Check if server online
Check if API is available

Server

Manage server activities

Get server information

GET /

Description

Returns information about the Sync Gateway node.

Produces

application/json

Responses

HTTP Code

Description

Schema

200

Returned server information

Get200Response

Check if API is available

GET /_ping

Description

Returns OK status if API is available.

Produces

text/plain

Responses

HTTP Code

Description

Schema

200

Returned status

String

Check if server online

HEAD /

Description

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

Responses

HTTP Code

Description

Schema

200

Server is online

Check if API is available

HEAD /_ping

Description

Returns OK status if API is available.

Responses

HTTP Code

Description

Schema

200

Server is available

Session

Manage user sessions

Log out
Get information about the current user
/{db}/_session
Create a new user session

Log out

DELETE /{db}/_session

Description

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.

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Responses

HTTP Code	Description	Schema
200	Successfully removed session (logged out)
400	Bad Request
404	Resource could not be found	HTTPError

Get information about the current user

GET /{db}/_session

Description

This will get the information about the current user.

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Responses

HTTP Code

Description

Schema

200

Properties associated with a user session

UserSessionInformation

404

Resource could not be found

/{db}/_session

HEAD /{db}/_session

Description

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Responses

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

Create a new user session

POST /{db}/_session

Description

Generates a login session for 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.

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

Body Parameter

Name

Description

Schema

Body
optional

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

PostDbSessionRequest

Responses

HTTP Code

Description

Schema

200

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

PostDbSession200Response

400

Origin is not in the approved list of allowed origins

404

Resource could not be found

GetDbDesignDdoc200Response

Unsupported

Endpoints that are not supported by Sync Gateway

Delete a design document | Unsupported

DELETE /{db}/_design/{ddoc}

Description

This is unsupported

Delete a design document.

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

ddoc
required

The design document name.

String

Responses

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

Get views of a design document | Unsupported

GET /{db}/_design/{ddoc}

Description

This is unsupported

Query a design document.

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

ddoc
required

The design document name.

String

Responses

HTTP Code

Description

Schema

200

Successfully returned design document.

403

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

404

Resource could not be found

GetDbDesignDdocViewView200Response

Query a view on a design document | Unsupported

GET /{db}/_design/{ddoc}/_view/{view}

Description

This is unsupported

Query a view on a design document.

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

ddoc
required

The design document name.

String

view
required

The view to target.

String

Query Parameters

Name Description Schema

inclusive_end
optional

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

Boolean

descending
optional

Return documents in descending order.

Boolean

include_docs
optional

Only works when using Couchbase Server 3.0 and earlier. Indicates whether to include the full content of the documents in the response.

Boolean

reduce
optional

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

Boolean

group
optional

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

Boolean

skip
optional

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

Integer

limit
optional

Return only the specified number of documents

Integer

group_level
optional

Specify the group level to be used.

Integer

startkey_docid
optional

Return documents starting with the specified document identifier.

String

endkey_docid
optional

Stop returning records when the specified document identifier is reached.

String

stale
optional

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

Values: "ok", "update_after"

String

startkey
optional

Return records starting with the specified key.

String

endkey
optional

Stop returning records when this key is reached.

String

key
optional

Return only the document that matches the specified key.

String

keys
optional

An array of document ID strings to filter by.

String array

Responses

HTTP Code

Description

Schema

200

Returned view successfully

403

Forbidden

404

Resource could not be found

GetDbDesignDdoc200Response

Check if view of design document exists | Unsupported

HEAD /{db}/_design/{ddoc}

Description

This is unsupported

Check if a design document can be queried.

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

ddoc
required

The design document name.

String

Responses

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

Update views of a design document | Unsupported

PUT /{db}/_design/{ddoc}

Description

This is unsupported

Update the views of a design document.

Consumes

application/json

Produces

application/json

Parameters

Path Parameters

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

ddoc
required

The design document name.

String

Body Parameter

Name

Description

Schema

Body
optional

Responses

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

Definitions

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

ChangesFeed
DesignDoc
Document
Get200Response
Get200ResponseVendor
GetDb200Response
GetDbDesignDdoc200Response
GetDbDesignDdoc200ResponseOptions
GetDbDesignDdoc200ResponseViewsValue
GetDbDesignDdocViewView200Response
GetDbDesignDdocViewView200ResponseErrorsInner
GetDbDesignDdocViewView200ResponseRowsInner
GetDbOidcTestingCerts200Response
GetDbOidcTestingCerts200ResponseKeysInner
GetDbOidcTestingWellKnownOpenidConfiguration200Response
GetKeyspaceAllDocs200Response
GetKeyspaceAllDocs200ResponseRowsInner
GetKeyspaceAllDocs200ResponseRowsInnerValue
GetKeyspaceChanges200Response
GetKeyspaceChanges200ResponseResultsInner
GetKeyspaceChanges200ResponseResultsInnerChangesInner
GetKeyspaceDocid200Response
HTTP-Error
New-revision
NodeInfo
OpenID Connect callback properties
OIDCLoginPageHandler
OIDC-token
OpenID Connect callback properties
PostDbEnsureFullCommit201Response
PostDbFacebook401Response
PostDbFacebookRequest
PostDbGoogleRequest
PostDbOidcTestingAuthenticateRequest
PostDbOidcTestingTokenRequest
PostDbSession200Response
PostDbSession200ResponseUserCtx
PostDbSession200ResponseUserCtxChannelsValue
PostDbSessionRequest
PostKeyspaceAllDocsRequest
PostKeyspaceBulkDocs201ResponseInner
PostKeyspaceBulkDocsRequest
PostKeyspaceBulkGetRequest
PostKeyspaceBulkGetRequestDocsInner
PostKeyspaceChangesRequest
PostKeyspaceRequest
PostKeyspaceRequestAttachmentsValue
PostKeyspaceRequestRevisions
PostKeyspaceRevsDiff200Response
PostKeyspaceRevsDiff200ResponseDocid
PostKeyspaceRevsDiffRequest
PutKeyspaceLocalDocidRequest
User Session Information
UserSessionInformationUserCtx

ChangesFeed

Object

Property Schema

results
optional

Unique items: true

GetKeyspaceChanges200ResponseResultsInner array

last_seq
optional

The last change sequence number.

String

DesignDoc

Object

Property

Schema

language
optional

String

views
optional

GetDbDesignDdoc200ResponseOptions

options
optional

Document

Object

Property Schema

_id
optional

The ID of the document.

String

_rev
optional

The revision of the document.

String

_exp
optional

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

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

String

_deleted
optional

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

Boolean

_revisions
optional

PostKeyspaceRequestRevisions

_attachments
optional

additional
property

Any Type

Get200Response

Object

Property Schema

ADMIN
optional

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

Boolean

couchdb
required

CouchDB welcome

String

vendor
required

Product vendor

Get200ResponseVendor

version
optional

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

String

persistent_config
optional

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

Boolean

Get200ResponseVendor

Object

Property Schema

name
required

Product name

String

version
optional

API version. Omitted if api.hide_product_version=true

String

GetDb200Response

Object

Property Schema

db_name
optional

Database name

String

update_seq
optional

The last sequence number that was committed to the database.

Will return 0 if the database is offline.

Integer

committed_update_seq
optional

The last sequence number that was committed to the database.

Will return 0 if the database is offline.

Integer

instance_start_time
optional

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

Integer

compact_running
optional

Indicates whether database compaction is currently taking place or not.

Boolean

purge_seq
optional

Unused field.

Big Decimal

disk_format_version
optional

Unused field.

Big Decimal

state
optional

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

Values: "Online", "Offline"

String

server_uuid
optional

Unique server identifier.

String

GetDbDesignDdoc200Response

Object

Property

Schema

language
optional

String

views
optional

GetDbDesignDdoc200ResponseOptions

options
optional

Object

Property

Schema

local_seq
optional

String

include_design
optional

String

raw
optional

String

index_xattr_on_deleted_docs
optional

String

GetDbDesignDdoc200ResponseViewsValue

Object

Property

Schema

map
optional

String

reduce
optional

String

GetDbDesignDdocViewView200Response

Object

Property

Schema

total_rows
required

Integer

rows
required

GetDbDesignDdocViewView200ResponseRowsInner array

errors
optional

GetDbDesignDdocViewView200ResponseErrorsInner array

GetDbDesignDdocViewView200ResponseErrorsInner

Object

Property

Schema

From
optional

String

Reason
optional

String

GetDbDesignDdocViewView200ResponseRowsInner

Object

Property

Schema

id
optional

String

key
optional

Object

value
optional

Object

doc
optional

Object

GetDbOidcTestingCerts200Response

Object

Property

Schema

keys
required

GetDbOidcTestingCerts200ResponseKeysInner array

GetDbOidcTestingCerts200ResponseKeysInner

Object

Property

Schema

Key
required

Object

KeyID
required

String

Use
required

String

Certificates
optional

Object array

Algorithm
optional

String

GetDbOidcTestingWellKnownOpenidConfiguration200Response

Object

Property

Schema

issuer
optional

String

authorization_endpoint
optional

String

token_endpoint
optional

String

jwks_uri
optional

String

userinfo_endpoint
optional

String

id_token_signing_alg_values_supported
optional

String

response_types_supported
optional

String

subject_types_supported
optional

String

scopes_supported
optional

String

claims_supported
optional

String

token_endpoint_auth_methods_supported
optional

String

GetKeyspaceAllDocs200Response

Object

Property Schema

rows
required

Unique items: true

GetKeyspaceAllDocs200ResponseRowsInner array

total_rows
required

Big Decimal

update_seq
required

Big Decimal

GetKeyspaceAllDocs200ResponseRowsInner

Object

Property

Schema

key
optional

String

id
optional

String

value
optional

GetKeyspaceAllDocs200ResponseRowsInnerValue

Object

Property

Schema

rev
optional

String

GetKeyspaceChanges200Response

Object

Property Schema

results
optional

Unique items: true

GetKeyspaceChanges200ResponseResultsInner array

last_seq
optional

The last change sequence number.

String

GetKeyspaceChanges200ResponseResultsInner

Object

Property Schema

seq
optional

The change sequence number.

Big Decimal

id
optional

The document ID the change happened on.

String

changes
optional

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

Unique items: true

GetKeyspaceChanges200ResponseResultsInnerChangesInner array

GetKeyspaceChanges200ResponseResultsInnerChangesInner

Object

Property

Schema

rev
optional

The new revision that was caused by that change.

String

GetKeyspaceDocid200Response

Object

Property

Schema

_id
optional

The ID of the document.

String

_rev
optional

The revision ID of the document.

String

additional
property

Any Type

HTTP-Error

Object

Property

Schema

error
required

The error name.

String

reason
required

The error description.

String

New-revision

Object

Property

Schema

id
required

The ID of the document.

String

ok
required

Whether the request completed successfully.

Boolean

rev
required

The revision of the document.

String

NodeInfo

Object

Property Schema

ADMIN
optional

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

Boolean

couchdb
required

CouchDB welcome

String

vendor
required

Product vendor

Get200ResponseVendor

version
optional

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

String

persistent_config
optional

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

Boolean

OpenID Connect callback properties

Object

Property

Schema

id_token
optional

The OpenID Connect ID token

String

refresh_token
optional

The OpenID Connect ID refresh token

String

session_id
optional

The Sync Gateway session token

String

name
optional

The Sync Gateway user

String

access_token
optional

The OpenID Connect access token

String

token_type
optional

The OpenID Connect ID token type

String

expires_in
optional

The time until the id_token expires (TTL).

Big Decimal

Object

Property

Schema

username
required

String

tokenttl
required

String

identity-token-formats
required

String

authenticated
required

String

OIDC-token

Object

Property

Schema

access_token
optional

String

token_type
optional

String

refresh_token
optional

String

expires_in
optional

String

id_token
optional

String

OpenID Connect callback properties

Object

Property

Schema

id_token
optional

The OpenID Connect ID token

String

refresh_token
optional

The OpenID Connect ID refresh token

String

session_id
optional

The Sync Gateway session token

String

name
optional

The Sync Gateway user

String

access_token
optional

The OpenID Connect access token

String

token_type
optional

The OpenID Connect ID token type

String

expires_in
optional

The time until the id_token expires (TTL).

Big Decimal

PostDbEnsureFullCommit201Response

Object

Property

Schema

instance_start_time
optional

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

Integer

ok
optional

Boolean

PostDbFacebook401Response

Object

Property

Schema

error
optional

String

reason
optional

String

PostDbFacebookRequest

Object

Property

Schema

access_token
required

Facebook access token to base the new session on.

String

PostDbGoogleRequest

Object

Property

Schema

id_token
required

Google ID token to base the new session on.

String

PostDbOidcTestingAuthenticateRequest

Object

Property

Schema

username
required

String

tokenttl
required

String

identity-token-formats
required

String

authenticated
required

String

PostDbOidcTestingTokenRequest

Object

Property Schema

grant_type
required

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

String

code
optional

grant_type=authorization_code only: The OpenID Connect authentication token.

String

refresh_token
optional

grant_type=refresh_token only: The OpenID Connect refresh token.

String

PostDbSession200Response

Object

Property Schema

authentication_handlers
required

Used for CouchDB compatability. Always contains "default" and "cookie".

Values: default, cookie

String array

ok
required

Used for CouchDB compatability. Always true.

Boolean

userCtx
required

PostDbSession200ResponseUserCtx

Object

Property Schema

channels
required

A map of the channels the user is in along with the sequence number the user was granted access.

PostKeyspaceRequestRevisions

name
required

The name of the user.

Minimum length: 1

String

PostDbSession200ResponseUserCtxChannelsValue

Composite Schema

One of the following:

Big Decimal
String

PostDbSessionRequest

Object

Property

Schema

name
optional

User name to generate the session for.

String

password
optional

Password of the user to generate the session for.

String

PostKeyspaceAllDocsRequest

Object

Property

Schema

keys
required

List of the documents to retrieve.

String array

PostKeyspaceBulkDocs201ResponseInner

Object

Property

Schema

id
required

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

String

rev
optional

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

String

error
optional

The error type if the operation of the document failed.

String

reason
optional

The reason the operation failed.

String

status
optional

The HTTP status code for why the operation failed.

Integer

PostKeyspaceBulkDocsRequest

Object

Property Schema

new_edits
optional

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

Boolean

docs
required

PostKeyspaceRequest array

PostKeyspaceBulkGetRequest

Object

Property

Schema

docs
required

PostKeyspaceBulkGetRequestDocsInner array

PostKeyspaceBulkGetRequestDocsInner

Object

Property

Schema

id
required

ID of the document to retrieve.

String

PostKeyspaceChangesRequest

Object

Property Schema

limit
optional

Maximum number of changes to return.

String

style
optional

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

String

active_only
optional

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

String

include_docs
optional

Include the body associated with each document.

Boolean

revocations
optional

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

String

filter
optional

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

String

channels
optional

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

String

doc_ids
optional

String

heartbeat
optional

String

timeout
optional

String

feed
optional

The type of changes feed to use.

String

PostKeyspaceRequest

Object

Property Schema

_id
optional

The ID of the document.

String

_rev
optional

The revision of the document.

String

_exp
optional

String

_deleted
optional

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

Boolean

_revisions
optional

_attachments
optional