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:
GETHEADPOSTPUTDELETECONNECTOPTIONSTRACEPATCH
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/jsonis parsed and returned as a JSON value;text/plainis 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 OKwithupdated: false. - When the update changes the project, the project is stored and connected clients receive the
projectTagBaseSettingsUpdatednotification.
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.configurationis 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:
nonebasicbearer
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
eventis the SSE event name.datacontains 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 |