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)

    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 resources section groups together the available API operations under functional categories.

    Attachment

    Work with attachments

    Get Specific Attachment

    GET /{db}/{doc}/{attachment}
    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.

    To remove an attachment from a document, simply update the _attachments dictionary of the document in the PUT /{db}/{id} request. From then on, the attachment will not be replicated but will still reside in the Couchbase Server bucket (see open ticket #1648).

    Parameters
    Type Name Description Schema

    Path

    attachment
    required

    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

    Path

    db
    required

    Database name

    string

    Path

    doc
    required

    Document ID

    string

    Query

    rev
    optional

    Revision identifier of the parent revision the new one should replace. (Not used when creating a new document.)

    string
    Responses
    HTTP Code Description Schema

    200

    The message body contains the attachment, in the format specified in the Content-Type header.

    string (binary)

    304

    Not Modified, the attachment wasn’t modified if ETag equals the If-None-Match header

    No Content

    404

    Not Found, the specified database, document or attachment was not found.

    No Content

    Create or Update Specific Attachment

    PUT /{db}/{doc}/{attachment}
    Description

    This request adds or updates the supplied request content as an attachment to the specified document, the maximum content size of an attachment is 20MB. The attachment name must be a URL-encoded string (the file name). You must also supply either the rev query parameter or the If-Match HTTP header for validation, and the Content-Type headers (to set the attachment content type).

    When uploading an attachment using an existing attachment name, the corresponding stored content of the database will be updated. Because you must supply the revision information to add an attachment to the document, this serves as validation to update the existing attachment.

    Uploading an attachment updates the corresponding document revision. Revisions are tracked for the parent document, not individual attachments.

    To remove an attachment from a document, simply update the _attachments dictionary of the document in the PUT /{db}/{id} request. From then on, the attachment will not be replicated but will still reside in the Couchbase Server bucket (see open ticket #1648).

    Parameters
    Type Name Description Schema

    Header

    Content-Type
    optional

    Attachment Content-Type

    string

    Path

    attachment
    required

    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

    Path

    db
    required

    Database name

    string

    Path

    doc
    required

    Document ID

    string

    Query

    rev
    optional

    Revision identifier of the parent revision the new one should replace. (Not used when creating a new document.)

    string

    Body

    body
    optional

    The request body

    string (binary)
    Responses
    HTTP Code Description Schema

    200

    Operation completed successfully

    Success

    409

    Conflict, the document revision wasn’t specified or it’s not the latest.

    No Content

    Authentication

    Work with authentication

    Get Facebook Authenticated Session

    POST /{db}/_facebook
    Description

    Sync Gateway allows users to authenticate using a Facebook account.

    Your application is responsible for generating a Facebook token; this generally needs to be done by running the Facebook login flow inside a web-view and capturing the generated token. This endpoint can be used to check the validity of the access token. To allow Facebook Login with Sync Gateway, it must be explicitly enabled in the Sync Gateway configuration file by setting the facebook.register property to true.

    Parameters
    Type Name Description Schema

    Path

    db
    required

    Database name

    string

    Body

    body
    optional

    Request body

    body

    body

    Name Description Schema

    access_token
    optional

    The access token for the user to authenticate

    string
    Responses
    HTTP Code Description Schema

    200

    Session successfully created. The Set-Cookie response header contains the session credentials.

    Session

    401

    Facebook verification server status <Facebook status code>

    No Content

    502

    Invalid response from Facebook verifier

    No Content

    Get Google Authenticated Session

    POST /{db}/_google
    Description

    Sync Gateway allows users to authenticate using a Google account.

    Your application is responsible for generating a Google token; this generally needs to be done by running the Google login flow inside a web-view and capturing the generated token. This endpoint can be used to check the validity of the access token. To allow Google Login with Sync Gateway, it must be explicitly enabled in the Sync Gateway configuration file by setting the google.register property to true and setting the google.app_client_id property with a Google app client ID.

    Parameters
    Type Name Description Schema

    Path

    db
    required

    Database name

    string

    Body

    body
    optional

    Request body

    body

    body

    Name Description Schema

    id_token
    optional

    The access token for the user to authenticate

    string
    Responses
    HTTP Code Description Schema

    200

    Session successfully created. The Set-Cookie response header contains the session credentials.

    Session

    401

    Returns the Google response’s ErrorDescription

    No Content

    502

    Invalid response from Google token verifier

    No Content

    OpenID Connect Authentication.

    GET /{db}/_oidc
    Description

    Called by clients to initiate the OIDC Authorization Code flow.

    Parameters
    Type Name Description Schema

    Path

    db
    required

    Database name

    string

    Query

    offline
    optional

    When true, requests a refresh token from the OP. Sets access_type=offline and prompt=consent on the redirect to the OP. Secure clients should set offline=true and persist the returned refresh token to secure storage.

    boolean

    Query

    provider
    optional

    OpenId Connect provider to be used for authentication, from the list of providers defined in the Sync Gateway Config. If not specified, will attempt to authenticate using the default provider.

    string
    Responses
    HTTP Code Description Schema

    302

    Redirect to the requested OpenID Connect provider for authentication. Redirect link is returned in the Location header.

    No Content

    400

    Bad request. Reason is returned as "OpenID Connect not configured for database default". If a provider was specified in the request, that provider was not defined in the Sync Gateway config. If no provider was specified, OpenID Connect is not configured in the Sync Gateway config.

    No Content

    500

    Server Error. Sync Gateway is unable to connect and validate the OpenID Connect provider requested.

    No Content

    Get OIDC Callback.

    GET /{db}/_oidc_callback
    Description

    Sync Gateway callback URL that clients are redirected to by the OpenID Connect provider.

    Parameters
    Type Name Description Schema

    Path

    db
    required

    Database name

    string

    Query

    code
    required

    OpenID Connect Authorization code.

    string

    Query

    provider
    optional

    OpenId Connect provider to be used for authentication, from the list of providers defined in the Sync Gateway Config. If not specified, will attempt to authenticate using the default provider.

    string
    Responses
    HTTP Code Description Schema

    200

    Successful OpenID Connect authentication.

    Response 200

    400

    Bad request.

    No Content

    401

    Authentication failed. Reason returned in the response body.

    No Content

    Response 200

    Name Description Schema

    access_token
    optional

    OpenID Connect access token

    string

    expires_in
    optional

    TTL for id_token

    number

    id_token
    optional

    OpenID Connect ID token

    string

    name
    optional

    Sync Gateway username

    string

    refresh_token
    optional

    OpenID Connect refresh token

    string

    session_id
    optional

    Sync Gateway session token

    string

    token_type
    optional

    OpenID Connect token type

    string

    Get OIDC Authentication.

    GET /{db}/_oidc_challenge
    Description

    Called by clients to initiate the OIDC Authorization Code flow.

    Parameters
    Type Name Description Schema

    Path

    db
    required

    Database name

    string

    Query

    offline
    optional

    When true, requests a refresh token from the OP. Sets access_type=offline and prompt=consent on the redirect to the OP. Secure clients should set offline=true and persist the returned refresh token to secure storage.

    boolean

    Query

    provider
    optional

    OpenId Connect provider to be used for authentication, from the list of providers defined in the Sync Gateway Config. If not specified, will attempt to authenticate using the default provider.

    string
    Responses
    HTTP Code Description Schema

    302

    Redirect to the requested OpenID Connect provider for authentication. Redirect link is returned in the Location header.

    No Content

    400

    Bad request. Reason is returned as "OpenID Connect not configured for database default". If a provider was specified in the request, that provider was not defined in the Sync Gateway config. If no provider was specified, OpenID Connect is not configured in the Sync Gateway config.

    No Content

    500

    Server Error. Sync Gateway is unable to connect and validate the OpenID Connect provider requested.

    No Content

    Get OIDC Refresh.

    GET /{db}/_oidc_refresh
    Description

    Used to obtain a new OpenID Connect ID token based on the provided refresh token.

    Parameters
    Type Name Description Schema

    Path

    db
    required

    Database name

    string

    Query

    provider
    optional

    OpenId Connect provider to be used for authentication, from the list of providers defined in the Sync Gateway Config. If not specified, will attempt to authenticate using the default provider.

    string

    Query

    refresh_token
    required

    OpenID Connect refresh token.

    string
    Responses
    HTTP Code Description Schema

    200

    Successful OpenID Connect authentication.

    Response 200

    400

    Bad request.

    No Content

    401

    Authentication failed. Unable to refresh token.

    No Content

    Response 200

    Name Description Schema

    access_token
    optional

    OpenID Connect access token

    string

    expires_in
    optional

    TTL for id_token

    number

    id_token
    optional

    OpenID Connect ID token

    string

    name
    optional

    Sync Gateway username

    string

    session_id
    optional

    Sync Gateway session token

    string

    token_type
    optional

    OpenID Connect token type

    string

    Database

    Work with databases

    Get Database Data

    GET /{db}/
    Description

    This request retrieves information about the database.

    Parameters
    Type Name Description Schema

    Path

    db
    required

    Database name

    string
    Responses
    HTTP Code Description Schema

    200

    Request completed successfully.

    Database

    401

    Unauthorized. Login required.

    No Content

    404

    Not Found. Requested database not found.

    No Content

    Get All Specified Documents

    POST /{db}/_all_docs
    Description

    This request retrieves specified documents from the database.

    Parameters
    Type Name Description Schema Default

    Path

    db
    required

    Database name

    string

    Query

    access
    optional

    Indicates whether to include in the response a list of what access this document grants (i.e. which users it allows to access which channels.) This option may only be used from the admin port.

    boolean

    "false"

    Query

    channels
    optional

    Indicates whether to include in the response a channels property containing an array of channels this document is assigned to. (Channels not accessible by the user making the request will not be listed.)

    boolean

    "false"

    Query

    include_docs
    optional

    Default is false. Indicates whether to include the associated document with each result. If there are conflicts, only the winning revision is returned.

    boolean

    "false"

    Query

    revs
    optional

    Default is false. Indicates whether to include a _revisions property for each document in the response, which contains a revision history of the document. The length of the returned revision tree can be specified with the revs_limit querystring parameter.

    boolean

    "false"

    Query

    update_seq
    optional

    Default is false. Indicates whether to include the update_seq (document sequence ID) property in the response.

    boolean

    "false"

    Body

    body
    optional

    Request body

    AllDocs
    Responses
    HTTP Code Description Schema

    200

    Query results

    QueryResult

    Get All Docs

    GET /{db}/_all_docs
    Description

    This request returns a built-in view of all the documents in the database.

    Parameters
    Type Name Description Schema Default

    Path

    db
    required

    Database name

    string

    Query

    access
    optional

    Indicates whether to include in the response a list of what access this document grants (i.e. which users it allows to access which channels.) This option may only be used from the admin port.

    boolean

    "false"

    Query

    channels
    optional

    Indicates whether to include in the response a channels property containing an array of channels this document is assigned to. (Channels not accessible by the user making the request will not be listed.)

    boolean

    "false"

    Query

    endkey
    optional

    If this parameter is provided, stop returning records when the specified key is reached.

    string

    Query

    include_docs
    optional

    Default is false. Indicates whether to include the associated document with each result. If there are conflicts, only the winning revision is returned.

    boolean

    "false"

    Query

    keys
    optional

    Specify a list of document IDs.

    < string > array

    Query

    limit
    optional

    Limits the number of result rows to the specified value. Using a value of 0 has the same effect as the value 1.

    integer

    Query

    revs
    optional

    Default is false. Indicates whether to include a _revisions property for each document in the response, which contains a revision history of the document. The length of the returned revision tree can be specified with the revs_limit querystring parameter.

    boolean

    "false"

    Query

    startkey
    optional

    Returns records starting with the specified key.

    string

    Query

    update_seq
    optional

    Default is false. Indicates whether to include the update_seq (document sequence ID) property in the response.

    boolean

    "false"
    Responses
    HTTP Code Description Schema

    200

    Query results

    QueryResult

    Create, Update or Delete Bulk docs

    POST /{db}/_bulk_docs
    Description

    This request enables you to add, update, or delete multiple documents to a database in a single request. To add new documents, you can either specify the ID (_id) or let the software create an ID. To update existing documents, you must provide the document ID, revision identifier (_rev), and new document values. To delete existing documents you must provide the document ID, revision identifier, and the deletion flag (_deleted).

    The JSON returned by the _bulk_docs operation consists of an array of JSON structures, one for each document in the original submission. The returned JSON structure should be examined to ensure that all of the documents submitted in the original request were successfully added to the database.

    Parameters
    Type Name Description Schema

    Path

    db
    required

    Database name

    string

    Body

    BulkDocsBody
    optional

    The request body

    BulkDocsBody

    BulkDocsBody

    Name Description Schema

    docs
    optional

    List containing new or updated documents. Each object in the array can contain the following properties _id, _rev, _deleted, and values for new and updated documents.

    < Document > array

    new_edits
    optional

    Indicates whether to assign new revision identifiers to new edits.
    Default : true

    boolean
    Responses
    HTTP Code Description Schema

    201

    Documents have been created or updated. The response object is an array with the status for each document submitted in the original request.

    < Response 201 > array

    409

    The operation failed with a forbidden error. Probably because the document already exists in the database but a revision number wasn’t specified.

    Forbidden

    Response 201

    Name Description Schema

    id
    optional

    Design document identifier

    string

    rev
    optional

    Revision identifier

    string

    Get Bulk Documents

    POST /{db}/_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. 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. Its first part will be the document’s JSON, and the subsequent parts will be the attachments (each identified by a Content-Disposition header giving its attachment name.)

    Parameters
    Type Name Description Schema Default

    Path

    db
    required

    Database name

    string

    Query

    attachments
    optional

    Default is false. Include attachment bodies in response.

    boolean

    "false"

    Query

    revs
    optional

    Default is false. Indicates whether to include a _revisions property for each document in the response, which contains a revision history of the document. The length of the returned revision tree can be specified with the revs_limit querystring parameter.

    boolean

    "false"

    Query

    revs_limit
    optional

    The number of revisions to include in the response from the document history. This parameter is only honoured if the revs=true querystring parameter is also sent in the request. If revs=true is specified and revs_limit isn’t, the full revision history is returned.

    integer

    Body

    BulkGetBody
    optional

    List of documents being requested. Each array element is an object that must contain an id property giving the document ID. It may contain a rev property if a specific revision is desired. It may contain an atts_since property (as in a single-document GET) to limit which attachments are sent.

    BulkGetBody

    BulkGetBody

    Name Schema

    docs
    optional

    < docs > array

    docs

    Name Description Schema

    id
    optional

    Document ID.

    string
    Responses
    HTTP Code Description Schema

    200

    Request completed successfully

    No Content

    301

    Request failed with a forbidden error. This usually happens because the user requesting that document doesn’t have access to it. Access to documents is granted to users through channels.

    Response 301

    Response 301

    Name Description Schema

    _id
    optional

    The document ID that was requested

    string

    _removed
    optional

    Default : true

    boolean

    _rev
    optional

    The revision number that was requested

    string
    Produces

    • multipart/mixed

    Example HTTP response
    Response 200
    {
  "multipart/mixed (document found)" : "--1cba224ff2aa106566e3ab65de9c861c24558ba368f8cd7f6fcde53b88f4\nContent-Type: application/json\n\n{\"_id\":\"doc123\",\"_rev\":\"1-c543d6514c609f65180f94af247aaffe\",\"hello\":\"world!\"}\n--1cba224ff2aa106566e3ab65de9c861c24558ba368f8cd7f6fcde53b88f4\n",
  "multipart/mixed (document not found)" : "--1cba224ff2aa106566e3ab65de9c861c24558ba368f8cd7f6fcde53b88f4\nContent-Type: application/json; error=\"true\"\n\n{\"error\":\"not_found\",\"id\":\"doc1234\",\"reason\":\"missing\",\"status\":404}\n--1cba224ff2aa106566e3ab65de9c861c24558ba368f8cd7f6fcde53b88f4\n"
}

    Get Changes Feed (body parameters)

    POST /{db}/_changes
    Description

    Same as the GET /_changes request except the parameters are in the JSON body.

    Parameters
    Type Name Description Schema

    Path

    db
    required

    Database name

    string

    Body

    ChangesBody
    optional

    The request body

    ChangesBody

    ChangesBody

    Name Description Schema

    active_only
    optional

    Default is false. When true, the changes response doesn’t include either deleted documents, or notification for documents that the user no longer has access to.
    Default : false

    boolean

    channels
    optional

    A comma-separated list of channel names. The response will be filtered to only documents in these channels. (This parameter must be used with the sync_gateway/bychannel filter parameter; see below.)

    string

    doc_ids
    optional

    A list of document IDs as a valid JSON array. The response will be filtered to only documents with these IDs. (This parameter must be used with the _doc_ids filter parameter; see below.)

    < string > array

    feed
    optional

    Default is 'normal'. Specifies type of change feed. Valid values are normal, continuous, longpoll, websocket.
    Default : "normal"

    string

    filter
    optional

    Indicates that the returned documents should be filtered. The valid values are sync_gateway/bychannel and _doc_ids.

    string

    heartbeat
    optional

    The heartbeat defines the interval (in milliseconds) at which an empty line (CRLF) is written to the response. It helps prevent Sync Gateway from deciding the socket is idle and closing it.

    The heartbeat value overrides any timeout value, to keep the feed alive indefinitely.

    Setting heartbeat=0 results in no heartbeat.

    Default: 0, which is no heartbeat

    Constraints:

    * Applies ONLY where feed=longpoll or feed=continuous

    * Minimum: 25000 (25 seconds)

    * Maximum: None – unless you define one in your configuration file using MaxHeartbeat

    integer

    include_docs
    optional

    Default is false. Indicates whether to include the associated document with each result. If there are conflicts, only the winning revision is returned.
    Default : false

    boolean

    limit
    optional

    Limits the number of result rows to the specified value. Using a value of 0 has the same effect as the value 1.

    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.

    object

    style
    optional

    Default is 'main_only'. Number of revisions to return in the changes array. The only possible value is all_docs and it returns all leaf revisions including conflicts and deleted former conflicts.
    Default : "main_only"

    string

    timeout
    optional

    The timeout value defines the maximum period (in milliseconds) to wait for a change, before sending a response. This wait applies even when there are no results.

    Setting timeout=0 results in no timeout.

    Default: 300000 (5 minutes/300 seconds)

    Constraints:

    * Applies ONLY where feed=longpoll or feed=continuous

    * Minimum: 0, no timeout

    * Maximum: 1500000 (15 minutes)

    integer
    Responses
    HTTP Code Description Schema

    200

    Request completed successfully

    Changes

    Get Changes Feed (query parameters)

    GET /{db}/_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’s 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
    Type Name Description Schema Default

    Path

    db
    required

    Database name

    string

    Query

    active_only
    optional

    Default is false. When true, the changes response doesn’t include either deleted documents, or notification for documents that the user no longer has access to.

    boolean

    "false"

    Query

    channels
    optional

    A comma-separated list of channel names. The response will be filtered to only documents in these channels. (This parameter must be used with the sync_gateway/bychannel filter parameter; see below.)

    string

    Query

    doc_ids
    optional

    A list of document IDs as a valid JSON array. The response will be filtered to only documents with these IDs. This parameter must be used with the filter=_doc_ids and feed=normal parameters.

    < string > array

    Query

    feed
    optional

    Default is 'normal'. Specifies type of change feed. Valid values are normal, continuous, longpoll, websocket.

    string

    "normal"

    Query

    filter
    optional

    Indicates that the reported documents should be filtered. The valid values are sync_gateway/bychannel and _doc_ids.

    string

    Query

    heartbeat
    optional

    The heartbeat defines the interval (in milliseconds) at which an empty line (CRLF) is written to the response. It helps prevent Sync Gateway from deciding the socket is idle and closing it.

    The heartbeat value overrides any timeout value, to keep the feed alive indefinitely.

    Setting heartbeat=0 results in no heartbeat.

    Default: 0, which is no heartbeat

    Constraints:

    * Applies ONLY where feed=longpoll or feed=continuous.

    * Minimum: 25000 (25 seconds)

    * Maximum: None – unless you define one in your configuration file using MaxHeartbeat

    integer

    0

    Query

    include_docs
    optional

    Default is false. Indicates whether to include the associated document with each result. If there are conflicts, only the winning revision is returned.

    boolean

    "false"

    Query

    limit
    optional

    Limits the number of result rows to the specified value. Using a value of 0 has the same effect as the value 1.

    integer

    Query

    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

    Query

    style
    optional

    Default is 'main_only'. Number of revisions to return in the changes array. main_only returns the current winning revision, all_docs returns all leaf revisions including conflicts and deleted former conflicts.

    string

    "main_only"

    Query

    timeout
    optional

    The timeout value defines the maximum period (in milliseconds) to wait for a change, before sending a response. This wait applies even when there are no results.

    Setting timeout=0 results in no timeout.

    Default: 300000 (5 minutes/300 seconds)

    Constraints:

    * Applies ONLY where feed=longpoll or feed=continuous.

    * Minimum: 0, no timeout

    * Maximum: 1500000 (15 minutes)

    integer

    300000
    Responses
    HTTP Code Description Schema

    200

    Request completed successfully

    Changes

    Get Revision ID Diff

    POST /{db}/_revs_diff
    Description

    Given a set of document/revision IDs, returns the subset of those that do not correspond to revisions stored in the database.

    Parameters
    Type Name Description Schema

    Path

    db
    required

    Database name

    string

    Body

    body
    optional

    Request body

    < string, < string > array > map
    Responses
    HTTP Code Description Schema

    200

    The request was successful

    < string, Response 200 > map

    Response 200

    Name Description Schema

    missing
    optional

    A list of revision IDs for that document (the ones that are not stored in the database).

    < string > array

    Document

    Work with documents

    Create New Document

    POST /{db}/
    Description

    This request creates a new document in the specified database.

    You can either specify the document ID by including the _id in the request message body (the value must be a string), or let the software generate an ID.

    The maximum size allowed for a document is 20MB.

    Parameters
    Type Name Description Schema

    Path

    db
    required

    Database name

    string

    Body

    body
    optional

    The document body

    object
    Responses
    HTTP Code Description Schema

    201

    The document was written successfully

    Success

    Get Specific Document

    GET /{db}/{doc}
    Description

    This request retrieves a document from a database.

    Parameters
    Type Name Description Schema Default

    Path

    db
    required

    Database name

    string

    Path

    doc
    required

    Document ID

    string

    Query

    attachments
    optional

    Default is false. Include attachment bodies in response.

    boolean

    "false"

    Query

    atts_since
    optional

    Include attachments only since specified revisions. Does not include attachments for specified revisions.

    < string > array

    Query

    open_revs
    optional

    Option to fetch specified revisions of the document. The value can be all to fetch all leaf revisions or an array of revision numbers (i.e. open_revs=["rev1", "rev2"]). Only leaf revision bodies that haven’t been pruned are guaranteed to be returned.

    If this option is specified the response will be in multipart format. Use the Accept: application/json request header to get the result as a JSON object.

    < string > array

    Query

    rev
    optional

    Revision identifier of the revision to get. By default, Sync Gateway returns the current revision. This parameter is generally only needed for conflict resolution. For example where the app might need to retrieve a conflicting leaf revision that isn’t the current revision.

    string

    Query

    revs
    optional

    Default is false. Indicates whether to include a _revisions property for each document in the response, which contains a revision history of the document. The length of the returned revision tree can be specified with the revs_limit querystring parameter.

    boolean

    "false"

    Query

    show_exp
    optional

    Whether to show the _exp property in the response.

    boolean

    "false"
    Responses
    HTTP Code Description Schema

    200

    The message body contains the following objects in a JSON document.

    object

    Create or Update Specific Document

    PUT /{db}/{doc}
    Description

    This request creates a new document or creates a new revision of an existing document. It enables you to specify the identifier for a new document rather than letting the software create an identifier.

    If you want to create a new document and let the software create an identifier, use the POST /db request.

    If the document specified by doc does not exist, a new document is created and assigned the identifier specified in doc. If the document already exists, the document is updated with the JSON document in the message body and given a new revision. The maximum size allowed for a document is 20MB.

    Since Sync Gateway 1.3, an expiry property (_exp) can also be specified to purge the document after a given time. If convergence is enabled (introduced in Sync Gateway 1.5), the behavior of the expiry feature changes in the following way: when the expiry value is reached, instead of getting purged, the active revision of the document is tombstoned. If there is another non-tombstoned revision for this document (i.e a conflict) it will become the active revision. The tombstoned revision will be purged when the server’s metadata purge interval is reached.

    Parameters
    Type Name Description Schema Default

    Path

    db
    required

    Database name

    string

    Path

    doc
    required

    Document ID

    string

    Query

    new_edits
    optional

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

    boolean

    "true"

    Query

    rev
    required

    Revision identifier of the revision to update. It must be the last revision in the history.

    string

    Body

    Document
    optional

    Request body

    Document
    Responses
    HTTP Code Description Schema

    200

    The response is a JSON document that contains the following objects

    Success

    Delete Specific Document

    DELETE /{db}/{doc}
    Description

    This request deletes a document from the database.

    When a document is deleted, the revision number is updated so the database can track the deletion in synchronized copies.

    Parameters
    Type Name Description Schema

    Path

    db
    required

    Database name

    string

    Path

    doc
    required

    Document ID

    string

    Query

    rev
    required

    Revision identifier of the revision to delete. It must be the identifier of the latest revision in the history.

    string
    Responses
    HTTP Code Description Schema

    200

    Document successfully removed

    Success

    Document (local)

    Work with local documents

    Get Specific Local Document

    GET /{db}/_local/{local_doc}
    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 local documents mostly used by Couchbase Lite’s replicator, as a place to store replication checkpoint data.

    Parameters
    Type Name Description Schema

    Path

    db
    required

    Database name

    string

    Path

    local_doc
    required

    Local document IDs begin with _local/.

    string
    Responses
    HTTP Code Description Schema

    200

    The message body contains the following objects in a JSON document.

    Success

    Create or Update a Local Document

    PUT /{db}/_local/{local_doc}
    Description

    This request creates or updates 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 the client’s replicator, as a place to store replication checkpoint data.

    Parameters
    Type Name Description Schema

    Path

    db
    required

    Database name

    string

    Path

    local_doc
    required

    Local document IDs begin with _local/.

    string
    Responses
    HTTP Code Description Schema

    201

    Created

    Success

    Delete Specific Local Document

    DELETE /{db}/_local/{local_doc}
    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
    Type Name Description Schema

    Path

    db
    required

    Database name

    string

    Path

    local_doc
    required

    Local document IDs begin with _local/.

    string

    Query

    batch
    optional

    Stores the document in batch mode. To use, set the value to ok.

    string

    Query

    rev
    optional

    Revision identifier of the parent revision the new one should replace. (Not used when creating a new document.)

    string
    Responses
    HTTP Code Description Schema

    200

    Document successfully removed

    Success

    Server

    Work with the server

    Get Server Data

    GET /
    Description

    Returns meta-information about the server.

    Responses
    HTTP Code Description Schema

    200

    Meta-information about the server.

    ServerData_model

    Session

    Work with sessions

    Create User Session

    POST /{db}/_session
    Description

    If the credentials provided in the request body are valid, the session is created with an idle session timeout of 24 hours.

    An idle session timeout in the context of Sync Gateway is defined as the following: if 10% or more of the current expiration time has elapsed when a subsequent request with that session id is processed, the session’s expiry time is automatically updated to 24 hours from that time.

    Parameters
    Type Name Description Schema

    Path

    db
    required

    Database name

    string

    Body

    SessionBody
    optional

    The message body is a JSON document that contains the following objects.

    SessionBody

    SessionBody

    Name Description Schema

    name
    optional

    Username of the user the session will be associated to.

    string

    password
    optional

    User password.

    string
    Responses
    HTTP Code Description Schema

    200

    Session successfully created. The Set-Cookie response header contains the session credentials.

    Session

    Delete User Session

    DELETE /{db}/_session
    Description

    This request deletes the session that currently authenticates the requests.

    Parameters
    Type Name Description Schema

    Header

    cookie
    optional

    The cookie of the logged-in session.

    string

    Path

    db
    required

    Database name

    string
    Responses
    HTTP Code Description Schema

    200

    The session was successfully removed.

    No Content

    Definitions

    DocumentResponse

    Name Description Schema

    _id
    optional

    Document identifier

    string

    _rev
    optional

    Revision identifier

    string

    Error

    Name Schema

    code
    optional

    integer (int32)

    fields
    optional

    string

    message
    optional

    string

    ExpVars

    Name Description Schema

    cb
    optional

    Variables reported by the Couchbase SDK (go_couchbase package)

    object

    cmdline
    optional

    Built-in variables from the Go runtime, lists the command-line arguments

    object

    mc
    optional

    Variables reported by the low-level memcached API (gomemcached package)

    object

    memstats
    optional

    Dumps a large amount of information about the memory heap and garbage collector

    object

    syncGateway_changeCache
    optional

    syncGateway_changeCache

    syncGateway_db
    optional

    syncGateway_db

    syncGateway_changeCache

    Name Description Schema

    lag-queue-0000ms
    optional

    Histogram of delay from Tap feed till doc is posted to changes feed

    object

    lag-tap-0000ms
    optional

    Histogram of delay from doc save till it shows up in Tap feed

    object

    lag-total-0000ms
    optional

    Histogram of total delay from doc save till posted to changes feed

    object

    maxPending
    optional

    Max number of sequences waiting on a missing earlier sequence number

    object

    outOfOrder
    optional

    Number of out-of-order sequences posted

    object

    view_queries
    optional

    Number of queries to channels view

    object

    syncGateway_db

    Name Description Schema

    channelChangesFeeds
    optional

    Number of calls to db.changesFeed, i.e. generating a changes feed for a single channel.

    object

    channelLogAdds
    optional

    Number of entries added to channel logs

    object

    channelLogAppends
    optional

    Number of times entries were written to channel logs using an APPEND operation

    object

    channelLogCacheHits
    optional

    Number of requests for channel-logs that were fulfilled from the in-memory cache

    object

    channelLogRewriteCollisions
    optional

    Number of collisions while attempting to rewrite channel logs using SET

    object

    channelLogRewrites
    optional

    Number of times entries were written to channel logs using a SET operation (rewriting the entire log)

    object

    document_gets
    optional

    Number of times a document was read from the database

    object

    revisionCache_adds
    optional

    Number of revisions added to the revision cache

    object

    revisionCache_hits
    optional

    Number of times a revision-cache lookup succeeded

    object

    revisionCache_misses
    optional

    Number of times a revision-cache lookup failed

    object

    revs_added
    optional

    Number of revisions added to the database (including deletions)

    object

    sequence_gets
    optional

    Number of times the database’s lastSequence was read

    object

    sequence_reserves
    optional

    Number of times the database’s lastSequence was incremented

    object

    Forbidden

    Name Description Schema

    error
    optional

    Default : "conflict"

    string

    id
    optional

    string

    reason
    optional

    string

    status
    optional

    integer

    LogTags

    Name Description Schema

    Access
    optional

    access() calls made by the sync function

    boolean

    Attach
    optional

    Attachment processing

    boolean

    Auth
    optional

    Authentication

    boolean

    Bucket
    optional

    Sync Gateway interactions with the bucket (verbose logging).

    boolean

    CRUD
    optional

    Updates made by Sync Gateway to documents (CRUD+ for verbose logging)

    boolean

    Cache
    optional

    Interactions with Sync Gateway’s in-memory channel cache (Cache+ for verbose logging)

    boolean

    Changes
    optional

    Processing of _changes requests (Changes+ for verbose logging)

    boolean

    DCP
    optional

    DCP-feed processing (verbose logging)

    boolean

    Events
    optional

    Event processing (webhooks) (Events+ for verbose logging)

    boolean

    Feed
    optional

    Server-feed processing (Feed+ for verbose logging)

    boolean

    HTTP
    optional

    All requests made to the Sync Gateway REST APIs (Sync and Admin). Note that the log keyword HTTP is always enabled, which means that HTTP requests and error responses are always logged (in a non-verbose manner). HTTP+ provides more verbose HTTP logging.

    boolean

    PurgeBody

    Document ID

    Name Description Schema

    a_doc_id
    optional

    Only possible value is ["*"]. It permanently removes all revisions for that document ID.

    < enum (*) > array

    Success

    Name Description Schema

    id
    optional

    Design document identifier

    string

    ok
    optional

    Indicates whether the operation was successful

    boolean

    rev
    optional

    Revision identifier

    string

    User

    Name Description Schema

    admin_channels
    optional

    Array of channel names to give the user access to

    < string > array

    admin_roles
    optional

    Array of role names to assign to this user

    < string > array

    all_channels
    optional

    Array of channel names the user is given access to

    < string > array

    disabled
    optional

    Boolean property to disable this user. The user will not be able to login if this property is set to true.

    boolean

    email
    optional

    Email of the user that will be created.

    string

    name
    optional

    Name of the user that will be created

    string

    password
    optional

    Password of the user that will be created. Required, unless the allow_empty_password Sync Gateway per-database configuration value is set to true, in which case the password can be omitted.

    string

    roles
    optional

    Array of role names the user is given access to

    < string > array

    ChangesFeedRow

    Name Description Schema

    changes
    optional

    List of the document’s leafs. Each leaf object contains one field, rev.

    < changes > array

    deleted
    optional

    Indicate whether the row is deleted
    Default : false

    boolean

    doc
    optional

    object

    id
    optional

    Document identifier

    string

    seq
    optional

    Update sequence number

    integer

    changes

    Name Description Schema

    rev
    optional

    Identifier of the document revision that changed.

    string

    View

    Name Description Schema

    _rev
    optional

    Revision identifier of the parent revision the new one should replace. (Not used when creating a new document.)

    string

    views
    optional

    List of views to save on this design document.

    views

    views

    Name Description Schema

    my_view_name
    optional

    The view’s map/reduce functions.

    my_view_name

    my_view_name

    Name Description Schema

    map
    optional

    Inline JavaScript definition for the map function

    string

    reduce
    optional

    Inline JavaScript definition for the reduce function

    string

    QueryRow

    Name Description Schema

    doc
    optional

    The document body. This is only returned if include_docs=true is specified in the URL.

    object

    id
    optional

    The ID of the document.

    string

    key
    optional

    The key in the output row.

    object

    value
    optional

    The value in the output row.

    object

    Design

    Name Description Schema

    count
    optional

    Total number of items available.

    integer (int32)

    limit
    optional

    Number of items to retrieve (100 max).

    integer (int32)

    offset
    optional

    Position in pagination.

    integer (int32)

    AllDocs

    Name Description Schema

    keys
    optional

    List of identifiers of the documents to retrieve

    < string > array

    Changes

    Name Description Schema

    last_seq
    optional

    Last change sequence number

    object

    results
    optional

    List of changes to the database. See the following table for a list of fields in this object.

    < ChangesFeedRow > array

    Database

    Name Description Schema

    db_name
    optional

    Name of the database

    string

    db_uuid
    optional

    Database identifier

    integer

    disk_format_version
    optional

    Database schema version

    integer

    disk_size
    optional

    Total amount of data stored on the disk (in bytes)

    integer

    instance_start_time
    optional

    Date and time the database was opened (in microseconds since 1 January 1970)

    string

    state
    optional

    The state of the specified database. Possible values are 'Online' and 'Offline'. A database can be taken offline and brought back online using the /{db}/_offline and /{db}/_online endpoints on the Admin REST API.

    string

    update_seq
    optional

    Number of updates to the database

    string

    Document

    Name Description Schema

    _attachments
    optional

    _attachments

    _exp
    optional

    Expiry time after which the document will be purged. The expiration time is set and managed on the Couchbase Server document (TTL is not supported for databases in walrus mode). The value can be specified in two ways; in ISO-8601 format, for example the 6th of July 2016 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 querystring.

    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

    _id
    optional

    The document ID.

    string

    _rev
    optional

    Revision identifier of the parent revision the new one should replace. (Not used when creating a new document.)

    string

    _revisions
    optional

    _revisions

    _attachments

    Name Schema

    attachment_name
    optional

    attachment_name

    attachment_name

    Name Description Schema

    content_type
    optional

    The content type of the attachment.

    string

    _revisions

    Name Description Schema

    ids
    optional

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

    < string > array

    start
    optional

    Prefix number for the latest revision.

    integer

    QueryResult

    Name Description Schema

    offset
    optional

    Starting index of the returned rows.

    string

    rows
    optional

    < QueryRow > array

    total_rows
    optional

    Number of documents in the database. This number is not the number of rows returned.

    integer

    Replication

    Name Description Schema

    ok
    optional

    Indicates whether the replication operation was successful

    boolean

    session_id
    optional

    Session identifier

    string

    ServerData_model

    Name Description Schema

    couchdb
    optional

    Contains the string 'Welcome' (this is required for compatibility with CouchDB)

    string

    vendor/name
    optional

    The server type ('Couchbase Sync Gateway)

    string

    vendor/version
    optional

    The server version

    string

    version
    optional

    Sync Gateway version number

    string

    Session

    Name Description Schema

    authentication_handlers
    optional

    List of authentication methods.

    < string > array

    ok
    optional

    Always true if the operation was successful.

    boolean

    userCtx
    optional

    UserContext

    UserContext

    Context for this user.

    Name Description Schema

    channels
    optional

    Key-value pairs with a channel name as the key and the sequence number that granted the user access to the channel as value. ! is the public channel and every user has access to it.

    object

    name
    optional

    The user’s name.

    string

    Related Content

    API Topics
    Reference
    Community

    Mobile Forum | Blog | Blog (Mobile) | Tutorials