bleenc v2.24 API


The Bleenc HTTP API allows external clients to invoke registered application endpoints using the HTTP request-response protocol.

A request URL has the following general form:

http[s]://<host>[:<port>]/<api-path>

Most Bleenc endpoint paths start with /api/; the exact path is shown in each endpoint definition.

The method, path, parameters, request body, response body and possible errors are described separately for each endpoint in this reference.

HTTP authentication

Bleenc supports three HTTP API authorization modes.

Disabled

HTTP access to registered API and SSE endpoints is disabled. Requests to a registered endpoint return 403 ERR_API_DISABLED.

Basic authentication

Clients must send an Authorization header using the Basic authentication scheme and the credentials configured in Bleenc.

Authorization: Basic <base64-encoded-credentials>

Basic authentication only encodes the credentials; it does not encrypt them. HTTPS should therefore be used whenever Basic authentication is enabled.

JWT bearer authentication

Clients must send a Bleenc JWT in the Authorization header using the Bearer scheme.

Authorization: Bearer <token>

A JWT API token can define:

  • whether the token is enabled;
  • a not-before date and an optional expiry date;
  • an optional list of authorized client IP addresses;
  • which API paths can be invoked;
  • a maximum number of invocations per hour.

Bleenc validates the token signature, issuer and configured restrictions before invoking the endpoint.

Licensing

When the system is limited by a license error, regular HTTP API endpoints return 403 ERR_LICENSE. Endpoints explicitly marked as license-free remain available over HTTP.

SSE endpoints are unavailable while the system is limited by a license error.

Invoking APIs through MQTT

An external client can also invoke registered Bleenc APIs through the MQTT system interface. This is useful when Bleenc cannot be reached directly over HTTP but both systems can connect to the same MQTT broker.

The API bridge uses two configurable topics:

  • the request topic, subscribed to by Bleenc;
  • the response topic, used by Bleenc to publish execution results.

HTTP Basic and JWT authentication are not applied to MQTT requests. Access control for this transport must therefore be enforced through broker authentication, topic authorization and transport security.

MQTT requests are still subject to the system license check. Unlike the HTTP transport, the current MQTT implementation rejects every API request while the system is limited, including requests targeting endpoints marked as license-free.

MQTT request payload

Publish a JSON object to the configured request topic.

{
  "id": "93ed16a4-e63f-4fb0-b872-cffd178e47cb",
  "method": "GET",
  "target": "/api/tags",
  "parameters": {
    "project": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707"
  },
  "headers": {
    "X-Correlation-ID": "example-request"
  }
}
Field Type Required Description
id string Yes Non-empty client-generated identifier used to correlate the response
method string Yes HTTP method associated with the registered endpoint
target string Yes API path to invoke
parameters object No Query parameters exposed to the endpoint
headers object No Request headers exposed to the endpoint
body any JSON value No Request body exposed to the endpoint

Parameter and header values should be strings because endpoints read them through the IRequest string accessors.

The MQTT request parser recognizes these methods:

  • GET
  • HEAD
  • POST
  • PUT
  • DELETE
  • CONNECT
  • OPTIONS
  • TRACE
  • PATCH

The method and target must match a registered API. Bleenc prepends / when target does not already start with it.

If the payload is not a JSON object, a required field is missing, or the method is not recognized, Bleenc discards the malformed request and logs the parsing error. No MQTT response is generated because the request is rejected before response handling is attached.

If the request is valid but no matching API exists, Bleenc publishes a response with status 404 and description ERR_API_NOT_FOUND.

MQTT response payload

Bleenc publishes the execution result to the configured response topic.

{
  "id": "93ed16a4-e63f-4fb0-b872-cffd178e47cb",
  "timestamp": 1784023200000,
  "execution": 12,
  "method": "GET",
  "target": "/api/tags",
  "status": 200,
  "type": "application/json",
  "body": []
}
Field Type Optional Description
id string No Identifier received in the request
timestamp number No UTC time at which the response was composed, as Unix milliseconds
execution number No Time elapsed from request parsing to response composition, including queue wait and endpoint execution, in milliseconds
method string No Method received in the request
target string No Normalized API path used for endpoint resolution
status number No HTTP-compatible response status code
description string Yes Response description or application error code
headers object Yes Response headers; media responses include this object even when empty
type string Yes MIME type of the response body
body JSON value or string Yes Response body encoded according to type

The body representation depends on the exact MIME type returned by the endpoint:

  • application/json is parsed and returned as a JSON value;
  • text/plain is decoded and returned as a string;
  • every other MIME type is returned as a Base64-encoded string.

Media and file responses are returned with status 200, their MIME type and a Base64-encoded body.

Response topic placeholders

The response topic supports the following placeholders:

Placeholder Description
<system-id> Unique identifier of the Bleenc system
<timestamp> Topic rendering time as 100-nanosecond ticks since the Unix epoch
<request-id> Client-generated request identifier
<request> Normalized API request path

Placeholder rendering affects only the MQTT topic. Response payload timestamps remain Unix timestamps expressed in milliseconds.

API List

GET /api.md


Generates and downloads the complete API reference for the current bleenc instance.

This endpoint builds a Markdown document at request time. The generated document includes the current engine version in the title, the general API description, all registered REST APIs that are not marked as hidden, and the available EventSource stream endpoints. Each API entry is rendered from the metadata registered in the system, including method, path, category, description and linked documentation summary when available.

The response is intended to be downloaded as a .md file. The server sets a Content-Disposition header with a filename in the form api-v{version}.md, where {version} is the current engine version.

Hidden APIs are intentionally excluded from the generated document.

Request

GET /api.md

Responses

Status Code Status Description MIME type Description
200 OK text/x-markdown Generated Markdown API reference document

Response headers

Header Description
Expires Set to -1 to prevent stale cached API documentation
Cache-Control Set to force validation before reusing a cached response
Content-Disposition Attachment filename in the form api-v{version}.md

Response body

The response body is a Markdown document similar to:

# bleenc v1.0.0 API
---
<general API description>

### API List

<visible REST API documentation>

<EventSource stream documentation>

The exact content depends on the APIs and EventSource streams registered by the running system.

GET /api/{project}/tag/{id}


Returns the information related to a specific tag that belongs to the specified project.

The endpoint resolves the tag by both project ID and tag ID. A tag with the requested ID is returned only when it belongs to the project provided in the URL.

URL Parameters

Key Type Description Required
project string Project ID Yes
id string Tag ID Yes

Responses

Status Code Status Description Description
200 OK The response contains the information about the requested tag.
400 ERR_MISSING_PROJECT_ID The project URL parameter is missing.
400 ERR_MISSING_TAG_ID The id URL parameter is missing.
404 ERR_TAG_NOT_FOUND No tag was found with the provided ID in the specified project.

Response Example

{
  "uid": 63,
  "type": "Tag",
  "model": "bleenc",
  "id": "fa000b0e",
  "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
  "alias": "Safex Plus",
  "last_update": 1779811693515,
  "last_update_et": 741,
  "device": 250,
  "serial": 2830,
  "mac_address": "cb:00:fa:00:0b:0e",
  "network_id": 1347,
  "class": 0,
  "firmware": "4.3.1",
  "hardware": {
    "model": 250,
    "revision": 16,
    "variant": 0,
    "led_0": "rgb",
    "led_1": "none",
    "led_2": "none",
    "led_3": "none",
    "button_1": true,
    "button_2": true,
    "button_3": false,
    "button_4": false,
    "gpio_1": false,
    "gpio_2": false,
    "gpio_3": false,
    "gpio_4": false,
    "accelerometer": true,
    "buzzer": true,
    "vibration": true,
    "display": false
  },
  "alert_running": false,
  "cfg_seq": 70,
  "cfg_status": "match",
  "cmd_seq": 4,
  "state": "default",
  "moving": false,
  "motion_date": 1779810803051,
  "motion_time": 890891,
  "alarm_type": "none",
  "alarm_count": 0,
  "button_evt": "none",
  "buttons": [
    false,
    false,
    false,
    false
  ],
  "button_press_count": 20,
  "power_connected": false,
  "battery_low": false,
  "battery": 4010,
  "calibrated_rssi": -54,
  "receivers": 8,
  "nearest_receiver": {
    "id": "00007cdfa1fe411c",
    "alias": "Dev 3 (441c)",
    "rssi_raw": -45,
    "rssi": -44.335471646424,
    "rssi_offset": 0,
    "rssi_stability": 0.992148651502626,
    "attenuation": -9.66452835357602,
    "n": 1.6,
    "estimated_distance": 0.248866808224459,
    "proximity": 3,
    "last_update": 1779811693500,
    "last_update_et": 756
  },
  "scan_enabled": true,
  "realtime_tracking": {
    "type": "estimated",
    "last_update": 1779810804191,
    "map": {
      "id": "cc5b3382-4aed-4000-b362-e463495c00b7",
      "description": "Ufficio BlueUp"
    },
    "mode": "realtime",
    "estimator": "trilateration",
    "position": {
      "x": 9.254,
      "y": 11.387,
      "z": 0
    },
    "accuracy": 1
  },
  "snapshot_tracking": {
    "type": "estimated",
    "last_update": 1779808821448,
    "map": {
      "id": "cc5b3382-4aed-4000-b362-e463495c00b7",
      "description": "Ufficio BlueUp"
    },
    "mode": "snapshot",
    "estimator": "zoning",
    "zone": {
      "id": "dev2",
      "description": "Development 2"
    }
  },
  "detected": true
}
Response Parameters
Parameter Type Description
uid number Internal device numeric identifier.
type string Device type. For this endpoint the value is Tag.
model string Device model family.
id string Tag identifier.
project_id string Project ID associated with the tag.
alias string Device alias, available when an alias is set.
last_update number UNIX timestamp in milliseconds of the latest device update.
last_update_et number Elapsed time from the last update in milliseconds.
device number Device model number.
serial number Device serial number.
mac_address string Device MAC address.
network_id number Network ID.
class number Device class number.
firmware string Device firmware version.
hardware object Device hardware characteristics.
alert_running bool Indicates whether an alert is currently running on the device.
cfg_seq number Configuration sequence identifier.
cfg_status string Indicates whether the configuration set in bleenc matches the configuration on the device.
cmd_seq number Sequence of the command sent to the device.
state string Device state.
moving bool Indicates whether the device is moving.
motion_date number UNIX timestamp in milliseconds of when the device started or stopped moving.
motion_time number Elapsed time in milliseconds since the device started or stopped moving.
alarm_type string Type of alarm raised on the device.
alarm_count number Number of alarms raised on the device since the last reboot or power on.
button_evt string Type of button event reported by the device.
buttons array[bool] Four-item array indicating which buttons are currently pressed.
button_press_count number Counter of button presses since the last device reboot or power on.
power_connected bool Indicates whether a rechargeable device is connected to a power supply.
battery_low bool Indicates whether the battery is low.
battery number Battery level in mV.
calibrated_rssi number Device RSSI calibration level.
receivers number Number of receivers currently detecting the device.
nearest_receiver object Information about the nearest receiver.
scan_enabled bool Indicates whether the device is configured to perform device scans.
realtime_tracking object Current realtime tracking data, when available.
snapshot_tracking object Current snapshot tracking data, when available.
detected bool Indicates whether the device is currently detected by at least one gateway.
location object Static device location, when configured.

POST /api/command


Sends a command to one tag or to a multicast class of tags.

The endpoint exposed by the system is POST /api/command. The request body selects the target, an optional timeout, an optional gateway for unicast delivery, and the command payload.

Body Parameters

Key Type Description Required
target string Unicast target tag ID. Yes
target object Unicast target composed by model and serial. Yes
target number Multicast target class from 0 to 7. Yes
project_id string Project ID. Required only when target is a multicast class number. Conditional
timeout number Timeout in milliseconds. If omitted or too low it is clamped to 5000 ms; if above 60000 ms it is clamped to 60000 ms. No
gateway string Optional gateway ID for unicast commands. If missing or not found, the system automatically selects a gateway or broadcasts through all suitable gateways. Must be omitted for multicast commands. No
command object string Command to send. Objects use type and optional data; strings are parsed as raw hex or statement commands.

Supported Commands

Type Description
alert Starts or stops alert output on the target tag.
class Changes the tag class.
scan Requests a BLE scan from the target tag.
reboot Reboots the target tag.

The parser also accepts display-data and display-refresh. These are e-paper micro-operations used by POST /api/epaper/write; they are documented below only for completeness and should not normally be used atomically through this endpoint.

Alert Command

The alert command starts or stops visual, acoustic, and vibration feedback on the target tag. When data is a JSON object, the alert is enabled. When data is null or omitted, the alert is disabled.

Alert Parameters
Parameter Type Description
duty_cycle number Percentage of the active part of the alert period. Values below 0 are clamped to 0; values above 100 are clamped to 100. Default is 50.
period number Base alert period value. Values below 0 are clamped to 0; values above 63 are clamped to 63. Default is 10.
repeats number Number of repetitions in one alert series. Values below 0 are clamped to 0; values above 255 are clamped to 255. Default is 1.
interval number Interval between alert series. Values below 0 are clamped to 0; values above 4095 are clamped to 4095. Default is 0.
series number Number of alert series. Values below 0 are clamped to 0; values above 4095 are clamped to 4095. Default is 1.
buzzer bool Enables the buzzer output. Default is false.
vibration bool Enables the vibration output. Default is false.
led object Detailed LED settings. Missing LED flags default to false; missing color defaults to red, green, and blue enabled when the LED object form is used.
led bool true enables LED 0 with RGB color; false disables LEDs.
led number Enables one LED by index: 0, 1, 2, or 3.
led array[number] Enables the LED indexes listed in the array.
led string Compact LED expression, such as "0 b" for LED 0 blue or "0 1 rg seq" for LEDs 0 and 1, red/green, sequential mode.

Detailed led object parameters:

Parameter Type Description
led0 bool Enables LED 0.
led1 bool Enables LED 1.
led2 bool Enables LED 2.
led3 bool Enables LED 3.
color string LED color expression. The parser checks the letters r, g, and b; for example "b" means blue and "rg" means red plus green.
sequential bool Runs selected LEDs sequentially instead of all at once.
Alert Example 1: Blue LED And Buzzer
{
  "target": {
    "model": 250,
    "serial": 2830
  },
  "timeout": 30000,
  "gateway": "00007cdfa1fe411c",
  "command": {
    "type": "alert",
    "data": {
      "duty_cycle": 50,
      "period": 10,
      "repeats": 3,
      "interval": 10,
      "series": 1,
      "buzzer": true,
      "vibration": false,
      "led": {
        "led0": true,
        "led1": false,
        "led2": false,
        "led3": false,
        "color": "b",
        "sequential": false
      }
    }
  }
}
Alert Example 2: Stop Current Alert
{
  "target": "fa000b0e",
  "timeout": 30000,
  "gateway": "00007cdfa1fe411c",
  "command": {
    "type": "alert",
    "data": null
  }
}
Alert Example 3: Sequential Red/Green LEDs With Vibration
{
  "target": "fa000b0e",
  "timeout": 30000,
  "command": {
    "type": "alert",
    "data": {
      "duty_cycle": 80,
      "period": 20,
      "repeats": 5,
      "interval": 30,
      "series": 2,
      "buzzer": false,
      "vibration": true,
      "led": "0 1 rg seq"
    }
  }
}
Alert Example 4: Select LED By Index
{
  "target": {
    "model": 250,
    "serial": 2830
  },
  "timeout": 30000,
  "command": {
    "type": "alert",
    "data": {
      "repeats": 1,
      "buzzer": false,
      "vibration": false,
      "led": 2
    }
  }
}

Set Class Example

{
  "target": "fa000b0e",
  "timeout": 30000,
  "command": {
    "type": "class",
    "data": {
      "class": 2
    }
  }
}

Multicast Set Class Example

{
  "target": 0,
  "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
  "timeout": 30000,
  "command": {
    "type": "class",
    "data": {
      "class": 2
    }
  }
}

Scan Example

{
  "target": {
    "model": 250,
    "serial": 2830
  },
  "timeout": 30000,
  "gateway": "00007cdfa1fe411c",
  "command": {
    "type": "scan",
    "data": {
      "protocol": "ble",
      "packet": "bleenc",
      "window": 1700,
      "repeats": 1,
      "interval": 0
    }
  }
}

For iBeacon scans, uuid is required:

{
  "target": "fa000b0e",
  "timeout": 30000,
  "command": {
    "type": "scan",
    "data": {
      "protocol": "ble39",
      "packet": "ibeacon",
      "uuid": "fda50693-a4e2-4fb1-afcf-c6eb07647825",
      "window": 1700,
      "repeats": 2,
      "interval": 10
    }
  }
}

protocol accepts ble, ble37, ble38, ble39, pro1, pro2, or pro3. packet accepts bleenc or ibeacon. window is expressed in milliseconds and must be between 100 and 3000. When interval is set, it must be at least 10 seconds and repeats must be greater than 1.

Reboot Example

{
  "target": {
    "model": 250,
    "serial": 2830
  },
  "timeout": 30000,
  "command": {
    "type": "reboot"
  }
}

Reboot supports default, dfu, and provision options. The pin value is used only with the provision option and must be between 0 and 999999.

{
  "target": "fa000b0e",
  "timeout": 30000,
  "command": {
    "type": "reboot",
    "data": {
      "option": "provision",
      "pin": 123456
    }
  }
}

E-Paper Micro-Operations

The following command types are accepted by the parser, but are intended to be orchestrated by POST /api/epaper/write.

{
  "target": "fa000b0e",
  "timeout": 30000,
  "command": {
    "type": "display-data",
    "data": {
      "canvas": 0,
      "data": "ORDER-1042"
    }
  }
}

canvas must be between 0 and 15. data is optional; when provided, its UTF-8 encoded length must be less than 64 bytes.

{
  "target": "fa000b0e",
  "timeout": 30000,
  "command": {
    "type": "display-refresh",
    "data": {
      "clear": true,
      "fast": false,
      "partial": false,
      "mask": 0
    }
  }
}

clear, fast, and partial are optional boolean flags. mask is optional and may be provided as a numeric update mask.

Responses

Status Code Status Description Description
200 OK The command completed and the response body contains the command result.
400 ERR_MISSING_BODY Body is missing or is not a valid JSON object.
400 ERR_MISSING_COMMAND The command field is missing.
400 ERR_PARSE_COMMAND The command cannot be parsed. The response body contains parser details when available.
400 ERR_INVALID_COMMAND The command field has an unsupported JSON type or invalid format.
400 ERR_MISSING_TARGET The target field is missing.
400 ERR_INVALID_TARGET The target field has an unsupported JSON type.
400 ERR_INVALID_CLASS The multicast target class is outside the valid range.
400 ERR_MISSING_PROJECT_ID project_id is missing for a multicast command.
400 ERR_PROJECT_NOT_FOUND The project specified by project_id does not exist.
400 ERR_MISSING_MODEL The object target does not contain model.
400 ERR_INVALID_MODEL The object target model is outside the valid range.
400 ERR_MISSING_SERIAL The object target does not contain serial.
400 ERR_INVALID_SERIAL The object target serial is outside the valid range.
400 ERR_INVALID_TAG_STATE The command cannot be executed because of the current tag state.
404 ERR_TAG_NOT_FOUND No tag was found for the provided unicast target.
408 ERR_TIMEOUT The command did not complete within the configured timeout.
500 ERR_UNABLE_TO_SEND_COMMAND Internal error during command dispatch. The response body contains details when available.

The response body is dynamically generated by the command handler. Reboot commands are handled by the reboot-specific handler; other unicast commands and multicast commands return their command result when completed.

POST /api/epaper/write


Writes data to an e-paper tag.

The endpoint exposed by the system is POST /api/epaper/write. It builds a sequence of internal display-data micro-operations, one for each frame, followed by a display-refresh operation that updates the e-paper display.

Body Parameters

Key Type Description Required
target string Target tag ID. Yes
target object Target tag composed by model and serial. Yes
timeout number Timeout in milliseconds. If omitted or too low it is clamped to 20000 ms; if above 60000 ms it is clamped to 60000 ms. No
gateway string Optional gateway ID. If missing or not found, the system automatically selects a gateway or broadcasts through all suitable gateways. No
frames array List of e-paper frame values to write. Yes
fast bool Enables fast display refresh. Default is false. No

Target Format

Type Description
string Hexadecimal tag identifier, for example fa000b0e.
object Object containing model and serial, for example { "model": 250, "serial": 2830 }.

When the object target form is used, model must be between 1 and 255; serial must be between 1 and 16777215.

Frame Item Format

Key Type Description Required
id number Canvas/frame identifier from 0 to 15. Each identifier can be used only once in the same request. Yes
value string number Frame value. A string is encoded as UTF-8 and must be shorter than 64 bytes. A numeric value is interpreted as an icon index from 0 to 9. An empty string clears the frame.

Request Example: Target As Object

{
  "target": {
    "model": 250,
    "serial": 2830
  },
  "timeout": 30000,
  "gateway": "00007cdfa1fe411c",
  "fast": true,
  "frames": [
    {
      "id": 0,
      "value": "ORDER-1042"
    },
    {
      "id": 1,
      "value": "PICKING"
    },
    {
      "id": 2,
      "value": 3
    }
  ]
}

Request Example: Target As Tag ID

{
  "target": "fa000b0e",
  "timeout": 30000,
  "frames": [
    {
      "id": 0,
      "value": "Room A"
    },
    {
      "id": 1,
      "value": "Shelf 12"
    },
    {
      "id": 2,
      "value": ""
    }
  ]
}

Responses

Status Code Status Description Description
200 OK The e-paper write command completed and the response body contains the command result.
400 ERR_MISSING_BODY Body is missing or is not a valid JSON object.
400 ERR_MISSING_TARGET The target field is missing.
400 ERR_INVALID_TARGET The target field has an unsupported JSON type.
400 ERR_MISSING_MODEL The object target does not contain model.
400 ERR_INVALID_MODEL The object target model is outside the valid range.
400 ERR_MISSING_SERIAL The object target does not contain serial.
400 ERR_INVALID_SERIAL The object target serial is outside the valid range.
400 ERR_MISSING_FRAMES The frames field is missing or is not an array.
400 ERR_INVALID_FRAME_TYPE One or more items in frames are not JSON objects.
400 ERR_INVALID_FRAME A frame is missing id or value, has an invalid id, or has a value with an unsupported type.
400 ERR_FRAME_ALREADY_DEFINED A frame with the same identifier has already been added.
400 ERR_INVALID_ICON_INDEX A numeric frame value is outside the valid icon index range.
400 ERR_FRAME_VALUE_SIZE A string frame value is too large. The encoded value must be shorter than 64 bytes.
404 ERR_TAG_NOT_FOUND No tag was found for the provided target.
408 ERR_TIMEOUT The command did not complete within the configured timeout.
500 ERR_UNABLE_TO_SEND_COMMAND Internal error during command dispatch. The response body contains details when available.

The response body is dynamically generated by the command handler after the internal display operations complete.

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=tagBatteryLevelChanged,gatewayStatusChanged&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.

Parameters

Key Value Optional
token token ✗

Body

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

data contains data of the generated event. Refer to the Events documentation for the daat object.

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

GET /api/gateway/{id}


Returns information about a specific gateway connected to the system.

The gateway is resolved by its device identifier.

URL Parameters

Key Type Description Required
id string Gateway ID Yes

Responses

Status Code Status Description Description
200 OK The response contains information about the requested gateway.
400 ERR_MISSING_ID The id URL parameter is missing.
404 ERR_GATEWAY_NOT_FOUND No gateway was found with the provided ID.

Response Example

{
  "uid": 2,
  "type": "Gateway",
  "model": "bleenc",
  "id": "00007cdfa1fe411c",
  "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
  "alias": "Warehouse Gateway 1",
  "last_update": 1779811693515,
  "last_update_et": 741,
  "configuration_template": "7b8c2dc4-cf74-4a2b-a6ff-4aaac9d7e7c8",
  "gw_model": "wifi",
  "os_version": "11.2.0",
  "fw_version": "4.3.1",
  "fw_release": "stable",
  "ui_version": "2.8.0",
  "mcu_version": "1.12.6",
  "mac_address": "00:07:cd:fa:1f:e4",
  "ip_address": "192.168.10.42",
  "uptime": 32847000,
  "last_boot": 1779778846515,
  "timesync": true,
  "packet_sec": 18,
  "working_status": "running",
  "last_advertising": 1779811693500,
  "last_advertising_et": 756,
  "configuration": {
    "id": "7b8c2dc4-cf74-4a2b-a6ff-4aaac9d7e7c8",
    "scan_enable": true,
    "response_enable": true,
    "ble_whitelist_enable": false,
    "scan_channel": "ble39",
    "scan_rssi_threshold": -90,
    "response_rssi_threshold": -70,
    "network_id": 1347,
    "sec_key": "00112233445566778899aabbccddeeff",
    "provision_enable": false
  },
  "proximity_settings": {
    "override_project": false
  },
  "online": true,
  "location": {
    "type": "static",
    "last_update": 1779810804191,
    "map": {
      "id": "cc5b3382-4aed-4000-b362-e463495c00b7",
      "description": "Ufficio BlueUp"
    },
    "position": {
      "x": 12.4,
      "y": 8.7,
      "z": 0
    },
    "zone": {
      "id": "warehouse-a",
      "description": "Warehouse A"
    }
  }
}
Response Parameters
Parameter Type Description
uid number Internal device numeric identifier.
type string Device type. For this endpoint the value is Gateway.
model string Device model family.
id string Gateway identifier.
project_id string Project ID associated with the gateway.
alias string Gateway alias, available when set.
last_update number UNIX timestamp in milliseconds of the latest gateway update.
last_update_et number Elapsed time from the last update in milliseconds.
configuration_template string Identifier of the configuration template currently assigned to the gateway.
gw_model string Gateway model, such as wifi, eth, or lte.
os_version string Gateway OS version.
fw_version string Gateway firmware version.
fw_release string Gateway firmware release channel or label.
ui_version string Gateway UI version.
mcu_version string Gateway MCU version.
mac_address string Gateway MAC address.
ip_address string Gateway IP address.
uptime number Gateway uptime in milliseconds, when available.
last_boot number UNIX timestamp in milliseconds of the last gateway boot, when available.
timesync bool Indicates whether the gateway internal time is synchronized.
packet_sec number Number of packets per second processed by the gateway.
working_status string Current gateway working status.
last_advertising number UNIX timestamp in milliseconds of the last gateway advertising, when available.
last_advertising_et number Elapsed time from the last advertising in milliseconds, when available.
configuration object Current gateway configuration.
proximity_settings object Gateway proximity settings.
online bool Gateway current online/offline state.
location object Gateway static location, when configured.

DELETE /api/gateway/{id}/alias


Removes the alias from the provided gateway.

URL Parameters

Key Type Description Required
id string Gateway ID Yes

Responses

Status Code Status Description Description
200 OK Operation was successful.
400 ERR_MISSING_GATEWAY_ID The id URL parameter is missing.
404 ERR_GATEWAY_NOT_FOUND No gateway was found with the provided ID.

Response Example

{
  "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
  "gateway_id": "00007cdfa1fe411c",
  "alias": null
}
Response Parameters
Parameter Type Description
project_id string Project ID associated with the gateway.
gateway_id string Gateway ID.
alias string|null Gateway alias. After deletion the value is null.

POST /api/gateway/{id}/alias


Sets an alias on the provided gateway.

URL Parameters

Key Type Description Required
id string Gateway ID Yes

Body Parameters

{
  "alias": "Warehouse Gateway 1"
}
Parameter Type Description Required
alias string Alias to assign to the gateway. Yes

Responses

Status Code Status Description Description
200 OK Operation was successful.
400 ERR_MISSING_GATEWAY_ID The id URL parameter is missing.
400 ERR_MISSING_BODY The request does not contain a JSON object body.
400 ERR_MISSING_ALIAS The request body does not contain the alias key.
404 ERR_GATEWAY_NOT_FOUND No gateway was found with the provided ID.

Response Example

{
  "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
  "gateway_id": "00007cdfa1fe411c",
  "alias": "Warehouse Gateway 1"
}
Response Parameters
Parameter Type Description
project_id string Project ID associated with the gateway.
gateway_id string Gateway ID.
alias string|null Gateway alias.

GET /api/gateway/{id}/alias


Retrieves the alias currently set on the provided gateway.

URL Parameters

Key Type Description Required
id string Gateway ID Yes

Responses

Status Code Status Description Description
200 OK The response contains the current gateway alias information.
400 ERR_MISSING_GATEWAY_ID The id URL parameter is missing.
404 ERR_GATEWAY_NOT_FOUND No gateway was found with the provided ID.

Response Example

{
  "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
  "gateway_id": "00007cdfa1fe411c",
  "alias": "Warehouse Gateway 1"
}
Response Parameters
Parameter Type Description
project_id string Project ID associated with the gateway.
gateway_id string Gateway ID.
alias string|null Gateway alias, or null when no alias is set.

PUT /api/gateway/{id}/location


Sets the gateway static location inside a map.

URL Parameters

Key Type Description Required
id string Gateway ID Yes

Body Parameters

{
  "map": "cc5b3382-4aed-4000-b362-e463495c00b7",
  "position": {
    "x": 12.4,
    "y": 8.7,
    "z": 0
  }
}
Parameter Type Description Required
map string ID of the map where the gateway is. Yes
position object Gateway position inside the map. Yes
Position Object
Parameter Type Description Required
x number X coordinate. Yes
y number Y coordinate. Yes
z number Z coordinate. No

Responses

Status Code Status Description Description
200 OK The response contains the updated location.
400 ERR_MISSING_BODY The request does not contain a JSON object body.
400 ERR_MISSING_ID The id URL parameter is missing.
400 ERR_INVALID_LOCATION The request body does not contain a valid map.
400 ERR_MISSING_LOCATION_POSITION The request body does not contain position.
400 ERR_INVALID_LOCATION_POSITION The provided position is malformed.
404 ERR_GATEWAY_NOT_FOUND No gateway was found with the provided ID.
404 ERR_MAP_NOT_FOUND No map was found with the provided ID.

Response Example

{
  "location": {
    "type": "static",
    "last_update": 1779810804191,
    "map": {
      "id": "cc5b3382-4aed-4000-b362-e463495c00b7",
      "description": "Warehouse"
    },
    "position": {
      "x": 12.4,
      "y": 8.7,
      "z": 0
    },
    "zone": {
      "id": "warehouse-a",
      "description": "Warehouse A"
    }
  }
}
Response Parameters
Parameter Type Description
location object Gateway static location.

DELETE /api/gateway/{id}/location


Removes the gateway static location inside a map.

URL Parameters

Key Type Description Required
id string Gateway ID Yes

Responses

Status Code Status Description Description
200 OK The static location was removed.
400 ERR_MISSING_ID The id URL parameter is missing.
404 ERR_GATEWAY_NOT_FOUND No gateway was found with the provided ID.

Response Example

{
  "location": null
}
Response Parameters
Parameter Type Description
location null Gateway static location after the remove action.

GET /api/gateway/{id}/location


Gets the gateway static location inside a map.

URL Parameters

Key Type Description Required
id string Gateway ID Yes

Responses

Status Code Status Description Description
200 OK The response contains the gateway location.
400 ERR_MISSING_ID The id URL parameter is missing.
404 ERR_GATEWAY_NOT_FOUND No gateway was found with the provided ID.

Response Example

{
  "location": {
    "type": "static",
    "last_update": 1779810804191,
    "map": {
      "id": "cc5b3382-4aed-4000-b362-e463495c00b7",
      "description": "Warehouse"
    },
    "position": {
      "x": 12.4,
      "y": 8.7,
      "z": 0
    },
    "zone": {
      "id": "warehouse-a",
      "description": "Warehouse A"
    }
  }
}

When no static location is assigned, the response contains null.

{
  "location": null
}
Response Parameters
Parameter Type Description
location object null

POST /api/gateway/{id}/remote


Invokes an internal API exposed by a gateway connected to the system.

This endpoint is intended for diagnostic and maintenance operations. The request is forwarded to the target gateway and the HTTP response returned by the gateway is propagated to the caller.

URL Parameters

Key Type Description Required
id string Gateway ID Yes

Body Parameters

{
  "timeout": 30,
  "method": "GET",
  "target": "/api/system",
  "body": {
    "include": "status"
  }
}
Parameter Type Description Required
timeout number Timeout in seconds. If omitted, the default value is 30. No
method string HTTP method to invoke on the gateway, for example GET, POST, or DELETE. Yes
target string Gateway API target path. If it does not start with /, the server prepends it automatically. Yes
body object Request body forwarded to the gateway. Required only when the target gateway API requires a body. No

Responses

Status Code Status Description Description
400 ERR_MISSING_GATEWAY_ID The id URL parameter is missing.
400 ERR_MISSING_REQUEST_BODY The request does not contain a JSON object body.
400 ERR_MISSING_BODY_PARAMETER The request body does not contain method or target. The response body contains the missing parameter name.
404 ERR_GATEWAY_NOT_FOUND No gateway was found with the provided ID.
408 ERR_TIMEOUT The system did not receive a gateway response within the configured timeout.
500 ERR_MQTT_PUBLISH_ERROR The system was not able to publish the request to the gateway. The response body contains the publish result.
500 Gateway-specific error The gateway request failed before a gateway response was received.
503 ERR_MQTT_CLIENT_DISCONNECTED The MQTT client was disconnected when attempting to invoke the gateway API.
xxx Gateway response On success, the endpoint uses the status code, status message, and body returned by the gateway.

Missing Parameter Response Example

{
  "parameter": "target"
}

Gateway Response Example

{
  "uuid": "8a3c4e77-ec5e-49e9-a639-a28782e174d5",
  "hostname": "gateway-warehouse-1",
  "version": "4.3.1",
  "status": "running"
}

GET /api/gateways


Fetches the gateways connected to the system.

When no filter is provided, the endpoint returns the full gateway collection. Passing the optional project query string parameter restricts the response to gateways associated with that project. The project value must be a valid UUID and must reference an existing project.

The endpoint supports FTR query parameters and inline FTR queries. When an FTR query is provided, the query is applied to the gateway array before returning the response.

Query String Parameters

Parameter Type Description Optional
project string Project UUID used to filter gateways by project. Yes

Responses

Status Code Status Description Description
200 OK The response contains an array of gateways connected to the system with related information.
400 ERR_INVALID_PROJECT_ID The project query string parameter is not a valid UUID.
404 ERR_PROJECT_NOT_FOUND The project specified by the project query string parameter does not exist.
500 ERR_FTR_QUERY The FTR query could not be processed. The response body contains the query exception details when available.

Response Example

[
  {
    "uid": 2,
    "type": "Gateway",
    "model": "bleenc",
    "id": "00007cdfa1fe411c",
    "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
    "alias": "Warehouse Gateway 1",
    "last_update": 1779811693515,
    "last_update_et": 741,
    "configuration_template": "7b8c2dc4-cf74-4a2b-a6ff-4aaac9d7e7c8",
    "gw_model": "wifi",
    "os_version": "11.2.0",
    "fw_version": "4.3.1",
    "fw_release": "stable",
    "ui_version": "2.8.0",
    "mcu_version": "1.12.6",
    "mac_address": "00:07:cd:fa:1f:e4",
    "ip_address": "192.168.10.42",
    "uptime": 32847000,
    "last_boot": 1779778846515,
    "timesync": true,
    "packet_sec": 18,
    "working_status": "running",
    "last_advertising": 1779811693500,
    "last_advertising_et": 756,
    "configuration": {
      "id": "7b8c2dc4-cf74-4a2b-a6ff-4aaac9d7e7c8",
      "scan_enable": true,
      "response_enable": true,
      "ble_whitelist_enable": false,
      "scan_channel": "ble39",
      "scan_rssi_threshold": -90,
      "response_rssi_threshold": -70,
      "network_id": 1347,
      "sec_key": "00112233445566778899aabbccddeeff",
      "provision_enable": false
    },
    "proximity_settings": {
      "override_project": false
    },
    "online": true
  }
]
Response Parameters
Parameter Type Description
uid number Internal device numeric identifier.
type string Device type. For this endpoint the value is Gateway.
model string Device model family.
id string Gateway identifier.
project_id string Project ID associated with the gateway.
alias string Gateway alias, available when set.
last_update number UNIX timestamp in milliseconds of the latest gateway update.
last_update_et number Elapsed time from the last update in milliseconds.
configuration_template string Identifier of the configuration template currently assigned to the gateway.
gw_model string Gateway model, such as wifi, eth, or lte.
os_version string Gateway OS version.
fw_version string Gateway firmware version.
fw_release string Gateway firmware release channel or label.
ui_version string Gateway UI version.
mcu_version string Gateway MCU version.
mac_address string Gateway MAC address.
ip_address string Gateway IP address.
uptime number Gateway uptime in milliseconds, when available.
last_boot number UNIX timestamp in milliseconds of the last gateway boot, when available.
timesync bool Indicates whether the gateway internal time is synchronized.
packet_sec number Number of packets per second processed by the gateway.
working_status string Current gateway working status.
last_advertising number UNIX timestamp in milliseconds of the last gateway advertising, when available.
last_advertising_et number Elapsed time from the last advertising in milliseconds, when available.
configuration object Current gateway configuration.
proximity_settings object Gateway proximity settings.
online bool Gateway current online/offline state.
location object Gateway static location, when configured.

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


Creates a new map under a project

Body parameters

Key Type Description Optional
project string The project where the map have to be created No
description string The map description (max length: 64 characters) No
pixel_per_mt number The map scale (the amount of pixels per meter, min: 1px) No
image string The image data, base64 encoded No
z number The height of the map (unit: meters, default: 0m) Yes
zones array An array of zones to create inside the map Yes
Zone object
{
  "id": "office",
  "description": "Office",
  "color": "#4169E1",
  "z": 0,
  "vertexes": [
    {
      "x": 11.063829787234,
      "y": 13.5957446808511,
      "z": 0
    },
    {
      "x": 11.063829787234,
      "y": 6.63829787234043,
      "z": 0
    },
    {
      "x": 18.063829787234,
      "y": 6.63829787234043,
      "z": 0
    },
    {
      "x": 18.063829787234,
      "y": 13.5957446808511,
      "z": 0
    }
  ]
}

Invalid zone objects are ignored and do not make the map creation fail.

Key Type Description Optional
id string Zone identifier, up to 64 characters No
description string Zone description Yes
color string Zone color Yes
z number Used to define a reference order between zones Yes
vertexes array Array of points defining the zone polygon No

The zone identifier can contain letters, digits, _ and -, up to 64 characters. Separators cannot be used at the beginning or end and cannot be consecutive.

Responses

Status Code Status Description Description
200 OK The response contains the created map
400 ERR_INVALID_BODY The request does not contain a JSON object body
400 ERR_MISSING_PROJECT_ID The request body does not contain the project ID
400 ERR_INVALID_PROJECT_ID The project ID provided is malformed
400 ERR_PROJECT_NOT_FOUND No project with the specified ID exists
400 ERR_INVALID_DESCRIPTION The map description is missing or invalid
400 ERR_INVALID_SCALE The map scale is missing or invalid
400 ERR_INVALID_IMAGE The map image is missing, malformed or invalid
500 ERR_MAP_CREATE The map could not be saved

Response Example

{
  "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
  "id": "2914eeb9-562e-422e-8a79-614812c3aa55",
  "description": "Map sample",
  "pixel_per_mt": 6.16857142857143,
  "z": 0,
  "gps_coordinates": false,
  "image": {
    "id": "58eb6e09-3798-482c-a1d4-26efac69a6f6",
    "type": "image/png",
    "url": "/map/58eb6e09-3798-482c-a1d4-26efac69a6f6",
    "thumbnail": "/map/58eb6e09-3798-482c-a1d4-26efac69a6f6/thumb",
    "size": 109680,
    "width": 1689,
    "height": 480
  },
  "offset": {
    "x": 0,
    "y": 0,
    "z": 0
  },
  "area": {
    "vertexes": [
      {
        "x": 0,
        "y": 0,
        "z": 0
      },
      {
        "x": 0,
        "y": 78,
        "z": 0
      },
      {
        "x": 274,
        "y": 78,
        "z": 0
      },
      {
        "x": 274,
        "y": 0,
        "z": 0
      }
    ]
  },
  "zones": [],
  "exclusion_areas": [],
  "guides": [],
  "placeholders": [],
  "layout": {
    "nodes": []
  }
}

DELETE /api/map/{id}


Deletes a map

URL Parameters

Key Type Description Optional
id string ID of the map to delete No

Responses

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

PUT /api/map/{id}


Updates map properties

URL Parameters

Key Type Description Optional
id string ID of the map to update No

Body parameters

Key Type Description Optional
description string The map description Yes
pixel_per_mt number The map scale (the amount of pixels per meter, min: 1px) Yes
z number The height of the map (unit: meters, default: 0m) Yes

Responses

Status Code Status Description Description
200 OK Operation was successful
400 ERR_INVALID_BODY The request does not contain a JSON object body
400 ERR_MISSING_MAP_ID The map ID URL parameter is missing
400 ERR_INVALID_MAP_ID The map ID provided is malformed
400 ERR_INVALID_MAP_SCALE The map scale is invalid
404 ERR_MAP_NOT_FOUND No map with the specified ID exists

GET /api/map/{id}.zip


Exports a map as zip file

URL Parameters

Key Type Description Optional
id string ID of the map to export No

Response

A zip file containing the map information and image

Response errors

Status Code Status Description Description
400 ERR_MISSING_MAP_ID The map ID URL parameter is missing
400 ERR_INVALID_MAP_ID The map ID provided is malformed
404 ERR_MAP_NOT_FOUND No map with the specified ID exists

DELETE /api/map/{id}/zone


Deletes a zone from a map.

URL Parameters

Key Type Description Optional
id string ID of the map to update No

Body parameters

{
  "id": "office"
}
Key Type Description Optional
id string Zone identifier No

Responses

Status Code Status Description Description
200 OK The zone was deleted successfully
400 ERR_MISSING_BODY The request does not contain a JSON object body
400 ERR_MISSING_ZONE_IDENTIFIER The request body does not contain the zone ID
400 ERR_MISSING_MAP_ID The map ID URL parameter is missing
400 ERR_INVALID_MAP_ID The map ID provided is malformed
404 ERR_MAP_NOT_FOUND No map with the specified ID exists
404 ERR_ZONE_NOT_FOUND No zone with the specified ID exists on the map

POST /api/map/{id}/zone


Creates or updates a zone on a map.

The zone is added to the map or updated when a zone with the same id already exists.

URL Parameters

Key Type Description Optional
id string ID of the map to update No

Body parameters

{
  "id": "office",
  "description": "Office",
  "color": "#4169E1",
  "z": 0,
  "vertexes": [
    {
      "x": 11.063829787234,
      "y": 13.5957446808511,
      "z": 0
    },
    {
      "x": 11.063829787234,
      "y": 6.63829787234043,
      "z": 0
    },
    {
      "x": 18.063829787234,
      "y": 6.63829787234043,
      "z": 0
    },
    {
      "x": 18.063829787234,
      "y": 13.5957446808511,
      "z": 0
    }
  ]
}
Zone object
Key Type Description Optional
id string Zone identifier No
description string Zone description Yes
color string Zone color Yes
z number Used to define a reference order between zones Yes
vertexes array Array of points defining the zone polygon No

Responses

Status Code Status Description Description
200 OK The response contains the created or updated zone
400 ERR_MISSING_BODY The request does not contain a JSON object body
400 ERR_MISSING_MAP_ID The map ID URL parameter is missing
400 ERR_INVALID_MAP_ID The map ID provided is malformed
400 ERR_PARSE_ZONE_OBJECT The provided zone object could not be parsed
404 ERR_MAP_NOT_FOUND No map with the specified ID exists

Response Example

{
  "id": "office",
  "description": "Office",
  "color": "#4169E1",
  "z": 0,
  "vertexes": [
    {
      "x": 11.063829787234,
      "y": 13.5957446808511,
      "z": 0
    },
    {
      "x": 11.063829787234,
      "y": 6.63829787234043,
      "z": 0
    },
    {
      "x": 18.063829787234,
      "y": 6.63829787234043,
      "z": 0
    },
    {
      "x": 18.063829787234,
      "y": 13.5957446808511,
      "z": 0
    }
  ]
}

GET /api/map/{id}/zones


Gets all zones defined on a map.

URL Parameters

Key Type Description Optional
id string ID of the map to inspect No

Responses

Status Code Status Description Description
200 OK The response contains an array of zones
400 ERR_MISSING_MAP_ID The map ID URL parameter is missing
400 ERR_INVALID_MAP_ID The map ID provided is malformed
404 ERR_MAP_NOT_FOUND No map with the specified ID exists

Response Example

[
  {
    "id": "office",
    "description": "Office",
    "color": "#4169E1",
    "z": 0,
    "vertexes": [
      {
        "x": 11.063829787234,
        "y": 13.5957446808511,
        "z": 0
      },
      {
        "x": 11.063829787234,
        "y": 6.63829787234043,
        "z": 0
      },
      {
        "x": 18.063829787234,
        "y": 6.63829787234043,
        "z": 0
      },
      {
        "x": 18.063829787234,
        "y": 13.5957446808511,
        "z": 0
      }
    ]
  }
]
Response parameters
Parameter Type Description
id string Zone identifier
description string Zone description
color string Zone color
z number Used to define a reference order between zones
vertexes array Array of points defining the zone polygon

POST /api/map/{id}/zones


Creates or updates multiple zones on a map.

Each zone in the request body is added to the map or updated when a zone with the same id already exists.

URL Parameters

Key Type Description Optional
id string ID of the map to update No

Body parameters

The request body must be a JSON array of zone objects.

[
  {
    "id": "office",
    "description": "Office",
    "color": "#4169E1",
    "z": 0,
    "vertexes": [
      {
        "x": 11.063829787234,
        "y": 13.5957446808511,
        "z": 0
      },
      {
        "x": 11.063829787234,
        "y": 6.63829787234043,
        "z": 0
      },
      {
        "x": 18.063829787234,
        "y": 6.63829787234043,
        "z": 0
      },
      {
        "x": 18.063829787234,
        "y": 13.5957446808511,
        "z": 0
      }
    ]
  }
]
Zone object
Key Type Description Optional
id string Zone identifier No
description string Zone description Yes
color string Zone color Yes
z number Used to define a reference order between zones Yes
vertexes array Array of points defining the zone polygon No

Responses

Status Code Status Description Description
200 OK The response contains the created or updated zones
400 ERR_MISSING_BODY The request does not contain a JSON array body
400 ERR_MISSING_MAP_ID The map ID URL parameter is missing
400 ERR_INVALID_MAP_ID The map ID provided is malformed
400 ERR_INVALID_ZONE_OBJECT One of the provided array items is not a JSON object
400 ERR_PARSE_ZONE_OBJECT One of the provided zone objects could not be parsed
404 ERR_MAP_NOT_FOUND No map with the specified ID exists

Response Example

[
  {
    "id": "office",
    "description": "Office",
    "color": "#4169E1",
    "z": 0,
    "vertexes": [
      {
        "x": 11.063829787234,
        "y": 13.5957446808511,
        "z": 0
      },
      {
        "x": 11.063829787234,
        "y": 6.63829787234043,
        "z": 0
      },
      {
        "x": 18.063829787234,
        "y": 6.63829787234043,
        "z": 0
      },
      {
        "x": 18.063829787234,
        "y": 13.5957446808511,
        "z": 0
      }
    ]
  }
]

GET /api/maps


Fetch the maps defined in the system. Passing the parameter project in the query string, allows to get only the maps related to provided project

Query String parameters

Parameter Type Description :Optional:
project string Project ID Yes

Responses

Status Code Status Description Description
200 OK The response contains an array of maps setup in the system with related information
400 ERR_INVALID_PROJECT_ID The project ID provided in the query string is malformed
404 ERR_PROJECT_NOT_FOUND No project with the specified ID exists

Response Example

[
  {
    "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
    "id": "2914eeb9-562e-422e-8a79-614812c3aa55",
    "description": "Map sample",
    "pixel_per_mt": 6.16857142857143,
    "z": 0,
    "gps_coordinates": false,
    "image": {
      "id": "58eb6e09-3798-482c-a1d4-26efac69a6f6",
      "type": "image/png",
      "url": "/map/58eb6e09-3798-482c-a1d4-26efac69a6f6",
      "thumbnail": "/map/58eb6e09-3798-482c-a1d4-26efac69a6f6/thumb",
      "size": 109680,
      "width": 1689,
      "height": 480
    },
    "offset": {
      "x": 0,
      "y": 0,
      "z": 0
    },
    "area": {
      "vertexes": [
        {
          "x": 0,
          "y": 0,
          "z": 0
        },
        {
          "x": 0,
          "y": 78,
          "z": 0
        },
        {
          "x": 274,
          "y": 78,
          "z": 0
        },
        {
          "x": 274,
          "y": 0,
          "z": 0
        }
      ]
    },
    "zones": [],
    "exclusion_areas": [],
    "guides": [
      {
        "id": "v_5840e089-f317-4628-95b6-21a47f3bacf6",
        "type": "v",
        "position": 7.97543542702684
      },
      {
        "id": "h_3fa8c005-afed-416f-b8fe-5777c0abacfc",
        "type": "h",
        "position": 66.6755758028554
      },
      {
        "id": "v_69db67ff-fb59-441f-bd66-cfe72368cbd0",
        "type": "v",
        "position": 33.3086168791829
      },
      {
        "id": "h_48ba687b-1e79-466a-a5f0-56b8da9a468a",
        "type": "h",
        "position": 73.3607209082855
      },
      {
        "id": "h_c8eec343-5537-403b-b4c8-fa8451726d83",
        "type": "h",
        "position": 57.6447657481517
      },
      {
        "id": "v_72048fcc-f6ec-4cca-a850-9314508fdbaa",
        "type": "v",
        "position": 72.8330712744449
      },
      {
        "id": "h_b7c7c26e-1e64-4462-8138-dccd78c56818",
        "type": "h",
        "position": 28.5585203771577
      },
      {
        "id": "v_78ab0b22-ad11-403a-9e2c-74ebcdd2464e",
        "type": "v",
        "position": 104.734114584567
      },
      {
        "id": "h_435f4520-45d4-4431-a78e-56d83700cdde",
        "type": "h",
        "position": 24.8054564583197
      },
      {
        "id": "v_4b31c7a1-299f-4a56-aa53-ffd412d9fc25",
        "type": "v",
        "position": 111.536542937461
      },
      {
        "id": "h_03e817f2-dce1-48b0-823c-e443193a5ea2",
        "type": "h",
        "position": 0.175974490945794
      },
      {
        "id": "h_02df3847-8069-4d61-9b69-65c73a3d8292",
        "type": "h",
        "position": 0.175974490945794
      },
      {
        "id": "h_6ca3186e-6cbf-405b-a89a-918778ffb677",
        "type": "h",
        "position": 43.8373113222867
      },
      {
        "id": "v_1928b480-3834-459c-8812-167a01db91b0",
        "type": "v",
        "position": 137.999305763452
      },
      {
        "id": "v_a76fe81b-dcea-475c-8347-190ce6c769e2",
        "type": "v",
        "position": 144.18253121095
      },
      {
        "id": "h_d9147a64-fa41-49bf-824b-8052840e0607",
        "type": "h",
        "position": 17.581088292323
      },
      {
        "id": "h_f3a1b7c6-3543-4a0b-a57c-43754fb5c192",
        "type": "h",
        "position": 10.6325457265985
      },
      {
        "id": "h_fb4a40dc-6f73-43d7-a441-61fe72323c30",
        "type": "h",
        "position": 4.9200369222262
      }
    ],
    "placeholders": []
  }
]
Response parameters
Parameter Type Description
project_id string Project ID
id string Map identifier
description string Map description assigned by the user
pixel_per_mt number Pixel per meter scale of the map
z number Used in case of overlying elements, to define a reference order
gps_coordinates bool Parameter identifying wether there is a reference to GPS coordinates
image object Information about the image used for the map
offset object Offset of the origin of the Map
area object Object containing the vertexes of the map area
zones array Array of zones defined on the map.
Empty if there are no zones
exclusion_areas array Array of exclusion areas defined on the map.
Empty if there are none
guides array Array of guides defined on the map.
Empty if there are none
placeholders array Array of placeholders defined on the map.
Empty if there are none
layout object Object containing the array of nodes defined on the layout on the map

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 as JSON payload.

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

A JSON element with the updated plugin configuration.

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

A JSON element with the plugin configuration.

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 an 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
  }
]

DELETE /api/project/{id}


Deletes a project if no registered device belongs to it. The same deletion checks apply to requests from the Bleenc client.

URL Parameters

Key Type Description Required
id string Project identifier Yes

Responses

Status Code Status Description Description
200 OK Project deleted successfully.
400 ERR_MISSING_PROJECT_ID The project ID was not provided.
404 ERR_PROJECT_NOT_FOUND No project with the specified ID exists.
409 ERR_REMOVED_DENIED Deletion was denied. The response body contains a reason explaining why.
409 ERR_PROJECT_ALREADY_REMOVED The project was already inactive when runtime cleanup was attempted.
500 ERR_PROJECT_DELETE_ERROR The project could not be deleted from storage.

GET /api/project/{id}


Returns information about a specific project.

URL Parameters

Key Type Description Required
id string Project identifier Yes

Responses

Status Code Status Description Description
200 OK The response contains the requested project
400 ERR_MISSING_PROJECT_ID The project id was not provided
404 ERR_PROJECT_NOT FOUND No project with the specified identifier exists

Response Example

{
  "id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
  "description": "Warehouse tracking",
  "scan_channel": "ble39",
  "network_id": 5908,
  "sec_key": "00112233445566778899aabbccddeeff",
  "provision_params": {
    "network_id": 5908
  },
  "mqtt_connection": "production-mqtt",
  "gateway_mqtt_connection": "gateway-mqtt",
  "mqtt_connection_state": "running",
  "gateway_templates": [],
  "tag_settings": {},
  "tracking": {},
  "last_update": 1747897503525
}
Response parameters
Parameter Type Description
id string Project identifier
description string Project description, if available
scan_channel string BLE scan channel configured for the project
network_id number BLE network identifier
sec_key string BLE security key, if configured
provision_params object Provisioning parameters configured for the project
mqtt_connection string MQTT connection used by the project, if configured
gateway_mqtt_connection string Gateway MQTT connection, if configured
mqtt_connection_state string Current MQTT source state, if the source is available
gateway_templates array Gateway templates configured for the project
tag_settings object Tag settings configured for the project
tracking object Project tracking configuration
last_update number Last project update timestamp, in Unix milliseconds

GET /api/project/{id}/tag/class/{class}


Returns the settings for a single project tag class.

Use this endpoint when the client needs the current configuration of one class only. To retrieve all class settings in a single response, use GET /api/project/{id}/tag/classes.

URL Parameters

Key Type Description Required
id string Project identifier Yes
class number Tag class number. Valid values: 0 - 7 Yes

Responses

Status Code Status Description Description
200 OK The response contains the selected class settings
400 ERR_MISSING_PROJECT_ID The project id was not provided
400 ERR_MISSING_CLASS_ID The tag class was not provided
400 ERR_INVALID_CLASS_ID The tag class is outside the valid range
404 ERR_PROJECT_NOT_FOUND No project with the specified id exists

Response Body

Parameter Type Description
class number Requested tag class number
settings object Current serialized settings for the class

Response Example

{
  "class": 1,
  "settings": {
    "alias": "Mobile tags",
    "configuration": [
      {
        "id": 48,
        "type": "bleenc",
        "data": {
          "button_enabled": true,
          "button_shutdown": false,
          "button_ack_feedback": true,
          "alerts_enabled": true,
          "default": {
            "advertising_interval": 1000,
            "tx_power": 0,
            "response_mode": "standard"
          },
          "calibrated_rssi_offset": 0
        }
      }
    ],
    "tag_type": "mobile",
    "tracking": true,
    "detection_timeout": 60,
    "rssi_filter": "balanced"
  }
}

Settings Object

The settings object is the serialized TagSetting for the requested class.

Parameter Type Description
alias string Optional human-readable alias for the class. Omitted when not configured
configuration array Optional tag configuration frame array. Omitted when the class has no configuration
tag_type string Tag type associated with the class
tracking boolean Enables or disables project tracking for tags in this class
detection_timeout number Detection timeout in seconds
rssi_filter string RSSI filter preset used by receivers for tags in this class

PUT /api/project/{id}/tag/class/{class}


Updates the settings for a single project tag class.

The request body must contain one serialized TagSetting object for the class specified in the URL.

This endpoint replaces the settings of the selected class with the parsed body. Fields omitted from the body are parsed using the same defaults used by the server-side TagSetting parser.

URL Parameters

Key Type Description Required
id string Project identifier Yes
class number Tag class number. Valid values: 0 - 7 Yes

Request Body

The body is a tag class settings object.

Parameter Type Description
alias string Optional human-readable alias for the class. Omit or use an empty value for no alias
configuration array Optional tag configuration frame array. Omit when the class has no configuration
tag_type string Tag type associated with the class: none, mobile, or fixed
tracking boolean Enables or disables project tracking for tags in this class
detection_timeout number or string Detection timeout. Numeric values are interpreted by BleencTime; values below 5s are normalized to 5s by the parser
rssi_filter string RSSI filter preset used by receivers for tags in this class

Request Example

{
  "alias": "Mobile tags",
  "configuration": [
    {
      "id": 48,
      "type": "bleenc",
      "data": {
        "button_enabled": true,
        "button_shutdown": false,
        "button_ack_feedback": true,
        "alerts_enabled": true,
        "default": {
          "advertising_interval": 1000,
          "tx_power": 0,
          "response_mode": "standard"
        },
        "calibrated_rssi_offset": 0
      }
    }
  ],
  "tag_type": "mobile",
  "tracking": true,
  "detection_timeout": 60,
  "rssi_filter": "balanced"
}

Responses

Status Code Status Description Description
200 OK The request was processed
400 ERR_MISSING_PROJECT_ID The project id was not provided
400 ERR_MISSING_CLASS_ID The tag class was not provided
400 ERR_INVALID_CLASS_ID The tag class is outside the valid range
400 ERR_INVALID_BODY The request body is missing or is not a valid JSON object
400 ERR_PARSE_TAG_CLASS_SETTINGS The request body cannot be parsed as tag class settings
404 ERR_PROJECT_NOT_FOUND No project with the specified id exists
500 ERR_STORE_PROJECT The project could not be stored after the update

Response Body

The response body contains the update result and the current settings for the class.

Parameter Type Description
updated boolean true when the stored class settings changed; otherwise false
class number Updated tag class number
settings object Current serialized settings for the class

Response Example

{
  "updated": true,
  "class": 1,
  "settings": {
    "alias": "Mobile tags",
    "tag_type": "mobile",
    "tracking": true,
    "detection_timeout": 60,
    "rssi_filter": "balanced"
  }
}

Notes

  • The endpoint updates one class only.
  • When no effective change is detected, the server returns 200 OK with updated: false.
  • When the update changes the project, the project is stored and connected clients receive the projectTagBaseSettingsUpdated notification.

GET /api/project/{id}/tag/classes


Returns the tag settings for all project tag classes.

The response always contains one item for each supported tag class, from class 0 to class 7.

URL Parameters

Key Type Description Required
id string Project identifier Yes

Responses

Status Code Status Description Description
200 OK The response contains all tag settings
400 ERR_MISSING_PROJECT_ID The project id was not provided
404 ERR_PROJECT_NOT_FOUND No project with the specified id exists

Response Body

The response body is an array of 8 objects.

Parameter Type Description
class number Tag class number. Valid values are 0 through 7
settings object Settings for the specified class

Response Example

[
  {
    "class": 0,
    "settings": {
      "tag_type": "none",
      "tracking": false,
      "detection_timeout": 60,
      "rssi_filter": "balanced"
    }
  },
  {
    "class": 1,
    "settings": {
      "alias": "Mobile tags",
      "configuration": [
        {
          "id": 48,
          "type": "bleenc",
          "data": {
            "button_enabled": true,
            "button_shutdown": false,
            "button_ack_feedback": true,
            "alerts_enabled": true,
            "default": {
              "advertising_interval": 1000,
              "tx_power": 0,
              "response_mode": "standard"
            },
            "calibrated_rssi_offset": 0
          }
        }
      ],
      "tag_type": "mobile",
      "tracking": true,
      "detection_timeout": 60,
      "rssi_filter": "balanced"
    }
  }
]

Settings Object

Each settings object is the serialized TagSetting for the class.

Parameter Type Description
alias string Optional human-readable alias for the class. Omitted when not configured
configuration array Optional tag configuration frame array. Omitted when the class has no configuration
tag_type string Tag type associated with the class
tracking boolean Enables or disables project tracking for tags in this class
detection_timeout number Detection timeout in seconds
rssi_filter string RSSI filter preset used by receivers for tags in this class

Tag Type

tag_type can be:

Value Description
none No explicit tag type
mobile Mobile tag
fixed Fixed tag, normally used for anchors or static devices

RSSI Filter

rssi_filter is the Kalman RSSI filter preset configured for the class.

Common values are:

Value Description
stable More stable RSSI filtering
balanced Default balanced filtering
responsive More responsive filtering
noisy Filtering tuned for noisy environments
custom Custom preset marker

Configuration Frames

When present, settings.configuration is an array of tag configuration frames.

Each frame has this common shape:

Parameter Type Description
id number Numeric frame identifier used by the tag protocol
type string Logical frame type
data object or null Frame-specific configuration payload

The system can expose additional frame types when plugins or additional assemblies register custom TagConfigurationFrame implementations.

Core Configuration Frames

bleenc

Configures core tag behavior.

Typical data fields:

Field Type Description
button_enabled boolean Enables or disables the tag button
button_shutdown boolean Enables shutdown through the tag button
button_ack_feedback boolean Enables acknowledgement feedback on button actions
alerts_enabled boolean Enables alert features
accelerometer object Accelerometer and motion-related configuration
default object Default operating profile
active object Optional active operating profile
sleep object Optional sleep operating profile
calibrated_rssi_offset number RSSI calibration offset applied to the tag

Operating profile fields include advertising_interval, tx_power, optional timeout, and response_mode.

beacons

Configures beacon advertising payloads.

Typical data fields:

Field Type Description
type string Beaconing type
channel string Advertising channel
interval number Advertising interval
tx_power number Advertising transmission power
uuid string iBeacon UUID, when iBeacon advertising is used
namespace_id string Eddystone namespace, when Eddystone advertising is used
identifiers string Identifier mode
major number iBeacon major value, when serialized
minor number iBeacon minor value, when serialized
instance_id string Eddystone instance identifier, when serialized

The exact identifier fields depend on the selected beaconing type and identifier mode.

scanner

Configures BLE scanning behavior.

Typical data fields:

Field Type Description
protocol string Scan protocol
packet_type string Packet type to scan
uuid string Optional scan UUID, depending on protocol and packet type
mode number Scan mode bitmask
window number Scan window
interval object Scan interval, present when periodic scan mode is enabled
moving_time object Moving-time setting, present when on-motion-end mode is enabled
alerts

Configures alert feedback output.

Typical data fields:

Field Type Description
duty_cycle number Alert duty cycle
period number Alert period
repeats number Number of alert repetitions
interval number Interval between alert repetitions
buzzer boolean Enables buzzer output
vibration boolean Enables vibration output
led object LED output configuration

The led object contains led0, led1, led2, led3, color, and sequential. The color object contains red, green, and blue.

display

Configures e-paper or display canvas slots.

Typical data fields:

Field Type Description
count number Number of configured canvas slots
items array Canvas definitions. Present when count is greater than 0

The maximum canvas count supported by the core frame is 16.

Notes

  • The endpoint returns tag class settings, not individual tag state.
  • settings.configuration is omitted when no configuration frames are defined for a class.
  • All 8 classes are returned even when they contain only default settings.

GET /api/project/{id}/tracking


Returns the tracking configuration of a specific project.

URL Parameters

Key Type Description Required
id string Project identifier Yes

Responses

Status Code Status Description Description
200 OK The response contains the tracking configuration
400 ERR_MISSING_PROJECT_ID The project id was not provided
404 ERR_PROJECT_NOT_FOUND No project with the specified identifier exists

Response Example

{
  "realtime": {
    "enabled": true,
    "parameters": {
      "mode": "trilateration",
      "trilateration_min_rssi_threshold": -90,
      "trilateration_map_detection_rssi_delta": 5,
      "trilateration_averaging_anchors": 3,
      "trilateration_min_anchors": 1,
      "trilateration_max_anchors": 3,
      "trilateration_motion_threshold": 0.5
    }
  },
  "snapshot": {
    "enabled": true,
    "parameters": {
      "mode": "zoning",
      "zoning_min_rssi": -10,
      "zoning_delta_rssi": 3
    }
  },
  "proximity": {
    "enabled": true,
    "settings": {
      "preset": "balanced"
    }
  }
}

Tracking Payload

The response body is a tracking configuration object with three mandatory sections:

Parameter Type Description
realtime object Realtime tracking configuration
snapshot object Snapshot tracking configuration
proximity object Proximity tracking configuration
Realtime Tracking

realtime controls tracking computed continuously while receiver data is available.

Parameter Type Description
enabled boolean Enables or disables realtime tracking
parameters object Realtime tracking parameters. Present only if enabled

When enabled is false, the object contains only:

{
  "enabled": false
}

When enabled is true, parameters is present and must contain mode.

# Realtime trilateration Parameters

Supported mode value:

Value Description
trilateration Uses RSSI observations from multiple anchors to estimate position
Parameter Type Description
mode string Realtime tracking mode. Current supported value: trilateration
trilateration_min_rssi_threshold number Minimum RSSI threshold used by realtime trilateration
trilateration_map_detection_rssi_delta number RSSI delta used for map detection decisions
trilateration_averaging_anchors number Number of anchors used for averaging
trilateration_min_anchors number Minimum number of anchors required for trilateration
trilateration_max_anchors number Maximum number of anchors considered for trilateration
trilateration_motion_threshold number Motion threshold used by the realtime trilateration logic
Snapshot Tracking

snapshot controls tracking computed from a snapshot of receiver data.

Parameter Type Description
enabled boolean Enables or disables snapshot tracking
parameters object Snapshot tracking parameters. Present only if enabled

When enabled is false, the object contains only:

{
  "enabled": false
}

When enabled is true, parameters is present and must contain mode.

# Snapshot zoning Parameters

Supported mode value:

Value Description
zoning Selects a zone using RSSI thresholds and RSSI delta rules
Parameter Type Description
mode string Snapshot tracking mode. Value: zoning
zoning_min_rssi number Minimum RSSI accepted by zoning
zoning_delta_rssi number RSSI delta used to distinguish candidate zones
# Snapshot trilateration Parameters

Supported mode value:

Value Description
trilateration Uses RSSI observations from multiple anchors to estimate position
Parameter Type Description
mode string Snapshot tracking mode. Value: trilateration
trilateration_min_rssi number Minimum RSSI accepted by snapshot trilateration
Proximity Tracking

proximity controls proximity classification.

Parameter Type Description
enabled boolean Enables or disables proximity tracking
settings object Proximity settings. Present only if enabled

When enabled is false, the object contains only:

{
  "enabled": false
}

When enabled is true, settings is present.

# Proximity Presets

settings.preset can be one of:

Value Description
fast Fast reaction, lower stability
balanced Default balanced preset
stable More stable classification
noisy Conservative preset for noisy RSSI environments
custom Custom proximity thresholds
disabled Disables proximity settings

For non-custom presets, the serialized settings object contains only preset.

{
  "preset": "balanced"
}

For custom, the settings object contains the custom thresholds:

{
  "preset": "custom",
  "immediate": 0,
  "near": 10,
  "transition": 2.0,
  "hysteresis": 1000
}
Parameter Type Description
preset string Proximity preset
immediate number Immediate proximity threshold. Required for custom
near number Near proximity threshold. Required for custom
transition number Transition factor. Required for custom
hysteresis number Hysteresis duration in milliseconds. Required for custom

PUT /api/project/{id}/tracking


Updates the tracking configuration of a specific project.

The request body must contain the full tracking configuration. Partial updates are not supported.

URL Parameters

Key Type Description Required
id string Project identifier Yes

Request Body

The request body is the same tracking payload returned by GET /api/project/{id}/tracking.

Parameter Type Description Required
realtime object Realtime tracking configuration Yes
snapshot object Snapshot tracking configuration Yes
proximity object Proximity tracking configuration Yes

Request Example

{
  "realtime": {
    "enabled": true,
    "parameters": {
      "mode": "trilateration",
      "trilateration_min_rssi_threshold": -90,
      "trilateration_map_detection_rssi_delta": 5,
      "trilateration_averaging_anchors": 3,
      "trilateration_min_anchors": 1,
      "trilateration_max_anchors": 3,
      "trilateration_motion_threshold": 0.5
    }
  },
  "snapshot": {
    "enabled": true,
    "parameters": {
      "mode": "zoning",
      "zoning_min_rssi": -10,
      "zoning_delta_rssi": 3
    }
  },
  "proximity": {
    "enabled": true,
    "settings": {
      "preset": "balanced"
    }
  }
}

Payload Rules

Top-Level Object

All three top-level sections are required.

Parameter Type Description
realtime object Realtime tracking configuration
snapshot object Snapshot tracking configuration
proximity object Proximity tracking configuration

If any section is missing, the endpoint returns 400 ERR_CONFIG_PARSE.

Disabled Tracking Section

For realtime, snapshot, and proximity, a disabled section is represented as:

{
  "enabled": false
}

When enabled is false, parameters or settings is not required and is ignored by the parser.

Realtime Tracking
Parameter Type Description Required
enabled boolean Enables or disables realtime tracking Yes
parameters object Realtime tracking parameters Only if enabled is true

Supported realtime mode:

Value Description
trilateration Uses RSSI observations from multiple anchors to estimate position

For mode: "trilateration", parameters supports:

Parameter Type Description Required
mode string Realtime tracking mode. Must be trilateration Yes
trilateration_min_rssi_threshold number Minimum RSSI threshold used by realtime trilateration No, default -90
trilateration_map_detection_rssi_delta number RSSI delta used for map detection decisions No, default 5
trilateration_averaging_anchors number Number of anchors used for averaging No, default 3
trilateration_min_anchors number Minimum number of anchors required for trilateration Yes
trilateration_max_anchors number Maximum number of anchors considered for trilateration Yes
trilateration_motion_threshold number Motion threshold used by realtime trilateration. Must be greater than or equal to 0 Yes
Snapshot Tracking
Parameter Type Description Required
enabled boolean Enables or disables snapshot tracking Yes
parameters object Snapshot tracking parameters Only if enabled is true

Supported snapshot modes:

Value Description
zoning Selects a zone using RSSI thresholds and RSSI delta rules
trilateration Uses RSSI observations from multiple anchors to estimate position

For mode: "zoning", parameters supports:

Parameter Type Description Required
mode string Snapshot tracking mode. Must be zoning Yes
zoning_min_rssi number Minimum RSSI accepted by zoning Yes
zoning_delta_rssi number RSSI delta used to distinguish candidate zones Yes

For mode: "trilateration", parameters supports:

Parameter Type Description Required
mode string Snapshot tracking mode. Must be trilateration Yes
trilateration_min_rssi number Minimum RSSI accepted by snapshot trilateration Yes
Proximity Tracking
Parameter Type Description Required
enabled boolean Enables or disables proximity tracking Yes
settings object Proximity settings Only if enabled is true

Supported settings.preset values:

Value Description
fast Fast reaction, lower stability
balanced Default balanced preset
stable More stable classification
noisy Conservative preset for noisy RSSI environments
custom Custom proximity thresholds
disabled Disables proximity settings

For fast, balanced, stable, noisy, or disabled, the settings object only requires preset.

{
  "preset": "stable"
}

For custom, the following fields are required:

Parameter Type Description Required
preset string Must be custom Yes
immediate number Immediate proximity threshold Yes
near number Near proximity threshold Yes
transition number Transition factor Yes
hysteresis number Hysteresis duration in milliseconds Yes
{
  "preset": "custom",
  "immediate": 0,
  "near": 10,
  "transition": 2.0,
  "hysteresis": 1000
}

Responses

Status Code Status Description Description
200 OK The tracking configuration was accepted
400 ERR_MISSING_BODY The request body was not provided or is invalid
400 ERR_MISSING_PROJECT_ID The project id was not provided
400 ERR_CONFIG_PARSE The tracking configuration could not be parsed
404 ERR_PROJECT_NOT_FOUND No project with the specified identifier exists
500 ERR_STORE_PROJECT The updated project could not be stored

Response Example

{
  "update": 8,
  "tracking": {
    "realtime": {
      "enabled": true,
      "parameters": {
        "mode": "trilateration",
        "trilateration_min_rssi_threshold": -90,
        "trilateration_map_detection_rssi_delta": 5,
        "trilateration_averaging_anchors": 3,
        "trilateration_min_anchors": 1,
        "trilateration_max_anchors": 3,
        "trilateration_motion_threshold": 0.5
      }
    },
    "snapshot": {
      "enabled": true,
      "parameters": {
        "mode": "zoning",
        "zoning_min_rssi": -10,
        "zoning_delta_rssi": 3
      }
    },
    "proximity": {
      "enabled": true,
      "settings": {
        "preset": "balanced"
      }
    }
  }
}

Response Parameters

Parameter Type Description
update number Bitmask of changed tracking sections. 0 means no change
tracking object Current project tracking configuration after the request

Update Bitmask

Value Description
0 No change
2 Proximity tracking changed
4 Realtime tracking changed
8 Snapshot tracking changed

Values can be combined when more than one section changes.

GET /api/projects


Returns all projects defined in the system.

Responses

Status Code Status Description Description
200 OK The response contains an array of project objects

Response Example

[
  {
    "id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
    "description": "Warehouse tracking",
    "scan_channel": "ble39",
    "network_id": 5908,
    "sec_key": "00112233445566778899aabbccddeeff",
    "provision_params": {
      "network_id": 5908
    },
    "mqtt_connection": "production-mqtt",
    "gateway_mqtt_connection": "gateway-mqtt",
    "mqtt_connection_state": "running",
    "gateway_templates": [],
    "tag_settings": {},
    "tracking": {},
    "last_update": 1747897503525
  }
]
Response parameters
Parameter Type Description
id string Project identifier
description string Project description, if available
scan_channel string BLE scan channel configured for the project
network_id number BLE network identifier
sec_key string BLE security key, if configured
provision_params object Provisioning parameters configured for the project
mqtt_connection string MQTT connection used by the project, if configured
gateway_mqtt_connection string Gateway MQTT connection, if configured
mqtt_connection_state string Current MQTT source state, if the source is available
gateway_templates array Gateway templates configured for the project
tag_settings object Tag settings configured for the project
tracking object Project tracking configuration
last_update number Last project update timestamp, in Unix milliseconds

GET /api/status


Get all the information about system status.

Responses

Status Code Status Description Description
200 OK n/a

Response Example

{
    "uuid": <system_uuid>,
    "session_id": <session_id>,
    "os": { <os_info> },
    "hostname": <hostname>,
    "title": "bleenc v1.0.2505.21000",
    "version": <system_version>,
    "system": { <system_info> },
    "license": { <license_info> },
    "timezone": "Europe/Rome",
    "timestamp": 1747904755011,
    "activated": true,
    "started_on": 1747845248,
    "uptime": { <uptime> },
    "network": { <network_info> },
    "processors": 4, 
    "ram_total": 16540381184,
    "pressure": { <system_pressure> }
}

GET /api/system


This API returns the basic information about the BPE system.

Responses

Status Code Status Description
200 OK

Response Example

{
  "id": "bleenc",
  "uuid": "1c73b5b0-40a5-4a7f-8f63-6b6943d7f7f5",
  "description": "bleenc",
  "version": "1.0.2505.21000"
}
Response parameters
Parameter Type Description
id string BPE system identifier: bleenc
uuid string Unique system identifier
description string BPE system description: bleenc
version string BPE system version

GET /api/system/diagnostics


Get the system diagnostics information.

The response body is generated by the internal diagnostics composer. The available sections and the content of each data object depend on the diagnostics providers registered by the running system.

Responses

Status Code Status Description
200 OK

Response Example

{
  "status": {
    "description": "System Status",
    "data": {}
  },
  "threads": {
    "description": "System threads",
    "data": {}
  },
  "localStorage": {
    "description": "Local Storage",
    "data": {}
  },
  "clientHandler": {
    "description": "Client Handler",
    "data": {}
  },
  "eventManager": {
    "description": "EventManager",
    "data": {}
  },
  "httpServer": {
    "description": "Http Server",
    "data": {}
  }
}
Response parameters
Parameter Type Description
description string Human-readable description of the diagnostics section
data object Diagnostics data produced by the corresponding diagnostics module

GET /api/system/log


Get the current log file content.

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

Responses

Status Code Status Description Mime type Description
200 OK text/plain Current log file content
500 Internal server error JSON Error raised while preparing or reading the file

GET /api/system/log/{file}


Get the log content of a stored log file.

URL Parameters

Key Description
file The log file name <date>.log previously obtained calling /api/system/logs API

Responses

Status Code Status Description Mime type Description
200 OK text/plain Requested log file content
404 Not found text/plain The requested log file does not exist
500 Internal server error JSON Error raised while preparing or reading the file

GET /api/system/logs


Get the list of execution log files stored by the system.

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
  }
]
Response parameters
Parameter Type Description
name string Log file name
size number Log file size in bytes
current boolean Indicates whether this is the current log file
created number UNIX timestamp of the file creation time
last_write number UNIX timestamp of the last file write time

GET /api/tag/{id}


Returns the information related to a specific tag.

The tag is resolved by its device identifier. If the identifier is missing or no matching tag exists, the endpoint returns an error response.

URL Parameters

Key Type Description Required
id string Tag ID Yes

Responses

Status Code Status Description Description
200 OK The response contains the information about the requested tag.
400 ERR_MISSING_TAG_ID The id URL parameter is missing.
404 ERR_TAG_NOT_FOUND No tag was found with the provided ID.

Response Example

{
  "uid": 63,
  "type": "Tag",
  "model": "bleenc",
  "id": "fa000b0e",
  "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
  "alias": "Safex Plus",
  "last_update": 1779811693515,
  "last_update_et": 741,
  "device": 250,
  "serial": 2830,
  "mac_address": "cb:00:fa:00:0b:0e",
  "network_id": 1347,
  "class": 0,
  "firmware": "4.3.1",
  "hardware": {
    "model": 250,
    "revision": 16,
    "variant": 0,
    "led_0": "rgb",
    "led_1": "none",
    "led_2": "none",
    "led_3": "none",
    "button_1": true,
    "button_2": true,
    "button_3": false,
    "button_4": false,
    "gpio_1": false,
    "gpio_2": false,
    "gpio_3": false,
    "gpio_4": false,
    "accelerometer": true,
    "buzzer": true,
    "vibration": true,
    "display": false
  },
  "alert_running": false,
  "cfg_seq": 70,
  "cfg_status": "match",
  "cmd_seq": 4,
  "state": "default",
  "moving": false,
  "motion_date": 1779810803051,
  "motion_time": 890891,
  "alarm_type": "none",
  "alarm_count": 0,
  "button_evt": "none",
  "buttons": [
    false,
    false,
    false,
    false
  ],
  "button_press_count": 20,
  "power_connected": false,
  "battery_low": false,
  "battery": 4010,
  "calibrated_rssi": -54,
  "receivers": 8,
  "nearest_receiver": {
    "id": "00007cdfa1fe411c",
    "alias": "Dev 3 (441c)",
    "rssi_raw": -45,
    "rssi": -44.335471646424,
    "rssi_offset": 0,
    "rssi_stability": 0.992148651502626,
    "attenuation": -9.66452835357602,
    "n": 1.6,
    "estimated_distance": 0.248866808224459,
    "proximity": 3,
    "last_update": 1779811693500,
    "last_update_et": 756
  },
  "scan_enabled": true,
  "realtime_tracking": {
    "type": "estimated",
    "last_update": 1779810804191,
    "map": {
      "id": "cc5b3382-4aed-4000-b362-e463495c00b7",
      "description": "Ufficio BlueUp"
    },
    "mode": "realtime",
    "estimator": "trilateration",
    "position": {
      "x": 9.254,
      "y": 11.387,
      "z": 0
    },
    "accuracy": 1
  },
  "snapshot_tracking": {
    "type": "estimated",
    "last_update": 1779808821448,
    "map": {
      "id": "cc5b3382-4aed-4000-b362-e463495c00b7",
      "description": "Ufficio BlueUp"
    },
    "mode": "snapshot",
    "estimator": "zoning",
    "zone": {
      "id": "dev2",
      "description": "Development 2"
    }
  },
  "detected": true
}
Response Parameters
Parameter Type Description
uid number Internal device numeric identifier.
type string Device type. For this endpoint the value is Tag.
model string Device model family.
id string Tag identifier.
project_id string Project ID associated with the tag.
alias string Device alias, available when an alias is set.
last_update number UNIX timestamp in milliseconds of the latest device update.
last_update_et number Elapsed time from the last update in milliseconds.
device number Device model number.
serial number Device serial number.
mac_address string Device MAC address.
network_id number Network ID.
class number Device class number.
firmware string Device firmware version.
hardware object Device hardware characteristics.
alert_running bool Indicates whether an alert is currently running on the device.
cfg_seq number Configuration sequence identifier.
cfg_status string Indicates whether the configuration set in bleenc matches the configuration on the device.
cmd_seq number Sequence of the command sent to the device.
state string Device state.
moving bool Indicates whether the device is moving.
motion_date number UNIX timestamp in milliseconds of when the device started or stopped moving.
motion_time number Elapsed time in milliseconds since the device started or stopped moving.
alarm_type string Type of alarm raised on the device.
alarm_count number Number of alarms raised on the device since the last reboot or power on.
button_evt string Type of button event reported by the device.
buttons array[bool] Four-item array indicating which buttons are currently pressed.
button_press_count number Counter of button presses since the last device reboot or power on.
power_connected bool Indicates whether a rechargeable device is connected to a power supply.
battery_low bool Indicates whether the battery is low.
battery number Battery level in mV.
calibrated_rssi number Device RSSI calibration level.
receivers number Number of receivers currently detecting the device.
nearest_receiver object Information about the nearest receiver.
scan_enabled bool Indicates whether the device is configured to perform device scans.
realtime_tracking object Current realtime tracking data, when available.
snapshot_tracking object Current snapshot tracking data, when available.
detected bool Indicates whether the device is currently detected by at least one gateway.
location object Static device location, when configured.

DELETE /api/tag/{id}/alias


Removes an alias to provided tag

URL Parameters

Key Type Description Required
id string Tag ID Yes

Responses

Status Code Status Description Description
400 ERR_MISSING_BODY The request does not contain a JSON Object body
404 ERR_TAG_NOT_FOUND The provided tag does not exist
200 OK Operation was successful

Response Example

{
    "project_id": string,
    "tag_id": string,
    "alias": null
}
Response parameters
Parameter Type Description
project_id string Project ID
tag_id string Tag ID
alias null Alias

GET /api/tag/{id}/alias


Retrieve the alias set on the provided tag.

URL Parameters

Key Type Description Required
id string Tag ID Yes

Responses

Status Code Status Description Description
200 OK The response contains the information about the requested tag

Response Example

{
    "project_id": string,
    "tag_id": string,
    "alias": string | null
}
Response parameters
Parameter Type Description
project_id string Project ID
tag_id string Tag ID
alias string | null Alias

POST /api/tag/{id}/alias


Set an alias to provided tag

URL Parameters

Key Type Description Required
id string Tag ID Yes

Body parameters

{
    "alias": string (mandatory)
}

Responses

Status Code Status Description Description
400 ERR_MISSING_BODY The request does not contain a JSON Object body
400 ERR_MISSING_ALIAS The request body does not contain the key alias
404 ERR_TAG_NOT_FOUND The provided tag does not exist
200 OK Operation was successful

Response Example

{
    "project_id": string,
    "tag_id": string,
    "alias": string | null
}
Response parameters
Parameter Type Description
project_id string Project ID
tag_id string Tag ID
alias string | null Alias

PUT /api/tag/{id}/class


Changes the class of a specific tag.

This endpoint is a REST alias for sending a unicast class command through POST /api/command. It builds the same internal TagSetClassFrame command and sends it to the tag identified by the URL parameter.

URL Parameters

Key Type Description Required
id string Tag ID Yes

Body Parameters

Key Type Description Required
class number New tag class. Valid range is 0 to 7. Yes
timeout number Timeout in milliseconds. If omitted or too low it is clamped to 5000 ms; if above 60000 ms it is clamped to 60000 ms. No
gateway string Optional gateway ID. If missing or not found, the system automatically selects a gateway or broadcasts through all suitable gateways. No

Request Example

{
  "class": 2,
  "timeout": 30000,
  "gateway": "00007cdfa1fe411c"
}

Responses

Status Code Status Description Description
200 OK The class command completed and the response body contains the command result.
400 ERR_MISSING_TAG_ID The id URL parameter is missing.
400 ERR_MISSING_BODY Body is missing or is not a valid JSON object.
400 ERR_MISSING_CLASS The class body parameter is missing.
400 ERR_INVALID_CLASS The class body parameter is outside the valid range.
404 ERR_TAG_NOT_FOUND No tag was found with the provided ID.
408 ERR_TIMEOUT The command did not complete within the configured timeout.
500 ERR_UNABLE_TO_SEND_COMMAND Internal error during command dispatch. The response body contains details when available.

The response body is dynamically generated by the command handler after the internal class command completes.

PUT /api/tag/{id}/location


Sets the tag static location inside a map.

A tag can be assigned a static location only when its class is configured with TagType set to Fixed. This is normally the case for tags configured as anchor beacons. Tags whose class is configured as Mobile cannot be assigned a static location and the endpoint returns ERR_STATIC_LOCATION_NOT_ALLOWED.

URL Parameters

Key Type Description Required
id string Tag ID Yes

Body Parameters

{
  "map": "cc5b3382-4aed-4000-b362-e463495c00b7",
  "position": {
    "x": 12.4,
    "y": 8.7,
    "z": 0
  }
}
Parameter Type Description Required
map string ID of the map where the tag is. Yes
position object Tag position inside the map. Yes
Position Object
Parameter Type Description Required
x number X coordinate. Yes
y number Y coordinate. Yes
z number Z coordinate. No

Responses

Status Code Status Description Description
200 OK The response contains the updated location.
400 ERR_MISSING_BODY The request does not contain a JSON object body.
400 ERR_MISSING_TAG_ID The id URL parameter is missing.
400 ERR_STATIC_LOCATION_NOT_ALLOWED The tag class is not configured with TagType set to Fixed.
400 ERR_INVALID_LOCATION The request body does not contain a valid map.
400 ERR_MISSING_LOCATION_POSITION The request body does not contain position.
400 ERR_INVALID_LOCATION_POSITION The provided position is malformed.
404 ERR_TAG_NOT_FOUND No tag was found with the provided ID.
404 ERR_MAP_NOT_FOUND No map was found with the provided ID.

Response Example

{
  "location": {
    "type": "static",
    "last_update": 1779810804191,
    "map": {
      "id": "cc5b3382-4aed-4000-b362-e463495c00b7",
      "description": "Warehouse"
    },
    "position": {
      "x": 12.4,
      "y": 8.7,
      "z": 0
    },
    "zone": {
      "id": "warehouse-a",
      "description": "Warehouse A"
    }
  }
}
Response Parameters
Parameter Type Description
location object Tag static location.

DELETE /api/tag/{id}/location


Removes the tag static location inside a map.

A tag can have a static location only when its class is configured with TagType set to Fixed. This is normally the case for tags configured as anchor beacons. This endpoint can remove the current static location from any existing tag.

URL Parameters

Key Type Description Required
id string Tag ID Yes

Responses

Status Code Status Description Description
200 OK The static location was removed.
400 ERR_MISSING_TAG_ID The id URL parameter is missing.
404 ERR_TAG_NOT_FOUND No tag was found with the provided ID.

Response Example

{
  "location": null
}
Response Parameters
Parameter Type Description
location null Tag static location after the remove action.

GET /api/tag/{id}/location


Gets the tag static location inside a map.

A tag can have a static location only when its class is configured with TagType set to Fixed. This is normally the case for tags configured as anchor beacons. Tags whose class is configured as Mobile cannot be assigned a static location.

URL Parameters

Key Type Description Required
id string Tag ID Yes

Responses

Status Code Status Description Description
200 OK The response contains the tag location.
400 ERR_MISSING_TAG_ID The id URL parameter is missing.
404 ERR_TAG_NOT_FOUND No tag was found with the provided ID.

Response Example

{
  "location": {
    "type": "static",
    "last_update": 1779810804191,
    "map": {
      "id": "cc5b3382-4aed-4000-b362-e463495c00b7",
      "description": "Warehouse"
    },
    "position": {
      "x": 12.4,
      "y": 8.7,
      "z": 0
    },
    "zone": {
      "id": "warehouse-a",
      "description": "Warehouse A"
    }
  }
}

When no static location is assigned, the response contains null.

{
  "location": null
}
Response Parameters
Parameter Type Description
location object null

GET /api/tag/{id}/receivers


Returns the current receivers of a tag.

The response contains the gateways currently detecting the tag, with RSSI, proximity and timing information.

URL Parameters

Key Type Description Required
id string Tag ID Yes

Responses

Status Code Status Description Description
200 OK The response contains the current receivers of the tag
400 ERR_MISSING_TAG_ID The id URL parameter is missing
404 ERR_TAG_NOT_FOUND No tag was found with the provided ID

Response Example

[
  {
    "id": "000048ca439c429c",
    "alias": "Dev 0",
    "rssi_raw": -48,
    "rssi": -48.3508427766572,
    "rssi_offset": 0,
    "rssi_stability": 0.991777030272854,
    "attenuation": -5.64915722334281,
    "n": 1,
    "estimated_distance": 0.272322971722443,
    "proximity": 3,
    "location": {
      "type": "static",
      "last_update": 1768512000000,
      "map": {
        "id": "cc5b3382-4aed-4000-b362-e463495c00b7",
        "description": "Warehouse"
      },
      "position": {
        "x": 12.4,
        "y": 8.7,
        "z": 0
      },
      "zone": {
        "id": "warehouse-a",
        "description": "Warehouse A"
      }
    },
    "last_update": 1768512132428,
    "last_update_et": 231
  }
]
Receiver object fields
Parameter Type Description
id string Gateway ID
alias string Gateway alias, when set
rssi_raw number Raw RSSI
rssi number Filtered RSSI
rssi_offset number RSSI offset
rssi_stability number Signal stability (experimental)
attenuation number Signal attenuation
n number Environmental factor
estimated_distance number Estimated distance between tag and gateway in meters
proximity number Current proximity value, see table below
location object Gateway static location, when configured
last_update number Last update UNIX timestamp in milliseconds
last_update_et number Elapsed time from last update in milliseconds
Proximity conversion table
Value Description
0 None
1 Far
2 Near
3 Immediate

GET /api/tags


Fetches the tags currently known by the system.

When no filter is provided, the endpoint returns the full tag collection serialized by the tag manager. Passing the optional project query string parameter restricts the response to the tags associated with that project. The project value must be a valid UUID and must reference an existing project.

The endpoint supports FTR query parameters and inline FTR queries. When an FTR query is provided, the query is applied to the tag array before returning the response.

Query String parameters

Parameter Type Description :Optional:
project string Project UUID used to filter tags by project Yes

Responses

Status Code Status Description Description
200 OK The response contains an array of tags connected to the system with related information.
400 ERR_INVALID_PROJECT_ID The project query string parameter is not a valid UUID.
404 ERR_PROJECT_NOT_FOUND The project specified by the project query string parameter does not exist.
500 ERR_FTR_QUERY The FTR query could not be processed. The response body contains the query exception details when available.

Response Example

[
  {
    "uid": 63,
    "type": "Tag",
    "model": "bleenc",
    "id": "fa000b0e",
    "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
    "alias": "Safex Plus",
    "last_update": 1779811693515,
    "last_update_et": 741,
    "device": 250,
    "serial": 2830,
    "mac_address": "cb:00:fa:00:0b:0e",
    "network_id": 1347,
    "class": 0,
    "firmware": "4.3.1",
    "hardware": {
      "model": 250,
      "revision": 16,
      "variant": 0,
      "led_0": "rgb",
      "led_1": "none",
      "led_2": "none",
      "led_3": "none",
      "button_1": true,
      "button_2": true,
      "button_3": false,
      "button_4": false,
      "gpio_1": false,
      "gpio_2": false,
      "gpio_3": false,
      "gpio_4": false,
      "accelerometer": true,
      "buzzer": true,
      "vibration": true,
      "display": false
    },
    "alert_running": false,
    "cfg_seq": 70,
    "cfg_status": "match",
    "cmd_seq": 4,
    "state": "default",
    "moving": false,
    "motion_date": 1779810803051,
    "motion_time": 890891,
    "alarm_type": "none",
    "alarm_count": 0,
    "button_evt": "none",
    "buttons": [
      false,
      false,
      false,
      false
    ],
    "button_press_count": 20,
    "power_connected": false,
    "battery_low": false,
    "battery": 4010,
    "calibrated_rssi": -54,
    "receivers": 8,
    "nearest_receiver": {
      "id": "00007cdfa1fe411c",
      "alias": "Dev 3 (441c)",
      "rssi_raw": -45,
      "rssi": -44.335471646424,
      "rssi_offset": 0,
      "rssi_stability": 0.992148651502626,
      "attenuation": -9.66452835357602,
      "n": 1.6,
      "estimated_distance": 0.248866808224459,
      "proximity": 3,
      "last_update": 1779811693500,
      "last_update_et": 756
    },
    "scan_enabled": true,
    "realtime_tracking": {
      "type": "estimated",
      "last_update": 1779810804191,
      "map": {
        "id": "cc5b3382-4aed-4000-b362-e463495c00b7",
        "description": "Ufficio BlueUp"
      },
      "mode": "realtime",
      "estimator": "trilateration",
      "position": {
        "x": 9.254,
        "y": 11.387,
        "z": 0
      },
      "accuracy": 1
    },
    "snapshot_tracking": {
      "type": "estimated",
      "last_update": 1779808821448,
      "map": {
        "id": "cc5b3382-4aed-4000-b362-e463495c00b7",
        "description": "Ufficio BlueUp"
      },
      "mode": "snapshot",
      "estimator": "zoning",
      "zone": {
        "id": "dev2",
        "description": "Development 2"
      }
    },
    "detected": true
  }
]
Response parameters
Parameter Type Description
type string Device type: Tag
model string Device model: bleenc
id string Device identifier
project_id string Project ID
alias string Device alias, avaiable if the alias is set
last_update number UNIX timestamp of the latest device update
last_update_et number Elapsed time from the last update in ms
device number Device model number
serial number Device serial number
mac_address string Device MAC address
network_id number Network ID
class number Device class number. A tag can be programmed to work in one of 8 different class numers
firmware string Device FW version
hardware object Device hardware characteristics
alert_running bool Parameter reporting wether an alert is currently running on the device
cfg_seq number Configuration sequence identifier
cfg_status string Parameter reporting wether the configuration set in bleenc matches the configuration on the device
cmd_seq number Sequence of the command sent to the device
state string Device state. Possible states are:
- Idle
- Active
- Sleep
- Off
moving bool Parameter reporting wether the device is moving or is still
motion_date number UNIX timestamp of when the device started/stopped moving, according to the moving parameter
motion_time number Time elapsed form when the device started/stopped moving, according to the moving parameter
alarm_type string Type of alarm raised on the device. Possible alarms are:
- None
- Shock
- Mandown
- No motion
alarm_count number Counter of the number of alarms raised on the device since the last reboot or power on
button_evt string Type of button pressed on the device. Possible button events are:
- None
- Pressed
- Long
- N-clicks (up to 5 clicks are reported)
buttons array[0..3] Array the indicates which button was pressed. button1 = 0, button2=1, button3 = 2, button4=3
button_press_count number Counter of button presses since the last device reboot or power on
power_connected bool Related to rechargeable devices, parametrer reporting wether the device is connected to a power-supply
battery_low bool Parameter reporting wether the battery is low
battery number Parameter reporting the battery level in mV
calibrated_rssi number Device RSSI level calibration
receivers number Number of receivers that detect the device
nearest_receiver object Object containing information regarding the nearest receiver, such as Received ID, RSSI, proximity, estimated distance, and others
scan_enabled bool Parameter reporting wether the device is configured to perform Device scans
detected bool Parameter reporting wether the device is currently detected. This parameter is set to true when the device is detected by at least one gateway
location object Object containing information about the current device location

POST /api/webhook


Creates a webhook.

Body parameters

Key Type Description Optional
description string The webhook description. It is trimmed and sanitized before being stored. No
endpoint string The remote HTTP or HTTPS endpoint that will receive webhook events. No
validate_certificate boolean Enables TLS certificate validation for HTTPS endpoints. Default: true. Yes
auth object Authentication configuration used when sending webhook requests. No
project string Optional project filter. If set, only events belonging to this project are sent. Yes
event_selection string Event selection mode: all, inclusion, or exclusion. No
events array List of event identifiers. Required when event_selection is not all. Yes
retry_window number Maximum retry window, in seconds. Minimum value: 30. No
retry_interval number Delay between retry attempts, in seconds. Minimum value: 1. No
signature_key string Secret key used to calculate the webhook HMAC signature. No

Authentication object

The auth object always requires a mode field.

Supported modes are:

  • none
  • basic
  • bearer
No authentication
{
  "mode": "none"
}
Basic authentication
{
  "mode": "basic",
  "params": {
    "username": "my-user",
    "password": "my-password"
  }
}

The webhook sender will use the following HTTP header:

Authorization: Basic <base64(username:password)>
Bearer authentication
{
  "mode": "bearer",
  "params": {
    "token": "my-token"
  }
}

The webhook sender will use the following HTTP header:

Authorization: Bearer <token>

Event selection

The event_selection field controls which events are forwarded.

Value Description
all All matching events are sent.
inclusion Only events listed in events are sent.
exclusion Events listed in events are ignored.

When event_selection is inclusion or exclusion, the events array is required and must contain at least one valid event identifier.

Example request

{
  "description": "Production webhook",
  "endpoint": "https://example.com/webhooks/bleenc",
  "validate_certificate": true,
  "auth": {
    "mode": "bearer",
    "params": {
      "token": "my-secret-token"
    }
  },
  "project": "project-001",
  "event_selection": "inclusion",
  "events": [
    "tag.updated",
    "button.pressed"
  ],
  "retry_window": 60,
  "retry_interval": 5,
  "signature_key": "my-hmac-secret"
}

Successful response

Returns 200 OK and the created webhook object.

{
  "id": "webhook-id",
  "description": "Production webhook",
  "enabled": false,
  "state": "idle",
  "project": "project-001",
  "endpoint": "https://example.com/webhooks/bleenc",
  "validate_certificate": true,
  "auth": {
    "mode": "bearer",
    "params": {
      "token": "my-secret-token"
    }
  },
  "event_selection": "inclusion",
  "events": [
    "button.pressed",
    "tag.updated"
  ],
  "retry_window": 60,
  "retry_interval": 5,
  "signature_key": "my-hmac-secret"
}

Error responses

HTTP status Error Description
400 ERR_INVALID_BODY The request body is missing or is not valid JSON.
400 ERR_MISSING_DESCRIPTION Missing description.
400 ERR_MISSING_ENDPOINT Missing endpoint.
400 ERR_INVALID_ENDPOINT The endpoint is not a valid absolute URI.
400 ERR_INVALID_ENDPOINT_SCHEME The endpoint scheme is not http or https.
400 ERR_MISSING_AUTHENTICATION Missing auth object.
400 ERR_INVALID_AUTHENTICATION Invalid authentication configuration.
400 ERR_PROJECT_NOT_FOUND The specified project does not exist.
400 ERR_MISSING_EVENT_SELECTION Missing event_selection.
400 ERR_INVALID_EVENT_SELECTION Invalid event selection mode.
400 ERR_MISSING_EVENT_LIST Missing events array when required.
400 ERR_INVALID_EVENT_LIST The event list is empty or invalid.
400 ERR_MISSING_RETRY_WINDOW Missing retry_window.
400 ERR_MISSING_RETRY_INTERVAL Missing retry_interval.
400 ERR_MISSING_SIGNATURE_KEY Missing signature_key.
400 ERR_INVALID_SIGNATURE_KEY The signature key is empty.
500 ERR_STORAGE_ERROR The webhook could not be stored.

Webhook delivery format

When a webhook is running and receives a matching event, the system sends an HTTP POST request to the configured endpoint.

Request headers sent to the remote endpoint

Header Description
User-Agent Application name, version, system id and webhook id.
Authorization Optional authentication header, depending on auth.
X-Webhook-Id The webhook identifier.
X-Webhook-Timestamp Unix timestamp generated when the event is sent.
X-Webhook-Signature HMAC-SHA256 signature of the payload.
Content-Type application/json.

Signature

The signature is calculated as:

HMACSHA256(
  key = signature_key,
  data = timestamp + "." + webhook_id + "." + payload
)

The resulting hash is encoded as hexadecimal string.

Receivers should verify the signature before processing the webhook payload.

Successful delivery responses

The following HTTP status codes are considered successful:

HTTP status Description
200 OK
202 Accepted
204 No Content

Retryable delivery responses

The following HTTP status codes are considered retryable:

HTTP status Description
408 Request Timeout
425 Too Early
429 Too Many Requests
500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout

Other non-success HTTP status codes are treated as final delivery failures.


Customer recommendations

Endpoint availability

The remote endpoint should be highly available and should respond quickly. The webhook sender uses a 30-second HTTP timeout.

Idempotency

Receivers should treat webhook requests as potentially duplicated. Network errors or retryable responses may cause the same event to be sent more than once.

Signature verification

Receivers should verify X-Webhook-Signature using the configured signature_key before processing the payload.

Timestamp validation

Receivers may use X-Webhook-Timestamp to reject old requests and reduce replay risk.

TLS certificate validation

For production HTTPS endpoints, validate_certificate should remain true.

Disabling TLS certificate validation allows invalid, expired or self-signed certificates and should only be used for testing or controlled environments.

Retry policy

The webhook system retries failed deliveries only within the configured retry_window. After that window expires, the event is considered failed.

Pending queue behavior

Pending events are kept in memory. If the webhook is disabled or the system shuts down, queued events may be discarded.

PUT /api/webhook/{id}


Partially updates an idle webhook.

The webhook must be in the idle state. Running, starting or stopping webhooks cannot be updated.

Unlike creation, this endpoint supports partial updates: only the fields included in the request body are modified.

URL parameters

Key Type Description Optional
id string The webhook identifier. No

Body parameters

Key Type Description Optional
description string The webhook description. It is trimmed and sanitized before being stored. Yes
endpoint string The remote HTTP or HTTPS endpoint that will receive webhook events. Yes
validate_certificate boolean Enables TLS certificate validation for HTTPS endpoints. Yes
auth object Authentication configuration used when sending webhook requests. Yes
project string or null Optional project filter. Use null to clear the project filter. Yes
event_selection string Event selection mode: all, inclusion, or exclusion. Yes
events array List of event identifiers. Required when changing event_selection to inclusion or exclusion. Yes
retry_window number Maximum retry window, in seconds. Minimum value: 30. Yes
retry_interval number Delay between retry attempts, in seconds. Minimum value: 1. Yes
signature_key string Secret key used to calculate the webhook HMAC signature. Yes

Example request

{
  "description": "Updated production webhook",
  "validate_certificate": true,
  "retry_window": 120,
  "retry_interval": 10
}

Example: clear project filter

{
  "project": null
}

Example: change event selection

{
  "event_selection": "exclusion",
  "events": [
    "debug.event",
    "test.event"
  ]
}

Successful response

Returns 200 OK and the updated webhook object.

Error responses

HTTP status Error Description
400 ERR_MISSING_WEBHOOK_ID Missing webhook id in URL arguments.
400 ERR_INVALID_BODY The request body is missing or is not valid JSON.
400 ERR_INVALID_EVENT_SELECTION Invalid event selection mode.
400 ERR_MISSING_EVENT_LIST Missing events array when required.
400 ERR_INVALID_EVENT_LIST The event list is empty or invalid.
400 ERR_INVALID_SIGNATURE_KEY The signature key is empty.
404 ERR_WEBHOOK_NOT_FOUND The webhook does not exist.
409 ERR_INVALID_WEBHOOK_STATE The webhook is not idle and cannot be updated.
409 ERR_UNEXPECTED_WEBHOOK_STATE The webhook is in an unexpected state.
400 ERR_WEBHOOK_EMPTY_DESCRIPTION The provided description is empty.
400 ERR_INVALID_ENDPOINT The endpoint is not a valid absolute URI.
400 ERR_INVALID_ENDPOINT_SCHEME The endpoint scheme is not http or https.
400 ERR_INVALID_AUTHENTICATION Invalid authentication configuration.
404 ERR_PROJECT_NOT_FOUND The specified project does not exist.
500 ERR_STORAGE_ERROR The webhook could not be stored.

GET /api/webhook/{id}


Gets a webhook by identifier.

This API returns the configuration of a single webhook identified by its unique id.

Path parameters

Key Type Description Optional
id string The webhook unique identifier No

Body parameters

This request does not require a body.

Successful response

If the webhook exists, the server returns:

200 OK

The response body contains the webhook object.

{
  "id": "018f7e3b-1c9a-4f3d-9d4d-33d46f12d8a1",
  "description": "ERP integration",
  "enabled": true,
  "state": "running",
  "project": "cc5b3382-4aed-4000-b362-e463495c00b7",
  "endpoint": "https://example.com/webhooks/bleenc",
  "validate_certificate": true,
  "auth": {
    "mode": "bearer",
    "params": {
      "token": "example-token"
    }
  },
  "event_selection": "inclusion",
  "events": [
    "tagLocationUpdated",
    "tagButtonPressed"
  ],
  "retry_window": 60,
  "retry_interval": 1,
  "signature_key": "example-signature-key"
}

Webhook object

Key Type Description Optional
id string The webhook unique identifier No
description string The webhook description No
enabled boolean Indicates whether the webhook is configured as enabled No
state string The current runtime state of the webhook No
project string The project filter, when configured Yes
endpoint string The remote HTTP/HTTPS endpoint No
validate_certificate boolean Whether the TLS server certificate is validated No
auth object The webhook authentication configuration No
event_selection string The event selection mode: all, inclusion, exclusion No
events array The selected event list, when applicable Yes
retry_window number Total retry window, in seconds No
retry_interval number Delay between retry attempts, in seconds No
signature_key string The secret key used to calculate the HMAC signature No

State values

Value Description
idle The webhook is stopped
starting The webhook is starting
running The webhook is active
stopping The webhook is stopping

Error responses

Status Error code Description
400 ERR_MISSING_ID The webhook id was not provided in the URL path
404 ERR_WEBHOOK_NOT_FOUND No webhook with the specified id exists

Example request

GET /api/webhook/018f7e3b-1c9a-4f3d-9d4d-33d46f12d8a1

DELETE /api/webhook/{id}


Deletes an idle webhook.

The webhook must be in idle state before it can be deleted. Running, starting or stopping webhooks cannot be deleted.

Path parameters

Key Type Description Optional
id string The webhook unique identifier No

Body parameters

This request does not require a body.

Successful response

If the webhook is successfully deleted, the server returns:

200 OK

No response body is required.

Error responses

Status Error code Description
400 ERR_MISSING_WEBHOOK_ID The webhook id was not provided in the URL path
404 ERR_WEBHOOK_NOT_FOUND No webhook with the specified id exists
400 ERR_WEBHOOK_INVALID_STATE The webhook is not in idle state and cannot be deleted
500 ERR_DELETE_WEBHOOK The webhook could not be deleted from persistent storage
500 ERR_DROP_WEBHOOK The webhook could not be dropped safely

Invalid state response

If the webhook is not idle, the response includes the current state:

{
  "state": "running"
}

Possible state values are:

Value Description
idle The webhook is stopped and can be deleted
starting The webhook is starting
running The webhook is active
stopping The webhook is stopping

Example request

DELETE /api/webhook/018f7e3b-1c9a-4f3d-9d4d-33d46f12d8a1

Operational notes

A webhook should be disabled before deletion.

Deleting a webhook removes its configuration from the system and from persistent storage. Once deleted, the webhook can no longer be enabled, disabled or updated.

If the webhook is currently running, call the disable API first and wait for the webhook to return to idle state before deleting it.

POST /api/webhook/{id}/disable


Disables a running or starting webhook.

The webhook can be disabled while it is running or starting.

When disabled, the system unsubscribes from events, cancels pending delivery operations, stops the processing thread, discards pending queued events, disposes the HTTP client and moves the webhook back to the idle state.

The request completes successfully only when the webhook reaches the idle state.

URL parameters

Key Type Description Optional
id string The webhook identifier. No

Successful response

Returns 200 OK.

If the webhook is already disabled, the endpoint also returns 200 OK.

Error responses

HTTP status Error Description
400 ERR_MISSING_WEBHOOK_ID Missing webhook id in URL arguments.
404 ERR_WEBHOOK_NOT_FOUND The webhook does not exist.
400 ERR_WEBHOOK_INVALID_STATE The webhook is not running or starting.
500 ERR_WEBHOOK_DISABLE_FAILED The disable operation could not be started.

POST /api/webhook/{id}/enable


Enables an idle webhook.

The webhook must be in the idle state. When enabled, the system creates the HTTP client, configures the authentication header, subscribes to matching system events and moves the webhook to the running state.

The request completes successfully only when the webhook reaches the running state.

URL parameters

Key Type Description Optional
id string The webhook identifier. No

Successful response

Returns 200 OK.

If the webhook is already enabled, the endpoint also returns 200 OK.

Error responses

HTTP status Error Description
400 ERR_MISSING_WEBHOOK_ID Missing webhook id in URL arguments.
400 ERR_WEBHOOK_INVALID_STATE The webhook is not idle and cannot be enabled.
400 ERR_WEBHOOK_START_FAILED The webhook could not reach the running state.
404 ERR_WEBHOOK_NOT_FOUND The webhook does not exist.
500 ERR_WEBHOOK_ENABLE_FAILED The enable operation could not be started.

GET /api/webhooks


Lists all configured webhooks.

This API returns the complete list of webhook configurations currently defined in the system.

The endpoint supports stored FTR queries and inline FTR queries. When an FTR query is provided, it is applied to the webhook array before the response is returned. Without an FTR query, the array is returned unchanged.

Path parameters

This request does not require path parameters.

Body parameters

This request does not require a body.

Successful response

If the request succeeds, the server returns:

200 OK

The response body contains an array of webhook objects.

[
  {
    "id": "018f7e3b-1c9a-4f3d-9d4d-33d46f12d8a1",
    "description": "ERP integration",
    "enabled": true,
    "state": "running",
    "project": "cc5b3382-4aed-4000-b362-e463495c00b7",
    "endpoint": "https://example.com/webhooks/bleenc",
    "validate_certificate": true,
    "auth": {
      "mode": "bearer",
      "params": {
        "token": "example-token"
      }
    },
    "event_selection": "inclusion",
    "events": [
      "tagLocationUpdated",
      "tagButtonPressed"
    ],
    "retry_window": 60,
    "retry_interval": 1,
    "signature_key": "example-signature-key"
  }
]

Webhook object

Key Type Description Optional
id string The webhook unique identifier No
description string The webhook description No
enabled boolean Indicates whether the webhook is configured as enabled No
state string The current runtime state of the webhook No
project string The project filter, when configured Yes
endpoint string The remote HTTP/HTTPS endpoint No
validate_certificate boolean Whether the TLS server certificate is validated No
auth object The webhook authentication configuration No
event_selection string The event selection mode: all, inclusion, exclusion No
events array The selected event list, when applicable Yes
retry_window number Total retry window, in seconds No
retry_interval number Delay between retry attempts, in seconds No
signature_key string The secret key used to calculate the HMAC signature No

State values

Value Description
idle The webhook is stopped
starting The webhook is starting
running The webhook is active
stopping The webhook is stopping

Error responses

HTTP status Error Description
500 ERR_FTR_QUERY The FTR query could not be processed. Diagnostic details are returned when available.

Example request

GET /api/webhooks

GET /api/event-stream


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

The response body will be a stream of 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.

The endpoint is subject to the API authorization settings configured in the system.

Parameters

project (Optional)

A valid project UUID created in the bleenc instance. When specified, only project-related events for the requested project are sent. Events that are not related to a project are ignored.

listen (Optional)

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

Example 1

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

The system will only notify events gatewayStatusChanged and tagBatteryLevelChanged

Example 2

Url: GET /api/event-stream?project=c0aa9fe7-046c-4608-b107-874b1f5533ca&listen=tagButtonEvent

The system will only notify event tagButtonEvent related to project c0aa9fe7-046c-4608-b107-874b1f5533ca

Response Events

  • event is the SSE event name.
  • data contains the generated event object. Refer to the Events documentation for specific event payload.
event: event
data: {
  "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 LocateBLE interface in section Logs -> System

Response Events

syslog object contains data of the generated log.

{
  "uid": `string`, 
  "ticks": `number`,
  "timestamp": `number`, 
  "malloc": `number`,
  "source": `string`, 
  "type": `number`, 
  "message": `string` 
}
Response parameters
Parameter Type Description
uid string Unique identifier generated by the system
ticks number Number of ticks (1 tick = 100 nanosecond) elapsed from 0000-01-01
timestamp number Unix timestamp (milliseconds)
malloc string Service emory allocation
source string Application component which generated the message
type number Log Type. See the table below
message string Log message
Log types
Type Description
1 Information
2 Warning
4 Error
8 Debug
16 Verbose