SolarUser API

The SolarUser API provides methods to manipulate nodes. All dates and times are represented in the Gregorian calendar system. All requests must provide a valid authentication token. See SolarNet API authentication for information on how to use authentication tokens.

Request formats

Unless otherwise noted, all HTTP request methods that accept content (like POST or PUT) expect application/x-www-form-urlencoded content.

Response formats

SolarUser supports different response data formats, which are based on the Accept HTTP header used in the request. The supported formats, and their associated Accept header values, are:

CBOR - application/cbor
JSON - application/json
XML - text/xml
CSV - text/csv

Endpoints

Verb	Endpoint	Description
`POST`	`/associate.{json,xml}`	Accept a SolarNode invitation and associate the node with SolarNetwork.
`GET`	`/datum/auxiliary`	List datum auxiliary records.
`POST`	`/datum/auxiliary`	Add or update datum auxiliary records.
`POST`	`/datum/auxiliary/move`	Update and move an existing datum auxiliary record.
`GET`	`/datum/auxiliary/{type}/{nodeId}/{date}/{sourceId}`	View a specific datum auxiliary record.
`DELETE`	`/datum/auxiliary/{type}/{nodeId}/{date}/{sourceId}`	Delete datum auxiliary records.
`GET`	`/datum/maint/agg/stale`	List stale aggregate datum records.
`POST`	`/datum/maint/agg/stale`	Mark ranges of aggregate datum data as stale so it will be re-computed.
`POST`	`/datum/meta/{nodeId}/{sourceId}`	Add metadata to a node datum source.
`PUT`	`/datum/meta/{nodeId}/{sourceId}`	Store metadata for a node datum source.
`DELETE`	`/datum/meta/{nodeId}/{sourceId}`	Delete metadata for a node datum source.
`GET`	`/datum/stream/meta/node/{streamId}`	View datum stream metadata.
`PATCH`	`/datum/stream/meta/node/{streamId}`	Update the node or source ID associated with a datum stream.
`POST`	`/datum/stream/meta/node/{streamId}`	Update the node, source, or property names associated with a datum stream.
`GET`	`/instr`	List instructions matching a search filter.
`POST`	`/instr/add`	Enqueue an instruction for one or more nodes.
`POST`	`/instr/add/{topic}`	Enqueue an instruction for one or more nodes.
`POST`	`/instr/exec`	Execute an instruction for one or more nodes and wait for the result.
`POST`	`/instr/exec/{topic}`	Execute an instruction for one or more nodes and wait for the result.
`GET`	`/instr/view`	Get one or more instructions by their ID.
`GET`	`/instr/viewActive`	View queued instructions for one or more nodes.
`GET`	`/instr/viewPending`	View instructions that are still being processed for one or more nodes.
`POST`	`/instr/updateState`	Change the state of an instruction.
`POST`	`/instr/updateState`	Change the state of instructions matching search criteria.
`POST`	`/location/datum/meta/{locationId}/{sourceId}`	Add metadata to a location datum source.
`PUT`	`/location/datum/meta/{locationId}/{sourceId}`	Store metadata for a location datum source.
`DELETE`	`/location/datum/meta/{locationId}/{sourceId}`	Delete metadata for a location datum source.
`GET`	`/nodes`	Get all nodes associated with an account.
`GET`	`/nodes/archived`	List all archived nodes associated with an account.
`POST`	`/nodes/archived`	Change the archived status for a set of nodes.
`GET`	`/nodes/create-cert`	Manually create a new SolarNode certificate.
`GET`	`/nodes/cert/{nodeId}`	Download a node certificate.
`POST`	`/nodes/cert/{nodeId}`	View a node certificate.
`GET`	`/nodes/find`	Get metadata for one or more nodes.
`GET`	`/nodes/meta`	List node information matching a search criteria.
`GET`	`/nodes/meta/{nodeId}`	Get metadata for a specific node.
`POST`	`/nodes/meta/{nodeId}`	Add metadata to a node.
`PUT`	`/nodes/meta/{nodeId}`	Store metadata on a node.
`DELETE`	`/nodes/meta/{nodeId}`	Remove metadata from a node.
`GET`	`/user/auth-tokens`	List security tokens.
`DELETE`	`/user/auth-tokens`	Delete a security token.
`GET`	`/user/auth-tokens/find`	Find security tokens matching a filter.
`POST`	`/user/auth-tokens/generate/{type}`	Create a new security token.
`POST`	`/user/auth-tokens/info`	Update the name and description of a security token.
`PATCH`	`/user/auth-tokens/policy`	Add new policy elements to a security token.
`PUT`	`/user/auth-tokens/policy`	Save a policy on a security token.
`POST`	`/user/auth-tokens/status`	Update the status of a security token.
`GET`	`/user/events`	List user-related application events.
`GET`	`/users/meta`	Get metadata for the active user.
`POST`	`/users/meta`	Add metadata to the active user.
`PUT`	`/users/meta`	Store metadata on the active user.
`DELETE`	`/users/meta`	Remove metadata from the active user.
`GET`	`/whoami`	Verify authentication.

Associate node

This method is the second step in the SolarNode setup process to associate a node with SolarNetwork via an invitation from SolarNetwork, after the SolarIn /identity.do method. This method can be called as /associate.json for a JSON response or /associate.xml for an XML response.

POST	`/solaruser/associate.{json,xml}`
`username`	The SolarNetwork account email from the SolarNode invitation.
`confirmationKey`	The confirmation key from the SolarNode invitation.
`keystorePassword`	The password to use for the SolarNode certificate keystore.

Associate node response

The response contains details such as the ID assigned to the node and the node's X.509 client certificate.

Property	Type	Description
`networkCertificateStatus`	string	Status of the X.509 client certificate; one of `Requested`, `Active`, or `Disabled`.
`networkCertificateSubjectDN`	string	The X.509 client certificate subject distinguished name assigned to the node.
`networkCertificate`	string	The X.509 client certificate, Base-64 encoded.
`networkId`	number	The unique ID assigned to the node.
`username`	string	The SolarNetwork account email from the SolarNode invitation.
`confirmationKey`	string	The confirmation key from the SolarNode invitation.

An example XML response looks like:

<NetworkAssociationDetailsnetworkId="123"networkCertificateStatus="Active"networkCertificateSubjectDN="UID=123,O=SolarNetwork"networkCertificate="DLKJDLS..."username="foo@example.com"confirmationKey="abc123..."
>
</NetworkAssociationDetails>

Create node certificate

This method is for manually creating a new SolarNode certificate, without going through the normal invitation/association process. This is useful for integrating custom data collection applications with SolarNetwork that want to be able to post data, and thus require a certificate.

POST	`/solaruser/api/v1/sec/nodes/create-cert`
`timeZone`	A full time zone ID for the location of the node, e.g. `Pacific/Auckland`.
`country`	A 2-character country code for the location of the node, e.g. `NZ`.
`keystorePassword`	A password to use for the certificate private key.

Create node certificate response

The response will include details on the new node, most importantly its new unique ID. This ID can then be used to download the node's certificate using the certificate download method.

An example response looks like this:

{
"success": true,
"data": {
"created": "2019-02-27 18:34:16.550Z",
"requiresAuthorization": false,
"user": {
"id": 147,
"created": "2016-07-21 02:42:52.673Z",
"name": "Matt",
"email": "example@localhost",
"enabled": true,
"locationId": 11536819
},
"node": {
"id": 177,
"created": "2015-05-06 02:22:09.866Z",
"locationId": 11532079,
"timeZone": "Pacific/Auckland"
},
"certificate": {
"created": "2019-02-27 18:34:16.913Z",
"status": "v",
"requestId": "1a61eeda1a4ae637234adc0774904766",
"nodeId": 177,
"userId": 147
},
"userId": 147,
"nodeLocation": {
"id": 11532079,
"created": "2013-05-29 22:41:15.266Z",
"country": "NZ",
"timeZoneId": "Pacific/Auckland"
},
"idAndName": "177"
}
}

Node certificate download

This method will return a PKCS#12 keystore with a node's private key and signed certificate. The keystore is encrypted with the certificate password used when the node was created. SolarNetwork does not retain this password, so it is up to users/client applications to provide it when needed.

GET	`/solaruser/api/v1/sec/nodes/cert/{nodeId}`
`nodeId`	The ID of the node to download the certificate of.

The response will include a Content-Disposition header with a suggested filename for the keystore, for example:

attachment; filename=solarnode-177.p12

Node certificate view

View a node certificate.

POST	`/solaruser/api/v1/sec/nodes/cert/{nodeId}`
`nodeId`	The ID of the node to view the certificate for.
`password`	The certificate password.

☝️ Note the POST method is used so the password can be provided in the request body, not the URL.

Node certificate view response

The response contains details about the node certificate, and the PEM-encoded certificate chain.

Property	Type	Description
`userId`	number	The account owner ID.
`nodeId`	number	The node ID.
`created`	string	The event date, in `yyyy-MM-dd HH:mm:ss.SSS'Z'` format in the UTC time zone.
`requestId`	string	The certificate request ID.
`certificateSubjectDN`	string	The certificate subject distinguished name.
`certificateIssuerDN`	string	The certificate issuer distinguished name.
`certificateSerialNumber`	string	The certificate serial number.
`certificateValidFromDate`	string	The certificate validity starting date, in `yyyy-MM-dd HH:mm:ss.SSS'Z'` format in the UTC time zone.
`certificateValidUntilDate`	string	The certificate validity expiration date, in `yyyy-MM-dd HH:mm:ss.SSS'Z'` format in the UTC time zone.
`certificateRenewAfterDate`	string	The date after which the certificate can be renewed, in `yyyy-MM-dd HH:mm:ss.SSS'Z'` format in the UTC time zone.
`pemValue`	string	The PEM-encoded certificate chain.

For example:

{
"userId": 123,
"nodeId": 1,
"created": "2019-05-02 23:24:28.176Z",
"requestId": "9",
"certificateSubjectDN": "UID=1,O=SolarNetwork",
"certificateIssuerDN": "CN=SolarNetwork Root CA,OU=SolarNetwork Certification Authority,O=SolarNetwork",
"certificateSerialNumber": "0x40",
"certificateValidFromDate": "2019-05-02 23:25:28Z",
"certificateValidUntilDate": "2029-04-29 23:25:28Z",
"certificateRenewAfterDate": "2028-10-29 23:25:28Z",
"pemValue": "-----BEGIN CERTIFICATE CHAIN-----...\n-----END CERTIFICATE CHAIN-----\n"
}

Node certificate renew

This method will renew a node certificate and then issue a RenewCertificate instruction for the node to download and install the renewed certificate.

POST	`/solaruser/api/v1/sec/nodes/cert/renew/{nodeId}`
`nodeId`	The ID of the node to renew the certificate for.
`password`	The certificate password.

⚠️Note the certificate can only be renewed after the certificateRenewAfterDate as shown in the Node certificate view response, which will be before the certificate's expiration date.

The response will be a certificate details object, as detailed in the Node certificate view response section.

Datum auxiliary list

This method returns datum auxiliary records. Datum auxiliary records represent special events that occur at a specific point in time for a specific node and datum source.

This method supports paged query parameters.

GET	`/solaruser/api/v1/sec/datum/auxiliary`
`localStartDate`	An inclusive starting date to use in the query, in `YYYY-MM-dd` or `YYYY-MM-dd HH:mm:ss.SSS'Z'` patterns. The date will be interpreted in the time zone of the node associated with each datum. The `Z` suffix is optional, and the space between the date and time may be specified as `T`.
`localEndDate`	An exclusive ending date to use in the query, in `YYYY-MM-dd` or `YYYY-MM-dd HH:mm:ss.SSS'Z'` patterns. The date will be interpreted in the time zone of the node associated with each datum. The `Z` suffix is optional, and the space between the date and time may be specified as `T`.
`startDate`	An inclusive starting date to use in the query, in a `yyyy-MM-dd HH:mm:ss.SSS'Z'` pattern in the UTC time zone. The `Z` suffix is optional, and the space between the date and time may be specified as `T`.
`endDate`	An exclusive ending date to use in the query, in a `yyyy-MM-dd HH:mm:ss.SSS'Z'` pattern in the UTC time zone. The `Z` suffix is optional, and the space between the date and time may be specified as `T`.
`metadataFilter`	An optionalmetadata filter to limit the results to.
`nodeId`	The ID of a single node.
`nodeIds`	A comma-delimited list of node IDs. This parameter may be also provided multiple times.
`sourceId`	The ID of a single source to restrict the results to. A wildcard pattern can be used to restrict the results to only source IDs that match the pattern.
`sourceIds`	A comma-delimited list of source IDs to restrict the results to. This parameter may also be provided multiple times.
`withoutTotalResultsCount`	If `true` then the results will not contain a `totalResults` value. This allows the query to execute faster. When iterating over the result data pages, you then iterate until less than the requested page size is returned.

Datum auxiliary list queries support the following sort query parameter keys:

created
node
source
updated

Datum auxiliary list response

The response contains a paged results object with the following properties returned for each result datum auxiliary object:

Property	Type	Description
`created`	string	The event date, in `yyyy-MM-dd HH:mm:ss.SSS'Z'` format in the UTC time zone.
`nodeId`	number	The node ID.
`sourceId`	string	The source ID.
`type`	string	The datum auxiliary type.
`localDate`	string	The creation date of the record, in a `YYYY-MM-dd` pattern in the node's local time zone.
`localTime`	string	The creation time of the record, in a `HH:mm` pattern in the node's local time zone.
`updated`	string	The record last modified date, in `yyyy-MM-dd HH:mm:ss.SSS'Z'` format in the UTC time zone.
`notes`	string	A comment to include that describes the event record.
`final`	object	A general datum sample representing the final data associated with the datum immediately before the `created` date.
`start`	object	A general datum sample representing the starting data associated with the datum at the `created` date.
`meta`	object	A metadata object for client application use.

Note that the final general datum sample will be augmented with two tags: final and the record's type value. Similarly the start general datum sample will be augmented with two tags: start and the record's type value.

An example response object looks like this:

{
"success": true,
"data": {
"totalResults": 1,
"startingOffset": 0,
"returnedResultCount": 1,
"results": [
{
"created": "2019-02-06 18:37:28.244Z",
"nodeId": 11,
"sourceId": "Foo",
"type": "Reset",
"localDate": "2019-02-07",
"localTime": "07:37",
"updated": "2019-02-06 18:37:28.437Z",
"notes": "Meter replaced.",
"final": {
"a": {
"wattHours": 12345
},
"t": [
"final",
"Reset"
]
},
"start": {
"a": {
"wattHours": 123
},
"t": [
"start",
"Reset"
]
},
"meta": {
"m": {
"foo": "bar"
}
}
}
]
}
}

Datum auxiliary store

This method adds or updates datum auxiliary records. Datum auxiliary records represent special events that occur at a specific point in time for a specific node and datum source.

POST	`/solaruser/api/v1/sec/datum/auxiliary`

This method accepts a JSON encoded datum auxiliary record object as the request content. It returns a simple success flag.

All datum auxiliary properties are mandatory except for notes. The type, nodeId, created, and sourceId properties uniquely identify the record, and any existing record based on those primary key values will be updated with the values provided on the request.

Note that the created property may be specified as a millisecond epoch value or using a yyyy-MM-dd HH:mm:ss.SSS'Z' pattern in the UTC time zone, where the final Z may be omitted.

⚠️Note that Reset auxiliary records should not be created on the exact dates of actual datum records, otherwise unexpected difference calculations can occur. This type of auxiliary record should be created between the two datum records where the discontinuity of the accumulating values occurs.

Datum auxiliary move

This method moves a record from one primary key to another, updating the other properties at the same time.

POST	`/solaruser/api/v1/sec/datum/auxiliary/move`
`from`	Datum auxiliary primary key object to move, with `created`, `nodeId`, `sourceId`, and `type` properties.
`to`	A full datum auxiliary record, including the new primary key properties.

This method accepts a JSON encoded object with from and to objects representing the existing primary key to move and the new primary key and data to store.

Note that the created properties in the from and to objects must be specified as millisecond epoch values.

An example request body looks like this:

{
"from": {
"created": 1393657200000,
"nodeId": "11",
"sourceId": "Main",
"type": "Reset"
},
"to": {
"created": 1551310811948,
"nodeId": "11",
"sourceId": "Foo",
"type": "Reset",
"final": {
"a": {
"wattHours": 12345
}
},
"start": {
"a": {
"wattHours": "123"
}
}
}
}

The method returns a boolean true if a matching record was found and updated, or false if the from key was not found. An example response looks like:

{
"success": true,
"data": true
}

Datum auxiliary view

This method retrieves a single datum auxiliary records based on its primary key components.

GET	`/solaruser/api/v1/sec/datum/auxiliary/{type}/{nodeId}/{date}/{sourceId}`
`type`	The datum auxiliary type.
`nodeId`	The node ID.
`date`	The event date, in `yyyy-MM-dd HH:mm:ss.SSS'Z'` or `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'` format in the UTC time zone. The literal `Z` suffix is optional.
`sourceId`	The source ID.

This method can also be called using query parameters instead of path variables, for example /datum/auxiliary?type={type}&nodeId={nodeId}&date={date}&sourceId={sourceId}. Calling this method using request parameters is required if {sourceId} has any / characters in it.

Note that the final general datum sample will be augmented with two tags: final and the record's type value. Similarly the start general datum sample will be augmented with two tags: start and the record's type value.

An example response object looks like this:

{
"success": true,
"data": {
"created": "2019-02-06 18:35:50.943Z",
"nodeId": 11,
"sourceId": "Foo",
"type": "Reset",
"updated": "2019-02-06 18:35:51.165Z",
"final": {
"a": {
"wattHours": 12345
},
"t": [
"final",
"Reset"
]
},
"start": {
"a": {
"wattHours": 123
},
"t": [
"start",
"Reset"
]
}
}
}

Datum auxiliary delete

DELETE	`/solaruser/api/v1/sec/datum/auxiliary/{type}/{nodeId}/{date}/{sourceId}`
`type`	The datum auxiliary type.
`nodeId`	The node ID.
`date`	The event date, in `yyyy-MM-dd HH:mm:ss.SSS'Z'` or `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'` format in the UTC time zone. The literal `Z` suffix is optional.
`sourceId`	The source ID.

This method can also be called using query parameters instead of path variables, for example /datum/auxiliary?type={type}&nodeId={nodeId}&date={date}&sourceId={sourceId}. Calling this method using request parameters is required if {sourceId} has any / characters in it.

Datum maintenance aggregates stale list

This method returns stale aggregate datum records. These records represent "stale" aggregate datum periods. SolarNetwork automatically re-computes the aggregates represented by these records.

GET	`/solaruser/api/v1/sec/datum/maint/agg/stale`
`endDate`	An exclusive ending date to use in the criteria, in `YYYY-MM-dd` or `YYYY-MM-ddTHH:mm` patterns. The date must be provided in the UTC time zone.
`nodeId`	The ID of a single node to use in the criteria.
`nodeIds`	A comma-delimited list of node IDs to use in the criteria. This parameter may be also provided multiple times.
`sourceId`	The ID of a single source to use in the criteria. A wildcard pattern can be used to restrict the results to only source IDs that match the pattern.
`sourceIds`	A comma-delimited list of source IDs to use in the criteria. This parameter may also be provided multiple times.
`startDate`	An inclusive starting date to use in the criteria, in `YYYY-MM-dd` or `YYYY-MM-ddTHH:mm` patterns. The date must be provided in the UTC time zone.
`type`	The type of stale aggregate. One of `h`, `d`, or `m`, representing hour, day, and month aggregation levels.

A node ID parameter must all be provided at a minimum. This method supports paged query parameters. This method support the following sort query parameter keys:

created - the stale datum creation date
kind - the stale aggregation kind: one of h, d, or m, representing hour, day, and month aggregation levels
node
source
start - the stale datum aggregation date

The default sort order is kind, node, source, start all in ascending order.

Datum maintenance aggregates stale list response

The response contains a paged results object with the following properties returned for each result stale datum:

Property	Type	Description
`created`	string	The stale datum creation date, in `yyyy-MM-dd HH:mm:ss.SSS'Z'` format in the UTC time zone.
`kind`	string	The aggregation kind: one of `h`, `d`, or `m`, representing hour, day, and month aggregation levels.
`nodeId`	number	The node ID.
`sourceId`	string	The source ID.
`startDate`	string	The stale datum date, in `yyyy-MM-dd HH:mm:ss.SSS'Z'` format in the UTC time zone. This is the starting date of the period represented by `kind`. The period has an implicit end date of `startDate + kind`.

An example response looks like this:

{
"success": true,
"data": {
"totalResults": 2,
"startingOffset": 0,
"returnedResultCount": 2,
"results": [
{
"nodeId": 11,
"sourceId": "Main",
"startDate": "2019-04-10 12:00:00.000Z",
"kind": "d",
"created": "2019-04-11 02:46:15.176Z"
},
{
"nodeId": 11,
"sourceId": "Main",
"startDate": "2019-03-31 11:00:00.000Z",
"kind": "m",
"created": "2019-04-11 02:45:30.580Z"
}
]
}
}

Datum maintenance aggregates stale mark

This method will cause a range of aggregate datum data to be re-computed. Normally calling this method is not necessary, as SolarNetwork keeps aggregate datum data up-to-date automatically. In rare situations the aggregate data might become out-of-sync with the raw datum data. If that happens, this method should be used to cause the aggregate data to be re-computed.

POST	`/solaruser/api/v1/sec/datum/maint/agg/stale`
`localStartDate`	An inclusive starting date to use in the query, in `YYYY-MM-dd` or `YYYY-MM-ddTHH:mm` patterns. The date will be interpreted in the time zone of the node associated with each datum.
`localEndDate`	An exclusive ending date to use in the query, in `YYYY-MM-dd` or `YYYY-MM-ddTHH:mm` patterns. The date will be interpreted in the time zone of the node associated with each datum.
`endDate`	An exclusive ending date to use in the criteria, in `YYYY-MM-dd` or `YYYY-MM-ddTHH:mm` patterns. The date must be provided in the UTC time zone.
`startDate`	An inclusive starting date to use in the criteria, in `YYYY-MM-dd` or `YYYY-MM-ddTHH:mm` patterns. The date must be provided in the UTC time zone.
`nodeId`	The ID of a single node to use in the criteria.
`nodeIds`	A comma-delimited list of node IDs to use in the criteria. This parameter may be also provided multiple times.
`sourceId`	The ID of a single source to use in the criteria. A wildcard pattern can be used to restrict the results to only source IDs that match the pattern.
`sourceIds`	A comma-delimited list of source IDs to use in the criteria. This parameter may also be provided multiple times.

The node, source, and date range parameters must all be provided. Once invoked, SolarNetwork will re-compute the aggregate data matching the criteria at some point in the future. The amount of time it takes to completely re-compute the aggregate data depends on the amount of data matching the given criteria. Generally speaking, the larger the date range or more node/source IDs provided, the longer it will take.

Datum metadata

Datum metadata is metadata associated with a datum stream.

Datum metadata add

This endpoint allows updating existing node datum metadata by adding new values (or replacing existing values). The request body should be a metadata document with values you want to merge into any existing values. If no metadata exists, it will be created.

POST	`/solaruser/api/v1/sec/datum/meta/{nodeId}/{sourceId}`
`nodeId`	The node ID to update metadata for.
`sourceId`	The source ID to update metadata for. The source ID may alternatively be specified as a query parameter, e.g. `datum/meta/123?sourceId=Foo`.

Datum metadata store

This endpoint allows storing complete node datum metadata documents, replacing any existing metadata for the given node and source ID. The request body should be the complete metadata document to store.

PUT	`/solaruser/api/v1/sec/datum/meta/{nodeId}/{sourceId}`
`nodeId`	The node ID to store metadata for.
`sourceId`	The source ID to store metadata for. The source ID may alternatively be specified as a query parameter, e.g. `datum/meta/123?sourceId=Foo`.

Datum metadata delete

This endpoint allows deleting entire node datum metadata documents.

DELETE	`/solaruser/api/v1/sec/datum/meta/{nodeId}/{sourceId}`
`nodeId`	The node ID to delete metadata for.
`sourceId`	The source ID to delete metadata for. The source ID may alternatively be specified as a query parameter, e.g. `datum/meta/123?sourceId=Foo`.

Datum stream metadata view

Use this method to view a specific datum stream metadata.

GET	`/solaruser/api/v1/sec/datum/stream/meta/node/{streamId}`
`streamId`	The ID of the stream to view. Can be provided as a path parameter or a request parameter.

Datum stream metadata view response

The response is a datum stream metadata object, with the following properties:

Property	Type	Description
`streamId`	string	The stream ID.
`zone`	string	The stream's time zone ID.
`kind`	string	The type of datum stream, `n` for node or `l` for location.
`objectId`	number	The node ID.
`sourceId`	string	The source ID.
`i`	string[]	The instantaneous property names.
`a`	string[]	The accumulating property names.
`s`	string[]	The status property names.

An example response looks like this:

{
"success": true,
"data": {
"streamId": "5add151c-9bc5-4b18-951f-24d49a2e90bd",
"zone": "Pacific/Auckland",
"kind": "n",
"objectId": 123,
"sourceId": "/foo/bar",
"i": ["current","voltage","watts"],
"a": ["wattHours"],
"s": ["status"]
}
}

Datum stream metadata update IDs

Use this method to change the node ID or source ID in a given datum stream metadata. You can update both IDs (node and source) at once, or just one of the IDs by omitting the other, in which case the omitted ID will remain unchanged.

PATCH	`/solaruser/api/v1/sec/datum/stream/meta/node/{streamId}`
`streamId`	The ID of the stream to update. Can be provided as a path parameter or a request parameter.
`nodeId`	The new node ID to associate with the stream. Omit to leave the node ID unchanged.
`sourceId`	The new source ID to associate with the stream. Omit to leave the source ID unchanged.

Datum stream metadata update IDs response

The response is a datum stream metadata ID object, with the following properties:

Property	Type	Description
`streamId`	string	The stream ID.
`kind`	string	The type of stream, `n` for node or `l` for location.
`objectId`	number	The updated (or unchanged) node ID.
`sourceId`	string	The updated (or unchanged) source ID.

An example response looks like this:

{
"success": true,
"data": {
"streamId": "5add151c-9bc5-4b18-951f-24d49a2e90bd",
"kind": "n",
"objectId": 123,
"sourceId": "/foo/bar",
}
}

Datum stream metadata update

Use this method to change the node or source ID, or the instantaneous, accumulating, or status property names in a given datum stream metadata. You can update all values at once, or omit any value to keep it unchanged from its current value.

⚠️Note that the given i, a, and s lists must have at least as many elements as exists in the datum stream metadata. Put another way, you can rename, or add new, property names, but you can not remove property names. You can omit any of these parameter to leave the associated property names unchanged.

This method returns the updated datum stream metadata, or an empty result if the metadata could not be updated, for example if a given i, a, or s list has too few elements.

POST	`/solaruser/api/v1/sec/datum/stream/meta/node/{streamId}`
`streamId`	The ID of the stream to update. Can be provided as a path parameter or a request parameter.
`nodeId`	The new node ID to associate with the stream. Omit to leave the node ID unchanged.
`sourceId`	The new source ID to associate with the stream. Omit to leave the source ID unchanged.
`i`	A comma-delimited list of instantaneous property names.
`a`	A comma-delimited list of accumulating property names.
`s`	A comma-delimited list of status property names.

Datum stream metadata update response

The response is a datum stream metadata object. See the view response section for more details.

Location datum metadata

Location datum metadata is metadata associated with a location datum stream.

Location datum metadata add

This endpoint allows updating existing location datum metadata by adding new values (or replacing existing values). The request body should be a metadata document with values you want to merge into any existing values. If no metadata exists, it will be created.

POST	`/solaruser/api/v1/sec/location/datum/meta/{nodeId}/{sourceId}`
`locationId`	The location ID to update metadata for.
`sourceId`	The source ID to update metadata for. The source ID may alternatively be specified as a query parameter, e.g. `datum/meta/123?sourceId=Foo`.

Location datum metadata store

This endpoint allows storing complete node datum metadata documents, replacing any existing metadata for the given node and source ID. The request body should be the complete metadata document to store.

PUT	`/solaruser/api/v1/sec/location/datum/meta/{nodeId}/{sourceId}`
`locationId`	The location ID to store metadata for.
`sourceId`	The source ID to store metadata for. The source ID may alternatively be specified as a query parameter, e.g. `datum/meta/123?sourceId=Foo`.

Location datum metadata delete

This endpoint allows deleting entire node datum metadata documents.

DELETE	`/solaruser/api/v1/sec/location/datum/meta/{nodeId}/{sourceId}`
`locationId`	The location ID to delete metadata for.
`sourceId`	The source ID to delete metadata for. The source ID may alternatively be specified as a query parameter, e.g. `datum/meta/123?sourceId=Foo`.

Node list

This method will return a list of all the SolarNode IDs associated with the account.

This method supports paged query parameters.

Note this endpoint is similar to the SolarQuery /nodes endpoint, but requires a user security token.

💡 See the /nodes/find endpoint for an alternative API that also accepts filter criteria.

GET	`/solaruser/api/v1/sec/nodes`

Node list response

The response contains a paged results object of SolarNode objects with the following properties returned for each node:

Property	Type	Description
`created`	string	The node creation date, in `yyyy-MM-dd HH:mm:ss.SSS'Z'` format in the UTC time zone.
`name`	string	The name assigned to the node.
`description`	string	The description assigned to the node.
`id`	number	The unique ID assigned to the node.
`idAndName`	string	A formatted string comprised of the node ID and name. Always provided, even if a name has not been assigned.
`node`	object	An object with more details about the node.
`node.locationId`	number	The ID of the location assigned to the node.
`node.timeZone`	string	The time zone assigned to the node, e.g. `Pacific/Auckland`.
`nodeLocation`	object	An object with more details about the node's assigned location.
`requiresAuthorization`	boolean	`true` if the node is configured as private, requiring a token to access its data.
`user`	object	An object with details on the user account that owns the node.

An example response looks like:

{
"success": true,
"data": {
"results": [
{
"created": "2015-02-26 21:00:00.000Z",
"description": "Example SolarNode",
"id": 123,
"idAndName": "160 - Home",
"name": "Home",
"node": {
"created": "2015-02-26 21:00:00.000Z",
"id": 160,
"locationId": 11532079,
"timeZone": "Pacific/Auckland"
},
"nodeLocation": {
"country": "NZ",
"created": "2013-05-29 22:00:00.000Z",
"id": 11532079,
"timeZoneId": "Pacific/Auckland"
},
"requiresAuthorization": false,
"user": {
"created": "2015-06-09 02:00:00.000Z",
"email": "owner@localhost",
"enabled": true,
"id": 234,
"name": "Example Owner"
}
}
],
"returnedResultCount": 1,
"startingOffset": 0,
"totalResults": 1
}
}

Node find

This method will return a list of the SolarNode information records matching filter criteria.

This method supports paged query parameters.

GET	`/solaruser/api/v1/sec/nodes/find`
`locationId`	The ID of a single node location to match.
`locationIds`	A comma-delimited list of node location IDs to match. Matches using a logical OR.
`location.country`	A node location's country code to match, for example `NZ` or `US`.
`location.timeZoneId`	A node location's time zone ID to match, for example `Pacific/Auckland` or `UTC`.
`name`	A case-insensitive name substring to match. Also matches against the description.
`names`	A comma-delimited list of case-insensitive name substrings to match. Also matches against the description. Matches using a logical OR.
`nodeId`	The ID of a single node to match.
`nodeIds`	A comma-delimited list of node IDs to match. Matches using a logical OR.
`orderBy`	A comma-delimited list of sort order keys. See below for the supported values.

Node find sorting

Node find queries support the following orderBy query parameter keys that affect the sort order of the results:

created - node creation date
name - node name
node - node ID
zone - time zone ID (the text, not the offset from UTC)

The default sort order, if none provided, is node.

Node find response

The response contains a paged results object of SolarNode objects with the following properties returned for each node:

Property	Type	Description
`country`	string	The node location's country code.
`created`	string	The node creation date, in `yyyy-MM-dd HH:mm:ss.SSS'Z'` format in the UTC time zone.
`description`	string	The description assigned to the node, if available.
`idAndName`	string	A formatted string comprised of the node ID and name. Always provided, even if a name has not been assigned.
`name`	string	The name assigned to the node, if available.
`nodeId`	number	The unique ID assigned to the node.
`locationId`	number	The ID of the location assigned to the node.
`requiresAuthorization`	boolean	`true` if the node is configured as private, requiring a token to access its data.
`timeZone`	string	The node location's time zone ID, e.g. `Pacific/Auckland`.
`userId`	number	The ID of the SolarNetwork account that owns the node.

An example response looks like:

{
"success": true,
"data": {
"startingOffset": 0,
"returnedResultCount": 2,
"results": [
{
"userId": 1,
"nodeId": 10,
"name": "New York site",
"idAndName": "10 - New York site",
"description": "1MW solar farm.",
"locationId": 1000,
"country": "US",
"timeZone": "America/New_York",
"requiresAuthorization": true,
"created": "2025-08-05 22:10:13Z"
},
{
"userId": 1,
"nodeId": 14,
"idAndName": "14",
"locationId": 11532079,
"country": "NZ",
"timeZone": "Pacific/Auckland",
"requiresAuthorization": false,
"created": "2025-11-13 17:39:18Z"
}
]
}
}

Node archived list

This method lists all archived nodes for the active account.

GET	`/solaruser/api/v1/sec/nodes/archived`

Node archived list response

The response is the same as in Node list.

Node archived update

This method can update the archived status of a set of nodes.

POST	`/solaruser/api/v1/sec/nodes/archived`
`nodeIds`	Comma-delimited list of node IDs to change the archived status of.
`archived`	`true` to archive or `false` to un-archive.

Node archived list response

The response data will be empty.

Queue instruction

This method queues an instruction for a SolarNode to execute at some point in the future. Node instructions have a topic and an optional set of parameters. See Node instruction topics for a list of standard instruction topics and the parameters they accept.

Instructions are executed in an asynchronous fashion (see the /instr/exec method to synchronously wait for the instruction to complete). After an instruction has been submitted via this endpoint, the state of the instruction will change over time as the node specified in the instruction receives and processes the instruction. See the Node instruction state type documentation for possible state types. In general an instruction's state will transition like this:

Queuing
Queued
Received
Executing
Completed

A node might also post a set of result parameters after executing the instruction. See the View instruction endpoint for more information.

This endpoint can handle either application/x-www-form-urlencoded or application/json content, but their syntax is slightly different. For application/x-www-form-urlencoded the parameters are:

POST	`/solaruser/api/v1/sec/instr/add/{topic}`
`topic`	The instruction to enqueue. This can be provided via a path parameter or as a query parameter. See the Node instruction topics for more information.
`nodeId`	The ID of a single node to pass the instruction to.
`nodeIds`	A comma-delimited list of node IDs to pass the instruction do. This takes precedence over the `nodeId` parameter. This parameter may be also provided multiple times. Note that there will be one instruction queued for each ID provided.
`expirationDate`	An optional date after which the instruction can be automatically transitioned to the `Declined` state if it has not already reached the `Completed` or `Declined` state. The date format is `yyyy-MM-dd HH:mm:ss` in the UTC time zone.
`parameters[].name`	An indexed instruction parameter name, which is paired with a `parameters[].value` with the same index. Indices start at `0` and any number of `name` + `value` pairs may be included. For example the first parameter name would be written as `parameters[0].name`.
`parameters[].value`	An indexed instruction parameter value, which must be paired with a `parameters[].name` with the same index. For example the first parameter value would be written as `parameters[0].value`.

For application/json the request must be a JSON object with the following properties:

POST	`/solaruser/api/v1/sec/instr/add/{topic}`
`topic`	The instruction to enqueue. This can be provided via a path parameter or as a propery. See the Node instruction topics for more information.
`nodeId`	The `Number` ID of a single node to pass the instruction to.
`expirationDate`	An optional date after which the instruction can be automatically transitioned to the `Declined` state if it has not already reached the `Completed` or `Declined` state. The date format is `yyyy-MM-dd HH:mm:ss` in the UTC time zone.
`parameters`	A JSON `Array` of parameter objects. Must not be mixed with the `params` JSON object property.
`parameters.name`	The `String` parameter name.
`parameters.value`	The `String` parameter value.
`params`	A JSON object of parameter key/value `String` pairs. Must not be mixed with the `parameters` JSON array property.

For example, to enqueue a SetControlParameter instruction for node 123 to set the value of control /switch/1 to 1:

/solaruser/api/v1/sec/instr/add?nodeId=123&topic=SetControlParameter&parameters%5B0%5D.name=/switch/1&parameters%5B0%5D.value=1

Or, as JSON:

{"nodeId":123, "topic":"SetControlParameter","params":{"/switch/1":"1"}}

To enqueue an UpdatePlatform instruction for nodes 123 and 234 to update to platform version 000009:

/solaruser/api/v1/sec/instr/add?nodeIds=123,234&topic=UpdatePlatform&parameters%5B0%5D.name=Version&parameters%5B0%5D.value=000009

Note that the JSON form cannot be used when nodeIds is specified (it can only be used for a single nodeId value).

Here's an example of setting a single setting value, as JSON:

{"nodeId":123, "topic":"UpdateSetting","params":{
"key":"placeholder",
"type":"me",
"value":"booyah"
}}

Here's an example of setting multiple setting values, as JSON:

{"nodeId":123, "topic":"UpdateSetting","parameters":[
{"name":"key","value":"placeholder"},
{"name":"type","value":"me"},
{"name":"value","value":"RockinIt"},
{"name":"key","value":"placeholder"},
{"name":"type","value":"you"},
{"name":"value","value":"AwesomeSauce"}
]}

Expiring instruction

An instruction can be configured to auto-expire by providing the expirationDate property. The value of this property must be either:

a Unix millisecond epoch integer, for example 1680030000000
a UTC instant string formatted as yyyy-MM-dd HH:mm:ss, for example 2023-03-28 19:00:00
an ISO 8601 instant, for example 2023-03-28T19:00:00Z

If an instruction has not transitioned to the Completed or Declined state by the given expiration date, it becomes eligible for SolarNetwork to transition the state to Declined automatically. Typically this transition will occur within about a minute of the expiration date. When SolarNetwork does transition an expired instruction, it will also add a message result parameter with a value of Expired.

Deferred instruction

An instruction's execution can be deferred to a specific (future) date by providing an executionDate parameter. The value of this parameter must be either:

a Unix millisecond epoch integer, for example 1680030000000
an ISO 8601 instant, for example 2023-03-28T19:00:00Z

Here's an example of setting a control parameter with a specific execution date:

{"nodeId":123, "topic":"SetControlParameter","params":{
"/switch/1": "1",
"executionDate": "2023-03-28T19:00:00Z"
}}

SolarNode will accept deferred instructions, save them internally in the Received state, and then execute them at the given date.

Deferred instruction notes

There are a few important things to note about deferred instructions:

SolarNode must be online and receiving instructions from SolarNetwork.
SolarNode's job execution time precision is configurable, and by default has 10 second resolution. That means a deferred job could execute up to 10 seconds later than the specified date.
The execution date relies on the clock of the system SolarNode is running on; an inaccurate system clock will result in unexpected deferred instruction execution times.

Cancelling a deferred instruction

If an instruction is in the Queued state, that means SolarNode has not yet received the instruction. It can be cancelled by changing its state to Declined with the /instr/updateState API.

If an instruction is in the Received state, that means SolarNode has received and saved the instruction. A new CancelInstruction instruction can be issued to the same node to cancel such an instruction. For example:

{"nodeId":123, "topic":"CancelInstruction","params":{
"id": "12345"
}}

Queue instruction response

The response contains either a single instruction object—as detailed in View instruction response object—if the nodeId request parameter is used, or an array of instruction objects if the nodeIds request parameter is used.

For example, when the nodeId request parameter is used:

{
"success": true,
"data": {
"id": 4316548,
"created": "2015-02-26 21:00:00.000Z",
"topic": "SetControlParameter",
"instructionDate": "2015-02-26 21:00:00.000Z",
"state": "Queued",
"statusDate": "2015-02-26 21:00:00.000Z",
"expirationDate": "2015-02-26 21:05:00Z",
"parameters": [
{
"name": "/switch/1",
"value": "1"
}
],
"nodeId": 123
}
}

When the nodeIds request parameter is used:

{
"success": true,
"data": [
{
"id": 11537126,
"created": "2017-10-30 01:08:10.052Z",
"topic": "SetControlParameter",
"instructionDate": "2017-10-30 01:08:10.051Z",
"state": "Queued",
"statusDate": "2017-10-30 01:08:10.051Z",
"parameters": [
{
"name": "/switch/1",
"value": "1"
}
],
"nodeId": 123
},
{
"id": 11537127,
"created": "2017-10-30 01:08:10.101Z",
"topic": "SetControlParameter",
"instructionDate": "2017-10-30 01:08:10.101Z",
"state": "Queued",
"statusDate": "2017-10-30 01:08:10.101Z",
"parameters": [
{
"name": "/switch/1",
"value": "1"
}
],
"nodeId": 234
}
]
}

Execute instruction

This method is similar to /instr/add, however SolarNetwork will wait for the instructions to complete before returning the response. An instruction is considered complete when its state changes to either Completed or Declined. This method provides a way for a client to synchronously execute an instruction and receive the result.

The resultMaxWait query parameter can be provided to specify the maximum number of milliseconds to wait for the results, before giving up and returning the queued instruction information the same way /instr/add would.

POST	`/solaruser/api/v1/sec/instr/exec/{topic}`
`topic`	The instruction to execute. This can be provided via a path parameter or as a query parameter. See the Node instruction topics for more information.
`nodeId`	The ID of a single node to pass the instruction to.
`nodeIds`	A comma-delimited list of node IDs to pass the instruction do. This takes precedence over the `nodeId` parameter. This parameter may be also provided multiple times. Note that there will be one instruction queued for each ID provided.
`parameters[].name`	An indexed instruction parameter name, which is paired with a `parameters[].value` with the same index. Indices start at `0` and any number of `name` + `value` pairs may be included. For example the first parameter name would be written as `parameters[0].name`.
`parameters[].value`	An indexed instruction parameter value, which must be paired with a `parameters[].name` with the same index. For example the first parameter value would be written as `parameters[0].value`.
`resultMaxWait`	An optional maximum number of milliseconds to wait for the instruction(s) to complete before giving up. The maximum allowed is 60000. Defaults to 60000.

💡 Note that the request may also be provided as a JSON body. See /instr/add for more details.

List instructions

List instructions that match a search filter. At least one node ID parameter must be provided.

GET	`/solaruser/api/v1/sec/instr`
`endDate`	An exclusive ending date to use in the query, in `YYYY-MM-dd` or `YYYY-MM-ddTHH:mm` patterns. The date must be provided in the UTC time zone.
`instructionIds`	A comma-delimited list of instruction IDs to view.
`nodeId`	An ID of the node to view the instructions for.
`nodeIds`	A comma-delimited list of node IDs to view the instructions for. This takes precedence over the `nodeId` parameter.
`startDate`	An inclusive starting date to use in the query, in `YYYY-MM-dd` or `YYYY-MM-ddTHH:mm` patterns. The date must be provided in the UTC time zone.
`state`	A single instruction state to match.
`states`	A comma-delimited list of instruction states to match (instructions with any matching state will be returned). This takes precedence over the `state` parameter.

List instructions response

The response contains an array of instruction objects, as detailed in View instruction.

For example:

{
"success": true,
"data": [
{
"id": 4316529,
"created": "2015-02-26 21:00:00.000Z",
"nodeId": 11,
"topic": "SetControlParameter",
"instructionDate": "2015-02-26 21:00:00.000Z",
"state": "Completed",
"statusDate": "2015-02-26 21:00:00.000Z",
"parameters": [
{
"name": "/power/switch/1",
"value": "1"
}
]
},
{
"id": 4316530,
"created": "2015-02-26 22:00:00.000Z",
"nodeId": 11,
"topic": "SetControlParameter",
"instructionDate": "2015-02-26 22:00:00.000Z",
"state": "Queued",
"statusDate": "2015-02-26 22:00:00.000Z",
"parameters": [
{
"name": "/power/switch/1",
"value": "1"
}
]
}
]
}

View instruction

Obtain details on either a single instruction or list of instructions by their unique IDs.

GET	`/solaruser/api/v1/sec/instr/view`
`id`	The ID of the instruction to view.
`ids`	A comma-delimited list of instruction IDs to view; takes precedence over the `id` parameter.

View instruction response

The response contains either a single instruction object (if the id request parameter is used) or an array of instruction objects (if the ids request parameter is used). Each instruction object contains the following properties:

Property	Type	Description
`id`	number	A unique ID assigned to the instruction.
`created`	string	The date the instruction was created, in `YYYY-MM-dd HH:mm:ss.SSSZ` format in GMT.
`nodeId`	number	The node ID the instruction applies to.
`topic`	string	The requested instruction topic.
`instructionDate`	string	The date of the instruction, in `YYYY-MM-dd HH:mm:ss.SSSZ` format in GMT.
`state`	string	The instruction state value.
`statusDate`	string	The last modification date of the instruction, in `YYYY-MM-dd HH:mm:ss.SSSZ` format in GMT.
`parameters`	array	An array of parameter objects, which all have `name` and `value` string properties.
`resultParameters`	object	Holds parameters reported back by the node that executed the instruction. It is a JSON object with arbitrary string keys and associated values. Two standard keys are `code` to represent an error state and `message` to represent a message, such as an error message.

For example:

{
"success": true,
"code": null,
"message": null,
"data": {
"id": 4316529,
"created": "2015-02-26 21:00:00.000Z",
"nodeId": 11,
"topic": "SetControlParameter",
"instructionDate": "2015-02-26 21:00:00.000Z",
"state": "Declined",
"statusDate": "2015-02-26 21:01:00.000Z",
"parameters": [
{
"name": "/power/switch/1",
"value": "1"
}
],
"resultParameters": {
"code" : "5000",
"message": "Control '/power/switch/1' not available."
}
}
}

View active instructions

Obtain a list of active instructions, that is instructions that are in the Queued state, for one or more nodes.

GET	`/solaruser/api/v1/sec/instr/viewActive`
`nodeId`	The ID of the SolarNode to view the active (queued) instructions for.
`nodeIds`	A comma-delimited list of SolarNode IDs to view the instructions for. This takes precedence over the `nodeId` parameter.

Note that a maximum of 2,000 values will be returned by this method. You can use the /instr/list method with state=Queued to list all available active instructions without this limit.

View active instructions response

The response contains an array of instruction objects, as detailed in View instruction response object.

For example:

{
"success": true,
"data": [
{
"id": 4316529,
"created": "2015-02-26 21:00:00.000Z",
"topic": "SetControlParameter",
"instructionDate": "2015-02-26 21:00:00.000Z",
"state": "Queued",
"statusDate": "2015-02-26 21:00:00.000Z",
"parameters": [
{
"name": "/power/switch/1",
"value": "1"
}
],
"nodeId": 11
},
{
"id": 4316530,
"created": "2015-02-26 22:00:00.000Z",
"topic": "SetControlParameter",
"instructionDate": "2015-02-26 22:00:00.000Z",
"state": "Queued",
"statusDate": "2015-02-26 22:00:00.000Z",
"parameters": [
{
"name": "/power/switch/1",
"value": "1"
}
],
"nodeId": 11
}
]
}

View pending instructions

Obtain a list of pending instructions, that is instructions that are in the Queued, Received, or Executing state, for one or more nodes. See Node instruction state type for an explanation of the state types.

GET	`/solaruser/api/v1/sec/instr/viewPending`
`nodeId`	The ID of the SolarNode to view the pending (unfinished) instructions for.
`nodeIds`	A comma-delimited list of SolarNode IDs to view the instructions for. This takes precedence over the `nodeId` parameter.

Note that a maximum of 2,000 values will be returned by this method. You can use the /instr/list method with states=Queued,Received,Executing to list all available pending instructions without this limit.

View pending instructions response

The response contains an array of instruction objects, similar to the View active instructions example response, with instruction objects detailed in View instruction response object.

Update instruction state

Change the state of one or more instructions. See Node instruction state type for possible state types.

POST	`/solaruser/api/v1/sec/instr/updateState`
`id`	The ID of the instruction to update.
`ids`	A comma-delimited list of instruction IDs to update; takes precedence over the `id` parameter.
`state`	The instruction state to set the instruction(s) to.

Update instruction state response

The response contains no data.

Update instruction state matching criteria

Change the state of instructions that match search criteria. All search criteria are combined with a logical AND. Only the state parameter is required (this is the desired state to update matching instructions to).

POST	`/solaruser/api/v1/sec/instr/updateState`
`endDate`	An optional exclusive ending date to match, in `YYYY-MM-dd` or `YYYY-MM-ddTHH:mm` patterns. The date must be provided in the UTC time zone.
`instructionId`	An optional ID of a single instruction to match.
`instructionIds`	An optional comma-delimited list of instruction IDs to match.
`nodeId`	An optional ID of the node to match.
`nodeIds`	An optional comma-delimited list of node IDs to match.
`startDate`	An optional inclusive starting date to match, in `YYYY-MM-dd` or `YYYY-MM-ddTHH:mm` patterns. The date must be provided in the UTC time zone.
`states`	An optional comma-delimited list of instruction state values to match.
`state`	The requiredinstruction state to set the matching instructions to.

💡 Note that only instructions that match all the search criteria and are not already in the given state will be updated. Put another way: instructions that match the search criteria but are already in the given state will not be updated.

Update instruction state matching criteria response

The response contains a list of instruction IDs that were updated to the given state. For example:

{
"success": true,
"data": [
123456,
456789
]
}

Node metadata

Node metadata is metadata associated with a specific SolarNode. It may be managed using the following endpoints. All returned metadata objects will include nodeId property for the ID of the node the metadata is associated with.

Node metadata list

This method returns node metadata for one or more nodes. This method supports paged query parameters.

GET	`/solaruser/api/v1/{pub,sec}/nodes/meta`
`nodeIds`	A comma-delimited list of node IDs to get metadata for. If not specified, then metadata for all nodes the current request is authorized to access will be returned.
`metadataFilter`	An optionalmetadata filter to limit the results to.

Node metadata list queries support the following sort query parameter keys:

created
node
updated

Node metadata view

This endpoint returns the node metadata for a specific node.

GET	`/solaruser/api/v1/sec/nodes/meta/{nodeId}`
`nodeId`	The node ID to get metadata for.

An example response looks like this:

{
"success": true,
"data": {
"results": [
{
"created": "2017-02-27 04:41:17.510Z",
"updated": "2017-02-27 05:01:32.198Z",
"nodeId": 123,
"m": {
"num": 12
},
"pm": {
"room": {
"foo": "bar"
}
},
"t": [
"green",
"yellow"
],
}
],
"returnedResultCount": 1,
"startingOffset": 0,
"totalResults": 1
},
}

Node metadata add

This endpoint allows updating a node's metadata by adding new values. The request body should be metadata with values you want to merge into any existing values. If no metadata exists, it will be created.

POST	`/solaruser/api/v1/sec/nodes/meta/{nodeId}`

Node metadata store

This endpoint allows replacing complete the metadata for the given node, replacing any existing metadata. The request body should contain the metadata which will be stored.

PUT	`/solaruser/api/v1/sec/nodes/meta/{nodeId}`

Node metadata delete

This endpoint allows deleting all of the metadata for the given node.

DELETE	`/solaruser/api/v1/sec/nodes/meta/{nodeId}`

User metadata

User metadata is metadata associated with a specific SolarNetwork account. It may be managed using the following endpoints. All returned metadata objects will include userId property for the ID of the user the metadata is associated with.

User metadata view

This endpoint returns the user metadata for the active user.

GET	`/solaruser/api/v1/sec/users/meta`

An example response looks like this:

{
"success": true,
"data": {
"results": [
{
"created": "2017-02-27 04:41:17.510Z",
"updated": "2017-02-27 05:01:32.198Z",
"userId": 123,
"m": {
"num": 12
},
"pm": {
"room": {
"foo": "bar"
}
},
"t": [
"green",
"yellow"
],
}
],
"returnedResultCount": 1,
"startingOffset": 0,
"totalResults": 1
},
}

User metadata add

This endpoint allows updating the active user's metadata by adding new values (or replacing existing values). The request body should be a metadata document with values you want to merge into any existing values. If no metadata exists, it will be created.

POST	`/solaruser/api/v1/sec/users/meta`

User metadata store

This endpoint allows storing a complete user metadata document for the active user, replacing any existing metadata for the given node and source ID. The request body should be the complete metadata document to store.

PUT	`/solaruser/api/v1/sec/users/meta`

User metadata delete

This endpoint allows deleting the entire user metadata document for the active user.

DELETE	`/solaruser/api/v1/sec/users/meta`

Authentication check

Check who the caller is. This is a convenient way to verify the credentials of a user, or to discover the ID of the token's account owner.

GET	`/solaruser/api/v1/sec/whoami`

Authentication check response

Property	Type	Description
`token`	string	The security token authorized on the request.
`tokenType`	string	Either `ReadNodeData` or `User`.
`userId`	number	The SolarNetwork account ID that owns the token.

An example response looks like this:

{
"success": true,
"data": {
"token": "abcdefghijklmnop",
"tokenType": "User",
"userId": 123
}
}

Security tokens

The following endpoints support managing account security tokens.

Security token list

This method returns a list of all available security tokens in the current account.

GET	`/solaruser/api/v1/sec/user/auth-tokens`

Security token list response

The response contains a list of security token detail objects. Each object contains the following properties:

Property	Type	Description
`id`	string	The security token ID.
`created`	string	The token creation date, in `yyyy-MM-dd HH:mm:ss.SSS'Z'` format in the UTC time zone.
`userId`	number	The user ID that owns the token.
`name`	string	A friendly name.
`description`	string	A description.
`status`	string	Either `Active` or `Disabled`.
`type`	string	The token type. Either `ReadNodeData` or `User`.
`expired`	boolean	`true` if the token has expired.
`policy`	object	A security policy.

An example response looks like this:

{
"success": true,
"data": [
{
"id": "abcdefghijklmnop0001",
"created": "2017-06-19 03:09:01.716Z",
"userId": 1,
"name": "Test token",
"description": "A token for testing purposes only.",
"status": "Active",
"type": "User",
"expired": false
},
{
"id": "abcdefghijklmnop0002",
"created": "2018-04-15 08:29:51.625Z",
"userId": 1,
"status": "Active",
"type": "ReadNodeData",
"policy": {
"nodeIds": [
123
],
"sourceIds": [
"/power/switch/2",
"/power/switch/3"
],
"nodeMetadataPaths": [
"/pm/**"
],
"userMetadataPaths": [
"/pm/**"
]
},
"expired": false
}
]
}

Security token find

This method returns a list of security tokens in the current account that match search criteria.

GET	`/solaruser/api/v1/sec/user/auth-tokens/find`
`active`	`true` to match tokens with `Active` status, `false` for `Disabled` status
`identifier`	A single token ID to match
`identifiers`	A comma-delimited list of token IDs to match
`tokenType`	A single token type to match: one of `ReadNodeData` or `User`
`tokenTypes`	A comma-delimited list of token types to match

Queries support the following sort query parameter keys:

created
status
type

Security token find response

The response is a paged results object of security token objects. See Security token list for more details.

An example response looks like this:

{
"success": true,
"data": {
"startingOffset": 0,
"returnedResultCount": 1,
"results": [
{
"id": "ABCDEFGHIJgsEwxYXnbx",
"created": "2023-01-19 01:20:00Z",
"userId": 123,
"name": "My Token",
"description": "Token used for stuff",
"status": "Active",
"type": "User",
"policy": {
"apiPaths": [
"/foo/bar"
]
},
"expired": false
}
]
}
}

Security token add

This method generates a new security token.

POST	`/solaruser/api/v1/sec/user/auth-tokens/generate/{type}`
`type`	The token type, either `ReadNodeData` or `User`.

An optional security policy can be provided by including an application/json body with a JSON object.

Security token add response

The response contains a the new security token detail object, including the generated secret value. The secret value will not be returned from any SolarNetwork API after this point, so it should be saved in a safe place. The token object will contain the following properties:

Property	Type	Description
`id`	string	The security token ID.
`authSecret`	string	The security token secret. ⚠️ You must store this in a safe place, it cannot be retrieved after this point.
`created`	string	The token creation date, in `yyyy-MM-dd HH:mm:ss.SSS'Z'` format in the UTC time zone.
`userId`	number	The user ID that owns the token.
`name`	string	A friendly name.
`description`	string	A description.
`status`	string	Either `Active` or `Disabled`.
`type`	string	The token type requested.
`expired`	boolean	Will start off as `false`.

{
"success": true,
"data": {
"id": "abcdefghijklmnop0001",
"created": "2022-03-16 21:04:48.218599Z",
"userId": 147,
"name": "Personal",
"description": "Personal use only.",
"authSecret": "abcdefghijklmnopqrstuvwxyz",
"status": "Active",
"type": "ReadNodeData",
"expired": false
}
}

Security token update info

This method allows you to change the name and description of a specific token.

POST	`/solaruser/api/v1/sec/user/auth-tokens/info`
`tokenId`	The token to update the status for.
`name`	The desired name.
`description`	The desired description.

The response will indicate success, for example:

{
"success": true
}

Security token update status

This method allows you to change the status of a specific token.

POST	`/solaruser/api/v1/sec/user/auth-tokens/status`
`tokenId`	The token to update the status for.
`status`	The desired status, either `Active` or `Disabled`.

The response will indicate success, for example:

{
"success": true
}

Security token delete

This method allows you to change the status of a specific token.

DELETE	`/solaruser/api/v1/sec/user/auth-tokens`
`tokenId`	The token to remove.

The response will indicate success, for example:

{
"success": true
}

Security token policy add

This method allows you to add elements to a token's security policy. The posted policy values are merged into any existing policy. For example, any node IDs in the request policy will be added to any node IDs already in the token's policy. Duplicate values are eliminated so that no duplicates will be saved in the final policy.

PATCH	`/solaruser/api/v1/sec/user/auth-tokens/policy`
`tokenId`	The token to add policy to.

The request body must be a security policy JSON object, for example:

{
"nodeIds": [1, 2, 3],
"sourceIds": ["/foo", "/bar"]
}

The response will be the final token detail object with the final merged policy values. Here are some examples of how the policy values are merged:

Current Policy

Add Request

Final Policy

-

{
"nodeIds": [
1,
2
],
"sourceIds": [
"/foo",
"/bar"
]
}

{
"nodeIds": [
1,
2
],
"sourceIds": [
"/foo",
"/bar"
]
}

{
"nodeIds": [
1
]
}

{
"nodeIds": [
2
],
"sourceIds": [
"/foo/**",
],
"minAggregation": "Hour"
}

{
"nodeIds": [
1,
2
],
"sourceIds": [
"/foo/**",
],
"minAggregation": "Hour"
}

{
"nodeIds": [
1,
2
],
"sourceIds": [
"/foo",
"/bar"
]
}

{
"nodeIds": [
1
],
"minAggregation": "Hour"
}

{
"nodeIds": [
1,
2
],
"sourceIds": [
"/foo",
"/bar"
],
"minAggregation": "Hour"
}

Security token policy store

This method sets a token's security policy, replacing any existing policy with the given policy.

PUT	`/solaruser/api/v1/sec/user/auth-tokens/policy`
`tokenId`	The token to set the policy for.

The request body must be a security policy JSON object, for example:

{
"nodeIds": [1, 2, 3],
"sourceIds": ["/foo", "/bar"]
}

The response will be the final token detail object with the given policy values.

User application events

The SolarNetwork applications log events related to user activities into a stream that you can query.

User app event list

This method returns user application event records for the authenticated user.

This method supports paged query parameters.

GET	`/solaruser/api/v1/sec/user/events`
`startDate`	An inclusive starting date to use in the query, in a `yyyy-MM-dd HH:mm:ss.SSS'Z'` pattern in the UTC time zone.
`endDate`	An exclusive ending date to use in the query, in a `yyyy-MM-dd HH:mm:ss.SSS'Z'` pattern in the UTC time zone.
`searchFilter`	An event data filter, see below for more information. ⚠️Note that the filter must be URI escaped, for example `(foo=bar)` would be escaped as `(foo%3Dbar)`.
`tag`	A single tag.
`tags`	A comma-delimited list of tags. This parameter may be also provided multiple times. Only events that include all the provided tags will be returned.

Note for the startDate and endDate parameters the entire time component is optional. If time is specified, a T delimiter may be used instead of a space character, and the seconds and millisecond values are optional.

The response contains a paged results object of user application event objects. An example response object looks like this:

{
"success": true,
"data": [
{
"userId": 123,
"created": "2022-08-09 03:03:28.533452Z",
"eventId": "0182808e-a615-7712-bd86-80acee3b28cd",
"tags": [
"ocpp",
"message",
"received"
],
"data": {
"cp": "1234ZY",
"action": "Heartbeat",
"messageId": "rukjys5f8q9fjce8x79kl4is",
"status": 1,
"options": {
"duration": 60,
"errorThreshold": 3
}
}
}
]
}

User app event list search filter

The searchFilter parameter follows a similar syntax to the Metadata Filter syntax, except that key paths use a . delimiter instead of a /. It is evaluated against the data property of events, and only events where the filter matches will be returned. Here are some examples, using the example event JSON shown above:

Search filter	Matches	Description
`(cp=1234ZY)`	Yes	Simple equality match on the `cp` property.
`(&(cp=1234ZY)(action=Heartbeat))`	Yes	Logical AND match on both the `cp` and `action` properties.
`(status>1)`	No	Only match events where `status` is greater than `1`.
`(messageId~=^rukjys)`	Yes	Regular expression match on `messageId` properties that start with `rukjys`.
`(&(cp=1234ZY)(!(messageId~=^rukjys)))`	No	Matches only when `cp` is `1234ZY` and `messageId` does not start with `rukjys`.
`(options.duration<=60)`	Yes	The `duration` property of the `options` object is 60 or less.

Uh oh!

SolarUser API

Request formats

Response formats

Endpoints

Associate node

Associate node response

Create node certificate

Create node certificate response

Node certificate download

Node certificate view

Node certificate view response

Node certificate renew

Datum auxiliary list

Datum auxiliary list response

Datum auxiliary store

Datum auxiliary move

Datum auxiliary view

Datum auxiliary delete

Datum maintenance aggregates stale list

Datum maintenance aggregates stale list response

Datum maintenance aggregates stale mark

Datum metadata

Datum metadata add

Datum metadata store

Datum metadata delete

Datum stream metadata view

Datum stream metadata view response

Datum stream metadata update IDs

Datum stream metadata update IDs response

Datum stream metadata update

Datum stream metadata update response

Location datum metadata

Location datum metadata add

Location datum metadata store

Location datum metadata delete

Node list

Node list response

Node find

Node find sorting

Node find response

Node archived list

Node archived list response

Node archived update

Node archived list response

Queue instruction

Expiring instruction

Deferred instruction

Deferred instruction notes

Cancelling a deferred instruction

Queue instruction response

Execute instruction

List instructions

List instructions response

View instruction

View instruction response

View active instructions

View active instructions response

View pending instructions

View pending instructions response

Update instruction state

Update instruction state response

Update instruction state matching criteria

Update instruction state matching criteria response

Node metadata

Node metadata list

Node metadata view

Node metadata add

Node metadata store

Node metadata delete

User metadata

User metadata view

User metadata add

User metadata store

User metadata delete

Authentication check

Authentication check response

Security tokens

Security token list

Security token list response