Sync Gateway (3.2)

Download OpenAPI specification:Download

Sync Gateway manages access and synchronization between Couchbase Lite and Couchbase 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

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

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

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

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

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

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

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

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

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

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

Manage OpenID Connect Authentication

Create a new Facebook-based session Deprecated

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

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

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

Request Body schema: application/json
access_token
required
string

Facebook access token to base the new session on.

Responses

Request samples

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.

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

Create and manage documents

Create a new document

Create a new document in the keyspace.

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

A document can have a maximum size of 20MB.

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

The keyspace to run the operation against.

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

query Parameters
roundtrip
boolean

Block until document has been received by change cache

Request Body schema: application/json
_id
string

The ID of the document.

_rev
string

The revision of the document.

_exp
string

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

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

_deleted
boolean

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

object
object
property name*
additional property
any

Responses

Request samples

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.

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

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

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

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

The keyspace to run the operation against.

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

Request Body schema: application/json
new_edits
boolean
Default: true

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

required
Array of objects (Document)

Responses

Request samples

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.

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

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

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

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

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

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

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

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

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

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

The keyspace to run the operation against.

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

docid
required
string
Example: doc1

The document ID to run the operation against.

query Parameters
rev
string
Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58

The document revision to target.

open_revs
Array of strings

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

show_exp
boolean

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

revs_from
Array of strings

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

atts_since
Array of strings

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

revs_limit
integer

Maximum amount of revisions to return for each document.

attachments
boolean

Include attachment bodies in response.

replicator2
boolean

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

Responses

Response samples

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.

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

The keyspace to run the operation against.

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

docid
required
string
Example: doc1

The document ID to run the operation against.

query Parameters
roundtrip
boolean

Block until document has been received by change cache

replicator2
boolean

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

new_edits
boolean
Default: "true"

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

rev
string
Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58

The document revision to target.

header Parameters
If-Match
string

The revision ID to target.

Request Body schema: application/json
_id
string

The ID of the document.

_rev
string

The revision of the document.

_exp
string

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

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

_deleted
boolean

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

object
object
property name*
additional property
any

Responses

Request samples

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.

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

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

The keyspace to run the operation against.

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

docid
required
string
Example: doc1

The document ID to run the operation against.

query Parameters
rev
string
Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58

The document revision to target.

open_revs
Array of strings

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

show_exp
boolean

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

revs_from
Array of strings

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

atts_since
Array of strings

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

revs_limit
integer

Maximum amount of revisions to return for each document.

attachments
boolean

Include attachment bodies in response.

replicator2
boolean

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

Responses

Response samples

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

Document Attachment

Create and manage document attachments

Get an attachment from a document

This request retrieves a file attachment associated with the document.

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

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

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

The keyspace to run the operation against.

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

docid
required
string
Example: doc1

The document ID to run the operation against.

attach
required
string

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

query Parameters
rev
string
Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58

The document revision to target.

content_encoding
boolean
Default: "true"

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

meta
boolean
Default: "false"

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

header Parameters
Range
string
Example: bytes=123-456

RFC-2616 bytes range header.

Responses

Response samples

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

Create or update an attachment on a document

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

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

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

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

The keyspace to run the operation against.

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

docid
required
string
Example: doc1

The document ID to run the operation against.

attach
required
string

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

query Parameters
rev
string

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

header Parameters
Content-Type
string
Default: application/octet-stream

The content type of the attachment.

If-Match
string

An alternative way of specifying the document revision ID.

Request Body schema: Attachment content type

The attachment data

string

The content to store in the body

Responses

Response samples

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.

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

This request deletes an attachment associated with the document.

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

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

The keyspace to run the operation against.

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

docid
required
string
Example: doc1

The document ID to run the operation against.

attach
required
string

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

query Parameters
rev
string

The existing document revision ID to modify.

header Parameters
If-Match
string

An alternative way of specifying the document revision ID.

Responses

Response samples

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

Endpoints that are not supported by Sync Gateway

Get views of a design document | Unsupported

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

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

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

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

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