SolarUser SolarFlux API

The SolarUser SolarFlux API provides methods to manage SolarFlux settings within SolarNetwork, that manage how SolarNetwork interacts with SolarFlux.

For general information about SolarFlux see the SolarFlux guide.

📒 Note that these settings do not manage how SolarNode devices interact with SolarFlux: that is managed in SolarNode itself.

API Endpoints

The following endpoint paths are all relative to the base path /solaruser/api/v1/sec/user/flux:

Verb	Endpoint	Description
PUT	/agg/pub/default-settings	Save aggregate datum publish default settings
GET	/agg/pub/default-settings	View the aggregate datum publish default settings
DELETE	/agg/pub/default-settings	Delete the aggregate datum publish default settings
POST	/agg/pub/settings	Create aggregate datum publish settings
GET	/agg/pub/settings	List aggregate datum publish settings
GET	/agg/pub/settings/{configurationId}	View aggregate datum publish settings
PUT	/agg/pub/settings/{configurationId}	Update aggregate datum publish settings
DELETE	/agg/pub/settings/{configurationId}	Delete aggregate datum publish settings

Date formatting

For endpoints that return timestamp values (full date and time) the timestamps will be rendered as string values using the ISO 8601 timestamp format YYYY-MM-dd HH:mm:ss.SSSSSS'Z' in the UTC time zone, for example 2020-03-01 10:30:49.346827Z. The fractional second can contain up to 6 digits for nanosecond level precision, and will only display up to the precision set in the timestamp. That means the fractional seconds might not appear if the timestamp has no fractional seconds.

For endpoints that accept timestamp values, the same ISO 8601 timestamp format is required, however the fractional seconds may be omitted. For example 2020-03-01 10:30:49Z is a valid value.

Aggregate datum publish default settings

Default aggregate datum publish settings act as the SolarFlux settings to use when no other specific aggregate datum publish settings are configured.

Aggregate datum publish default settings save

This method saves (creates or updates) an aggregate datum publish default settings entity. An application/json request body must be provided with the entity details to save.

PUT	/solaruser/api/v1/sec/user/flux/agg/pub/default-settings

The request body accepts an aggregate datum publish default settings JSON object with the following properties:

Property	Type	Description
publish	Boolean	true to enable publishing, false to disable publishing.
retain	Boolean	When enabled, SolarFlux messages will be published with the MQTT retain flag enabled, which means SolarFlux will cache the last-posted message and return that immediately when a client subscribes to a topic that includes that message. When disabled, clients will only receive new messages that are published after they subscribe.

For example:

{"publish":true, "retain":true}

The response will be an aggregate datum publish default settings entity object. See Aggregate datum publish default settings view response for more information.

Aggregate datum publish default settings view

This method returns an aggregate datum publish default settings entity.

GET	/solaruser/api/v1/sec/user/flux/agg/pub/default-settings

Aggregate datum publish default settings view response

The response will be an aggregate datum publish default settings entity object with the following properties:

Property	Type	Description
userId	Number	The SolarNetwork account ID that owns the entity.
created	String	The creation date.
publish	Boolean	true to publish, false to not publish.
retain	String	true to set the MQTT retain flag on published messages.

An example response looks like:

{
  "success": true,
  "data": {
    "userId": 123,
    "created": "1970-01-01 00:00:00Z",
    "publish": true,
    "retain": false
  }
}

Aggregate datum publish default settings delete

This method deletes an aggregate datum publish default settings entity. Once deleted, the system defaults where publishing is disabled will be assumed.

DELETE	/solaruser/api/v1/sec/user/flux/agg/pub/default-settings

Aggregate datum publish settings

Aggregate datum publish settings define the SolarFlux settings to use for specific nodes and sources. They override the default publish settings. If two settings have overlaping node or source ID values, the settings with the highest ID value will be used, with wildcard settings (those with an empty node IDs or source IDs value) used as a last resort.

Aggregate datum publish settings create

This method creates a new aggregate datum publish settings entity. An application/json request body must be provided with the entity details to create.

POST	/solaruser/api/v1/sec/user/flux/agg/pub/settings

The request body accepts an aggregate datum publish settings JSON object with the following properties:

Property	Type	Description
nodeIds	Number[]	An array of node IDs to apply the settings to. If not provided then the settings will apply to all nodes.
sourceIds	String[]	An array of source IDs to apply the settings to. If not provided then the settings will apply to all sources.
publish	Boolean	true to enable publishing, false to disable publishing.
retain	Boolean	When enabled, SolarFlux messages will be published with the MQTT retain flag enabled, which means SolarFlux will cache the last-posted message and return that immediately when a client subscribes to a topic that includes that message. When disabled, clients will only receive new messages that are published after they subscribe.

☝️ Note that for a settings entity to match a given datum stream, both the configured nodeIds and sourceIds values must match those of the stream.

For example:

{
  "publish": true,
  "retain": true,
  "nodeIds": [
    1,
    2,
    3
  ],
  "sourceIds": [
    "a",
    "b",
    "c"
  ]
}

The response will be a aggregate datum publish settings entity object that provides the ID assigned to the new aggregate datum publish settings. See Aggregate datum publish settings view response for more information. In addition a Location HTTP header will be returned with the path to view the entity, for example:

Location: /solaruser/api/v1/sec/user/flux/agg/pub/settings/1

Aggregate datum publish settings list

This method returns a list of Aggregate datum publish settings entities matching an optional search filter.

GET	/solaruser/api/v1/sec/user/flux/agg/pub/settings

The request body accepts the following search filter query parameters:

Property	Type	Description
nodeId	Number	The ID of a node ID to match.
nodeIds	String	A comma-delimited list of node IDs to match (logical OR).
sourceId	Number	The ID of a node ID to match.
sourceIds	String	A comma-delimited list of source IDs to match (logical OR).
offset	Number	Optional starting result offset. Defaults to 0.
max	Number	Optional maximum result count, or unlimited if not provided.

The response will be a [paged results][paged-results] list of aggregate datum publish settings entity objects. See the Aggregate datum publish settings view response for details.

Aggregate datum publish settings view

This method returns a Aggregate datum publish settings entity.

GET	/solaruser/api/v1/sec/user/flux/agg/pub/settings/{configurationId}
configurationId	The ID of the aggregate datum publish settings to view.

Aggregate datum publish settings view response

The response will be a Aggregate datum publish settings entity object with the following properties:

Property	Type	Description
userId	Number	The SolarNetwork account ID that owns the entity.
id	Number	A unique ID assigned to the entity.
created	String	The creation date.
modified	String	The modification date.
publish	Boolean	true to publish datum matching these settings.
retain	String	true to set the MQTT retain flag on published messages.

An example response looks like:

{
  "success": true,
  "data": {
    "userId": 123,
    "id": 1,
    "created": "2024-06-23 18:53:24.642209Z",
    "modified": "2024-06-23 18:53:24.642209Z",
    "nodeIds": [
      1,
      2,
      3
    ],
    "sourceIds": [
      "a",
      "b",
      "c"
    ],
    "publish": true,
    "retain": false,
    "enabled": true
  }
}

Aggregate datum publish settings update

This method updates an existing aggregate datum publish settings entity. An application/json request body must be provided with the complete entity details to save.

PUT	/solaruser/api/v1/sec/user/flux/agg/pub/settings/{configurationId}
configurationId	The ID of the aggregate datum publish settings to update.

The request body accepts an aggregate datum publish settings JSON object as specified in the Aggregate datum publish settings create method.

Aggregate datum publish settings delete

This method deletes an aggregate datum publish settings entity.

DELETE	/solaruser/api/v1/sec/user/flux/agg/pub/settings/{configurationId}
configurationId	The ID of the aggregate datum publish settings to delete.