Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

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
      required

      The name of the database to run the operation against.

      String
      Query Parameters
      Name Description Schema

      provider
      optional

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

      String

      offline
      optional

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

      String
      Produces

      • application/json

      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

      HTTP_Error

      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
      required

      The name of the database to run the operation against.

      String
      Query Parameters
      Name Description Schema

      error
      optional

      The OpenID Connect error, if any occurred.

      String

      code
      required

      The OpenID Connect authentication code.

      String

      provider
      optional

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

      String

      state
      optional

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

      String
      Produces

      • application/json

      Responses
      HTTP Code Description Schema

      200

      Successfully authenticated with OpenID Connect.

      OpenID_Connect_callback_properties

      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

      HTTP_Error

      500

      A problem occurred in regards to the token

      post_db__facebook_401_response

      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
      required

      The name of the database to run the operation against.

      String
      Query Parameters
      Name Description Schema

      provider
      optional

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

      String

      offline
      optional

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

      String
      Produces

      • application/json

      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

      HTTP_Error

      500

      Unable to connect and validate with the OpenID Connect provider requested

      OpenID Connect token refresh

      GET /{db}/_oidc_refresh
      Description

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

      Parameters
      Path Parameters
      Name Description Schema

      db
      required

      The name of the database to run the operation against.

      String
      Query Parameters
      Name Description Schema

      refresh_token
      required

      The OpenID Connect refresh token.

      String

      provider
      optional

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

      String
      Produces

      • application/json

      Responses
      HTTP Code Description Schema

      200

      Successfully authenticated with OpenID Connect.

      OpenID_Connect_callback_properties

      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

      HTTP_Error

      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.

      Parameters
      Path Parameters
      Name Description Schema

      db
      required

      The name of the database to run the operation against.

      String
      Produces

      • application/json

      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 oidc_test_provider is not enabled. To use this endpoint, this option must be enabled.

      404

      Resource could not be found

      HTTP_Error

      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
      Path Parameters
      Name Description Schema

      db
      required

      The name of the database to run the operation against.

      String
      Query Parameters
      Name Description Schema

      redirect_uri
      optional

      The Sync Gateway OpenID Connect callback URL.

      String

      scope
      required

      The OpenID Connect authentication scope.

      String

      username
      required

      String

      tokenttl
      required

      Integer

      identity-token-formats
      required

      String

      authenticated
      required

      String
      Produces

      • application/json

      Responses
      HTTP Code Description Schema

      302

      Redirecting to Sync Gateway OpenID Connect callback URL

      403

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

      404

      Resource could not be found

      HTTP_Error

      OpenID Connect mock login page

      GET /{db}/_oidc_testing/authorize
      Description

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

      Parameters
      Path Parameters
      Name Description Schema

      db
      required

      The name of the database to run the operation against.

      String
      Query Parameters
      Name Description Schema

      scope
      required

      The OpenID Connect authentication scope.

      String
      Produces

      • application/json

      Responses
      HTTP Code Description Schema

      200

      OK

      400

      A validation error occurred with the scope.

      HTTP_Error

      403

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

      404

      Resource could not be found

      HTTP_Error

      500

      An error occurred.

      HTTP_Error

      OpenID Connect public certificates for signing keys

      GET /{db}/_oidc_testing/certs
      Description

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

      Parameters
      Path Parameters
      Name Description Schema

      db
      required

      The name of the database to run the operation against.

      String
      Produces

      • application/json

      Responses
      HTTP Code Description Schema

      200

      Returned public key successfully

      get_db__oidc_testing_certs_200_response

      403

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

      404

      Resource could not be found

      HTTP_Error

      500

      An error occurred while getting the private RSA key

      post_db__facebook_401_response

      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
      required

      The name of the database to run the operation against.

      String
      Body Parameter
      Name Description Schema

      Body
      optional

      PostDbFacebookRequest
      Produces

      • application/json

      Consumes

      • application/json

      Responses
      HTTP Code Description Schema

      200

      Session created successfully

      400

      Origin is not in the approved list of allowed origins

      HTTP_Error

      401

      Received error from Facebook verifier

      post_db__facebook_401_response

      404

      Resource could not be found

      HTTP_Error

      502

      Received invalid response from the Facebook verifier

      post_db__facebook_401_response

      504

      Unable to send request to Facebook API

      post_db__facebook_401_response

      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
      required

      The name of the database to run the operation against.

      String
      Body Parameter
      Name Description Schema

      Body
      optional

      PostDbGoogleRequest
      Produces

      • application/json

      Consumes

      • application/json

      Responses
      HTTP Code Description Schema

      200

      Session created successfully

      400

      Origin is not in the approved list of allowed origins

      HTTP_Error

      401

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

      post_db__facebook_401_response

      404

      Resource could not be found

      HTTP_Error

      502

      Received invalid response from the Google token verifier

      post_db__facebook_401_response

      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
      required

      The name of the database to run the operation against.

      String
      Body Parameter
      Name Description Schema

      Body
      optional

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

      PostDbOidcTestingAuthenticateRequest
      Query Parameters
      Name Description Schema

      redirect_uri
      optional

      The Sync Gateway OpenID Connect callback URL.

      String

      scope
      required

      The OpenID Connect authentication scope.

      String
      Produces

      • application/json

      Consumes

      • application/json

      Responses
      HTTP Code Description Schema

      302

      Redirecting to Sync Gateway OpenID Connect callback URL

      403

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

      404

      Resource could not be found

      HTTP_Error

      OpenID Connect mock login page

      POST /{db}/_oidc_testing/authorize
      Description

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

      Parameters
      Path Parameters
      Name Description Schema

      db
      required

      The name of the database to run the operation against.

      String
      Query Parameters
      Name Description Schema

      scope
      required

      The OpenID Connect authentication scope.

      String
      Produces

      • application/json

      Responses
      HTTP Code Description Schema

      200

      OK

      400

      A validation error occurred with the scope.

      HTTP_Error

      403

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

      404

      Resource could not be found

      HTTP_Error

      500

      An error occurred.

      HTTP_Error

      OpenID Connect mock token

      POST /{db}/_oidc_testing/token
      Description

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

      Parameters
      Path Parameters
      Name Description Schema

      db
      required

      The name of the database to run the operation against.

      String
      Body Parameter
      Name Description Schema

      Body
      optional

      PostDbOidcTestingTokenRequest
      Produces

      • application/json

      Consumes

      • application/json

      Responses
      HTTP Code Description Schema

      200

      Properties expected back from an OpenID Connect provider after successful authentication

      OIDC_token

      400

      Invalid token provided

      403

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

      404

      Resource could not be found

      HTTP_Error

      Database Management

      Create and manage Sync Gateway databases

      Get database information

      GET /{db}/
      Description

      Retrieve information about the database.

      Parameters
      Path Parameters
      Name Description Schema

      db
      required

      The name of the database to run the operation against.

      String
      Produces

      • application/json

      Responses
      HTTP Code Description Schema

      200

      Successfully returned database information

      get_db__200_response

      404

      Resource could not be found

      HTTP_Error

      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
      required

      The keyspace to run the operation against.

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

      String
      Query Parameters
      Name Description Schema

      limit
      optional

      Maximum number of changes to return.

      Integer

      since
      optional

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

      String

      style
      optional

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

      Values: main_only, all_docs
      Default: main_only

      String

      active_only
      optional

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

      Default: false

      Boolean

      include_docs
      optional

      Include the body associated with each document.

      String

      revocations
      optional

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

      Boolean

      filter
      optional

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

      Values: sync_gateway/bychannel, _doc_ids

      String

      channels
      optional

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

      String

      doc_ids
      optional

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

      String List

      heartbeat
      optional

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

      Default: 0
      Minimum: 25000

      Integer

      timeout
      optional

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

      Default: 300000
      Minimum: 0
      Maximum: 900000

      Integer

      feed
      optional

      The type of changes feed to use.

      Values: normal, longpoll, continuous, websocket
      Default: normal

      String
      Produces

      • application/json

      Responses
      HTTP Code Description Schema

      200

      Successfully returned the changes feed

      get_keyspace__changes_200_response

      400

      There was a problem with your request

      HTTP_Error

      404

      Resource could not be found

      HTTP_Error

      Check if database exists

      HEAD /{db}/
      Description

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

      Parameters
      Path Parameters
      Name Description Schema

      db
      required

      The name of the database to run the operation against.

      String
      Produces

      • application/json

      Responses
      HTTP Code Description Schema

      200

      Database exists

      404

      Resource could not be found

      HTTP_Error

      /{db}/_changes

      HEAD /{keyspace}/_changes
      Description
      Parameters
      Path Parameters
      Name Description Schema

      keyspace
      required

      The keyspace to run the operation against.

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

      String
      Responses
      HTTP Code Description Schema

      200

      OK

      400

      Bad Request

      404

      Not Found

      /{db}/_ensure_full_commit

      POST /{db}/_ensure_full_commit
      Description

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

      Parameters
      Path Parameters
      Name Description Schema

      db
      required

      The name of the database to run the operation against.

      String
      Produces

      • application/json

      Responses
      HTTP Code Description Schema

      201

      OK

      post_db__ensure_full_commit_201_response

      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
      required

      The keyspace to run the operation against.

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

      String
      Body Parameter
      Name Description Schema

      Body
      optional

      PostKeyspaceChangesRequest
      Produces

      • application/json

      Consumes

      • application/json

      Responses
      HTTP Code Description Schema

      200

      Successfully returned the changes feed

      get_keyspace__changes_200_response

      400

      There was a problem with your request

      HTTP_Error

      404

      Resource could not be found

      HTTP_Error

      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
      required

      The keyspace to run the operation against.

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

      String
      Body Parameter
      Name Description Schema

      Body
      optional

      PostKeyspaceRevsDiffRequest
      Produces

      • application/json

      Consumes

      • application/json

      Responses
      HTTP Code Description Schema

      200

      Comparisons successful

      post_keyspace__revs_diff_200_response

      404

      Resource could not be found

      HTTP_Error

      Create DB public API stub

      PUT /{targetdb}/
      Description

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

      Parameters
      Path Parameters
      Name Description Schema

      targetdb
      required

      The database name to target.

      String
      Responses
      HTTP Code Description Schema

      403

      Database does not exist and cannot be created over the public API

      412

      Database exists

      Document

      Create and manage documents

      Delete a document

      DELETE /{keyspace}/{docid}
      Description

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

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

      Parameters
      Path Parameters
      Name Description Schema

      keyspace
      required

      The keyspace to run the operation against.

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

      String

      docid
      required

      The document ID to run the operation against.

      String
      Header Parameters
      Name Description Schema

      If-Match
      optional

      The revision ID to target.

      String
      Query Parameters
      Name Description Schema

      rev
      optional

      The document revision to target.

      String
      Produces

      • application/json

      Responses
      HTTP Code Description Schema

      200

      New revision created successfully

      New_revision

      400

      There was a problem with your request

      HTTP_Error

      404

      Resource could not be found

      HTTP_Error

      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
      required

      The keyspace to run the operation against.

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

      String

      docid
      required

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

      String
      Query Parameters
      Name Description Schema

      rev
      required

      The revision ID of the revision to delete.

      String
      Produces

      • application/json

      Responses
      HTTP Code Description Schema

      200

      Successfully removed the local document.

      400

      There was a problem with your request

      HTTP_Error

      404

      Resource could not be found

      HTTP_Error

      409

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

      Gets all the documents in the database with the given parameters

      GET /{keyspace}/_all_docs
      Description

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

      Parameters
      Path Parameters
      Name Description Schema

      keyspace
      required

      The keyspace to run the operation against.

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

      String
      Query Parameters
      Name Description Schema

      include_docs
      optional

      Include the body associated with each document.

      String

      channels
      optional

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

      String

      access
      optional

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

      String

      revs
      optional

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

      String

      update_seq
      optional

      Include the document sequence number update_seq property for each document.

      String

      keys
      optional

      An array of document ID strings to filter by.

      String List

      startkey
      optional

      Return records starting with the specified key.

      String

      endkey
      optional

      Stop returning records when this key is reached.

      String

      limit
      optional

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

      BigDecimal
      Produces

      • application/json

      Responses
      HTTP Code Description Schema

      200

      Operation ran successfully

      get_keyspace__all_docs_200_response

      400

      There was a problem with your request

      HTTP_Error

      404

      Resource could not be found

      HTTP_Error

      Get a document

      GET /{keyspace}/{docid}
      Description

      Retrieve a document from the database by its doc ID.

      Parameters
      Path Parameters
      Name Description Schema

      keyspace
      required

      The keyspace to run the operation against.

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

      String

      docid
      required

      The document ID to run the operation against.

      String
      Query Parameters
      Name Description Schema

      rev
      optional

      The document revision to target.

      String

      open_revs
      optional

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

      String List

      show_exp
      optional

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

      Boolean

      revs_from
      optional

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

      String List

      atts_since
      optional

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

      String List

      revs_limit
      optional

      Maximum amount of revisions to return for each document.

      Integer

      attachments
      optional

      Include attachment bodies in response.

      Boolean

      replicator2
      optional

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

      Boolean
      Produces

      • application/json

      Responses
      HTTP Code Description Schema

      200

      Document found and returned successfully

      get_keyspace_docid_200_response

      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 (\"_\").

      HTTP_Error

      404

      Resource could not be found

      HTTP_Error

      501

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

      HTTP_Error

      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
      required

      The keyspace to run the operation against.

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

      String

      docid
      required

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

      String
      Produces

      • application/json

      Responses
      HTTP Code Description Schema

      200

      Successfully found local document

      400

      There was a problem with your request

      HTTP_Error

      404

      Resource could not be found

      HTTP_Error

      /{db}/_all_docs

      HEAD /{keyspace}/_all_docs
      Description
      Parameters
      Path Parameters
      Name Description Schema

      keyspace
      required

      The keyspace to run the operation against.

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

      String
      Query Parameters
      Name Description Schema

      include_docs
      optional

      Include the body associated with each document.

      String

      channels
      optional

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

      String

      access
      optional

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

      String

      revs
      optional

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

      String

      update_seq
      optional

      Include the document sequence number update_seq property for each document.

      String

      keys
      optional

      An array of document ID strings to filter by.

      String List

      startkey
      optional

      Return records starting with the specified key.

      String

      endkey
      optional

      Stop returning records when this key is reached.

      String

      limit
      optional

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

      BigDecimal
      Produces

      • application/json

      Responses
      HTTP Code Description Schema

      200

      OK

      400

      There was a problem with your request

      HTTP_Error

      404

      Resource could not be found

      HTTP_Error

      Check if a document exists

      HEAD /{keyspace}/{docid}
      Description

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

      Parameters
      Path Parameters
      Name Description Schema

      keyspace
      required

      The keyspace to run the operation against.

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

      String

      docid
      required

      The document ID to run the operation against.

      String
      Query Parameters
      Name Description Schema

      rev
      optional

      The document revision to target.

      String

      open_revs
      optional

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

      String List

      show_exp
      optional

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

      Boolean

      revs_from
      optional

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

      String List

      atts_since
      optional

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

      String List

      revs_limit
      optional

      Maximum amount of revisions to return for each document.

      Integer

      attachments
      optional

      Include attachment bodies in response.

      Boolean

      replicator2
      optional

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

      Boolean
      Produces

      • application/json

      Responses
      HTTP Code Description Schema

      200

      Document exists

      400

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

      HTTP_Error

      404

      Resource could not be found

      HTTP_Error

      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
      required

      The keyspace to run the operation against.

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

      String

      docid
      required

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

      String
      Produces

      • application/json

      Responses
      HTTP Code Description Schema

      200

      Document exists

      400

      There was a problem with your request

      HTTP_Error

      404

      Resource could not be found

      HTTP_Error

      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
      required

      The keyspace to run the operation against.

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

      String
      Body Parameter
      Name Description Schema

      Body
      optional

      PostKeyspaceRequest
      Query Parameters
      Name Description Schema

      roundtrip
      optional

      Block until document has been received by change cache

      Boolean
      Produces

      • application/json

      Consumes

      • application/json

      Responses
      HTTP Code Description Schema

      200

      New document revision created successfully.

      New_revision

      400

      There was a problem with your request

      HTTP_Error

      404

      Resource could not be found

      HTTP_Error

      409

      Resource already exists under that name

      HTTP_Error

      415

      Invalid content type

      HTTP_Error

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

      POST /{keyspace}/_all_docs
      Description

      Get a built-in view of all the documents in the database.

      Parameters
      Path Parameters
      Name Description Schema

      keyspace
      required

      The keyspace to run the operation against.

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

      String
      Body Parameter
      Name Description Schema

      Body
      optional

      PostKeyspaceAllDocsRequest
      Query Parameters
      Name Description Schema

      include_docs
      optional

      Include the body associated with each document.

      String

      channels
      optional

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

      String

      access
      optional

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

      String

      revs
      optional

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

      String

      update_seq
      optional

      Include the document sequence number update_seq property for each document.

      String

      startkey
      optional

      Return records starting with the specified key.

      String

      endkey
      optional

      Stop returning records when this key is reached.

      String

      limit
      optional

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

      BigDecimal
      Produces

      • application/json

      Consumes

      • application/json

      Responses
      HTTP Code Description Schema

      200

      Operation ran successfully

      get_keyspace__all_docs_200_response

      400

      There was a problem with your request

      HTTP_Error

      404

      Resource could not be found

      HTTP_Error

      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
      required

      The keyspace to run the operation against.

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

      String
      Body Parameter
      Name Description Schema

      Body
      optional

      Example: {"new_edits":true,"docs":[{"_id":"FooBar","foo":"bar"},{"_id":"AliceSettings","_rev":"5-832a6db48ed130adadede928aee54576","FailedLoginAttempts":7},{"_id":"BobSettings","_rev":"1-fa76ba41ee5fdfee1b91fc478ed09e59","_deleted":true}]}

      PostKeyspaceBulkDocsRequest
      Produces

      • application/json

      Consumes

      • application/json

      Responses
      HTTP Code Description Schema

      201

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

      Set

      400

      There was a problem with your request

      HTTP_Error

      404

      Resource could not be found

      HTTP_Error

      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
      required

      The keyspace to run the operation against.

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

      String
      Body Parameter
      Name Description Schema

      Body
      optional

      Example: {"docs":[{"id":"FooBar"},{"id":"attachment"},{"id":"AliceSettings"}]}

      PostKeyspaceBulkGetRequest
      Header Parameters
      Name Description Schema

      X-Accept-Part-Encoding
      optional

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

      String

      Accept-Encoding
      optional

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

      String
      Query Parameters
      Name Description Schema

      attachments
      optional

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

      Default: false

      Boolean

      revs
      optional

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

      String

      revs_limit
      optional

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

      Integer
      Produces

      • application/json

      Consumes

      • application/json

      Responses
      HTTP Code Description Schema

      200

      Returned the requested docs as multipart/mixed response type

      400

      Bad Request

      404

      Resource could not be found

      HTTP_Error

      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
      required

      The keyspace to run the operation against.

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

      String

      docid
      required

      The document ID to run the operation against.

      String
      Body Parameter
      Name Description Schema

      Body
      optional

      PostKeyspaceRequest
      Header Parameters
      Name Description Schema

      If-Match
      optional

      The revision ID to target.

      String
      Query Parameters
      Name Description Schema

      roundtrip
      optional

      Block until document has been received by change cache

      Boolean

      replicator2
      optional

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

      Boolean

      new_edits
      optional

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

      Default: true

      Boolean

      rev
      optional

      The document revision to target.

      String
      Produces

      • application/json

      Consumes

      • application/json

      Responses
      HTTP Code Description Schema

      201

      Created

      New_revision

      400

      There was a problem with your request

      HTTP_Error

      404

      Resource could not be found

      HTTP_Error

      409

      Resource already exists under that name

      HTTP_Error

      415

      Invalid content type

      HTTP_Error

      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
      required

      The keyspace to run the operation against.

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

      String

      docid
      required

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

      String
      Body Parameter
      Name Description Schema

      Body
      optional

      The body of the document

      PutKeyspaceLocalDocidRequest
      Produces

      • application/json

      Consumes

      • application/json

      Responses
      HTTP Code Description Schema

      201

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

      New_revision

      400

      There was a problem with your request

      HTTP_Error

      404

      Resource could not be found

      HTTP_Error

      409

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

      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
      required

      The keyspace to run the operation against.

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

      String

      docid
      required

      The document ID to run the operation against.

      String

      attach
      required

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

      String
      Header Parameters
      Name Description Schema

      If-Match
      optional

      An alternative way of specifying the document revision ID.

      String
      Query Parameters
      Name Description Schema

      rev
      optional

      The existing document revision ID to modify.

      String
      Produces

      • application/json

      Responses
      HTTP Code Description Schema

      200

      Attachment removed from the document successfully

      New_revision

      404

      Resource could not be found

      HTTP_Error

      409

      Resource already exists under that name

      HTTP_Error

      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
      required

      The keyspace to run the operation against.

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

      String

      docid
      required

      The document ID to run the operation against.

      String

      attach
      required

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

      String
      Header Parameters
      Name Description Schema

      Range
      optional

      RFC-2616 bytes range header.

      String
      Query Parameters
      Name Description Schema

      rev
      optional

      The document revision to target.

      String

      content_encoding
      optional

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

      Default: true

      Boolean

      meta
      optional

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

      Default: false

      Boolean
      Produces

      • application/json

      Responses
      HTTP Code Description Schema

      200

      Found attachment successfully.

      206

      Partial attachment content returned

      404

      Resource could not be found

      HTTP_Error

      416

      Requested range exceeds content length

      Check if attachment exists

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

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

      Parameters
      Path Parameters
      Name Description Schema

      keyspace
      required

      The keyspace to run the operation against.

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

      String

      docid
      required

      The document ID to run the operation against.

      String

      attach
      required

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

      String
      Query Parameters
      Name Description Schema

      rev
      optional

      The document revision to target.

      String
      Produces

      • application/json

      Responses
      HTTP Code Description Schema

      200

      The document exists and the attachment exists on the document.

      404

      Resource could not be found

      HTTP_Error

      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
      required

      The keyspace to run the operation against.

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

      String

      docid
      required

      The document ID to run the operation against.

      String

      attach
      required

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

      String
      Body Parameter
      Name Description Schema

      Body
      optional

      The attachment data

      Example: body_example

      String
      Header Parameters
      Name Description Schema

      Content-Type
      optional

      The content type of the attachment.

      Default: application/octet-stream

      String

      If-Match
      optional

      An alternative way of specifying the document revision ID.

      String
      Query Parameters
      Name Description Schema

      rev
      optional

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

      String
      Produces

      • application/json

      Consumes

      • Attachment content type

      Responses
      HTTP Code Description Schema

      201

      Attachment added to new or existing document successfully

      New_revision

      404

      Resource could not be found

      HTTP_Error

      409

      Resource already exists under that name

      HTTP_Error

      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
      Path Parameters
      Name Description Schema

      db
      required

      The name of the database to run the operation against.

      String
      Query Parameters
      Name Description Schema

      client
      optional

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

      Values: cbl2, sgr2
      Default: cbl2

      String
      Produces

      • application/json

      Responses
      HTTP Code Description Schema

      101

      Upgraded to a web socket connection

      404

      Resource could not be found

      HTTP_Error

      426

      Cannot upgrade connection to a web socket connection

      HTTP_Error

      Server

      Manage server activities

      Get server information

      GET /
      Description

      Returns information about the Sync Gateway node.

      Produces

      • application/json

      Responses
      HTTP Code Description Schema

      200

      Returned server information

      get___200_response

      Check if API is available

      GET /_ping
      Description

      Returns OK status if API is available.

      Produces

      • text/plain

      Responses
      HTTP Code Description Schema

      200

      Returned status

      String

      Check if server online

      HEAD /
      Description

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

      Responses
      HTTP Code Description Schema

      200

      Server is online

      Check if API is available

      HEAD /_ping
      Description

      Returns OK status if API is available.

      Responses
      HTTP Code Description Schema

      200

      Server is available

      Session

      Manage user sessions

      Log out

      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.

      Parameters
      Path Parameters
      Name Description Schema

      db
      required

      The name of the database to run the operation against.

      String
      Produces

      • application/json

      Responses
      HTTP Code Description Schema

      200

      Successfully removed session (logged out)

      400

      Bad Request

      404

      Resource could not be found

      HTTP_Error

      Get information about the current user

      GET /{db}/_session
      Description

      This will get the information about the current user.

      Parameters
      Path Parameters
      Name Description Schema

      db
      required

      The name of the database to run the operation against.

      String
      Produces

      • application/json

      Responses
      HTTP Code Description Schema

      200

      Properties associated with a user session

      User_Session_Information

      404

      Resource could not be found

      HTTP_Error

      /{db}/_session

      HEAD /{db}/_session
      Description
      Parameters
      Path Parameters
      Name Description Schema

      db
      required

      The name of the database to run the operation against.

      String
      Produces

      • application/json

      Responses
      HTTP Code Description Schema

      200

      OK

      404

      Resource could not be found

      HTTP_Error

      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
      required

      The name of the database to run the operation against.

      String
      Body Parameter
      Name Description Schema

      Body
      optional

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

      PostDbSessionRequest
      Produces

      • application/json

      Consumes

      • application/json

      Responses
      HTTP Code Description Schema

      200

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

      post_db__session_200_response

      400

      Origin is not in the approved list of allowed origins

      HTTP_Error

      404

      Resource could not be found

      HTTP_Error

      Unsupported

      Endpoints that are not supported by Sync Gateway

      Delete a design document | Unsupported

      DELETE /{db}/_design/{ddoc}
      Description

      This is unsupported

      Delete a design document.

      Parameters
      Path Parameters
      Name Description Schema

      db
      required

      The name of the database to run the operation against.

      String

      ddoc
      required

      The design document name.

      String
      Produces

      • application/json

      Responses
      HTTP Code Description Schema

      200

      Design document deleted successfully

      403

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

      404

      Resource could not be found

      HTTP_Error

      Get views of a design document | Unsupported

      GET /{db}/_design/{ddoc}
      Description

      This is unsupported

      Query a design document.

      Parameters
      Path Parameters
      Name Description Schema

      db
      required

      The name of the database to run the operation against.

      String

      ddoc
      required

      The design document name.

      String
      Produces

      • application/json

      Responses
      HTTP Code Description Schema

      200

      Successfully returned design document.

      get_db__design_ddoc_200_response

      403

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

      404

      Resource could not be found

      HTTP_Error

      Query a view on a design document | Unsupported

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

      This is unsupported

      Query a view on a design document.

      Parameters
      Path Parameters
      Name Description Schema

      db
      required

      The name of the database to run the operation against.

      String

      ddoc
      required

      The design document name.

      String

      view
      required

      The view to target.

      String
      Query Parameters
      Name Description Schema

      inclusive_end
      optional

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

      Boolean

      descending
      optional

      Return documents in descending order.

      Boolean

      include_docs
      optional

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

      Boolean

      reduce
      optional

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

      Boolean

      group
      optional

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

      Boolean

      skip
      optional

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

      Integer

      limit
      optional

      Return only the specified number of documents

      Integer

      group_level
      optional

      Specify the group level to be used.

      Integer

      startkey_docid
      optional

      Return documents starting with the specified document identifier.

      String

      endkey_docid
      optional

      Stop returning records when the specified document identifier is reached.

      String

      stale
      optional

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

      Values: ok, update_after

      String

      startkey
      optional

      Return records starting with the specified key.

      String

      endkey
      optional

      Stop returning records when this key is reached.

      String

      key
      optional

      Return only the document that matches the specified key.

      String

      keys
      optional

      An array of document ID strings to filter by.

      String List
      Produces

      • application/json

      Responses
      HTTP Code Description Schema

      200

      Returned view successfully

      get_db__design_ddoc__view_view_200_response

      403

      Forbidden

      404

      Resource could not be found

      HTTP_Error

      Check if view of design document exists | Unsupported

      HEAD /{db}/_design/{ddoc}
      Description

      This is unsupported

      Check if a design document can be queried.

      Parameters
      Path Parameters
      Name Description Schema

      db
      required

      The name of the database to run the operation against.

      String

      ddoc
      required

      The design document name.

      String
      Produces

      • application/json

      Responses
      HTTP Code Description Schema

      200

      Design document exists

      403

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

      404

      Resource could not be found

      HTTP_Error

      Update views of a design document | Unsupported

      PUT /{db}/_design/{ddoc}
      Description

      This is unsupported

      Update the views of a design document.

      Parameters
      Path Parameters
      Name Description Schema

      db
      required

      The name of the database to run the operation against.

      String

      ddoc
      required

      The design document name.

      String
      Body Parameter
      Name Description Schema

      Body
      optional

      GetDbDesignDdoc200Response
      Produces

      • application/json

      Consumes

      • application/json

      Responses
      HTTP Code Description Schema

      200

      Design document changes successfully

      403

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

      404

      Resource could not be found

      HTTP_Error

      Definitions

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

      ChangesFeed

      Name Description Schema

      results
      optional

      get_keyspace__changes_200_response_results_inner Set

      last_seq
      optional

      The last change sequence number.

      String

      DesignDoc

      Name Description Schema

      language
      optional

      String

      views
      optional

      get_db__design_ddoc_200_response_views_value Map

      options
      optional

      get_db__design_ddoc_200_response_options

      Document

      Name Description Schema

      _id
      optional

      The ID of the document.

      String

      _rev
      optional

      The revision of the document.

      String

      _exp
      optional

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

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

      String

      _deleted
      optional

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

      Boolean

      _revisions
      optional

      post_keyspace__request__revisions

      _attachments
      optional

      post_keyspace__request__attachments_value Map

      Get200Response

      Name Description Schema

      ADMIN
      optional

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

      Example: true

      Boolean

      couchdb
      required

      CouchDB welcome

      Example: Welcome

      String

      vendor
      required

      Product vendor

      get___200_response_vendor

      version
      optional

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

      Example: Couchbase Sync Gateway/3.1.0(1;a765231) EE

      String

      persistent_config
      optional

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

      Example: true

      Boolean

      Get200ResponseVendor

      Name Description Schema

      name
      required

      Product name

      Example: Couchbase Sync Gateway

      String

      version
      optional

      API version. Omitted if api.hide_product_version=true

      Example: 3.1

      String

      GetDb200Response

      Name Description Schema

      db_name
      optional

      Database name

      Example: db

      String

      update_seq
      optional

      The last sequence number that was committed to the database.

      Will return 0 if the database is offline.

      Example: 123456

      Integer

      committed_update_seq
      optional

      The last sequence number that was committed to the database.

      Will return 0 if the database is offline.

      Example: 123456

      Integer

      instance_start_time
      optional

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

      Example: 1644600082279583

      Integer

      compact_running
      optional

      Indicates whether database compaction is currently taking place or not.

      Boolean

      purge_seq
      optional

      Unused field.

      Default: 0

      BigDecimal

      disk_format_version
      optional

      Unused field.

      Default: 0

      BigDecimal

      state
      optional

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

      Values: Online, Offline

      String

      server_uuid
      optional

      Unique server identifier.

      Example: 995618a6a6cc9ac79731bd13240e19b5

      String

      GetDbDesignDdoc200Response

      Name Description Schema

      language
      optional

      String

      views
      optional

      get_db__design_ddoc_200_response_views_value Map

      options
      optional

      get_db__design_ddoc_200_response_options

      GetDbDesignDdoc200ResponseOptions

      Name Description Schema

      local_seq
      optional

      String

      include_design
      optional

      String

      raw
      optional

      String

      index_xattr_on_deleted_docs
      optional

      String

      GetDbDesignDdoc200ResponseViewsValue

      Name Description Schema

      map
      optional

      String

      reduce
      optional

      String

      GetDbDesignDdocViewView200Response

      Name Description Schema

      total_rows
      required

      Integer

      rows
      required

      get_db__design_ddoc__view_view_200_response_rows_inner List

      errors
      optional

      get_db__design_ddoc__view_view_200_response_errors_inner List

      GetDbDesignDdocViewView200ResponseErrorsInner

      Name Description Schema

      From
      optional

      String

      Reason
      optional

      String

      GetDbDesignDdocViewView200ResponseRowsInner

      Name Description Schema

      id
      optional

      String

      key
      optional

      Object

      value
      optional

      Object

      doc
      optional

      Object

      GetDbOidcTestingCerts200Response

      Name Description Schema

      keys
      required

      get_db__oidc_testing_certs_200_response_keys_inner List

      GetDbOidcTestingCerts200ResponseKeysInner

      Name Description Schema

      Key
      required

      Object

      KeyID
      required

      String

      Use
      required

      String

      Certificates
      optional

      Object List

      Algorithm
      optional

      String

      GetDbOidcTestingWellKnownOpenidConfiguration200Response

      Name Description Schema

      issuer
      optional

      String

      authorization_endpoint
      optional

      String

      token_endpoint
      optional

      String

      jwks_uri
      optional

      String

      userinfo_endpoint
      optional

      String

      id_token_signing_alg_values_supported
      optional

      String

      response_types_supported
      optional

      String

      subject_types_supported
      optional

      String

      scopes_supported
      optional

      String

      claims_supported
      optional

      String

      token_endpoint_auth_methods_supported
      optional

      String

      GetKeyspaceAllDocs200Response

      Name Description Schema

      rows
      required

      get_keyspace__all_docs_200_response_rows_inner Set

      total_rows
      required

      BigDecimal

      update_seq
      required

      BigDecimal

      GetKeyspaceAllDocs200ResponseRowsInner

      Name Description Schema

      key
      optional

      String

      id
      optional

      String

      value
      optional

      get_keyspace__all_docs_200_response_rows_inner_value

      GetKeyspaceAllDocs200ResponseRowsInnerValue

      Name Description Schema

      rev
      optional

      String

      GetKeyspaceChanges200Response

      Name Description Schema

      results
      optional

      get_keyspace__changes_200_response_results_inner Set

      last_seq
      optional

      The last change sequence number.

      String

      GetKeyspaceChanges200ResponseResultsInner

      Name Description Schema

      seq
      optional

      The change sequence number.

      BigDecimal

      id
      optional

      The document ID the change happened on.

      String

      changes
      optional

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

      get_keyspace__changes_200_response_results_inner_changes_inner Set

      GetKeyspaceChanges200ResponseResultsInnerChangesInner

      Name Description Schema

      rev
      optional

      The new revision that was caused by that change.

      String

      GetKeyspaceDocid200Response

      Name Description Schema

      _id
      optional

      The ID of the document.

      String

      _rev
      optional

      The revision ID of the document.

      String

      HTTP-Error

      Name Description Schema

      error
      required

      The error name.

      String

      reason
      required

      The error description.

      String

      New-revision

      Name Description Schema

      id
      required

      The ID of the document.

      String

      ok
      required

      Whether the request completed successfully.

      Boolean

      rev
      required

      The revision of the document.

      String

      NodeInfo

      Name Description Schema

      ADMIN
      optional

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

      Example: true

      Boolean

      couchdb
      required

      CouchDB welcome

      Example: Welcome

      String

      vendor
      required

      Product vendor

      get___200_response_vendor

      version
      optional

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

      Example: Couchbase Sync Gateway/3.1.0(1;a765231) EE

      String

      persistent_config
      optional

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

      Example: true

      Boolean

      OpenID Connect callback properties

      Name Description Schema

      id_token
      optional

      The OpenID Connect ID token

      String

      refresh_token
      optional

      The OpenID Connect ID refresh token

      String

      session_id
      optional

      The Sync Gateway session token

      String

      name
      optional

      The Sync Gateway user

      String

      access_token
      optional

      The OpenID Connect access token

      String

      token_type
      optional

      The OpenID Connect ID token type

      String

      expires_in
      optional

      The time until the id_token expires (TTL).

      BigDecimal

      OIDCLoginPageHandler

      Name Description Schema

      username
      required

      String

      tokenttl
      required

      String

      identity-token-formats
      required

      String

      authenticated
      required

      String

      OIDC-token

      Name Description Schema

      access_token
      optional

      String

      token_type
      optional

      String

      refresh_token
      optional

      String

      expires_in
      optional

      String

      id_token
      optional

      String

      OpenID Connect callback properties

      Name Description Schema

      id_token
      optional

      The OpenID Connect ID token

      String

      refresh_token
      optional

      The OpenID Connect ID refresh token

      String

      session_id
      optional

      The Sync Gateway session token

      String

      name
      optional

      The Sync Gateway user

      String

      access_token
      optional

      The OpenID Connect access token

      String

      token_type
      optional

      The OpenID Connect ID token type

      String

      expires_in
      optional

      The time until the id_token expires (TTL).

      BigDecimal

      PostDbEnsureFullCommit201Response

      Name Description Schema

      instance_start_time
      optional

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

      Example: 1644600082279583

      Integer

      ok
      optional

      Default: true
      Example: true

      Boolean

      PostDbFacebook401Response

      Name Description Schema

      error
      optional

      String

      reason
      optional

      String

      PostDbFacebookRequest

      Name Description Schema

      access_token
      required

      Facebook access token to base the new session on.

      String

      PostDbGoogleRequest

      Name Description Schema

      id_token
      required

      Google ID token to base the new session on.

      String

      PostDbOidcTestingAuthenticateRequest

      Name Description Schema

      username
      required

      String

      tokenttl
      required

      String

      identity-token-formats
      required

      String

      authenticated
      required

      String

      PostDbOidcTestingTokenRequest

      Name Description Schema

      grant_type
      required

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

      String

      code
      optional

      grant_type=authorization_code only: The OpenID Connect authentication token.

      String

      refresh_token
      optional

      grant_type=refresh_token only: The OpenID Connect refresh token.

      String

      PostDbSession200Response

      Name Description Schema

      authentication_handlers
      required

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

      Values:

      String List

      ok
      required

      Used for CouchDB compatability. Always true.

      Default: true

      Boolean

      userCtx
      required

      post_db__session_200_response_userCtx

      PostDbSession200ResponseUserCtx

      Name Description Schema

      channels
      required

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

      post_db__session_200_response_userCtx_channels_value Map

      name
      required

      The name of the user.

      String

      PostDbSession200ResponseUserCtxChannelsValue

      One of the following:

      • BigDecimal

      • String

      PostDbSessionRequest

      Name Description Schema

      name
      optional

      User name to generate the session for.

      String

      password
      optional

      Password of the user to generate the session for.

      String

      PostKeyspaceAllDocsRequest

      Name Description Schema

      keys
      required

      List of the documents to retrieve.

      String List

      PostKeyspaceBulkDocs201ResponseInner

      Name Description Schema

      id
      required

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

      String

      rev
      optional

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

      String

      error
      optional

      The error type if the operation of the document failed.

      String

      reason
      optional

      The reason the operation failed.

      String

      status
      optional

      The HTTP status code for why the operation failed.

      Integer

      PostKeyspaceBulkDocsRequest

      Name Description Schema

      new_edits
      optional

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

      Default: true

      Boolean

      docs
      required

      post_keyspace__request List

      PostKeyspaceBulkGetRequest

      Name Description Schema

      docs
      required

      post_keyspace__bulk_get_request_docs_inner List

      PostKeyspaceBulkGetRequestDocsInner

      Name Description Schema

      id
      required

      ID of the document to retrieve.

      String

      PostKeyspaceChangesRequest

      Name Description Schema

      limit
      optional

      Maximum number of changes to return.

      String

      style
      optional

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

      String

      active_only
      optional

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

      String

      include_docs
      optional

      Include the body associated with each document.

      String

      revocations
      optional

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

      String

      filter
      optional

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

      String

      channels
      optional

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

      String

      doc_ids
      optional

      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.

      String

      heartbeat
      optional

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

      String

      timeout
      optional

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

      String

      feed
      optional

      The type of changes feed to use.

      String

      PostKeyspaceRequest

      Name Description Schema

      _id
      optional

      The ID of the document.

      String

      _rev
      optional

      The revision of the document.

      String

      _exp
      optional

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

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

      String

      _deleted
      optional

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

      Boolean

      _revisions
      optional

      post_keyspace__request__revisions

      _attachments
      optional

      post_keyspace__request__attachments_value Map

      PostKeyspaceRequestAttachmentsValue

      Name Description Schema

      content_type
      optional

      Content type of the attachment.

      String

      data
      optional

      The data in the attachment in base64.

      String

      PostKeyspaceRequestRevisions

      Name Description Schema

      start
      optional

      Prefix number for the latest revision.

      BigDecimal

      ids
      optional

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

      String List

      PostKeyspaceRevsDiff200Response

      Name Description Schema

      docid
      optional

      The document ID.

      post_keyspace__revs_diff_200_response_docid

      PostKeyspaceRevsDiff200ResponseDocid

      Name Description Schema

      missing
      optional

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

      String List

      possible_ancestors
      optional

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

      String List

      PostKeyspaceRevsDiffRequest

      Name Description Schema

      docid
      optional

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

      String List

      PutKeyspaceLocalDocidRequest

      Name Description Schema

      _rev
      optional

      Revision to replace. Required if updating existing local document.

      String

      User Session Information

      Name Description Schema

      authentication_handlers
      optional

      The ways authentication can be established to authenticate as the user.

      String List

      ok
      optional

      Boolean

      userCtx
      optional

      User_Session_Information_userCtx

      UserSessionInformationUserCtx

      Name Description Schema

      channels
      optional

      A map of the channels the user has access to and the sequence number each channel was created at.

      The key is the channel name and the value is the sequence number.

      Object

      name
      optional

      The name of the user.

      String

      Related Content

      API Topics
      Reference
      Community

      Mobile Forum | Blog | Blog (Mobile) | Tutorials