Skip to content
REST API Reference/
/
Insert time series values

Willow Public API (v3)

Download OpenAPI description
willow-api.json
willow-api.yaml
Languages
Servers
https://{instance}.app.willowinc.com/api/v3/

OAuth2

Authentication is required prior to accessing the Willow API. Refer to Authentication section above for details.

Operations

Models

Models endpoints are used for getting the models and their details.

Operations

Twins

The Twins endpoints enable creating, updating, and fetching one or more twins at a time. When receiving twins, there are also options to include relationships in the same response.

Operations

Relationships

Relationship endpoints enable creating, updating, and fetching relationship details.

Operations

Time Series

The Time Series endpoints are used for sending or receiving telemetry data. Once a Capability twin has been created that represents the time series, the telemetry associated with that twin can be created using either the twin's dtId (aka twinId) or externalId, a timestamp, and a value. Data is transmitted as an array so time series data can be batched and sent within a single request. Similarly, time series can be retreived for one or more Capability twins at a time using the twinId(s).

Operations

Insert time series values

Request

Security
oauth2
Bodyapplication/jsonrequiredArray [
connectorIdstringrequired

Id of the connector

Example: "TW-CC-01"
dtIdstring or null

Id of the twin

externalIdstring or null

External Id of the twin

Example: "PNTC4Jm8vXy7bWq9rT5sHkLz2p"
sourceTimestampstring(date-time)required

Timestamp when the source recorded the value in ISO 8601 format

Example: "2024-10-01T12:34:56Z"
scalarValuenumber or object(double)required

The data value being trended

Example: 42
Any of:
number
propertiesobject

Properties or metadata about the observation or event being trended.

Example: {"customerEquipmentId":"X-1234"}
]
application/json
[
  {
    "connectorId": "TW-CC-01",
    "twinId": "TW-DD-II-01",
    "externalId": "PNTC4Jm8vXy7bWq9rT5sHkLz2p",
    "sourceTimestamp": "2024-10-01T12:34:56Z",
    "scalarValue": 42,
    "properties": { … }
  }
]

Responses

Accepted

Retrieve a time series

Request

Security
oauth2
Path
twinIdstringrequired

Id of the twin

Example: TW-DD-II-01
Query
startstring(date-time)required

Start timestamp for the request

Example: start=2024-10-01T00:00:00Z
endstring(date-time)required

End timestamp for the request

Example: end=2024-10-07T00:00:00Z
pageSizeinteger(int32)required

Number of items returned per page (minimum 1)

Example: pageSize=100
continuationTokenstring

Token for retrieving the next page of results

Example: continuationToken=CgAAYQAAAAAAABQ...
includeDataQualityboolean

If true, include data quality metrics in the response

No request payload

Responses

OK

Bodyapplication/json
dataArray of objects or null(TelemetryData)

Gets or sets the data.

Example: [{"connectorId":"TW-CC-01","twinId":"TW-DD-II-01","externalId":"PNTC4Jm8vXy7bWq9rT5sHkLz2p","sourceTimestamp":"2024-10-01T12:34:56Z","scalarValue":42,"properties":{"customerEquipmentId":"X-1234"},"dataQuality":{"offline":false,"valueOutOfRange":false,"sparse":false,"flatline":false,"delayed":false}}]
continuationTokenstring or null

Gets or sets the continuation token.

Example: "CgAAYQAAAAAAABQ..."
errorListobject or ErrorData (object)
One of:
Response
application/json
{
  "data": [
    { … }
  ],
  "continuationToken": "CgAAYQAAAAAAABQ...",
  "errorData": {
    "message": "Error message",
    "ids": [ … ]
  }
}

Retrieve the latest value

Request

Security
oauth2
Path
twinIdstringrequired

Id of the twin

Example: TW-DD-II-01
Query
startstring(date-time)

Start timestamp for the request

Example: start=2024-10-01T00:00:00Z
endstring(date-time)

End timestamp for the request

Example: end=2024-10-07T00:00:00Z
includeDataQualityboolean

If true, include data quality metrics in the response

No request payload

Responses

OK

Bodyapplication/jsonArray [
connectorIdstring or null

Id of the connector

Example: "TW-CC-01"
twinIdstring or null

Id of the twin

Example: "TW-DD-II-01"
externalIdstring or null

External Id of the twin

Example: "PNTC4Jm8vXy7bWq9rT5sHkLz2p"
sourceTimestampstring(date-time)

Timestamp when the source recorded the value in ISO 8601 format

Example: "2024-10-01T12:34:56Z"
enqueuedTimestampstring(date-time)

Timestamp when Willow received the value in ISO 8601 format

Example: "2024-10-01T12:35:00Z"
scalarValue(number or null) or (string or null) or (boolean or null) or (integer or null)

The data value being trended

Example: 42
One of:

The data value being trended

number or null
propertiesobject

Properties or metadata about the observation or event being trended.

Example: {"customerEquipmentId":"X-1234"}
dataQualityobject or DataQuality (object)
Example: {"offline":false,"valueOutOfRange":false,"sparse":false,"flatline":false,"delayed":false}
One of:
]
Response
application/json
[
  {
    "connectorId": "TW-CC-01",
    "twinId": "TW-DD-II-01",
    "externalId": "PNTC4Jm8vXy7bWq9rT5sHkLz2p",
    "sourceTimestamp": "2024-10-01T12:34:56Z",
    "enqueuedTimestamp": "2024-10-01T12:35:00Z",
    "scalarValue": 42,
    "properties": { … },
    "dataQuality": { … }
  }
]

Retrieve multiple time series

Request

Security
oauth2
Query
startstring(date-time)required

Start timestamp for the request

Example: start=2024-10-01T00:00:00Z
endstring(date-time)required

End timestamp for the request

Example: end=2024-10-07T00:00:00Z
pageSizeinteger(int32)required

Number of items returned per page (minimum 1)

Example: pageSize=100
continuationTokenstringrequired

Token for retrieving the next page of results

Example: continuationToken=CgAAYQAAAAAAABQ...
includeDataQualityboolean

If true, include data quality metrics in the response

Bodyapplication/jsonrequiredArray [
string
]
application/json
[
  "string"
]

Responses

OK

Bodyapplication/json
dataArray of objects or null(TelemetryData)

Gets or sets the data.

Example: [{"connectorId":"TW-CC-01","twinId":"TW-DD-II-01","externalId":"PNTC4Jm8vXy7bWq9rT5sHkLz2p","sourceTimestamp":"2024-10-01T12:34:56Z","scalarValue":42,"properties":{"customerEquipmentId":"X-1234"},"dataQuality":{"offline":false,"valueOutOfRange":false,"sparse":false,"flatline":false,"delayed":false}}]
continuationTokenstring or null

Gets or sets the continuation token.

Example: "CgAAYQAAAAAAABQ..."
errorListobject or ErrorData (object)
One of:
Response
application/json
{
  "data": [
    { … }
  ],
  "continuationToken": "CgAAYQAAAAAAABQ...",
  "errorData": {
    "message": "Error message",
    "ids": [ … ]
  }
}

Retrieve multiple latest values

Request

Security
oauth2
Query
startstring(date-time)

Start timestamp for the request

Example: start=2024-10-01T00:00:00Z
endstring(date-time)

End timestamp for the request

Example: end=2024-10-07T00:00:00Z
includeDataQualityboolean

If true, include data quality metrics in the response

Bodyapplication/jsonrequiredArray [
string
]
application/json
[
  "string"
]

Responses

OK

Bodyapplication/jsonArray [
connectorIdstring or null

Id of the connector

Example: "TW-CC-01"
twinIdstring or null

Id of the twin

Example: "TW-DD-II-01"
externalIdstring or null

External Id of the twin

Example: "PNTC4Jm8vXy7bWq9rT5sHkLz2p"
sourceTimestampstring(date-time)

Timestamp when the source recorded the value in ISO 8601 format

Example: "2024-10-01T12:34:56Z"
enqueuedTimestampstring(date-time)

Timestamp when Willow received the value in ISO 8601 format

Example: "2024-10-01T12:35:00Z"
scalarValue(number or null) or (string or null) or (boolean or null) or (integer or null)

The data value being trended

Example: 42
One of:

The data value being trended

number or null
propertiesobject

Properties or metadata about the observation or event being trended.

Example: {"customerEquipmentId":"X-1234"}
dataQualityobject or DataQuality (object)
Example: {"offline":false,"valueOutOfRange":false,"sparse":false,"flatline":false,"delayed":false}
One of:
]
Response
application/json
[
  {
    "connectorId": "TW-CC-01",
    "twinId": "TW-DD-II-01",
    "externalId": "PNTC4Jm8vXy7bWq9rT5sHkLz2p",
    "sourceTimestamp": "2024-10-01T12:34:56Z",
    "enqueuedTimestamp": "2024-10-01T12:35:00Z",
    "scalarValue": 42,
    "properties": { … },
    "dataQuality": { … }
  }
]

Insights

Insights are issues, opportunities, or knowledge that can help optimize or improve the performance of a building. They can be associated with any twin within Willow and are triggered in real-time by Skills that are running within Willow's Activate Technology and analyzing the incoming time series data.

Operations

Events

Events endpoints enable creating, updating, and deleting discrete occurrences such as Weather Forecast, Calendar events etc.

Operations

Tickets

This API group is in pre-release and may change without notice. Use with caution. Breaking changes may occur as development continues.
Tickets endpoints enable creating, updating and retrieving Tickets.

Operations

Ticket Metadata

This API group is in pre-release and may change without notice. Use with caution. Breaking changes may occur as development continues.
Ticket Metadata endpoints enable creating, updating and retrieving Ticket Metadata.

Operations
Copyright © 2024 Willow. All rights reserved.