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.

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	/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.
GET	/nodes/meta	Get metadata for one or more nodes.
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.
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:

<NetworkAssociationDetails
  networkId="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

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
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.
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.

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.

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 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:

1. Queuing
2. Queued
3. Received
4. Executing
5. 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.
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.
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"}
]}

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:

1. a Unix millisecond epoch integer, for example 1680030000000
2. 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",
    "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 seconds 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 seconds to wait for the instruction(s) to complete before giving up. The maximum allowed is 60. Defaults to 60.

💡 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	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.
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 an instruction. See Node instruction state type for possible state types.

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

Update instruction state response

The response contains no data.

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 optional metadata 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.

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.

An example response looks like this:

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

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 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.
name	An optional friendly name.
description	An optional description.

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.