Willow API Reference (v1.0)

Download OpenAPI specification:Download

Welcome to the Willow API Reference documentation!

We are excited to see what you build with the Willow platform. Ensure you are looking at the correct version of the API documentation as we are always building and incrementing our APIs to provide more value for our customers.

You can find information about how to obtain your Access Token here.

View response samples in the right panel. Check back soon for request samples in your favorite programming language.

For more information about Willow products, visit our product page.

Authentication

Prerequisites

You first need to register your application in the Willow system. You can do so by sending a e-mail to developers@willowinc.com.

Coming Soon - You will be able to Sign Up to create a Developer Account and self-register your application.

Once your application is registered to use the Willow API, you will receive a Client ID and Client Secret that will allow you to request an access token. Review the Authentication Guide for more details.

OAuth2

Security Scheme Type: OAuth2
Flow type: clientCredentials
Token URL: https://api.willowinc.com/v1/oauth2/token

Pagination

In many of our endpoints, we support the Continuation Token method of pagination. When you make a request to an endpoint supporting continuation tokens, you will receive a continuation token string in the response body.

When making a new request for the next page of results, include the continuation token as a query parameter along with the desired page size.

Errors

The Willow API uses HTTP response status codes to indicate the success or otherwise of API requests. While not all codes listed below are used, some may be used in the future. Codes in the 2xx range indicate success, codes in the 4xx range indicate an error, and codes in the 5xx range indicate a server-side error. Note that 4xx and 5xx responses may be returned for any request and clients should cater for them.

Response
Code		 Description
200 Success -- The request was successful.
201 Created -- The resource was successfully created.
400 Bad Request -- General client error, possibly malformed data.
401 Unauthorized -- The API Key was not authorised (or no API Key was found).
402 Payment Required -- The API is not available on your current plan.
403 Forbidden -- The request is not allowed.
404 Not Found -- The resource was not found.
405 Method Not Allowed -- The resource does not accept the HTTP method.
406 Not Acceptable -- The resource cannot return the client's required content type.
408 Request Timeout -- The server would not wait any longer for the client.
409 Conflict - This request attempts to create a duplicate.
415 Unsupported Media Type - The server doesn't accept the submitted content-type.
422 Unprocessable Entity -- The data was well-formed but invalid.
429 Too Many Requests -- The client has reached or exceeded a rate limit, or the server is overloaded.
500, 502,
503, 504		 Server errors - something went wrong with Willow's servers.
These errors are most likely momentary operational errors, and requests should be retried once.

Rate Limiting

API Rate Limits are in place to protect Willow from API traffic spikes and flooding attacks that could put our platform at risk. We therefore measure the amount of requests sent to the API in order to throttle these when they surpass the amount allowed. Upon exceeding the threshold, we will respond with '429 Too Many Requests'.

Willow Rate Limits

X-RateLimit-Limit: 3600
X-RateLimit-Remaining: 3599
X-RateLimit-Reset: 1590793125

The default rate limit for the Willow API is 3,600 API calls per hour at this time. The following response headers are returned with each API call to help your app monitor its rate limiting status.

Header Description
X-RateLimit-Limit Maximum number of requests allowed for the app.
X-RateLimit-Remaining Number of requests left in the current time.
X-RateLimit-Reset The Unix Timestamp when the number of requests will be reset to the maximum limit.

Auth

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

Retrieve an access token

Request
Request Body schema:
clientId
string or null
clientSecret
string or null
Responses
200

Success

post/oauth2/token
Request samples
{
  • "clientId": "string",
  • "clientSecret": "string"
}
Response samples
application/json
{
  • "accessToken": "string",
  • "expiresIn": 0,
  • "tokenType": "string"
}

Sites

Sites are the root node for location objects in the digital twin. The term site is used to refer to buildings, venues, campuses, and other asset classes and geolocations. Because sites are a well understood locations, they are flexible in the exact type of structure or area in which they define. Floors are attached to Sites and can be retrieved by defining the siteId as a path parameter.

List sites

SecurityOAuth2
Responses
200

Success

401

Unauthorized

403

Forbidden

get/sites
Request samples 
Response samples 
application/json
[
  • {
    • "id": "1218614a-9822-43c5-94ca-1ecc29ab80b0",
    • "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac",
    • "name": "North America HQ",
    • "tzid": "Eastern Standard Time",
    • "location": {
      • "address": "575 5th Ave, 17th Floor",
      • "postCode": "10017",
      • "suburb": "New York",
      • "state": "New York",
      • "country": "United States"
      },
    • "regionId": "string"
    }
]
List floors
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
query Parameters
pageSize
integer or null <int32> 
Page size (number of elements to return)


 
continuationToken
string or null
String used for pagination. Submit the Continuation Token returned in the previous request to fetch the next page of results.


 
Responses 
200
Success


401
Unauthorized


403
Forbidden


get/sites/{siteId}/floors
Request samples 
Response samples 
application/json
[
  • {
    • "id": "b7d170fd-48fd-4392-a4e9-1ad5880edc62",
    • "name": "Level 10",
    • "code": "L010"
    }
]
Assets
Assets are physical objects located at the site that have a commonly understood identity and value. The WillowTwin product suite refers to the collection of Assets at a site as the Asset Register. These may be Equipment objects such as Electrical Panelboards or Fire Pumps or static objects such as doors, windows, or workstations. Each asset is assigned to a Category such as HVAC - Air Side or Architectural to enable grouping of common pieces of equipment.
Each Asset also has a rich set of parameters, or properties. These parameters may be common across all assets, such as Specification Section, or unique to an Asset type such as VAV-Box Maximum Airflow Rating (CFM).


Retrieve an Asset
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
assetId
required
string <uuid> 
The unique ID of the asset which is given by Willow


 
 Example:  62b1928c-7331-02a3-bc74-3dba18ca91a2
Responses 
200
Success


401
Unauthorized


403
Forbidden


get/sites/{siteId}/assets/{assetId}
Request samples 
Response samples 
application/json
{
  • "id": "62b1928c-7331-02a3-bc74-3dba18ca91a2",
  • "categoryId": "00300000-0000-0000-0000-000000010976",
  • "floorId": "b7d170fd-48fd-4392-a4e9-1ad5880edc62",
  • "name": "Variable Air Volume Box VAV-01.1",
  • "identifier": "VAV-01.1",
  • "assetParameters": [
    • {
      • "key": "assetType",
      • "displayName": "Asset Type",
      • "value": "Terminal Unit - VAV Box"
      },
    • {
      • "key": "specificationSection",
      • "displayName": "Specification Section",
      • "value": "23 36 00"
      },
    • {
      • "key": "roomNumber",
      • "displayName": "Room Number",
      • "value": "01-104"
      },
    • {
      • "key": "maxAirflowRating",
      • "displayName": "Maximum Airflow Rating (CFM)",
      • "value": 300
      }
    ]
}
List Asset Categories
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
Responses 
200
Success


401
Unauthorized


403
Forbidden


get/sites/{siteId}/categories
Request samples 
Response samples 
application/json
[
  • {
    • "id": "00300000-0000-0000-0000-000000010605",
    • "name": "Mechanical - Air Side",
    • "childCategories": [
      • [
        • {
          • "id": "00300000-0000-0000-0000-000000010976",
          • "name": "VAV Boxes",
          • "childCategories": [ ]
          },
        • {
          • "id": "00300000-0000-0000-0000-000000010979",
          • "name": "Fan Coil Units",
          • "childCategories": [ ]
          },
        • {
          • "id": "00300000-0000-0000-0000-000000010980",
          • "name": "Dampers",
          • "childCategories": [ ]
          }
        ]
      ]
    }
]
List Assets
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
categoryId
required
string <uuid> 
The unique ID of the asset category which is given by Willow


 
 Example:  00300000-0000-0000-0000-000000010605
Responses 
200
Success


401
Unauthorized


403
Forbidden


get/sites/{siteId}/categories/{categoryId}/assets
Request samples 
Response samples 
application/json
[
  • {
    • "id": "62b1928c-7331-02a3-bc74-3dba18ca91a2",
    • "categoryId": "00300000-0000-0000-0000-000000010976",
    • "floorId": "b7d170fd-48fd-4392-a4e9-1ad5880edc62",
    • "name": "Variable Air Volume Box VAV-01.1",
    • "identifier": "VAV-01.1",
    • "assetParameters": [
      • {
        • "key": "assetType",
        • "displayName": "Asset Type",
        • "value": "Terminal Unit - VAV Box"
        },
      • {
        • "key": "specificationSection",
        • "displayName": "Specification Section",
        • "value": "23 36 00"
        },
      • {
        • "key": "roomNumber",
        • "displayName": "Room Number",
        • "value": "01-104"
        },
      • {
        • "key": "maxAirflowRating",
        • "displayName": "Maximum Airflow Rating (CFM)",
        • "value": 300
        }
      ]
    }
]
Equipment
Equipment is the root node for asset objects in the digital twin. Equipment are physical objects that may optionally have associated Devices, Points, and Live Data. Equipment is associated to a location in the digital twin as well as a parent which enables a user to understand location context as well as system relationships between equipment. The Equipment Object is categorized with a discipline such as HVAC or Electrical to enable grouping of common pieces of equipment.
The digital twin also has tags associated with each Equipment to provide metadata about the object. These tags follow the guidance of Project Haystack but can be customized for each Customer and Site. Tags are strings that can be grouped together into arrays and applied to Equipment to provide metadata about the type, function, or purpose. These arrays are often referred to as Tagsets and are a means of providing standard context about an entity.


List equipment
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
query Parameters
pageSize
integer or null <int32> 
Page size (number of elements to return)


 
continuationToken
string or null
String used for pagination. Submit the Continuation Token returned in the previous request to fetch the next page of results.


 
Responses 
200
Success


401
Unauthorized


403
Forbidden


404
Not Found


get/sites/{siteId}/equipment
Request samples 
Response samples 
application/json
{
  • "continuationToken": "string",
  • "data": [
    • {
      • "id": "6be53768-811e-4db8-baee-471a01498df7",
      • "name": "VAV-01.1",
      • "location": "1st Floor, Rm. 123",
      • "discipline": "HVAC",
      • "parentId": "d27058e5-32cb-4411-992b-0804dbdb929d",
      • "tags": [
        • "equip",
        • "hvac",
        • "vav",
        • "coolOnly"
        ]
      }
    ]
}
List equipment
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
query Parameters
pageSize
integer or null <int32> 
Page size (number of elements to return)


 
continuationToken
string or null
String used for pagination. Submit the Continuation Token returned in the previous request to fetch the next page of results.


 
Responses 
200
Success


401
Unauthorized


403
Forbidden


404
Not Found


get/sites/{siteId}/equipments
Request samples 
Response samples 
application/json
{
  • "continuationToken": "string",
  • "data": [
    • {
      • "id": "6be53768-811e-4db8-baee-471a01498df7",
      • "name": "VAV-01.1",
      • "location": "1st Floor, Rm. 123",
      • "discipline": "HVAC",
      • "parentId": "d27058e5-32cb-4411-992b-0804dbdb929d",
      • "tags": [
        • "equip",
        • "hvac",
        • "vav",
        • "coolOnly"
        ]
      }
    ]
}
Devices
Devices are controller objects that have inputs and outputs that correspond to Point objects receiving and transmitting Live Data. We adopt the use of Devices to follow BACnet terminology. These controllers are often associated with a single Equipment object but may have Point objects that span across multiple pieces of Equipment.


List devices
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
query Parameters
pageSize
integer or null <int32> 
Page size (number of elements to return)


 
continuationToken
string or null
String used for pagination. Submit the Continuation Token returned in the previous request to fetch the next page of results.


 
Responses 
200
Success


401
Unauthorized


403
Forbidden


get/sites/{siteId}/devices
Request samples 
Response samples 
application/json
{
  • "continuationToken": "string",
  • "data": [
    • {
      • "id": "19f770eb-b77f-4c35-b479-63d2c08f35b6",
      • "registrationId": "string",
      • "registrationKey": "string",
      • "points": [
        • {
          • "id": "0fcd55ad-251d-4111-bed9-de32c7addb52",
          • "name": "zone air temp sensor",
          • "type": "analog",
          • "equipmentIds": [
            • "12a81670-1b05-465f-940f-ec5371843e34",
            • "09ade39f-a69a-4d95-a8e0-dc28309874e4"
            ],
          • "unit": "degC",
          • "interval": 1200,
          • "metadata": [
            • {
              • "key": "manufacturer",
              • "value": "omega",
              • "dataType": "string"
              }
            ],
          • "tags": [
            • "zone",
            • "air",
            • "temp",
            • "sensor"
            ],
          • "trendlog": [
            • {
              • "timestamp": "2020-05-27T16:48:20.773Z",
              • "value": "22.5863236278265"
              },
            • {
              • "timestamp": "2020-05-25T02:20:00.000Z",
              • "value": "21.2955047175106"
              }
            ]
          }
        ]
      }
    ]
}
Points
Points can be treated as leaf nodes for asset objects in the digital twin. They are children to both Equipment and Devices and correspond to Live Data that is often being received of transmitted from a device.
Similar to Equipment, tags are associated with each Point to provide metadata about the object. These tags also follow the guidance of Project Haystack and can be customized for each Customer and Site. Tags are strings that can be grouped together into arrays and applied to Points to provide metadata about the type, function, or purpose. These arrays are often referred to as Tagsets and are a means of providing standard context about an entity.


List points
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
query Parameters
pageSize
integer or null <int32> 
Page size (number of elements to return)


 
continuationToken
string or null
String used for pagination. Submit the Continuation Token returned in the previous request to fetch the next page of results.


 
equipmentId
string or null <uuid> 
The unique ID of the equipment which is given by Willow


 
 Example:  equipmentId=6be53768-811e-4db8-baee-471a01498df7
includeEquipment
boolean or null
Whether the response should include the equipment object


 
 Example:  includeEquipment=true
Responses 
200
Success


401
Unauthorized


403
Forbidden


get/sites/{siteId}/points
Request samples 
Response samples 
application/json
{
  • "continuationToken": "string",
  • "data": [
    • {
      • "id": "0fcd55ad-251d-4111-bed9-de32c7addb52",
      • "name": "zone air temp sensor",
      • "type": "analog",
      • "equipmentIds": [
        • "12a81670-1b05-465f-940f-ec5371843e34",
        • "09ade39f-a69a-4d95-a8e0-dc28309874e4"
        ],
      • "unit": "degC",
      • "interval": 1200,
      • "metadata": [
        • {
          • "key": "manufacturer",
          • "value": "omega",
          • "dataType": "string"
          }
        ],
      • "tags": [
        • "zone",
        • "air",
        • "temp",
        • "sensor"
        ],
      • "trendlog": [
        • {
          • "timestamp": "2020-05-27T16:48:20.773Z",
          • "value": "22.5863236278265"
          },
        • {
          • "timestamp": "2020-05-25T02:20:00.000Z",
          • "value": "21.2955047175106"
          }
        ]
      }
    ]
}
Live Data
Live Data generated by Points and stored in the digital twin and always associated with a timestamp value. The Willow API has the ability to read current values as well as a historical trend via the Trend Logs endpoint.


Add live data
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
Request Body schema: 
Array of objects or null (PointLiveData) 
 
Responses 
200
Success


401
Unauthorized


403
Forbidden


post/sites/{siteId}/livedata
Request samples 
{
  • "points": [
    • {
      • "pointId": "0fcd55ad-251d-4111-bed9-de32c7addb52",
      • "timestamp": "2020-05-27T16:48:20.773Z",
      • "value": 22.5863236278265
      }
    ]
}
Response samples 
application/json
{ }
List time series
This endpoint returns the time series data for point(s) in an aggregated response according to the defined granularity. The following
table shows the default and recommended granularity parameter for a give date range:






Range of Days
Default
Granularity		
Granularity
Recommendations		
Granularity
Recommendations (ISO 8601)		





<= 1
5 minutes
5 minutes
10 minutes
15 minutes
30 minutes		
PT5M
PT10M
PT15M
PT30M		




<= 3
5 minutes
5 minutes
10 minutes
15 minutes
30 minutes
1 hour		
PT5M
PT10M
PT15M
PT30M
PT1H		




<=7
10 minutes
10 minutes
15 minutes
30 minutes
1 hour
2 hours
4 hours
12 hours
1 day		
PT10M
PT15M
PT30M
PT1H
PT2H
PT4H
PT12H
P1D		




<= 11
15 minutes
15 minutes
30 minutes
1 hour
2 hours
4 hours
12 hours
1 day		
PT15M
PT30M
PT1H
PT2H
PT4H
PT12H
P1D		




<= 35
30 minutes
30 minutes
1 hour
2 hours
4 hours
12 hours
1 day		
PT30M
PT1H
PT2H
PT4H
PT12H
P1D		




<= 49
1 hour
1 hour
2 hours
4 hours
12 hours
1 day
1 week		
PT1H
PT2H
PT4H
PT12H
P1D
P1W		




<= 91
2 hours
2 hours
4 hours
12 hours
1 day
1 week		
PT2H
PT4H
PT12H
P1D
P1W		




<= 182
4 hours
4 hours
12 hours
1 day
1 week
1 month		
PT4H
PT12H
P1D
P1W
P1M		




<= 371
12 hours
12 hours
1 day
1 week
1 month		
PT12H
P1D
P1W
P1M		





While this endpoint will accept additional granularity options, the above are recommended for the best performance.


SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
query Parameters
pointIds
Array of strings or null <uuid> 
Array of unique point IDs given by Willow


 
 Example:  pointIds=pointIds=0fcd55ad-251d-4111-bed9-de32c7addb52&pointIds=7461183c-139f-4e60-95ba-6a6b3d3f9321
startDate
required
string or null <date-time> 
Start date and time of specific results desired in ISO 8601 format


 
 Example:  startDate=2020-05-23T22:12:21.047Z
endDate
required
string or null <date-time> 
End date and time of specific results desired in ISO 8601 format


 
 Example:  endDate=2020-05-30T22:12:21.047Z
granularity
string or null <ISO8601> 
Interval at which the time series values should be aggregated, aligned, and returned in ISO 8601 format


 
 Example:  granularity=P0DT1H
Responses 
200
Success


401
Unauthorized


403
Forbidden


get/sites/{siteId}/timemachine
Request samples 
Response samples 
application/json
[
  • {
    • "pointId": "0fcd55ad-251d-4111-bed9-de32c7addb52",
    • "name": "zone air temp sensor",
    • "type": "analog",
    • "unit": "degC",
    • "data": [
      • {
        • "timestamp": "2020-05-27T16:00:00.000Z",
        • "average": "22.5",
        • "minimum": "18.9",
        • "maximum": "26.8",
        • "sum": "120.8",
        • "onCount": "5",
        • "offCount": "4"
        },
      • {
        • "timestamp": "2020-05-27T17:00:00.000Z",
        • "average": "24.1",
        • "minimum": "20.7",
        • "maximum": "25.9",
        • "sum": "110.4",
        • "onCount": "3",
        • "offCount": "6"
        }
      ]
    }
]
Trend Logs
Trend logs return an array of timestamped Point values. Because Live Data is often captured at intervals on the order of minutes, this endpoint can return a large amount of data with a single API call. Therefore, we recommend leveraging the query parameters to return a specific Point and interval by specifying the desired startDate and endDate.


Retrieve a point trend log
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
pointId
required
string <uuid> 
The unique ID of the point which is given by Willow


 
 Example:  0fcd55ad-251d-4111-bed9-de32c7addb52
query Parameters
startDate
string or null <date-time> 
Start date and time of specific results desired in ISO 8601 format


 
 Example:  startDate=2020-05-23T22:12:21.047Z
endDate
string or null <date-time> 
End date and time of specific results desired in ISO 8601 format


 
 Example:  endDate=2020-05-30T22:12:21.047Z
Responses 
200
Success


401
Unauthorized


403
Forbidden


get/sites/{siteId}/points/{pointId}/trendlog
Request samples 
Response samples 
application/json
{
  • "continuationToken": "string",
  • "point": {
    • "id": "0fcd55ad-251d-4111-bed9-de32c7addb52",
    • "name": "zone air temp sensor",
    • "type": "analog",
    • "equipmentIds": [
      • "12a81670-1b05-465f-940f-ec5371843e34",
      • "09ade39f-a69a-4d95-a8e0-dc28309874e4"
      ],
    • "unit": "degC",
    • "interval": 1200,
    • "metadata": [
      • {
        • "key": "manufacturer",
        • "value": "omega",
        • "dataType": "string"
        }
      ],
    • "tags": [
      • "zone",
      • "air",
      • "temp",
      • "sensor"
      ],
    • "trendlog": [
      • {
        • "timestamp": "2020-05-27T16:48:20.773Z",
        • "value": "22.5863236278265"
        },
      • {
        • "timestamp": "2020-05-25T02:20:00.000Z",
        • "value": "21.2955047175106"
        }
      ]
    },
  • "data": [
    • {
      • "timestamp": "2019-08-24T14:15:22Z",
      • "value": "string"
      }
    ]
}
Create point trend logsDeprecated
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
query Parameters
startDate
string or null <date-time> 
Start date and time of specific results desired in ISO 8601 format


 
 Example:  startDate=2020-05-23T22:12:21.047Z
endDate
string or null <date-time> 
End date and time of specific results desired in ISO 8601 format


 
 Example:  endDate=2020-05-30T22:12:21.047Z
Request Body schema: 
 Array 
string <uuid> 
 
Responses 
200
Success


401
Unauthorized


403
Forbidden


post/sites/{siteId}/trendlogs
Request samples 
[
  • "497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
Response samples 
application/json
[
  • {
    • "continuationToken": "string",
    • "point": {
      • "id": "0fcd55ad-251d-4111-bed9-de32c7addb52",
      • "name": "zone air temp sensor",
      • "type": "analog",
      • "equipmentIds": [
        • "12a81670-1b05-465f-940f-ec5371843e34",
        • "09ade39f-a69a-4d95-a8e0-dc28309874e4"
        ],
      • "unit": "degC",
      • "interval": 1200,
      • "metadata": [
        • {
          • "key": "manufacturer",
          • "value": "omega",
          • "dataType": "string"
          }
        ],
      • "tags": [
        • "zone",
        • "air",
        • "temp",
        • "sensor"
        ],
      • "trendlog": [
        • {
          • "timestamp": "2020-05-27T16:48:20.773Z",
          • "value": "22.5863236278265"
          },
        • {
          • "timestamp": "2020-05-25T02:20:00.000Z",
          • "value": "21.2955047175106"
          }
        ]
      },
    • "data": [
      • {
        • "timestamp": "2019-08-24T14:15:22Z",
        • "value": "string"
        }
      ]
    }
]
List point trend logs
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
query Parameters
pointIds
Array of strings or null <uuid> 
Array of unique point IDs given by Willow


 
 Example:  pointIds=pointIds=0fcd55ad-251d-4111-bed9-de32c7addb52&pointIds=7461183c-139f-4e60-95ba-6a6b3d3f9321
startDate
string or null <date-time> 
Start date and time of specific results desired in ISO 8601 format


 
 Example:  startDate=2020-05-23T22:12:21.047Z
endDate
string or null <date-time> 
End date and time of specific results desired in ISO 8601 format


 
 Example:  endDate=2020-05-30T22:12:21.047Z
Responses 
200
Success


401
Unauthorized


403
Forbidden


get/sites/{siteId}/trendlogs
Request samples 
Response samples 
application/json
[
  • {
    • "continuationToken": "string",
    • "point": {
      • "id": "0fcd55ad-251d-4111-bed9-de32c7addb52",
      • "name": "zone air temp sensor",
      • "type": "analog",
      • "equipmentIds": [
        • "12a81670-1b05-465f-940f-ec5371843e34",
        • "09ade39f-a69a-4d95-a8e0-dc28309874e4"
        ],
      • "unit": "degC",
      • "interval": 1200,
      • "metadata": [
        • {
          • "key": "manufacturer",
          • "value": "omega",
          • "dataType": "string"
          }
        ],
      • "tags": [
        • "zone",
        • "air",
        • "temp",
        • "sensor"
        ],
      • "trendlog": [
        • {
          • "timestamp": "2020-05-27T16:48:20.773Z",
          • "value": "22.5863236278265"
          },
        • {
          • "timestamp": "2020-05-25T02:20:00.000Z",
          • "value": "21.2955047175106"
          }
        ]
      },
    • "data": [
      • {
        • "timestamp": "2019-08-24T14:15:22Z",
        • "value": "string"
        }
      ]
    }
]
Insights
Insights are often referred to as faults or notifications and are generated within the digital twin based on rules and analytics that trigger from Live and Trended data. Likewise, Insights that are generated outside the Willow platform can be created using this endpoint.


List insights
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
Responses 
200
Success


401
Unauthorized


403
Forbidden


get/sites/{siteId}/insights
Request samples 
Response samples 
application/json
[
  • {
    • "id": "8cf1743b-fcb7-44c8-9b6d-0038323ba9e5",
    • "sequenceNumber": "av-I-465",
    • "floorCode": "L010",
    • "equipmentId": "6be53768-811e-4db8-baee-471a01498df7",
    • "type": "fault",
    • "name": "258adba7",
    • "priority": 3,
    • "status": "inProgress",
    • "state": "active",
    • "updatedDate": "2020-04-28T13:46:01.919Z",
    • "externalId": "20200428_d4b43edf",
    • "externalStatus": "active",
    • "externalMetadata": "string"
    }
]
Create an insight
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
Request Body schema: 
floorCode
string or null
 
equipmentId
string or null <uuid> 
 
type
string (InsightType) 
The insight type


 Enum: "fault" "energyOptimisation"  
name
string or null
 
description
string or null
 
priority
integer <int32> 
 
state
string (InsightState) 
The state of the insight


 Enum: "inactive" "active" "archived"  
occurredDate
string <date-time> 
 
detectedDate
string <date-time> 
 
externalId
string or null
 
externalStatus
string or null
 
externalMetadata
string or null
 
Responses 
200
Success


401
Unauthorized


403
Forbidden


post/sites/{siteId}/insights
Request samples 
{
  • "floorCode": "string",
  • "equipmentId": "d2a795e1-f645-4e24-bc0a-ab1965048fcc",
  • "type": "fault",
  • "name": "string",
  • "description": "string",
  • "priority": 0,
  • "state": "active",
  • "occurredDate": "2019-08-24T14:15:22Z",
  • "detectedDate": "2019-08-24T14:15:22Z",
  • "externalId": "string",
  • "externalStatus": "string",
  • "externalMetadata": "string"
}
Response samples 
application/json
{
  • "id": "8cf1743b-fcb7-44c8-9b6d-0038323ba9e5",
  • "sequenceNumber": "av-I-465",
  • "floorCode": "L010",
  • "equipmentId": "6be53768-811e-4db8-baee-471a01498df7",
  • "type": "fault",
  • "name": "258adba7",
  • "priority": 3,
  • "status": "inProgress",
  • "state": "active",
  • "updatedDate": "2020-04-28T13:46:01.919Z",
  • "externalId": "20200428_d4b43edf",
  • "externalStatus": "active",
  • "externalMetadata": "string",
  • "customerId": "3fc260f3-3e91-470b-8285-15a11c799491",
  • "siteId": "1218614a-9822-43c5-94ca-1ecc29ab80b0",
  • "description": "Chilled Water Pump CWP-01.1 is running when Chiller CH-01 is off.",
  • "createdDate": "2020-05-28T01:25:02.881Z",
  • "occurredDate": "2020-05-28T00:33:02.836Z",
  • "detectedDate": "2020-05-28T01:02:02.836Z"
}
Retrieve an insight
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
insightId
required
string <uuid> 
The unique ID of the insight which is given by Willow


 
 Example:  8cf1743b-fcb7-44c8-9b6d-0038323ba9e5
Responses 
200
Success


401
Unauthorized


403
Forbidden


get/sites/{siteId}/insights/{insightId}
Request samples 
Response samples 
application/json
{
  • "id": "8cf1743b-fcb7-44c8-9b6d-0038323ba9e5",
  • "sequenceNumber": "av-I-465",
  • "floorCode": "L010",
  • "equipmentId": "6be53768-811e-4db8-baee-471a01498df7",
  • "type": "fault",
  • "name": "258adba7",
  • "priority": 3,
  • "status": "inProgress",
  • "state": "active",
  • "updatedDate": "2020-04-28T13:46:01.919Z",
  • "externalId": "20200428_d4b43edf",
  • "externalStatus": "active",
  • "externalMetadata": "string",
  • "customerId": "3fc260f3-3e91-470b-8285-15a11c799491",
  • "siteId": "1218614a-9822-43c5-94ca-1ecc29ab80b0",
  • "description": "Chilled Water Pump CWP-01.1 is running when Chiller CH-01 is off.",
  • "createdDate": "2020-05-28T01:25:02.881Z",
  • "occurredDate": "2020-05-28T00:33:02.836Z",
  • "detectedDate": "2020-05-28T01:02:02.836Z"
}
Update an insight
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
insightId
required
string <uuid> 
The unique ID of the insight which is given by Willow


 
 Example:  8cf1743b-fcb7-44c8-9b6d-0038323ba9e5
Request Body schema: 
name
string or null
 
description
string or null
 
priority
integer or null <int32> 
 
state
string (InsightState) 
The state of the insight


 Enum: "inactive" "active" "archived"  
occurredDate
string or null <date-time> 
 
detectedDate
string or null <date-time> 
 
externalId
string or null
 
externalStatus
string or null
 
externalMetadata
string or null
 
Responses 
200
Success


401
Unauthorized


403
Forbidden


put/sites/{siteId}/insights/{insightId}
Request samples 
{
  • "name": "string",
  • "description": "string",
  • "priority": 0,
  • "state": "active",
  • "occurredDate": "2019-08-24T14:15:22Z",
  • "detectedDate": "2019-08-24T14:15:22Z",
  • "externalId": "string",
  • "externalStatus": "string",
  • "externalMetadata": "string"
}
Response samples 
application/json
{
  • "id": "8cf1743b-fcb7-44c8-9b6d-0038323ba9e5",
  • "sequenceNumber": "av-I-465",
  • "floorCode": "L010",
  • "equipmentId": "6be53768-811e-4db8-baee-471a01498df7",
  • "type": "fault",
  • "name": "258adba7",
  • "priority": 3,
  • "status": "inProgress",
  • "state": "active",
  • "updatedDate": "2020-04-28T13:46:01.919Z",
  • "externalId": "20200428_d4b43edf",
  • "externalStatus": "active",
  • "externalMetadata": "string",
  • "customerId": "3fc260f3-3e91-470b-8285-15a11c799491",
  • "siteId": "1218614a-9822-43c5-94ca-1ecc29ab80b0",
  • "description": "Chilled Water Pump CWP-01.1 is running when Chiller CH-01 is off.",
  • "createdDate": "2020-05-28T01:25:02.881Z",
  • "occurredDate": "2020-05-28T00:33:02.836Z",
  • "detectedDate": "2020-05-28T01:02:02.836Z"
}
Delete an insight
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
insightId
required
string <uuid> 
The unique ID of the insight which is given by Willow


 
 Example:  8cf1743b-fcb7-44c8-9b6d-0038323ba9e5
Responses 
204
Success


401
Unauthorized


403
Forbidden


delete/sites/{siteId}/insights/{insightId}
Request samples 
Tickets
Tickets are used to describe both service requests and incidents that can be generated and tracked within the Willow platform. When a ticket is generated, a pre-defined workflow will determine how the problem is responded to and remedied. The Willow platform can automate the creation of tickets when an Insight is generated. Tickets that are generated outside the Willow platform can be created and updated using this endpoint.


List tickets
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
Responses 
200
Success


401
Unauthorized


403
Forbidden


get/sites/{siteId}/tickets
Request samples 
Response samples 
application/json
[
  • {
    • "id": "9740da10-9f90-4623-9d48-51d14c093526",
    • "sequenceNumber": "av-T-4",
    • "floorCode": "L010",
    • "priority": 2,
    • "status": "inProgress",
    • "issueType": "equipment",
    • "issueId": "6be53768-811e-4db8-baee-471a01498df7",
    • "issueName": "VAV-10.1",
    • "description": "The area around my workstation is too hot today.",
    • "reporterName": "Michael Bennett",
    • "assigneeType": "customerUser",
    • "assigneeId": "2a4d6a10-72e5-414f-94a3-389967df4a00",
    • "sourceType": "platform",
    • "sourceId": "92913814g-9822-43c5-94gc-1ecf27ac80b2",
    • "externalId": "WHQ-BLDG1-00000789",
    • "dueDate": "2020-05-27T07:00:00.000Z",
    • "createdDate": "2020-05-28T05:17:47.142Z",
    • "updatedDate": "2020-05-28T05:19:00.181Z",
    • "resolvedDate": "2020-05-28T09:14:02.713Z",
    • "closedDate": "2020-05-28T09:14:22.479Z"
    }
]
Create a Ticket
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
Request Body schema: 
floorId
string or null
The unique ID of the floor which is given by Willow


 
priority
integer <int32> 
The code for the priority level. Urgent=1, High=2, Medium=3, Low=4


 
summary
string or null
 
description
string or null
 
status
string (TicketStatus) 
The status of the ticket


 Enum: "open" "reassign" "inProgress" "limitedAvailability" "resolved" "closed"  
externalId
string or null
 
externalStatus
string or null
 
externalMetadata
string or null
 
Responses 
200
Success


401
Unauthorized


403
Forbidden


post/sites/{siteId}/tickets
Request samples 
{
  • "floorId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  • "priority": 2,
  • "summary": "string",
  • "description": "The area around my workstation is too hot today.",
  • "status": "inProgress",
  • "externalId": "string",
  • "externalStatus": "string",
  • "externalMetadata": "string"
}
Response samples 
application/json
{
  • "id": "9740da10-9f90-4623-9d48-51d14c093526",
  • "sequenceNumber": "av-T-4",
  • "floorCode": "L010",
  • "priority": 2,
  • "status": "inProgress",
  • "issueType": "equipment",
  • "issueId": "6be53768-811e-4db8-baee-471a01498df7",
  • "issueName": "VAV-10.1",
  • "description": "The area around my workstation is too hot today.",
  • "reporterName": "Michael Bennett",
  • "assigneeType": "customerUser",
  • "assigneeId": "2a4d6a10-72e5-414f-94a3-389967df4a00",
  • "sourceType": "platform",
  • "sourceId": "92913814g-9822-43c5-94gc-1ecf27ac80b2",
  • "externalId": "WHQ-BLDG1-00000789",
  • "dueDate": "2020-05-27T07:00:00.000Z",
  • "createdDate": "2020-05-28T05:17:47.142Z",
  • "updatedDate": "2020-05-28T05:19:00.181Z",
  • "resolvedDate": "2020-05-28T09:14:02.713Z",
  • "closedDate": "2020-05-28T09:14:22.479Z",
  • "customerId": "3fc260f3-3e91-470b-8285-15a11c799491",
  • "siteId": "1218614a-9822-43c5-94ca-1ecc29ab80b0",
  • "cause": "VAV Box fan stuck",
  • "solution": "Replaced fan motor",
  • "reporterId": "c5260fe8-520d-4513-af62-28439855c48a",
  • "reporterPhone": "(555) 555-5555",
  • "reporterEmail": "mbennett@acmecorp.com",
  • "reporterCompany": "Acme Corp",
  • "externalStatus": "In Progress",
  • "externalMetadata": "string",
  • "attachments": [
    • {
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "type": "image",
      • "fileName": "string",
      • "createdDate": "2019-08-24T14:15:22Z"
      }
    ]
}
Retrieve a ticket
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
ticketId
required
string <uuid> 
The unique ID of the ticket which is given by Willow


 
 Example:  9740da10-9f90-4623-9d48-51d14c093526
Responses 
200
Success


401
Unauthorized


403
Forbidden


get/sites/{siteId}/tickets/{ticketId}
Request samples 
Response samples 
application/json
{
  • "id": "9740da10-9f90-4623-9d48-51d14c093526",
  • "sequenceNumber": "av-T-4",
  • "floorCode": "L010",
  • "priority": 2,
  • "status": "inProgress",
  • "issueType": "equipment",
  • "issueId": "6be53768-811e-4db8-baee-471a01498df7",
  • "issueName": "VAV-10.1",
  • "description": "The area around my workstation is too hot today.",
  • "reporterName": "Michael Bennett",
  • "assigneeType": "customerUser",
  • "assigneeId": "2a4d6a10-72e5-414f-94a3-389967df4a00",
  • "sourceType": "platform",
  • "sourceId": "92913814g-9822-43c5-94gc-1ecf27ac80b2",
  • "externalId": "WHQ-BLDG1-00000789",
  • "dueDate": "2020-05-27T07:00:00.000Z",
  • "createdDate": "2020-05-28T05:17:47.142Z",
  • "updatedDate": "2020-05-28T05:19:00.181Z",
  • "resolvedDate": "2020-05-28T09:14:02.713Z",
  • "closedDate": "2020-05-28T09:14:22.479Z",
  • "customerId": "3fc260f3-3e91-470b-8285-15a11c799491",
  • "siteId": "1218614a-9822-43c5-94ca-1ecc29ab80b0",
  • "cause": "VAV Box fan stuck",
  • "solution": "Replaced fan motor",
  • "reporterId": "c5260fe8-520d-4513-af62-28439855c48a",
  • "reporterPhone": "(555) 555-5555",
  • "reporterEmail": "mbennett@acmecorp.com",
  • "reporterCompany": "Acme Corp",
  • "externalStatus": "In Progress",
  • "externalMetadata": "string",
  • "attachments": [
    • {
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "type": "image",
      • "fileName": "string",
      • "createdDate": "2019-08-24T14:15:22Z"
      }
    ]
}
Update a ticket
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
ticketId
required
string <uuid> 
The unique ID of the ticket which is given by Willow


 
 Example:  9740da10-9f90-4623-9d48-51d14c093526
Request Body schema: 
priority
integer or null <int32> 
 
status
string (TicketStatus) 
The status of the ticket


 Enum: "open" "reassign" "inProgress" "limitedAvailability" "resolved" "closed"  
floorCode
string or null
 
summary
string or null
 
description
string or null
 
cause
string or null
 
solution
string or null
 
assigneeType
string (TicketAssigneeType) 
The user type of who is assigned to work on the ticket


 Enum: "noAssignee" "contractor" "customerUser"  
assigneeId
string or null <uuid> 
 
dueDate
string or null <date-time> 
 
Responses 
200
Success


401
Unauthorized


403
Forbidden


put/sites/{siteId}/tickets/{ticketId}
Request samples 
{
  • "priority": 0,
  • "status": "inProgress",
  • "floorCode": "string",
  • "summary": "string",
  • "description": "string",
  • "cause": "string",
  • "solution": "string",
  • "assigneeType": "customerUser",
  • "assigneeId": "665a9750-71bd-4b96-bacd-9efa4ae022dd",
  • "dueDate": "2019-08-24T14:15:22Z"
}
Response samples 
application/json
{
  • "id": "9740da10-9f90-4623-9d48-51d14c093526",
  • "sequenceNumber": "av-T-4",
  • "floorCode": "L010",
  • "priority": 2,
  • "status": "inProgress",
  • "issueType": "equipment",
  • "issueId": "6be53768-811e-4db8-baee-471a01498df7",
  • "issueName": "VAV-10.1",
  • "description": "The area around my workstation is too hot today.",
  • "reporterName": "Michael Bennett",
  • "assigneeType": "customerUser",
  • "assigneeId": "2a4d6a10-72e5-414f-94a3-389967df4a00",
  • "sourceType": "platform",
  • "sourceId": "92913814g-9822-43c5-94gc-1ecf27ac80b2",
  • "externalId": "WHQ-BLDG1-00000789",
  • "dueDate": "2020-05-27T07:00:00.000Z",
  • "createdDate": "2020-05-28T05:17:47.142Z",
  • "updatedDate": "2020-05-28T05:19:00.181Z",
  • "resolvedDate": "2020-05-28T09:14:02.713Z",
  • "closedDate": "2020-05-28T09:14:22.479Z",
  • "customerId": "3fc260f3-3e91-470b-8285-15a11c799491",
  • "siteId": "1218614a-9822-43c5-94ca-1ecc29ab80b0",
  • "cause": "VAV Box fan stuck",
  • "solution": "Replaced fan motor",
  • "reporterId": "c5260fe8-520d-4513-af62-28439855c48a",
  • "reporterPhone": "(555) 555-5555",
  • "reporterEmail": "mbennett@acmecorp.com",
  • "reporterCompany": "Acme Corp",
  • "externalStatus": "In Progress",
  • "externalMetadata": "string",
  • "attachments": [
    • {
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "type": "image",
      • "fileName": "string",
      • "createdDate": "2019-08-24T14:15:22Z"
      }
    ]
}
Create Multiple Tickets
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
Request Body schema: 
 Array 
floorId
string or null
The unique ID of the floor which is given by Willow


 
priority
integer <int32> 
The code for the priority level. Urgent=1, High=2, Medium=3, Low=4


 
summary
string or null
 
description
string or null
 
status
string (TicketStatus) 
The status of the ticket


 Enum: "open" "reassign" "inProgress" "limitedAvailability" "resolved" "closed"  
externalId
string or null
 
externalStatus
string or null
 
externalMetadata
string or null
 
Responses 
200
Success


401
Unauthorized


403
Forbidden


post/sites/{siteId}/tickets/batch
Request samples 
[
  • {
    • "floorId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    • "priority": 2,
    • "summary": "string",
    • "description": "The area around my workstation is too hot today.",
    • "status": "inProgress",
    • "externalId": "string",
    • "externalStatus": "string",
    • "externalMetadata": "string"
    }
]
Copyright © 2022 Willow. All rights reserved.