TALQ Documentation

This page contains all TALQ-related endpoints separate from the main V2 API documentation. It includes both the TALQ protocol endpoints and the TALQ CMS gateway registration endpoints.

For details on the V2 API, return to the main API documentation.

TALQ API

The TALQ API provides integration with the TALQ Smart City Protocol, an international standard for managing outdoor lighting and other smart city devices. TALQ defines a standardised interface between Central Management Software (CMS) and Outdoor Device Networks (ODN), enabling interoperable control of intelligent outdoor lighting infrastructure.

The Sustainder Brokerage Layer implements the TALQ protocol to communicate with TALQ-compliant gateways. Through these endpoints, you can manage devices, calendars, control programs, and issue commands to gateways that speak the TALQ protocol.

The base URL for the TALQ API is https://httpapi.sustainder.com/talq.

This API communicates in JSON.

Key Concepts

Concept	Description
Gateway	A TALQ-compliant gateway that manages a network of outdoor devices (e.g., luminaires).
Device	A physical device (e.g., a streetlight controller) registered through a TALQ gateway.
Device Class	A template that defines the functions and attributes available on a category of devices.
Calendar	A schedule that assigns control programs to specific time periods for device operation.
Control Program	A set of time-based instructions (e.g., dimming levels) that define how devices behave during a period.
Service	A TALQ service capability advertised by a gateway.
Logger Config	A configuration that defines which device attributes to log and how to report them.

Authentication

All TALQ API endpoints require JWT authentication. Include the token in the Authorization header:

Authorization: JWT {your_token}

See the Authentication section for details on obtaining a JWT token.

TALQ Services

TALQ services represent the capabilities advertised by TALQ gateways. Each service describes a functional capability that the gateway and its connected devices can provide (e.g., lighting control, metering, sensor data).

/talq/services [GET]

Request

curl "https://httpapi.sustainder.com/talq/services" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response (200 OK)

{
    "services": [
        {
            "serviceName": "LightingService",
            "version": "2.4.0",
            "description": "TALQ Lighting control service for outdoor luminaires",
            "serviceType": "lighting",
            "gateway_address": "urn:talq:gateway:550e8400-e29b-41d4-a716-446655440000",
            "supported_functions": [
                "dimmingLevel",
                "onOff",
                "colorTemperature"
            ]
        },
        {
            "serviceName": "MeteringService",
            "version": "2.4.0",
            "description": "Energy metering service for power consumption tracking",
            "serviceType": "metering",
            "gateway_address": "urn:talq:gateway:550e8400-e29b-41d4-a716-446655440000",
            "supported_functions": [
                "activePower",
                "activeEnergy",
                "voltage"
            ]
        }
    ]
}

Lists all TALQ services that have been announced by connected gateways. Each service describes a capability and the functions it supports.

Response Fields

Field	Type	Description
serviceName	string	Unique name identifier for the service.
version	string	TALQ protocol version supported by this service.
description	string	Human-readable description of the service.
serviceType	string	Category of the service (e.g., lighting, metering, sensor).
gateway_address	string	URN of the gateway that provides this service.
supported_functions	array	List of function names this service supports.

/talq/services/{serviceName} [GET]

Request

curl "https://httpapi.sustainder.com/talq/services/LightingService" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response (200 OK)

{
    "serviceName": "LightingService",
    "version": "2.4.0",
    "description": "TALQ Lighting control service for outdoor luminaires",
    "serviceType": "lighting",
    "gateway_address": "urn:talq:gateway:550e8400-e29b-41d4-a716-446655440000",
    "supported_functions": [
        "dimmingLevel",
        "onOff",
        "colorTemperature"
    ],
    "configuration": {
        "max_devices": 1000,
        "supports_multicast": true,
        "supports_logging": true
    }
}

Returns detailed information about a specific TALQ service.

Path Parameters

Parameter	Type	Description
serviceName	string	The unique name of the TALQ service (e.g., LightingService).

Response Fields

Same fields as the service list response, plus:

Field	Type	Description
configuration	object	Service-specific configuration details.
configuration.max_devices	integer	Maximum number of devices this service can manage.
configuration.supports_multicast	boolean	Whether the service supports multicast commands.
configuration.supports_logging	boolean	Whether the service supports data logging.

Error Responses

Status	Description
404	Service not found.

TALQ Devices

TALQ devices represent physical equipment (e.g., luminaire controllers, sensors, meters) that are managed through TALQ gateways. Each device has a unique address, belongs to a device class, and exposes one or more functions with configurable attributes.

/talq/devices [GET]

Request

curl "https://httpapi.sustainder.com/talq/devices?offset=0&limit=50" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response (200 OK)

{
    "devices": [
        {
            "address": "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "deviceClass": "LuminaireController",
            "gateway_address": "urn:talq:gateway:550e8400-e29b-41d4-a716-446655440000",
            "status": "operational",
            "description": "Streetlight controller - Keizersgracht 42",
            "functions": [
                {
                    "functionId": "dimmingLevel",
                    "currentValue": 75,
                    "unit": "percent"
                },
                {
                    "functionId": "onOff",
                    "currentValue": true,
                    "unit": "boolean"
                }
            ],
            "last_communication": "2024-11-15T14:32:08Z"
        },
        {
            "address": "urn:talq:device:b2c3d4e5-f6a7-8901-bcde-f12345678901",
            "deviceClass": "LuminaireController",
            "gateway_address": "urn:talq:gateway:550e8400-e29b-41d4-a716-446655440000",
            "status": "operational",
            "description": "Streetlight controller - Herengracht 108",
            "functions": [
                {
                    "functionId": "dimmingLevel",
                    "currentValue": 100,
                    "unit": "percent"
                },
                {
                    "functionId": "onOff",
                    "currentValue": true,
                    "unit": "boolean"
                }
            ],
            "last_communication": "2024-11-15T14:30:45Z"
        }
    ],
    "total": 256,
    "offset": 0,
    "limit": 50
}

Lists all TALQ devices registered through connected gateways. Supports pagination via offset and limit query parameters.

Query Parameters

Parameter	Type	Default	Description
offset	integer	0	Number of records to skip before returning results.
limit	integer	50	Maximum number of devices to return per request.

Response Fields

Field	Type	Description
address	string	Unique TALQ URN address of the device.
deviceClass	string	Name of the device class this device belongs to.
gateway_address	string	URN of the gateway managing this device.
status	string	Device status: operational, degraded, not_operational, or unknown.
description	string	Human-readable description of the device.
functions	array	List of functions exposed by this device.
functions[].functionId	string	Unique identifier for the function.
functions[].currentValue	mixed	Current value of the function.
functions[].unit	string	Unit of measurement for the value.
last_communication	string	ISO 8601 timestamp of the last communication with the device.
total	integer	Total number of devices available.
offset	integer	Current offset in the result set.
limit	integer	Current page size limit.

/talq/devices/count [GET]

Request

curl "https://httpapi.sustainder.com/talq/devices/count" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response (200 OK)

{
    "count": 256
}

Returns the total number of TALQ devices registered in the system.

Response Fields

Field	Type	Description
count	integer	Total number of TALQ devices.

/talq/devices/{deviceAddress} [GET]

Request

curl "https://httpapi.sustainder.com/talq/devices/urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response (200 OK)

{
    "address": "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "deviceClass": "LuminaireController",
    "gateway_address": "urn:talq:gateway:550e8400-e29b-41d4-a716-446655440000",
    "status": "operational",
    "description": "Streetlight controller - Keizersgracht 42",
    "functions": [
        {
            "functionId": "dimmingLevel",
            "currentValue": 75,
            "unit": "percent",
            "writable": true,
            "minValue": 0,
            "maxValue": 100
        },
        {
            "functionId": "onOff",
            "currentValue": true,
            "unit": "boolean",
            "writable": true
        },
        {
            "functionId": "activePower",
            "currentValue": 42.5,
            "unit": "watt",
            "writable": false
        },
        {
            "functionId": "operatingHours",
            "currentValue": 18240,
            "unit": "hours",
            "writable": false
        }
    ],
    "calendar_address": "urn:talq:calendar:c3d4e5f6-a7b8-9012-cdef-123456789012",
    "last_communication": "2024-11-15T14:32:08Z",
    "firmware_version": "3.2.1"
}

Returns detailed information for a specific TALQ device, including all functions and their current values.

Path Parameters

Parameter	Type	Description
deviceAddress	string	The TALQ URN address of the device.

Response Fields

Same fields as the device list response, plus:

Field	Type	Description
functions[].writable	boolean	Whether this function can be written to (controlled).
functions[].minValue	number	Minimum allowed value (for numeric writable functions).
functions[].maxValue	number	Maximum allowed value (for numeric writable functions).
calendar_address	string	URN of the calendar currently assigned to this device.
firmware_version	string	Current firmware version of the device.

Error Responses

Status	Description
404	Device not found.

/talq/devices/{deviceAddress}/{functionId} [GET]

Request

curl "https://httpapi.sustainder.com/talq/devices/urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890/dimmingLevel" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response (200 OK)

{
    "functionId": "dimmingLevel",
    "currentValue": 75,
    "unit": "percent",
    "writable": true,
    "minValue": 0,
    "maxValue": 100,
    "attributes": [
        {
            "attributeName": "targetLevel",
            "value": 75,
            "type": "integer",
            "writable": true
        },
        {
            "attributeName": "fadeTime",
            "value": 2000,
            "type": "integer",
            "writable": true,
            "unit": "milliseconds"
        },
        {
            "attributeName": "actualLevel",
            "value": 74,
            "type": "integer",
            "writable": false
        }
    ],
    "last_updated": "2024-11-15T14:32:08Z"
}

Returns the details of a specific function on a TALQ device, including all attributes of that function.

Path Parameters

Parameter	Type	Description
deviceAddress	string	The TALQ URN address of the device.
functionId	string	The function identifier (e.g., dimmingLevel, onOff, activePower).

Response Fields

Field	Type	Description
functionId	string	The function identifier.
currentValue	mixed	Current value of the function.
unit	string	Unit of measurement.
writable	boolean	Whether this function can be written to.
minValue	number	Minimum allowed value.
maxValue	number	Maximum allowed value.
attributes	array	List of individual attributes within this function.
attributes[].attributeName	string	Name of the attribute.
attributes[].value	mixed	Current value of the attribute.
attributes[].type	string	Data type: integer, float, boolean, string.
attributes[].writable	boolean	Whether this attribute is writable.
attributes[].unit	string	Unit of measurement (if applicable).
last_updated	string	ISO 8601 timestamp of the last value update.

Error Responses

Status	Description
404	Device or function not found.

/talq/devices/{deviceAddress}/{functionId}/{attributeName} [GET]

Request

curl "https://httpapi.sustainder.com/talq/devices/urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890/dimmingLevel/targetLevel" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response (200 OK)

{
    "attributeName": "targetLevel",
    "value": 75,
    "type": "integer",
    "writable": true,
    "unit": "percent",
    "minValue": 0,
    "maxValue": 100,
    "last_updated": "2024-11-15T14:32:08Z"
}

Returns the value and metadata of a specific attribute within a device function.

Path Parameters

Parameter	Type	Description
deviceAddress	string	The TALQ URN address of the device.
functionId	string	The function identifier (e.g., dimmingLevel).
attributeName	string	The attribute name (e.g., targetLevel, fadeTime).

Response Fields

Field	Type	Description
attributeName	string	Name of the attribute.
value	mixed	Current value of the attribute.
type	string	Data type: integer, float, boolean, string.
writable	boolean	Whether this attribute can be modified.
unit	string	Unit of measurement (if applicable).
minValue	number	Minimum allowed value (for numeric attributes).
maxValue	number	Maximum allowed value (for numeric attributes).
last_updated	string	ISO 8601 timestamp of the last value update.

Error Responses

Status	Description
404	Device, function, or attribute not found.

TALQ Device Classes

Device classes define templates for categories of TALQ devices. A device class specifies which functions and attributes are available on devices of that type. For example, a LuminaireController device class defines functions like dimmingLevel and onOff, while a PowerMeter class defines functions like activePower and activeEnergy.

/talq/device-classes [GET]

Request

curl "https://httpapi.sustainder.com/talq/device-classes" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response (200 OK)

{
    "device_classes": [
        {
            "className": "LuminaireController",
            "description": "TALQ luminaire controller with dimming and on/off capability",
            "version": "2.4.0",
            "functions": [
                {
                    "functionId": "dimmingLevel",
                    "description": "Controls the dimming level of the luminaire",
                    "type": "numeric",
                    "writable": true
                },
                {
                    "functionId": "onOff",
                    "description": "On/Off control for the luminaire",
                    "type": "boolean",
                    "writable": true
                },
                {
                    "functionId": "activePower",
                    "description": "Current active power consumption",
                    "type": "numeric",
                    "writable": false
                }
            ]
        },
        {
            "className": "PowerMeter",
            "description": "Energy metering device for power consumption monitoring",
            "version": "2.4.0",
            "functions": [
                {
                    "functionId": "activePower",
                    "description": "Current active power consumption in watts",
                    "type": "numeric",
                    "writable": false
                },
                {
                    "functionId": "activeEnergy",
                    "description": "Cumulative active energy in kilowatt-hours",
                    "type": "numeric",
                    "writable": false
                },
                {
                    "functionId": "voltage",
                    "description": "Current supply voltage",
                    "type": "numeric",
                    "writable": false
                }
            ]
        }
    ],
    "total": 2
}

Lists all TALQ device classes that have been registered by connected gateways.

Response Fields

Field	Type	Description
className	string	Unique name of the device class.
description	string	Human-readable description of the device class.
version	string	TALQ protocol version of this device class definition.
functions	array	List of functions available on devices of this class.
functions[].functionId	string	Unique identifier for the function.
functions[].description	string	Description of the function.
functions[].type	string	Data type: numeric, boolean, string, enum.
functions[].writable	boolean	Whether the function can be controlled (written to).
total	integer	Total number of device classes.

/talq/device-classes/count [GET]

Request

curl "https://httpapi.sustainder.com/talq/device-classes/count" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response (200 OK)

{
    "count": 2
}

Returns the total number of TALQ device classes registered in the system.

Response Fields

Field	Type	Description
count	integer	Total number of device classes.

/talq/device-classes/{className} [GET]

Request

curl "https://httpapi.sustainder.com/talq/device-classes/LuminaireController" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response (200 OK)

{
    "className": "LuminaireController",
    "description": "TALQ luminaire controller with dimming and on/off capability",
    "version": "2.4.0",
    "functions": [
        {
            "functionId": "dimmingLevel",
            "description": "Controls the dimming level of the luminaire",
            "type": "numeric",
            "writable": true,
            "attributes": [
                {
                    "attributeName": "targetLevel",
                    "type": "integer",
                    "unit": "percent",
                    "minValue": 0,
                    "maxValue": 100,
                    "writable": true
                },
                {
                    "attributeName": "fadeTime",
                    "type": "integer",
                    "unit": "milliseconds",
                    "minValue": 0,
                    "maxValue": 60000,
                    "writable": true
                },
                {
                    "attributeName": "actualLevel",
                    "type": "integer",
                    "unit": "percent",
                    "writable": false
                }
            ]
        },
        {
            "functionId": "onOff",
            "description": "On/Off control for the luminaire",
            "type": "boolean",
            "writable": true,
            "attributes": [
                {
                    "attributeName": "state",
                    "type": "boolean",
                    "writable": true
                }
            ]
        },
        {
            "functionId": "activePower",
            "description": "Current active power consumption",
            "type": "numeric",
            "writable": false,
            "attributes": [
                {
                    "attributeName": "value",
                    "type": "float",
                    "unit": "watt",
                    "writable": false
                }
            ]
        }
    ]
}

Returns full details for a specific device class, including all functions and their attribute definitions.

Path Parameters

Parameter	Type	Description
className	string	The unique name of the device class (e.g., LuminaireController).

Response Fields

Same fields as the device class list response, with additional attribute details per function:

Field	Type	Description
functions[].attributes	array	Detailed attribute definitions for this function.
functions[].attributes[].attributeName	string	Name of the attribute.
functions[].attributes[].type	string	Data type: integer, float, boolean, string.
functions[].attributes[].unit	string	Unit of measurement (if applicable).
functions[].attributes[].minValue	number	Minimum allowed value (for numeric attributes).
functions[].attributes[].maxValue	number	Maximum allowed value (for numeric attributes).
functions[].attributes[].writable	boolean	Whether this attribute can be modified.

Error Responses

Status	Description
404	Device class not found.

TALQ Calendars

Calendars in TALQ define schedules that assign control programs to specific time periods. A calendar is the primary mechanism for automating device behaviour -- it tells devices which control program to follow at any given time. Each calendar has a default program and a set of rules that override the default for specific date ranges.

Calendars are assigned to devices using the Assign Commands endpoint.

/talq/calendars [GET]

Request

curl "https://httpapi.sustainder.com/talq/calendars?offset=0&limit=50" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response (200 OK)

{
    "calendars": [
        {
            "address": "urn:talq:calendar:c3d4e5f6-a7b8-9012-cdef-123456789012",
            "owner_cms": true,
            "default_program": "urn:talq:program:d4e5f6a7-b890-1234-cdef-234567890123",
            "rules": [
                {
                    "start_date": "2024-12-01",
                    "end_date": "2025-02-28",
                    "control_program": "urn:talq:program:e5f6a7b8-9012-3456-cdef-345678901234",
                    "description": "Winter extended lighting"
                }
            ],
            "description": "Standard residential street calendar"
        },
        {
            "address": "urn:talq:calendar:f6a7b8c9-0123-4567-cdef-456789012345",
            "owner_cms": true,
            "default_program": "urn:talq:program:a7b8c9d0-1234-5678-cdef-567890123456",
            "rules": [],
            "description": "Highway calendar - constant brightness"
        }
    ],
    "total": 2,
    "offset": 0,
    "limit": 50
}

Lists all TALQ calendars configured in the system. Supports pagination via offset and limit query parameters.

Query Parameters

Parameter	Type	Default	Description
offset	integer	0	Number of records to skip before returning results.
limit	integer	50	Maximum number of calendars to return per request.

Response Fields

Field	Type	Description
address	string	Unique TALQ URN address of the calendar.
owner_cms	boolean	Whether the CMS (Sustainder) owns this calendar.
default_program	string	URN address of the default control program.
rules	array	List of rules that override the default program for specific date ranges.
rules[].start_date	string	Start date of the rule (YYYY-MM-DD).
rules[].end_date	string	End date of the rule (YYYY-MM-DD).
rules[].control_program	string	URN address of the control program for this rule.
rules[].description	string	Human-readable description of the rule.
description	string	Human-readable description of the calendar.
total	integer	Total number of calendars available.

/talq/calendars/count [GET]

Request

curl "https://httpapi.sustainder.com/talq/calendars/count" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response (200 OK)

{
    "count": 2
}

Returns the total number of TALQ calendars configured in the system.

Response Fields

Field	Type	Description
count	integer	Total number of calendars.

/talq/calendars/{calendarAddress} [GET]

Request

curl "https://httpapi.sustainder.com/talq/calendars/urn:talq:calendar:c3d4e5f6-a7b8-9012-cdef-123456789012" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response (200 OK)

{
    "address": "urn:talq:calendar:c3d4e5f6-a7b8-9012-cdef-123456789012",
    "owner_cms": true,
    "default_program": "urn:talq:program:d4e5f6a7-b890-1234-cdef-234567890123",
    "rules": [
        {
            "start_date": "2024-12-01",
            "end_date": "2025-02-28",
            "control_program": "urn:talq:program:e5f6a7b8-9012-3456-cdef-345678901234",
            "description": "Winter extended lighting"
        }
    ],
    "description": "Standard residential street calendar",
    "assigned_devices": [
        "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "urn:talq:device:b2c3d4e5-f6a7-8901-bcde-f12345678901"
    ]
}

Returns detailed information for a specific calendar, including the list of devices it is assigned to.

Path Parameters

Parameter	Type	Description
calendarAddress	string	The TALQ URN address of the calendar.

Response Fields

Same fields as the calendar list response, plus:

Field	Type	Description
assigned_devices	array	List of device URN addresses this calendar is currently assigned to.

Error Responses

Status	Description
404	Calendar not found.

/talq/calendars [POST]

Request

curl -X POST "https://httpapi.sustainder.com/talq/calendars" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "id": "urn:talq:calendar:new-calendar-001",
    "owner_cms": true,
    "default_program": "urn:talq:program:d4e5f6a7-b890-1234-cdef-234567890123",
    "rules": [
        {
            "start_date": "2025-06-01",
            "end_date": "2025-08-31",
            "control_program": "urn:talq:program:a7b8c9d0-1234-5678-cdef-567890123456",
            "description": "Summer energy saving mode"
        }
    ],
    "description": "Park pathway calendar"
  }'

Request body

{
    "id": "urn:talq:calendar:new-calendar-001",
    "owner_cms": true,
    "default_program": "urn:talq:program:d4e5f6a7-b890-1234-cdef-234567890123",
    "rules": [
        {
            "start_date": "2025-06-01",
            "end_date": "2025-08-31",
            "control_program": "urn:talq:program:a7b8c9d0-1234-5678-cdef-567890123456",
            "description": "Summer energy saving mode"
        }
    ],
    "description": "Park pathway calendar"
}

Response (201 Created)

{
    "address": "urn:talq:calendar:new-calendar-001",
    "owner_cms": true,
    "default_program": "urn:talq:program:d4e5f6a7-b890-1234-cdef-234567890123",
    "rules": [
        {
            "start_date": "2025-06-01",
            "end_date": "2025-08-31",
            "control_program": "urn:talq:program:a7b8c9d0-1234-5678-cdef-567890123456",
            "description": "Summer energy saving mode"
        }
    ],
    "description": "Park pathway calendar"
}

Creates a new TALQ calendar. The calendar defines a default control program and optional rules that override the default for specific date ranges.

Request Parameters

Parameter	Type	Required	Description
id	string	Yes	Unique URN identifier for the new calendar.
owner_cms	boolean	No	Whether the CMS owns this calendar. Defaults to true.
default_program	string	Yes	URN address of the default control program to use.
rules	array	No	List of rules that override the default program. Defaults to empty array.
rules[].start_date	string	Yes	Start date of the rule (YYYY-MM-DD).
rules[].end_date	string	Yes	End date of the rule (YYYY-MM-DD).
rules[].control_program	string	Yes	URN address of the control program for this rule.
rules[].description	string	No	Human-readable description of the rule.
description	string	No	Human-readable description of the calendar.

Error Responses

Status	Description
400	Validation error (e.g., missing required fields, invalid control program reference).
409	Calendar with the specified ID already exists.

/talq/calendars/{calendarAddress} [PATCH]

Request

curl -X PATCH "https://httpapi.sustainder.com/talq/calendars/urn:talq:calendar:c3d4e5f6-a7b8-9012-cdef-123456789012" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "default_program": "urn:talq:program:a7b8c9d0-1234-5678-cdef-567890123456",
    "rules": [
        {
            "start_date": "2025-01-01",
            "end_date": "2025-03-31",
            "control_program": "urn:talq:program:e5f6a7b8-9012-3456-cdef-345678901234",
            "description": "Q1 winter schedule"
        },
        {
            "start_date": "2025-06-01",
            "end_date": "2025-08-31",
            "control_program": "urn:talq:program:d4e5f6a7-b890-1234-cdef-234567890123",
            "description": "Summer schedule"
        }
    ]
  }'

Request body

{
    "default_program": "urn:talq:program:a7b8c9d0-1234-5678-cdef-567890123456",
    "rules": [
        {
            "start_date": "2025-01-01",
            "end_date": "2025-03-31",
            "control_program": "urn:talq:program:e5f6a7b8-9012-3456-cdef-345678901234",
            "description": "Q1 winter schedule"
        },
        {
            "start_date": "2025-06-01",
            "end_date": "2025-08-31",
            "control_program": "urn:talq:program:d4e5f6a7-b890-1234-cdef-234567890123",
            "description": "Summer schedule"
        }
    ]
}

Response (200 OK)

{
    "address": "urn:talq:calendar:c3d4e5f6-a7b8-9012-cdef-123456789012",
    "owner_cms": true,
    "default_program": "urn:talq:program:a7b8c9d0-1234-5678-cdef-567890123456",
    "rules": [
        {
            "start_date": "2025-01-01",
            "end_date": "2025-03-31",
            "control_program": "urn:talq:program:e5f6a7b8-9012-3456-cdef-345678901234",
            "description": "Q1 winter schedule"
        },
        {
            "start_date": "2025-06-01",
            "end_date": "2025-08-31",
            "control_program": "urn:talq:program:d4e5f6a7-b890-1234-cdef-234567890123",
            "description": "Summer schedule"
        }
    ],
    "description": "Standard residential street calendar"
}

Updates an existing TALQ calendar. Only the fields provided in the request body are updated; omitted fields remain unchanged.

Path Parameters

Parameter	Type	Description
calendarAddress	string	The TALQ URN address of the calendar to update.

Request Parameters

Parameter	Type	Required	Description
default_program	string	No	New default control program URN.
rules	array	No	Replacement list of rules. This replaces all existing rules.
description	string	No	Updated description.

Error Responses

Status	Description
400	Validation error (e.g., invalid control program reference).
404	Calendar not found.

/talq/calendars/{calendarAddress} [DELETE]

Request

curl -X DELETE "https://httpapi.sustainder.com/talq/calendars/urn:talq:calendar:c3d4e5f6-a7b8-9012-cdef-123456789012" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response (204 No Content)

204 No Content

Deletes a TALQ calendar. The calendar must not be currently assigned to any devices.

Path Parameters

Parameter	Type	Description
calendarAddress	string	The TALQ URN address of the calendar to delete.

Error Responses

Status	Description
404	Calendar not found.
409	Calendar is still assigned to one or more devices. Unassign the calendar first.

TALQ Control Programs

Control programs define the operational behaviour for TALQ devices during a specific time period. A control program consists of active periods (when the program is in effect) and fixed time controls (specific dimming levels at specific times). Control programs are assigned to devices through calendars.

/talq/control-programs [GET]

Request

curl "https://httpapi.sustainder.com/talq/control-programs" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response (200 OK)

{
    "control_programs": [
        {
            "address": "urn:talq:program:d4e5f6a7-b890-1234-cdef-234567890123",
            "description": "Standard evening dimming profile",
            "activePeriods": [
                {
                    "start": "sunset",
                    "startOffset": -15,
                    "end": "sunrise",
                    "endOffset": 10
                }
            ],
            "fixedTimeControls": [
                {
                    "time": "sunset",
                    "offset": -15,
                    "dimmingLevel": 100
                },
                {
                    "time": "22:00",
                    "offset": 0,
                    "dimmingLevel": 75
                },
                {
                    "time": "00:00",
                    "offset": 0,
                    "dimmingLevel": 50
                },
                {
                    "time": "05:30",
                    "offset": 0,
                    "dimmingLevel": 100
                },
                {
                    "time": "sunrise",
                    "offset": 10,
                    "dimmingLevel": 0
                }
            ]
        },
        {
            "address": "urn:talq:program:e5f6a7b8-9012-3456-cdef-345678901234",
            "description": "Winter extended lighting - high brightness",
            "activePeriods": [
                {
                    "start": "sunset",
                    "startOffset": -30,
                    "end": "sunrise",
                    "endOffset": 20
                }
            ],
            "fixedTimeControls": [
                {
                    "time": "sunset",
                    "offset": -30,
                    "dimmingLevel": 100
                },
                {
                    "time": "23:00",
                    "offset": 0,
                    "dimmingLevel": 80
                },
                {
                    "time": "05:00",
                    "offset": 0,
                    "dimmingLevel": 100
                },
                {
                    "time": "sunrise",
                    "offset": 20,
                    "dimmingLevel": 0
                }
            ]
        }
    ],
    "total": 2
}

Lists all TALQ control programs configured in the system.

Response Fields

Field	Type	Description
address	string	Unique TALQ URN address of the control program.
description	string	Human-readable description of the program.
activePeriods	array	Time periods when this control program is active.
activePeriods[].start	string	Start trigger: sunset, sunrise, or a fixed time (HH:MM).
activePeriods[].startOffset	integer	Offset in minutes from the start trigger (negative = before).
activePeriods[].end	string	End trigger: sunset, sunrise, or a fixed time (HH:MM).
activePeriods[].endOffset	integer	Offset in minutes from the end trigger.
fixedTimeControls	array	Ordered list of dimming level changes during the active period.
fixedTimeControls[].time	string	Time trigger: sunset, sunrise, or a fixed time (HH:MM).
fixedTimeControls[].offset	integer	Offset in minutes from the time trigger.
fixedTimeControls[].dimmingLevel	integer	Target dimming level (0-100 percent).
total	integer	Total number of control programs.

/talq/control-programs/count [GET]

Request

curl "https://httpapi.sustainder.com/talq/control-programs/count" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response (200 OK)

{
    "count": 2
}

Returns the total number of TALQ control programs configured in the system.

Response Fields

Field	Type	Description
count	integer	Total number of control programs.

/talq/control-programs/{controlProgramAddress} [GET]

Request

curl "https://httpapi.sustainder.com/talq/control-programs/urn:talq:program:d4e5f6a7-b890-1234-cdef-234567890123" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response (200 OK)

{
    "address": "urn:talq:program:d4e5f6a7-b890-1234-cdef-234567890123",
    "description": "Standard evening dimming profile",
    "activePeriods": [
        {
            "start": "sunset",
            "startOffset": -15,
            "end": "sunrise",
            "endOffset": 10
        }
    ],
    "fixedTimeControls": [
        {
            "time": "sunset",
            "offset": -15,
            "dimmingLevel": 100
        },
        {
            "time": "22:00",
            "offset": 0,
            "dimmingLevel": 75
        },
        {
            "time": "00:00",
            "offset": 0,
            "dimmingLevel": 50
        },
        {
            "time": "05:30",
            "offset": 0,
            "dimmingLevel": 100
        },
        {
            "time": "sunrise",
            "offset": 10,
            "dimmingLevel": 0
        }
    ],
    "referenced_by_calendars": [
        "urn:talq:calendar:c3d4e5f6-a7b8-9012-cdef-123456789012"
    ]
}

Returns detailed information for a specific control program, including which calendars reference it.

Path Parameters

Parameter	Type	Description
controlProgramAddress	string	The TALQ URN address of the control program.

Response Fields

Same fields as the control program list response, plus:

Field	Type	Description
referenced_by_calendars	array	List of calendar URN addresses that reference this control program.

Error Responses

Status	Description
404	Control program not found.

/talq/control-programs [POST]

Request

curl -X POST "https://httpapi.sustainder.com/talq/control-programs" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Festival mode - full brightness all night",
    "activePeriods": [
        {
            "start": "sunset",
            "startOffset": -30,
            "end": "sunrise",
            "endOffset": 15
        }
    ],
    "fixedTimeControls": [
        {
            "time": "sunset",
            "offset": -30,
            "dimmingLevel": 100
        },
        {
            "time": "sunrise",
            "offset": 15,
            "dimmingLevel": 0
        }
    ]
  }'

Request body

{
    "description": "Festival mode - full brightness all night",
    "activePeriods": [
        {
            "start": "sunset",
            "startOffset": -30,
            "end": "sunrise",
            "endOffset": 15
        }
    ],
    "fixedTimeControls": [
        {
            "time": "sunset",
            "offset": -30,
            "dimmingLevel": 100
        },
        {
            "time": "sunrise",
            "offset": 15,
            "dimmingLevel": 0
        }
    ]
}

Response (201 Created)

{
    "address": "urn:talq:program:f6a7b8c9-0123-4567-cdef-456789012345",
    "description": "Festival mode - full brightness all night",
    "activePeriods": [
        {
            "start": "sunset",
            "startOffset": -30,
            "end": "sunrise",
            "endOffset": 15
        }
    ],
    "fixedTimeControls": [
        {
            "time": "sunset",
            "offset": -30,
            "dimmingLevel": 100
        },
        {
            "time": "sunrise",
            "offset": 15,
            "dimmingLevel": 0
        }
    ]
}

Creates a new TALQ control program. The program can then be referenced by calendars to define device behaviour.

Request Parameters

Parameter	Type	Required	Description
description	string	No	Human-readable description of the control program.
activePeriods	array	Yes	At least one active period defining when the program is in effect.
activePeriods[].start	string	Yes	Start trigger: sunset, sunrise, or fixed time (HH:MM).
activePeriods[].startOffset	integer	No	Offset in minutes from start trigger. Defaults to 0.
activePeriods[].end	string	Yes	End trigger: sunset, sunrise, or fixed time (HH:MM).
activePeriods[].endOffset	integer	No	Offset in minutes from end trigger. Defaults to 0.
fixedTimeControls	array	Yes	At least one time-based dimming control step.
fixedTimeControls[].time	string	Yes	Time trigger: sunset, sunrise, or fixed time (HH:MM).
fixedTimeControls[].offset	integer	No	Offset in minutes from the time trigger. Defaults to 0.
fixedTimeControls[].dimmingLevel	integer	Yes	Target dimming level (0-100).

Error Responses

Status	Description
400	Validation error (e.g., missing required fields, dimming level out of range, no active periods).

TALQ Commands

TALQ commands allow you to send operational instructions to devices through their gateways. There are two types of commands:

• Assign commands assign calendars or other resources to devices, defining their long-term scheduling behaviour.
• Override commands send temporary overrides to devices, taking immediate effect and expiring after a specified duration.

/talq/assign-commands [POST]

Request - Assign a calendar to devices

curl -X POST "https://httpapi.sustainder.com/talq/assign-commands" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "entity": "calendars",
    "addresses": [
        {
            "device_address": "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "resource_address": "urn:talq:calendar:c3d4e5f6-a7b8-9012-cdef-123456789012"
        },
        {
            "device_address": "urn:talq:device:b2c3d4e5-f6a7-8901-bcde-f12345678901",
            "resource_address": "urn:talq:calendar:c3d4e5f6-a7b8-9012-cdef-123456789012"
        }
    ]
  }'

Request body

{
    "entity": "calendars",
    "addresses": [
        {
            "device_address": "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "resource_address": "urn:talq:calendar:c3d4e5f6-a7b8-9012-cdef-123456789012"
        },
        {
            "device_address": "urn:talq:device:b2c3d4e5-f6a7-8901-bcde-f12345678901",
            "resource_address": "urn:talq:calendar:c3d4e5f6-a7b8-9012-cdef-123456789012"
        }
    ]
}

Response (200 OK)

{
    "status": "accepted",
    "assigned": 2,
    "results": [
        {
            "device_address": "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "status": "success"
        },
        {
            "device_address": "urn:talq:device:b2c3d4e5-f6a7-8901-bcde-f12345678901",
            "status": "success"
        }
    ]
}

Assigns calendars or other resources to one or more TALQ devices. This is the primary mechanism for setting up long-term scheduling behaviour on devices.

Request Parameters

Parameter	Type	Required	Description
entity	string	No	Type of resource to assign. Defaults to calendars.
addresses	array	Yes	List of device-to-resource assignments. Must contain at least one entry.
addresses[].device_address	string	Yes	TALQ URN address of the target device.
addresses[].resource_address	string	Yes	TALQ URN address of the resource (e.g., calendar) to assign.

Response Fields

Field	Type	Description
status	string	Overall command status: accepted or rejected.
assigned	integer	Number of devices successfully assigned.
results	array	Per-device assignment results.
results[].device_address	string	The device that was targeted.
results[].status	string	Result for this device: success or failed.

Error Responses

Status	Description
400	Validation error (e.g., empty addresses array, invalid resource references).
404	One or more device or resource addresses not found.

/talq/override-commands [POST]

Request - Override devices to 50% dimming

curl -X POST "https://httpapi.sustainder.com/talq/override-commands" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": [
        "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "urn:talq:device:b2c3d4e5-f6a7-8901-bcde-f12345678901"
    ],
    "target_command": {
        "dimmingLevel": 50,
        "expiration_minutes": 120
    }
  }'

Request body

{
    "addresses": [
        "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "urn:talq:device:b2c3d4e5-f6a7-8901-bcde-f12345678901"
    ],
    "target_command": {
        "dimmingLevel": 50,
        "expiration_minutes": 120
    }
}

Response (200 OK)

{
    "status": "accepted",
    "overridden": 2,
    "expiration": "2024-11-15T16:32:08Z",
    "results": [
        {
            "device_address": "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "status": "success"
        },
        {
            "device_address": "urn:talq:device:b2c3d4e5-f6a7-8901-bcde-f12345678901",
            "status": "success"
        }
    ]
}

Request - Clear overrides on devices

curl -X POST "https://httpapi.sustainder.com/talq/override-commands" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": [
        "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "urn:talq:device:b2c3d4e5-f6a7-8901-bcde-f12345678901"
    ],
    "target_command": null
  }'

Request body (clear overrides)

{
    "addresses": [
        "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "urn:talq:device:b2c3d4e5-f6a7-8901-bcde-f12345678901"
    ],
    "target_command": null
}

Response (200 OK)

{
    "status": "accepted",
    "overridden": 2,
    "expiration": null,
    "results": [
        {
            "device_address": "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "status": "success"
        },
        {
            "device_address": "urn:talq:device:b2c3d4e5-f6a7-8901-bcde-f12345678901",
            "status": "success"
        }
    ]
}

Sends temporary override commands to one or more TALQ devices. Overrides take immediate effect and expire after the specified duration, at which point devices return to their calendar-defined behaviour.

Set target_command to null to clear any active overrides on the specified devices.

Request Parameters

Parameter	Type	Required	Description
addresses	array	Yes	List of device URN addresses to send the override to.
target_command	object\	null	Yes
target_command.dimmingLevel	integer	Yes	Target dimming level (0-100).
target_command.expiration_minutes	integer	Yes	Duration in minutes before the override expires. Maximum: 240 minutes.

Response Fields

Field	Type	Description
status	string	Overall command status: accepted or rejected.
overridden	integer	Number of devices successfully overridden.
expiration	string\	null
results	array	Per-device override results.
results[].device_address	string	The device that was targeted.
results[].status	string	Result for this device: success or failed.

Error Responses

Status	Description
400	Validation error (e.g., expiration exceeds 240 minutes, empty addresses, dimming level out of range).
404	One or more device addresses not found.

TALQ Logging

TALQ logging allows you to configure data collection from device attributes. Logger configurations define which attributes to record, how to record them (recording mode), and how to report the collected data (reporting mode). Log reports contain the actual recorded data from the configured loggers.

/talq/logger-configs [GET]

Request

curl "https://httpapi.sustainder.com/talq/logger-configs" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response (200 OK)

{
    "logger_configs": [
        {
            "address": "urn:talq:logger:l1a2b3c4-d5e6-7890-abcd-ef1234567890",
            "recording_mode": "periodic",
            "reporting_mode": "on_demand",
            "source_addresses": [
                "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890/activePower/value",
                "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890/activeEnergy/value"
            ],
            "description": "Power monitoring - Keizersgracht 42",
            "interval_minutes": 15
        },
        {
            "address": "urn:talq:logger:m2b3c4d5-e6f7-8901-bcde-f12345678901",
            "recording_mode": "on_change",
            "reporting_mode": "periodic",
            "source_addresses": [
                "urn:talq:device:b2c3d4e5-f6a7-8901-bcde-f12345678901/dimmingLevel/actualLevel"
            ],
            "description": "Dimming level change log - Herengracht 108",
            "reporting_interval_minutes": 60
        }
    ],
    "total": 2
}

Lists all TALQ logger configurations.

Response Fields

Field	Type	Description
address	string	Unique TALQ URN address of the logger configuration.
recording_mode	string	How data is recorded: periodic (at fixed intervals) or on_change (when values change).
reporting_mode	string	How data is reported: periodic (at fixed intervals), on_demand (when requested), or on_threshold (when thresholds are exceeded).
source_addresses	array	List of device attribute URN paths to record (format: {deviceAddress}/{functionId}/{attributeName}).
description	string	Human-readable description of the logger configuration.
interval_minutes	integer	Recording interval in minutes (for periodic recording mode).
reporting_interval_minutes	integer	Reporting interval in minutes (for periodic reporting mode).
total	integer	Total number of logger configurations.

/talq/logger-configs/{loggerAddress} [GET]

Request

curl "https://httpapi.sustainder.com/talq/logger-configs/urn:talq:logger:l1a2b3c4-d5e6-7890-abcd-ef1234567890" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response (200 OK)

{
    "address": "urn:talq:logger:l1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "recording_mode": "periodic",
    "reporting_mode": "on_demand",
    "source_addresses": [
        "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890/activePower/value",
        "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890/activeEnergy/value"
    ],
    "description": "Power monitoring - Keizersgracht 42",
    "interval_minutes": 15,
    "created_at": "2024-10-01T10:00:00Z",
    "last_report_at": "2024-11-15T14:15:00Z"
}

Returns detailed information for a specific logger configuration.

Path Parameters

Parameter	Type	Description
loggerAddress	string	The TALQ URN address of the logger configuration.

Response Fields

Same fields as the logger config list response, plus:

Field	Type	Description
created_at	string	ISO 8601 timestamp of when the logger was created.
last_report_at	string	ISO 8601 timestamp of the most recent log report.

Error Responses

Status	Description
404	Logger configuration not found.

/talq/logger-configs [POST]

Request

curl -X POST "https://httpapi.sustainder.com/talq/logger-configs" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "address": "urn:talq:logger:new-logger-001",
    "recording_mode": "periodic",
    "reporting_mode": "on_demand",
    "source_addresses": [
        "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890/activePower/value",
        "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890/voltage/value"
    ],
    "description": "Voltage and power monitoring",
    "interval_minutes": 30
  }'

Request body

{
    "address": "urn:talq:logger:new-logger-001",
    "recording_mode": "periodic",
    "reporting_mode": "on_demand",
    "source_addresses": [
        "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890/activePower/value",
        "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890/voltage/value"
    ],
    "description": "Voltage and power monitoring",
    "interval_minutes": 30
}

Response (201 Created)

{
    "address": "urn:talq:logger:new-logger-001",
    "recording_mode": "periodic",
    "reporting_mode": "on_demand",
    "source_addresses": [
        "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890/activePower/value",
        "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890/voltage/value"
    ],
    "description": "Voltage and power monitoring",
    "interval_minutes": 30,
    "created_at": "2024-11-15T15:00:00Z"
}

Creates a new TALQ logger configuration.

Request Parameters

Parameter	Type	Required	Description
address	string	Yes	Unique URN identifier for the new logger configuration.
recording_mode	string	Yes	Recording mode: periodic or on_change.
reporting_mode	string	Yes	Reporting mode: periodic, on_demand, or on_threshold.
source_addresses	array	Yes	List of device attribute URN paths to record.
description	string	No	Human-readable description.
interval_minutes	integer	Conditional	Recording interval in minutes. Required when recording_mode is periodic.
reporting_interval_minutes	integer	Conditional	Reporting interval in minutes. Required when reporting_mode is periodic.

Error Responses

Status	Description
400	Validation error (e.g., missing required fields, invalid source addresses).
409	Logger configuration with the specified address already exists.

/talq/logger-configs/{loggerAddress} [PUT]

Request

curl -X PUT "https://httpapi.sustainder.com/talq/logger-configs/urn:talq:logger:l1a2b3c4-d5e6-7890-abcd-ef1234567890" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "recording_mode": "periodic",
    "reporting_mode": "periodic",
    "source_addresses": [
        "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890/activePower/value",
        "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890/activeEnergy/value",
        "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890/voltage/value"
    ],
    "description": "Extended power monitoring - Keizersgracht 42",
    "interval_minutes": 10,
    "reporting_interval_minutes": 60
  }'

Request body

{
    "recording_mode": "periodic",
    "reporting_mode": "periodic",
    "source_addresses": [
        "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890/activePower/value",
        "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890/activeEnergy/value",
        "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890/voltage/value"
    ],
    "description": "Extended power monitoring - Keizersgracht 42",
    "interval_minutes": 10,
    "reporting_interval_minutes": 60
}

Response (200 OK)

{
    "address": "urn:talq:logger:l1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "recording_mode": "periodic",
    "reporting_mode": "periodic",
    "source_addresses": [
        "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890/activePower/value",
        "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890/activeEnergy/value",
        "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890/voltage/value"
    ],
    "description": "Extended power monitoring - Keizersgracht 42",
    "interval_minutes": 10,
    "reporting_interval_minutes": 60
}

Replaces the entire configuration of an existing logger. All fields in the request body are required as this performs a full replacement.

Path Parameters

Parameter	Type	Description
loggerAddress	string	The TALQ URN address of the logger configuration to update.

Request Parameters

Same as POST /talq/logger-configs, except address is not included (it is taken from the URL path).

Error Responses

Status	Description
400	Validation error.
404	Logger configuration not found.

/talq/logger-configs/{loggerAddress} [DELETE]

Request

curl -X DELETE "https://httpapi.sustainder.com/talq/logger-configs/urn:talq:logger:l1a2b3c4-d5e6-7890-abcd-ef1234567890" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response (204 No Content)

204 No Content

Deletes a TALQ logger configuration. Any pending log reports for this logger will still be available until they are retrieved.

Path Parameters

Parameter	Type	Description
loggerAddress	string	The TALQ URN address of the logger configuration to delete.

Error Responses

Status	Description
404	Logger configuration not found.

/talq/log-reports/count [GET]

Request

curl "https://httpapi.sustainder.com/talq/log-reports/count" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response (200 OK)

{
    "count": 1482
}

Returns the total number of log report entries across all loggers.

Response Fields

Field	Type	Description
count	integer	Total number of log report entries.

/talq/log-reports/{loggerAddress} [GET]

Request

curl "https://httpapi.sustainder.com/talq/log-reports/urn:talq:logger:l1a2b3c4-d5e6-7890-abcd-ef1234567890" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response (200 OK)

{
    "logger_address": "urn:talq:logger:l1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "reports": [
        {
            "timestamp": "2024-11-15T14:00:00Z",
            "values": [
                {
                    "source": "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890/activePower/value",
                    "value": 42.5,
                    "unit": "watt"
                },
                {
                    "source": "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890/activeEnergy/value",
                    "value": 1285.7,
                    "unit": "kilowatt_hour"
                }
            ]
        },
        {
            "timestamp": "2024-11-15T14:15:00Z",
            "values": [
                {
                    "source": "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890/activePower/value",
                    "value": 38.2,
                    "unit": "watt"
                },
                {
                    "source": "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890/activeEnergy/value",
                    "value": 1286.3,
                    "unit": "kilowatt_hour"
                }
            ]
        }
    ],
    "total_reports": 96
}

Returns the log reports collected for a specific logger configuration. Reports contain timestamped values for each configured source attribute.

Path Parameters

Parameter	Type	Description
loggerAddress	string	The TALQ URN address of the logger configuration.

Response Fields

Field	Type	Description
logger_address	string	URN address of the logger this report belongs to.
reports	array	List of timestamped data entries.
reports[].timestamp	string	ISO 8601 timestamp of when the data was recorded.
reports[].values	array	List of recorded values at this timestamp.
reports[].values[].source	string	URN path of the source attribute.
reports[].values[].value	number	Recorded value.
reports[].values[].unit	string	Unit of measurement.
total_reports	integer	Total number of report entries available for this logger.

Error Responses

Status	Description
404	Logger configuration not found.

TALQ CMS API

The TALQ CMS API handles inbound communications from TALQ-compliant gateways. In the TALQ architecture, the Sustainder Brokerage Layer (SBL) acts as the Central Management System (CMS) -- the central server that gateways register with and report to.

These endpoints receive registrations, device announcements, and service declarations from gateways. When a TALQ gateway connects to the SBL for the first time, it sends its device inventory, device class definitions, and service capabilities through these endpoints.

The base URL for the TALQ CMS API is https://httpapi.sustainder.com/talqcms.

This API communicates in JSON.

How Gateway Registration Works

The registration process follows the TALQ specification:

1. Service announcement -- The gateway sends its service capabilities via POST /talqcms/services.
2. Device class announcement -- The gateway announces the device classes it supports via POST /talqcms/device-classes.
3. Device registration -- The gateway registers its devices via POST /talqcms/devices, initially using a zero UUID as the client address.
4. Ongoing updates -- The gateway can update device details via PATCH /talqcms/devices/{deviceAddress} as device states change.

Authentication

All TALQ CMS API endpoints require JWT authentication. Include the token in the Authorization header:

Authorization: JWT {your_token}

TALQ CMS Devices

These endpoints handle device registration and management from TALQ gateways. Gateways use these endpoints to announce their devices to the CMS, update device information, and manage the device lifecycle.

/talqcms/devices [GET]

Request

curl "https://httpapi.sustainder.com/talqcms/devices" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response (200 OK)

{
    "devices": [
        {
            "address": "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "deviceClass": "LuminaireController",
            "gateway_address": "urn:talq:gateway:550e8400-e29b-41d4-a716-446655440000",
            "status": "operational",
            "description": "Streetlight controller - Keizersgracht 42",
            "registered_at": "2024-09-15T10:30:00Z"
        },
        {
            "address": "urn:talq:device:b2c3d4e5-f6a7-8901-bcde-f12345678901",
            "deviceClass": "LuminaireController",
            "gateway_address": "urn:talq:gateway:550e8400-e29b-41d4-a716-446655440000",
            "status": "operational",
            "description": "Streetlight controller - Herengracht 108",
            "registered_at": "2024-09-15T10:30:05Z"
        }
    ],
    "total": 2
}

Lists all devices that have been registered through the CMS interface by TALQ gateways.

Response Fields

Field	Type	Description
address	string	Unique TALQ URN address of the device.
deviceClass	string	Name of the device class this device belongs to.
gateway_address	string	URN address of the gateway that registered this device.
status	string	Device status: operational, degraded, not_operational, or unknown.
description	string	Human-readable description of the device.
registered_at	string	ISO 8601 timestamp of when the device was registered with the CMS.
total	integer	Total number of registered CMS devices.

/talqcms/devices [POST]

Request - Initial device registration (zero UUID)

curl -X POST "https://httpapi.sustainder.com/talqcms/devices?clientAddress=00000000-0000-0000-0000-000000000000" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "devices": [
        {
            "deviceClass": "LuminaireController",
            "description": "Streetlight controller - Vondelpark East",
            "functions": [
                {
                    "functionId": "dimmingLevel",
                    "currentValue": 0,
                    "unit": "percent"
                },
                {
                    "functionId": "onOff",
                    "currentValue": false,
                    "unit": "boolean"
                }
            ]
        },
        {
            "deviceClass": "LuminaireController",
            "description": "Streetlight controller - Vondelpark West",
            "functions": [
                {
                    "functionId": "dimmingLevel",
                    "currentValue": 0,
                    "unit": "percent"
                },
                {
                    "functionId": "onOff",
                    "currentValue": false,
                    "unit": "boolean"
                }
            ]
        }
    ]
  }'

Request body

{
    "devices": [
        {
            "deviceClass": "LuminaireController",
            "description": "Streetlight controller - Vondelpark East",
            "functions": [
                {
                    "functionId": "dimmingLevel",
                    "currentValue": 0,
                    "unit": "percent"
                },
                {
                    "functionId": "onOff",
                    "currentValue": false,
                    "unit": "boolean"
                }
            ]
        },
        {
            "deviceClass": "LuminaireController",
            "description": "Streetlight controller - Vondelpark West",
            "functions": [
                {
                    "functionId": "dimmingLevel",
                    "currentValue": 0,
                    "unit": "percent"
                },
                {
                    "functionId": "onOff",
                    "currentValue": false,
                    "unit": "boolean"
                }
            ]
        }
    ]
}

Response (201 Created)

{
    "devices": [
        {
            "address": "urn:talq:device:c3d4e5f6-a7b8-9012-cdef-123456789012",
            "deviceClass": "LuminaireController",
            "gateway_address": "urn:talq:gateway:550e8400-e29b-41d4-a716-446655440000",
            "status": "operational",
            "description": "Streetlight controller - Vondelpark East",
            "registered_at": "2024-11-15T15:00:00Z"
        },
        {
            "address": "urn:talq:device:d4e5f6a7-b890-1234-cdef-234567890123",
            "deviceClass": "LuminaireController",
            "gateway_address": "urn:talq:gateway:550e8400-e29b-41d4-a716-446655440000",
            "status": "operational",
            "description": "Streetlight controller - Vondelpark West",
            "registered_at": "2024-11-15T15:00:00Z"
        }
    ]
}

Registers new devices with the CMS. This endpoint is called by TALQ gateways during the initial registration process.

For the initial registration, the clientAddress query parameter should be set to the zero UUID (00000000-0000-0000-0000-000000000000). The CMS will assign permanent URN addresses to each device and return them in the response.

Query Parameters

Parameter	Type	Required	Description
clientAddress	string	Yes	Client address for the registration. Use 00000000-0000-0000-0000-000000000000 for initial registration.

Request Parameters

Parameter	Type	Required	Description
devices	array	Yes	List of devices to register.
devices[].deviceClass	string	Yes	Device class name. Must match a previously announced device class.
devices[].description	string	No	Human-readable description of the device.
devices[].functions	array	No	Initial function values for the device.
devices[].functions[].functionId	string	Yes	Function identifier.
devices[].functions[].currentValue	mixed	Yes	Initial value of the function.
devices[].functions[].unit	string	No	Unit of measurement.

Error Responses

Status	Description
400	Validation error (e.g., unknown device class, missing required fields).

/talqcms/devices/{deviceAddress} [GET]

Request

curl "https://httpapi.sustainder.com/talqcms/devices/urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response (200 OK)

{
    "address": "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "deviceClass": "LuminaireController",
    "gateway_address": "urn:talq:gateway:550e8400-e29b-41d4-a716-446655440000",
    "status": "operational",
    "description": "Streetlight controller - Keizersgracht 42",
    "functions": [
        {
            "functionId": "dimmingLevel",
            "currentValue": 75,
            "unit": "percent"
        },
        {
            "functionId": "onOff",
            "currentValue": true,
            "unit": "boolean"
        }
    ],
    "registered_at": "2024-09-15T10:30:00Z",
    "last_updated": "2024-11-15T14:32:08Z"
}

Returns detailed information for a specific CMS-registered device.

Path Parameters

Parameter	Type	Description
deviceAddress	string	The TALQ URN address of the device.

Error Responses

Status	Description
404	Device not found.

/talqcms/devices/{deviceAddress} [PATCH]

Request

curl -X PATCH "https://httpapi.sustainder.com/talqcms/devices/urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "degraded",
    "functions": [
        {
            "functionId": "dimmingLevel",
            "currentValue": 50,
            "unit": "percent"
        }
    ]
  }'

Request body

{
    "status": "degraded",
    "functions": [
        {
            "functionId": "dimmingLevel",
            "currentValue": 50,
            "unit": "percent"
        }
    ]
}

Response (200 OK)

{
    "address": "urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "deviceClass": "LuminaireController",
    "gateway_address": "urn:talq:gateway:550e8400-e29b-41d4-a716-446655440000",
    "status": "degraded",
    "description": "Streetlight controller - Keizersgracht 42",
    "functions": [
        {
            "functionId": "dimmingLevel",
            "currentValue": 50,
            "unit": "percent"
        },
        {
            "functionId": "onOff",
            "currentValue": true,
            "unit": "boolean"
        }
    ],
    "last_updated": "2024-11-15T15:10:00Z"
}

Updates information for a CMS-registered device. This is typically called by gateways to report status changes or updated function values.

Path Parameters

Parameter	Type	Description
deviceAddress	string	The TALQ URN address of the device to update.

Request Parameters

Parameter	Type	Required	Description
status	string	No	Updated device status: operational, degraded, not_operational.
description	string	No	Updated device description.
functions	array	No	Updated function values. Only specified functions are updated; others remain unchanged.

Error Responses

Status	Description
400	Validation error.
404	Device not found.

/talqcms/devices/{deviceAddress} [DELETE]

Request

curl -X DELETE "https://httpapi.sustainder.com/talqcms/devices/urn:talq:device:a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response (204 No Content)

204 No Content

Removes a device from the CMS registry. This is typically called when a device is decommissioned or removed from a gateway's network.

Path Parameters

Parameter	Type	Description
deviceAddress	string	The TALQ URN address of the device to remove.

Error Responses

Status	Description
404	Device not found.

TALQ CMS Device Classes

This endpoint receives device class announcements from TALQ gateways. When a gateway connects to the CMS, it announces the device classes it supports so that the CMS knows what types of devices to expect during registration.

/talqcms/device-classes [POST]

Request

curl -X POST "https://httpapi.sustainder.com/talqcms/device-classes" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "device_classes": [
        {
            "className": "LuminaireController",
            "description": "TALQ luminaire controller with dimming and on/off capability",
            "version": "2.4.0",
            "functions": [
                {
                    "functionId": "dimmingLevel",
                    "description": "Controls the dimming level of the luminaire",
                    "type": "numeric",
                    "writable": true,
                    "attributes": [
                        {
                            "attributeName": "targetLevel",
                            "type": "integer",
                            "unit": "percent",
                            "minValue": 0,
                            "maxValue": 100
                        },
                        {
                            "attributeName": "actualLevel",
                            "type": "integer",
                            "unit": "percent"
                        }
                    ]
                },
                {
                    "functionId": "onOff",
                    "description": "On/Off control for the luminaire",
                    "type": "boolean",
                    "writable": true,
                    "attributes": [
                        {
                            "attributeName": "state",
                            "type": "boolean"
                        }
                    ]
                }
            ]
        }
    ]
  }'

Request body

{
    "device_classes": [
        {
            "className": "LuminaireController",
            "description": "TALQ luminaire controller with dimming and on/off capability",
            "version": "2.4.0",
            "functions": [
                {
                    "functionId": "dimmingLevel",
                    "description": "Controls the dimming level of the luminaire",
                    "type": "numeric",
                    "writable": true,
                    "attributes": [
                        {
                            "attributeName": "targetLevel",
                            "type": "integer",
                            "unit": "percent",
                            "minValue": 0,
                            "maxValue": 100
                        },
                        {
                            "attributeName": "actualLevel",
                            "type": "integer",
                            "unit": "percent"
                        }
                    ]
                },
                {
                    "functionId": "onOff",
                    "description": "On/Off control for the luminaire",
                    "type": "boolean",
                    "writable": true,
                    "attributes": [
                        {
                            "attributeName": "state",
                            "type": "boolean"
                        }
                    ]
                }
            ]
        }
    ]
}

Response (201 Created)

{
    "acknowledged": 1
}

Receives device class announcements from a TALQ gateway. The gateway sends its supported device class definitions so the CMS can validate subsequent device registrations.

If a device class with the same className already exists, it will be updated with the new definition.

Request Parameters

Parameter	Type	Required	Description
device_classes	array	Yes	List of device class definitions to announce.
device_classes[].className	string	Yes	Unique name of the device class.
device_classes[].description	string	No	Human-readable description.
device_classes[].version	string	Yes	TALQ protocol version of this device class definition.
device_classes[].functions	array	Yes	List of functions available on devices of this class.
device_classes[].functions[].functionId	string	Yes	Unique function identifier.
device_classes[].functions[].description	string	No	Description of the function.
device_classes[].functions[].type	string	Yes	Data type: numeric, boolean, string, enum.
device_classes[].functions[].writable	boolean	Yes	Whether the function can be controlled.
device_classes[].functions[].attributes	array	No	Attribute definitions for this function.

Response Fields

Field	Type	Description
acknowledged	integer	Number of device classes successfully processed.

Error Responses

Status	Description
400	Validation error (e.g., missing required fields, invalid function definitions).

TALQ CMS Services

This endpoint receives service announcements from TALQ gateways. When a gateway connects to the CMS, it declares the services it is capable of providing.

/talqcms/services [POST]

Request

curl -X POST "https://httpapi.sustainder.com/talqcms/services" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "services": [
        {
            "serviceName": "LightingService",
            "version": "2.4.0",
            "description": "TALQ Lighting control service for outdoor luminaires",
            "serviceType": "lighting",
            "supported_functions": [
                "dimmingLevel",
                "onOff",
                "colorTemperature"
            ],
            "configuration": {
                "max_devices": 1000,
                "supports_multicast": true,
                "supports_logging": true
            }
        },
        {
            "serviceName": "MeteringService",
            "version": "2.4.0",
            "description": "Energy metering service for power consumption tracking",
            "serviceType": "metering",
            "supported_functions": [
                "activePower",
                "activeEnergy",
                "voltage"
            ],
            "configuration": {
                "max_devices": 1000,
                "supports_multicast": false,
                "supports_logging": true
            }
        }
    ]
  }'

Request body

{
    "services": [
        {
            "serviceName": "LightingService",
            "version": "2.4.0",
            "description": "TALQ Lighting control service for outdoor luminaires",
            "serviceType": "lighting",
            "supported_functions": [
                "dimmingLevel",
                "onOff",
                "colorTemperature"
            ],
            "configuration": {
                "max_devices": 1000,
                "supports_multicast": true,
                "supports_logging": true
            }
        },
        {
            "serviceName": "MeteringService",
            "version": "2.4.0",
            "description": "Energy metering service for power consumption tracking",
            "serviceType": "metering",
            "supported_functions": [
                "activePower",
                "activeEnergy",
                "voltage"
            ],
            "configuration": {
                "max_devices": 1000,
                "supports_multicast": false,
                "supports_logging": true
            }
        }
    ]
}

Response (201 Created)

201 Created

Receives service announcements from a TALQ gateway. Per the TALQ specification, the response body is empty with a 201 Created status code, indicating that the services have been acknowledged and registered.

Request Parameters

Parameter	Type	Required	Description
services	array	Yes	List of service definitions to announce.
services[].serviceName	string	Yes	Unique name of the service.
services[].version	string	Yes	TALQ protocol version supported by this service.
services[].description	string	No	Human-readable description.
services[].serviceType	string	Yes	Category of the service (e.g., lighting, metering, sensor).
services[].supported_functions	array	No	List of function names this service supports.
services[].configuration	object	No	Service-specific configuration parameters.

Error Responses

Status	Description
400	Validation error (e.g., missing required fields).