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.

A newer version of this documentation is available.

View Latest

Public REST API (Static Page)

    March 23, 2025
    + 12

    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.

    Boolean

    revocations
    optional

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

    Boolean

    filter
    optional

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

    Values: sync_gateway/bychannel, _doc_ids

    String

    channels
    optional

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

    String

    doc_ids
    optional

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

    String 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 database 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.

    Boolean

    channels
    optional

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

    Boolean

    access
    optional

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

    Boolean

    revs
    optional

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

    Boolean

    update_seq
    optional

    Include the document sequence number update_seq property for each document.

    Boolean

    keys
    optional

    An array of document ID strings to filter by.

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

    Boolean

    channels
    optional

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

    Boolean

    access
    optional

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

    Boolean

    revs
    optional

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

    Boolean

    update_seq
    optional

    Include the document sequence number update_seq property for each document.

    Boolean

    keys
    optional

    An array of document ID strings to filter by.

    String 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

    Returns all documents in the database 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
    Body Parameter
    Name Description Schema

    Body
    optional

    PostKeyspaceAllDocsRequest
    Query Parameters
    Name Description Schema

    include_docs
    optional

    Include the body associated with each document.

    Boolean

    channels
    optional

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

    Boolean

    access
    optional

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

    Boolean

    revs
    optional

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

    Boolean

    update_seq
    optional

    Include the document sequence number update_seq property for each document.

    Boolean

    startkey
    optional

    Return records starting with the specified key.

    String

    endkey
    optional

    Stop returning records when this key is reached.

    String

    limit
    optional

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

    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.

    Boolean

    revs_limit
    optional

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

    Integer
    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 expiry values are specified as Unix time, and if the desired TTL is below 30 days then it can also represent an interval in seconds from the current time (for example, a value of 5 will remove the document 5 seconds after it is written to Couchbase Server). The document expiration time is returned in the response of GET /{db}/{doc} ` when `show_exp=true is included in the query.

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

    String

    _deleted
    optional

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

    Boolean

    _revisions
    optional

    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.

    Boolean

    revocations
    optional

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

    String

    filter
    optional

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

    String

    channels
    optional

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

    String

    doc_ids
    optional

    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 expiry values are specified as Unix time, and if the desired TTL is below 30 days then it can also represent an interval in seconds from the current time (for example, a value of 5 will remove the document 5 seconds after it is written to Couchbase Server). The document expiration time is returned in the response of GET /{db}/{doc} ` when `show_exp=true is included in the query.

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

    String

    _deleted
    optional

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

    Boolean

    _revisions
    optional

    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