Willow Public API (v3)

Download OpenAPI specification:Download

OAuth2

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

Get OAuth2 Token

Generates an OAuth2 token.

Request
Request Body schema: application/x-www-form-urlencoded
grant_type
required
string
client_id
required
string
client_secret
required
string
Responses
200

Token response

post/oauth2/token
Request samples
application/x-www-form-urlencoded
grant_type=string&client_id=string&client_secret=string
Response samples
application/json
{
  • "access_token": "string",
  • "token_type": "string",
  • "expires_in": 0
}

Models

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

Retrieve a model

Securityoauth2
Request
path Parameters
id
required
string

Id of the model

Responses
200

If model retrieved successfully.

400

If id is not valid or null or empty.

404

If model not found

get/models/{id}
Request samples 
Response samples 
application/json
{
  • "id": "dtmi:com:willowinc:Room;1",
  • "displayName": {
    • "en": "Room"
    },
  • "description": {
    • "en": "A portion of space within a building that's usually enclosed and has its own walls, floor, and ceiling."
    },
  • "modelDefinition": "{\"@id\":\"dtmi:com:willowinc:Room;1\",\n    \"@type\":\"Interface\",\n    \"displayName\":{\"en\":\"Room\"},\n    \"description\":{\"en\":\"A portion of space within a building that's usually enclosed and has its own walls, floor, and ceiling.\"},\n    \"extends\":[\"dtmi:com:willowinc:Space;1\"],\n    \"contents\":[{\n        \"@type\":\"Property\",\n        \"name\":\"type\",\n        \"displayName\":{\"en\":\"Type\"},\n        \"writable\": true,\n        \"schema\":\"string\"\n      },\n      {\n        \"@type\":[\"Property\",\"Volume\"],\n        \"name\":\"volume\",\n        \"displayName\":{\"en\":\"Volume\"},\n        \"writable\": true,\n        \"schema\":\"double\",\n        \"unit\":\"cubicMetre\"\n      },\n      {\n        \"@type\":[\"Property\",\"ValueAnnotation\",\"Override\"],\n        \"displayName\":{\"en\":\"volume unit\"},\n        \"name\":\"volumeUnit\",\n        \"annotates\":\"volume\",\n        \"overrides\":\"unit\",\n        \"schema\":\"VolumeUnit\",\n        \"writable\": true\n      }\n    ],\n    \"@context\":[\n      \"dtmi:dtdl:context;3\",\n      \"dtmi:dtdl:extension:quantitativeTypes;1\",\n      \"dtmi:dtdl:extension:annotation;1\",\n      \"dtmi:dtdl:extension:overriding;1\"\n    ]\n  }",
  • "uploadTime": "2024-08-30T03:33:54.7015118+00:00"
}
List models
Securityoauth2 
Request 
query Parameters
rootModel
string or null
Root model to get dependencies from


 
includeModelDefinitions
boolean
 Default:  false
When true, the response includes the model definitions


 
Responses 
200
Returns models for the input root Id.


400
If a input validation error occurs.


get/models
Request samples 
Response samples 
application/json
[
  • {
    • "id": "dtmi:com:willowinc:Room;1",
    • "displayName": {
      • "en": "Room"
      },
    • "description": {
      • "en": "A portion of space within a building that's usually enclosed and has its own walls, floor, and ceiling."
      },
    • "modelDefinition": "{\"@id\":\"dtmi:com:willowinc:Room;1\",\n    \"@type\":\"Interface\",\n    \"displayName\":{\"en\":\"Room\"},\n    \"description\":{\"en\":\"A portion of space within a building that's usually enclosed and has its own walls, floor, and ceiling.\"},\n    \"extends\":[\"dtmi:com:willowinc:Space;1\"],\n    \"contents\":[{\n        \"@type\":\"Property\",\n        \"name\":\"type\",\n        \"displayName\":{\"en\":\"Type\"},\n        \"writable\": true,\n        \"schema\":\"string\"\n      },\n      {\n        \"@type\":[\"Property\",\"Volume\"],\n        \"name\":\"volume\",\n        \"displayName\":{\"en\":\"Volume\"},\n        \"writable\": true,\n        \"schema\":\"double\",\n        \"unit\":\"cubicMetre\"\n      },\n      {\n        \"@type\":[\"Property\",\"ValueAnnotation\",\"Override\"],\n        \"displayName\":{\"en\":\"volume unit\"},\n        \"name\":\"volumeUnit\",\n        \"annotates\":\"volume\",\n        \"overrides\":\"unit\",\n        \"schema\":\"VolumeUnit\",\n        \"writable\": true\n      }\n    ],\n    \"@context\":[\n      \"dtmi:dtdl:context;3\",\n      \"dtmi:dtdl:extension:quantitativeTypes;1\",\n      \"dtmi:dtdl:extension:annotation;1\",\n      \"dtmi:dtdl:extension:overriding;1\"\n    ]\n  }",
    • "uploadTime": "2024-08-30T03:33:54.7015118+00:00"
    }
]
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.


Retrieve a twin
Securityoauth2 
Request 
path Parameters
id
required
string
Id of the twin


 
query Parameters
includeRelationships
boolean
 Default:  false
When true, the response includes the incoming and outgoing relationships


 
Responses 
200
Twin information successfully retrieved.


404
Twin not found.


get/twins/{id}
Request samples 
Response samples 
application/json
{
  • "id": "TW-DD-II-L01",
  • "modelId": "dtmi:com:willowinc:Level;1",
  • "lastUpdateTime": "2024-08-30T03:49:30.4062816+00:00",
  • "contents": {
    • "levelNumber": 0,
    • "mappedIds": [
      • {
        • "exactType": "ExternalIdentity",
        • "scope": "CONNECTOR",
        • "scopeId": "CONxxxxxxxxxxx",
        • "value": "TW-CC-II-L01"
        },
      • {
        • "exactType": "FloorLevelIdentity",
        • "scope": "BUILDING",
        • "scopeId": "BLDGxxxxxxxxxxxxxxx",
        • "value": "0"
        },
      • {
        • "exactType": "ExternalIdentity",
        • "scope": "ORG",
        • "scopeId": "ORG2xxxxxxxxxxx",
        • "value": "urn:willowinc:twin:id:TW-DD-II-L01"
        }
      ],
    • "name": "Floor_1",
    • "uniqueID": "a360cf30-c112-40a1-b4b4-f65da82fa9e8",
    • "externalID": "FLRPXxxxxxxxxxxxxxxxx",
    • "code": "L01",
    • "siteID": "104bd33c-a697-4027-b6a6-677e30a53d09",
    • "alternateClassification": {
      • "brickSchema": {
        • "version": "2024-01-03",
        • "code": "dtmi:org:brickschema:schema:Brick:Floor;1"
        }
      },
    • "externalIds": {
      • "mappingKey": "msrc:///CON5xxxxxxxxxxxxxxxx@willow-source/twin/TW-DD-II-L01"
      },
    • "area": {
      • "$metadata": {
        • "$lastUpdateTime": "2024-08-30T03:49:30.4062816+00:00"
        }
      }
    },
  • "incomingRelationships": [
    • {
      • "Id": "Room-L01-100_isPartOf_TW-DD-II-L01",
      • "targetId": "TW-DD-II-L01",
      • "sourceId": "Room-L01-100",
      • "name": "isPartOf"
      }
    ],
  • "outgoingRelationships": [
    • {
      • "Id": "TW-DD-II-L01_isPartOf_BLDG-1",
      • "targetId": "BLDG-1",
      • "sourceId": "TW-DD-II-L01",
      • "name": "isPartOf"
      }
    ]
}
Update a twin
Securityoauth2 
Request 
path Parameters
id
required
string
Id of the twin


 
Request Body schema: application/json
List of Patch Operations.


 Array 
operationType
string (OperationType) 
 Enum: "Add" "Remove" "Replace" "Move" "Copy" "Test" "Invalid"  
path
string or null
 
op
string or null
 
from
string or null
 
value
any or null
 
Responses 
200
Ok Response.


400
404
Twin not found with the supplied Id.


patch/twins/{id}
Request samples 
application/json
[
  • {
    • "operationType": "Add",
    • "path": "string",
    • "op": "string",
    • "from": "string",
    • "value": null
    }
]
Response samples 
application/json
"string"
Retrieve multiple twins
Retrieve twin details for the list of twin Ids included in the request body.
Any ids that do not reference valid twins will silently be omitted from the response -- no 404/NotFound will be generated.
Match response against your query to find any invalid IDs.


Securityoauth2 
Request 
query Parameters
includeRelationships
boolean
 Default:  false
When true, the response includes the incoming and outgoing relationships


 
Request Body schema: application/json
Array of twin Ids.


 Array ([ 1 .. 100 ] items)
string
 
Responses 
200
Twin information


400
post/twins/ids
Request samples 
application/json
[
  • "string"
]
Response samples 
application/json
[
  • {
    • "id": "TW-DD-II-L01",
    • "modelId": "dtmi:com:willowinc:Level;1",
    • "lastUpdateTime": "2024-08-30T03:49:30.4062816+00:00",
    • "contents": {
      • "levelNumber": 0,
      • "mappedIds": [
        • {
          • "exactType": "ExternalIdentity",
          • "scope": "CONNECTOR",
          • "scopeId": "CONxxxxxxxxxxx",
          • "value": "TW-CC-II-L01"
          },
        • {
          • "exactType": "FloorLevelIdentity",
          • "scope": "BUILDING",
          • "scopeId": "BLDGxxxxxxxxxxxxxxx",
          • "value": "0"
          },
        • {
          • "exactType": "ExternalIdentity",
          • "scope": "ORG",
          • "scopeId": "ORG2xxxxxxxxxxx",
          • "value": "urn:willowinc:twin:id:TW-DD-II-L01"
          }
        ],
      • "name": "Floor_1",
      • "uniqueID": "a360cf30-c112-40a1-b4b4-f65da82fa9e8",
      • "externalID": "FLRPXxxxxxxxxxxxxxxxx",
      • "code": "L01",
      • "siteID": "104bd33c-a697-4027-b6a6-677e30a53d09",
      • "alternateClassification": {
        • "brickSchema": {
          • "version": "2024-01-03",
          • "code": "dtmi:org:brickschema:schema:Brick:Floor;1"
          }
        },
      • "externalIds": {
        • "mappingKey": "msrc:///CON5xxxxxxxxxxxxxxxx@willow-source/twin/TW-DD-II-L01"
        },
      • "area": {
        • "$metadata": {
          • "$lastUpdateTime": "2024-08-30T03:49:30.4062816+00:00"
          }
        }
      },
    • "incomingRelationships": [
      • {
        • "Id": "Room-L01-100_isPartOf_TW-DD-II-L01",
        • "targetId": "TW-DD-II-L01",
        • "sourceId": "Room-L01-100",
        • "name": "isPartOf"
        }
      ],
    • "outgoingRelationships": [
      • {
        • "Id": "TW-DD-II-L01_isPartOf_BLDG-1",
        • "targetId": "BLDG-1",
        • "sourceId": "TW-DD-II-L01",
        • "name": "isPartOf"
        }
      ]
    }
]
List twins
Securityoauth2 
Request 
Request Body schema: application/json
Instance of GetTwinsRequest.


(RequestModelFilter (object or null))
Filter by twin model.


 
(RequestLocationFilter (object or null))
Filter by twin location.


 
(RequestDateFilter (object or null))
Filter by twin last updated date time.


 
(RequestIncludeOption (object or null))
Additional data to include in the response.


 
pageSize
integer <int32>   [ 1 .. 1000 ] 
Maximum number of twins to return per request. Minimum is 1 and Maximum is 1000.


 
continuationToken
string or null
Continuation Token for subsequent requests. Set the Continuation token for the initial request.


 
Responses 
200
Page`1.


400
post/twins
Request samples 
application/json
{
  • "ModelFilter": {
    • "ModelIds": [ ],
    • "ExactModelMatch": true
    },
  • "LocationFilter": {
    • "LocationId": null
    },
  • "DateFilter": {
    • "LastUpdatedAfter": "2024-09-23T15:16:03.4050000+00:00",
    • "LastUpdatedBefore": "2024-09-23T15:16:03.4050000+00:00"
    },
  • "Include": {
    • "OutgoingRelationships": true,
    • "IncomingRelationships": true
    },
  • "PageSize": 101,
  • "ContinuationToken": null
}
Response samples 
application/json
{
  • "content": [
    • {
      • "id": "TW-DD-II-L01",
      • "modelId": "dtmi:com:willowinc:Level;1",
      • "lastUpdateTime": "2024-08-30T03:49:30.4062816+00:00",
      • "contents": {
        • "levelNumber": 0,
        • "mappedIds": [
          • {
            • "exactType": "ExternalIdentity",
            • "scope": "CONNECTOR",
            • "scopeId": "CONxxxxxxxxxxx",
            • "value": "TW-CC-II-L01"
            },
          • {
            • "exactType": "FloorLevelIdentity",
            • "scope": "BUILDING",
            • "scopeId": "BLDGxxxxxxxxxxxxxxx",
            • "value": "0"
            },
          • {
            • "exactType": "ExternalIdentity",
            • "scope": "ORG",
            • "scopeId": "ORG2xxxxxxxxxxx",
            • "value": "urn:willowinc:twin:id:TW-DD-II-L01"
            }
          ],
        • "name": "Floor_1",
        • "uniqueID": "a360cf30-c112-40a1-b4b4-f65da82fa9e8",
        • "externalID": "FLRPXxxxxxxxxxxxxxxxx",
        • "code": "L01",
        • "siteID": "104bd33c-a697-4027-b6a6-677e30a53d09",
        • "alternateClassification": {
          • "brickSchema": {
            • "version": "2024-01-03",
            • "code": "dtmi:org:brickschema:schema:Brick:Floor;1"
            }
          },
        • "externalIds": {
          • "mappingKey": "msrc:///CON5xxxxxxxxxxxxxxxx@willow-source/twin/TW-DD-II-L01"
          },
        • "area": {
          • "$metadata": {
            • "$lastUpdateTime": "2024-08-30T03:49:30.4062816+00:00"
            }
          }
        },
      • "incomingRelationships": [
        • {
          • "Id": "Room-L01-100_isPartOf_TW-DD-II-L01",
          • "targetId": "TW-DD-II-L01",
          • "sourceId": "Room-L01-100",
          • "name": "isPartOf"
          }
        ],
      • "outgoingRelationships": [
        • {
          • "Id": "TW-DD-II-L01_isPartOf_BLDG-1",
          • "targetId": "BLDG-1",
          • "sourceId": "TW-DD-II-L01",
          • "name": "isPartOf"
          }
        ]
      }
    ],
  • "continuationToken": "string"
}
Create or replace a twin.
Securityoauth2 
Request 
Request Body schema: application/json
Instance of DigitalTwin.


id
required
string  non-empty 
The unique Id of the digital twin.


 
modelId
required
string  non-empty 
Digital Twin Model Identifier.


 
lastUpdateTime
string or null <date-time> 
Timestamp when the twin was last updated in ISO 8601 format.


 
object
This field will contain properties and components as defined in the contents section of the DTDL definition of the twin.


 
Responses 
200
Created Twin .


400
put/twins
Request samples 
application/json
{
  • "id": "TW-DD-II-L01",
  • "modelId": "dtmi:com:willowinc:Level;1",
  • "lastUpdateTime": "2024-08-30T03:49:30.4062816+00:00",
  • "contents": {
    • "levelNumber": 0,
    • "mappedIds": [
      • {
        • "exactType": "ExternalIdentity",
        • "scope": "CONNECTOR",
        • "scopeId": "CONxxxxxxxxxxx",
        • "value": "TW-CC-II-L01"
        },
      • {
        • "exactType": "FloorLevelIdentity",
        • "scope": "BUILDING",
        • "scopeId": "BLDGxxxxxxxxxxxxxxx",
        • "value": "0"
        },
      • {
        • "exactType": "ExternalIdentity",
        • "scope": "ORG",
        • "scopeId": "ORG2xxxxxxxxxxx",
        • "value": "urn:willowinc:twin:id:TW-DD-II-L01"
        }
      ],
    • "name": "Floor_1",
    • "uniqueID": "a360cf30-c112-40a1-b4b4-f65da82fa9e8",
    • "externalID": "FLRPXxxxxxxxxxxxxxxxx",
    • "code": "L01",
    • "siteID": "104bd33c-a697-4027-b6a6-677e30a53d09",
    • "alternateClassification": {
      • "brickSchema": {
        • "version": "2024-01-03",
        • "code": "dtmi:org:brickschema:schema:Brick:Floor;1"
        }
      },
    • "externalIds": {
      • "mappingKey": "msrc:///CON5xxxxxxxxxxxxxxxx@willow-source/twin/TW-DD-II-L01"
      },
    • "area": {
      • "$metadata": {
        • "$lastUpdateTime": "2024-08-30T03:49:30.4062816+00:00"
        }
      }
    }
}
Response samples 
application/json
{
  • "id": "TW-DD-II-L01",
  • "modelId": "dtmi:com:willowinc:Level;1",
  • "lastUpdateTime": "2024-08-30T03:49:30.4062816+00:00",
  • "contents": {
    • "levelNumber": 0,
    • "mappedIds": [
      • {
        • "exactType": "ExternalIdentity",
        • "scope": "CONNECTOR",
        • "scopeId": "CONxxxxxxxxxxx",
        • "value": "TW-CC-II-L01"
        },
      • {
        • "exactType": "FloorLevelIdentity",
        • "scope": "BUILDING",
        • "scopeId": "BLDGxxxxxxxxxxxxxxx",
        • "value": "0"
        },
      • {
        • "exactType": "ExternalIdentity",
        • "scope": "ORG",
        • "scopeId": "ORG2xxxxxxxxxxx",
        • "value": "urn:willowinc:twin:id:TW-DD-II-L01"
        }
      ],
    • "name": "Floor_1",
    • "uniqueID": "a360cf30-c112-40a1-b4b4-f65da82fa9e8",
    • "externalID": "FLRPXxxxxxxxxxxxxxxxx",
    • "code": "L01",
    • "siteID": "104bd33c-a697-4027-b6a6-677e30a53d09",
    • "alternateClassification": {
      • "brickSchema": {
        • "version": "2024-01-03",
        • "code": "dtmi:org:brickschema:schema:Brick:Floor;1"
        }
      },
    • "externalIds": {
      • "mappingKey": "msrc:///CON5xxxxxxxxxxxxxxxx@willow-source/twin/TW-DD-II-L01"
      },
    • "area": {
      • "$metadata": {
        • "$lastUpdateTime": "2024-08-30T03:49:30.4062816+00:00"
        }
      }
    }
}
Relationships
Relationship endpoints enable creating, updating, and fetching relationship details.


Retrieve a twin relationship
Securityoauth2 
Request 
path Parameters
twinId
required
string
Id of the twin. SourceId for the relationship.


 
relationshipId
required
string
Id of the relationship


 
Responses 
200
Target relationship retrieved


404
Relationship not found


get/twins/{twinId}/relationships/{relationshipId}
Request samples 
Response samples 
application/json
{
  • "Id": "AHU-1_isFedBy_substance_ChilledWater_Chiller-1",
  • "targetId": "Chiller-1",
  • "sourceId": "AHU-1",
  • "name": "isFedBy",
  • "properties": {
    • "substance": "ChilledWater"
    }
}
List outgoing relationships for a twin
Securityoauth2 
Request 
path Parameters
twinId
required
string
Id of the source twin


 
query Parameters
relationshipName
string or null
Name of the relationship to filter the list.
            This parameter is optional and sending null will return all the outgoing relationships.


 
Responses 
200
Target relationships retrieved.


404
If Twin is not found.


get/twins/{twinId}/relationships/outgoing
Request samples 
Response samples 
application/json
[
  • {
    • "Id": "AHU-1_isFedBy_substance_ChilledWater_Chiller-1",
    • "targetId": "Chiller-1",
    • "sourceId": "AHU-1",
    • "name": "isFedBy",
    • "properties": {
      • "substance": "ChilledWater"
      }
    }
]
List incoming relationships for a twin
Securityoauth2 
Request 
path Parameters
twinId
required
string
Id of the target twin


 
Responses 
200
Relationships retrieved.


404
Twin not found.


get/twins/{twinId}/relationships/incoming
Request samples 
Response samples 
application/json
[
  • {
    • "Id": "AHU-1_isFedBy_substance_ChilledWater_Chiller-1",
    • "targetId": "Chiller-1",
    • "sourceId": "AHU-1",
    • "name": "isFedBy",
    • "properties": {
      • "substance": "ChilledWater"
      }
    }
]
Create or replace a twin relationship
Only one relationship between twin T1 and twin T2 with the same name and properties can be present -- if the given relationship already exists, the operation is idempotent.
Id of the relationship will be derived by the system and will override the value present in the request.


Securityoauth2 
Request 
Request Body schema: application/json
Instance of DigitalTwinRelationship.


id
string
The unique Id of the relationship entity.


 
targetId
required
string  non-empty 
The Id of the target twin.


 
sourceId
required
string  non-empty 
The Id of the source twin.


 
name
required
string  non-empty 
The name of the relationship, which defines the type of link from source twin to target twin (e.g. isPartOf, locatedIn, servedBy, etc.. ).


 
object
Additional properties of the relationship as defined in the DTDL model.


 
Responses 
200
Created or Updated DigitalTwinRelationship.


400
If provided relationship has empty sourceId, targetId or name.


404
If sourceId, targetId or name does not exist. 


put/twins/relationships
Request samples 
application/json
{
  • "Id": "AHU-1_isFedBy_substance_ChilledWater_Chiller-1",
  • "targetId": "Chiller-1",
  • "sourceId": "AHU-1",
  • "name": "isFedBy",
  • "properties": {
    • "substance": "ChilledWater"
    }
}
Response samples 
application/json
{
  • "Id": "AHU-1_isFedBy_substance_ChilledWater_Chiller-1",
  • "targetId": "Chiller-1",
  • "sourceId": "AHU-1",
  • "name": "isFedBy",
  • "properties": {
    • "substance": "ChilledWater"
    }
}
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).


Retrieve a time series
Securityoauth2 
Request 
path Parameters
twinId
required
string
 
query Parameters
start
required
string <date-time> 
 
end
required
string <date-time> 
 
pageSize
required
integer <int32> 
 
continuationToken
string
 
Responses 
200
OK


401
Unauthorized


403
Forbidden


404
Not Found


get/time-series/{twinId}
Request samples 
Response samples 
application/json
{
  • "data": {
    • "connectorId": "TW-CC-01",
    • "twinId": "TW-DD-II-01",
    • "externalId": "PNTC4Jm8vXy7bWq9rT5sHkLz2p",
    • "sourceTimestamp": "2024-10-01T12:34:56.0000000+00:00",
    • "scalarValue": 42,
    • "properties": {
      • "customerEquipmentId": "X-1234"
      }
    },
  • "continuationToken": "CgAAYQAAAAAAABQ...",
  • "errorData": {
    • "message": "Error message",
    • "ids": [
      • "TW-DD-II-02"
      ]
    }
}
Retrieve multiple time series
Securityoauth2 
Request 
query Parameters
start
required
string <date-time> 
 
end
required
string <date-time> 
 
pageSize
required
integer <int32> 
 
continuationToken
string
 
Request Body schema: application/json
 Array 
string
 
Responses 
200
OK


401
Unauthorized


403
Forbidden


404
Not Found


post/time-series/ids
Request samples 
application/json
[
  • "string"
]
Response samples 
application/json
{
  • "data": {
    • "connectorId": "TW-CC-01",
    • "twinId": "TW-DD-II-01",
    • "externalId": "PNTC4Jm8vXy7bWq9rT5sHkLz2p",
    • "sourceTimestamp": "2024-10-01T12:34:56.0000000+00:00",
    • "scalarValue": 42,
    • "properties": {
      • "customerEquipmentId": "X-1234"
      }
    },
  • "continuationToken": "CgAAYQAAAAAAABQ...",
  • "errorData": {
    • "message": "Error message",
    • "ids": [
      • "TW-DD-II-02"
      ]
    }
}
Retrieve the latest value
Securityoauth2 
Request 
path Parameters
twinId
required
string
 
Responses 
200
OK


401
Unauthorized


403
Forbidden


404
Not Found


get/time-series/{twinId}/latest
Request samples 
Response samples 
application/json
[
  • {
    • "connectorId": "TW-CC-01",
    • "twinId": "TW-DD-II-01",
    • "externalId": "PNTC4Jm8vXy7bWq9rT5sHkLz2p",
    • "trendId": "0d90ca30-190e-4f45-9ea7-52cb529ba9ea",
    • "sourceTimestamp": "2024-10-01T12:34:56.0000000+00:00",
    • "enqueuedTimestamp": "2024-10-01T12:35:00.0000000+00:00",
    • "scalarValue": 42,
    • "properties": {
      • "customerEquipmentId": "X-1234"
      }
    }
]
Retrieve multiple latest values
Securityoauth2 
Request 
Request Body schema: application/json
 Array 
string
 
Responses 
200
OK


401
Unauthorized


403
Forbidden


404
Not Found


post/time-series/ids/latest
Request samples 
application/json
[
  • "string"
]
Response samples 
application/json
[
  • {
    • "connectorId": "TW-CC-01",
    • "twinId": "TW-DD-II-01",
    • "externalId": "PNTC4Jm8vXy7bWq9rT5sHkLz2p",
    • "trendId": "0d90ca30-190e-4f45-9ea7-52cb529ba9ea",
    • "sourceTimestamp": "2024-10-01T12:34:56.0000000+00:00",
    • "enqueuedTimestamp": "2024-10-01T12:35:00.0000000+00:00",
    • "scalarValue": 42,
    • "properties": {
      • "customerEquipmentId": "X-1234"
      }
    }
]
Insert time series values
Securityoauth2 
Request 
Request Body schema: application/json
 Array 
connectorId
string or null
Id of the connector


 
dtId
string or null
Id of the twin


 
externalId
string or null
External Id of the twin


 
sourceTimestamp
required
string <date-time> 
Timestamp when the source recorded the value in ISO 8601 format


 
scalarValue
required
number <double> 
The data value being trended


 
latitude
number or null <double> 
Gets the latitude of the device.


 
longitude
number or null <double> 
Gets the longitude of the device.


 
altitude
number or null <double> 
Gets the Altitude of the device.


 
properties
object or null
Properties or metadata about the observation or event being trended.


 
Responses 
202
Accepted


400
Bad Request


401
Unauthorized


403
Forbidden


post/time-series
Request samples 
application/json
[
  • {
    • "connectorId": "TW-CC-01",
    • "twinId": "TW-DD-II-01",
    • "externalId": "PNTC4Jm8vXy7bWq9rT5sHkLz2p",
    • "sourceTimestamp": "2024-10-01T12:34:56.0000000+00:00",
    • "scalarValue": 42,
    • "properties": {
      • "customerEquipmentId": "X-1234"
      }
    }
]
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.


List insights
Securityoauth2 
Request 
query Parameters
addFloor
boolean
 Default:  false
When true, the response includes the floorId


 
Request Body schema: 
Array of objects or null (SortSpecification) 
 
Array of objects or null (FilterSpecification) 
 
page
integer or null <int32> 
 
pageSize
integer or null <int32> 
 
Responses 
200
OK


401
Unauthorized


403
Forbidden


post/insights
Request samples 
{
  • "sortSpecifications": [
    • {
      • "field": "string",
      • "sort": "string"
      }
    ],
  • "filterSpecifications": [
    • {
      • "field": "string",
      • "operator": "string",
      • "value": { }
      }
    ],
  • "page": 0,
  • "pageSize": 0
}
Response samples 
application/json
{
  • "before": 0,
  • "after": 0,
  • "total": 0,
  • "items": [
    • {
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac",
      • "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
      • "sequenceNumber": "string",
      • "equipmentId": "d2a795e1-f645-4e24-bc0a-ab1965048fcc",
      • "twinId": "string",
      • "twinName": "string",
      • "type": "fault",
      • "name": "string",
      • "description": "string",
      • "recommendation": "string",
      • "impactScores": [
        • {
          • "name": "string",
          • "fieldId": "string",
          • "value": 0,
          • "unit": "string",
          • "externalId": "string",
          • "ruleId": "string"
          }
        ],
      • "priority": 0,
      • "lastStatus": "open",
      • "state": "inactive",
      • "createdDate": "2019-08-24T14:15:22Z",
      • "updatedDate": "2019-08-24T14:15:22Z",
      • "occurredDate": "2019-08-24T14:15:22Z",
      • "detectedDate": "2019-08-24T14:15:22Z",
      • "sourceType": "willow",
      • "sourceId": "797f5a94-3689-4ac8-82fd-d749511ea2b2",
      • "sourceName": "string",
      • "primaryModelId": "string",
      • "externalId": "string",
      • "externalStatus": "string",
      • "externalMetadata": "string",
      • "occurrenceCount": 0,
      • "createdUserId": "ea7e097f-834f-4fa5-87fc-4730a5fb67fe",
      • "ruleId": "string",
      • "ruleName": "string",
      • "newOccurrence": true,
      • "previouslyIgnored": 0,
      • "previouslyResolved": 0,
      • "floorId": "f4b95b27-8806-47f9-baf2-7b034d2e232f",
      • "reported": true,
      • "lastResolvedDate": "2019-08-24T14:15:22Z",
      • "lastIgnoredDate": "2019-08-24T14:15:22Z",
      • "locations": [
        • "string"
        ],
      • "tags": [
        • "string"
        ]
      }
    ]
}
Retrieve an insight
Securityoauth2 
Request 
path Parameters
insightId
required
string <uuid> 
Id of the insight


 
Responses 
200
OK


401
Unauthorized


403
Forbidden


get/insights/{insightId}
Request samples 
Response samples 
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac",
  • "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
  • "sequenceNumber": "string",
  • "equipmentId": "d2a795e1-f645-4e24-bc0a-ab1965048fcc",
  • "twinId": "string",
  • "twinName": "string",
  • "type": "fault",
  • "name": "string",
  • "description": "string",
  • "recommendation": "string",
  • "impactScores": [
    • {
      • "name": "string",
      • "fieldId": "string",
      • "value": 0,
      • "unit": "string",
      • "externalId": "string",
      • "ruleId": "string"
      }
    ],
  • "priority": 0,
  • "lastStatus": "open",
  • "state": "inactive",
  • "createdDate": "2019-08-24T14:15:22Z",
  • "updatedDate": "2019-08-24T14:15:22Z",
  • "occurredDate": "2019-08-24T14:15:22Z",
  • "detectedDate": "2019-08-24T14:15:22Z",
  • "sourceType": "willow",
  • "sourceId": "797f5a94-3689-4ac8-82fd-d749511ea2b2",
  • "sourceName": "string",
  • "primaryModelId": "string",
  • "externalId": "string",
  • "externalStatus": "string",
  • "externalMetadata": "string",
  • "occurrenceCount": 0,
  • "createdUserId": "ea7e097f-834f-4fa5-87fc-4730a5fb67fe",
  • "ruleId": "string",
  • "ruleName": "string",
  • "newOccurrence": true,
  • "previouslyIgnored": 0,
  • "previouslyResolved": 0,
  • "floorId": "f4b95b27-8806-47f9-baf2-7b034d2e232f",
  • "reported": true,
  • "lastResolvedDate": "2019-08-24T14:15:22Z",
  • "lastIgnoredDate": "2019-08-24T14:15:22Z",
  • "locations": [
    • "string"
    ],
  • "tags": [
    • "string"
    ]
}
Copyright © 2024 Willow. All rights reserved.