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.

Security
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.


403
Unauthorized: You do not have permission to access this twin.


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": "2025-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: null null null null null null null  
path
string or null
 
op
string or null
 
from
string or null
 
object
 
Responses 
400
403
Unauthorized: You do not have permission to access this twin.


404
Twin not found with the supplied Id.


patch/twins/{id}
Request samples 
application/json
[
  • {
    • "operationType": "Add",
    • "path": "string",
    • "op": "string",
    • "from": "string",
    • "value": {
      • "property1": null,
      • "property2": null
      }
    }
]
Response samples 
application/json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "property1": null,
  • "property2": null,
  • "errors": {
    • "property1": [
      • "string"
      ],
    • "property2": [
      • "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
403
Unauthorized: You do not have permission to access these twins.


404
Twin not found.


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": "2025-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"
        }
      ]
    }
]
Retrieve Twin graph. Retrieves a twin by its ID along with its associated twins as defined in the request.
GetTwinGraphRequest.Relationships field 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.


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


alias
string
Name of the Primary Twin Collection.


 
id
string
DtId of the Primary Twin.


 
Array of objects (RequestGraphRelationship) 
Graph relationship definition to retrieve the related twins.


 
Responses 
200
Twin Graph Response.


403
Unauthorized: You do not have permission to access this twin.


404
Twin not found.


504
post/twins/graph
Request samples 
application/json
{
  • "id": "PNT2Uga",
  • "alias": "Twin",
  • "relationships": [
    • {
      • "alias": "Components",
      • "relationshipNames": [
        • "isPartOf"
        ],
      • "modelNames": [
        • "dtmi:com:willowinc:Fan;1"
        ],
      • "direction": "Incoming",
      • "relationship": {
        • "alias": "ComponentPoints",
        • "relationshipNames": [
          • "isCapabilityOf"
          ],
        • "modelNames": [ ],
        • "direction": "Incoming",
        • "relationship": { }
        }
      },
    • {
      • "alias": "TwinPoints",
      • "relationshipNames": [
        • "isCapabilityOf"
        ],
      • "modelNames": [ ],
      • "direction": "Incoming",
      • "relationship": { }
      }
    ]
}
Response samples 
application/json
{
  • "property1": [
    • {
      • "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": "2025-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"
          }
        ]
      }
    ],
  • "property2": [
    • {
      • "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": "2025-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.


object (RequestModelFilter) 
Model Filter Class for Get Twins Request.


 
object (RequestRelationshipFilter) 
Get Twins Request Relationship Filter


 
object (RequestLocationFilter) 
Location Filter Class for Get Twins Request.


 
object (RequestDateFilter) 
Date Filter Class for Get Twins Request.


 
object (RequestPropertyFilter) 
Represents a group of filter specifications. Contains a list of individual filter specifications.


 
object (RequestIncludeOption) 
Include Option Class for Get Twins Request.


 
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": [
      • "string"
      ],
    • "exactModelMatch": true
    },
  • "relationshipFilter": {
    • "relationshipDirection": "Incoming",
    • "relationshipNames": [
      • "isPartOf"
      ],
    • "relatedModelFilter": {
      • "modelIds": [
        • "string"
        ],
      • "exactModelMatch": true
      }
    },
  • "locationFilter": {
    • "locationId": "string"
    },
  • "dateFilter": {
    • "lastUpdatedAfter": "2019-08-24T14:15:22Z",
    • "lastUpdatedBefore": "2019-08-24T14:15:22Z"
    },
  • "propertyFilter": {
    • "field": "string",
    • "operator": "string",
    • "value": {
      • "property1": null,
      • "property2": null
      },
    • "filterConditionOperator": "And",
    • "filters": [
      • null
      ]
    },
  • "ModelFilter": {
    • "ModelIds": [
      • "dtmi:com:willowinc:Room;1"
      ],
    • "ExactModelMatch": true
    },
  • "RelationshipFilter": {
    • "RelationshipDirection": "Outgoing",
    • "RelationshipNames": [
      • "isPartOf",
      • "isDocumentOf",
      • "isCapabilityOf",
      • "locatedIn",
      • "hostedBy",
      • "includedIn",
      • "servedBy"
      ],
    • "RelatedModelFilter": {
      • "ModelIds": [
        • "dtmi:com:willowinc:Level;1"
        ],
      • "ExactModelMatch": true
      }
    },
  • "LocationFilter": {
    • "LocationId": null
    },
  • "DateFilter": {
    • "LastUpdatedAfter": "2024-09-23T15:16:03.4050000+00:00",
    • "LastUpdatedBefore": "2024-09-23T15:16:03.4050000+00:00"
    },
  • "PropertyFilter": {
    • "Filters": [
      • {
        • "Field": "externalID",
        • "Operator": "in",
        • "Value": [
          • "ExX12345"
          ]
        }
      ],
    • "FilterConditionOperator": "and"
    },
  • "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": "2025-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": "2025-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": "2025-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"
        }
      }
    }
}
Count of Twins matching the criteria
Securityoauth2 
Request 
Request Body schema: application/json
object (RequestModelFilter) 
Model Filter Class for Get Twins Request.


 
object (RequestRelationshipFilter) 
Get Twins Request Relationship Filter


 
object (RequestLocationFilter) 
Location Filter Class for Get Twins Request.


 
object (RequestDateFilter) 
Date Filter Class for Get Twins Request.


 
object (RequestPropertyFilter) 
Represents a group of filter specifications. Contains a list of individual filter specifications.


 
Responses 
200
400
post/twins/count
Request samples 
application/json
{
  • "modelFilter": {
    • "modelIds": [
      • "string"
      ],
    • "exactModelMatch": true
    },
  • "relationshipFilter": {
    • "relationshipDirection": "Incoming",
    • "relationshipNames": [
      • "isPartOf"
      ],
    • "relatedModelFilter": {
      • "modelIds": [
        • "string"
        ],
      • "exactModelMatch": true
      }
    },
  • "locationFilter": {
    • "locationId": "string"
    },
  • "dateFilter": {
    • "lastUpdatedAfter": "2019-08-24T14:15:22Z",
    • "lastUpdatedBefore": "2019-08-24T14:15:22Z"
    },
  • "propertyFilter": {
    • "field": "string",
    • "operator": "string",
    • "value": {
      • "property1": null,
      • "property2": null
      },
    • "filterConditionOperator": "And",
    • "filters": [
      • null
      ]
    },
  • "ModelFilter": {
    • "ModelIds": [
      • "dtmi:com:willowinc:Room;1"
      ],
    • "ExactModelMatch": true
    },
  • "RelationshipFilter": {
    • "RelationshipDirection": "Outgoing",
    • "RelationshipNames": [
      • "isPartOf",
      • "isDocumentOf",
      • "isCapabilityOf",
      • "locatedIn",
      • "hostedBy",
      • "includedIn",
      • "servedBy"
      ],
    • "RelatedModelFilter": {
      • "ModelIds": [
        • "dtmi:com:willowinc:Level;1"
        ],
      • "ExactModelMatch": true
      }
    },
  • "LocationFilter": {
    • "LocationId": null
    },
  • "DateFilter": {
    • "LastUpdatedAfter": "2024-09-23T15:16:03.4050000+00:00",
    • "LastUpdatedBefore": "2024-09-23T15:16:03.4050000+00:00"
    },
  • "PropertyFilter": {
    • "Filters": [
      • {
        • "Field": "externalID",
        • "Operator": "=",
        • "Value": "ExX12345"
        }
      ],
    • "FilterConditionOperator": "and"
    }
}
Response samples 
application/json
0
0
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. 


409
Relationship entity already exists for create relationship calls. (Request will be considered as Create if Id is string empty)
            or Attempted to update a relationship field that matches another already existing relationship causing conflict.


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
 
includeDataQuality
boolean
 
Responses 
200
OK


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"
        },
      • "dataQuality": {
        • "offline": false,
        • "valueOutOfRange": false,
        • "sparse": false,
        • "flatline": false,
        • "delayed": false
        }
      }
    ],
  • "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
required
string
 
includeDataQuality
boolean
 
Request Body schema: application/json
 Array 
string
 
Responses 
200
OK


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"
        },
      • "dataQuality": {
        • "offline": false,
        • "valueOutOfRange": false,
        • "sparse": false,
        • "flatline": false,
        • "delayed": false
        }
      }
    ],
  • "continuationToken": "CgAAYQAAAAAAABQ...",
  • "errorData": {
    • "message": "Error message",
    • "ids": [
      • "TW-DD-II-02"
      ]
    }
}
Retrieve the latest value
Securityoauth2 
Request 
path Parameters
twinId
required
string
 
query Parameters
start
string <date-time> 
 
end
string <date-time> 
 
includeDataQuality
boolean
 
Responses 
200
OK


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"
      },
    • "dataQuality": {
      • "offline": false,
      • "valueOutOfRange": false,
      • "sparse": false,
      • "flatline": false,
      • "delayed": false
      }
    }
]
Retrieve multiple latest values
Securityoauth2 
Request 
query Parameters
start
string <date-time> 
 
end
string <date-time> 
 
includeDataQuality
boolean
 
Request Body schema: application/json
 Array 
string
 
Responses 
200
OK


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"
      },
    • "dataQuality": {
      • "offline": false,
      • "valueOutOfRange": false,
      • "sparse": false,
      • "flatline": false,
      • "delayed": false
      }
    }
]
Insert time series values
Securityoauth2 
Request 
Request Body schema: application/json
 Array 
connectorId
required
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


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


 
Responses 
202
Accepted


400
Bad Request


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.


Retrieve an insight.
Securityoauth2 
Request 
path Parameters
insightId
required
string <uuid> 
Id of the insight.


 
query Parameters
ignoreQueryFilters
boolean
 Default:  true
Ignore global filter.


 
Responses 
200
OK


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,
  • "commentCount": 0,
  • "lastResolvedDate": "2019-08-24T14:15:22Z",
  • "lastIgnoredDate": "2019-08-24T14:15:22Z",
  • "locations": [
    • "string"
    ],
  • "locationDetails": [
    • {
      • "id": "string",
      • "name": "string",
      • "modelId": "string"
      }
    ],
  • "tags": [
    • "string"
    ],
  • "isDiagnosticsData": true,
  • "ignoreUntil": "2019-08-24T14:15:22Z",
  • "openTicketCount": 0,
  • "completedTicketCount": 0,
  • "closedTicketCount": 0,
  • "ticketClosedDate": "2019-08-24T14:15:22Z",
  • "secondaryTwins": [
    • {
      • "id": "string",
      • "name": "string",
      • "modelId": "string",
      • "eTag": "string"
      }
    ]
}
List insights.
Returns a paginated list tickets. Default page size is 10.


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


 
Request Body schema: 
Filter and sort specifications.


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


post/insights
Request samples 
{
  • "sortSpecifications": [
    • {
      • "field": "string",
      • "sort": "string"
      }
    ],
  • "filterSpecifications": [
    • {
      • "field": "string",
      • "operator": "string",
      • "value": {
        • "property1": null,
        • "property2": null
        },
      • "filterConditionOperator": "And"
      }
    ],
  • "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,
      • "commentCount": 0,
      • "lastResolvedDate": "2019-08-24T14:15:22Z",
      • "lastIgnoredDate": "2019-08-24T14:15:22Z",
      • "locations": [
        • "string"
        ],
      • "locationDetails": [
        • {
          • "id": "string",
          • "name": "string",
          • "modelId": "string"
          }
        ],
      • "tags": [
        • "string"
        ],
      • "isDiagnosticsData": true,
      • "ignoreUntil": "2019-08-24T14:15:22Z",
      • "openTicketCount": 0,
      • "completedTicketCount": 0,
      • "closedTicketCount": 0,
      • "ticketClosedDate": "2019-08-24T14:15:22Z",
      • "secondaryTwins": [
        • {
          • "id": "string",
          • "name": "string",
          • "modelId": "string",
          • "eTag": "string"
          }
        ]
      }
    ]
}
Events
Events endpoints enable creating, updating, and deleting discrete occurrences such as Weather Forecast, Calendar events etc.


List event types.
Returns the possible types that an event can have.


Securityoauth2 
Responses 
200
OK


get/events/types
Request samples 
Response samples 
No sample
List events.
Returns a paginated list of events.


Securityoauth2 
Request 
Request Body schema: 
The filter criteria and pagination details for the events to be retrieved.


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


post/events
Request samples 
{
  • "sortSpecifications": [
    • {
      • "field": "string",
      • "sort": "string"
      }
    ],
  • "filterSpecifications": [
    • {
      • "field": "string",
      • "operator": "string",
      • "value": {
        • "property1": null,
        • "property2": null
        },
      • "filterConditionOperator": "And"
      }
    ],
  • "page": 0,
  • "pageSize": 0
}
Response samples 
{
  • "before": 0,
  • "after": 0,
  • "total": 0,
  • "items": [
    • {
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "name": "string",
      • "description": "string",
      • "startTime": "2019-08-24T14:15:22Z",
      • "endTime": "2019-08-24T14:15:22Z",
      • "eventTypeId": 0,
      • "eventSourceId": "string",
      • "externalId": "string",
      • "payload": "string",
      • "payloadVersion": "string",
      • "scalarValue": 0,
      • "twinId": "string",
      • "locations": "string",
      • "createdDate": "2019-08-24T14:15:22Z",
      • "lastModifiedDate": "2019-08-24T14:15:22Z"
      }
    ]
}
Create an event.
Securityoauth2 
Request 
Request Body schema: 
The event object to be created.


id
string <uuid> 
Gets the event id which acts as the primary key in the database.


 
name
required
string or null
Gets or sets the event name.


 
description
string or null
Gets or sets the event description.


 
startTime
required
string <date-time> 
Gets or sets the event start time.


 
endTime
string or null <date-time> 
Gets or sets the event end time.


 
eventTypeId
required
integer <int32> 
Gets the event type id which is defined by Willow, e.g. CalendarEvent, WeatherForecast, UtilityBill, ….


 
eventSourceId
string or null
Gets the name of the source system, which is for informational purposes.


 
externalId
string or null
Gets an Id linking it to the source system, facilitating updates and deletes.


 
payload
required
string or null
Gets or sets a JSON string containing type-specific values.


 
payloadVersion
required
string or null
Gets or sets a version for the payload to assist in the deserialization of the payload.


 
scalarValue
number or null <double> 
Gets or sets a double value that may be stored to complement the Payload value.


 
twinId
required
string or null
Gets the id of the twin that is a reference to to an existing space, or equipment twin.


 
locations
string or null
Gets or sets a JSON string with the expanded location ancestors for the twinId.


 
createdDate
required
string <date-time> 
Gets or sets the date the event was created in the system.


 
lastModifiedDate
required
string <date-time> 
Gets or sets the date the event was last modified in the system.


 
Responses 
201
Created


put/events
Request samples 
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "startTime": "2019-08-24T14:15:22Z",
  • "endTime": "2019-08-24T14:15:22Z",
  • "eventTypeId": 0,
  • "eventSourceId": "string",
  • "externalId": "string",
  • "payload": "string",
  • "payloadVersion": "string",
  • "scalarValue": 0,
  • "twinId": "string",
  • "locations": "string",
  • "createdDate": "2019-08-24T14:15:22Z",
  • "lastModifiedDate": "2019-08-24T14:15:22Z"
}
Response samples 
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "startTime": "2019-08-24T14:15:22Z",
  • "endTime": "2019-08-24T14:15:22Z",
  • "eventTypeId": 0,
  • "eventSourceId": "string",
  • "externalId": "string",
  • "payload": "string",
  • "payloadVersion": "string",
  • "scalarValue": 0,
  • "twinId": "string",
  • "locations": "string",
  • "createdDate": "2019-08-24T14:15:22Z",
  • "lastModifiedDate": "2019-08-24T14:15:22Z"
}
Delete multiple events.
Securityoauth2 
Request 
Request Body schema: 
Collection of ids for the events to be deleted.


 Array 
string <uuid> 
 
Responses 
204
No Content


delete/events
Request samples 
[
  • "497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
Retrieve an event.
Securityoauth2 
Request 
path Parameters
eventId
required
string <uuid> 
Id of the event.


 
Responses 
200
OK


404
Not Found


get/events/{eventId}
Request samples 
Response samples 
No sample
Create multiple events.
Securityoauth2 
Request 
Request Body schema: 
A collection of Willow.Events.Entities.Event objects to be created.


 Array 
id
string <uuid> 
Gets the event id which acts as the primary key in the database.


 
name
required
string or null
Gets or sets the event name.


 
description
string or null
Gets or sets the event description.


 
startTime
required
string <date-time> 
Gets or sets the event start time.


 
endTime
string or null <date-time> 
Gets or sets the event end time.


 
eventTypeId
required
integer <int32> 
Gets the event type id which is defined by Willow, e.g. CalendarEvent, WeatherForecast, UtilityBill, ….


 
eventSourceId
string or null
Gets the name of the source system, which is for informational purposes.


 
externalId
string or null
Gets an Id linking it to the source system, facilitating updates and deletes.


 
payload
required
string or null
Gets or sets a JSON string containing type-specific values.


 
payloadVersion
required
string or null
Gets or sets a version for the payload to assist in the deserialization of the payload.


 
scalarValue
number or null <double> 
Gets or sets a double value that may be stored to complement the Payload value.


 
twinId
required
string or null
Gets the id of the twin that is a reference to to an existing space, or equipment twin.


 
locations
string or null
Gets or sets a JSON string with the expanded location ancestors for the twinId.


 
createdDate
required
string <date-time> 
Gets or sets the date the event was created in the system.


 
lastModifiedDate
required
string <date-time> 
Gets or sets the date the event was last modified in the system.


 
Responses 
201
Created


put/events/batch
Request samples 
[
  • {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "string",
    • "description": "string",
    • "startTime": "2019-08-24T14:15:22Z",
    • "endTime": "2019-08-24T14:15:22Z",
    • "eventTypeId": 0,
    • "eventSourceId": "string",
    • "externalId": "string",
    • "payload": "string",
    • "payloadVersion": "string",
    • "scalarValue": 0,
    • "twinId": "string",
    • "locations": "string",
    • "createdDate": "2019-08-24T14:15:22Z",
    • "lastModifiedDate": "2019-08-24T14:15:22Z"
    }
]
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.


List tickets.
Returns a paginated list of tickets. Default page size is 100, maximum is 1000.


Securityoauth2 
Request 
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


post/tickets
Request samples 
{
  • "sortSpecifications": [
    • {
      • "field": "string",
      • "sort": "string"
      }
    ],
  • "filterSpecifications": [
    • {
      • "field": "string",
      • "operator": "string",
      • "value": {
        • "property1": null,
        • "property2": null
        },
      • "filterConditionOperator": "And"
      }
    ],
  • "page": 0,
  • "pageSize": 0
}
Response samples 
application/json
{
  • "before": 0,
  • "after": 0,
  • "total": 0,
  • "items": [
    • {
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "priority": "string",
      • "status": "string",
      • "issueType": "noIssue",
      • "twinId": "string",
      • "twinName": "string",
      • "insightId": "e0b109ff-077c-4d58-916e-b128cab16ecb",
      • "summary": "string",
      • "description": "string",
      • "reporter": {
        • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        • "name": "string",
        • "email": "string",
        • "phone": "string",
        • "company": "string"
        },
      • "assigneeType": "noAssignee",
      • "userAssignee": {
        • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        • "name": "string",
        • "email": "string",
        • "phone": "string",
        • "company": "string"
        },
      • "workgroupAssignee": {
        • "name": "string"
        },
      • "creator": {
        • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        • "name": "string",
        • "email": "string",
        • "phone": "string",
        • "company": "string"
        },
      • "dueDate": "2019-08-24T14:15:22Z",
      • "createdDate": "2019-08-24T14:15:22Z",
      • "updatedDate": "2019-08-24T14:15:22Z",
      • "startedDate": "2019-08-24T14:15:22Z",
      • "resolvedDate": "2019-08-24T14:15:22Z",
      • "closedDate": "2019-08-24T14:15:22Z",
      • "sourceType": "willow",
      • "sourceName": "string",
      • "externalId": "string",
      • "externalCreatedDate": "2019-08-24T14:15:22Z",
      • "externalUpdatedDate": "2019-08-24T14:15:22Z",
      • "latitude": 0,
      • "longitude": 0,
      • "customProperties": {
        • "property1": "string",
        • "property2": "string"
        },
      • "extendableSearchablePropertyKeys": [
        • "string"
        ],
      • "scheduledDate": "2019-08-24T14:15:22Z",
      • "occurrence": 0,
      • "locations": [
        • {
          • "id": "string",
          • "name": "string",
          • "modelId": "string"
          }
        ],
      • "categoryId": "337f5e5d-288b-40d5-be14-901cc3acacc0",
      • "jobTypeId": "e7fed64c-d7a0-4b92-b323-987c8904a687",
      • "serviceNeededId": "1aa099e5-6900-4be9-91d2-38308a317250",
      • "subStatusId": "c9b6af8c-39fe-4426-a105-7343d1ed54d3"
      }
    ]
}
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.


List categories.
Returns a paginated list of the possible categories that a ticket can have.


Securityoauth2 
Request 
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


post/tickets/categories
Request samples 
{
  • "sortSpecifications": [
    • {
      • "field": "string",
      • "sort": "string"
      }
    ],
  • "filterSpecifications": [
    • {
      • "field": "string",
      • "operator": "string",
      • "value": {
        • "property1": null,
        • "property2": null
        },
      • "filterConditionOperator": "And"
      }
    ],
  • "page": 0,
  • "pageSize": 0
}
Response samples 
application/json
{
  • "before": 0,
  • "after": 0,
  • "total": 0,
  • "items": [
    • {
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "name": "string",
      • "isActive": true,
      • "locations": [
        • "string"
        ]
      }
    ]
}
Create a category.
Securityoauth2 
Request 
Request Body schema: 
name
required
string  [ 0 .. 80 ] characters 
Gets or sets the name of the ticket category.


 
locations
Array of strings or null
Gets or sets the list of locations associated with the ticket category.


 
Responses 
201
Created


400
Bad Request


default
Error


put/tickets/categories
Request samples 
{
  • "name": "string",
  • "locations": [
    • "string"
    ]
}
Response samples 
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "isActive": true,
  • "locations": [
    • "string"
    ]
}
Update a category.
Securityoauth2 
Request 
path Parameters
categoryId
required
string <uuid> 
 
Request Body schema: 
name
string or null  [ 0 .. 80 ] characters 
Gets or sets the category name.


 
isActive
boolean or null
Gets or sets a value indicating whether the category is active or not.


 
locations
Array of strings or null
Gets or sets the list of locations associated with the ticket category.


 
Responses 
204
No Content


400
Bad Request


404
Not Found


default
Error


patch/tickets/categories/{categoryId}
Request samples 
{
  • "name": "string",
  • "isActive": true,
  • "locations": [
    • "string"
    ]
}
Response samples 
application/json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "property1": null,
  • "property2": null
}
List job types.
Returns a paginated list of the possible job types that a ticket can have.


Securityoauth2 
Request 
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


post/tickets/job-types
Request samples 
{
  • "sortSpecifications": [
    • {
      • "field": "string",
      • "sort": "string"
      }
    ],
  • "filterSpecifications": [
    • {
      • "field": "string",
      • "operator": "string",
      • "value": {
        • "property1": null,
        • "property2": null
        },
      • "filterConditionOperator": "And"
      }
    ],
  • "page": 0,
  • "pageSize": 0
}
Response samples 
application/json
{
  • "before": 0,
  • "after": 0,
  • "total": 0,
  • "items": [
    • {
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "name": "string",
      • "isActive": true
      }
    ]
}
Create a job type.
Securityoauth2 
Request 
Request Body schema: 
name
required
string  [ 0 .. 500 ] characters 
Gets or sets the job type name.


 
Responses 
201
Created


400
Bad Request


default
Error


put/tickets/job-types
Request samples 
{
  • "name": "string"
}
Response samples 
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "isActive": true
}
Update a job type.
Securityoauth2 
Request 
path Parameters
jobTypeId
required
string <uuid> 
 
Request Body schema: 
name
string or null  [ 0 .. 500 ] characters 
Gets or sets the job type name.


 
isActive
boolean or null
Gets or sets a value indicating whether the job type is active.


 
Responses 
204
No Content


400
Bad Request


404
Not Found


default
Error


patch/tickets/job-types/{jobTypeId}
Request samples 
{
  • "name": "string",
  • "isActive": true
}
Response samples 
application/json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "property1": null,
  • "property2": null
}
List services needed.
Returns a paginated list of the possible services needed that a ticket can have.


Securityoauth2 
Request 
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


post/tickets/service-needed
Request samples 
{
  • "sortSpecifications": [
    • {
      • "field": "string",
      • "sort": "string"
      }
    ],
  • "filterSpecifications": [
    • {
      • "field": "string",
      • "operator": "string",
      • "value": {
        • "property1": null,
        • "property2": null
        },
      • "filterConditionOperator": "And"
      }
    ],
  • "page": 0,
  • "pageSize": 0
}
Response samples 
application/json
{
  • "before": 0,
  • "after": 0,
  • "total": 0,
  • "items": [
    • {
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "name": "string",
      • "categoryId": "337f5e5d-288b-40d5-be14-901cc3acacc0",
      • "locations": [
        • "string"
        ],
      • "isActive": true
      }
    ]
}
Create a service needed.
Securityoauth2 
Request 
Request Body schema: 
name
required
string  [ 0 .. 500 ] characters 
Gets or sets the name of the service needed.


 
categoryId
string or null <uuid> 
Gets or sets the category Id of the service needed.


 
locations
Array of strings or null
Gets or sets the space twin Ids associated with the service needed.


 
Responses 
201
Created


400
Bad Request


default
Error


put/tickets/service-needed
Request samples 
{
  • "name": "string",
  • "categoryId": "337f5e5d-288b-40d5-be14-901cc3acacc0",
  • "locations": [
    • "string"
    ]
}
Response samples 
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "categoryId": "337f5e5d-288b-40d5-be14-901cc3acacc0",
  • "locations": [
    • "string"
    ],
  • "isActive": true
}
Update a service needed.
Securityoauth2 
Request 
path Parameters
serviceNeededId
required
string <uuid> 
 
Request Body schema: 
name
string or null  [ 0 .. 500 ] characters 
Gets or sets the name of the service needed.


 
categoryId
string or null <uuid> 
Gets or sets the category Id of the service needed.


 
isActive
boolean or null
Gets or sets a value indicating whether the service needed is active.


 
locations
Array of strings or null
Gets or sets the space twin Ids associated with the service needed.


 
Responses 
204
No Content


400
Bad Request


404
Not Found


default
Error


patch/tickets/service-needed/{serviceNeededId}
Request samples 
{
  • "name": "string",
  • "categoryId": "337f5e5d-288b-40d5-be14-901cc3acacc0",
  • "isActive": true,
  • "locations": [
    • "string"
    ]
}
Response samples 
application/json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "property1": null,
  • "property2": null
}
List ticket statuses.
Returns the possible statuses that a ticket can have.


Securityoauth2 
Responses 
200
OK


get/tickets/status
Request samples 
Response samples 
application/json
[
  • {
    • "statusCode": 0,
    • "status": "string",
    • "tab": "string",
    • "color": "string"
    }
]
List ticket priorities
Returns the possible priorities that a ticket can have.


Securityoauth2 
Responses 
200
OK


get/tickets/priorities
Request samples 
Response samples 
application/json
[
  • {
    • "name": "string"
    }
]
Copyright © 2024 Willow. All rights reserved.