Skip to content
/Relationships

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

Create or replace a twin relationship

Request

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.

Security
oauth2
Bodyapplication/jsonrequired

Instance of DigitalTwinRelationship.

idstring

The unique Id of the relationship entity.

targetIdstringnon-emptyrequired

The Id of the target twin.

Example: "Chiller-1"
sourceIdstringnon-emptyrequired

The Id of the source twin.

Example: "AHU-1"
namestringnon-emptyrequired

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

Example: "isFedBy"
propertiesobject

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

Example: {"substance":"ChilledWater"}
application/json
{
  "Id": "AHU-1_isFedBy_substance_ChilledWater_Chiller-1",
  "targetId": "Chiller-1",
  "sourceId": "AHU-1",
  "name": "isFedBy",
  "properties": {
    "substance": "ChilledWater"
  }
}

Responses

Created or Updated DigitalTwinRelationship.

Bodyapplication/json
idstring

The unique Id of the relationship entity.

targetIdstringnon-emptyrequired

The Id of the target twin.

Example: "Chiller-1"
sourceIdstringnon-emptyrequired

The Id of the source twin.

Example: "AHU-1"
namestringnon-emptyrequired

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

Example: "isFedBy"
propertiesobject

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

Example: {"substance":"ChilledWater"}
Response
application/json
{
  "Id": "AHU-1_isFedBy_substance_ChilledWater_Chiller-1",
  "targetId": "Chiller-1",
  "sourceId": "AHU-1",
  "name": "isFedBy",
  "properties": {
    "substance": "ChilledWater"
  }
}

Retrieve a twin relationship

Request

Security
oauth2
Path
twinIdstringrequired

Id of the twin. SourceId for the relationship.

relationshipIdstringrequired

Id of the relationship

No request payload

Responses

Target relationship retrieved

Bodyapplication/json
idstring

The unique Id of the relationship entity.

targetIdstringnon-emptyrequired

The Id of the target twin.

Example: "Chiller-1"
sourceIdstringnon-emptyrequired

The Id of the source twin.

Example: "AHU-1"
namestringnon-emptyrequired

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

Example: "isFedBy"
propertiesobject

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

Example: {"substance":"ChilledWater"}
Response
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

Request

Security
oauth2
Path
twinIdstringrequired

Id of the source twin

Query
relationshipNamestring or null

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

No request payload

Responses

Target relationships retrieved.

Bodyapplication/jsonArray [
idstring

The unique Id of the relationship entity.

targetIdstringnon-emptyrequired

The Id of the target twin.

Example: "Chiller-1"
sourceIdstringnon-emptyrequired

The Id of the source twin.

Example: "AHU-1"
namestringnon-emptyrequired

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

Example: "isFedBy"
propertiesobject

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

Example: {"substance":"ChilledWater"}
]
Response
application/json
[
  {
    "Id": "AHU-1_isFedBy_substance_ChilledWater_Chiller-1",
    "targetId": "Chiller-1",
    "sourceId": "AHU-1",
    "name": "isFedBy",
    "properties": { … }
  }
]

List incoming relationships for a twin

Request

Security
oauth2
Path
twinIdstringrequired

Id of the target twin

No request payload

Responses

Relationships retrieved.

Bodyapplication/jsonArray [
idstring

The unique Id of the relationship entity.

targetIdstringnon-emptyrequired

The Id of the target twin.

Example: "Chiller-1"
sourceIdstringnon-emptyrequired

The Id of the source twin.

Example: "AHU-1"
namestringnon-emptyrequired

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

Example: "isFedBy"
propertiesobject

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

Example: {"substance":"ChilledWater"}
]
Response
application/json
[
  {
    "Id": "AHU-1_isFedBy_substance_ChilledWater_Chiller-1",
    "targetId": "Chiller-1",
    "sourceId": "AHU-1",
    "name": "isFedBy",
    "properties": { … }
  }
]

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

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.