Canary Write

Technical Preview

Overview

Client-mode REST API connectors for the Canary Historian: browse nodes and tags, read last values, raw history and aggregates, poll live data, annotations and events through the Views Read API, and write MQTT values into Canary through the Store and Forward Write API session (getSessionToken, storeData, keepAlive). This is one of the templates in the Canary Historian REST API app (canary-historian). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

Auth

token: Identity API token as apiToken inside the JSON body (payload field body); sessionToken / liveDataToken / userToken for session, live data and Windows-account calls
windows: Read API GetUserToken over https with username/password of a Windows account mapped to a Canary user -> userToken (5 min idle expiry). Not available on the v24+ Write API.
secret: [“CANARY_API_TOKEN”]
unauthenticated: [“GetVersion”]
note: No Authorization header is sent; the Read API would also accept ‘Authorization: Bearer <apiToken>’ but the Write API documents only the body field, so both connectors use the body for consistency. Canary services typically use a self-signed certificate; the broker host must trust it.

Template parameters

Placeholder	Type	Description	Required
`RouteName`	string	Name of the Canary Write connector	no
`BaseUrl`	string	Canary Write base URL without trailing slash (e.g. https://YOUR_CANARY_HOST:55293)	yes

BASE_ADDRESS default: https://YOUR_CANARY_HOST:55293.

Events

Event	Method	Endpoint	Request topic	Response topic	Payload fields
`GetVersion`	POST	`/api/v1/version`	`historian/canary-write/version/get`	`historian/canary-write/version/get/response`	`body`
`GetDatasets`	POST	`/api/v1/getDatasets`	`historian/canary-write/dataset/list`	`historian/canary-write/dataset/list/response`	`body`
`GetSessionToken`	POST	`/api/v1/getSessionToken`	`historian/canary-write/session/create`	`historian/canary-write/session/create/response`	`body`
`UpdateSettings`	POST	`/api/v1/updateSettings`	`historian/canary-write/session/update`	`historian/canary-write/session/update/response`	`body`
`KeepAlive`	POST	`/api/v1/keepAlive`	`historian/canary-write/session/refresh`	`historian/canary-write/session/refresh/response`	`body`
`RevokeSessionToken`	POST	`/api/v1/revokeSessionToken`	`historian/canary-write/session/delete`	`historian/canary-write/session/delete/response`	`body`
`ConfigureTags`	POST	`/api/v1/configureTags`	`historian/canary-write/tag-config/update`	`historian/canary-write/tag-config/update/response`	`body`
`StoreData`	POST	`/api/v1/storeData`	`historian/canary-write/tag-data/store`	`historian/canary-write/tag-data/store/response`	`body`
`ManualEntryStoreData`	POST	`/api/v1/manualEntryStoreData`	`historian/canary-write/manual-entry/store`	`historian/canary-write/manual-entry/store/response`	`body`
`WriteNoData`	POST	`/api/v1/noData`	`historian/canary-write/no-data/create`	`historian/canary-write/no-data/create/response`	`body`

Deploy

Get the template card (JSON with template and metadata) from the broker, then deploy the connector:

mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode CANARY_WRITE"

The deployable connector from the REST API app, with BASE_ADDRESS already filled in:

DEFINE CONNECTOR CanaryWrite WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_CANARY_HOST:55293"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT GetVersion
        WITH SOURCE_TOPIC "historian/canary-write/version/get"
        WITH DESTINATION_TOPIC "historian/canary-write/version/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/version"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT GetDatasets
        WITH SOURCE_TOPIC "historian/canary-write/dataset/list"
        WITH DESTINATION_TOPIC "historian/canary-write/dataset/list/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/getDatasets"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT GetSessionToken
        WITH SOURCE_TOPIC "historian/canary-write/session/create"
        WITH DESTINATION_TOPIC "historian/canary-write/session/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/getSessionToken"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT UpdateSettings
        WITH SOURCE_TOPIC "historian/canary-write/session/update"
        WITH DESTINATION_TOPIC "historian/canary-write/session/update/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/updateSettings"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT KeepAlive
        WITH SOURCE_TOPIC "historian/canary-write/session/refresh"
        WITH DESTINATION_TOPIC "historian/canary-write/session/refresh/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/keepAlive"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT RevokeSessionToken
        WITH SOURCE_TOPIC "historian/canary-write/session/delete"
        WITH DESTINATION_TOPIC "historian/canary-write/session/delete/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/revokeSessionToken"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ConfigureTags
        WITH SOURCE_TOPIC "historian/canary-write/tag-config/update"
        WITH DESTINATION_TOPIC "historian/canary-write/tag-config/update/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/configureTags"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT StoreData
        WITH SOURCE_TOPIC "historian/canary-write/tag-data/store"
        WITH DESTINATION_TOPIC "historian/canary-write/tag-data/store/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/storeData"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ManualEntryStoreData
        WITH SOURCE_TOPIC "historian/canary-write/manual-entry/store"
        WITH DESTINATION_TOPIC "historian/canary-write/manual-entry/store/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/manualEntryStoreData"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT WriteNoData
        WITH SOURCE_TOPIC "historian/canary-write/no-data/create"
        WITH DESTINATION_TOPIC "historian/canary-write/no-data/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/noData"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"

Deploy it with -addConnector (do not include ADD METADATA).

Usage example

Call GetVersion by publishing a JSON payload to its request topic, and read the reply on the response topic:

mosquitto_sub -t 'historian/canary-write/version/get/response' &
mosquitto_pub -t 'historian/canary-write/version/get' -m '{"body": {}}'

Last modified on October 26, 2026

⌘I

Quick Start

Coreflux MQTT Broker

LoT Language

Coreflux HUB

VS Code - LoT Notebooks

Coreflux Portal

Using AI with Coreflux

Product Updates

Overview

Auth

Template parameters

Events

Deploy

Usage example

​Overview

​Auth

​Template parameters

​Events

​Deploy

​Usage example

​Related

Overview

Auth

Template parameters

Events

Deploy

Usage example

Related