Public REST API (Static Page)
Description of the Sync Gateway Public REST API, alternative representation as a static page
Related REST API topics: Admin REST API (Static Page) | Metrics REST API (Static Page)
Resources
This section describes the operations available with this REST API. The operations are grouped in the following categories.
Authentication
Manage OpenID Connect Authentication
OpenID Connect authentication initiation via Location header redirect
GET /{db}/_oidc
Description
Called by clients to initiate the OpenID Connect Authorization Code Flow. Redirects to the OpenID Connect provider if successful.
Parameters
Path Parameters
Name | Description | Schema |
---|---|---|
db |
The name of the database to run the operation against. |
String |
Query Parameters
Name | Description | Schema |
---|---|---|
provider |
The OpenID Connect provider to use for authentication. The list of providers are defined in the Sync Gateway config. If left empty, the default provider will be used. |
String |
offline |
If true, the OpenID Connect provider is requested to confirm with the user the permissions requested and refresh the OIDC token. To do this, access_type=offline and prompt=consent is set on the redirection link. |
String |
Responses
HTTP Code | Description | Schema |
---|---|---|
302 |
Successfully connected with the OpenID Connect provider so now redirecting to the requested OIDC provider for authentication. |
|
400 |
The provider provided is not defined in the Sync Gateway config. If no provided was specified then there is no default provider set. |
|
404 |
Resource could not be found |
|
500 |
Unable to connect and validate with the OpenID Connect provider requested |
OpenID Connect authentication callback
GET /{db}/_oidc_callback
Description
The callback URL that the client is redirected to after authenticating with the OpenID Connect provider.
Parameters
Path Parameters
Name | Description | Schema |
---|---|---|
db |
The name of the database to run the operation against. |
String |
Query Parameters
Name | Description | Schema |
---|---|---|
error |
The OpenID Connect error, if any occurred. |
String |
code |
The OpenID Connect authentication code. |
String |
provider |
The OpenID Connect provider to use for authentication. The list of providers are defined in the Sync Gateway config. If left empty, the default provider will be used. |
String |
state |
The OpenID Connect state to verify against the state cookie. This is used to prevent cross-site request forgery (CSRF). This is not required if |
String |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
Successfully authenticated with OpenID Connect. |
|
400 |
A problem occurred when reading the callback request body |
|
401 |
An error was received from the OpenID Connect provider. This means the error query parameter was filled. |
|
404 |
Resource could not be found |
|
500 |
A problem occurred in regards to the token |
OpenID Connect authentication initiation via WWW-Authenticate header
GET /{db}/_oidc_challenge
Description
Called by clients to initiate the OpenID Connect Authorization Code Flow. This will establish a connection with the provider, then put the redirect URL in the WWW-Authenticate
header.
Parameters
Path Parameters
Name | Description | Schema |
---|---|---|
db |
The name of the database to run the operation against. |
String |
Query Parameters
Name | Description | Schema |
---|---|---|
provider |
The OpenID Connect provider to use for authentication. The list of providers are defined in the Sync Gateway config. If left empty, the default provider will be used. |
String |
offline |
If true, the OpenID Connect provider is requested to confirm with the user the permissions requested and refresh the OIDC token. To do this, access_type=offline and prompt=consent is set on the redirection link. |
String |
Responses
HTTP Code | Description | Schema |
---|---|---|
400 |
The provider provided is not defined in the Sync Gateway config. If no provided was specified then there is no default provider set. |
|
401 |
Successfully connected with the OpenID Connect provider so now the client can login. |
|
404 |
Resource could not be found |
|
500 |
Unable to connect and validate with the OpenID Connect provider requested |
OpenID Connect token refresh
GET /{db}/_oidc_refresh
Parameters
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
Successfully authenticated with OpenID Connect. |
|
400 |
The provider provided is not defined in the Sync Gateway config. If no provided was specified then there is no default provider set. |
|
404 |
Resource could not be found |
|
500 |
Unable to connect and validate with the OpenID Connect provider requested |
OpenID Connect mock provider
GET /{db}/_oidc_testing/.well-known/openid-configuration
Description
Mock an OpenID Connect provider response for testing purposes. This returns a response that is the same structure as what Sync Gateway expects from an OIDC provider after initiating OIDC authentication.
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
Successfully generated OpenID Connect provider mock response. |
get_db__oidc_testing__well_known_openid_configuration_200_response |
403 |
The OpenID Connect unsupported config option |
|
404 |
Resource could not be found |
OpenID Connect mock login page handler
GET /{db}/_oidc_testing/authenticate
Description
Used to handle the login page displayed for the GET /{db}/_oidc_testing/authorize
endpoint.
Parameters
OpenID Connect mock login page
GET /{db}/_oidc_testing/authorize
Parameters
OpenID Connect public certificates for signing keys
GET /{db}/_oidc_testing/certs
Create a new Facebook-based session
POST /{db}/_facebook
Description
Creates a new session based on a Facebook user. On a successful session creation, a session cookie is stored to keep the user authenticated for future API calls.
If CORS is enabled, the origin must match an allowed login origin otherwise an error will be returned.
Parameters
Path Parameters
Name | Description | Schema |
---|---|---|
db |
The name of the database to run the operation against. |
String |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
Session created successfully |
|
400 |
Origin is not in the approved list of allowed origins |
|
401 |
Received error from Facebook verifier |
|
404 |
Resource could not be found |
|
502 |
Received invalid response from the Facebook verifier |
|
504 |
Unable to send request to Facebook API |
Create a new Google-based session
POST /{db}/_google
Description
Creates a new session based on a Google user. On a successful session creation, a session cookie is stored to keep the user authenticated for future API calls.
If CORS is enabled, the origin must match an allowed login origin otherwise an error will be returned.
Parameters
Path Parameters
Name | Description | Schema |
---|---|---|
db |
The name of the database to run the operation against. |
String |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
Session created successfully |
|
400 |
Origin is not in the approved list of allowed origins |
|
401 |
Received error from Google token verifier or invalid application ID in the config |
|
404 |
Resource could not be found |
|
502 |
Received invalid response from the Google token verifier |
|
504 |
Unable to send request to the Google token verifier |
OpenID Connect mock login page handler
POST /{db}/_oidc_testing/authenticate
Description
Used to handle the login page displayed for the GET /{db}/_oidc_testing/authorize
endpoint.
Parameters
Path Parameters
Name | Description | Schema |
---|---|---|
db |
The name of the database to run the operation against. |
String |
OpenID Connect mock login page
POST /{db}/_oidc_testing/authorize
Parameters
OpenID Connect mock token
POST /{db}/_oidc_testing/token
Parameters
Path Parameters
Name | Description | Schema |
---|---|---|
db |
The name of the database to run the operation against. |
String |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
Properties expected back from an OpenID Connect provider after successful authentication |
|
400 |
Invalid token provided |
|
403 |
The OpenID Connect unsupported config option |
|
404 |
Resource could not be found |
Database Management
Create and manage Sync Gateway databases
Get database information
GET /{db}/
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.
Parameters
Path Parameters
Name | Description | Schema |
---|---|---|
keyspace |
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
String |
Query Parameters
Name | Description | Schema |
---|---|---|
limit |
Maximum number of changes to return. |
Integer |
since |
Starts the results from the change immediately after the given sequence ID. Sequence IDs should be considered opaque; they come from the last_seq property of a prior response. |
String |
style |
Controls whether to return the current winning revision ( Values: |
String |
active_only |
Set true to exclude deleted documents and notifications for documents the user no longer has access to from the changes feed. Default: |
Boolean |
include_docs |
Include the body associated with each document. |
Boolean |
revocations |
If true, revocation messages will be sent on the changes feed. |
Boolean |
filter |
Set a filter to either filter by channels or document IDs. Values: |
String |
channels |
A comma-separated list of channel names to filter the response to only the channels specified. To use this option, the |
String |
doc_ids |
A valid JSON array of document IDs to filter the documents in the response to only the documents specified. To use this option, the |
String List |
heartbeat |
The interval (in milliseconds) to send an empty line (CRLF) in the response. This is to help prevent gateways from deciding the socket is idle and therefore closing it. This is only applicable to Default: |
Integer |
timeout |
This is the maximum period (in milliseconds) to wait for a change before the response is sent, even if there are no results. This is only applicable for Default: |
Integer |
feed |
The type of changes feed to use. Values: |
String |
Check if database exists
HEAD /{db}/
/{db}/_ensure_full_commit
POST /{db}/_ensure_full_commit
Get changes list
POST /{keyspace}/_changes
Description
This request retrieves a sorted list of changes made to documents in the database, in time order of application. Each document appears at most once, ordered by its most recent change, regardless of how many times it has been changed.
This request can be used to listen for update and modifications to the database for post processing or synchronization. A continuously connected changes feed is a reasonable approach for generating a real-time log for most applications.
Parameters
Path Parameters
Name | Description | Schema |
---|---|---|
keyspace |
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
String |
Compare revisions to what is in the database
POST /{keyspace}/_revs_diff
Description
Takes a set of document IDs, each with a set of revision IDs. For each document, an array of unknown revisions are returned with an array of known revisions that may be recent ancestors.
Parameters
Path Parameters
Name | Description | Schema |
---|---|---|
keyspace |
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
String |
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.
Parameters
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.
Parameters
Path Parameters
Name | Description | Schema |
---|---|---|
keyspace |
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
String |
docid |
The name of the local document ID excluding the |
String |
Gets all the documents in the database with the given parameters
GET /{keyspace}/_all_docs
Parameters
Path Parameters
Name | Description | Schema |
---|---|---|
keyspace |
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
String |
Query Parameters
Name | Description | Schema |
---|---|---|
include_docs |
Include the body associated with each document. |
Boolean |
channels |
Include the channels each document is part of that the calling user also has access too. |
Boolean |
access |
Include what user/roles that each document grants access too. |
Boolean |
revs |
Include all the revisions for each document under the |
Boolean |
update_seq |
Include the document sequence number |
Boolean |
keys |
An array of document ID strings to filter by. |
String List |
startkey |
Return records starting with the specified key. |
String |
endkey |
Stop returning records when this key is reached. |
String |
limit |
This limits the number of result rows returned. Using a value of |
BigDecimal |
Get a document
GET /{keyspace}/{docid}
Parameters
Path Parameters
Name | Description | Schema |
---|---|---|
keyspace |
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
String |
docid |
The document ID to run the operation against. |
String |
Query Parameters
Name | Description | Schema |
---|---|---|
rev |
The document revision to target. |
String |
open_revs |
Option to fetch specified revisions of the document. The value can be all to fetch all leaf revisions or an array of revision numbers (i.e. open_revs=["rev1", "rev2"]). Only leaf revision bodies that haven't been pruned are guaranteed to be returned. If this option is specified the response will be in multipart format. Use the |
String List |
show_exp |
Whether to show the expiry property ( |
Boolean |
revs_from |
Trim the revision history to stop at the first revision in the provided list. If no match is found, the revisions will be trimmed to the |
String List |
atts_since |
Include attachments only since specified revisions. Excludes the attachments for the specified revisions. Only gets used if |
String List |
revs_limit |
Maximum amount of revisions to return for each document. |
Integer |
attachments |
Include attachment bodies in response. |
Boolean |
replicator2 |
Returns the document with the required properties for replication. This is an enterprise-edition only feature. |
Boolean |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
Document found and returned successfully |
|
400 |
Document ID is not in an allowed format therefore is invalid. This could be because it is over 250 characters or is prefixed with an underscore (\"_\"). |
|
404 |
Resource could not be found |
|
501 |
Not Implemented. It is likely this error was caused due to trying to use an enterprise-only feature on the community edition. |
Get local document
GET /{keyspace}/_local/{docid}
Description
This request retrieves a local document.
Local document IDs begin with _local/
. Local documents are not replicated or indexed, don't support attachments, and don't save revision histories. In practice they are almost only used by Couchbase Lite's replicator, as a place to store replication checkpoint data.
Parameters
Path Parameters
Name | Description | Schema |
---|---|---|
keyspace |
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
String |
docid |
The name of the local document ID excluding the |
String |
/{db}/_all_docs
HEAD /{keyspace}/_all_docs
Parameters
Path Parameters
Name | Description | Schema |
---|---|---|
keyspace |
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
String |
Query Parameters
Name | Description | Schema |
---|---|---|
include_docs |
Include the body associated with each document. |
Boolean |
channels |
Include the channels each document is part of that the calling user also has access too. |
Boolean |
access |
Include what user/roles that each document grants access too. |
Boolean |
revs |
Include all the revisions for each document under the |
Boolean |
update_seq |
Include the document sequence number |
Boolean |
keys |
An array of document ID strings to filter by. |
String List |
startkey |
Return records starting with the specified key. |
String |
endkey |
Stop returning records when this key is reached. |
String |
limit |
This limits the number of result rows returned. Using a value of |
BigDecimal |
Check if a document exists
HEAD /{keyspace}/{docid}
Parameters
Path Parameters
Name | Description | Schema |
---|---|---|
keyspace |
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
String |
docid |
The document ID to run the operation against. |
String |
Query Parameters
Name | Description | Schema |
---|---|---|
rev |
The document revision to target. |
String |
open_revs |
Option to fetch specified revisions of the document. The value can be all to fetch all leaf revisions or an array of revision numbers (i.e. open_revs=["rev1", "rev2"]). Only leaf revision bodies that haven't been pruned are guaranteed to be returned. If this option is specified the response will be in multipart format. Use the |
String List |
show_exp |
Whether to show the expiry property ( |
Boolean |
revs_from |
Trim the revision history to stop at the first revision in the provided list. If no match is found, the revisions will be trimmed to the |
String List |
atts_since |
Include attachments only since specified revisions. Excludes the attachments for the specified revisions. Only gets used if |
String List |
revs_limit |
Maximum amount of revisions to return for each document. |
Integer |
attachments |
Include attachment bodies in response. |
Boolean |
replicator2 |
Returns the document with the required properties for replication. This is an enterprise-edition only feature. |
Boolean |
Check if local document exists
HEAD /{keyspace}/_local/{docid}
Description
This request checks if a local document exists.
Local document IDs begin with _local/
. Local documents are not replicated or indexed, don't support attachments, and don't save revision histories. In practice they are almost only used by Couchbase Lite's replicator, as a place to store replication checkpoint data.
Parameters
Path Parameters
Name | Description | Schema |
---|---|---|
keyspace |
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
String |
docid |
The name of the local document ID excluding the |
String |
Create a new document
POST /{keyspace}/
Description
Create a new document in the keyspace.
This will generate a random document ID unless specified in the body.
A document can have a maximum size of 20MB.
Parameters
Path Parameters
Name | Description | Schema |
---|---|---|
keyspace |
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
String |
Get all the documents in the database using a built-in view
POST /{keyspace}/_all_docs
Parameters
Path Parameters
Name | Description | Schema |
---|---|---|
keyspace |
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
String |
Query Parameters
Name | Description | Schema |
---|---|---|
include_docs |
Include the body associated with each document. |
Boolean |
channels |
Include the channels each document is part of that the calling user also has access too. |
Boolean |
access |
Include what user/roles that each document grants access too. |
Boolean |
revs |
Include all the revisions for each document under the |
Boolean |
update_seq |
Include the document sequence number |
Boolean |
startkey |
Return records starting with the specified key. |
String |
endkey |
Stop returning records when this key is reached. |
String |
limit |
This limits the number of result rows returned. Using a value of |
BigDecimal |
Bulk document operations
POST /{keyspace}/_bulk_docs
Description
This will allow multiple documented to be created, updated or deleted in bulk.
To create a new document, simply add the body in an object under docs
. A doc ID will be generated by Sync Gateway unless _id
is specified.
To update an existing document, provide the document ID (_id
) and revision ID (_rev
) as well as the new body values.
To delete an existing document, provide the document ID (_id
), revision ID (_rev
), and set the deletion flag (_deleted
) to true.
Parameters
Path Parameters
Name | Description | Schema |
---|---|---|
keyspace |
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
String |
Get multiple documents in a MIME multipart response
POST /{keyspace}/_bulk_get
Description
This request returns any number of documents, as individual bodies in a MIME multipart response.
Each enclosed body contains one requested document. The bodies appear in the same order as in the request, but can also be identified by their X-Doc-ID
and X-Rev-ID
headers (if the attachments
query is true
).
A body for a document with no attachments will have content type application/json
and contain the document itself.
A body for a document that has attachments will be written as a nested multipart/related
body.
Parameters
Path Parameters
Name | Description | Schema |
---|---|---|
keyspace |
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
String |
Body Parameter
Name | Description | Schema |
---|---|---|
Body |
Example: |
Header Parameters
Name | Description | Schema |
---|---|---|
X-Accept-Part-Encoding |
If this header includes |
String |
Accept-Encoding |
If this header includes |
String |
Query Parameters
Name | Description | Schema |
---|---|---|
attachments |
This is for whether to include attachments in each of the documents returned or not. Default: |
Boolean |
revs |
Include all the revisions for each document under the |
Boolean |
revs_limit |
The number of revisions to include in the response from the document history. This parameter only makes a different if the |
Integer |
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.
Parameters
Path Parameters
Name | Description | Schema |
---|---|---|
keyspace |
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
String |
docid |
The document ID to run the operation against. |
String |
Query Parameters
Name | Description | Schema |
---|---|---|
roundtrip |
Block until document has been received by change cache |
Boolean |
replicator2 |
Returns the document with the required properties for replication. This is an enterprise-edition only feature. |
Boolean |
new_edits |
Setting this to false indicates that the request body is an already-existing revision that should be directly inserted into the database, instead of a modification to apply to the current document. This mode is used for replication. This option must be used in conjunction with the Default: |
Boolean |
rev |
The document revision to target. |
String |
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.
Parameters
Path Parameters
Name | Description | Schema |
---|---|---|
keyspace |
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
String |
docid |
The name of the local document ID excluding the |
String |
Document Attachment
Create and manage document attachments
Delete an attachment on a document
DELETE /{keyspace}/{docid}/{attach}
Description
This request deletes an attachment associated with the document.
If the attachment exists, the attachment will be removed from the document.
Parameters
Path Parameters
Name | Description | Schema |
---|---|---|
keyspace |
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
String |
docid |
The document ID to run the operation against. |
String |
attach |
The attachment name. This value must be URL encoded. For example, if the attachment name is |
String |
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.
Parameters
Path Parameters
Name | Description | Schema |
---|---|---|
keyspace |
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
String |
docid |
The document ID to run the operation against. |
String |
attach |
The attachment name. This value must be URL encoded. For example, if the attachment name is |
String |
Query Parameters
Name | Description | Schema |
---|---|---|
rev |
The document revision to target. |
String |
content_encoding |
Set to false to disable the Default: |
Boolean |
meta |
Return only the metadata of the attachment in the response body. Default: |
Boolean |
Check if attachment exists
HEAD /{keyspace}/{docid}/{attach}
Parameters
Path Parameters
Name | Description | Schema |
---|---|---|
keyspace |
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
String |
docid |
The document ID to run the operation against. |
String |
attach |
The attachment name. This value must be URL encoded. For example, if the attachment name is |
String |
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.
Parameters
Path Parameters
Name | Description | Schema |
---|---|---|
keyspace |
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
String |
docid |
The document ID to run the operation against. |
String |
attach |
The attachment name. This value must be URL encoded. For example, if the attachment name is |
String |
Body Parameter
Name | Description | Schema |
---|---|---|
Body |
The attachment data Example: |
String |
Replication
Create and manage inter-Sync Gateway replications
Handle incoming BLIP Sync web socket request
GET /{db}/_blipsync
Description
This handles incoming BLIP Sync requests from either Couchbase Lite or another Sync Gateway node. The connection has to be upgradable to a websocket connection or else the request will fail.
Parameters
Server
Manage server activities
Session
Manage user sessions
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.
Get information about the current user
GET /{db}/_session
/{db}/_session
HEAD /{db}/_session
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.
Parameters
Path Parameters
Name | Description | Schema |
---|---|---|
db |
The name of the database to run the operation against. |
String |
Unsupported
Endpoints that are not supported by Sync Gateway
Delete a design document | Unsupported
DELETE /{db}/_design/{ddoc}
Get views of a design document | Unsupported
GET /{db}/_design/{ddoc}
Query a view on a design document | Unsupported
GET /{db}/_design/{ddoc}/_view/{view}
Parameters
Path Parameters
Name | Description | Schema |
---|---|---|
db |
The name of the database to run the operation against. |
String |
ddoc |
The design document name. |
String |
view |
The view to target. |
String |
Query Parameters
Name | Description | Schema |
---|---|---|
inclusive_end |
Indicates whether the specified end key should be included in the result. |
Boolean |
descending |
Return documents in descending order. |
Boolean |
include_docs |
Only works when using Couchbase Server 3.0 and earlier. Indicates whether to include the full content of the documents in the response. |
Boolean |
reduce |
Whether to execute a reduce function on the response or not. |
Boolean |
group |
Group the results using the reduce function to a group or single row. |
Boolean |
skip |
Skip the specified number of documents before starting to return results. |
Integer |
limit |
Return only the specified number of documents |
Integer |
group_level |
Specify the group level to be used. |
Integer |
startkey_docid |
Return documents starting with the specified document identifier. |
String |
endkey_docid |
Stop returning records when the specified document identifier is reached. |
String |
stale |
Allow the results from a stale view to be used, without triggering a rebuild of all views within the encompassing design document. Values: |
String |
startkey |
Return records starting with the specified key. |
String |
endkey |
Stop returning records when this key is reached. |
String |
key |
Return only the document that matches the specified key. |
String |
keys |
An array of document ID strings to filter by. |
String List |
Check if view of design document exists | Unsupported
HEAD /{db}/_design/{ddoc}
Update views of a design document | Unsupported
PUT /{db}/_design/{ddoc}
Parameters
Path Parameters
Name | Description | Schema |
---|---|---|
db |
The name of the database to run the operation against. |
String |
ddoc |
The design document name. |
String |
Definitions
This section describes the properties consumed and returned by this REST API.
ChangesFeed
Name | Description | Schema |
---|---|---|
results |
||
last_seq |
The last change sequence number. |
String |
Document
Name | Description | Schema |
---|---|---|
_id |
The ID of the document. |
String |
_rev |
The revision of the document. |
String |
_exp |
Expiry time after which the document will be purged. The expiration time is set and managed on the Couchbase Server document. The value can be specified in two ways; in ISO-8601 format, for example the 6th of July 2022 at 17:00 in the BST timezone would be As with the existing explicit purge mechanism, this applies only to the local database; it has nothing to do with replication. This expiration time is not propagated when the document is replicated. The purge of the document does not cause it to be deleted on any other database. |
String |
_deleted |
Whether the document is a tombstone or not. If true, it is a tombstone. |
Boolean |
_revisions |
||
_attachments |
Get200Response
Name | Description | Schema |
---|---|---|
ADMIN |
Example: |
Boolean |
couchdb |
CouchDB welcome Example: |
String |
vendor |
Product vendor |
|
version |
Product version, including the build number and edition (i.e. Example: |
String |
persistent_config |
Indication for whether sync gateway is running in persistent config mode or legacy config mode.
Example: |
Boolean |
Get200ResponseVendor
Name | Description | Schema |
---|---|---|
name |
Product name Example: |
String |
version |
API version.
Omitted if Example: |
String |
GetDb200Response
Name | Description | Schema |
---|---|---|
db_name |
Database name Example: |
String |
update_seq |
The last sequence number that was committed to the database. Will return 0 if the database is offline. Example: |
Integer |
committed_update_seq |
The last sequence number that was committed to the database. Will return 0 if the database is offline. Example: |
Integer |
instance_start_time |
Timestamp of when the database opened, in microseconds since the Unix epoch. Example: |
Integer |
compact_running |
Indicates whether database compaction is currently taking place or not. |
Boolean |
purge_seq |
Unused field. Default: |
BigDecimal |
disk_format_version |
Unused field. Default: |
BigDecimal |
state |
The database state. Change using the Values: |
String |
server_uuid |
Unique server identifier. Example: |
String |
GetDbDesignDdoc200Response
Name | Description | Schema |
---|---|---|
language |
String |
|
views |
||
options |
GetDbDesignDdoc200ResponseOptions
Name | Description | Schema |
---|---|---|
local_seq |
String |
|
include_design |
String |
|
raw |
String |
|
index_xattr_on_deleted_docs |
String |
GetDbDesignDdoc200ResponseViewsValue
Name | Description | Schema |
---|---|---|
map |
String |
|
reduce |
String |
GetDbDesignDdocViewView200Response
Name | Description | Schema |
---|---|---|
total_rows |
Integer |
|
rows |
||
errors |
get_db__design_ddoc__view_view_200_response_errors_inner List |
GetDbDesignDdocViewView200ResponseErrorsInner
Name | Description | Schema |
---|---|---|
From |
String |
|
Reason |
String |
GetDbDesignDdocViewView200ResponseRowsInner
Name | Description | Schema |
---|---|---|
id |
String |
|
key |
Object |
|
value |
Object |
|
doc |
Object |
GetDbOidcTestingCerts200ResponseKeysInner
Name | Description | Schema |
---|---|---|
Key |
Object |
|
KeyID |
String |
|
Use |
String |
|
Certificates |
Object List |
|
Algorithm |
String |
GetDbOidcTestingWellKnownOpenidConfiguration200Response
Name | Description | Schema |
---|---|---|
issuer |
String |
|
authorization_endpoint |
String |
|
token_endpoint |
String |
|
jwks_uri |
String |
|
userinfo_endpoint |
String |
|
id_token_signing_alg_values_supported |
String |
|
response_types_supported |
String |
|
subject_types_supported |
String |
|
scopes_supported |
String |
|
claims_supported |
String |
|
token_endpoint_auth_methods_supported |
String |
GetKeyspaceAllDocs200Response
Name | Description | Schema |
---|---|---|
rows |
||
total_rows |
BigDecimal |
|
update_seq |
BigDecimal |
GetKeyspaceAllDocs200ResponseRowsInner
Name | Description | Schema |
---|---|---|
key |
String |
|
id |
String |
|
value |
GetKeyspaceChanges200Response
Name | Description | Schema |
---|---|---|
results |
||
last_seq |
The last change sequence number. |
String |
GetKeyspaceChanges200ResponseResultsInner
Name | Description | Schema |
---|---|---|
seq |
The change sequence number. |
BigDecimal |
id |
The document ID the change happened on. |
String |
changes |
List of document leafs with each leaf containing only a |
get_keyspace__changes_200_response_results_inner_changes_inner Set |
GetKeyspaceChanges200ResponseResultsInnerChangesInner
Name | Description | Schema |
---|---|---|
rev |
The new revision that was caused by that change. |
String |
GetKeyspaceDocid200Response
Name | Description | Schema |
---|---|---|
_id |
The ID of the document. |
String |
_rev |
The revision ID of the document. |
String |
HTTP-Error
Name | Description | Schema |
---|---|---|
error |
The error name. |
String |
reason |
The error description. |
String |
New-revision
Name | Description | Schema |
---|---|---|
id |
The ID of the document. |
String |
ok |
Whether the request completed successfully. |
Boolean |
rev |
The revision of the document. |
String |
NodeInfo
Name | Description | Schema |
---|---|---|
ADMIN |
Example: |
Boolean |
couchdb |
CouchDB welcome Example: |
String |
vendor |
Product vendor |
|
version |
Product version, including the build number and edition (i.e. Example: |
String |
persistent_config |
Indication for whether sync gateway is running in persistent config mode or legacy config mode.
Example: |
Boolean |
OpenID Connect callback properties
Name | Description | Schema |
---|---|---|
id_token |
The OpenID Connect ID token |
String |
refresh_token |
The OpenID Connect ID refresh token |
String |
session_id |
The Sync Gateway session token |
String |
name |
The Sync Gateway user |
String |
access_token |
The OpenID Connect access token |
String |
token_type |
The OpenID Connect ID token type |
String |
expires_in |
The time until the id_token expires (TTL). |
BigDecimal |
OIDCLoginPageHandler
Name | Description | Schema |
---|---|---|
username |
String |
|
tokenttl |
String |
|
identity-token-formats |
String |
|
authenticated |
String |
OIDC-token
Name | Description | Schema |
---|---|---|
access_token |
String |
|
token_type |
String |
|
refresh_token |
String |
|
expires_in |
String |
|
id_token |
String |
OpenID Connect callback properties
Name | Description | Schema |
---|---|---|
id_token |
The OpenID Connect ID token |
String |
refresh_token |
The OpenID Connect ID refresh token |
String |
session_id |
The Sync Gateway session token |
String |
name |
The Sync Gateway user |
String |
access_token |
The OpenID Connect access token |
String |
token_type |
The OpenID Connect ID token type |
String |
expires_in |
The time until the id_token expires (TTL). |
BigDecimal |
PostDbEnsureFullCommit201Response
Name | Description | Schema |
---|---|---|
instance_start_time |
Timestamp of when the database opened, in microseconds since the Unix epoch. Example: |
Integer |
ok |
Default: |
Boolean |
PostDbFacebookRequest
Name | Description | Schema |
---|---|---|
access_token |
Facebook access token to base the new session on. |
String |
PostDbGoogleRequest
Name | Description | Schema |
---|---|---|
id_token |
Google ID token to base the new session on. |
String |
PostDbOidcTestingAuthenticateRequest
Name | Description | Schema |
---|---|---|
username |
String |
|
tokenttl |
String |
|
identity-token-formats |
String |
|
authenticated |
String |
PostDbOidcTestingTokenRequest
Name | Description | Schema |
---|---|---|
grant_type |
The grant type of the token to request. Can either be an |
String |
code |
|
String |
refresh_token |
|
String |
PostDbSession200Response
Name | Description | Schema |
---|---|---|
authentication_handlers |
Used for CouchDB compatability. Always contains "default" and "cookie". Values: |
String List |
ok |
Used for CouchDB compatability. Always true. Default: |
Boolean |
userCtx |
PostDbSession200ResponseUserCtx
Name | Description | Schema |
---|---|---|
channels |
A map of the channels the user is in along with the sequence number the user was granted access. |
|
name |
The name of the user. |
String |
PostDbSessionRequest
Name | Description | Schema |
---|---|---|
name |
User name to generate the session for. |
String |
password |
Password of the user to generate the session for. |
String |
PostKeyspaceAllDocsRequest
Name | Description | Schema |
---|---|---|
keys |
List of the documents to retrieve. |
String List |
PostKeyspaceBulkDocs201ResponseInner
Name | Description | Schema |
---|---|---|
id |
The ID of the document that the operation was performed on. |
String |
rev |
The new revision of the document if the operation was a success. |
String |
error |
The error type if the operation of the document failed. |
String |
reason |
The reason the operation failed. |
String |
status |
The HTTP status code for why the operation failed. |
Integer |
PostKeyspaceBulkDocsRequest
Name | Description | Schema |
---|---|---|
new_edits |
This controls whether to assign new revision identifiers to new edits ( Default: |
Boolean |
docs |
post_keyspace__request List |
PostKeyspaceBulkGetRequestDocsInner
Name | Description | Schema |
---|---|---|
id |
ID of the document to retrieve. |
String |
PostKeyspaceChangesRequest
Name | Description | Schema |
---|---|---|
limit |
Maximum number of changes to return. |
String |
style |
Controls whether to return the current winning revision ( |
String |
active_only |
Set true to exclude deleted documents and notifications for documents the user no longer has access to from the changes feed. |
String |
include_docs |
Include the body associated with each document. |
Boolean |
revocations |
If true, revocation messages will be sent on the changes feed. |
String |
filter |
Set a filter to either filter by channels or document IDs. |
String |
channels |
A comma-separated list of channel names to filter the response to only the channels specified. To use this option, the |
String |
doc_ids |
A valid JSON array of document IDs to filter the documents in the response to only the documents specified. To use this option, the |
String |
heartbeat |
The interval (in milliseconds) to send an empty line (CRLF) in the response. This is to help prevent gateways from deciding the socket is idle and therefore closing it. This is only applicable to |
String |
timeout |
This is the maximum period (in milliseconds) to wait for a change before the response is sent, even if there are no results. This is only applicable for |
String |
feed |
The type of changes feed to use. |
String |
PostKeyspaceRequest
Name | Description | Schema |
---|---|---|
_id |
The ID of the document. |
String |
_rev |
The revision of the document. |
String |
_exp |
Expiry time after which the document will be purged. The expiration time is set and managed on the Couchbase Server document. The value can be specified in two ways; in ISO-8601 format, for example the 6th of July 2022 at 17:00 in the BST timezone would be As with the existing explicit purge mechanism, this applies only to the local database; it has nothing to do with replication. This expiration time is not propagated when the document is replicated. The purge of the document does not cause it to be deleted on any other database. |
String |
_deleted |
Whether the document is a tombstone or not. If true, it is a tombstone. |
Boolean |
_revisions |
||
_attachments |
PostKeyspaceRequestAttachmentsValue
Name | Description | Schema |
---|---|---|
content_type |
Content type of the attachment. |
String |
data |
The data in the attachment in base64. |
String |
PostKeyspaceRequestRevisions
Name | Description | Schema |
---|---|---|
start |
Prefix number for the latest revision. |
BigDecimal |
ids |
Array of valid revision IDs, in reverse order (latest first). |
String List |
PostKeyspaceRevsDiff200ResponseDocid
Name | Description | Schema |
---|---|---|
missing |
The revisions that are not in the database (and therefore |
String List |
possible_ancestors |
An array of known revisions that might be the recent ancestors. |
String List |
PostKeyspaceRevsDiffRequest
Name | Description | Schema |
---|---|---|
docid |
The document ID with an array of revisions to use for the comparison. |
String List |
PutKeyspaceLocalDocidRequest
Name | Description | Schema |
---|---|---|
_rev |
Revision to replace. Required if updating existing local document. |
String |