NAV

Introduction

Welcome to the Kuzzle API Documentation!

Connecting to Kuzzle

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

HTTP

 $ curl "http://localhost:7511/"

By default, Kuzzle exposes itself on the 7511 port. Assuming the Kuzzle server runs locally, it can be reached on http://localhost:7511/. Note that HTTP is the only protocol shipped in Kuzzle’s core.

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:7513");
</script>

By default, Kuzzle embarks our official WebSocket plugin, accepting websocket requests on the 7513 port.

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 Socket.io protocol plugin.

By default, this plugin listens to the port 7512.

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:7511/<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": "<data index>",

  // Collection on which the action is handled (empty for actions that do not manage a unique collection)
  "collection": "<data 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:7511/..."
{
  // Optional: Unique request Identifier
  "requestId": "<unique request identifier>",
  "controller": "<controller>",
  "action": "<action>",
  "collection": "<data 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": "<data index>",
  "collection": "<collection>",
  "controller": "<controller>",
  "action": "<action>",

  // 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 ID>",

  // 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": "<data index>",
  "collection": "<data collection>",
  "controller": "document",
  "action": "update",
  "_id": "<a document ID>",
  "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": "<data index>",
  "collection": "<data 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": "<data index>",
  "collection": "<data 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": "<data index>",
  "collection": "<data collection>",
  "controller": "realtime",
  "action": "unsubscribe",
  "state": "done",
  "scope": "out",
  "metadata": {
    "hello": "my name is Bob"
  },
  "requestId": "<unique request identifier>",
  "result": {
    "roomId": "<uniqueKuzzleRoomID>",
    "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:7513"),
    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": "<data index>",
  "collection": "<data 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": {
    "_id": "unique document ID",
    "_source": {...}                    // The created document
  }
}

An updated document entered your listening scope

{
  "status": 200,                        // Assuming everything went well
  "error": null,                        // Assuming everything went well
  "index": "<data index>",
  "collection": "<data 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": "<unique document ID>",
    ...
  }
}

An updated document left your listening scope

{
  "status": 200,                        // Assuming everything went well
  "error": null,                        // Assuming everything went well
  "index": "<data index>",
  "collection": "<data 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": "<unique document ID>",
    ...
  }
}

A document has been deleted

{
  "status": 200,                        // Assuming everything went well
  "error": null,                        // Assuming everything went well
  "index": "<data index>",
  "collection": "<data 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": "<unique document ID>",
    ...
  }
}

A document is about to be created

{
  "status": 200,                        // Assuming everything went well
  "error": null,                        // Assuming everything went well
  "index": "<data index>",
  "collection": "<data 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": "<data index>",
  "collection": "<data 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": "<data index>",
  "collection": "<data collection>",
  "controller": "realtime",
  "action": "subscribe",
  "metadata": {
    // metadata embedded in the request
  },
  "requestId": "<unique request identifier>",
  "result": {
    "roomId": "<unique Kuzzle room ID>",
    "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": "<data index>",
  "collection": "<data collection>",
  "controller": "realtime",
  "action": "unsubscribe",
  "metadata": {
    // metadata embedded in the request
  },
  "requestId": "<unique request identifier>",
  "result": {
    "roomId": "<unique Kuzzle room ID>",
    "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:7511/_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:7511/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": "<data index>",
  "collection": "<data collection>",
  "controller": "auth",
  "action": "getCurrentUser",
  "requestId": "<unique request identifier>",
  "jwt": "<encrypted_jwt_token>",
  "result": {
    "_id":"<user id>",
    "_source": {
      "name": {
        "first": "Steve",
        "last": "Wozniak"
        },
        ...                         // The user object content
        "profile": {
          "_id":"<profile id>",
          "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:7511/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:7511/_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": "<user ID>",
    "jwt": "<JWT encrypted token>"
  }
}

Authenticate 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:7511/_logout
Method: GET
Headers: Authorization: "Bearer <encrypted_jwt_token>"

Query

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

Revoke token validity & unsubscribe from registered rooms

The _logout action doesn’t take strategy.

updateSelf

URL: http://kuzzle:7511/_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": "<user id>",
    "_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:7511/<data index>/<data 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": "<data index>",
  "collection": "<data 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": "<data index>",
  "collection": "<data collection>",
  "controller": "bulk",
  "action": "import",
  "requestId": "<unique request identifier>",
  "result": {
    // The list of executed queries, with their status
    "hits": [
      {
        "create": {
          "_id": "<document Id>",
          "status": <HTTP status code>
        }
      },
      {
        "create": {
          "_id": "<document ID>",
          "status": <HTTP status code>
        }
      },
      {
        "create": {
          "_id": "<document Id>",
          "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:7511/_bulk
Method: POST
Body:

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

Query

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

  "body": {
    // Data mapping using ElasticSearch bulk syntax.
    "bulkData": [
      {"create": {"_index": "<data index>", "_type": "<data collection>"}},
      {"a": "document", "with": "any", "number": "of fields"},
      {"create": {"_index": "<data index>", "_type": "<data collection>"}},
      {"another": "document"},
      {"create": {"_index": "<data index>", "_type": "<data collection>"}},
      {"and": { "another": "one"} },
      ...
      {"create": {"index": { "_index": "<another data index>", "_type": "<another data 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": "<document Id>",
          "status": <HTTP status code>
        }
      },
      {
        "create": {
          "_id": ""<document Id>",
          "status": <HTTP status code>
        }
      },
      {
        "create": {
          "_id": "<document Id>",
          "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:7511/<data index>/<collection name>
Method: PUT

Query

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

Response

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

When creating a document, Kuzzle will automatically create a data 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:7511/<data index>/<data collection>/_specifications
Method: DELETE

Query

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

Response

{
  status: 200,                      // Assuming everything went well
  error: null,                      // Assuming everything went well
  index: "<data index>",
  collection: "<data 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:7511/<data index>/<data collection>/_exists
Method: GET

Query

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

Response

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

Check if a collection exists in Kuzzle database storage layer.

getMapping

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

Query

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

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<data index>",
  "collection": "<data collection>",
  "controller": "collection",
  "action": "getMapping",
  "requestId": "<unique request identifier>",
  "result": {
    "mainindex": {
      "mappings": {
        <data 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:7511/<data index>/<data collection>/_specifications
Method: GET

Query

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

Response

{
  status: 200,                      // Assuming everything went well
  error: null,                      // Assuming everything went well
  action: "getSpecifications",
  controller: "collection",
  collection: "<data collection>",
  index: "<data index>",
  result: {
    collection: "<data collection>",
    index: "<data 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: "<data index>",
  collection: "<data collection>"
  result: null
}

This command allows getting the validation specifications associated to the given index and collection if some specifications has been defined first

list

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

Query

{
  "index": "<data 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": "<data 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"
  }
}

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

truncate

URL: http://kuzzle:7511/<data index>/<collection name>/_truncate
Method: DELETE

Query

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

Response

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

This method 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:7511/<data index>/<data collection>/_mapping
Method: PUT
Body:

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

Query

{
  "index": "<data index>",
  "collection": "<data 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": "<data index>",
  "collection": "<data 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:7511/_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: "<data index>",
  collection: "<data 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:7511/_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: "<data index>",
  collection: "<data 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:7511/<data index>/<data 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": "<data index>",
  "collection": "<data 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": "<data index>",
  "collection": "<data 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:7511/<data index>/<data collection>/_create[?refresh=wait_for]
Method: POST
Body:

{
  // The message to send
}

Query

{
  "index": "<data index>",
  "collection": "<data collection>",
  "controller": "document",
  "action": "create",
  ["refresh": "wait_for",]
  "body": {
    // the document to create
  }
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<data index>",
  "collection": "<data collection>",
  "controller": "document",
  "action": "create",
  "requestId": "<unique request identifier>",
  "result": {
    "_id": "<Unique document ID>",    // The generated 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 (availability using search).

createOrReplace

URL: http://kuzzle:7511/<data index>/<data collection>/<documentId>[?refresh=wait_for] or http://kuzzle:7511/<data index>/<data collection>/<documentId>/_createOrReplace[?refresh=wait_for]
Method: PUT
Body:

{
  // The document to update
}

Query

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

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<data index>",
  "collection": "<data collection>",
  "controller": "document",
  "action": "createOrReplace",
  "requestId": "<unique request identifier>",
  "result": {
    "_id": "<Unique document ID>",    // The generated document ID
    "_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 (availability using search).

delete

URL: http://kuzzle:7511/<data index>/<data collection>/<documentID>[?refresh=wait_for]
Method: DELETE

Query

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

  // The document unique identifier. It's the same one that Kuzzle sends you
  // in its responses when you create a document, or when you do a search query.
  "_id": "<document ID>"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<data index>",
  "collection": "<data collection>",
  "controller": "document",
  "action": "delete",
  "requestId": "<unique request identifier>",
  "result": {
    "_id": "<document ID>"            // 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:7511/<data index>/<data 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": "<data index>",
  "collection": "<data 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": "<data index>",
  "collection": "<data 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:7511/<data index>/<data collection>/<document Id>
Method: GET

Query

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

  // The document unique identifier. It's the same one that Kuzzle sends you
  // in its responses when you create a document, or when you do a search query.
  "_id": "<document ID>"
}

Response

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

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

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

replace

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

{
  // The document to update
}

Query

{
  "index": "<data index>",
  "collection": "<data 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": "<data index>",
  "collection": "<data collection>",
  "controller": "document",
  "action": "replace",
  "requestId": "<unique request identifier>",
  "result": {
    "_id": "<Unique document ID>",    // The document unique ID
    "_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 (availability using search).

scroll

URL: http://kuzzle:7511/_scroll/<scrollId>
Method: POST
Body:

{
  // The scroll parameter tells Elasticsearch to keep the search context open for another 1m.
  "scroll": "1m"
}

Query

{
  "controller": "document",
  "action": "scroll",

  "body": {
    "scrollId": "<scrollId>"
    // The scroll parameter tells Elasticsearch to keep the search context open for another 1m.
    "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": "<document unique ID>",
        "_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:7511/<data index>/<data collection>/_search[?from=0][&size=42]
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": {
    ...
  },
  "aggregations": {
    ...
  }
}

Query

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

  "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": {

    },
    "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": "<data index>",
  "collection": "<data 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": "<document unique ID>",
        "_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.

update

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

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

Query

{
  "index": "<data index>",
  "collection": "<data collection>",
  "controller": "document",
  "action": "update",
  ["refresh": "wait_for",]
  // The document unique identifier. It's the same one that Kuzzle sends you
  // in its responses when you create a document, or when you do a search query.
  "_id": "<document ID>"

  // 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": "<data index>",
  "collection": "<data collection>",
  "controller": "document",
  "action": "update",
  "requestId": "<unique request identifier>",
  "result": {
    "_id":
  }
}

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 (availability using search).

validate

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

{
    // The message to send
}

Query

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

Response

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

Validate 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:7511/<data index>
Method: PUT

Query

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

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<data 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:7511/<data index>
Method: DELETE

Query

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

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<data 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:7511/<data index>/_exists
Method: GET

Query

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

Response

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

Check if the given index exists in Kuzzle storage layer.

getAutoRefresh

URL: http://kuzzle:7511/<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:7511/_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"
    ]
  }
}

Return the complete data indexes.

mDelete

URL: http://kuzzle:7511/_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:7511/<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": "<data index>",
  "controller": "index",
  "action": "delete",
  "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.

setAutoRefresh

URL: http://kuzzle:7511/<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:7511/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": "<data index>",
  "collection": "<data 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": "<data index>",
  "collection": "<data collection>",
  "controller": "realtime",
  "action": "count",
  "requestId": "<unique request identifier>",
  "result": {
    "roomId": "<unique Kuzzle room ID>",
    "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": "<data index>",
  "collection": "<data collection>",
  "controller": "realtime",
  "action": "join",
  "body": {
    "roomId": "<the room ID 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": "<data index>",
  "collection": "<data collection>",
  "controller": "realtime",
  "action": "subscribe",
  "metadata": {},                     // subscription metadata
  "requestId": "<unique request identifier>",
  "result": {
    "roomId": "<unique Kuzzle room ID>"
  }
}

Joins a previously created subscription.

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

publish

URL: http://kuzzle:7511/<data index>/<data collection>
Method: POST
Body:

{
  // The message to send
}

Query

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

Response

{
  "error": null,
  "status": 200,
  "index": "<data index>",
  "collection": "<data 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": "<data index>",
  "collection": "<data 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": "<data index>",
  "collection": "<data collection>",
  "controller": "realtime",
  "action": "subscribe",
  "metadata": {},                     // subscription metadata
  "requestId": "<unique request identifier>",
  "result": {
    "roomId": "<unique Kuzzle room ID>",
    "channel": "<unique channel ID>"
  }
}

Websocket

<script>
  var
    socket = new WebSocket("ws://localhost:7513"),
    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":"<data index>",
        "collection":""<data 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 ID>"
  }
}

This action instucts 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:7511/<data index>/<data collection>/_validate
Method: POST
Body:

{
    // The message to send
}

Query

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

Response

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

Validate 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

createOrReplaceProfile

URL: http://kuzzle:7511/profiles/<profile_id>
Method: PUT
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>"
          ]
        }
      ]
    },
    ...
  ]
}

Query

{
  "controller": "security",
  "action": "createOrReplaceProfile",

  "_id": "<the profile id>",
  // 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 wen well
  "result": {
    "_id": "<profile_id>",
    "_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:7511/roles/<role id> or http://kuzzle:7511/roles/<role id>/_createOrReplace
Method: PUT
Body

{
  "indexes": {
    "_canCreate": true,
    "*": {
      "_canDelete": true,
      "collections": {
        "_canCreate": true,
        "*": {
          "_canDelete": true,
          "controllers": {
            "*": {
              "actions": {
                "*": true
              }
            }
          }
        }
      }
    }
  }
}

Query

{
  "controller": "security",
  "action": "createOrReplaceRole",

  "_id": "<the role id>",
  // the role definition
  "body": {
    "indexes": {
      "_canCreate": true,
      "*": {
        "_canDelete": true,
        "collections": {
          "_canCreate": true,
          "*": {
            "_canDelete": true,
            "controllers": {
              "*": {
                "actions": {
                  "*": true
                }
              }
            }
          }
        }
      }
    }
  }
}

Response

{
  "status":200,                       // Assuming everything went well
  error":null,                      // Assuming everything wen well
  "result": {
    "_id": "<role id>",
    "_index": "%kuzzle",
    "_type": "roles",
    "_version": 1,
    "created": true,
    "_source": {} // your role definition
  }
  "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:7511/users/<user id>
Method: PUT
Body

{
  "profileId": "<profile id>",            // mandatory. The profile id for the user
  "name": "John Doe",                     // Additional optional User properties
  ...
}

Query

{
  "controller": "security",
  "action": "createOrReplaceUser",

  "_id": "<the user id>",
  "body": {
    "profileId": "<profile id>",          // mandatory. The profile id 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": "<user id, either provided or auto-generated>",
    "_index": "%kuzzle",
    "_source": {
      "profileId": "<profile id>",
      "name": "John Doe",
      ...
    },
    "_type": "users",
    "_version": 1,
    "created": true
  }
}

Persist 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:7511/profiles/<profile id>/_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": "<the profile id>",

  // 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 wen well
  "result": {
    "_id": "<profile_id>",
    "_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:7511/roles/<role id>/_create
Method: POST
Body

{
  "indexes": {
    "_canCreate": true,
    "*": {
      "_canDelete": true,
      "collections": {
        "_canCreate": true,
        "*": {
          "_canDelete": true,
          "controllers": {
            "*": {
              "actions": {
                "*": true
              }
            }
          }
        }
      }
    }
  }
}

Query

{
  "controller": "security",
  "action": "createRole",
  "_id": "<the role id>",

  // the role definition
  "body": {
    "indexes": {
      "_canCreate": true,
      "*": {
        "_canDelete": true,
        "collections": {
          "_canCreate": true,
          "*": {
            "_canDelete": true,
            "controllers": {
              "*": {
                "actions": {
                  "*": true
                }
              }
            }
          }
        }
      }
    }
  }
}

Response

{
  "status":200,                       // Assuming everything went well
  error":null,                      // Assuming everything wen well
  "result": {
    "_id": "<role id>",
    "_index": "%kuzzle",
    "_type": "roles",
    "_version": 1,
    "created": true,
    "_source": {} // your role definition
  }
  "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:7511/users/<user id>/_create or http://kuzzle:7511/users/_create
Method: POST
Body

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

// example with a "local" authentication

{
  "profileIds": ["<profile id>"],         // 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": "<the user id>",                 // Optional. If not provided, will be generated automatically.

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

// example with a "local" authentication

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

  "body": {
    "profileIds": ["<profile id>"],       // 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": {},
  "scope": null,
  "requestId": "<unique request identifier>",
  "result": {
    "_id": "<user id, either provided or auto-generated>",
    "_index": "%kuzzle",
    "_source": {
      "profileIds": ["<profile id>"],
      "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 informations are needed depending on the authentication plugins installed you want to use.

createRestrictedUser

URL: http://kuzzle:7511/users/<user id>/_createRestricted or http://kuzzle:7511/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": "<the user id>",                 // 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": "<the user id>",                 // 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": {},
  "scope": null,
  "requestId": "<unique request identifier>",
  "result": {
    "_id": "<user id, either provided or auto-generated>",
    "_index": "%kuzzle",
    "_source": {
      "profileIds": ["<profile id>"],
      "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 informations are needed depending on the authentication plugins installed you want to use.

deleteProfile

URL: http://kuzzle:7511/_profiles/<profile_id>
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": "<profile ID>"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "result": {
    "_id": "<Profile ID>",        // 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:7511/roles/<role id>
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": "<role ID>"
}

Response

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

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

deleteUser

URL: http://kuzzle:7511/users/<user id>
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": "<role ID>"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "result": {
    "_id": "<Unique role ID>"         // 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:7511/_profiles/<profile_id>
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": "<profile ID>"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "result": {
    "_id": "<Unique profile ID>",    // 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.

getProfileRights

URL: http://kuzzle:7511/_profiles/<profile_id>/_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": "<profile ID>"
}

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:7511/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": "<role ID>"
}

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "result": {
    "_id": "<Unique role ID>",        // 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.

getUser

URL: http://kuzzle:7511/users/<user id>
Method: GET

Query

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

Response

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

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

getUserRights

URL: http://kuzzle:7511/_users/<user_id>/_rights
Method: GET

Query

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

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.

mGetProfiles

URL: http://kuzzle:7511/profiles/_mget
Method: POST
Body:

{
  "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:7511/roles/_mget
Method: POST
Body:

{
  "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:7511/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:7511/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:7511/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": "<user id>",
        "_source": { ... }             // The user object content
      },
      {
        ...
      }
    ]
  }
}

Retrieves all the users matching the given filter.

The from and size arguments allow pagination.

updateProfile

URL: http://kuzzle:7511/profiles/<profile id>
Method: POST
Body

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

Query

{
  "controller": "security",
  "action": "updateProfile",
  "_id": "<profile id>",
  "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": "<user id>",
    "_index": "%kuzzle",
    "_type": "profiles",
    "_version": 2
  }
}

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

updateRole

URL: http://kuzzle:7511/roles/<role id>
Method: POST
Body

{
    "indexes": {
      "some index": {
        "collections": {
          "some collection": {
            "_canDelete": true
          }
        }
      }
    }
}

Query

{
  "controller": "security",
  "action": "updateRole",
  "_id": "<role id>",
  "body": {
    "indexes": {
      "some index": {
        "collections": {
          "some collection": {
            "_canDelete": 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": "<user id>",
    "_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.

updateUser

URL: http://kuzzle:7511/users/<user id>
Method: POST
Body

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

Query

{
  "controller": "security",
  "action": "updateUser",
  "_id": "<user id>",
  "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": "<user id>",
    "_index": "%kuzzle",
    "_type": "users",
    "_version": 2
  }
}

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

~ server controller

adminExists

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

Query

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

Response

{
  "status": 200,                      // Assuming everything went well
  "error": null,                      // Assuming everything went well
  "index": "<data 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:7511/_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).

getLastStats

URL: http://kuzzle:7511/_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. This command allows getting 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:7511/_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 ..."
      }
    ]
  }
}

This command allows getting 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:7511/_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:7511/_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
  }
}

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