Skip to content
REST API Reference/
/
List twins

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

List twins

Request

Security
oauth2
Bodyapplication/jsonrequired

Instance of GetTwinsRequest.

modelFilterobject

Model Filter Class for Get Twins Request.

relationshipFilterobject

Get Twins Request Relationship Filter

locationFilterobject

Location Filter Class for Get Twins Request.

dateFilterobject

Date Filter Class for Get Twins Request.

propertyFilterobject

Represents a group of filter specifications. Contains a list of individual filter specifications.

includeobject

Include Option Class for Get Twins Request.

pageSizeinteger(int32)[ 1 .. 1000 ]

Maximum number of twins to return per request. Minimum is 1 and Maximum is 1000.

continuationTokennull or string

Continuation Token for subsequent requests. Set the Continuation token for the initial request.

application/json
{
  "modelFilter": {
    "modelIds": [ … ],
    "exactModelMatch": true
  },
  "relationshipFilter": {
    "relationshipDirection": "Incoming",
    "relationshipNames": null,
    "relatedModelFilter": { … }
  },
  "locationFilter": {
    "locationId": null
  },
  "dateFilter": {
    "lastUpdatedAfter": null,
    "lastUpdatedBefore": null
  },
  "propertyFilter": {
    "field": null,
    "operator": null,
    "value": { … },
    "filterConditionOperator": "And",
    "filters": [ … ]
  },
  "ModelFilter": {
    "ModelIds": [ … ],
    "ExactModelMatch": true
  },
  "RelationshipFilter": {
    "RelationshipDirection": "Outgoing",
    "RelationshipNames": [ … ],
    "RelatedModelFilter": { … }
  },
  "LocationFilter": {
    "LocationId": null
  },
  "DateFilter": {
    "LastUpdatedAfter": "2024-09-23T15:16:03.405Z",
    "LastUpdatedBefore": "2024-09-23T15:16:03.405Z"
  },
  "PropertyFilter": {
    "Filters": [ … ],
    "FilterConditionOperator": "and"
  },
  "Include": {
    "OutgoingRelationships": true,
    "IncomingRelationships": true
  },
  "PageSize": 101,
  "ContinuationToken": null
}

Responses

Page`1.

Bodyapplication/json
contentArray of objects(DigitalTwinWithRelationships)

Gets or sets the collection of items contained in the response.

Example: [{"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":"1.3","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.4062816Z"}}},"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"}]}]
continuationTokennull or string

Gets or sets the continuation token used to retrieve the next page of results in a paginated operation.

Response
application/json
{
  "content": [
    { … }
  ],
  "continuationToken": null
}

Create or replace a twin.

Request

Security
oauth2
Bodyapplication/jsonrequired

Instance of DigitalTwin.

idstringnon-emptyrequired

The unique Id of the digital twin.

Example: "TW-DD-II-L01"
modelIdstringnon-emptyrequired

Digital Twin Model Identifier.

Example: "dtmi:com:willowinc:Level;1"
lastUpdateTimenull or string(date-time)

Timestamp when the twin was last updated in ISO 8601 format.

Example: "2024-08-30T03:49:30.4062816+00:00"
contentsobject

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

Example: {"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":"1.3","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.4062816Z"}}}
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": [ … ],
    "name": "Floor_1",
    "uniqueID": "a360cf30-c112-40a1-b4b4-f65da82fa9e8",
    "externalID": "FLRPXxxxxxxxxxxxxxxxx",
    "code": "L01",
    "siteID": "104bd33c-a697-4027-b6a6-677e30a53d09",
    "alternateClassification": { … },
    "externalIds": { … },
    "area": { … }
  }
}

Responses

Created Twin .

Bodyapplication/json
idstringnon-emptyrequired

The unique Id of the digital twin.

Example: "TW-DD-II-L01"
modelIdstringnon-emptyrequired

Digital Twin Model Identifier.

Example: "dtmi:com:willowinc:Level;1"
lastUpdateTimenull or string(date-time)

Timestamp when the twin was last updated in ISO 8601 format.

Example: "2024-08-30T03:49:30.4062816+00:00"
contentsobject

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

Example: {"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":"1.3","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.4062816Z"}}}
Response
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": [ … ],
    "name": "Floor_1",
    "uniqueID": "a360cf30-c112-40a1-b4b4-f65da82fa9e8",
    "externalID": "FLRPXxxxxxxxxxxxxxxxx",
    "code": "L01",
    "siteID": "104bd33c-a697-4027-b6a6-677e30a53d09",
    "alternateClassification": { … },
    "externalIds": { … },
    "area": { … }
  }
}

Retrieve a twin

Request

Security
oauth2
Path
idstringrequired

Id of the twin

Query
includeRelationshipsboolean

When true, the response includes the incoming and outgoing relationships

Default false
No request payload

Responses

Twin information successfully retrieved.

Bodyapplication/json
idstringnon-emptyrequired

The unique Id of the digital twin.

Example: "TW-DD-II-L01"
modelIdstringnon-emptyrequired

Digital Twin Model Identifier.

Example: "dtmi:com:willowinc:Level;1"
lastUpdateTimenull or string(date-time)

Timestamp when the twin was last updated in ISO 8601 format.

Example: "2024-08-30T03:49:30.4062816+00:00"
contentsobject

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

Example: {"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":"1.3","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.4062816Z"}}}
incomingRelationshipsArray of objects(DigitalTwinRelationship)

Incoming relationships

Example: [{"Id":"Room-L01-100_isPartOf_TW-DD-II-L01","targetId":"TW-DD-II-L01","sourceId":"Room-L01-100","name":"isPartOf"}]
outgoingRelationshipsArray of objects(DigitalTwinRelationship)

Outgoing relationships

Example: [{"Id":"TW-DD-II-L01_isPartOf_BLDG-1","targetId":"BLDG-1","sourceId":"TW-DD-II-L01","name":"isPartOf"}]
Response
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": [ … ],
    "name": "Floor_1",
    "uniqueID": "a360cf30-c112-40a1-b4b4-f65da82fa9e8",
    "externalID": "FLRPXxxxxxxxxxxxxxxxx",
    "code": "L01",
    "siteID": "104bd33c-a697-4027-b6a6-677e30a53d09",
    "alternateClassification": { … },
    "externalIds": { … },
    "area": { … }
  },
  "incomingRelationships": [
    { … }
  ],
  "outgoingRelationships": [
    { … }
  ]
}

Update a twin

Request

Security
oauth2
Path
idstringrequired

Id of the twin

Bodyapplication/jsonrequired

List of Patch Operations.

Array [
operationTypestring
Enum"Add""Remove""Replace""Move""Copy""Test""Invalid"
pathnull or string
opnull or string
fromnull or string
valueobject
]
application/json
[
  {
    "operationType": "Add",
    "path": null,
    "op": null,
    "from": null,
    "value": { … }
  }
]

Responses

Bodyapplication/json
typenull or string
titlenull or string
statusnull or integer(int32)
detailnull or string
instancenull or string
errorsobject
property name*anyadditional property
Response
application/json
{
  "type": null,
  "title": null,
  "status": null,
  "detail": null,
  "instance": null,
  "errors": {
    "property1": [ … ],
    "property2": [ … ]
  },
  "property1": null,
  "property2": null
}

Retrieve multiple twins

Request

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.

Security
oauth2
Query
includeRelationshipsboolean

When true, the response includes the incoming and outgoing relationships

Default false
Bodyapplication/jsonrequired

Array of twin Ids.

Array [
string
]
application/json
[
  "string"
]

Responses

Twin information

Bodyapplication/jsonArray [
idstringnon-emptyrequired

The unique Id of the digital twin.

Example: "TW-DD-II-L01"
modelIdstringnon-emptyrequired

Digital Twin Model Identifier.

Example: "dtmi:com:willowinc:Level;1"
lastUpdateTimenull or string(date-time)

Timestamp when the twin was last updated in ISO 8601 format.

Example: "2024-08-30T03:49:30.4062816+00:00"
contentsobject

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

Example: {"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":"1.3","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.4062816Z"}}}
incomingRelationshipsArray of objects(DigitalTwinRelationship)

Incoming relationships

Example: [{"Id":"Room-L01-100_isPartOf_TW-DD-II-L01","targetId":"TW-DD-II-L01","sourceId":"Room-L01-100","name":"isPartOf"}]
outgoingRelationshipsArray of objects(DigitalTwinRelationship)

Outgoing relationships

Example: [{"Id":"TW-DD-II-L01_isPartOf_BLDG-1","targetId":"BLDG-1","sourceId":"TW-DD-II-L01","name":"isPartOf"}]
]
Response
application/json
[
  {
    "id": "TW-DD-II-L01",
    "modelId": "dtmi:com:willowinc:Level;1",
    "lastUpdateTime": "2024-08-30T03:49:30.4062816+00:00",
    "contents": { … },
    "incomingRelationships": [ … ],
    "outgoingRelationships": [ … ]
  }
]

Retrieve Twin graph.

Request

Retrieves a twin by its ID along with its associated twins as defined in the request. The relationships field in the request is optional. Twins will be returned in the response even if the nested relationships failed to find a twin. Similar to a sql outer join semantics.

Security
oauth2
Bodyapplication/jsonrequired

Instance of GetTwinGraphRequest.

aliasstring

Name of the Primary Twin Collection.

Example: "Twin"
idstring

DtId of the Primary Twin.

Example: "PNT2Uga"
relationshipsArray of objects(RequestGraphRelationship)

Graph relationship definition to retrieve the related twins.

Example: [{"alias":"Components","relationshipNames":["isPartOf"],"modelNames":["dtmi:com:willowinc:Fan;1"],"exactModelMatch":false,"direction":"Incoming","relationship":{"alias":"ComponentPoints","relationshipNames":["isCapabilityOf"],"modelNames":[],"exactModelMatch":false,"direction":"Incoming","relationship":{}}},{"alias":"TwinPoints","relationshipNames":["isCapabilityOf"],"modelNames":[],"exactModelMatch":false,"direction":"Incoming","relationship":{}}]
application/json
{
  "id": "PNT2Uga",
  "alias": "Twin",
  "relationships": [
    { … },
    { … }
  ]
}

Responses

Twin Graph Response.

Bodyapplication/json
property name*Array of objects(DigitalTwinWithRelationships)additional property
Example: [{"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":"1.3","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.4062816Z"}}},"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"}]}]
Response
application/json
{
  "property1": [
    { … }
  ],
  "property2": [
    { … }
  ]
}

Count twins

Request

Security
oauth2
Bodyapplication/jsonrequired
modelFilterobject

Model Filter Class for Get Twins Request.

relationshipFilterobject

Get Twins Request Relationship Filter

locationFilterobject

Location Filter Class for Get Twins Request.

dateFilterobject

Date Filter Class for Get Twins Request.

propertyFilterobject

Represents a group of filter specifications. Contains a list of individual filter specifications.

application/json
{
  "modelFilter": {
    "modelIds": [ … ],
    "exactModelMatch": true
  },
  "relationshipFilter": {
    "relationshipDirection": "Incoming",
    "relationshipNames": null,
    "relatedModelFilter": { … }
  },
  "locationFilter": {
    "locationId": null
  },
  "dateFilter": {
    "lastUpdatedAfter": null,
    "lastUpdatedBefore": null
  },
  "propertyFilter": {
    "field": null,
    "operator": null,
    "value": { … },
    "filterConditionOperator": "And",
    "filters": [ … ]
  },
  "ModelFilter": {
    "ModelIds": [ … ],
    "ExactModelMatch": true
  },
  "RelationshipFilter": {
    "RelationshipDirection": "Outgoing",
    "RelationshipNames": [ … ],
    "RelatedModelFilter": { … }
  },
  "LocationFilter": {
    "LocationId": null
  },
  "DateFilter": {
    "LastUpdatedAfter": "2024-09-23T15:16:03.405Z",
    "LastUpdatedBefore": "2024-09-23T15:16:03.405Z"
  },
  "PropertyFilter": {
    "Filters": [ … ],
    "FilterConditionOperator": "and"
  }
}

Responses

Bodyapplication/json
integer(int32)
Response
application/json
0

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

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.