Meshcube v6.3.2504.23000 API

HTTP APIs allow communication with MeshCube using the HTTP request-response communication protocol.

In this type of communication, the standard request is:

http(s)://<URL>[:port]/<request_type>

Authentication

The system provides three options for authenticating calls from external clients:

  1. No Auth
    The system does not require any authorization. This mode is only suitable for systems installed on-premises and thus running in a private network.

  2. Basic Auth
    The system requires the Basic Authentication for API invocation.
    When used in combination with a secure connection, this method provides good protection against unauthorized access with minimal overhead.

  3. JWT Token Auth
    The system requires a JWT Token for API invocation.
    The tokens generated by MeshCube allow configuration of:

  4. An optional expiry date

  5. An optional list of IP addresses allowed to invoke APIs
  6. What API paths are accessible using the token
  7. The maximum number of invocations per hour

For further details about API authentication, please refer to the system documentation

Invoking API via MQTT interface

MeshCube allows invoking the API using the MQTT interface, useful in scenarios where MeshCube is not directly connectable but is connected to an external MQTT Broker.

The MQTT interface allows configuration of:

  • The request topic
  • The response topic

See the manual for MQTT interface configuration

Sending an API request

Publish to <request-topic> the following payload:

{
  "id": "(string) client generated unique identifier",
  "method": "(string) the HTTP method",
  "target": "(string) the API target url",
  "parameters": "(object) the query string parameters [optional]",
  "headers": "(object) the request headers [optional]",
  "body": "(object) the request body [optional]"
}

id

The unique string identifier that must be generated by the client.

Usually a UUID is the best option.

method

The HTTP method. Must be set according to the API definition.

target

The API target URL. Must be set according to the API definition.

parameters

The API query string parameters. Should be set when expected.

headers

The API headers. Should be set when expected.

body

The API request body. Should be set when expected, for example in POST APIs.

Receiving the response

MeshCube processes the request and sends back a response, with the following structure:

{
  "id": "(string) client generated unique identifier",
  "timestamp": "(number) the unix timestamp of the API execution",
  "execution": "(number) the time spent for the API execution",
  "method": "(string) the HTTP method",
  "target": "(string) the API target url",
  "status": "(number) the HTTP status code",
  "type": "(string) the MIME type of the response body [optional]",
  "body": "(object | string) the response body [optional]"
}
id

The unique string identifier generated by the client.

timestamp

The Unix timestamp (resolution: milliseconds) of the API execution.

execution

The time that the system spent on API execution.

method

The HTTP method. Must be set according to the API definition.

target

The API target URL. Must be set according to the API definition.

status

The HTTP status of the API response.

type

Omitted when the API does not provide a response body

The content type of the API response body.

body

Omitted when the API does not provide a response body

The response body, encoded as base64, except for:

  • application/json: encoded as JSON element
  • text/plain: encoded as UTF-8 string

Responses

In the following are described the responses that are common for all API calls. Other responses will be specified for each call in detail.

Status Code Status Message Body
200 Success Depends on API definition
403 ERR_LICENSE 
The request can not be performed because of a license error		 The JSON license information
500 ERR_SERVER_FAILURE
The server was unable to fulfill the request due to an internal error		 (Optional) Error details as JSON object

Each response status different than 2xx provides a string identifier as HTTP status message in the form ERR_*, in order to identify the error.

For example, a response could return the status code 400 (Bad Request) for several scenarios, and the status message will contain the specific error detail.

API List

GET /api.md

Get a markdown file with all APIs described

Responses
Status Code Status Description Description
200 OK The markdown file was generated and returned successfully
Response Headers
Header Description
Expires Set to -1 to disable caching
Cache-Control Set to public, must-revalidate, post-check=0, pre-check=0
Content-Disposition Indicates the file is an attachment with the name api-v<version>.md
Response Body

The response body is a markdown (text/x-markdown) file containing:

  • General API description
  • List of available REST APIs
  • List of available Server-Sent Events

This endpoint is useful for programmatically downloading the API documentation.

POST /api/anchor

Place an anchor on a map

Body Parameters

Key Type Description Required
id string Node ID that identifies the anchor ✓
map number ID of the map where the anchor will be placed ✓
position object 2D coordinates where the anchor will be placed (x, y) ✓
positioning_enabled boolean Whether positioning is enabled for the anchor (default: true) ✕
calibrated_rssi number Calibrated RSSI at 1 meter ✕
rssi_offset number RSSI correction offset ✕
n number Environmental factor ✕
Request Example
{
  "id": "S1-140114",
  "map": 2,
  "position": {
    "x": 1.585,
    "y": 8.659
  },
  "positioning_enabled": true,
  "calibrated_rssi": -54,
  "rssi_offset": 0,
  "n": 1
}

Responses

Status Code Status Description Description
200 OK Anchor placed successfully
400 ERR_INVALID_BODY The request body is missing or malformed
400 ERR_MISSING_NODE_ID The node ID is not provided
400 ERR_MISSING_MAP_ID The map ID is not provided
400 ERR_MISSING_POSITION The position is not provided
400 ERR_INVALID POSITION The position provided is invalid
404 ERR_MAP_NOT_FOUND The specified map does not exist
404 ERR_NODE_NOT_FOUND The specified node does not exist

Response Example

{
  "wrapper_type": "MeshAnchor",
  "id": <anchor_ID>,
  "device": { <device_info> },
  "node_id": <node_ID>,
  "node_address": 12003380,
  "node_network_id": 12345678,
  "node_role": "router_node",
  "group": "Blueup",
  "map": { ~ },
  "position": { ~ },
  "zone": { ~ },
  "positioning_enabled": true,
  "calibrated_rssi": -54,
  "rssi_offset": 0,
  "n": 1,
  "last_update": 1744491083,
  "last_update_elapsed": { },
  "battery": 3632,
  "last_update_time": 12,
  "status": "online"
}
Anchor Object (Response)
Key Type Description
wrapper_type string Type wrapper (always MeshAnchor)
id string Unique anchor identifier
device object Device info (model, name, serial)
node_id string Node ID of the anchor
node_address number Mesh network address of the node
node_network_id number Network ID assigned to the node
node_role string Node role in the mesh (e.g. router_node)
group string Logical group or label assigned to the node
map object Associated map info (id, description)
position object Anchor position in 3D space (x, y, z)
zone object Zone info (id, description)
positioning_enabled boolean Whether positioning is enabled
calibrated_rssi number Calibrated RSSI at 1 meter
rssi_offset number RSSI correction offset
n number Environmental factor
last_update number (unix) Timestamp of the last update (seconds since epoch)
last_update_elapsed object Time elapsed since last update (sec)
battery number Battery level or voltage
last_update_time number Alias of last_update_elapsed.sec (for compatibility)
status string Status of the anchor: one of none, online, or offline

DELETE /api/anchor/{id}

Removes an anchor from a map

URL Parameters

Key Type Description Required
id string ID of the anchor to be removed ✓

Responses

Status Code Status Description Description
200 OK Anchor removed successfully
400 ERR_INVALID_ANCHOR_ID The anchor ID is missing or malformed
404 ERR_ANCHOR_NOT_FOUND The specified anchor does not exist or is not an anchor node

GET /api/anchor/{id}

Fetch information about an anchor

URL Parameters

Key Type Description Required
id string ID of the anchor to be retrieved ✓

Responses

Status Code Status Description Description
200 OK Anchor found and returned successfully
400 ERR_INVALID_ANCHOR_ID The anchor ID provided is missing or malformed
404 ERR_ANCHOR_NOT_FOUND No anchor with the specified ID exists

Response Example

{
  "wrapper_type": "MeshAnchor",
  "id": <anchor_ID>,
  "node_id": <node_ID>,
  "node_address": 1,
  "node_network_id": 140114,
  "node_role": <node_role>,
  "map": { ~ },
  "position": { ~ },
  "zone": { ~ },
  "positioning_enabled": false,
  "calibrated_rssi": -54,
  "rssi_offset": 0,
  "n": 1,
  "last_update": 1744457451,
  "last_update_elapsed": { },
  "last_update_time": 39,
  "status": "online"
}
Anchor Object (Response)
Key Type Description
wrapper_type string Type wrapper (always MeshAnchor)
id string Unique anchor identifier
node_id string Anchor hardware node ID
node_address number Mesh network node address
node_network_id number Network ID of the node
node_role string Node role in the mesh (e.g. sink_node)
map object Associated map info (id, description)
position object Anchor position in 3D space (x, y, z)
zone object Zone info (id, description)
positioning_enabled boolean Whether the anchor participates in positioning
calibrated_rssi number Calibrated RSSI value
rssi_offset number RSSI correction offset
n number Environmental factor
last_update number (unix) Timestamp of the last update (in seconds)
last_update_elapsed object Time elapsed since last update (sec)
last_update_time number Last update elapsed time (sec)
status string Anchor status

POST /api/anchor/{id}/position

Changes the anchor position on the map

URL Parameters

Key Type Description Required
id string Node ID that identifies the anchor ✓

Body Parameters

The body must contain a valid 2D position object with the following structure:

Key Type Description Required
x number X coordinate (meters) ✓
y number Y coordinate (meters) ✓
Request Example
{
  "x": 5.5,
  "y": 10.2
}

Responses

Status Code Status Description Description
200 OK Anchor position updated successfully
400 ERR_INVALID_BODY The request body is missing or malformed
400 ERR_INVALID_POSITION The position provided is not valid
400 ERR_INVALID_NODE_ID The node ID is missing or malformed
400 ERR_NODE_NOT_FOUND The specified node does not exist
404 ERR_ANCHOR_NOT_FOUND The node is not an anchor or no anchor found for the node

POST /api/anchor/{id}/settings

Changes positioning settings for an existing anchor

URL Parameters

Key Type Description Required
id string Node ID that identifies the anchor ✓

Body Parameters

Key Type Description Required
positioning_enabled boolean Whether positioning should be enabled ✕
calibrated_rssi number Calibrated RSSI at 1 meter (range: -90 to -20 dBm) ✕
rssi_offset number RSSI correction offset (range: -30 to +30 dBm) ✕
n number Environmental factor (range: 0.1 to 4.0) ✕
Request Example
{
  "positioning_enabled": true,
  "calibrated_rssi": -54,
  "rssi_offset": 0,
  "n": 1
}

Responses

Status Code Status Description Description
200 OK Settings updated successfully and anchor returned
400 ERR_INVALID_BODY The request body is missing or malformed
400 ERR_INVALID_NODE_ID The anchor ID is missing or invalid
400 ERR_INVALID_RSSI_OFFSET The RSSI offset is outside the valid range
400 ERR_INVALID_ENVIRONMENTAL_FACTOR The environmental factor is outside the valid range
400 ERR_INVALID_CALIBRATED_RSSI The calibrated RSSI is outside the valid range
404 ERR_ANCHOR_NOT_FOUND No anchor with the specified ID exists

Response Example

{
  "wrapper_type": "MeshAnchor",
  "id": <anchor_ID>,
  "device": { <device_info> },
  "node_id": <node_ID>,
  "node_address": 12003380,
  "node_network_id": 12345678,
  "node_role": "router_node",
  "group": "Blueup",
  "map": { ~ },
  "position": { ~ },
  "zone": { ~ },
  "positioning_enabled": true,
  "calibrated_rssi": -54,
  "rssi_offset": 0,
  "n": 1,
  "last_update": 1744491083,
  "last_update_elapsed": { },
  "battery": 3632,
  "last_update_time": 12,
  "status": "online"
}
Anchor Object (Response)
Key Type Description
wrapper_type string Type wrapper (always MeshAnchor)
id string Unique anchor identifier
device object Device info (model, name, serial)
node_id string Node ID of the anchor
node_address number Mesh network address of the node
node_network_id number Network ID assigned to the node
node_role string Node role in the mesh (e.g. router_node)
group string Logical group or label assigned to the node
map object Associated map info (id, description)
position object Anchor position in 3D space (x, y, z)
zone object Zone info (id, description)
positioning_enabled boolean Whether positioning is enabled
calibrated_rssi number Calibrated RSSI at 1 meter
rssi_offset number RSSI correction offset
n number Environmental factor
last_update number (unix) Timestamp of the last update (seconds since epoch)
last_update_elapsed object Time elapsed since last update (sec)
battery number Battery level or voltage
last_update_time number Alias of last_update_elapsed.sec (for compatibility)
status string Status of the anchor: one of none, online, or offline

GET /api/anchors

Get all anchors created on all maps

This API supports optional FTR Query filters. Go to the FTR Queries section for more information.

Responses

Status Code Status Description Description
200 OK List of anchors returned successfully
500 ERR_FTR_QUERY The provided FTR query is invalid or processing failed
Response Body

The response is a JSON array of Anchor objects

Response Example

[
  {
    "wrapper_type": "MeshAnchor",
    "id": <anchor_ID>,
    "node_id": <node_ID>,
    "node_address": 1,
    "node_network_id": 140114,
    "node_role": "sink_node",
    "map": { ~ },
    "position": { ~ },
    "positioning_enabled": true,
    "calibrated_rssi": -54,
    "rssi_offset": 0,
    "n": 1,
    "last_update": 1744457451,
    "status": "online"
  },
  ...
]

Each object in the array is a complete Anchor representation. Advanced filtering is supported via FTR queries.

POST /api/anchors

Place a list of anchors on a map

Body Parameters

Key Type Description Required
map number ID of the map where anchors will be placed ✓
anchors array List of anchors with their properties and positioning data ✓
Each anchor in the anchors array should be structured as follows:
Key Type Description Required
id string Node ID of the anchor ✓
position object 2D coordinates (x, y) where the anchor will be placed ✓
positioning_enabled boolean Whether positioning is enabled for this anchor (default: true) ✕
calibrated_rssi number Calibrated RSSI at 1 meter ✕
rssi_offset number RSSI correction offset ✕
n number Environmental factor ✕

Request Example

{
  "map": 2,
  "anchors": [
    {
      "id": "S1-140114",
      "position": {
        "x": 1.0,
        "y": 2.0
      },
      "positioning_enabled": true,
      "calibrated_rssi": -54,
      "rssi_offset": 0,
      "n": 1
    },
    {
      "id": "S1-140115",
      "position": {
        "x": 5.0,
        "y": 6.0
      }
    }
  ]
}

Responses

Status Code Status Description Description
200 OK All anchors processed successfully
400 ERR_INVALID_BODY The request body is missing or malformed
400 ERR_MISSING_MAP_ID The map ID is not provided
400 ERR_MISSING_ANCHOR_LIST The list of anchors is missing
400 ERR_INVALID_ANCHOR_LIST The anchor list is not an array of valid objects
400 ERR_MISSING_ANCHOR_ID One of the anchors does not specify an id
400 ERR_MISSING_ANCHOR_POSITION One of the anchors does not include a valid position
400 ERR_INVALID_ANCHOR_POSITION One of the anchor positions is invalid
404 ERR_MAP_NOT_FOUND The specified map was not found

GET /api/beacon/anchors

Get information about all the beacon router nodes detected by the system.

This API supports optional FTR Query filters. Go to the FTR Queries section for more information.

Responses

Status Code Status Description Description
200 OK n/a

Response Example

[
  {
    "from_cache": false,
    "wrapper_type": "MeshBeaconAnchor",
    "id": <beacon_anchor_id>,
    "node_id": <node_id>,
    "node_address": 9000001,
    "node_network_id": 8369957,
    "node_role": "router_node",
    "beaconing": "ibeacon",
    "ibeacon_uuid": "acfd065ec3c011e39bbe1a514932ac01",
    "ibeacon_major": 9,
    "ibeacon_minor": 1,
    "advertising_interval": 1000,
    "advertising_tx_power": 0,
    "map": {
      "id": 6,
      "description": "Sample Building 1st Floor"
    },
    "position": { ~ },
    "last_update": 1714653185,
    "last_update_time": 40,
    "battery": 3042,
    "status": "online"
  }
]

GET /api/beacon/tags

Get information about all the beacon non-router nodes detected by the system.

This API supports optional FTR Query filters. Go to the FTR Queries section for more information.

Responses

Status Code Status Description Description
200 OK n/a

Response Example

[
  {
    "from_cache": false,
    "wrapper_type": "MeshBeaconTag",
    "id": <beacon_tag_id>,
    "node_id": <node_id>,
    "node_address": 10003413,
    "node_network_id": 8369957,
    "node_role": "non_router_node",
    "beaconing": "safety",
    "safety_uuid": "a565cc841e0e4b5ab2d317c98ff5410a",
    "safety_major": 3413,
    "default_advertising_interval": 1000,
    "motion_advertising_interval": 300,
    "alarm_advertising_interval": 100,
    "sleep_advertising_interval": 2500,
    "advertising_tx_power": 0,
    "last_update": 1714653102,
    "last_update_time": 28,
    "battery": 2922,
    "status": "online"
  }
]

GET /api/beacons

Get information about all the beacon nodes detected by the system.

This API supports optional FTR Query filters. Go to the FTR Queries section for more information.

Responses

Status Code Status Description Description
200 OK n/a

Response Example

[
  {
    "from_cache": false,
    "wrapper_type": "MeshBeaconAnchor",
    "id": <beacon_id>,
    "node_id": <node_id>,
    "node_address": 9000001,
    "node_network_id": 8369957,
    "node_role": "router_node",
    "beaconing": "ibeacon",
    "ibeacon_uuid": "acfd065ec3c011e39bbe1a514932ac01",
    "ibeacon_major": 9,
    "ibeacon_minor": 1,
    "advertising_interval": 1000,
    "advertising_tx_power": 0,
    "map": {
      "id": 6,
      "description": "Sample Building 1st Floor"
    },
    "position": { ~ },
    "last_update": 1714655173,
    "last_update_time": 29,
    "battery": 3042,
    "status": "online"
  },
  {
    "from_cache": false,
    "wrapper_type": "MeshBeaconTag",
    "id": <beacon_id>,
    "node_id": <node_id>,
    "node_address": 20003421,
    "node_network_id": 8369957,
    "node_role": "non_router_node",
    "beaconing": "safety",
    "safety_uuid": "a565cc841e0e4b5ab2d317c98ff54114",
    "safety_major": 3421,
    "default_advertising_interval": 1000,
    "motion_advertising_interval": 300,
    "alarm_advertising_interval": 100,
    "sleep_advertising_interval": 2500,
    "advertising_tx_power": 0,
    "last_update": 1714655133,
    "last_update_time": 70,
    "battery": 2970,
    "status": "online"
  }
]

GET /api/event-listener

This request is used to generate a Listener that retrieves the Events generated by the system.

The request generates a token that has to be used in the /api/events/{token} to be able to receive the events.

Parameters

If no parameters are added, the Listener retrieves all the events generated by the system and devices. Otherwise it is possible to specify one or more events to listen to.

In addition, it is possible to specify the timeout of the token, i.e., the validity of the token in seconds.

Key Value Optional
events Event(s) name ✓
timeout Value in seconds ✓
Request example

localhost/api/event-listener?events=meshNonRouterNodesDetectionUpdate,meshSensorDataUpdated&timeout=60

Responses

Status Code Status Description Description
200 OK n/a

Response Example

{
  "token": <token>
}

GET /api/events/{token}

This request is used to fetch the Events generated by the system.

The request needs the token generated by /api/event-listener request.

URL Parameters

Key Description
token The token generated by the api /api/event-listener

Responses

Status Code Status description Description
200 OK The response will contain an array of events generated by the system
400 ERR_MISSING_TOKEN No token was specified in the request
404 ERR_LISTENER_NOT_FOUND The listener associated to the token does not exist or is expired

Response Example

[
    {
        "id": <eventID>,
        "sequence_number": 6139,
        "timestamp": 1708613562059,
        "data": {<event_data>}
    },
    {
        "id": <eventID>,
        "sequence_number": 6140,
        "timestamp": 1708613563015,
        "data": {<event_data>}
    }
]

POST /api/gateway/{id}

This API allows to invoke the internal APIs of a gateway connected to the system using the "Remote control" option.

Note 1 Use this API carefully. For example, disabling the remote Control on the Gateway will break this API.

Note 2 The documentation about BlueUp Gateway APIs are available on BlueUp Docs.

URL Parameters

Key Description
id The gateway id

Body request example

{
  "timeout": 10, // Optional (default: 10), unit: Seconds,
  "method": "GET | POST | DELETE", // The http method,
  "target": "api/system", // The Gateway API target url,
  "body": {} // The request body (could be optional or mandatory, depending on the API)
}

Responses

Status Code Status Description Description
503 ERR_MQTT_BROKER_NOT_RUNNING The MQTT Mesh Broker is not connected/configured
503 ERR_MQTT_INTERFACE_DISCONNECTED The MQTT Mesh Client was not connected when attempting to invoke the API
503 ERR_MQTT_PUBLISH_ERROR The MQTT Mesh Client was not able to publish the request on the MQTT Broker
408 ERR_TIMEOUT The system did not receive a response within the set timeout
404 ERR_GATEWAY_NOT_FOUND The target Gateway was not found
400 ERR_MISSING_REQUEST_BODY No body was passed to the request
400 ERR_MISSING_BODY_PARAMETER One or more required parameters was not included in the request body
xxx Specific Gateway response The Gateway response

GET /api/gateways

Get information about all the gateways connected to the system.

This API supports optional FTR Query filters. Go to the FTR Queries section for more information.

Responses

Status Code Status Description Description
200 OK The response contains an array of gateways connected to the system with related information

Response Example

[
    {
        "id": <gateway_id>,
        "model": <gateway_model>,
        "blueup_device": true,
        "device_type": "tinygateway",
        "device_variant": "eth", #available variants for TinyGateway gateways are WiFi, Ethernet, LTE
        "ip_address": <gateway_ip>,
        "sink_id": "sink0",
        "sink_on": true,
        "node_address": 1,
        "network_address": 31415,
        "network_channel": 6,
        "fw_version": "1.5.1.284",
        "www_version": "1.7.0.18",
        "os_version": "4.4.6",
        "api_version": 2,
        "diagnostics_interval": 60,
        "seq_app_config": 6,
        "has_app_config": true,
        "last_update_time": 17,
        "last_update": 1713796401,
        "is_running": true
    }
]

GET /api/healthcheck

Get the system healthcheck to assess if the system is running.

Responses

Status Code Status Description Description
200 n/a n/a

POST /api/map

Create a new map

Body Parameters

Key Type Description Optional
description string The map description (max length: 64 characters) ×
pixel_per_mt number The map scale (the amount of pixels per meter, min: 1px) ×
image string The image data, base64 encoded ×
z number The height of the map (unit: meters, default: 0m) ✓
gps object The GPS settings of the map ✓
GPS Object Field (if provided)
Key Type Description
x number Reference X point on the map (default: 0)
y number Reference Y point on the map (default: 0)
lat number Latitude in degrees
lng number Longitude in degrees
north number Map north angle

Body Example

{
    "description": "My Map",
    "pixel_per_mt": 100,
    "image": "iVBORw0KGgoAAAANSUhE...",
    "z": 0,
    "gps": {
        "lat": 12.0,
        "lng": 34.0,
        "north": 56.0
    }
}

Responses

Status Code Status Description Description
200 OK The map was created on the system
400 ERR_INVALID_BODY The body request is empty or malformed
400 ERR_MAP_QUOTA_EXCEEDED The map cannot be created: the MaxAllowedMaps license limit was exceeded
400 ERR_INVALID_DESCRIPTION The provided description is missing or invalid
400 ERR_INVALID_IMAGE The provided image is not valid or does not meet the constraints
500 ERR_MAP_CREATE The system is unable to create the map. Details are provided in the body response

Response Example

{
    "id": 8,
    "description": "Test API Map Create",
    "pixel_per_mt": 100,
    "z": 0,
    "gps_coordinates": false,
    "image": {
        "id": "5eb7abdb-4fc6-46df-9291-db4f33b007f2",
        "type": "image/png",
        "url": "/map/5eb7abdb-4fc6-46df-9291-db4f33b007f2",
        "thumbnail": "/map/5eb7abdb-4fc6-46df-9291-db4f33b007f2/thumb",
        "size": 771216,
        "width": 1440,
        "height": 406
    },
    "offset": {
        "x": 0,
        "y": 0,
        "z": 0
    },
    "area": {
        "vertexes": [
            { "x": 0, "y": 0, "z": 0 },
            { "x": 0, "y": 4, "z": 0 },
            { "x": 14, "y": 4, "z": 0 },
            { "x": 14, "y": 0, "z": 0 }
        ]
    },
    "zones": [],
    "exclusion_areas": [],
    "guides": [],
    "placeholders": [],
    "path_points": []
}
Map Object (Response)

The following fields are returned when a map is successfully created:

Key Type Description
id number Unique identifier of the map
description string Map description
pixel_per_mt number Number of pixels per meter (map scale)
z number Height (elevation) of the map in meters
gps_coordinates boolean Indicates if GPS coordinates are present or valid
image object Image object describing the map image (see Image Object)
offset object 3D offset position of the map origin
area object Area defined by vertexes (polygon representing the map boundary)
zones array List of zones defined in the map
exclusion_areas array List of areas to be excluded from the map logic
guides array List of guide elements (optional)
placeholders array List of placeholder elements positioned on the map
path_points array List of reference points or path nodes
Image Object

The image field in the response is an object with the following structure:

Key Type Description
id string Unique identifier of the image
type string MIME type of the image (e.g., image/png)
url string URL to access the full image
thumbnail string URL to access a resized preview (if available)
size number Size of the image in bytes
width number Width of the image in pixels
height number Height of the image in pixels
Offset Object

The origin of the map in 3D space.

Key Type Description
x number X coordinate
y number Y coordinate
z number Z coordinate
Area Object (Reserved for Future Use)

Polygon that defines the full boundary of the map.

Key Type Description
vertexes array List of 3D points forming a closed polygon
Zones Array

List of defined map zones, each as a polygon with additional metadata.

Key Type Description
id string Zone identifier
description string Human-readable name or label
color string Hex color code
z number Height level
vertexes array List of 3D coordinates defining shape
Placeholders Array

List of placeholder elements used for placing anchors or gateways.

Key Type Description
id string Unique identifier
number number Reference number (e.g., label)
color string Display color in hex format
position object 3D coordinates (x, y, z)

DELETE /api/map/{id}

Deletes a map

URL Parameters

Key Type Description Required
id number ID of the map to delete ✓

Responses

Status Code Status Description Description
200 OK Map deleted successfully
400 ERR_INVALID_MAP_ID The map ID provided is missing or malformed
400 ERR_MAP_NOT_FOUND No map with the specified ID exists
400 ERR_MAP_DELETE The map could not be removed from storage

This API does not return a response body. A status code 200 indicates success.

GET /api/map/{id}

Fetch information for an existing map

URL Parameters

Key Type Description Required
id number ID of the map to be retrieved ✓

Responses

Status Code Status Description Description
200 OK Map found and returned successfully
400 ERR_INVALID_MAP_ID The map ID provided is invalid or malformed
404 ERR_MAP_NOT_FOUND No map with the specified ID exists

Response Example

{
    "id": 8,
    "description": "Test API Map Create",
    "pixel_per_mt": 100,
    "z": 0,
    "gps_coordinates": false,
    "image": {
        "id": "5eb7abdb-4fc6-46df-9291-db4f33b007f2",
        "type": "image/png",
        "url": "/map/5eb7abdb-4fc6-46df-9291-db4f33b007f2",
        "thumbnail": "/map/5eb7abdb-4fc6-46df-9291-db4f33b007f2/thumb",
        "size": 771216,
        "width": 1440,
        "height": 406
    },
    "offset": {
        "x": 0,
        "y": 0,
        "z": 0
    },
    "area": {
        "vertexes": [
            { "x": 0, "y": 0, "z": 0 },
            { "x": 0, "y": 4, "z": 0 },
            { "x": 14, "y": 4, "z": 0 },
            { "x": 14, "y": 0, "z": 0 }
        ]
    },
    "zones": [],
    "exclusion_areas": [],
    "guides": [],
    "placeholders": [],
    "path_points": []
}

POST /api/map/{id}

Update information for an existing map

URL Parameters

Key Type Description Required
id number ID of the map to update ✓

Body Parameters

Key Type Description Required
description string New description of the map ✕
z number New height of the map (meters) ✕
gps object / null GPS settings (object with lat/lng/north) or null to disable GPS ✕
GPS Object (if provided)
Key Type Description
x number Reference X point on the map (default: 0)
y number Reference Y point on the map (default: 0)
lat number Latitude in degrees
lng number Longitude in degrees
north number Map north angle (°)
Request Example
{
  "description": "Updated map name",
  "z": 2.5,
  "gps": {
    "lat": 45.4642,
    "lng": 9.1900,
    "north": 0
  }
}

Responses

Status Code Status Description Description
200 OK Map updated successfully or no changes were applied
400 ERR_INVALID_MAP_ID The map ID is missing or malformed
400 ERR_INVALID_BODY The request body is missing or malformed
404 ERR_MAP_NOT_FOUND No map with the specified ID exists

GET /api/maps

Get information about all the maps setup in the system.

This API supports optional FTR Query filters. Go to the FTR Queries section for more information.

Responses

Status Code Status Description Description
200 OK The response contains an array of maps setup in the system with related information

Response Example

[
    {
        "id": 2,
        "description": "BlueUp office",
        "pixel_per_mt": 47,
        "z": 0,
        "gps_coordinates": false,
        "image": {
            "id": <image_id>,
            "type": "image/png",
            "url": <image_url>,
            "size": 270220,
            "width": 883,
            "height": 649
        },
        "offset": {<map_origin_coordinates>},
        "area": {
            "vertexes": [<map_vertexes>]
        },
        "zones": [
            {
                "id": "meeting-room",
                "description": "Meeting room",
                "color": "#4169E1",
                "z": 0,
                "vertexes": [<zone_vertexes>]
            },
            {
                "id": "management",
                "description": "Management",
                "color": "#a9e141",
                "z": 0,
                "vertexes": [<zone_vertexes>]
            }
        ],
        "exclusion_areas": [
            {
                "id": <exclusion_area_id>,
                "vertexes": [<zone_vertexes>]
            }
        ],
        {
        "guides": [<array_of_guides>],
        "placeholders": [
            {
                "id": "752851da-63a4-4305-820a-590daac6cc1a",
                "number": 47,
                "color": "#740af5",
                "position": {
                    "x": 15.17,
                    "y": 5.65,
                    "z": 0
                }
            }
        ]
    }
]

GET /api/mesh-packets.db

Get The mesh packets database file

GET /api/network/{address}

API that retrieves the network configurations for the specific network address.

URL Parameters

Key Description
address The network address

Responses

Status Code Status Description Description
200 OK n/a
404 ERR_NETWORK_NOT_FOUND The network was not found

Response Example

[
    {
        "address": 12345678,
        "description": <network_description>,
        "active": <active_configuration_id>,
        "templates": [
            {
                "id": <configuration_id>,
                "description": <configuration_description>,
                "last_update": <unix-timestamp-milliseconds>,
                "is_editable": true,
                "is_removable": true,
                "setup": {
                    "diagnostics_interval": 300,
                    "configuration": [
                        {
                            "node_class": "F9",
                            "packet_type": "A2",
                            "parameters": {
                                "sensing_interval": 300,
                                "alerts_enabled": true,
                                "off_by_position": false,
                                "beaconing": "disabled"
                            }
                        },
                        {
                            "node_class": "FA",
                            "packet_type": "B2",
                            "parameters": {
                                "default_positioning_interval": 60,
                                "default_timeout": 65,
                                "default_autoscan_enabled": false,
                                "motion_positioning_interval": 10,
                                "motion_timeout": 60,
                                "motion_autoscan_enabled": false,
                                "alarm_positioning_interval": 10,
                                "alarm_timeout": 60,
                                "alarm_autoscan_enabled": false,
                                "sleep_positioning_interval": 3600,
                                "sleep_autoscan_enabled": true,
                                "alerts_enabled": true,
                                "button_enabled": true,
                                "accelerometer_mode": "motion_detection",
                                "motion_threshold": 10,
                                "motion_duration": 1,
                                "beaconing": "disabled"
                            }
                        }
                    ]
                }
            },
            { ~ }

        ]
    }
]

POST /api/network/{address}/{configuration}

API that sets a specific configuration for the specific network address.
The configuration has to be specified in the Body of the API call.

URL Parameters

Key Description
address The network address
configuration The configuration template identifier

Body

{
  "diagnostics_interval": 300,
  "configuration": [
    {
      "node_class": "F9",
      "packet_type": "A2",
      "parameters": {
        "sensing_interval": 300,
        "alerts_enabled": true,
        "off_by_position": false,
        "beaconing": "disabled"
      }
    },
    {
      "node_class": "FA",
      "packet_type": "B2",
      "parameters": {
        "default_positioning_interval": 120,
        "default_timeout": 65,
        "default_autoscan_enabled": false,
        "motion_positioning_interval": 10,
        "motion_timeout": 60,
        "motion_autoscan_enabled": false,
        "alarm_positioning_interval": 10,
        "alarm_timeout": 60,
        "alarm_autoscan_enabled": false,
        "sleep_positioning_interval": 3600,
        "sleep_autoscan_enabled": true,
        "alerts_enabled": true,
        "button_enabled": true,
        "accelerometer_mode": "motion_detection",
        "motion_threshold": 10,
        "motion_duration": 1,
        "beaconing": "disabled"
      }
    }
  ]
}
Acceptable diagnostics intervals
Value Description
0 Disabled
30 30 sec
60 1 min
120 2 min
300 5 min
600 10 min
1800 30 min

Whether the diagnostic interval is disabled, the nodes will not send their diagnostics information, including routing.

Responses

Status Code Status Description Description
200 OK n/a
400 ERR_MISSING_CONFIG_ID The request body does not contain the required data
400 ERR_MISSING_CONFIG_DATA The configuration data is missing
400 ERR_NETWORK_CONFIGURATION_INVALID The passed configuration is not valid
404 ERR_NETWORK_NOT_FOUND The network was not found
400 ERR_NETWORK_CONFIGURATION_READONLY The configuration cannot be changed (readonly)

Response Example

{
  "changed": true
}

GET /api/network/{address}/{configuration}

API that retrieves a specific configuration for the specific network address.

URL Parameters

Key Description
address The network address
configuration The configuration template identifier

Responses

Status Code Status Description Description
200 OK n/a
404 ERR_NETWORK_NOT_FOUND The network was not found
404 ERR_NETWORK_CONFIGURATION_NOT_FOUND The network configuration was not found

Response Example

[
    {
        "address": 12345678,
        "description": <network_description>,
        "active": <active_configuration_id>,
        "templates": [
            {
                "id": <configuration_id>,
                "description": <configuration_description>,
                "is_editable": true,
                "is_removable": true,
                "setup": {
                    "diagnostics_interval": 300,
                    "configuration": [
                        {
                            "node_class": "F9",
                            "packet_type": "A2",
                            "parameters": {
                                "sensing_interval": 300,
                                "alerts_enabled": true,
                                "off_by_position": false,
                                "beaconing": "disabled"
                            }
                        },
                        {
                            "node_class": "FA",
                            "packet_type": "B2",
                            "parameters": {
                                "default_positioning_interval": 60,
                                "default_timeout": 65,
                                "default_autoscan_enabled": false,
                                "motion_positioning_interval": 10,
                                "motion_timeout": 60,
                                "motion_autoscan_enabled": false,
                                "alarm_positioning_interval": 10,
                                "alarm_timeout": 60,
                                "alarm_autoscan_enabled": false,
                                "sleep_positioning_interval": 3600,
                                "sleep_autoscan_enabled": true,
                                "alerts_enabled": true,
                                "button_enabled": true,
                                "accelerometer_mode": "motion_detection",
                                "motion_threshold": 10,
                                "motion_duration": 1,
                                "beaconing": "disabled"
                            }
                        }
                    ]
                }
            },
            { ~ }

        ]
    }
]

DELETE /api/network/{address}/{configuration}

API that deletes a specific configuration for the specific network address.

URL Parameters

Key Description
address The network address
configuration The configuration template identifier

Responses

Status Code Status Description Description
200 OK n/a
404 ERR_NETWORK_NOT_FOUND The network was not found
404 ERR_NETWORK_CONFIGURATION_NOT_FOUND The network configuration was not found
400 ERR_NETWORK_CONFIGURATION_ACTIVE The configuration cannot be deleted when it is the active one
400 ERR_NETWORK_CONFIGURATION_DEFAULT The default configuration of a network cannot be deleted

GET /api/network/{address}/{configuration}/app-config

API that retrieves the AppConfig of a specific configuration for the specific network address.

URL Parameters

Key Description
address The network address
configuration The configuration template identifier

Responses

Status Code Status Description Description
200 OK n/a
404 ERR_NETWORK_NOT_FOUND The network was not found
404 ERR_NETWORK_CONFIGURATION_NOT_FOUND The network configuration was not found

Response Example

Content-Type is text/plain

f9a204012c0100fab2140078000a000a0e100041003c003c0023010a01000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000

GET /api/network/{address}/{configuration}/apply

API that applies a specific configuration to the specific network.

URL Parameters

Key Description
address The network address
configuration The configuration template identifier

Responses

Status Code Status Description Description
200 OK n/a
404 ERR_NETWORK_NOT_FOUND The network was not found
404 ERR_NETWORK_CONFIGURATION_NOT_FOUND The network configuration was not found
503 ERR_SERVICE_UNAVAILABLE The Mesh Handler is not active

Response Example

{
  "applied": true
}

POST /api/network/{address}/{configuration}/create

Create a new configuration for a specific network address.

The new configuration has to be specified in the Body of the API call.

URL Parameters

Key Description
address The network address
configuration The configuration template identifier

Body

{
  "description": <Configuration_description>,
  "diagnostics_interval": 300,
  "configuration": [
    {
      "node_class": "F9",
      "packet_type": "A2",
      "parameters": {
        "sensing_interval": 300,
        "alerts_enabled": true,
        "off_by_position": false,
        "beaconing": "disabled"
      }
    },
    {
      "node_class": "FA",
      "packet_type": "B2",
      "parameters": {
        "default_positioning_interval": 120,
        "default_timeout": 65,
        "default_autoscan_enabled": false,
        "motion_positioning_interval": 10,
        "motion_timeout": 60,
        "motion_autoscan_enabled": false,
        "alarm_positioning_interval": 10,
        "alarm_timeout": 60,
        "alarm_autoscan_enabled": false,
        "sleep_positioning_interval": 3600,
        "sleep_autoscan_enabled": true,
        "alerts_enabled": true,
        "button_enabled": true,
        "accelerometer_mode": "motion_detection",
        "motion_threshold": 10,
        "motion_duration": 1,
        "beaconing": "disabled"
      }
    }
  ]
}
Acceptable diagnostics intervals
Value Description
0 Disabled
30 30 sec
60 1 min
120 2 min
300 5 min
600 10 min
1800 30 min

Whether the diagnostic interval is disabled, the nodes will not send their diagnostics information, including routing.

Responses

Status Code Status Description Description
200 OK n/a
400 ERR_MISSING_CONFIG_DATA The configuration data is missing
404 ERR_NETWORK_NOT_FOUND The network was not found
400 ERR_NETWORK_CONFIGURATION_ALREADY_EXISTS The configuration already exists

Response Example

The API response will return the above created configuration.

GET /api/networks

This API retrieves the list of all the networks in the MeshCube instance and for each network reports the network configurations.

This API supports optional FTR Query filters. Go to the FTR Queries section for more information.

Responses

Status Code Status Description Description
200 OK The response contains an array of networks with related configurations

Response Example

[
    {
        "address": 12345678,
        "description": <network_description>,
        "active": <active_configuration_id>,
        "templates": [
            {
                "id": <configuration_id>,
                "description": <configuration_description>,
                "last_update": <unix-timestamp-milliseconds>,
                "is_editable": true,
                "is_removable": true,
                "setup": {
                    "diagnostics_interval": 300,
                    "configuration": [
                        {
                            "node_class": "F9",
                            "packet_type": "A2",
                            "parameters": {
                                "sensing_interval": 300,
                                "alerts_enabled": true,
                                "off_by_position": false,
                                "beaconing": "disabled"
                            }
                        },
                        {
                            "node_class": "FA",
                            "packet_type": "B2",
                            "parameters": {
                                "default_positioning_interval": 60,
                                "default_timeout": 65,
                                "default_autoscan_enabled": false,
                                "motion_positioning_interval": 10,
                                "motion_timeout": 60,
                                "motion_autoscan_enabled": false,
                                "alarm_positioning_interval": 10,
                                "alarm_timeout": 60,
                                "alarm_autoscan_enabled": false,
                                "sleep_positioning_interval": 3600,
                                "sleep_autoscan_enabled": true,
                                "alerts_enabled": true,
                                "button_enabled": true,
                                "accelerometer_mode": "motion_detection",
                                "motion_threshold": 10,
                                "motion_duration": 1,
                                "beaconing": "disabled"
                            }
                        }
                    ]
                }
            },
            { ~ }

        ]
    }
]

GET /api/network-tree/{network}

API that retrieves the tree structure of the network. This API can be used to inspect the network organization: how the nodes are connected to the sink.

URL Parameters

Key Description
address network address

Responses

Status Code Status Description Description
200 OK n/a
404 ERR_NETWORK_NOT_FOUND The network was not found

Response Example

{
  "network": 12345678,
  "items": [
    {
      "type": 1,
      "id": <sink_id>, // type = 1  corresponds to the sink node
      "items": [
        {
          "type": 2,
          "id": <router_node_id>, // type = 2  corresponds to the router node
          "hop_count": 1,
          "radio_installation_quality": 100,
          "radio_installation_errors": 0,
          "items": []
        },
        {
          "type": 2,
          "id": <router _node_id>, // type = 2  corresponds to the router node
          "hop_count": 1,
          "radio_installation_quality": 100,
          "radio_installation_errors": 0,
          "items": [
            {
              "type": 2,
              "id": <router_node_id>, // type = 2  corresponds to the router node
              "parent": <parent_node_id>,
              "quality": 94,
              "power": 4,
              "rssi": -69,
              "hop_count": 2,
              "radio_installation_quality": 100,
              "radio_installation_errors": 0,
              "items": [
                {
                  "type": 3,
                  "id": <non_router_node_id>, // type = 3  corresponds to the non router node
                  "parent": <parent_node_id>,
                  "quality": 100,
                  "power": -20,
                  "rssi": -41,
                  "hop_count": 3
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

DELETE /api/node/{id}

Delete a node from the system, when not more used. The nodes must be not online.

URL Parameters

Key Description
id Node unique identifier, composed by:
- Node type prefix: S Sink, R Router node, N Non Router node.
- Node address
- Network address

Responses

Status Code Status Description Description
200 OK n/a
404 ERR_NOT_FOUND The node id was not found
400 ERR_CANNOT_DELETE_ONLINE_NODE Cannot delete online nodes

GET /api/node/{id}

Get information about the node having a given ID.

Specify the Node ID

URL Parameters

Key Description
id Node unique identifier, composed by:
- Node type prefix: S Sink, R Router node, N Non Router node.
- Node address
- Network address

Responses

Status Code Status Description Description
200 OK n/a
404 ERR_NOT_FOUND The node id was not found

Response Example

{
    "from_cache": false,
    "id": <Node_ID>,
    "address": 5003408,
    "network_id": 15074110,
    "device": {<device_id>},
    "version": "3.12",
    "node_class": "FB",
    "operation_mode": "autoscan_tag",
    "alarm": "none",
    "state": "sleep",
    "state_time": 183563,
    "role": "non_router_node",
    "low_latency": false,
    "autorole": false,
    "max_buffer_usage": 2,
    "avg_buffer_usage": 0,
    "routers_in_neighborhood": 1,
    "scans": 237,
    "battery": 2970,
    "nodes": {
        "timestamp": 1708505215,
        "travel_time": 0,
        "count": 1,
        "items": [<nodes_array> ]
    },
    "routing": {<routing_info>},
    "has_configuration": true,
    "configuration_status": "missing",
    "last_update": 1708505246,
    "last_update_time": 97661,
    "last_update_elapsed": {},
    "status": "offline"
}

GET /api/node/{id}/alias

Retrieve the alias set on the node.

Specify the Node ID

URL Parameters

Key Description
id Node unique identifier, composed by:
- Node type prefix: S Sink, R Router node, N Non Router node.
- Node address
- Network address

Responses

Status Code Status Description Description
200 OK

Response Example

{
    "id": <nodeID>,
    "alias": <alias>
}

DELETE /api/node/{id}/alias

Delete the alias set on the node.

URL Parameters

Key Description
id Node unique identifier, composed by:
- Node type prefix: S Sink, R Router node, N Non Router node.
- Node address
- Network address

Responses

Status Code Status Description Description
200 OK n/a
400 ERR_NOT_FOUND The node id was not found

Response Example

{
  "id": <nodeID>,
  "alias": null
}

POST /api/node/{id}/alias

Set the alias to the node.

URL Parameters

Key Description
id Node unique identifier, composed by:
- Node type prefix: S Sink, R Router node, N Non Router node.
- Node address
- Network address

Body

{
  "alias": `string`
}

Responses

Status Code Status Description Description
200 OK n/a
400 ERR_NOT_FOUND The node id was not found

Response Example

{
  "id": <nodeID>,
  "alias": <alias>
}

DELETE /api/node/{id}/group

Delete the group set on the node.

URL Parameters

Key Description
id Node unique identifier, composed by:
- Node type prefix: S Sink, R Router node, N Non Router node.
- Node address
- Network address

Responses

Status Code Status Description Description
200 OK n/a
400 ERR_NOT_FOUND The node id was not found

Response Example

{
  "id": `string`,
  "group": null
}

POST /api/node/{id}/group

Set the group to the node.

URL Parameters

Key Description
id Node unique identifier, composed by:
- Node type prefix: S Sink, R Router node, N Non Router node.
- Node address
- Network address

Body

{
  "group": `string`
}

Responses

Status Code Status Description Description
200 OK n/a
400 ERR_NOT_FOUND The node id was not found

Response Example

{
  "id": `string`,
  "group": `string` | null
}

GET /api/node/{id}/group

Retrieve the group set on the node.

Specify the Node ID

URL Parameters

Key Description
id Node unique identifier, composed by:
- Node type prefix: S Sink, R Router node, N Non Router node.
- Node address
- Network address

Responses

Status Code Status Description Description
200 OK

Response Example

{
    "id": `string`,
    "group": `string` | null
}

POST /api/node/{id}/subnet

Set a subnet for node

GET /api/node/{id}/subnet

Get node alias

GET /api/nodes

Get information about all the nodes detected by the system.

This API supports optional FTR Query filters. Go to the FTR Queries section for more information.

Responses

Status Code Status Description Description
200 OK The response contains an array of nodes detected by the system

Response Example

[
    {
        "from_cache": true,
        "id": <sink_id>,
        "address": 1,
        "network_id": 14480430,
        "role": "sink_node",
        "low_latency": true,
        "autorole": false,
        "max_buffer_usage": 0,
        "avg_buffer_usage": 0,
        "routers_in_neighborhood": 9,
        "scans": 8,
        "boot_count": 5,
        "stack_version": "5.3.0.89",
        "app_version": "1.4.0.0",
        "scratchpad_stored_sequence": 0,
        "scratchpad_processed_sequence": 255,
        "is_otap_enabled": true,
        "has_configuration": false,
        "configuration_status": "none",
        "last_update": 1707474364,
        "last_update_time": 1128398,
        "last_update_elapsed": {},
        "status": "none"
    },
    {
        "from_cache": false,
        "id": <router_id>,
        "address": 9000001,
        "network_id": 8369957,
        "device": {<device_info>},
        "version": "3.12",
        "node_class": "F9",
        "operation_mode": "opportunistic_anchor",
        "alarm": "none",
        "state": "default",
        "state_time": 183411,
        "role": "router_node",
        "low_latency": false,
        "autorole": false,
        "max_buffer_usage": 0,
        "avg_buffer_usage": 0,
        "routers_in_neighborhood": 2,
        "scans": 128,
        "battery": 3066,
        "routing": {<routing_info>},
        "has_configuration": true,
        "configuration_status": "matches",
        "last_update": 1708602755,
        "last_update_time": 7,
        "last_update_elapsed": {},
        "status": "online"
    },
    {
        "from_cache": false,
        "id": <non_router_id>,
        "address": 10003412,
        "network_id": 8369957,
        "device": {<device_info>},
        "version": "3.12",
        "node_class": "FA",
        "operation_mode": "nrls_tag",
        "alarm": "none",
        "state": "default",
        "state_time": 617,
        "role": "non_router_node",
        "low_latency": false,
        "autorole": false,
        "max_buffer_usage": 4,
        "avg_buffer_usage": 2,
        "routers_in_neighborhood": 0,
        "scans": 1,
        "battery": 2958,
        "nodes": {
            "timestamp": 1708602712,
            "travel_time": 54,
            "count": 2,
            "items": [<array_of_nodes>]
        },
        "routing": {<routing_info>},
        "has_configuration": true,
        "configuration_status": "matches",
        "last_update": 1708602712,
        "last_update_time": 50,
        "last_update_elapsed": {},
        "status": "online"
    }
]

POST /api/nodes/command

This API allows to send a command to the Node(s) in the network.

Body Parameters

Key Type Description Optional
mode string The send mode (unicast, multicast, broadcast) ✗
ack bool Whether the system should use and acknowledge response from target(s) ✓
timeout number The timeout (ms) of the operation (default: 60sec)) ✓
network number Network ID (if omitted all networks will be impacted) ✓
target number or string The target of the command. unicast, multicast ✗
broadcast✓
type string Command type ✗
data any Command data Depends on command type

In Body of the request has to be defined the command to send to the nodes. The supported commands are:

  • Reboot to reboot the device
  • Change node node-class property
  • Button switch to enable or disable the button
  • Alert to configure the alarm on the device
  • Alert Off to disable buzzer/vibration/led if they were configured as permanent on in the Alert command
  • Gpio to configure GPIO pins
ACK

The ack is supported on firmware 4.4+

Body

Each command requires different data inside the Body.

Reboot body
{
  "type": "reboot"
}

No additional data is required

Change node class
{
  "type": "node_class_change",
  "data": {
    "class": `string`
  }
}
# Valid node classes
  • F9 (Default Anchor class)
  • FA (Default Asset Tag class)
  • FB (Default Personal Tag class)
  • FC
  • FD
  • FE
  • FF
Button switch body
{
  "type": "button_switch",
  "data": {
    "enabled": `boolean`
  }
}
Alert body

Here is an example of the complete Alarm command to be sent.

{
  "type": "alert",
  "data": {
    "buzzer_period": 2,
    "buzzer_repeats": 20,
    "buzzer_duty_cycle": 50,
    "vibration_period": 2,
    "vibration_repeats": 20,
    "vibration_duty_cycle": 50,
    "led_period": 2,
    "led_repeats": 20,
    "led_duty_cycle": 50,
    "led_sequential": false,
    "led_red": true,
    "led_green": true,
    "led_blue": true,
    "led_0": true,
    "led_1": true,
    "led_2": true,
    "led_3": true
  }
}

The unnecessary parameters in data object can be omitted.

Alert Off body
{
  "type": "alert_off"
}
GPIO body
{
    "type": "gpio",
    "data":{
        "pin": <pin_number>,
        "mode": "reset" | "output" | "input",
        "pullcfg": "pulldown" | "pullup", #only in Input mode
        "send_interval": <number> #range [0; 255]
    }
}

Responses

Status Code Status Description Description
200 OK n/a
400 ERR_MISSING_BODY No body present in the request
400 ERR_INVALID_COMMAND The system is not able to parse the command
400 ERR_INVALID_SEND_MODE The specified sending mode in not valid
400 ERR_MISSING_NODE_ADDRESS The node address is missing (raises only for unicast sending mode)
400 ERR_INVALID_NODE_CLASS The specified node class is not valid (raises only for multicast sending mode)
500 ERR_SEND_FAILED Failed to send the command to the Sink(s)
503 ERR_SERVICE_UNAVAILABLE The MQTT Broker is not instantiated
503 ERR_NO_GATEWAY_AVAILABLE No gateway is online to receive the request

POST /api/plugin/{id}/configuration

This request allows to change the configuration of one of the plugins setup in the system.

POST Method

Specify the ID of the plugin in the request

URL Parameters

Key Description
id The plugin identifier

Body

In the body the user has to write the desired configuration of the plugin.

Body example to the request of configuration of SystemNotifications plugin

{
    "recipients": [<list of emails> ],
    "notify_system_start_stop": false,
    "notify_gateway_status": true,
    "notify_node_battery_low": true
}

Responses

Status Code Status Description Description
200 OK The response returns the new configuration parameters set to the plugin
400 ERR_MISSING_ID
400 ERR_MISSING_CONFIG
400 ERR_INVALID_CONFIG
400 ERR_PLUGIN_NOT_CONFIGURABLE Error generated in case the plugin does not support configuration
400 ERR_PLUGIN_CONF_DENIED Error generated when the configuration of the plugin has been denied
404 ERR_NOT_FOUND
500 ERR_UPDATE_CONFIG An error occurred when trying to update the configuration

Response Example

{
    "recipients": [<list of emails> ],
    "notify_system_start_stop": false,
    "notify_gateway_status": true,
    "notify_node_battery_low": true
}

GET /api/plugin/{id}/configuration

This request allows to retrieve the configuration of one of the plugins setup in the system.

Specify the ID of the plugin in the request

URL Parameters

Key Description
id The plugin identifier

Responses

Status Code Status Description Description
200 OK
400 ERR_MISSING_ID
400 ERR_PLUGIN_NOT_CONFIGURABLE Error generated in case the plugin does not support configuration
400 ERR_PLUGIN_CONF_DENIED Error generated when the configuration of the plugin has been denied
404 ERR_NOT_FOUND

Response Example

Response example to the request of configuration of SystemNotifications plugin

{
    "recipients": [<list of emails> ],
    "notify_system_start_stop": false,
    "notify_gateway_status": true,
    "notify_node_battery_low": true
}

GET /api/plugins

Get information about all the Plugins present the system.

The response is composed by an array of plugins and for each plugin is specified its ID, description, version and if the plugin is enabled.

Responses

Status Code Status Description Description
200 OK The response contains as array of plugins configured in the system

Response Example

[
  {
    "id": <PluginID>,
    "description": <Plugin description>,
    "version": {
      "major": 1,
      "minor": 0,
      "revision": 0,
      "stage": "release"
    },
    "icon": <icon>,
    "enabled": true
  }
]

GET /api/sensor/{id}/samples

This API allows to retrieve all the measurement samples of a selected sensor, that are stored in the database.

Specify the Sensor ID

Parameters

If no parameters are added, the API call retrieves all the samples stored in the database. Otherwise it is possible to specify some filtering parameters:

Key Value Optional Description
from number ✓ UNIX timestamp of the starting date and time for the data to retrieve
to number ✓ UNIX timestamp of the stopping date and time for the data to retrieve
type string ✓ Type of measurement to retrieve:
- temperature (or temp)
- co2
- pressure
- humidity

Responses

Status Code Status Description Description
200 OK The response contains the measurement samples required by the user

Response Example

Example of the call that retrieves data of temperature and co2 from a sensor. Request:

/api/sensor/SENSOR_R9000008-12345678/samples?type=temp,co2&from=1714428000000

[
    {
        "timestamp": 1714428182169,
        "co2": 665,
        "temperature": 23.4
    },
    {
        "timestamp": 1714428482197,
        "co2": 612,
        "temperature": 23.3
    },
    {
        "timestamp": 1714428782266,
        "co2": 618,
        "temperature": 23.3
    },
    { ~ }
]

GET /api/sensors

Get information about all the sensors present in the system.

This API supports optional FTR Query filters. Go to the FTR Queries section for more information.

Responses

Status Code Status Description Description
200 OK n/a

Response Example

[
  {
    "from_cache": false,
    "wrapper_type": "MeshSensor",
    "id": <sensor_id>,
    "alias": <sensor_alias>,
    "node_id": <node_id>,
    "node_address": 9000008,
    "node_network_id": 12345678,
    "node_role": "router_node",
    "temperature": {
      "unit": "celsius",
      "value": 26.9
    },
    "humidity": 52,
    "pressure": 98559,
    "co2": {
      "ppm": 448,
      "classification": "excellent"
    },
    "last_update": 1714488630,
    "last_update_time": 6,
    "battery": 2820,
    "status": "online"
  }
]

POST /api/sensors/configuration

This API allows to set the configuration of the Sensors.

POST method

Body

{
  "temperature_unit": "celsius",
  "data_retention_days": 730
}

Responses

Status Code Status Description Description
200 OK n/a

Response Example

{
  "updated": true
}

GET /api/sensors/configuration

This API allows to retrieve the configuration of the Sensors.

Responses

Status Code Status Description Description
200 OK The response contains the sensors configuration

Response Example

{
  "temperature_unit": "celsius",
  "data_retention_days": 730
}

GET /api/status

Get all the information about system status.

Responses

Status Code Status Description Description
200 OK n/a

Response Example

{
  "os": {<os_info>},
  "hostname": "blueupbeacons.com",
  "title": "BlueUp Processing Engine v.6.0.0.59",
  "version": "6.0.0.59",
  "system": {
    "code": "meshcube",
    "description": "MeshCube"
  },
  "license": { <license_info>},
  "timestamp": 1709712155206,
  "activated": true,
  "started_on": 1709670440,
  "uptime": { },
  "network": {<network_info>},
  "processors": 2,
  "pressure": {
    "ram": 141,
    "pram": 3.5,
    "pcpu": 0.7
  }
}

GET /api/system

Get the basic information about the BPE system.

Responses

Status Code Status Description
200 OK

Response Example

{
  "id": `string`,
  "uid": `string`,
  "description": `string`,
  "version": `string`
}

GET /api/system/diagnostics

Get all the information about system diagnostics

Responses

Status Code Status Description
200 OK

Response Example

{
  "eventManager": {
    "description": "EventManager",
    "data": {<data>}
  },
  "localStorage": {
    "description": "Local Storage",
    "data": {<data>}
  },
  "httpServer": {
    "description": "Http Server",
    "data": {<data>}
  }
}

GET /api/system/log

Get the current log content.

Note: The get live log stream, please refer to API: /api/log-stream

Responses

Status Code Status Description Mime type
200 OK text/plain

GET /api/system/log/{file}

Get the log content of a stored log.

URL Parameters

Key Description
file The log file name previously obtained calling /api/system/logs API

Responses

Status Code Status Description Mime type
200 OK text/plain

GET /api/system/logs

Get an array of the execution logs stored by the system.

Each item of the logs array identifies a log, with following properties:

  • name: The log filename
  • size: The log size (bytes)
  • current: Whether the log is the one the system is currently writing (true | false)
  • created: The UNIX timestamp of the file creation
  • last_write: The UNIX timestamp of last write

Responses

Status Code Status Description
200 OK

Response Example

[
  {
    "name": "2025_01_07_093049.log",
    "size": 187050,
    "current": false,
    "created": 1736246561,
    "last_write": 1736246561
  },
  {
    "name": "2025_01_23_120115.log",
    "size": 269435,
    "current": true,
    "created": 1737634773,
    "last_write": 1737634773
  }
]

POST /api/system/restart

Trigger an immediate service restart

Responses

Status Code Status Description Description
400 ERR_RESTART_ALREADY_TRIGGERED A restart is already triggered
200 OK n/a

GET /api/tag/settings

Get information about tag positioning settings saved in the system.

Responses

Status Code Status Description Description
200 OK n/a

Response Example

{
  "positioning_mode": 0,
  "anchor_rssi_threshold": -80,
  "state_default_update_position": 2,
  "state_default_update_mode": 2,
  "state_motion_update_position": 2,
  "state_motion_update_mode": 1,
  "state_alarm_update_position": 2,
  "state_alarm_update_mode": 1,
  "state_sleep_update_position": 0,
  "state_sleep_update_mode": 2,
  "map_selection_delta_rssi": 5,
  "map_selection_anchor_avg_number": 3,
  "map_selection_delta_avg": 0.5,
  "anchor_group_selection_delta_rssi": 6,
  "anchor_group_selection_anchor_avg_number": 3,
  "anchor_group_selection_delta_avg": 0.5,
  "mesh_anchor_localization_amount_min": 1,
  "mesh_anchor_localization_amount_max": 4
}

Positioning modes

Code Description
0 map-positioning
1 zone-positioning

POST /api/tag/settings

Change tag positioning settings in the system.

POST Method In the body of the request has to be specified the full configuration of tag positioning settings, changing the parameters the user is interested in.

Body

{
  "configuration_level": "basic",
  "remove_timeout": 0,
  "positioning_mode": 0,
  "anchor_rssi_threshold": -100,
  "state_default_update_position": 2,
  "state_default_update_mode": 1,
  "state_motion_update_position": 2,
  "state_motion_update_mode": 1,
  "state_alarm_update_position": 2,
  "state_alarm_update_mode": 1,
  "state_sleep_update_position": 0,
  "state_sleep_update_mode": 1,
  "map_selection_delta_rssi": 5,
  "map_selection_anchor_avg_number": 5,
  "map_selection_delta_avg": 0.5,
  "anchor_group_selection_delta_rssi": 5,
  "anchor_group_selection_anchor_avg_number": 5,
  "anchor_group_selection_delta_avg": 0.5,
  "mesh_anchor_localization_amount_min": 1,
  "mesh_anchor_localization_amount_max": 0
}

Responses

Status Code Status Description Description
200 OK
400 ERR_MISSING_SETTINGS

Response Example

{
  "changed": true
}

GET /api/tags

Get information about all tags present in the system.

The response is an array of the tags present in the system with related information.

This API supports optional FTR Query filters. Go to the FTR Queries section for more information.

Responses

Status Code Status Description Description
200 OK The response contains an array of the tags in the system

Response Example

[
  {
    "from_cache": false,
    "wrapper_type": "MeshTag",
    "id": <Tag_id>,
    "alias": "Wearable Tag",
    "node_id": <node_id>,
    "node_address": 10003378,
    "node_network_id": 140114,
    "node_role": "non_router_node",
    "version": "3.12",
    "node_class": "FA",
    "operation_mode": "nrls_tag",
    "alarm": "none",
    "state": "sleep",
    "state_time": 39543,
    "anchors": 4,
    "anchor": [<anchors_array>],
    "positioning_log_enabled": false,
    "positioning_mode": "trilateration",
    "location": {<location_info>},
    "last_update": 1709708841,
    "last_update_time": 3441,
    "battery": 3090,
    "status": "online"
  }
]

GET /api/tags/{network}

Get information about all tags handled by the system belonging to the specified network.

Specify the network ID.

The response contains an array of all the tags in the specified network and the related information.

URL Parameters

Key Value
network Network ID

Responses

Status Code Status Description Description
200 OK The response contains an array of tags detected in the specified network

Response Example

[
    {
        "from_cache": false,
        "wrapper_type": "MeshTag",
        "id": <tag_id>,
        "node_id": <node_id>,
        "node_address": 10003412,
        "node_network_id": 8369957,
        "node_role": "non_router_node",
        "version": "3.12",
        "node_class": "FA",
        "operation_mode": "nrls_tag",
        "alarm": "none",
        "state": "default",
        "state_time": 359,
        "anchors": 0,
        "positioning_log_enabled": false,
        "positioning_mode": "trilateration",
        "last_update": 1708602456,
        "last_update_time": 48,
        "battery": 2958,
        "status": "online"
    },
    {
        "from_cache": false,
        "wrapper_type": "MeshTag",
        "id": <tag_id>,
        "node_id": <node_id>,
        "node_address": 10003413,
        "node_network_id": 8369957,
        "node_role": "non_router_node",
        "version": "3.12",
        "node_class": "FA",
        "operation_mode": "nrls_tag",
        "alarm": "none",
        "state": "default",
        "state_time": 393,
        "anchors": 0,
        "positioning_log_enabled": false,
        "positioning_mode": "trilateration",
        "last_update": 1708602485,
        "last_update_time": 19,
        "battery": 2952,
        "status": "online"
    }
]

GET /api/event-stream

This Event Stream API allows to receive the events generated by the system as push notifications using Server Sent Events (SSE) technology.

The response body will be a stream with the events generated by the system, sent automatically when the event is generated. For more information about events, please check the API » Events panel or the documentation on BlueUp Docs.

Parameters

listen (Optional)

A list of valid event identifiers that the system shall notify. When omitting the parameter listen the system will notify all events.

Example

Url: GET /api/event-stream?listen=gatewayStatusChanged,meshNodeStateChanged

The system will only notify events: gatewayStatusChanged and meshNodeStateChanged

Response Events

  • event contains data of the generated event.
{
    "id": `string`,
    "sequence_number": `number`,
    "timestamp": `number`
    "data": `object`
}

GET /api/log-stream

This Event Stream API allows to receive the logs generated by the system as push notifications using Server Sent Events (SSE) technology.

The response body will contain the list of logs generated by the system, sent automatically when the event is generated. The same logs are also displayed in the MeshCube interface in section Logs -> System

Parameters

None

Example

Url: GET /api/log-stream

The system will notify log messages

Response Events

syslog object contains data of the generated log.

{
  "uid": `string`, // Unique identifier generated from system boot
  "ticks": `number`, // Number of ticks (1 tick = 100 nanosecond) elapsed from 0000-01-01
  "timestamp": `number`, // Unix timestamp (milliseconds)
  "source": `string`, // Application component which generated the message
  "type": `number`, // Message Type. See the table below
  "message": `string` // The Log Message
}

Log types

Type Description
1 Information
2 Warning
4 Error
8 Debug
16 Verbose

GET /api/information-stream

This Event Stream API allows to receive the system status data via Server Sent Events (SSE) technology.
The content of the received data is equal to the result of the API /api/status.

Parameters

interval (optional)

The interval (seconds) used by the system to send data.

Example

Url: GET /api/information-stream?interval=60

The system will send its status every 60 seconds.

Response Events

  • info contains the current system information.
{
  "uuid": <service_uuid>,
  "os": { <os_info> },
  "hostname": "blueupbeacons.com",
  "title": "MeshCube v6.0.0.62",
  "version": "6.0.0.62",
  "system": {
    "code": "meshcube",
    "description": "MeshCube"
  },
  "license": { <license_info> },
  "timestamp": 1714394598573,
  "activated": true,
  "started_on": 1714394595,
  "uptime": {
    "days": 0,
    "hours": 0,
    "minutes": 0,
    "seconds": 2
  },
  "network": { <network_info> },
  "processors": 16,
  "pressure": {
    "ram": 118,
    "pram": 0.1,
    "pcpu": 46.3
  }
}