Skip to main content

Realms

Create a realm​

POSThttps://api.hivekit.io/v2/realm/[realmId]

Request Body​

{ 
    "label": "My first realm",  // required
    "data": { // optional
        "myCustomData": "Some data" 
    }
}

Response Body​

{
    "id": "realm-123",
    "result": "success"
}

Update a realm​

PATCHhttps://api.hivekit.io/v2/realm/[realmId]

Updates a realm's label or data. Properties in data are merged into the realms existing data - so if your realm's current data is {"firstname": "Homer"} and you update it with {"lastname": "Simpson"}, the resulting data will be {"firstname": "Homer", "lastname": "Simpson"}. To remove a property, set it to null.

Request Body​

{ 
    "label": "My first realm",  // optional
    "data": { // optional
        "myCustomData": "Some data" 
    }
}

Response Body​

{
    "id": "realm-123",
    "result": "success"
}

Read a realm​

GEThttps://api.hivekit.io/v2/realm/[realmId]

Response Body​

{
    "id": "realm-123",
    "label": "My first realm",
    "data": {
        "myCustomData": "Some data"
    }
}

List realms​

GEThttps://api.hivekit.io/v2/realm

Response Body​

{
    "realm-123": {
        "id": "realm-123",
        "label": "My first realm",
        "data": {
            "myCustomData": "Some data"
        }
    },
    "realm-456": {
        "id": "realm-456",
        "label": "My second realm",
        "data": {
            "value": 123
        }
    }
}

Delete a realm​

DELETEhttps://api.hivekit.io/v2/realm/[realmId]

Response Body​

{
    "id": "realm-123",
    "result": "success"
}

Search within a realm​

GEThttps://api.hivekit.io/v2/realm/[realmId]/search?searchString=simpson&fields=id,label,data&maxObjectResults=20

This endpoint lets you perform a fulltext search accross ids, labels and fields in data for objects and areas within a realm. If you are looking for a method that returns objects based on certain filter criteria, e.g. type=scooter and charge<0.2, use the list objects endpoint instead.

Query Parameters​

  • searchString - The string to search for. Required.
  • fields - By default, search looks for matches in an object's id, label and the values in its data. You can limit the fields that are searched by specifying a comma separated list of fields. For example, fields=id,label will only search for matches in the id and label. Optional.
  • maxObjectResults - The maximum number of objects to return. Defaults to 999. Optional.
  • maxAreaResults - The maximum number of areas to return. Defaults to 999. Optional.

Response Body​

{
    "homer-simpson": {
        "id": "homer-simpson",
        "label": "Homer J. Simpson",

        // the position of the match in the field's value. Useful to highlight matches in a UI.
        "startIndex": 6,
        "endIndex": 13,

        // the field the match was found in. Can be "id", "label" or the name of a field in data.
        "foundIn": "id",

        // can be obj or are
        "type": "obj",

        // the actual value of whatever field the result was found in
        "value": "homer-simpson"
    },
    "lisa-simpson": {
        "endIndex": 12,
        "foundIn": "id",
        "id": "lisa-simpson",
        "label": "Lisa Simpson",
        "startIndex": 5,
        "type": "obj",
        "value": "lisa-simpson"
    }
}