NAV

Introduction

Welcome to the Kuzzle API Documentation!

Connecting to Kuzzle

The connection to Kuzzle depends on the protocol to be used.

HTTP, WebSocket and SocketIO protocols are shipped in Kuzzle’s core. Other protocols can be added with Protocol Plugins.

HTTP

 $ curl "http://localhost:7512/"

By default, Kuzzle exposes itself on the 7512 port. Assuming the Kuzzle server runs locally, it can be reached on http://localhost:7512/.

The default response is the ServerInfo controller. With this you will get detailed information about available HTTP API routes.

WebSocket

Websocket

<script>
    var socket = new WebSocket("ws://localhost:7512");
</script>

By default, Kuzzle enables the core websockets protocol, accepting websocket requests via the http server (on port 7512 by default).

Socket.io (WebSocket-like)

Socket.io

<script src="https://cdn.socket.io/socket.io-1.4.5.js"></script>
<script>
    var socket = io("http://localhost:7512");
</script>

To ensure compatibility with older web browsers, our official docker images embeds the Kuzzle embeds a socketio protocol, accepting socket requests via the http server (on port 7512 by default).

MQTT protocols

Kuzzle provides a plugin protocol that supports the MQTT protocol. This plugin protocol is a 2-way means of communication between your application and Kuzzle, forwarding your queries forth to Kuzzle, and notifications/responses from Kuzzle back to your application.

Examples

MQTT

# shell 1
node_modules/.bin/mqtt subscribe -v -h rabbit -t Kuzzle

# shell 2
node_modules/.bin/mqtt publish -h rabbit -t Kuzzle -m '{
  "collection":"index",
  "collection":"collection",
  "controller": "document",
  "action": "createOrReplace",
  "body": {
    "firstName": "John",
    "lastName": "Doe"
  }
}'

# shell 1 (prettified)
Kuzzle {
  "error": null,
  "result": {
    "_id": "AVF8NG3k5ZVpUuiPrN1K",
    "_index": "index",
    "_source": {"firstName":"John", "lastName":"Doe"},
    "_type": "collection",
    "_version": 1,
    "action": "createOrReplace",
    "collection": "collection",
    "controller": "document",
    "created": true,
    "metadata": {},
    "requestId":"5cb4d930-62f4-4393-afc1-9a71e284a214"
  },
  "status": 200
}

By default, the MQTT plugin protocol listens on the port 1883.

Query syntax

The query message format is (almost) identical between all the protocols.

The only exceptions are about the specific nature of HTTP protocol, where the URL represents the action.

Please refer to the code samples on the right pane for more detail on the specific implementations.

Common attributes

URL: http://kuzzle:7512/<action route>[route options] Method: get|post|put|delete Body: Can be empty (usually with get and delete methods) or a JSON object of the resource body (usually with post and put methods).

Websocket: The Websocket layer listens to a specific socket room in order to forward your queries to the right Kuzzle controller. Room name: kuzzle Query body syntax (JSON data):

MQTT: The MQTT layer listens to a specific topic in order to forward your queries to the right Kuzzle controller. Topic name: kuzzle Query body syntax (JSON data):

{
  // Optional: Unique request Identifier
  "requestId": "<unique request identifier>",

  // Required: Controller and Action to call:
  "controller": "<controller>",
  "action": "<action>",

  // Index on which the action is handled (empty for actions that do not manage a unique index)
  "index": "<index>",

  // Collection on which the action is handled (empty for actions that do not manage a unique collection)
  "collection": "<collection>",

  // A set of filters matching documents you want to listen to
  "body": {..}
}

controller

mandatory

The controller attribute specifies the type of action to perform. The current implementation of Kuzzle embeds nine controllers: auth, bulk, collection, document, index, memoryStorage, realtime, security and server.

action

mandatory

The action attribute indicates to Kuzzle which action to perform for the controller.

For instance, using the document controller, we can perform a get action or a search.

index

required depending on the controller/action

Kuzzle attaches its collections to a index. Any action impacting a document, a collection or an index itself will need this attribute fed.

collection

required depending on the controller/action

Kuzzle attaches its documents to a collection. Any action impacting a document or a collection itself will need this attribute fed.

body

mandatory

The body field contains the body of the resource sent to Kuzzle.

For instance, the body attribute will contain the filters on which to listen to during a real-time subscription or the content of the document to create/publish.

requestId

optional

Kuzzle will create a unique ID if you don’t provide one, but if you want to easily identify which query generated the response you got, the best way is to provide it yourself in the request.

Authorization token

 $ curl -H "Authorization: Bearer <encrypted_jwt_token>" "http://localhost:7512/..."
{
  // Optional: Unique request Identifier
  "requestId": "<unique request identifier>",
  "controller": "<controller>",
  "action": "<action>",
  "collection": "<collection>",

  // Request headers:
  "jwt": "<encrypted_jwt_token>"

  "body": {..}
}

Kuzzle uses JSON Web Tokens send within request headers to authenticate users. The token himself is generated by the Auth controller login action and must be included with each request.

Kuzzle response

{
  // Integer containing the status code (HTTP-like: 200 if OK, 4xx or 5xx in case of error)
  "status": 200,

  // Complex object containing error information, if something went wrong (null if OK)
  "error": {...},

  // Some information about the initial request
  "index": "<index>",
  "collection": "<collection>",
  "controller": "<controller>",
  "action": "<action>",

  // For notification only, completion state of the request.
  // A pending request will receive a "done" notification once it is processed by Kuzzle.
  "state": "<done|pending>",

  // For notifications only, indicates if the document is added or removed from the subscription.
  "scope": "<in|out>",

  // Arbitrary data repeated from the initial request (optional).
  "metadata": { foo: "bar" },

  // Your query unique identifier.
  "requestId": "<unique request identifier>",

  // Complex object, depending on your query
  "result": {
    ...
  }
}

A response is the result of a query you send to Kuzzle. It may be the results of a search query, an acknowledgement of a created action, and so on. When you subscribe to a room, Kuzzle also sends a notification to your application in the form of a response object.

A response is a JSON object as shown in the sample pane.

NB: For more details about status code and error object, see status-codes.md

Sending metadata

In every request you send to Kuzzle, you can include a metadata object. This object content will be ignored by Kuzzle, but it will also be forwarded back in responses and in notifications (see below).

You can also include metadata information to a subscription request. These metadata information will be forwarded to other subscribers at the moment of the subscription, and when you leave the room. Please note that when leaving the room, the forwarded metadata are those provided in the subscription request.

This feature is especially useful to include volatile information about the performed request.

Updating a document

Query

{
  "index": "<index>",
  "collection": "<collection>",
  "controller": "document",
  "action": "update",
  "_id": "<documentId>",
  "body": {
    "somefield": "now has a new value"
  },
  "metadata": {
    "modifiedBy": "awesome me",
    "reason": "it needed to be modified"
  }
}

The following update notification will be sent to all subscribers:

{
  "status": 200,
  "error": null,
  "index": "<index>",
  "collection": "<collection>",
  "controller": "document",
  "action": "update",
  "state": "pending",
  "scope": "<in|out>",
  "metadata": {
    "modifiedBy": "awesome me",
    "reason": "it needed to be modified"
  },
  "requestId": "<unique request identifier>",
  "result": {
    "_id": "a document ID",
    "_source": {
      "somefield": "now has a new value",
      "someOtherField": "was left unchanged"
    },
  }
}

Subscribe to a room

Query

{
  "index": "<index>",
  "collection": "<collection>",
  "controller": "realtime",
  "action": "subscribe",
  "body": {
    // subscription filters
  },
  "metadata": {
    "hello": "my name is Bob"
  }
}

And then, if you leave the room, the other subscribers will receive the following notification:

{
  "status": 200,
  "error": null,
  "index": "<index>",
  "collection": "<collection>",
  "controller": "realtime",
  "action": "unsubscribe",
  "state": "done",
  "scope": "out",
  "metadata": {
    "hello": "my name is Bob"
  },
  "requestId": "<unique request identifier>",
  "result": {
    "roomId": "<unique Kuzzle room identifier>",
    "count": <the new user count on that room>
  }
}

Notifications

Websocket

// For browsers not supporting websocket, use socket.io instead
<script>
  var
    socket = new WebSocket("ws://localhost:7512"),
    channel;

  socket.onmessage = function (payload) {
    var response = JSON.parse(payload.data);

    /*
     step 1 - we get the created channel name, as notifications will be sent
        with "room = channelName"
     */
    if (response.room === "mySubscription") {
      // we now have a channel to listen to
      channel = response.result.channel;
    }

    if (response.room === channel) {
      console.log("Received a notification: ", response);

      /*
      {
        "status": 200,
        "error": null,
        "index": "index",
        "collection":"collection",
        "controller": "realtime",
        "action": "publish",
        "state": "done",
        "scope": "in",
        "requestId": "<unique request identifier>",
        "result": {
          ...                      // the published document
        }
      }
      */
    }
  };

  // step 2 - we subscribe to our documents
  socket.onopen = function () {
    socket.send(JSON.stringify({
      "requestId": "mySubscription",
      "index": "index",
      "collection": "collection",
      "controller": "realtime",
      "action": "subscribe",
      "body": {}
    }));

    // step 3 - when publishing a message, we get some notifications back
    socket.send(JSON.stringify({
      "index": "index",
      "collection": "collection",
      "controller": "realtime",
      "action": "publish",
      "body": {
        "foo": "bar"
      }
    }));
  };
</script>

Socket.io

<script src="https://cdn.socket.io/socket.io-1.4.5.js"></script>
<script>
  var socket = io("http://localhost:7512");

  // step 1 - we prepare ourself to receive Kuzzle's subscription response and then listen to the created channel.
  socket.once("mySubscription", function (response) {
    // we now have a channel to listen to
    socket.on(response.result.channel, function (notification) {
      console.log(notification);

      /*
      {
        "status": 200,
        "error": null,
        "index": "index",
        "collection":"collection",
        "controller": "realtime",
        "action": "publish",
        "state": "done",
        "scope": "in",
        "requestId": "<unique request identifier>",
        "result": {
          ...                      // the published document
        }
      }
      */
    });
  });

  // step 2 - we subscribe to our documents
  socket.emit("kuzzle", {
    "requestId": "mySubscription",
    "index": "index",
    "collection": "collection",
    "controller": "realtime",
    "action": "subscribe",
    "body": {}
  });

  // step 3 - when publishing a message, we get some notifications back
  socket.emit("kuzzle", {
    "index": "index",
    "collection": "collection",
    "controller": "realtime",
    "action": "publish",
    "body": {
      "foo": "bar"
    }
  });
</script>

MQTT

# shell 1 - getting direct responses from kuzzle
node_modules/.bin/mqtt subscribe -v -h rabbit -t mqtt.myId

# shell 2 - we subscribe to our documents
node_modules/.bin/mqtt publish -h rabbit -t kuzzle -m '{
  "controller": "realtime",
  "action":"subscribe",
  "index": "index",
  "collection": "collection",
  "body": {}
}'

# shell 1 (prettified)
mqtt/myId {
  "status": 200,
  "error": null,
  "index": "index",
  "collection": "collection",
  "controller": "controller",
  "action": "action",
  "metadata": {},
  "requestId": "60621753-2da2-441a-b30b-546127f26cd1",
  "result": {
    "roomId": "632682a9eac95cfb95e3a697b29b7739",
    "channel": "632682a9eac95cfb95e3a697b29b7739-1c7beed7521fd0b0a8177f219b786d2e",
    "timestamp": 1450267140597
  }
}

# shell 3 - we subscribe to the nofitications
node_modules/.bin/mqtt subscribe -h rabbit -t 632682a9eac95cfb95e3a697b29b7739-1c7beed7521fd0b0a8177f219b786d2e

# shell 2 - we publish a message
node_modules/.bin/mqtt publish -h rabbit -t kuzzle -m '{
  "controller": "realtime",
  "action": "publish",
  "index": "index",
  "collection": "collection",
  "body": {"foo": "bar"}
}'

# shell 3
{
  "status": 200,
  "error": null,
  "index": "index",
  "collection": "collection",
  "controller": "controller",
  "action": "action",
  "state": "done",
  "scope": "in",
  "metadata": {},
  "requestId": "10bca195-f375-4b72-817a-04fcb22b3681",
  "result": {
    "_source": {"foo":"bar"}
  }
}

Subscribing to some documents in Kuzzle allows to be notified back each time a document matches your criteria. The subscription action (realtime/subscribe) returns a channel identifier which you can then listen to receive the notifications.

You can receive the following types of notifications:

Document Notifications:

  • A document has been created
  • A document has been updated and entered your subscription scope
  • A document has been updated and left your subscription scope
  • A document has been deleted
  • A document is about to be created (realtime)
  • A document is about to be deleted (realtime)

Subscription Notifications:

  • A user subscribed to this room
  • A user left this room

Server Notifications:

  • Your JWT Token has expired

A document has been created

{
  "status": 200,                        // Assuming everything went well
  "error": null,                        // Assuming everything went well
  "index": "<index>",
  "collection": "<collection>",
  "controller": "document",
  "action": "create",
  "state": "done",                      // The document has been fully created
  "scope": "in",                        // The document entered your room scope
  "metadata": {
    // metadata embedded in the request
  },
  "requestId": "<unique request identifier>",
  "result": {                           // The created document
    "_id": "documentId",
    "_source": {...}
  }
}

An updated document entered your listening scope

{
  "status": 200,                        // Assuming everything went well
  "error": null,                        // Assuming everything went well
  "index": "<index>",
  "collection": "<collection>",
  "controller": "document",
  "action": "update",
  "state": "done",                      // The document has been fully updated
  "scope": "in",                        // The document entered your room scope
  "metadata": {
    // metadata embedded in the request
  },
  "requestId": "<unique request identifier>",
  "result": {                           // The updated document
    "_id": "<documentId>",
    ...
  }
}

An updated document left your listening scope

{
  "status": 200,                        // Assuming everything went well
  "error": null,                        // Assuming everything went well
  "index": "<index>",
  "collection": "<collection>",
  "controller": "document",
  "action": "update",
  "state": "done",                     // The document has been fully updated
  "scope": "out",                      // The document left your room scope
  "metadata": {
    // metadata embedded in the request
  },
  "requestId": "<unique request identifier>",
  "result": {                          // The updated document
    "_id": "<documentId>",
    ...
  }
}

A document has been deleted

{
  "status": 200,                        // Assuming everything went well
  "error": null,                        // Assuming everything went well
  "index": "<index>",
  "collection": "<collection>",
  "controller": "document",
  "action": "delete",
  "state": "done",                     // The document has been fully deleted
  "scope": "out",                      // The document left your room scope
  "metadata": {
    // metadata embedded in the request
  },
  "requestId": "<unique request identifier>",
  "result": {                          // The updated document
    "_id": "<documentId>",
    ...
  }
}

A document is about to be created

{
  "status": 200,                        // Assuming everything went well
  "error": null,                        // Assuming everything went well
  "index": "<index>",
  "collection": "<collection>",
  "controller": "document",
  "action": "create",
  "state": "pending",                   // Indicates that the document will be created
  "metadata": {},
  "result": {}
}

A document is about to be deleted

{
  "status": 200,                        // Assuming everything went well
  "error": null,                        // Assuming everything went well
  "index": "<index>",
  "collection": "<collection>",
  "controller": "document",
  "action": "delete",
  "state": "pending",                   // Indicates that the document will be deleted
  "metadata": {},
  "result": {}
}

A user subscribed to this room

{
  "status": 200,                        // Assuming everything went well
  "error": null,                        // Assuming everything went well
  "index": "<index>",
  "collection": "<collection>",
  "controller": "realtime",
  "action": "subscribe",
  "metadata": {
    // metadata embedded in the request
  },
  "requestId": "<unique request identifier>",
  "result": {
    "roomId": "<unique Kuzzle room identifier>",
    "count": <the new user count on that room>
  }
}

A user left this room

{
  "status": 200,                        // Assuming everything went well
  "error": null,                        // Assuming everything went well
  "index": "<index>",
  "collection": "<collection>",
  "controller": "realtime",
  "action": "unsubscribe",
  "metadata": {
    // metadata embedded in the request
  },
  "requestId": "<unique request identifier>",
  "result": {
    "roomId": "<unique Kuzzle room identifier>",
    "count": <the new user count on that room>
  }
}

Your JWT Token has expired

{
  "status": 200,                        // Assuming everything went well
  "error": null,                        // Assuming everything went well
  "controller": "auth",
  "action": "jwtTokenExpired",
  "requestId": "server notification",
}

~ auth controller

checkToken

URL: http://kuzzle:7512/_checkToken Method: POST Body:

{
  "token": "..."
}

Query

{
  "controller": "auth",
  "action": "checkToken",
  "body": {
    "token": "..."
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "controller": "auth",
  "action": "checkToken",
  "requestId": "<unique request identifier>",
  "result": {
    "valid": <boolean>,

    // if "valid" is false, contains the reason why the provided token is
    // invalid.
    // This field is not present if "valid" is true.
    "state": "Error message",

    // if "valid" is true, contains the expiration timestamp.
    // This field is not present if "valid" is false.
    "expiresAt": <timestamp>
  }
}

Checks a JWT Token validity. This API route does not require to be logged in.

getCurrentUser

URL: http://kuzzle:7512/users/_me Method: GET Headers: Authorization: "Bearer <encrypted_jwt_token>"

Query

{
  "controller": "auth",
  "action": "getCurrentUser"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<index>",
  "collection": "<collection>",
  "controller": "auth",
  "action": "getCurrentUser",
  "requestId": "<unique request identifier>",
  "jwt": "<encrypted_jwt_token>",
  "result": {
    "_id":"<userId>",
    "_source": {
      "name": {
        "first": "Steve",
        "last": "Wozniak"
        },
        ...                         // The user object content
        "profile": {
          "_id":"<profileId>",
          "roles": [
            ...                     // Users roles definitions
          ]
        }
    }
  }
}

Gets the user object identified by the JSON Web Token provided in the query or the Authorization header.

getMyRights

URL: http://kuzzle:7512/users/_me/_rights Method: GET Headers: Authorization: "Bearer <encrypted_jwt_token>"

Query

{
  "controller": "auth",
  "action": "getMyRights"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "jwt": "<encrypted_jwt_token>",
  "result": {
    // An array of objects containing the user rights
    "hits": [
      {
        "controller": "<ctrl_name|*>",
        "action": "<action_name|*>",
        "index": "<index_name|*>",
        "collection": "<collection_name|*>",
        "value": "<allowed|denied|conditional>"
      },
      {
        // Another rights item... and so on
      }
    ],
}

Gets the rights of the user identified by the JSON Web Token provided in the query or the Authorization header.

login

URL: http://kuzzle:7512/_login Method: POST Body:

{
  // authentication strategy identifier (optionnal : kuzzle will use "local" strategy if not set)
  "strategy": "<passportjs_strategy>",

  // jwt token expiration time (optional - kuzzle will use server default value if not set)
  // expressed in seconds or a string describing a time span. Eg: 60, "2 days", "10h", "7d", "1y"
  "expiresIn": "<expiresIn>",

  // set of parameters depending of the chosen strategy. Example for "local" strategy:
  "username": "<username>",
  "password": "<password>"
}

Query

{
  "controller": "auth",
  "action": "login",

  "body": {
    // authentication strategy identifier (optional - kuzzle will use "local" strategy if not set)
    "strategy": "<passportjs_strategy>",

    // jwt token expiration time (optional - kuzzle will use server default value if not set)
    // expressed in seconds or a string describing a time span. Eg: 60, "2 days", "10h", "7d", "1y"
    "expiresIn": "<expiresIn>",

    // set of parameters depending of the chosen strategy. Example for "local" strategy:
    "username": "<username>",
    "password": "<password>"
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "controller": "auth",
  "action": "login",
  "requestId": "<unique request identifier>",
  "metadata": {},
  "result": {
    "_id": "<userId>",
    "jwt": "<JWT encrypted token>"
  }
}

Authenticates a user with a defined passportjs authentication strategy. See passportjs.org for more details about authentication strategies.

Strategies are implemented as plugins. The default “local” strategy is enabled by default (see kuzzle-plugin-auth-passport-local), and let you authenticate with a login and password.

The _login action returns an encrypted JWT token, that must then be sent within the requests headers.

logout

URL: http://kuzzle:7512/_logout Method: GET Headers: Authorization: "Bearer <encrypted_jwt_token>"

Query

{
  "controller": "auth",
  "action": "logout",
  "jwt": "<encrypted_jwt_token>"
}

Revokes the token validity & unsubscribe from registered rooms.

The _logout action doesn’t take strategy.

updateSelf

URL: http://kuzzle:7512/_updateSelf Method: PUT Headers: Authorization: "Bearer <encrypted_jwt_token>" Body

{
    "foo": "bar",                    // Some properties to update
    "name": "Walter Smith",
    ...
}

Query

{
  "controller": "auth",
  "action": "updateSelf",
  "jwt": "<encrypted_jwt_token>",
  "body": {
    "foo": "bar",                    // Some properties to update
    "name": "Walter Smith",
    ...
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "action": "updateSelf",
  "controller": "auth",
  "metadata": {},
  "requestId": "<unique request identifier>",
  "result": {
    "_id": "<userId>",
    "_source": {
      "foo": "bar",
      "name": "Walter Smith",
      ....
    }
  }
}

Updates the current User object in Kuzzle’s database layer.

~ bulk controller

A bulk import allows your application to perform multiple writing operations thanks to a single query. This is especially useful if you want to create a large number of documents. A bulk import will be a lot faster compared to creating them individually using create queries.

For other queries, the syntax for bulk imports closely resembles the ElasticSearch Bulk API.

import

Performing a bulk import on a data collection

URL: http://kuzzle:7512/<index>/<collection>/_bulk Method: POST Body:

{
  // Data mapping using ElasticSearch bulk syntax.
  "bulkData": [
    {"create": {}},
    {"a": "document", "with": "any", "number": "of fields"},
    {"create": {}},
    {"another": "document"},
    {"create": {}},
    {"and": {"another": "one"}},
    {"...": "..."}
  ]
}

Query

{
  "index": "<index>",
  "collection": "<collection>",
  "controller": "bulk",
  "action": "import",

  "body": {
    // Data mapping using ElasticSearch bulk syntax.
    "bulkData": [
      {"create": {}},
      {"a": "document", "with": "any", "number": "of fields"},
      {"create": {}},
      {"another": "document"},
      {"create": {}},
      {"and": {"another": "one"}},
      {"...": "..."}
    ]
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<index>",
  "collection": "<collection>",
  "controller": "bulk",
  "action": "import",
  "requestId": "<unique request identifier>",
  "result": {
    // The list of executed queries, with their status
    "hits": [
      {
        "create": {
          "_id": "<documentId>",
          "status": <HTTP status code>
        }
      },
      {
        "create": {
          "_id": "<documentId>",
          "status": <HTTP status code>
        }
      },
      {
        "create": {
          "_id": "<documentId>",
          "status": <HTTP status code>
        }
      }
    ]
  }
}

You can use the bulk import to save a list of documents in one specific collection in a specified index.
In such case, the collection in which the documents need to be inserted needs to be specified in the query.

Performing a global bulk import

URL: http://kuzzle:7512/_bulk Method: POST Body:

{
  // Data mapping using ElasticSearch bulk syntax.
  "bulkData": [
    {"create": {"_index": "<index>", "_type": "<collection>"}},
    {"a": "document", "with": "any", "number": "of fields"},
    {"create": {"_index": "<index>", "_type": "<collection>"}},
    {"another": "document"},
    {"create": {"_index": "<index>", "_type": "<collection>"}},
    {"and": { "another": "one"} },
    ...
    {"create": {"index": { "_index": "<another index>", "_type": "<another collection>" }}}
  ]
}

Query

{
  "controller": "bulk",
  "action": "import",

  "body": {
    // Data mapping using ElasticSearch bulk syntax.
    "bulkData": [
      {"create": {"_index": "<index>", "_type": "<collection>"}},
      {"a": "document", "with": "any", "number": "of fields"},
      {"create": {"_index": "<index>", "_type": "<collection>"}},
      {"another": "document"},
      {"create": {"_index": "<index>", "_type": "<collection>"}},
      {"and": { "another": "one"} },
      ...
      {"create": {"index": { "_index": "<another index>", "_type": "<another collection>" }}}
    ]
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "controller": "bulk",
  "action": "import",
  "requestId": "<unique request identifier>",
  "result": {
    // The list of executed queries, with their status
    "hits": [
      {
        "create": {
          "_id": "<documentId>",
          "status": <HTTP status code>
        }
      },
      {
        "create": {
          "_id": ""<documentId>",
          "status": <HTTP status code>
        }
      },
      {
        "create": {
          "_id": "<documentId>",
          "status": <HTTP status code>
        }
      }
    ]
  }
}

The bulk import can also be used in a more versatile (yet a little more verbose) way, to execute operations on a whole database, modifying multiple data collections in different indexes at once.
The collections to modify then need to be specified inside the query message,using the _typeargument, as specified in the ElasticSearch Bluk API.

~ collection controller

create

URL: http://kuzzle:7512/<data>/<collection> Method: PUT

Query

{
  "index": "<index>",
  "collection": "<collection>",
  "controller": "collection",
  "action": "create"
}

Response

{
  "status": 200,
  "error": null,
  "index": "<index>",
  "collection": "<collection>",
  "controller": "collection",
  "action": "create",
  "requestId": "<unique request identifier>",
  "result": {
    "acknowledged": true
  }
}

When creating a document, Kuzzle will automatically create a collection if needed. But in some cases, you may want to create an empty collection directly, prior to storing any document in it.
This method does nothing if the collection already exists.

deleteSpecifications

URL: http://kuzzle:7512/<index>/<collection>/_specifications Method: DELETE

Query

{
  "index": "<index>",
  "collection": "<collection>",
  "controller": "collection",
  "action": "deleteSpecifications",
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<index>",
  "collection": "<collection>",
  "action": "deleteSpecifications",
  "controller": "collection",
  "result": {}
}

Deletes the validation specification set for the /. It responds 200 even there where no validation specification manually set before.

Note: by default, an empty specification is implicitally applied to all collections which. In a way, “no specification set” means “all documents are valid”. This is why, using this route when no specifications have been set before, does not produce an error.

exists

URL: http://kuzzle:7512/<index>/<collection>/_exists Method: GET

Query

{
  "index": "<index>",
  "collection": "<collection>",
  "controller": "collection",
  "action": "exists"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<index>",
  "collection": "<collection>",
  "controller": "collection",
  "action": "exists",
  "requestId": "<unique request identifier>",
  "result": true
}

Checks if a collection exists in Kuzzle database storage layer.

getMapping

URL: http://kuzzle:7512/<index>/<collection>/_mapping Method: GET

Query

{
  "index": "<index>",
  "collection": "<collection>",
  "controller": "collection",
  "action": "getMapping"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<index>",
  "collection": "<collection>",
  "controller": "collection",
  "action": "getMapping",
  "requestId": "<unique request identifier>",
  "result": {
    "mainindex": {
      "mappings": {
        <collection>: {

          // Data mapping using ElasticSearch mapping syntax
          "properties": {
            "field1": {type: "field type", "...options..." },
            "field2": {type: "field type", "...options..." },
            ...
            "fieldn": {type: "field type", "...options..." },
          }
        }
      }
    }
  }
}

Gets the mapping of the given collection.

getSpecifications

URL: http://kuzzle:7512/<index>/<collection>/_specifications Method: GET

Query

{
  "index": "<index>",
  "collection": "<collection>",
  "controller": "collection",
  "action": "getSpecifications",
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "action": "getSpecifications",
  "controller": "collection",
  "collection": "<collection>",
  "index": "<index>",
  "result": {
    "collection": "<collection>",
    "index": "<index>",
    "validation": {
      "fields": {
        myField": {
          "defaultValue": 42,
          "mandatory": true,
          "type": "integer"
        }
        ...
      },
      "strict": true
    }
  }
}

{
  "status": 404,                      // No validation specification has been set for this index/collection
  "error": {
    "_source": {
      "body": {}
    },
    "message": "Not Found"
  },
  "action": "getSpecifications",
  "controller": "collection",
  "index": "<index>",
  "collection": "<collection>"
  "result": null
}

Allows to get the validation specifications associated to the given index and collection if some specifications has been defined first.

list

URL: http://kuzzle:7512/<index>/_list(/<all|stored|realtime>)[?from=0][&size=42] Method: GET

Query

{
  "index": "<index>",
  "controller": "collection",
  "action": "list",
  "type": "<all|stored|realtime>",
  // "from" and "size" argument for pagination
  "from": 0,
  "size": 42
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<index>",
  "controller": "collection",
  "action": "list",
  "requestId": "<unique request identifier>",
  "result": {
    "collections": [
      {
        "name": "realtime_1", "type": "realtime"
      },
      {
        "name": "realtime_2", "type": "realtime"
      },
      {
        "name": "realtime_...", "type": "realtime"
      },
      {
        "name": "realtime_n", "type": "realtime"
      },
      {
        "name": "stored_1", "type": "stored"
      },
      {
        "name": "stored_2", "type": "stored"
      },
      {
        "name": "stored_...", "type": "stored"
      },
      {
        "name": "stored_n", "type": "stored"
      }
    ],
    "type": "all"
  }
}

Returns the complete list of realtime and stored data collections in requested index sorted by name in alphanumerical order.
The type argument filters the returned collections. Allowed values: all, stored and realtime (default : all).
The from and size arguments allow pagination. They are returned in the response if provided.

searchSpecifications

URL: http://kuzzle:7512/_searchSpecifications Method: POST Body

{
  // A set of filters or queries matching documents you are looking for.
  "query": {
    ...
  }
}

Query

{
  "controller": "collection",
  "action": "searchSpecifications",
  "body": {
    // A set of filters or queries matching documents you are looking for.
    "query": {
      "Some": "filters"
    }
  },
  // "from" and "size" argument for pagination
  "from": 0,
  "size": 42
}

>Response

```litcoffee
{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "controller": "collection",
  "action": "searchSpecifications",
  "metadata": {},
  "requestId": "<unique request identifier>",
  "result": {
    "_shards": {
        "failed": 0,
        "successful": 5,
        "total": 5
    },
    "hits": [
      {
        "_id": "myIndex#myCollection",
        "_index": "%kuzzle",
        "_score": 1,
        "_source": {
          "collection": "myCollection",
          "index": "myIndex",
          "validation": {
            "fields": {
              "fieldName": {
                "defaultValue": "a default value",
                "mandatory": true,
                "multivalued": {
                  "maxCount": 5,
                  "minCount": 1,
                  "value": true
                },
                "type": "string",
                "typeOptions": {
                  "length": {
                    "max": 12,
                    "min": 2
                  }
                }
              }
            },
            "strict": true
          }
        },
        "_type": "validations"
      }
    ],
    "max_score": null,
    "timed_out": false,
    "took": 1,
    "total": <number of results>
  }
}

Allows to search in the persistence layer for collection specifications.

truncate

URL: http://kuzzle:7512/<index>/<collection>/_truncate Method: DELETE

Query

{
  "index": "<index>",
  "collection": "<collection>",
  "controller": "collection",
  "action": "truncate"
}

Response

{
  "status": 200,
  "error": null,
  "action": "truncate",
  "controller": "collection",
  "index": "<index>",
  "collection": "<collection>",
  "requestId": "<unique request identifier>",
  "result": {
    "acknowledged": true,
  }
}

Empties a collection from all its documents, while keeping any associated mapping.
It is also faster than deleting all documents from a collection using a query.

updateMapping

URL: http://kuzzle:7512/<index>/<collection>/_mapping Method: PUT Body:

{
  // Data mapping using ElasticSearch mapping syntax
  "properties": {
    "field1": {
      "type": "field type",
      "other": "...options..."
    },
    "field2": {
      "type": "field type",
      "other": "...options..."
    },
    ...
    "fieldn": {
      "type": "field type",
      "other": "...options..."
    }
  }
}

Query

{
  "index": "<index>",
  "collection": "<collection>",
  "controller": "collection",
  "action": "updateMapping",

  // Data mapping using ElasticSearch mapping syntax
  "body": {
    "properties": {
      "field1": {
        "type": "field type",
        "...options..."
      },
      "field2": {
        "type": "field type",
        "...options..."
      },
      ...
      "fieldn": {
        "type": "field type",
        "...options..."
      }
    }
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<index>",
  "collection": "<collection>",
  "action": "updateMapping",
  "controller": "collection",
  "requestId": "<unique request identifier>",
  "result": {}
}

When creating a new data collection in the persistent data storage layer, Kuzzle uses a default mapping.

It means that, by default, you won’t be able to exploit the full capabilities of our persistent data storage layer (currently handled by ElasticSearch), and your searches may suffer from below-average performances, depending on the amount of data you stored in a collection and the complexity of your database.

To solve this matter, Kuzzle’s API offers a way to create data mapping and to expose the entire mapping capabilities of ElasticSearch.

updateSpecifications

URL: http://kuzzle:7512/_specifications Method: PUT Body:

{
  "myindex": {
    "mycollection": {
      "strict": <true|false>,
      "fields": {
        // ... specification for each field
      }
    }
  }
}

Query

{
  "controller": "collection",
  "action": "updateSpecifications",

  // Data mapping using ElasticSearch mapping syntax
  "body": {
    "myindex": {
      "mycollection": {
        "strict": <true|false>,
        "fields": {
          // ... specification for each field
        }
      }
    }
  }

}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<index>",
  "collection": "<collection>",
  "action": "updateSpecifications",
  "controller": "collection",
  "result": {
    "myindex": {
      "mycollection": {
        "strict": <true|false>,
        "fields": {
          // ... specification for each field
        }
      }
    }
  }
}

{
  "status": 400,                      // There was an error on specification
  "action": "updateSpecifications",
  "controller": "collections",
  "error": {
    "_source": // ... given specifications,
    "message": {
      "description": // ...global error description,
      "details": // ... an array of detailed problem found,
      "valid": false // the specifications are not valid
    }
  },
  "metadata": {},
  "result": {
    "myindex": {
      "mycollection": {
        "strict": <true|false>,
        "fields": {
          "myField": {
             // ... specification with an error
          }
        }
      }
    }
  }
}

You can specify validation specifications in order to enforce your own rules over documents and real-time messages. Whenever a document is stored or updated, or a message is published, Kuzzle applies these specifications to check if the new data complies to the defined rules. If not, the document or message will be rejected along with an appropriate error message. This method allows you to specify or update the validation specifications. You can both use it to create or update validation specifications for one index/collection couple or more. When the validation specification is not well formatted, a detailed error message is answered by Kuzzle to help you to debug.

validateSpecifications

URL: http://kuzzle:7512/_validateSpecifications Method: POST Body:

{
  "myindex": {
    "mycollection": {
      "strict": <true|false>,
      "fields": {
        // ... specification for each field
      }
    }
  }
}

Query

{
  "controller": "admin",
  "action": "updateSpecifications",

  // Data mapping using ElasticSearch mapping syntax
  "body": {
    "myindex": {
      "mycollection": {
        "strict": <true|false>,
        "fields": {
          // ... specification for each field
        }
      }
    }
  }

}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<index>",
  "collection": "<collection>",
  "action": "updateMapping",
  "controller": "admin",
  "state": "done",
  "requestId": "<unique request identifier>",
  "result": {
    "valid": <true|false>,
    "details": [ // it some errors have been found
      // each spotted errors
    ],
    "description": "<string>" // global description if validation fails
  }
}

You can specify validation specifications in order to enforce your own rules over documents and real-time messages. Whenever a document is stored or updated, or a message is published, Kuzzle applies these specifications to check if the new data complies to the defined rules. If not, the document or message will be rejected along with an appropriate error message. This method checks if a validation specification is well-formed. It does not store nor modify in any way the existing specifications database. When the validation specification is not well formatted, a detailed error message is answered by Kuzzle to help you to debug.

~ document controller

count

URL: http://kuzzle:7512/<index>/<collection>/_count Method: POST Body:

{
  // A set of filters or queries matching documents you are looking for.
  // Use "query" instead of "filter" if you want to perform a query instead.
  "filter": {
    ...
  }
}

Query

{
  "index": "<index>",
  "collection": "<collection>",
  "controller": "document",
  "action": "count",

  // A set of filters or queries matching documents you are looking for.
  // Use "query" instead of "filter" if you want to perform a query instead.
  "body": {
    "filter": {
      ...
    }
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<index>",
  "collection": "<collection>",
  "controller": "document",
  "action": "count",
  "requestId": "<unique request identifier>",
  "result": {
    "count": <number of found documents>
  }
}

Given some filters, gets the number of matching documents from Kuzzle’s data storage layer.

Kuzzle uses the ElasticSearch Query DSL syntax.

create

URL: http://kuzzle:7512/<index>/<collection>/_create[?refresh=wait_for] or http://kuzzle:7512/<index>/<collection>/<documentId>/_create[?refresh=wait_for] Method: POST Body:

{
  // The message to send
}

Query

{
  "index": "<index>",
  "collection": "<collection>",
  "controller": "document",
  "action": "create",
  ["refresh": "wait_for",]
  "_id": "<documentId>",              // Optional. If not provided, will be generated automatically.
  "body": {
    // the document to create
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<index>",
  "collection": "<collection>",
  "controller": "document",
  "action": "create",
  "requestId": "<unique request identifier>",
  "result": {
    "_id": "<documentId>",            // The generated or provided document id
    "_version": 1                     // The version of the document in the persistent data storage
    "_source": {                      // The created document
      ...
    },
  }
}

Creates a new document in the persistent data storage.

Returns an error if the document already exists.

Elastisearch 5.x and above only: The optional parameter refresh can be used with the value wait_for in order to wait for the document indexation (indexed documents are available for search).

createOrReplace

URL: http://kuzzle:7512/<index>/<collection>/<documentId>[?refresh=wait_for] Method: PUT Body:

{
  // The document to update
}

Query

{
  "index": "<index>",
  "collection": "<collection>",
  "controller": "document",
  "action": "createOrReplace",
  ["refresh": "wait_for",]
  "_id": "<documentId>",            // Mandatory: The document id.
  // The document itself
  "body": {
    ...
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<index>",
  "collection": "<collection>",
  "controller": "document",
  "action": "createOrReplace",
  "requestId": "<unique request identifier>",
  "result": {
    "_id": "<documentId>",
    "_source": {                      // The created document
      ...
    },
    "_version": <number>,             // The new version number of this document
    "created": <boolean>              // true: a new document has been created, false: the document has been updated
  }
}

Creates a new document in the persistent data storage, or replaces it if it already exists.

Elastisearch 5.x and above only: The optional parameter refresh can be used with the value wait_for in order to wait for the document indexation (indexed documents are available for search).

delete

URL: http://kuzzle:7512/<index>/<collection>/<documentId>[?refresh=wait_for] Method: DELETE

Query

{
  "index": "<index>",
  "collection": "<collection>",
  "controller": "document",
  "action": "delete",
  ["refresh": "wait_for",]

  // The document id you provided or that was generated at document creation.
  // it is also the one returned during a search query.
  "_id": "<documentId>"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<index>",
  "collection": "<collection>",
  "controller": "document",
  "action": "delete",
  "requestId": "<unique request identifier>",
  "result": {
    "_id": "<documentId>"             // The deleted document identifier
  }
}

Given a documentId, deletes the corresponding document from Kuzzle’s database.

Only documents in the persistent data storage layer can be deleted.

Elastisearch 5.x and above only: The optional parameter refresh can be used with the value wait_for in order to wait for the document deletion (and its unavailability in search).

deleteByQuery

URL: http://kuzzle:7512/<index>/<collection>/_query Method: DELETE Body:

{
  // A set of filters or queries matching documents you are looking for.
  // Use "query" instead of "filter" if you want to perform a query instead.
  "filter": {
    ...
  }
}

Query

{
  "index": "<index>",
  "collection": "<collection>",
  "controller": "document",
  "action": "deleteByQuery",

  // A set of filters or queries matching documents you are looking for.
  // Use "query" instead of "filter" if you want to perform a query instead.
  "body": {
    "filter": {
      ...
    }
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<index>",
  "collection": "<collection>",
  "controller": "document",
  "action": "deleteByQuery",
  "requestId": "<unique request identifier>",
  "result": {
    // Array of strings listing the IDs of removed documents
    "hits": ["id1", "id2", ..., "idn"]
  }
}

Deletes all the documents matching the given filter or query from Kuzzle’s database.

Kuzzle uses the ElasticSearch Query DSL syntax.

get

URL: http://kuzzle:7512/<index>/<collection>/<documentId> Method: GET

Query

{
  "index": "<index>",
  "collection": "<collection>",
  "controller": "document",
  "action": "get",

  // The document id you provided or that was generated at document creation.
  // it is also the one returned during a search query.
  "_id": "<documentId>"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<index>",
  "collection": "<collection>",
  "controller": "document",
  "action": "get",
  "requestId": "<unique request identifier>",
  "result": {
    "_id": "<documentId>",
    "_index": "<index>",
    "_type": "<collection>",
    "_version": 1,
    "_source": {
      "name": {
        "first": "Steve",
        "last": "Wozniak"
      },
      "hobby": "Segway polo",
      ...
    }
  }
}

Given a document id, retrieves the corresponding document from the database.

Only documents in the persistent data storage layer can be retrieved.

replace

URL: http://kuzzle:7512/<index>/<collection>/<documentId>/_replace[?refresh=wait_for] Method: PUT Body:

{
  // The document to update
}

Query

{
  "index": "<index>",
  "collection": "<collection>",
  "controller": "document",
  "action": "replace",
  ["refresh": "wait_for",]
  // The document itself
  "body": {
    ...
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<index>",
  "collection": "<collection>",
  "controller": "document",
  "action": "replace",
  "requestId": "<unique request identifier>",
  "result": {
    "_id": "<documentId>",
    "_source": {                      // The resulting document
      ...
    },
    "_version": <number>,             // The new version number of this document
    "created": false
  }
}

Replaces an existing document in the persistent data storage. Only documents in the persistent data storage layer can be replaced.

Elastisearch 5.x and above only: The optional parameter refresh can be used with the value wait_for in order to wait for the document indexation (indexed documents are available for search).

scroll

URL: http://kuzzle:7512/_scroll/<scrollId>[?scroll=<scroll ttl]
Method: GET

Query

{
  "controller": "document",
  "action": "scroll",
  "scrollId": "<scrollId>",

  // Optional: time to live of the cursor
  "scroll": "1m"
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "action": "scroll",
  "controller": "document",
  "requestId": "<unique request identifier>",
  "result": {
    // The initial search request and each subsequent scroll request returns a new _scroll_id
    // only the most recent _scroll_id should be used.
    "_scroll_id": "<new scroll id>",

    // An array of objects containing your retrieved documents
    "hits": [
      {
        "_id": "documentId",
        "_score": "<document score>"
        "_source": { .. }         // The actual document
      },
      {
        // Another document... and so on
      }
    ],
    "total": <number of found documents>,
    "max_score": 1,
    "timed_out": false,
    "took": 1
  }
}

While a search request returns a single “page” of results, the scroll API can be used to retrieve large numbers of results (or even all results) from a single search request, in much the same way as you would use a cursor on a traditional database.

Scrolling is not intended for real time user requests, but rather for processing large amounts of data.

In order to use scrolling, the initial search request should specify the scroll parameter in the query string, which tells Elasticsearch how long it should keep the “search context” alive.

URL: http://kuzzle:7512/<index>/<collection>/_search[?from=0][&size=42] Method: POST Body:

{
  // A set of filters or queries matching documents you are looking for.
  "query": {
    ...
  },
  "aggregations": {
    ...
  }
}

Query

{
  "index": "<index>",
  "collection": "<collection>",
  "controller": "document",
  "action": "search",

  "body": {
    // A set of filters or queries matching documents you are looking for.
    "query": {

    },
    "aggregations": {

    }
  },
  // "from" and "size" argument for pagination
  "from": 0,
  "size": 42
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<index>",
  "collection": "<collection>",
  "action": "search",
  "controller": "document",
  "requestId": "<unique request identifier>",
  "result": {
    // The initial search request and each subsequent scroll request returns a new _scroll_id
    // only the most recent _scroll_id should be used.
    "_scroll_id": "<scroll id>",

    // An array of objects containing your retrieved documents
    "hits": [
      {
        "_id": "documentId",
        "_score": "<document score>"
        "_source": { ... }         // The actual document
      },
      {
        // Another document... and so on
      }
    ],
    "aggregations": {
      "aggs_name": {

      }
    }
    "total": <number of found documents>,
    "max_score": 1,
    "timed_out": false,
    "took": 1
  }
}

Only documents in the persistent data storage layer can be searched.

Kuzzle uses the ElasticSearch Query DSL syntax.

aggregations is not mandatory, see the Elasticsearch Documentation for more details.

mCreate

URL: http://kuzzle:7512/<index>/<collection>/_mCreate[?refresh=wait_for] Method: POST Body:

{
  "documents": [
    {
      "_id": "<documentId>",              // Optional. If not provided, will be generated automatically.
      "body": {
        "document": "body",
        ...
      }
    },
    {
      "_id": "<anotherDocumentId>"        // Optional. If not provided, will be generated automatically.
      "body": {
        "document": "body",
        ...
      }
    },
    ...
  ]
}

Query

{
  "index": "<index>",
  "collection": "<collection>",
  "controller": "document",
  "action": "mCreate",
  ["refresh": "wait_for",]
  "body": {
    "documents": [
      {
        "_id": "<documentId>",
        "body": {
          "document": "body",
          ...
        }
      },
      {
        "_id": "<anotherDocumentId>",
        "body": {
          "document": "body",
          ...
        }
      },
      ...
    ]
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<index>",
  "collection": "<collection>",
  "action": "mCreate",
  "controller": "document",
  "requestId": "<unique request identifier>",
  "result": {
    "hits": [
      {
        "_id": "<documentId>",
        "_index": "<index>",
        "_shards": {
          "failed": 0,
          "successful": 1,
          "total": 2
        },
        "_source": {
          "_kuzzle_info": {
            "active": true,
            "author": "-1",
            "createdAt": 1484225532686,
            "deletedAt": null,
            "updatedAt": null,
            "updater": null
          },
          "document": "body"
        },
        "_type": "<collection>",
        "_version": 1,
        "created": true,
        "result": "created"
      },
      {
        "_id": "<anotherDocumentId>",
        "_index": "<index>",
        "_shards": {
          "failed": 0,
          "successful": 1,
          "total": 2
        },
        "_source": {
          "_kuzzle_info": {
            "active": true,
            "author": "-1",
            "createdAt": 1484225532686,
            "deletedAt": null,
            "updatedAt": null,
            "updater": null
          },
          "document": "body"
        },
        "_type": "<collection>",
        "_version": 1,
        "created": true,
        "result": "created"
      },
      {
        // Other created documents
      }
    ],
    "total": <number of created documents>
  }
}

Creates new documents in the persistent data storage.

Returns a partial error (with status 206) if one or more documents already exist.

Elastisearch 5.x and above only: The optional parameter refresh can be used with the value wait_for in order to wait for the document indexation (indexed documents are available for search).

mCreateOrReplace

URL: http://kuzzle:7512/<index>/<collection>/_mCreateOrReplace[?refresh=wait_for] Method: PUT Body:

{
  "documents": [
    {
      "_id": "<documentId>",              // Mandatory
      "body": {
        "document": "body",
        ...
      }
    },
    {
      "_id": "<anotherDocumentId>"        // Mandatory
      "body": {
        "document": "body",
        ...
      }
    },
    ...
  ]
}

Query

{
  "index": "<index>",
  "collection": "<collection>",
  "controller": "document",
  "action": "mCreateOrReplace",
  ["refresh": "wait_for",]
  "body": {
    "documents": [
      {
        "_id": "<documentId>",
        "body": {
          "document": "body",
          ...
        }
      },
      {
        "_id": "<anotherDocumentId>",
        "body": {
          "document": "body",
          ...
        }
      },
      ...
    ]
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<index>",
  "collection": "<collection>",
  "action": "mCreateOrReplace",
  "controller": "document",
  "requestId": "<unique request identifier>",
  "result": {
    "hits": [
      {
        "_id": "<documentId>",
        "_index": "<index>",
        "_shards": {
          "failed": 0,
          "successful": 1,
          "total": 2
        },
        "_source": {
          "_kuzzle_info": {
            "active": true,
            "author": "-1",
            "createdAt": 1484226104822,
            "deletedAt": null,
            "updatedAt": null,
            "updater": null
          },
          "document": "body"
        },
        "_type": "<collection>",
        "_version": 2,
        "created": false,
        "result": "updated"
      },
      {
        "_id": "<anotherDocumentId>",
        "_index": "<index>",
        "_shards": {
          "failed": 0,
          "successful": 1,
          "total": 2
        },
        "_source": {
          "_kuzzle_info": {
            "active": true,
            "author": "-1",
            "createdAt": 1484226104822,
            "deletedAt": null,
            "updatedAt": null,
            "updater": null
          },
          "document": "body"
        },
        "_type": "<collection>",
        "_version": 2,
        "created": false,
        "result": "updated"
      },
      {
        // Other created or replaced documents
      }
    ],
    "total": <number of created or replaced documents>
  }
}

Creates or replaces documents in the persistent data storage.

Returns a partial error (with status 206) if one or more documents can not be created or replaced.

mDelete

URL: http://kuzzle:7512/<index>/<collection>/_mDelete[?refresh=wait_for] Method: DELETE Body:

{
  "ids": ["<documentId>", "<anotherDocumentId>", ...]
}

Query

{
  "index": "<index>",
  "collection": "<collection>",
  "controller": "document",
  "action": "mDelete",
  "body": {
    "ids": ["<documentId>", "<anotherDocumentId>", ...]
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<index>",
  "collection": "<collection>",
  "action": "mDelete",
  ["refresh": "wait_for",]
  "controller": "document",
  "requestId": "<unique request identifier>",
  "result": [
    "<documentId>",
    "<anotherDocumentId>",
    ...
  ]
}

Deletes documents in the persistent data storage.

Returns a partial error (with status 206) if one or more document can not be deleted.

Elastisearch 5.x and above only: The optional parameter refresh can be used with the value wait_for in order to wait for the document indexation (indexed documents are available for search).

mGet

URL: http://kuzzle:7512/<index>/<collection>/_mGet Method: POST Body:

{
  "ids": ["<documentId>", "<anotherDocumentId>", ...]
}

Query

{
  "index": "<index>",
  "collection": "<collection>",
  "controller": "document",
  "action": "mGet",
  "body": {
    "ids": ["<documentId>", "<anotherDocumentId>", ...]
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<index>",
  "collection": "<collection>",
  "action": "mGet",
  "controller": "document",
  "requestId": "<unique request identifier>",
  "result": {
    "hits": [
      {
        "_id": "<documentId>",
        "_index": "<index>",
        "_source": {
          "_kuzzle_info": {
            "active": true,
            "author": "-1",
            "createdAt": 1484226562795,
            "deletedAt": null,
            "updatedAt": null,
            "updater": null
          },
          "some": "body"
        },
        "_type": "<collection>",
        "_version": 4,
        "found": true
      },
      {
        "_id": "<anotherDocumentId>",
        "_index": "<index>",
        "_source": {
          "_kuzzle_info": {
            "active": true,
            "author": "-1",
            "createdAt": 1484226562795,
            "deletedAt": null,
            "updatedAt": null,
            "updater": null
          },
          "some": "body"
        },
        "_type": "<collection>",
        "_version": 4,
        "found": true
      }
      {
        // Other documents
      }
    ],
    "total": <number of retrieved documents>
  }
}

Given document ids, retrieves the corresponding documents from the database.

Only documents in the persistent data storage layer can be retrieved.

mReplace

URL: http://kuzzle:7512/<index>/<collection>/_mReplace[?refresh=wait_for] Method: PUT Body:

{
  "documents": [
    {
      "_id": "<documentId>",              // Mandatory
      "body": {
        "document": "body",
        ...
      }
    },
    {
      "_id": "<anotherDocumentId>"        // Mandatory
      "body": {
        "document": "body",
        ...
      }
    },
    ...
  ]
}

Query

{
  "index": "<index>",
  "collection": "<collection>",
  "controller": "document",
  "action": "mReplace",
  ["refresh": "wait_for",]
  "body": {
    "documents": [
      {
        "_id": "<documentId>",
        "body": {
          "document": "body",
          ...
        }
      },
      {
        "_id": "<anotherDocumentId>",
        "body": {
          "document": "body",
          ...
        }
      },
      ...
    ]
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<index>",
  "collection": "<collection>",
  "action": "mReplace",
  "controller": "document",
  "requestId": "<unique request identifier>",
  "result": {
    "hits": [
      {
        "_id": "<documentId>",
        "_index": "<index>",
        "_shards": {
          "failed": 0,
          "successful": 1,
          "total": 2
        },
        "_source": {
          "_kuzzle_info": {
            "active": true,
            "author": "-1",
            "createdAt": 1484226104822,
            "deletedAt": null,
            "updatedAt": null,
            "updater": null
          },
          "document": "body"
        },
        "_type": "<collection>",
        "_version": 2,
        "created": false,
        "result": "updated"
      },
      {
        "_id": "<anotherDocumentId>",
        "_index": "<index>",
        "_shards": {
          "failed": 0,
          "successful": 1,
          "total": 2
        },
        "_source": {
          "_kuzzle_info": {
            "active": true,
            "author": "-1",
            "createdAt": 1484226104822,
            "deletedAt": null,
            "updatedAt": null,
            "updater": null
          },
          "document": "body"
        },
        "_type": "<collection>",
        "_version": 2,
        "created": false,
        "result": "updated"
      },
      {
        // Other replaced documents
      }
    ],
    "total": <number of replaced documents>
  }
}

Replaces documents in the persistent data storage.

Returns a partial error (with status 206) if one or more documents can not be replaced.

Elastisearch 5.x and above only: The optional parameter refresh can be used with the value wait_for in order to wait for the document indexation (indexed documents are available for search).

mUpdate

URL: http://kuzzle:7512/<index>/<collection>/_mUpdate[?refresh=wait_for] Method: PUT Body:

{
  "documents": [
    {
      "_id": "<documentId>",              // Mandatory
      "body": {
        "partial": "body",
        ...
      }
    },
    {
      "_id": "<anotherDocumentId>"        // Mandatory
      "body": {
        "partial": "body",
        ...
      }
    },
    ...
  ]
}

Query

{
  "index": "<index>",
  "collection": "<collection>",
  "controller": "document",
  "action": "mUpdate",
  "body": {
    "documents": [
      {
        "_id": "<documentId>",
        "body": {
          "partial": "body",
          ...
        }
      },
      {
        "_id": "<anotherDocumentId>",
        "body": {
          "partial": "body",
          ...
        }
      },
      ...
    ]
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<index>",
  "collection": "<collection>",
  "action": "mUpdate",
  ["refresh": "wait_for",]
  "controller": "document",
  "requestId": "<unique request identifier>",
  "result": {
    "hits": [
      {
        "_id": "<documentId>",
        "_index": "<index>",
        "_shards": {
          "failed": 0,
          "successful": 1,
          "total": 2
        },
        "_type": "<collection>",
        "_version": 2,
        "result": "updated"
      },
      {
        "_id": "<anotherDocumentId>",
        "_index": "<index>",
        "_shards": {
          "failed": 0,
          "successful": 1,
          "total": 2
        },
        "_type": "<collection>",
        "_version": 2,
        "result": "updated"
      },
      {
        // Other updated documents
      }
    ],
    "total": <number of updated documents>
  }
}

Updates documents in the persistent data storage.

Returns a partial error (with status 206) if one or more documents can not be updated.

Elastisearch 5.x and above only: The optional parameter refresh can be used with the value wait_for in order to wait for the document indexation (indexed documents are available for search).

update

URL: http://kuzzle:7512/<index>/<collection>/<documentId>/_update[?refresh=wait_for] Method: PUT Body:

{
  "field_to_update1": "new value",
  "field_to_update2": "new value",
  ...
}

Query

{
  "index": "<index>",
  "collection": "<collection>",
  "controller": "document",
  "action": "update",
  ["refresh": "wait_for",]
  // The document id you provided or that was generated at document creation.
  // it is also the one returned during a search query.
  "_id": "<documentId>"

  // The actual update query
  "body": {
    "field_to_update1": "new value",
    "field_to_update2": "new value",
    ...
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<index>",
  "collection": "<collection>",
  "controller": "document",
  "action": "update",
  "requestId": "<unique request identifier>",
  "result": {
    "_id": "<documentId>",
    "_version": <number>,             // The new version number of this document
    "created": false
  }
}

Only documents in the persistent data storage layer can be updated.

Elastisearch 5.x and above only: The optional parameter refresh can be used with the value wait_for in order to wait for the document indexation (indexed documents are available for search).

validate

URL: http://kuzzle:7512/<index>/<collection>/_validate Method: POST Body:

{
    // The message to send
}

Query

{
  index: "<index>",
  collection: "<collection>",
  controller: "document",
  action: "validate",
  // The document itself
  body: {
    ...
  }
}

Response

{
  status: 200,                      // Assuming everything went well
  error: null,                      // Assuming everything went well
  index: "<index>",
  collection: "<collection>",
  controller: "document",
  action: "validate",
  metadata: {},
  result: {
    errorMessages: {},              // There is no error messages
    valid: true                     // The document complies with validation specifications
  }  
}

Validates data against existing validation rules. The data is not published nor stored by Kuzzle If the document complies, the result.valid value is true, if not, it is false. When the document does not complies, both result.errorMessages contains some very detailed hints on what is wrong with the document. Note that if no validation specifications are set for the <data index>/<data collection>, the document always validate. In any ways, the document is not stored nor published.

~ index controller

create

URL: http://kuzzle:7512/<index> Method: POST

Query

{
  "index": "<index>",
  "controller": "index",
  "action": "create"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<index>",
  "action": "create",
  "controller": "index",
  "requestId": "<unique request identifier>",
  "result": {
    "acknowledged": true
  }
}

When creating a document or a collection, Kuzzle will automatically create a data index if needed. But in some cases, you may want to create an empty index directly, prior to storing any document in it.

Create an index in Kuzzle’s persistent storage layer.

delete

URL: http://kuzzle:7512/<index> Method: DELETE

Query

{
  "index": "<index>",
  "controller": "index",
  "action": "delete"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<index>",
  "controller": "index",
  "action": "delete",
  "requestId": "<unique request identifier>",
  "result": {
    "acknowledged": true
  }
}

Deletes an entire index from Kuzzle’s persistent storage layer.

exists

URL: http://kuzzle:7512/<index>/_exists Method: GET

Query

{
  "index": "<index>",
  "controller": "index",
  "action": "exists"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<index>",
  "controller": "index",
  "action": "exists",
  "requestId": "<unique request identifier>",
  "result": true
}

Checks if the given index exists in Kuzzle storage layer.

getAutoRefresh

URL: http://kuzzle:7512/<index>/_autoRefresh Method: GET

Query

{
  "index": "<index>",
  "controller": "index",
  "action": "getAutoRefresh"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "requestId": "<unique request identifier>",
  "index": "<index>",
  "controller": "index",
  "action": "getAutoRefresh",
  "result":  true|false             // The autoRefresh status for <index>
}

The autoRefresh flag, when set to true, will make Kuzzle perform a refresh request immediately after each write request, forcing the documents to be immediately visible to search.

The getAutoRefresh actions returns the current autoRefresh status for the given index.

list

URL: http://kuzzle:7512/_list Method: GET

Query

{
  "controller": "index",
  "action": "list"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "controller": "index",
  "action": "list",
  "requestId": "<unique request identifier>",
  "result": {
    "total": 13,
    "hits": [
      "index_1",
      "index_2",
      "index_...",
      "index_n"
    ]
  }
}

Returns the complete data indexes.

mDelete

URL: http://kuzzle:7512/_mDelete Method: DELETE Body:

indexes: [
  "index1",
  "index2",
  ...
}

Query

{
  "controller": "index",
  "action": "mDelete",
  "body": {
    "indexes": [
      "index1",
      "index2",
      ...
    }
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "action": "mDelete",
  "controller": "index",
  "requestId": "<unique request identifier>",
  "result": {  // list of actual deleted indexes
    "deleted":[
      "index1",
      "index2"
    ]
  }
}

Deletes all indexes specified in the body, that current user is allowed to delete, from Kuzzle’s persistent storage layer.

If no indexes is specified in the body, all the indexes that the current user is allowed to delete will be deleted.

That means: if Kuzzle contains indexes “index1”, “index2” and “index3”, but current user is only allowed to delete “index1” and “index2”, only both of them are deleted, and “index3” is kept in the persistent storage layer.

The response contains the list of indexes that were actually deleted.

refresh

URL: http://kuzzle:7512/<index>/_refresh Method: POST

Query

{
  "index": "<index>",
  "controller": "index",
  "action": "refresh"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<index>",
  "controller": "index",
  "action": "refresh",
  "requestId": "<unique request identifier>",
  "result": {
    "_shards": {
        "failed": 0,
        "succressful": 5,
        "total": 10
    }
  }
}

When writing or deleting documents in Kuzzle’s database layer, the update needs to be indexed before being reflected in the search index. By default, this operation can take up to 1 second.

Given an index, the refresh action forces a refresh, on it, making the documents visible to search immediately.

refreshInternal

URL: http://kuzzle:7512/_refreshInternal Method: POST

Query

{
  "controller": "index",
  "action": "refreshInternal"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "controller": "index",
  "action": "refreshInternal",
  "requestId": "<unique request identifier>",
  "result": {
    "acknowledged": true
  }
}

When writing or deleting security and internal documents (users, roles, profiles, configuration, etc.) in Kuzzle’s database layer, the update needs to be indexed before being reflected in the search index. By default, this operation can take up to 1 second.

Given an index, the refreshInternal action forces a refresh, on the internal index, making the documents visible to search immediately.

setAutoRefresh

URL: http://kuzzle:7512/<index>/_autoRefresh Method: POST

Query

{
  "autoRefresh": true|false
}
{
  "index": "<index>",
  "controller": "index",
  "action": "setAutoRefresh",
  "body": {
    "autoRefresh": true|false
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<index>",
  "controller": "index",
  "action": "setAutoRefresh",
  "requestId": "<unique request identifier>",
  "result": true|false                // The autoRefresh status set for the index
}

The autoRefresh flag, when set to true, will make Kuzzle perform a refresh request immediately after each write request, forcing the documents to be immediately visible to search.

Given an index, the setAutoRefresh action updates its autoRefresh status.

~ memoryStorage controller

Description

URL: http://kuzzle:7512/ms/_ping Method: GET

Query

{
  "action": "ping",
  "controller": "ms",
  "metadata": {},
  "requestId": "<unique request identifier>"
}

Response

{
  "status": 200,
  "error": null,
  "requestId": "<unique request identifier>",
  "controller": "ms",
  "action": "ping",
  "metadata": {},
  "result": "PONG"
}

Kuzzle’s memory storage is a separate data store from the database layer. It is internaly based on Redis. You can access most of Redis functions (all lowercased), except:

  • all cluster based functions
  • all script based functions
  • all cursors functions

Here is the list of non implemented commands:

client cluster config debug echo eval evalsha flushall migrate monitor move psubscribe pubsub punsubscribe quit readonly readwrite role script select shutdown slaveof slowlog subscribe sync unsubscribe scan sscan hscan zscan

You can find a list of all redis command at: http://redis.io/commands

~ realtime controller

count

Due to the synchronous nature of the HTTP protocol, real-time messaging is not supported.

Query

{
  "index": "<index>",
  "collection": "<collection>",
  "controller": "realtime",
  "action": "count",
  "body": {
    "roomId": "unique room ID"
  },
  "metadata": {
    // query metadata
  }
}

Response

{
  "status": 200,                        // Assuming everything went well
  "error": null,                        // Assuming everything went well
  "index": "<index>",
  "collection": "<collection>",
  "controller": "realtime",
  "action": "count",
  "requestId": "<unique request identifier>",
  "result": {
    "roomId": "<unique Kuzzle room identifier>",
    "count": <number of subscriptions>,
  }
}

Returns the number of people/applications who have subscribed to the same documents as you have.

The expected parameter is the roomId returned by Kuzzle during the subscription.

join

Due to the synchronous nature of the HTTP protocol, real-time messaging is not supported.

Query

{
  "index": "<index>",
  "collection": "<collection>",
  "controller": "realtime",
  "action": "join",
  "body": {
    "roomId": "<the room identifier to join>"
  },
  "metadata": {
    // query metadata
  },
  "scope": "<all|in|out|none>",
  "state": "<all|pending|done>",
  "users": "<all|in|out|none>"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<index>",
  "collection": "<collection>",
  "controller": "realtime",
  "action": "subscribe",
  "metadata": {},                     // subscription metadata
  "requestId": "<unique request identifier>",
  "result": {
    "roomId": "<unique Kuzzle room identifier>"
  }
}

Joins a previously created subscription.

The roomId parameter is returned by Kuzzle when subscribing to some documents.

list

URL: http://kuzzle:7512/_listSubscriptions Method: GET

Query

{
  "controller": "realtime",
  "action": "list"
}

Response

{
  "error": null,
  "status": 200,
  "index": "<index>",
  "collection": "<collection>",
  "controller": "realtime",
  "action": "publish",
  "metadata": {},
  "requestId": "<unique request identifier>",
  "result": {
    "<index>": {
      "<collection>": {
        "afcd909773f197ab859447594bfbd154": 12,
        "4adbc1948ac4dc84ac89d14b488bcad1": 4,
        ...
      },
      "<anotherCollection>": {
        "bcd4ab54cdb4ad5b464ba4cd4564dc46": 1,
        ...
      },
      ...
    },
    "<anotherIndex>": {
      ...
    },
    ...
  },
}

Lists all subscriptions on all indexes and all collections.

publish

URL: http://kuzzle:7512/<index>/<collection>/_publish Method: POST Body:

{
  // The message to send
}

Query

{
  "index": "<index>",
  "collection": "<collection>",
  "controller": "realtime",
  "action": "publish",
  // The document itself
  "body": {
    ...
  }
}

Response

{
  "error": null,
  "status": 200,
  "index": "<index>",
  "collection": "<collection>",
  "controller": "realtime",
  "action": "publish",
  "metadata": {},
  "requestId": "<unique request identifier>",
  "result": {}
}

Sends a real-time message to Kuzzle. The message will be dispatched to all the clients who have subscribed to a subscription for which the filters match the message content.

subscribe

Due to the synchronous nature of the HTTP protocol, real-time messaging is not supported.

Query

{
  "index": "<index>",
  "collection": "<collection>",
  "controller": "realtime",
  "action": "subscribe",
  "body": {
    // subscription filters
  },
  "metadata": {
    // query metadata
  },

  /*
   * The "scope" argument filters document modifications when a change has been
   * detected in the database.
   * You may receive notifications only when documents enter your
   * scope (scope: "in"), when documents leave it (scope: "out"), or
   * both (scope: "all")
   *
   * You may also filter out all these notifications (scope = "none")
   *
   * Default: scope: "all"
   */
  "scope": "<all|in|out|none>",

  /*
   * The "state" argument filters document notifications depending on their state.
   * This does not affect pub/sub messages or user events.
   *
   * You may choose to only receive document notifications when a change has
   * been detected in the database (state = "done"), when a document is
   * about to be changed (state: "pending"), or both (state: "all")
   *
   * Default: "done"
   */
  "state": "<all|pending|done>",

  /*
   * User events are notification sent when users enter or leave the room you
   * subscribed to.
   *
   * You may choose to receive notifications when users enter the
   * room (users: "in"), when they leave the room (users: "out"), or
   * both (users: "all")
   *
   * Default: "none"
   */
  "users": "<all|in|out|none>"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<index>",
  "collection": "<collection>",
  "controller": "realtime",
  "action": "subscribe",
  "metadata": {},                     // subscription metadata
  "requestId": "<unique request identifier>",
  "result": {
    "roomId": "<unique Kuzzle room identifier>",
    "channel": "<unique channel identifier>"
  }
}

Websocket

<script>
  var
    socket = new WebSocket("ws://localhost:7512"),
    channel;

  socket.onmessage = function (payload) {
    var response = JSON.parse(payload.data);

    if (response.room === "mySubscription") {
      channel = response.result.channel;
    }

    if (response.room === channel) {
      console.log("Received a notification: ", response);

      /*
      {
        "status": 200,
        "error": null,
        "index": "index",
        "collection":"collection",
        "controller": "realtime",
        "action": "publish",
        "state": "done",
        "scope": "in",
        "requestId": "<unique request identifier>",
        "result":{
          "roomId":"632682a9eac95cfb95e3a697b29b7739",
          "requestId":"mySubscription",
          "timestamp":1449564937142
        }
      }
      */
    }
  };

  socket.onopen = function () {
    socket.send(JSON.stringify({
      "requestId": "mySubscription",
      "index": "index",
      "collection": "collection",
      "controller": "realtime",
      "action": "subscribe",
      "body": {}
    }));
  };
</script>

Socket.io

/*
  Using socket.io
 */
<script src="https://cdn.socket.io/socket.io-1.4.5.js"></script>
<script>
    var socket = io("http://localhost:7512");

    socket.once("mySubscription", function (response) {
      console.log(response);

      /*
      {
        "error": null,
        "status": 200,
        "index": "<index>",
        "collection": "<collection>"
        "controller": "realtime",
        "action": "subscribe",
        "state": "done",
        "metadata": {},
        "result": {
          "roomId": "632682a9eac95cfb95e3a697b29b7739",
          "requestId": "mySubscription",
          "timestamp": 1449564937142
        }
      }
      */
    });

    socket.emit("kuzzle", {
      "requestId": "mySubscription",
      "index": "index",
      "collection": "collection",
      "controller": "realtime",
      "action": "subscribe",
      "body": {}
    });
</script>

Subscription works differently in Kuzzle than with a regular publish/subscribe protocol. In Kuzzle, you don’t exactly subscribe to a room or to a topic but, instead, you subscribe to documents.

What it means is that, along with your subscription query, you also give to Kuzzle a set of document or message filters. Of course, you may also subscribe to a data collection with no other matching criteria, and you’ll effectively listen to a “topic”.

Once you have subscribed to a room, depending on your filters, you may receive the following notifications:

  • whenever a pub/sub message is published matching your criteria (realtime)
  • whenever a matching document is about to be created or deleted (realtime)
  • whenever a matching stored document is created, updated or deleted (once the change is effective in the database)
  • whenever a user enters or leaves the room

Good news is, you may ask Kuzzle to send only the notifications relevant to your application, by configuring your subscription request (see below). You can also subscribe multiple times to the same room, with different configurations. Kuzzle will provide you with a channel for each of these subscriptions, allowing different part of your application to concentrate on what it needs to process.

The matching criteria you pass on to Kuzzle are based upon Kuzzle DSL

How subscription works:

  • => You send a subscription query to Kuzzle
  • <= Kuzzle responds to you with a roomId and a channel
  • => You listen to the channel provided in the response
  • <= Kuzzle forwards the corresponding notifications on that channel

unsubscribe

Due to the synchronous nature of the HTTP protocol, real-time messaging is not supported.

Query

{
  "index": "<data index>",
  "collection": "<data collection>",
  "controller": "realtime",
  "action": "unsubscribe",

  "body": {
    "roomId": "<unique room ID>"
  },
  "metadata": {
    // query metadata
  }
}

Response

{
  "status": 200,                        // Assuming everything went well
  "error": null,                        // Assuming everything went well
  "index": "<data index>",
  "collection": "<data collection>",
  "controller": "realtime",
  "action": "unsubscribe",
  "metadata": {},                       // subscription metadata
  "requestId": "<unique request identifier>",
  "result": {
    "roomId": "<unique Kuzzle room identifier>"
  }
}

Instructs Kuzzle to detach you from its subscribers for the given room. In practice, your subscription won’t receive any new message on the room once this action is triggered.

The expected parameter is the roomId that Kuzzle returned during the subscription.

validate

URL: http://kuzzle:7512/<index>/<collection>/_validate Method: POST Body:

{
    // The message to send
}

Query

{
  index: "<index>",
  collection: "<collection>",
  controller: "realtime",
  action: "validate",
  // The document itself
  body: {
    ...
  }
}

Response

{
  status: 200,                      // Assuming everything went well
  error: null,                      // Assuming everything went well
  index: "<index>",
  collection: "<collection>",
  controller: "realtime",
  action: "validate",
  metadata: {},
  result: {
    errorMessages: {},              // There is no error messages
    valid: true                     // The document complies with validation specifications
  }  
}

Validates data against existing validation rules. The data is not published nor stored by Kuzzle If the document complies, the result.valid value is true, if not, it is false. When the document does not complies, both result.errorMessages contains some very detailed hints on what is wrong with the document. Note that if no validation specifications are set for the <data index>/<data collection>, the document always validate. In any ways, the document is not stored nor published.

~ security controller

createFirstAdmin

URL: http://kuzzle:7512/<userId>/_createFirstAdmin[?reset=1] or http://kuzzle:7512/_createFirstAdmin[?reset=1] Method: POST Body

{
  "name": "John Doe",                     // Additional optional User properties
  ...
}

// example with a "local" authentication

{
  "name": "John Doe",                     // Additional optional User properties
  ...
  "password": "MyPassword"                // ie: Mandatory for "local" authentication plugin
}

Query

{
  "controller": "security",
  "action": "createFirstAdmin",
  "reset": true|false,                    // Optional. Will reset the preset roles if set to true.
  "_id": "<userId>",                      // Optional. If not provided, will be generated automatically.

  "body": {
    "profileIds": ["<profileId>"],       // Mandatory. The profile ids for the user
    "name": "John Doe",                   // Additional optional User properties
    ...
  }
}

// example with a "local" authentication

{
  "controller": "security",
  "action": "createFirstAdmin",
  "reset": true|false,                    // Optional. Will reset the preset roles if set to true.
  "_id": "<userId>",                      // Optional. If not provided, will be generated automatically.

  "body": {
    "profileIds": ["<profileId>"],        // Mandatory. The profile ids for the user
    "name": "John Doe",                   // Additional optional User properties
    ...
    "password": "MyPassword"              // ie: Mandatory for "local" authentication plugin
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "controller": "security",
  "action": "createFirstAdmin",
  "metadata": {},
  "requestId": "<unique request identifier>",
  "result": {
    "_id": "<user id, either provided or auto-generated>",
    "_source": {
      "name": "John Doe",
      "profileIds": [
        "admin"
      ],
      ...
    }
  }
}

Creates the first admin user in Kuzzle’s database layer. Does nothing if an admin user already exists.

If an _id is provided in the query and if a user already exists with the given _id, it will be replaced and its profileIds will be set to ["admin"]. If not provided, the _id will be auto-generated.

If the optional field reset is set to true (1 with http), the preset roles (anonymous and default) will be reset with more restrictive rights.

Other mandatory additional information are needed depending on the authentication plugins installed you want to use.

createOrReplaceProfile

URL: http://kuzzle:7512/profiles/<profileId> Method: PUT Body

{
  // The new array of role IDs and restrictions (cannot be empty)
  "roles": [
    {
      "_id": "<roleId>"
    },
    {
      "_id": "<anotherRoleId>",
      "restrictedTo": [
        {
          "index": "<index>"
        },
        {
          "index": "<index>",
          "collections": [
            "<coll1>",
            "<coll2>"
          ]
        }
      ]
    },
    ...
  ]
}

Query

{
  "controller": "security",
  "action": "createOrReplaceProfile",
  "_id": "<profileId>",

  // the profile definition
  "body": {
    // The new array of role IDs and restrictions (cannot be empty)
    "roles": [
      {
        "_id": "<roleId>"
      },
      {
        "_id": "<roleId>",
        "restrictedTo": [
          {
            "index": "<index>"
          },
          {
            "index": "<index>",
            "collections": [
              "<coll1>",
              "<coll2>"
            ]
          }
        ]
      },
      ...
    ]
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "result": {
    "_id": "<profileId>",
    "_index": "%kuzzle",
    "_type": "profiles",
    "_version": 1,
    "created": false,
  },
  "requestId": "<unique request identifier>",
  "controller": "security",
  "action": "createOrReplaceProfile",
  "metadata": {}
}

Creates (if no _id provided) or updates (if _id matches an existing one) a profile with a new list of roles.

createOrReplaceRole

URL: http://kuzzle:7512/roles/<roleId> Method: PUT Body

{
  "controllers": {
    "*": {
      "actions": {
        "*": true
      }
    }
  }
}

Query

{
  "controller": "security",
  "action": "createOrReplaceRole",
  "_id": "<roleId>",

  // the role definition
  "body": {
    "controllers": {
      "*": {
        "actions": {
          "*": true
        }
      }
    }
  }
}

Response

{
  "status": 200,                     // Assuming everything went well
  "error": null,                     // Assuming everything went well
  "result": {
    "_id": "<roleId>",
    "_index": "%kuzzle",
    "_type": "roles",
    "_version": 1,
    "created": true,
    "_source": { // your role definition
      "controllers": {
        "*": {
          "actions": {
            "*": true
          }
        }
      }
    }
  }
  "requestId": "<unique request identifier>",
  "controller": "security",
  "action": "createOrReplaceRole",
  "metadata": {},
}

Validates and stores a role in Kuzzle’s persistent data storage.

The body content needs to match Kuzzle’s role definition. To get some more detailed information on the expected role definition, please refer to Kuzzle’s role reference definition documentation.

To get some more detailed information about Kuzzle’s user management model, please refer to Kuzzle’s security documentation.

createOrReplaceUser

URL: http://kuzzle:7512/users/<userId> Method: PUT Body

{
  "profileIds": ["<profileId>", "anotherProfileId", "..."] // Mandatory. The profile ids for the user
  "name": "John Doe",                                      // Additional optional User properties
  ...
}

Query

{
  "controller": "security",
  "action": "createOrReplaceUser",
  "_id": "<userId>",
  "body": {
    "profileIds": ["<profileId>", "anotherProfileId", "..."] // Mandatory. The profile ids for the user
    "name": "John Doe",                                      // Additional optional User properties
    ...
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "%kuzzle",
  "collection": "users",
  "controller": "security",
  "action": "createOrReplaceUser",
  "metadata": {},
  "requestId": "<unique request identifier>",
  "result": {
    "_id": "<userId>",
    "_index": "%kuzzle",
    "_source": {
      "profileIds": ["<profileId>", "anotherProfileId", "..."],
      "name": "John Doe",
      ...
    },
    "_type": "users",
    "_version": 1,
    "created": true
  }
}

Persists a user object to Kuzzle’s database layer.

The user is created if it does not exists yet or replaced with the given object if it does.

createProfile

URL: http://kuzzle:7512/profiles/<profileId>/_create Method: POST Body

{
  // The new array of role IDs and restrictions (cannot be empty)
  "policies": [
    {
      "_id": "<roleId>"
    },
    {
      "_id": "<roleId>",
      "restrictedTo": [
        {
          "index": "<index>"
        },
        {
          "index": "<index>",
          "collections": [
            "<coll1>",
            "<coll2>"
          ]
        }
      ]
    },
    ...
  ]
}

Query

{
  "controller": "security",
  "action": "createProfile",
  "_id": "<profileId>",

  // the profile definition
  "body": {
    // The new array of role IDs and restrictions (cannot be empty)
    "policies": [
      {
        "_id": "<roleId>"
      },
      {
        "_id": "<roleId>",
        "restrictedTo": [
          {
            "index": "<index>"
          },
          {
            "index": "<index>",
            "collections": [
              "<coll1>",
              "<coll2>"
            ]
          }
        ]
      },
      ...
    ]
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "result": {
    "_id": "<profileId>",
    "_index": "%kuzzle",
    "_type": "profiles",
    "_version": 1,
    "created": true,
    "_source": {} // your profile definition
  },
  "requestId": "<unique request identifier>",
  "controller": "security",
  "action": "createProfile",
  "metadata": {},
}

Creates a profile with a new list of roles.

Note: The _id parameter is mandatory.

createRole

URL: http://kuzzle:7512/roles/<roleId>/_create Method: POST Body

{
  "controllers": {
    "*": {
      "actions": {
        "*": true
      }
    }
  }
}

Query

{
  "controller": "security",
  "action": "createRole",
  "_id": "<roleId>",

  // the role definition
  "body": {
    "controllers": {
      "*": {
        "actions": {
          "*": true
        }
      }
    }
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "result": {
    "_id": "<roleId>",
    "_index": "%kuzzle",
    "_type": "roles",
    "_version": 1,
    "created": true,
    "_source": { // your role definition
      "controllers": {
        "*": {
          "actions": {
            "*": true
          }
        }
      }
    }
  }
  "requestId": "<unique request identifier>",
  "controller": "security",
  "action": "createRole",
  "metadata": {},
}

Validates and stores a role in Kuzzle’s persistent data storage. Note: The _id parameter is mandatory.

The body content needs to match Kuzzle’s role definition. To get some more detailed information on the expected role definition, please refer to Kuzzle’s role reference definition documentation.

To get some more detailed information about Kuzzle’s user management model, please refer to Kuzzle’s security documentation.

createUser

URL: http://kuzzle:7512/users/<userId>/_create or http://kuzzle:7512/users/_create Method: POST Body

{
  "profileIds": ["<profileId>"],          // Mandatory. The profile ids for the user
  "name": "John Doe",                     // Additional optional User properties
  ...
}

// example with a "local" authentication

{
  "profileIds": ["<profileId>"],          // Mandatory. The profile ids for the user
  "name": "John Doe",                     // Additional optional User properties
  ...
  "password": "MyPassword"                // ie: Mandatory for "local" authentication plugin
}

Query

{
  "controller": "security",
  "action": "createUser",
  "_id": "<userId>",                      // Optional. If not provided, will be generated automatically.

  "body": {
    "profileIds": ["<profileId>"],        // Mandatory. The profile ids for the user
    "name": "John Doe",                   // Additional optional User properties
    ...
  }
}

// example with a "local" authentication

{
  "controller": "security",
  "action": "createUser",
  "_id": "<userId>",                      // Optional. If not provided, will be generated automatically.

  "body": {
    "profileIds": ["<profileId>"],        // Mandatory. The profile ids for the user
    "name": "John Doe",                   // Additional optional User properties
    ...
    "password": "MyPassword"              // ie: Mandatory for "local" authentication plugin
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "%kuzzle",
  "collection": "users",
  "controller": "security",
  "action": "createUser",
  "metadata": {},
  "requestId": "<unique request identifier>",
  "result": {
    "_id": "<user id, either provided or auto-generated>",
    "_index": "%kuzzle",
    "_source": {
      "profileIds": ["<profileId>"],
      "name": "John Doe",
      ...
    },
    "_type": "users",
    "_version": 1,
    "created": true
  }
}

Creates a new user in Kuzzle’s database layer.

If an _id is provided in the query and if a user already exists with the given _id, an error is returned. If not provided, the _id will be auto-generated.

Provided profile ids are used to set the permissions of the user.

Other mandatory additional information are needed depending on the authentication plugins installed you want to use.

createRestrictedUser

URL: http://kuzzle:7512/users/<userId>/_createRestricted or http://kuzzle:7512/users/_createRestricted Method: POST Body

{
  "name": "John Doe",                     // Additional optional User properties
  ...
}

// example with a "local" authentication

{
  "name": "John Doe",                     // Additional optional User properties
  ...
  "password": "MyPassword"                // ie: Mandatory for "local" authentication plugin
}

Query

{
  "controller": "security",
  "action": "createRestrictedUser",
  "_id": "<userId>",                      // Optional. If not provided, will be generated automatically.
  "body": {
    "name": "John Doe",                   // Additional optional User properties
    ...
  }
}

// example with a "local" authentication

{
  "controller": "security",
  "action": "createRestrictedUser",
  "_id": "<userId>",                      // Optional. If not provided, will be generated automatically.
  "body": {
    "name": "John Doe",                   // Additional optional User properties
    ...
    "password": "MyPassword"              // ie: Mandatory for "local" authentication plugin
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "%kuzzle",
  "collection": "users",
  "controller": "security",
  "action": "createRestrictedUser",
  "metadata": {},
  "requestId": "<unique request identifier>",
  "result": {
    "_id": "<userId>",
    "_index": "%kuzzle",
    "_source": {
      "profileIds": ["<profileId>"],
      "name": "John Doe",
      ...
    },
    "_type": "users",
    "_version": 1,
    "created": true
  }
}

Creates a new user in Kuzzle’s database layer.

If an _id is provided in the query and if a user already exists with the given _id, an error is returned. If not provided, the _id will be auto-generated.

Profile ids are set accordingly to the Kuzzle configuration. This route is especially useful to allow anonymous users to create a user.

Other mandatory additional information are needed depending on the authentication plugins installed you want to use.

deleteProfile

URL: http://kuzzle:7512/_profiles/<profileId> Method: DELETE

Query

{
  "controller": "security",
  "action": "deleteProfile",

  // The profile unique identifier. It's the same one that Kuzzle sends you
  // in its responses when you create a profile.
  "_id": "<profileId>"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "result": {
    "_id": "<profileId>",             // The profile id
  },
  "index": "%kuzzle",
  "collection": "profiles",
  "action": "deleteProfile",
  "controller": "security",
  "requestId": "<unique request identifier>"
}

Given a profile id, deletes the corresponding profile from the database. Note that the related roles will NOT be deleted.

deleteRole

URL: http://kuzzle:7512/roles/<roleId> Method: DELETE

Query

{
  "controller": "security",
  "action": "deleteRole",

  // The role unique identifier. It's the same one that Kuzzle sends you
  // in its responses when you create a role.
  "_id": "<roleId>"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "result": {
    "_id": "<roleId>"                 // The role id
  }
  "index": "%kuzzle",
  "collection": "roles"
  "action": "deleteRole",
  "controller": "security",
  "requestId": "<unique request identifier>"
}

Given a role id, deletes the corresponding role from the database.

deleteUser

URL: http://kuzzle:7512/users/<userId> Method: DELETE

Query

{
  "controller": "security",
  "action": "deleteUser",

  // The role unique identifier. It's the same one that Kuzzle sends you
  // in its responses when you create a role.
  "_id": "<roleId>"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "result": {
    "_id": "<roleId>"                 // The role id
  }
  "index": "%kuzzle",
  "collection": "users",
  "action": "deleteUser",
  "controller": "security",
  "requestId": "<unique request identifier>"
}

Given a user id, deletes the corresponding user from Kuzzle’s database layer.

getProfile

URL: http://kuzzle:7512/_profiles/<profileId> Method: GET

Query

{
  "controller": "security",
  "action": "getProfile",

  // The profile unique identifier. It's the same one that Kuzzle sends you
  // in its responses when you create a profile.
  "_id": "<profileId>"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "result": {
    "_id": "<profileId>",             // The profile id
    "_source": {                      // The requested profile
      ...
    },
    "index": "%kuzzle",
    "collection": "profiles"
    "action": "getProfile",
    "controller": "security",
    "requestId": "<unique request identifier>"
  }
}

Given a profile id, retrieves the corresponding profile from the database.

getProfileMapping

URL: http://kuzzle:7512/profiles/_mapping Method: GET

Query

{
  "controller": "security",
  "action": "getProfileMapping"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "controller": "security",
  "action": "getProfileMapping",
  "requestId": "<unique request identifier>",
  "result": {
    "mapping": {
      "policies": {
        "properties": {
          "_id": {
            "type": "keyword"
          },
          "allowInternalIndex": {
            "type": "boolean"
          },
          "restrictedTo": {
            "properties": {
              "collections": {
                "type": "text",
                "fields": {
                  "keyword": {
                    "type": "keyword",
                    "ignore_above": 256
                  }
                }
              },
              "index": {
                "type": "text",
                "fields": {
                  "keyword": {
                    "type": "keyword",
                    "ignore_above": 256
                  }
                }
              }
            }
          },
          "roleId": {
            "type": "text",
            "fields": {
              "keyword": {
                "type": "keyword",
                "ignore_above": 256
              }
            }
          }
        }
      }
    }
  }
}

Gets the mapping of the internal profiles collection.

getProfileRights

URL: http://kuzzle:7512/_profiles/<profileId>/_rights Method: GET

Query

{
  "controller": "security",
  "action": "getProfileRights",

  // The profile unique identifier. It's the same one that Kuzzle sends you
  // in its responses when you create a profile.
  "_id": "<profileId>"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "result": {
    // An array of objects containing the profile rights
    "hits": [
      {
        "controller": "<ctrl_name|*>",
        "action": "<action_name|*>",
        "index": "<index_name|*>",
        "collection": "<collection_name|*>",
        "value": "<allowed|denied|conditional>"
      },
      {
        // Another rights item... and so on
      }
    ],
}

Given a profile id, retrieves the corresponding rights.

getRole

URL: http://kuzzle:7512/roles/<role id> Method: GET

Query

{
  "controller": "security",
  "action": "getRole",

  // The role unique identifier. It's the same one that Kuzzle sends you
  // in its responses when you create a role.
  "_id": "<roleId>"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "result": {
    "_id": "<roleId>",                // The role id
    "_source": {
      "indexes": {
        ...
      }
    }
  },
  "index": "%kuzzle",
  "collection": "roles"
  "action": "getRole",
  "controller": "security",
  "metadata": {},
  "requestId": "<unique request identifier>"
}

Given a role id, retrieves the corresponding role from the database.

getRoleMapping

URL: http://kuzzle:7512/roles/_mapping Method: GET

Query

{
  "controller": "security",
  "action": "getRoleMapping"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "controller": "security",
  "action": "getRoleMapping",
  "requestId": "<unique request identifier>",
  "result": {
    "mapping": {
      "controllers": {
        "type": "object",
        "enabled": false
      }
    }
  }
}

Gets the mapping of the internal roles collection.

getUser

URL: http://kuzzle:7512/users/<userId> Method: GET

Query

{
  "controller": "security",
  "action": "getUser",
  "_id": "<userId>"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<index>",
  "collection": "<collection>",
  "controller": "security",
  "action": "getUser",
  "requestId": "<unique request identifier>",
  "result": {
    "_id": "<userId>",
    "_source": {
      "profileId": "<profileId>",
      ...                             // The user object content
    }
  }
}

Given a user id, gets the matching user from Kuzzle’s dabatase layer.

getUserMapping

URL: http://kuzzle:7512/users/_mapping Method: GET

Query

{
  "controller": "security",
  "action": "getUserMapping"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "controller": "security",
  "action": "getUserMapping",
  "requestId": "<unique request identifier>",
  "result": {
    "mapping": {
      "hobby": {
        "fields": {
          "keyword": {
            "ignore_above": 256,
            "type": "keyword"
          }
        },
        "type": "text"
      },
      "name": {
        "properties": {
          "first": {
            "fields": {
              "keyword": {
                "ignore_above": 256,
                "type": "keyword"
              }
            },
            "type": "text"
          },
          "last": {
            "fields": {
              "keyword": {
                "ignore_above": 256,
                "type": "keyword"
              }
            },
            "type": "text"
          },
          "real": {
            "fields": {
              "keyword": {
                "ignore_above": 256,
                "type": "keyword"
              }
            },
            "type": "text"
          }
        }
      },
      "password": {
        "index": false,
        "type": "keyword"
      },
      "profileIds": {
        "type": "keyword"
      }
    }
  }
}

Gets the mapping of the internal users collection.

getUserRights

URL: http://kuzzle:7512/_users/<userId>/_rights Method: GET

Query

{
  "controller": "security",
  "action": "getUserRights",
  "_id": "<userId>"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "result": {
    // An array of objects containing the user rights
    "hits": [
      {
        "controller": "<ctrl_name|*>",
        "action": "<action_name|*>",
        "index": "<index_name|*>",
        "collection": "<collection_name|*>",
        "value": "<allowed|denied|conditional>"
      },
      {
        // Another rights item... and so on
      }
    ],
}

Given a user id, gets the matching user’s rights from Kuzzle’s dabatase layer.

mDeleteProfile

URL: http://kuzzle:7512/profiles/_mDelete Method: POST Body:

{
  // ids must be an array of profile ids
  "ids": ["myFirstProfile", "mySecondProfile"]
}

Query

{
  "controller": "security",
  "action": "mDeleteProfile",
  "body": {
    // ids must be an array of profile ids
    "ids": ["myFirstProfile", "mySecondProfile"]
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "action": "mDeleteProfile",
  "controller": "security",
  "requestId": "<unique request identifier>",
  "result": [
    "myFirstProfile",
    "mySecondProfile"
  ]
}

Deletes a list of profile objects from Kuzzle’s database layer given a list of profile ids.

mDeleteRole

URL: http://kuzzle:7512/roles/_mDelete Method: POST Body:

{
  // ids must be an array of profile ids
  "ids": ["myFirstRole", "mySecondRole"]
}

Query

{
  "controller": "security",
  "action": "mDeleteRole",
  "body": {
    // ids must be an array of profile ids
    "ids": ["myFirstRole", "mySecondRole"]
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "action": "mDeleteRole",
  "controller": "security",
  "requestId": "<unique request identifier>",
  "result": [
    "myFirstRole",
    "mySecondRole"
  ]
}

Deletes a list of roles objects from Kuzzle’s database layer given a list of role ids.

mDeleteUser

URL: http://kuzzle:7512/users/_mDelete Method: POST Body:

{
  // ids must be an array of profile ids
  "ids": ["myFirstUserId", "mySecondUserId"]
}

Query

{
  "controller": "security",
  "action": "mDeleteRole",
  "body": {
    // ids must be an array of profile ids
    "ids": ["myFirstUserId", "mySecondUserId"]
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "action": "mDeleteRole",
  "controller": "security",
  "requestId": "<unique request identifier>",
  "result": [
    "myFirstUserId",
    "mySecondUserId"
   ]
  }
}

Deletes a list of users objects from Kuzzle’s database layer given a list of user ids.

mGetProfiles

URL: http://kuzzle:7512/profiles/_mGet Method: POST Body:

{
  // ids must be an array of profile ids
  "ids": ["myFirstProfile", "MySecondProfile"]
}

Query

{
  "controller": "security",
  "action": "mGetProfiles",
  "body": {
    // ids must be an array of profile ids
    "ids": ["myFirstProfile", "MySecondProfile"]
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "%kuzzle",
  "collection": "profiles"
  "action": "mGetProfiles",
  "controller": "security",
  "requestId": "<unique request identifier>",
  "result": {
    "_source": {
      ...
    }
  }
}

Retrieves a list of profile objects from Kuzzle’s database layer given a list of profile ids.

mGetRoles

URL: http://kuzzle:7512/roles/_mGet Method: POST Body:

{
  // ids must be an array of role id
  "ids": ["myFirstRole", "MySecondRole"]
}

Query

{
  "controller": "security",
  "action": "mGetRoles",
  "body": {
    // ids must be an array of role id
    "ids": ["myFirstRole", "MySecondRole"]
  }
}

Response

{
  "action": "mGetRoles",
  "collection": "roles",
  "controller": "security",
  "error": null,
  "index": "%kuzzle",
  "metadata": {},
  "requestId": "<unique request identifier>",
  "result":
  {
     "_shards": {
       "failed": 0,
       "successful": 5,
       "total": 5
     },
     "hits": [
       {
         "_id": "test",
         "_index": "%kuzzle",
         "_score": 1,
         "_source": {
           "_id": "test",
           "indexes": {} // Rights for each indexes, controllers, ... can be found here
         },
         "_type": "roles"
       }
     ],
     "max_score": null,
     "timed_out": false,
     "took": 1,
     "total": 1
  },
  "status": 200
}

Retrieves a list of role objects from Kuzzle’s database layer given a list of role ids.

searchProfiles

URL: http://kuzzle:7512/profiles/_search[?from=0][&size=42] Method: POST Body

{
  // A roles array containing a list of role IDs can be added
  "policies":  [
    "myrole",
    "admin"
  ],
}

Query

{
  "controller": "security",
  "action": "searchProfiles",
  "body": {
    // A roles array containing a list of role IDs can be added
    "policies":  [
      "myrole",
      "admin"
    ]
  },
  // filter can handle pagination using the from and size properties
  "from": 0,
  "size": 42
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "result":
  {
    "_shards": {
      "failed": 0,
      "successful": 5,
      "total": 5
    },
    "hits": [
      {
        "_id": "my-profile-1",
        "_source": {
          "policies": [
            "_id": "myroleId"
          ]
        }
      },
      {
        "_id": "my-profile-2",
        "_source": {
          "policies": [
            "_id": "myroleId"
          ]
        }
      }
    ],
    "max_score": 1,
    "timed_out": false,
    "took": 1,
    "total": 2
    },
    "index": "%kuzzle",
    "collection": "profiles"
    "action": "searchProfiles",
    "controller": "security",
    "requestId": "<unique request identifier>"
  }
}

Retrieves profiles referring to a given set of roles in their policies.

Attribute policies in body is optional.

The from and size arguments allow pagination.

Available filters:

Filter Type Description Default
policies array Contains an array policies with a list of role ids undefined

searchRoles

URL: http://kuzzle:7512/roles/_search[?from=0][&size=42] Method: POST Body:

{
  // indexes must be an array of index
  "indexes": ["myindex"]
}

Query

{
  "controller": "security",
  "action": "searchRoles",
  "body": {
    "indexes": ["myindex"],
    // "from" and "size" argument for pagination
    "from": 0,
    "size": 10
  }
}

Response

{
  "action": "searchRoles",
  "collection": "roles",
  "controller": "security",
  "error": null,
  "index": ""%kuzzle",
  "metadata": {},
  "requestId": "<unique request identifier>",
  "result":
  {
     "_shards": {
       "failed": 0,
       "successful": 5,
       "total": 5
     },
     "hits": [
       {
         "_id": "test",
         "_index": "%kuzzle",
         "_score": 1,
         "_source": {
           "_id": "test",
           "indexes": {} // Rights for each indexes, controllers, ... can be found here
         },
         "_type": "roles"
       }
     ],
     "max_score": null,
     "timed_out": false,
     "took": 1,
     "total": 1
  },
  "status": 200
}

Retrieves all roles with rights defined for given indexes.

Attribute indexes in body is optional.

The from and size arguments allow pagination.

Available filters:

Filter Type Description Default
indexes array List of indexes id related to the searched role undefined

searchUsers

URL: http://kuzzle:7512/users/_search[?from=0][&size=42] Method: POST Body

{
  "filter": {
    "and": [
      {
        "in": {
          "profileId": ["anonymous", "default"],
        }
      },
      {
        "geo_distance": {
          "distance": "10km",
          "pos": {
            "lat": "48.8566140",
            "lon": "2.352222"
          }
        }
      }
    ]
  }
}

Query

{
  "controller": "security",
  "action": "searchUsers",
  "body": {
    "filter": { // If empty or missing, Kuzzle will return all users.
      "and": [
        {
          "in": {
            "profileId": [
              "anonymous",
              "default"
            ],
          }
        },
        {
          "geo_distance": {
            "distance": "10km",
            "pos": {
              "lat": "48.8566140",
              "lon": "2.352222"
            }
          }
        }
      ]
    }
  },
  // "from" and "size" argument for pagination
  "from": 0,
  "size": 10
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "%kuzzle",
  "collection": "users",
  "action": "search",
  "controller": "security",
  "requestId": "<unique request identifier>",
  "result": {
    "total": <total number of users matching the filter>,
    // An array of user objects
    "hits": [
      {
        "_id": "<userId>",
        "_source": { ... }             // The user object content
      },
      {
        ...
      }
    ]
  }
}

Retrieves all the users matching the given filter.

The from and size arguments allow pagination.

updateProfile

URL: http://kuzzle:7512/profiles/<profile id>/_update Method: PUT Body

{
    "policies": [
      {
        "_id": "<roleId>"
      },
      {
        "_id": "<roleId>",
        "restrictedTo": [
          {
            "index": "<index>"
          },
          {
            "index": "<index>",
            "collections": [
              "<coll1>",
              "<coll2>"
            ]
          }
        ]
      },
      ...
    ]
}

Query

{
  "controller": "security",
  "action": "updateProfile",
  "_id": "<profileId>",
  "body": {
    "policies": [
      {
        "_id": "<roleId>"
      },
      {
        "_id": "<roleId>",
        "restrictedTo": [
          {
            "index": "<index>"
          },
          {
            "index": "<index>",
            "collections": [
              "<coll1>",
              "<coll2>"
            ]
          }
        ]
      },
      ...
    ]
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "%kuzzle",
  "collection": "profiles",
  "action": "updateProfile",
  "controller": "security",
  "requestId": "<unique request identifier>",
  "result": {
    "_id": "<profileId>",
    "_index": "%kuzzle",
    "_type": "profiles",
    "_version": 2
  }
}

Given a profile id, updates the matching Profile object in Kuzzle’s database layer.

updateProfileMapping

URL: http://kuzzle:7512/profiles/_mapping Method: PUT Body:

{
  // Data mapping using ElasticSearch mapping syntax
  "properties": {
    "field1": {
      "type": "field type",
      "other": "...options..."
    },
    "field2": {
      "type": "field type",
      "other": "...options..."
    },
    ...
    "fieldn": {
      "type": "field type",
      "other": "...options..."
    }
  }
}

Query

{
  "controller": "security",
  "action": "updateProfileMapping",

  // Data mapping using ElasticSearch mapping syntax
  "body": {
    "properties": {
      "field1": {
        "type": "field type",
        "other": "...options..."
      },
      "field2": {
        "type": "field type",
        "other": "...options..."
      },
      ...
      "fieldn": {
        "type": "field type",
        "other": "...options..."
      }
    }
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "action": "updateProfileMapping",
  "controller": "security",
  "requestId": "<unique request identifier>",
  "result": {
    "acknowledged": true
  },
}

At the first initialization, Kuzzle defines a default mapping for the profiles internal collection in the persistent data storage layer.

This mapping is intended to store the basic information of a profile; typically, its policies (roles and restrictions).

But if you want to store more information about your users, Kuzzle’s API offers a way to update the profiles data mapping using the mapping capabilities of ElasticSearch.

updateRole

URL: http://kuzzle:7512/roles/<roleId>/_update Method: PUT Body

{
  "controllers": {
    "*": {
      "actions": {
        "*": true
      }
    }
  }
}

Query

{
  "controller": "security",
  "action": "updateRole",
  "_id": "<roleId>",
  "body": {
    "controllers": {
      "*": {
        "actions": {
          "*": true
        }
      }
    }
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "%kuzzle",
  "collection": "roles",
  "action": "updateRole",
  "controller": "security",
  "requestId": "<unique request identifier>",
  "result": {
    "_id": "<roleId>",
    "_index": "%kuzzle",
    "_type": "roles",
    "_version": 2
  }
}

Given a role id, updates the matching Role object in Kuzzle’s database layer.

The body content needs to match Kuzzle’s role definition.

To get some more detailed information on the expected role definition, please refer to Kuzzle’s role reference definition documentation.

To get some more detailed information about Kuzzle’s user management model, please refer to Kuzzle’s security documentation.

updateRoleMapping

URL: http://kuzzle:7512/roles/_mapping Method: PUT Body:

{
  // Data mapping using ElasticSearch mapping syntax
  "properties": {
    "field1": {
      "type": "field type",
      "other": "...options..."
    },
    "field2": {
      "type": "field type",
      "other": "...options..."
    },
    ...
    "fieldn": {
      "type": "field type",
      "other": "...options..."
    }
  }
}

Query

{
  "controller": "security",
  "action": "updateRoleMapping",

  // Data mapping using ElasticSearch mapping syntax
  "body": {
    "properties": {
      "field1": {
        "type": "field type",
        "other": "...options..."
      },
      "field2": {
        "type": "field type",
        "other": "...options..."
      },
      ...
      "fieldn": {
        "type": "field type",
        "other": "...options..."
      }
    }
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "action": "updateRoleMapping",
  "controller": "security",
  "requestId": "<unique request identifier>",
  "result": {
    "acknowledged": true
  },
}

At the first initialization, Kuzzle defines a default mapping for the roles internal collection in the persistent data storage layer.

This mapping is intended to store the basic information of a role; typically, its allowed controllers and actions.

But if you want to store more information about your users, Kuzzle’s API offers a way to update the roles data mapping using the mapping capabilities of ElasticSearch.

updateUser

URL: http://kuzzle:7512/users/<userId>/_update Method: PUT Body

{
    "foo": "bar",                    // Some properties to update
    "name": "Walter Smith",
    ...
}

Query

{
  "controller": "security",
  "action": "updateUser",
  "_id": "<userId>",
  "body": {
    "foo": "bar",                    // Some properties to update
    "name": "Walter Smith",
    ...
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "%kuzzle",
  "collection": "users",
  "action": "updateUser",
  "controller": "security",
  "requestId": "<unique request identifier>",
  "result": {
    "_id": "<userId>",
    "_index": "%kuzzle",
    "_type": "users",
    "_version": 2
  }
}

Given a user id, updates the matching User object in Kuzzle’s database layer.

updateUserMapping

URL: http://kuzzle:7512/users/_mapping Method: PUT Body:

{
  // Data mapping using ElasticSearch mapping syntax
  "properties": {
    "field1": {
      "type": "field type",
      "other": "...options..."
    },
    "field2": {
      "type": "field type",
      "other": "...options..."
    },
    ...
    "fieldn": {
      "type": "field type",
      "other": "...options..."
    }
  }
}

Query

{
  "controller": "security",
  "action": "updateUserMapping",

  // Data mapping using ElasticSearch mapping syntax
  "body": {
    "properties": {
      "field1": {
        "type": "field type",
        "other": "...options..."
      },
      "field2": {
        "type": "field type",
        "other": "...options..."
      },
      ...
      "fieldn": {
        "type": "field type",
        "other": "...options..."
      }
    }
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "action": "updateUserMapping",
  "controller": "security",
  "requestId": "<unique request identifier>",
  "result": {
    "acknowledged": true
  },
}

At the first initialization, Kuzzle defines a default mapping for the users internal collection in the persistent data storage layer.

This mapping is intended to store the basic information of a user; typically, its credentials and profiles.

But if you want to store more information about your users, Kuzzle’s API offers a way to update the users data mapping using the mapping capabilities of ElasticSearch.

~ server controller

adminExists

URL: http://kuzzle:7512/_adminExists Method: GET

Query

{
  "controller": "server",
  "action": "adminExists"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<index>",
  "action": "adminExists",
  "controller": "server",
  "requestId": "<unique request identifier>",
  "result": {
    "exists": true
  }
}

Checks if an administrator account has been created, and return a boolean as a result.

getAllStats

URL: http://kuzzle:7512/_getAllStats Method: GET

Query

{
  "controller": "server",
  "action": "getAllStats"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "action": "getAllStats",
  "controller": "server",
  "requestId": "<unique request identifier>",
  "result": {
    "total": 25,
    "hits": [
      {
        "completedRequests": {
          "websocket": 148,
          "http": 24,
          "mqtt": 78
        },
        "failedRequests": {
          "websocket": 3
        },
        "ongoingRequests": {
          "mqtt": 8,
          "http": 2
        }
        "connections": {
          "websocket": 13
        },
        "timestamp": "1453110641308"
      },
      ...
    ]
  }
}

Kuzzle monitors its internal activities and make snapshots regularly. This command allows getting all the stored statistics. By default, snapshots are made every 10s, and these snapshots are stored for 1hr.

These statistics include:

  • the number of connected users per protocol for the ones which allow to get this information (websocket, udp, …)
  • the number of ongoing requests
  • the number of completed requests since the last frame
  • the number of failed requests since the last frame

Statistics are returned as a JSON-object with each key being the snapshot’s timestamp (utc, in milliseconds).

getConfig

URL: http://kuzzle:7512/_getConfig Method: GET

Query

{
  "controller": "server",
  "action": "getConfig"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "action": "getConfig",
  "controller": "server",
  "result": {
    "kuzzle": {
      "_": [
        "start"
      ],
      "dump": {
        "dateFormat": "YYYYMMDD-HHmm",
        "enabled": false,
        "gcore": "gcore",
        "handledErrors": {
          "enabled": true,
          "whitelist": [
            "RangeError",
            "TypeError",
            "KuzzleError",
            "InternalError",
            "PluginImplementationError"
          ]
        },
        "path": "./dump/"
      },
      "http": {
        "accessControlAllowOrigin": "*",
        "routes": [
          {
            "action": "exists",
            "controller": "collection",
            "url": "/:index/:collection/_exists",
            "verb": "get"
          },
          /*
           * ... A long list of http routes ...
           */
        ]
      },
      "plugins": {
        "common": {
          "object": {},
          "pipeTimeout": 250,
          "pipeWarnTime": 40,
          "workerPrefix": "kpw:"
        },
        "kuzzle-plugin-auth-passport-local": {
          "activated": true,
          "config": {
            "algorithm": "sha1",
            "digest": "hex",
            "secret": "changeme"
          },
          "object": {},
          "version": "3.0.2"
        },
        "kuzzle-plugin-logger": {
          "activated": true,
          "config": {
            "services": {
              "file": {
                "addDate": true,
                "outputs": {
                  "error": {
                    "filename": "kuzzle.log",
                    "level": "warn"
                  }
                }
              },
              "stdout": {
                "level": "info"
              }
            },
            "threads": 2
          },
          "object": {},
          "version": "2.0.5"
        }
      },
      "queues": {
        "cliQueue": "cli-queue"
      },
      "repositories": {
        "common": {
          "cacheTTL": 1440
        }
      },
      "security": {
        "default": {
          "role": {
            "controllers": {
              "*": {
                "actions": {
                  "*": true
                }
              }
            }
          }
        },
        "jwt": {
          "algorithm": "HS256",
          "expiresIn": "1h",
          "secret": "Kuzzle rocks"
        },
        "restrictedProfileIds": [
          "default"
        ],
        "standard": {
          "profiles": {
            "admin": {
              "policies": [
                {
                  "allowInternalIndex": true,
                  "roleId": "admin"
                }
              ]
            },
            "anonymous": {
              "policies": [
                {
                  "roleId": "anonymous"
                }
              ]
            },
            "default": {
              "policies": [
                {
                  "roleId": "default"
                }
              ]
            }
          },
          "roles": {
            "admin": {
              "controllers": {
                "*": {
                  "actions": {
                    "*": true
                  }
                }
              }
            },
            "anonymous": {
              "controllers": {
                "auth": {
                  "actions": {
                    "checkToken": true,
                    "getCurrentUser": true,
                    "getMyRights": true,
                    "login": true
                  }
                },
                "server": {
                  "actions": {
                    "info": true
                  }
                }
              }
            },
            "default": {
              "controllers": {
                "auth": {
                  "actions": {
                    "checkToken": true,
                    "getCurrentUser": true,
                    "getMyRights": true,
                    "logout": true,
                    "updateSelf": true
                  }
                },
                "server": {
                  "actions": {
                    "info": true
                  }
                }
              }
            }
          }
        }
      },
      "server": {
        "maxConcurrentRequests": 50,
        "maxRequestHistorySize": 50,
        "maxRetainedRequests": 50000,
        "warningRetainedRequestsLimit": 5000
      },
      "services": {
        "common": {
          "defaultInitTimeout": 10000,
          "retryInterval": 1000
        },
        "db": {
          "aliases": [
            "storageEngine"
          ],
          "apiVersion": "5.0",
          "backend": "elasticsearch",
          "host": "elasticsearch",
          "port": 9200
        },
        "garbageCollector": {
          "cleanInterval": 86400000,
          "maxDelete": 1000
        },
        "internalBroker": {
          "aliases": [
            "broker"
          ],
          "retryInterval": 1000,
          "socket": "./run/broker.sock"
        },
        "internalCache": {
          "backend": "redis",
          "node": {
            "host": "redis",
            "port": 6379
          }
        },
        "memoryStorage": {
          "backend": "redis",
          "database": 5,
          "node": {
            "host": "redis",
            "port": 6379
          }
        },
        "proxyBroker": {
          "host": "proxy",
          "port": 7331,
          "retryInterval": 1000
        }
      },
      "stats": {
        "statsInterval": 10,
        "ttl": 3600
      },
      "validation": {},
      "version": "1.0.0-RC9"
    },
    "plugins": {
      "config": {
        "kuzzle-plugin-auth-passport-local": {
          "activated": true,
          "config": {
            "algorithm": "sha1",
            "digest": "hex",
            "secret": "changeme"
          },
          "version": "3.0.2"
        },
        "kuzzle-plugin-logger": {
          "activated": true,
          "config": {
            "services": {
              "file": {
                "addDate": true,
                "outputs": {
                  "error": {
                    "filename": "kuzzle.log",
                    "level": "warn"
                  }
                }
              },
              "stdout": {
                "level": "info"
              }
            },
            "threads": 2
          },
          "version": "2.0.5"
        }
      },
      "routes": []
    }
  }
}

Returns the current Kuzzle configuration as loaded at Kuzzle start.

getLastStats

URL: http://kuzzle:7512/_getLastStats Method: GET

Query

{
  "controller": "server",
  "action": "getLastStats"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "action": "getLastStats",
  "controller": "server",
  "requestId": "<unique request identifier>",
  "result": {
    "completedRequests": {
      "websocket": 148,
      "http": 24,
      "mqtt": 78
    },
    "failedRequests": {
      "websocket": 3
    },
    "ongoingRequests": {
      "mqtt": 8,
      "http": 2
    }
    "connections": {
      "websocket": 13
    },
    "timestamp": "1453110641308"
  }
}

Kuzzle monitors its internal activities and make snapshots regularly. Allows to get the last stored statistics frame. By default, snapshots are made every 10s.

These statistics include:

  • the number of connected users per protocol for the ones which allow to get this information (websocket, udp, …)
  • the number of ongoing requests
  • the number of completed requests since the last frame
  • the number of failed requests since the last frame

Statistics are returned as a JSON-object with each key being the snapshot’s timestamp (utc, in milliseconds).

getStats

URL: http://kuzzle:7512/_getStats[?startTime=123456789][&stopTime=234567890] Method: POST

Query

{
  "controller": "server",
  "action": "getStats",

  // Optional: Kuzzle will return all statistics if nor the startTime and stopTime are defined
  "startTime": <timestamp>,
  "stopTime": <timestamp>
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "action": "getStats",
  "controller": "server",
  "requestId": "<unique request identifier>",
  "result": {
    "total": 25,
    "hits": [
      {
        "completedRequests": {
          "websocket": 148,
          "http": 24,
          "mqtt": 78
        },
        "failedRequests": {
          "websocket": 3
        },
        "ongoingRequests": {
          "mqtt": 8,
          "http": 2
        }
        "connections": {
          "websocket": 13
        },
        "timestamp": "1453110641308"
      },
      {
        "etc...": "etc ..."
      }
    ]
  }
}

Allows to get statistics frames saved/stored after a provided timestamp (utc, in milliseconds).

These statistics include:

  • the number of connected users per protocol for the ones which allow to get this information (websocket, udp, …)
  • the number of ongoing requests
  • the number of completed requests since the last frame
  • the number of failed requests since the last frame

Statistics are returned as a JSON-object with each key being the snapshot’s timestamp (utc, in milliseconds).

info

URL: http://kuzzle:7512/_serverInfo Method: GET

Query

{
  "controller": "server",
  "action": "info"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "controller": "server",
  "action": "info",
  "result": {
    "serverInfo": {
      "kuzzle": {
        "api": {
          "routes": {
            "controller1": {
              "action1": {
                "method": "get",
                "name": "action1",
                "route": "..."
              },
              "action2": {
                "method": "post",
                "name": "action2",
                "route": "..."
              },
              {
                "etc...": "etc ..."
              }
            },
            "controller2": {
              "action1": {
                "method": "get",
                "name": "action1",
                "route": "..."
              },
              "action2": {
                "method": "post",
                "name": "action2",
                "route": "..."
              },
              {
                "etc...": "etc ..."
              }
            },
            {
              "etc...": "etc ..."
            }
          },
          "version": "1.0"
        },
        "memoryUsed": 82747392,
        "nodeVersion": "v4.4.3",
        "plugins": {},
        "system": {
          "cpus": [
            {
              "model": "Intel(R) Core(TM) i5-4670 CPU @ 3.40GHz",
              "speed": 2700,
              "times": {
                "idle": 19767912700,
                "irq": 73805400,
                "nice": 66474700,
                "sys": 588744200,
                "user": 1733754000
              }
            },
            {
              "etc...": "etc ..."
            }
          ],
          "memory": {
            "free": 1157988352,
            "total": 16768524288
          }
        },
        "uptime": "349.923s",
        "version": "1.0.0-RC4"
      },
      "services": {
        "internalCache": {
          "memoryPeak": "1.06M",
          "memoryUsed": "978.63K",
          "mode": "standalone",
          "type": "redis",
          "version": "3.0.7"
        },
        "memoryStorage": {
          "memoryPeak": "1.06M",
          "memoryUsed": "1014.62K",
          "mode": "standalone",
          "type": "redis",
          "version": "3.0.7"
        },
        {
          "etc...": "etc ..."
        }
      }
    }
  }
}

Retrieves information about Kuzzle, its plugins and active services.

now

URL: http://kuzzle:7512/_now Method: GET

{
  "controller": "server",
  "action": "now"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "controller": "server",
  "action": "now",
  "requestId": "<unique request identifier>",
  "result": {
    "now": 1447151167622              // Epoch time
  }
}

Returns the current Kuzzle UTC timestamp as Epoch time (number of milliseconds elapsed since 1 January 1970 00:00:00).