API v1.x

You are currently looking at the documentation of a previous version of Kuzzle. We strongly recommend that you use the latest version. You can also use the version selector in the top menu.

subscribe #

Subscribes by providing a set of filters: messages, document changes and, optionally, user events matching the provided filters will generate real-time notifications, sent to you in real-time by Kuzzle.

Query Syntax #


Due to the synchronous nature of the HTTP protocol, real-time notifications are not supported.

Other protocols #

Copied to clipboard!
  "index": "<index>",
  "collection": "<collection>",
  "controller": "realtime",
  "action": "subscribe",
  "body": {
    // subscription filters
  "volatile": {
    // query volatile data
  "scope": "<all|in|out|none>",
  "state": "<all|pending|done>",
  "users": "<all|in|out|none>"

Arguments #

  • collection: watched collection
  • index: watched index

Optional: #

  • scope: accepted values: all, in, out, none (default: all). Subscribe to either new documents entering the scope of the subscription filters (in), to documents leaving it (out), or both (all). Alternatively, document notifications can be ignored entirely (none)
  • state
    Deprecated since 1.5.0
    : accepted values: all, pending, done (default: done). Subscribe to either changes that are about to occur (pending), to changes having occured (done), or both (all). In the latter case, each document change will generate 2 real-time notifications
  • users: accepted values: all, in, out, none (default: none). Receive real-time notifications about users subscribing to the same filters (in), about users leaving the subscription (out), or both (all). If set to none, no notifications are sent about users
  • volatile: subscription information, used in user join/leave notifications

Body properties #

Subscription filters, following the Koncorde syntax

An empty filter subscribes to any change occuring on the selected index-collection pair.

Response #

Returns an object detailing the new subscription properties:

  • channel: unique channel identifier. A channel acts as a subscription configuration ID, allowing multiple subscriptions to occur with the same filters, but different notification options.
  • roomId: unique subscription identifier.

Notifications include the room property, which indicates to what channel the notification is for. This is how notifications can be linked to subscriptions by front-end applications (our SDK perform these operations automatically).

Example #

Copied to clipboard!
  "status": 200,
  "error": null,
  "index": "<index>",
  "collection": "<collection>",
  "controller": "realtime",
  "action": "subscribe",
  "requestId": "<unique request identifier>",
  "result": {
    "roomId": "<unique Kuzzle room identifier>",
    "channel": "<unique channel identifier>"