> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreflux.org/llms.txt
> Use this file to discover all available pages before exploring further.

# N3uron

> Client-mode REST API connector for N3uron: read real-time tags and tag details, browse the data model, pull raw or aggregated Historian data, list, count and acknowledge alarms, check node health, and write one or many tag values through the REST API Server module

Technical Preview

## Overview

A client-mode connector for the [N3uron REST API Server](https://docs.n3uron.com/docs/rest-api-server-calls) module. Use it to mirror N3uron tags into your MQTT namespace, push setpoints from the broker back into N3uron, pull hourly energy or other aggregates from the N3uron Historian, and surface active alarms on an andon board or shift report.

| Event | Request | Notes |
| - | - | - |
| GetSystemStatus | `GET /system?cmd=status` | Node status: N3uron version, node name, tag counts, errors, host CPU / RAM / disk usage, uptime |
| GetErrorCount | `GET /system?cmd=errorCount` | `0` when healthy; cheap auth check |
| GetRedundancyStatus | `GET /redundancy?cmd=status` | Redundancy mode: enabled, standby, primary / backup |
| ListModuleInstances | `GET /module?cmd=getInstances` | Module instances running on the node (Historian, OpcUaClient, MqttClient, RestApiServer...) |
| GetModuleDetails | `GET /module?cmd=details` | Run state, uptime and memory of the instanced modules |
| ListLinks | `GET /link?cmd=get` | Links to other N3uron nodes (edge to central) and their status |
| BrowseTags | `GET /tag?cmd=browse&path={path}` | Groups and tags under a path (navigate the data model) |
| ReadTags | `GET /tag?cmd=read&path={path}` | Single tag: `{status, data}`; group (`/*`): `{tags: {...}}` |
| ReadTagsFiltered | `GET /tag?cmd=read&path={path}&options.filter={filter}&options.recurrent={recurrent}` | Current values under a group, regex-filtered on the tag path, optionally including subgroups |
| GetTagDetails | `GET /tag?cmd=details&path={path}` | Full tag details: value plus config (type, engineering units, client access, source, history, alarms) |
| GetTagViews | `GET /tag?cmd=getViews` | Tag views defined on the node |
| GetTagHistory | `GET /tag?cmd=history&path={path}&start={start}&end={end}&options.mode={mode}` | Rows `[ts, value, quality, status]`; needs Historian |
| GetTagHistoryAggregated | `GET /tag?cmd=history&path={path}&start={start}&end={end}&options.mode=aggregated&options.method={method}&options.interval={interval}` | `method`: first, last, min, max, avg, delta, stddev |
| GetHistoryMany | `GET /tag?cmd=historyMany&paths={paths}&start={start}&end={end}&options.mode={mode}` | History for several tags in one call (comma-separated paths); response keyed by tag path |
| GetHistoryFiltered | `GET /tag?cmd=historyFilter&path={path}&start={start}&end={end}&options.filter={filter}&options.recurrent={recurrent}&options.mode={mode}` | History for every tag under a group whose path matches a regex |
| ListAlarms | `GET /alarm?cmd=get&path={path}&options.recurrent={recurrent}` | Alarms under a path with priority, status (0 cleared+acked .. 3 active+unacked), value and ack info |
| ListActiveUnackedAlarms | `GET /alarm?cmd=get&path={path}&options.recurrent=true&options.filter.status=3&options.filter.minPriority={minPriority}` | `status=3`, `minPriority` 1 to 4 |
| CountAlarms | `GET /alarm?cmd=count&path={path}&options.recurrent={recurrent}` | Number of alarms under a path |
| GetAlarmHistory | `GET /alarm?cmd=history&path={path}&start={start}&end={end}` | Alarm events of one alarm between start and end |
| WriteTag | `POST /tag?cmd=write` | Body `{"path","value"}`; empty `200` |
| WriteManyTags | `POST /tag?cmd=writeMany` | Body `{"paths": "a,b", "values": [..]}` |
| AckAlarms | `POST /alarm?cmd=ack` | Body `{"paths", "msg"}` |

Set `BASE_ADDRESS` to the N3uron node that runs the RestApiServer module, for example `https://edge01.example.com:3443` (HTTPS, default port 3443). For a plain HTTP lab setup use `http://<host>:3003` and set `USE_SSL "false"`. The API lives at the server root, so there is no `/api` prefix. Topics use `historian/n3uron/<object>/<verb>`; replies land on `<topic>/response`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Auth:** in N3uron, open the RestApiServer module's **Access** settings. **Token authentication** issues an API key that you send as `Bearer <token>`; **Role authentication** accepts a N3uron user and password as HTTP Basic. Grant `GET` or `GET/POST` per API group (Tag, Alarm, System, Module, Link) and add a tag filter (Include, path `/`, regex `.*`, or narrower); the filter is mandatory. Publish the full header value as `authorization` in every payload, keep it in a Hub secret (suggested name `N3URON_AUTHORIZATION`), and never commit it into the `.lot`. A missing or wrong value returns `401`.

## Basic Syntax

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
DEFINE ROUTE N3uronApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_N3URON_HOST:3443"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # Smoke: GetErrorCount -> GetSystemStatus -> BrowseTags -> ReadTags -> WriteTag -> ReadTags. Never commit tokens or passwords.
    # Node status: N3uron version, node name, tag counts, errors, host CPU / RAM / disk usage, uptime
    ADD EVENT GetSystemStatus
        WITH SOURCE_TOPIC "historian/n3uron/system/status/get"
        WITH DESTINATION_TOPIC "historian/n3uron/system/status/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/system?cmd=status"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Number of configuration errors on the node (0 = healthy); cheap health and auth check
    ADD EVENT GetErrorCount
        WITH SOURCE_TOPIC "historian/n3uron/system/error-count/get"
        WITH DESTINATION_TOPIC "historian/n3uron/system/error-count/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/system?cmd=errorCount"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Redundancy mode: enabled, standby, primary / backup
    ADD EVENT GetRedundancyStatus
        WITH SOURCE_TOPIC "historian/n3uron/redundancy/status/get"
        WITH DESTINATION_TOPIC "historian/n3uron/redundancy/status/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/redundancy?cmd=status"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Module instances running on the node (Historian, OpcUaClient, MqttClient, RestApiServer...)
    ADD EVENT ListModuleInstances
        WITH SOURCE_TOPIC "historian/n3uron/modules/instances/get"
        WITH DESTINATION_TOPIC "historian/n3uron/modules/instances/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/module?cmd=getInstances"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Run state, uptime and memory of the instanced modules
    ADD EVENT GetModuleDetails
        WITH SOURCE_TOPIC "historian/n3uron/modules/details/get"
        WITH DESTINATION_TOPIC "historian/n3uron/modules/details/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/module?cmd=details"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Links to other N3uron nodes (edge to central) and their status
    ADD EVENT ListLinks
        WITH SOURCE_TOPIC "historian/n3uron/links/get"
        WITH DESTINATION_TOPIC "historian/n3uron/links/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/link?cmd=get"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Groups and tags under a path (navigate the data model)
    ADD EVENT BrowseTags
        WITH SOURCE_TOPIC "historian/n3uron/tags/browse"
        WITH DESTINATION_TOPIC "historian/n3uron/tags/browse/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/tag?cmd=browse&path={value.json.path}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Current value, quality and timestamp of one tag, or every tag in a group (path ends with /*)
    ADD EVENT ReadTags
        WITH SOURCE_TOPIC "historian/n3uron/tags/read"
        WITH DESTINATION_TOPIC "historian/n3uron/tags/read/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/tag?cmd=read&path={value.json.path}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Current values under a group, regex-filtered on the tag path, optionally including subgroups
    ADD EVENT ReadTagsFiltered
        WITH SOURCE_TOPIC "historian/n3uron/tags/read-filtered"
        WITH DESTINATION_TOPIC "historian/n3uron/tags/read-filtered/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/tag?cmd=read&path={value.json.path}&options.filter={value.json.filter}&options.recurrent={value.json.recurrent}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Full tag details: value plus config (type, engineering units, client access, source, history, alarms)
    ADD EVENT GetTagDetails
        WITH SOURCE_TOPIC "historian/n3uron/tags/details/get"
        WITH DESTINATION_TOPIC "historian/n3uron/tags/details/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/tag?cmd=details&path={value.json.path}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Tag views defined on the node
    ADD EVENT GetTagViews
        WITH SOURCE_TOPIC "historian/n3uron/tags/views/get"
        WITH DESTINATION_TOPIC "historian/n3uron/tags/views/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/tag?cmd=getViews"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Historian samples for one tag between start and end (ISO or epoch ms); mode raw, filter or delta; rows are [ts, value, quality, status]
    ADD EVENT GetTagHistory
        WITH SOURCE_TOPIC "historian/n3uron/tag-history/get"
        WITH DESTINATION_TOPIC "historian/n3uron/tag-history/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/tag?cmd=history&path={value.json.path}&start={value.json.start}&end={value.json.end}&options.mode={value.json.mode}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Aggregated history (first, last, min, max, avg, delta, stddev) per interval in ms; for example hourly energy
    ADD EVENT GetTagHistoryAggregated
        WITH SOURCE_TOPIC "historian/n3uron/tag-history/aggregated/get"
        WITH DESTINATION_TOPIC "historian/n3uron/tag-history/aggregated/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/tag?cmd=history&path={value.json.path}&start={value.json.start}&end={value.json.end}&options.mode=aggregated&options.method={value.json.method}&options.interval={value.json.interval}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # History for several tags in one call (comma-separated paths); response keyed by tag path
    ADD EVENT GetHistoryMany
        WITH SOURCE_TOPIC "historian/n3uron/tag-history/many/get"
        WITH DESTINATION_TOPIC "historian/n3uron/tag-history/many/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/tag?cmd=historyMany&paths={value.json.paths}&start={value.json.start}&end={value.json.end}&options.mode={value.json.mode}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # History for every tag under a group whose path matches a regex
    ADD EVENT GetHistoryFiltered
        WITH SOURCE_TOPIC "historian/n3uron/tag-history/filtered/get"
        WITH DESTINATION_TOPIC "historian/n3uron/tag-history/filtered/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/tag?cmd=historyFilter&path={value.json.path}&start={value.json.start}&end={value.json.end}&options.filter={value.json.filter}&options.recurrent={value.json.recurrent}&options.mode={value.json.mode}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Alarms under a path with priority, status (0 cleared+acked .. 3 active+unacked), value and ack info
    ADD EVENT ListAlarms
        WITH SOURCE_TOPIC "historian/n3uron/alarms/get"
        WITH DESTINATION_TOPIC "historian/n3uron/alarms/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/alarm?cmd=get&path={value.json.path}&options.recurrent={value.json.recurrent}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Active and unacknowledged alarms at or above a priority (1 low .. 4 critical), for andon or shift handover
    ADD EVENT ListActiveUnackedAlarms
        WITH SOURCE_TOPIC "historian/n3uron/alarms/active-unacked/get"
        WITH DESTINATION_TOPIC "historian/n3uron/alarms/active-unacked/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/alarm?cmd=get&path={value.json.path}&options.recurrent=true&options.filter.status=3&options.filter.minPriority={value.json.minPriority}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Number of alarms under a path
    ADD EVENT CountAlarms
        WITH SOURCE_TOPIC "historian/n3uron/alarms/count/get"
        WITH DESTINATION_TOPIC "historian/n3uron/alarms/count/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/alarm?cmd=count&path={value.json.path}&options.recurrent={value.json.recurrent}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Alarm events of one alarm between start and end
    ADD EVENT GetAlarmHistory
        WITH SOURCE_TOPIC "historian/n3uron/alarm-history/get"
        WITH DESTINATION_TOPIC "historian/n3uron/alarm-history/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/alarm?cmd=history&path={value.json.path}&start={value.json.start}&end={value.json.end}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # WRITE: Write one tag value (type must match the tag: number, boolean or string); empty 200 on success
    ADD EVENT WriteTag
        WITH SOURCE_TOPIC "historian/n3uron/tag/write"
        WITH DESTINATION_TOPIC "historian/n3uron/tag/write/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/tag?cmd=write"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.request}"
    # WRITE: Write several tags in one call (comma-separated paths, values array in the same order)
    ADD EVENT WriteManyTags
        WITH SOURCE_TOPIC "historian/n3uron/tags/write-many"
        WITH DESTINATION_TOPIC "historian/n3uron/tags/write-many/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/tag?cmd=writeMany"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.request}"
    # WRITE: Acknowledge one or more alarms (paths: single, comma-separated or JSON array) with an optional message
    ADD EVENT AckAlarms
        WITH SOURCE_TOPIC "historian/n3uron/alarms/ack"
        WITH DESTINATION_TOPIC "historian/n3uron/alarms/ack/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/alarm?cmd=ack"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.request}"
```

## Payloads

GET parameters go into the URL as they are, so URL-encode tag paths or filters that contain spaces or special characters. `start` and `end` take an ISO string or a Unix epoch timestamp in milliseconds. POST events send the payload field `request` unchanged as the JSON body; a successful write or acknowledgement returns an empty `200`, and errors return `400` with a plain-text reason such as `Tag not found: /X`.

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{"authorization": "Bearer <token>", "path": "/LINE1/PRESS01/*"}
```

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{"authorization": "Bearer <token>", "request": {"path": "/LINE1/PRESS01/SETPOINT", "value": 555}}
```

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{"authorization": "Bearer <token>", "path": "/LINE1/METER01/ACTIVE_ENERGY", "start": "2026-10-05T00:00:00.000Z", "end": "2026-10-06T00:00:00.000Z", "method": "delta", "interval": "3600000"}
```

## Example actions

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION N3uronHealthPoll
ON EVERY 5 MINUTES DO
    SET "auth" WITH GET SECRET "N3URON_AUTHORIZATION"
    PUBLISH TOPIC "historian/n3uron/system/error-count/get" WITH { "authorization": {auth} }

DEFINE ACTION N3uronReadPressTags
ON EVERY 10 SECONDS DO
    SET "auth" WITH GET SECRET "N3URON_AUTHORIZATION"
    PUBLISH TOPIC "historian/n3uron/tags/read" WITH { "authorization": {auth}, "path": "/LINE1/PRESS01/*" }

DEFINE ACTION N3uronSetpointFromUns
ON TOPIC "porto/line1/press01/setpoint/set" DO
    SET "auth" WITH GET SECRET "N3URON_AUTHORIZATION"
    SET "sp" WITH PAYLOAD AS DOUBLE
    PUBLISH TOPIC "historian/n3uron/tag/write" WITH { "authorization": {auth}, "request": { "path": "/LINE1/PRESS01/SETPOINT", "value": {sp} } }

DEFINE ACTION N3uronShiftAlarms
ON EVERY 1 HOUR DO
    SET "auth" WITH GET SECRET "N3URON_AUTHORIZATION"
    PUBLISH TOPIC "historian/n3uron/alarms/active-unacked/get" WITH { "authorization": {auth}, "path": "/LINE1/", "minPriority": "3" }
```

## Limits and notes

* History and alarm history need a Historian module and history enabled on the tag or alarm; otherwise N3uron answers `400` (`Historization disabled for the target tag`).
* Configuration, restart, backup, license, certificate and subscription calls are left out on purpose. Manage those from the N3uron WebUI.
* Writes must match the tag type (number, boolean or string) and the tag must allow client writes (`clientAccess` `RW`).

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps](/latest/lot-language/routes/rest-api-apps/index)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.