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

Payload
JS
C#
Java
Python

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.

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

JS
C#
Java
Python

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"
}
]

Retrieve a model

Securityoauth2

Request

path Parameters

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

JS
C#
Java
Python

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.

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

Payload
JS
C#
Java
Python

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": [{ }
]
},
"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

Payload
JS
C#
Java
Python

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"
}
}
}
}

Retrieve a twin

Securityoauth2

Request

path Parameters

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

JS
C#
Java
Python

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

required

string

Id of the twin

Request Body schema: application/json

List of Patch Operations.

Array

operationType	string (OperationType) Enum: "Add" "Remove" "Replace" "Move" "Copy" "Test" "Invalid"
path	string or null
op	string or null
from	string or null
	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

Payload
JS
C#
Java
Python

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

Payload
JS
C#
Java
Python

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

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

Payload
JS
C#
Java
Python

application/json

{"id": "PNT2Uga",
"alias": "Twin",
"relationships": [{"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": { }
}
]
}

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"
}
]
}
]
}

Count twins

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

Payload
JS
C#
Java
Python

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": [{ }
]
},
"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

Relationships

Relationship endpoints enable creating, updating, and fetching relationship details.

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

Payload
JS
C#
Java
Python

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"
}
}

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

JS
C#
Java
Python

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

JS
C#
Java
Python

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

JS
C#
Java
Python

Response samples

application/json

[{"Id": "AHU-1_isFedBy_substance_ChilledWater_Chiller-1",
"targetId": "Chiller-1",
"sourceId": "AHU-1",
"name": "isFedBy",
"properties": {"substance": "ChilledWater"
}
}
]

Insights

Insights are issues, opportunities, or knowledge that can help optimize or improve the performance of a building. They can be associated with any twin within Willow and are triggered in real-time by Skills that are running within Willow's Activate Technology and analyzing the incoming time series data.

List insights.

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:
application/json

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

post/insights

Request samples

Payload
JS
C#
Java
Python

{"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",
"insightType": "standard",
"category": "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",
"ticketCompletedDate": "2019-08-24T14:15:22Z",
"secondaryTwins": [{"id": "string",
"name": "string",
"modelId": "string",
"eTag": "string"
}
],
"recommendations": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"recommendation": "string",
"tags": ["string"
],
"ignored": true,
"tickets": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"summary": "string",
"createdDate": "2019-08-24T14:15:22Z",
"ticketStatus": {"id": null,
"name": null,
"tab": null,
"color": null
}
}
]
}
],
"dependencyCount": 0,
"actionStatus": "needsAction",
"scenarioId": "e28e2f4c-7202-4457-b0d8-c4c537f7bff6",
"scenarioName": "string"
}
]
}

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

get/insights/{insightId}

Request samples

JS
C#
Java
Python

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",
"insightType": "standard",
"category": "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",
"ticketCompletedDate": "2019-08-24T14:15:22Z",
"secondaryTwins": [{"id": "string",
"name": "string",
"modelId": "string",
"eTag": "string"
}
],
"recommendations": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"recommendation": "string",
"tags": ["string"
],
"ignored": true,
"tickets": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"summary": "string",
"createdDate": "2019-08-24T14:15:22Z",
"ticketStatus": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"tab": "string",
"color": "string"
}
}
]
}
],
"dependencyCount": 0,
"actionStatus": "needsAction",
"scenarioId": "e28e2f4c-7202-4457-b0d8-c4c537f7bff6",
"scenarioName": "string"
}

Events

Events endpoints enable creating, updating, and deleting discrete occurrences such as Weather Forecast, Calendar events etc.

List events.

Returns a paginated list of events.

Securityoauth2

Request

Request Body schema:
application/json

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

post/events

Request samples

Payload
JS
C#
Java
Python

{"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 or update multiple events.

Securityoauth2

Request

Request Body schema:
application/json

A collection of Willow.Events.Entities.Event objects to be created or updated.

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

200

put/events

Request samples

Payload
JS
C#
Java
Python

[{"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

{"eventsCreatedCount": 0,
"eventsUpdatedCount": 0
}

Delete multiple events.

Securityoauth2

Request

Request Body schema:
application/json

Collection of ids for the events to be deleted.

Array

string <uuid>

Responses

204

No Content

delete/events

Request samples

Payload
JS
C#
Java
Python

["497f6eca-6276-4993-bfeb-53cbbbba6f08"
]

Retrieve an event.

Securityoauth2

Request

path Parameters

eventId

required

string <uuid>

Id of the event.

Responses

200

404

Not Found

get/events/{eventId}

Request samples

JS
C#
Java
Python

Response samples

No sample

List event types.

Returns the possible types that an event can have.

Securityoauth2

Responses

200

get/events/types

Request samples

JS
C#
Java
Python

Response samples

No sample

Upload events from files.

Securityoauth2

Request

Request Body schema: multipart/form-data

files

required

Array of strings <binary>

A collection of files to be uploaded.

Responses

200

post/events/files

Request samples

JS
C#
Java
Python

Response samples

No sample

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:
application/json

	Array of objects or null (SortSpecification)
	Array of objects or null (FilterSpecification)
page	integer or null <int32>
pageSize	integer or null <int32>

Responses

200

post/tickets

Request samples

Payload
JS
C#
Java
Python

{"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",
"ticketPriority": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"priorityLevel": "urgent"
},
"ticketStatus": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"tab": "string",
"color": "string"
},
"issueType": "noIssue",
"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": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"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"
}
],
"twin": {"id": "string",
"name": "string",
"modelId": "string"
},
"recommendations": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"recommendation": "string",
"tags": ["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"
}
]
}

Creates a new ticket.

Securityoauth2

Request

Request Body schema:
application/json

Create ticket request.

summary	string or null Gets or sets the summary of the ticket.
description	string or null Gets or sets the description of the ticket.
cause	string or null Gets or sets the cause of the ticket.
solution	string or null Gets or sets the solution of the ticket.
twinId	string or null Gets or sets the digital twin id associated with the ticket.
notes	string or null Gets or sets additional notes for the ticket.
latitude	number or null <double> Gets or sets the latitude of the ticket location.
longitude	number or null <double> Gets or sets the longitude of the ticket location.
insightId	string or null <uuid> Gets or sets the InsightId associated with the ticket.
insightName	string or null Gets or sets the name of the insight associated with the ticket.
	Array of objects or null (Insight) Gets or sets the diagnostics associated with the ticket.
	object (UserProfile)
	object (UserProfile)
assigneeType	string (AssigneeType) Enum: "noAssignee" "customerUser" "workGroup"
	object (UserProfile)
	object (WorkgroupAssignee)
dueDate	string or null <date-time> Gets or sets the due date of the ticket.
externalCreatedDate	string or null <date-time> Gets or sets the external created date of the ticket. This field represents the created date of the ticket in an external system.
externalUpdatedDate	string or null <date-time> Gets or sets the external updated date of the ticket. This field represents the last updated date of the ticket in an external system.
externalId	string or null Gets or sets the external id of the ticket. This field represents the id of the ticket in an external system.
externalMetadata	string or null Gets or sets the external metadata of the ticket.
categoryId	string or null <uuid> Gets or sets the category id of the ticket.
jobTypeId	string or null <uuid> Gets or sets the job type id of the ticket.
serviceNeededId	string or null <uuid> Gets or sets the service needed id of the ticket.
subStatusId	string or null <uuid> Gets or sets the sub status id of the ticket.
statusId	string <uuid> Gets or sets the status id of the ticket.
priorityId	string or null <uuid> Gets or sets the priority id of the ticket.
	Array of objects or null (TicketTask) Gets or sets the list of tasks associated with the ticket.
	object or null Gets or sets the custom properties of the ticket.
extendableSearchablePropertyKeys	Array of strings or null Gets or sets the list of property keys that can be extended and searched.
	Array of objects or null (TicketRecommendation) Gets or sets the list of ticket's recommendations.

Responses

201

Created

400

Bad Request

default

Error

put/tickets

Request samples

Payload
JS
C#
Java
Python

{"summary": "string",
"description": "string",
"cause": "string",
"solution": "string",
"twinId": "string",
"notes": "string",
"latitude": 0,
"longitude": 0,
"insightId": "e0b109ff-077c-4d58-916e-b128cab16ecb",
"insightName": "string",
"diagnostics": [{"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",
"insightType": "standard",
"category": "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",
"ticketCompletedDate": "2019-08-24T14:15:22Z",
"secondaryTwins": [{"id": "string",
"name": "string",
"modelId": "string",
"eTag": "string"
}
],
"recommendations": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"recommendation": "string",
"tags": ["string"
],
"ignored": true,
"tickets": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"summary": "string",
"createdDate": "2019-08-24T14:15:22Z",
"ticketStatus": {"id": null,
"name": null,
"tab": null,
"color": null
}
}
]
}
],
"dependencyCount": 0,
"actionStatus": "needsAction",
"scenarioId": "e28e2f4c-7202-4457-b0d8-c4c537f7bff6",
"scenarioName": "string"
}
],
"reporter": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"email": "string",
"phone": "string",
"company": "string"
},
"creator": {"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": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string"
},
"dueDate": "2019-08-24T14:15:22Z",
"externalCreatedDate": "2019-08-24T14:15:22Z",
"externalUpdatedDate": "2019-08-24T14:15:22Z",
"externalId": "string",
"externalMetadata": "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",
"statusId": "e900225c-0629-4e96-be6e-86a17a309645",
"priorityId": "a57eab25-838b-40cc-a576-57e4056f1d6c",
"tasks": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"taskName": "string",
"isCompleted": true,
"order": 0,
"numberValue": 0,
"type": "numeric",
"decimalPlaces": 0,
"minValue": 0,
"maxValue": 0,
"unit": "string"
}
],
"customProperties": {"property1": "string",
"property2": "string"
},
"extendableSearchablePropertyKeys": ["string"
],
"recommendations": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"recommendation": "string",
"tags": ["string"
]
}
]
}

Response samples

201
400
default

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"ticketPriority": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"priorityLevel": "urgent"
},
"ticketStatus": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"tab": "string",
"color": "string"
},
"issueType": "noIssue",
"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": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"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"
}
],
"twin": {"id": "string",
"name": "string",
"modelId": "string"
},
"category": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string"
},
"jobType": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string"
},
"serviceNeeded": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string"
},
"subStatus": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string"
},
"comments": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"text": "string",
"createdDate": "2019-08-24T14:15:22Z",
"creator": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"email": "string",
"phone": "string",
"company": "string"
}
}
],
"attachments": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"fileName": "string"
}
],
"recommendations": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"recommendation": "string",
"tags": ["string"
]
}
]
}

Retrieves a ticket by its Id.

Securityoauth2

Request

path Parameters

ticketId

required

string <uuid>

Responses

200

404

Not Found

default

Error

get/tickets/{ticketId}

Request samples

JS
C#
Java
Python

Response samples

200
404
default

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"ticketPriority": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"priorityLevel": "urgent"
},
"ticketStatus": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"tab": "string",
"color": "string"
},
"issueType": "noIssue",
"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": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"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"
}
],
"twin": {"id": "string",
"name": "string",
"modelId": "string"
},
"category": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string"
},
"jobType": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string"
},
"serviceNeeded": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string"
},
"subStatus": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string"
},
"comments": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"text": "string",
"createdDate": "2019-08-24T14:15:22Z",
"creator": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"email": "string",
"phone": "string",
"company": "string"
}
}
],
"attachments": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"fileName": "string"
}
],
"recommendations": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"recommendation": "string",
"tags": ["string"
]
}
]
}

Applies a JSON Patch document to update specific properties of a ticket.

This endpoint supports partial updates to a ticket using a JSON Patch document. The number of operations in the patch document must not exceed the number of updatable properties in the WorkflowCore.Controllers.Request.PatchTicketRequest model. Additionally, only "replace" operations are allowed.

Securityoauth2

Request

path Parameters

ticketId

required

string <uuid>

The unique identifier of the ticket to be updated.

Request Body schema:
application/json

A Microsoft.AspNetCore.JsonPatch.JsonPatchDocument`1 containing the operations to apply to the ticket. Only "replace" operations are supported.

Array

op	string The operation to be performed.
path	string A JSON Pointer path to the target location.
value	object The value to be used in the operation.

Responses

200

patch/tickets/{ticketId}

Request samples

Payload
JS
C#
Java
Python

[{"op": "string",
"path": "string",
"value": { }
}
]

Response samples

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"ticketPriority": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"priorityLevel": "urgent"
},
"ticketStatus": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"tab": "string",
"color": "string"
},
"issueType": "noIssue",
"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": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"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"
}
],
"twin": {"id": "string",
"name": "string",
"modelId": "string"
},
"category": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string"
},
"jobType": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string"
},
"serviceNeeded": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string"
},
"subStatus": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string"
},
"comments": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"text": "string",
"createdDate": "2019-08-24T14:15:22Z",
"creator": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"email": "string",
"phone": "string",
"company": "string"
}
}
],
"attachments": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"fileName": "string"
}
],
"recommendations": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"recommendation": "string",
"tags": ["string"
]
}
]
}

Retrieves a ticket attachment by its Id.

Securityoauth2

Request

path Parameters

ticketId required	string <uuid> Ticket Id.
attachmentId required	string <uuid> Attachment Id.

Responses

200

get/tickets/{ticketId}/attachments/{attachmentId}

Request samples

JS
C#
Java
Python

Response samples

application/json

"string"

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:
application/json

	Array of objects or null (SortSpecification)
	Array of objects or null (FilterSpecification)
page	integer or null <int32>
pageSize	integer or null <int32>

Responses

200

post/tickets/categories

Request samples

Payload
JS
C#
Java
Python

{"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:
application/json

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

Payload
JS
C#
Java
Python

{"name": "string",
"locations": ["string"
]
}

Response samples

201
400
default

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:
application/json

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

Payload
JS
C#
Java
Python

{"name": "string",
"isActive": true,
"locations": ["string"
]
}

Response samples

400
404
default

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:
application/json

	Array of objects or null (SortSpecification)
	Array of objects or null (FilterSpecification)
page	integer or null <int32>
pageSize	integer or null <int32>

Responses

200

post/tickets/job-types

Request samples

Payload
JS
C#
Java
Python

{"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:
application/json

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

Payload
JS
C#
Java
Python

{"name": "string"
}

Response samples

201
400
default

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:
application/json

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

Payload
JS
C#
Java
Python

{"name": "string",
"isActive": true
}

Response samples

400
404
default

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:
application/json

	Array of objects or null (SortSpecification)
	Array of objects or null (FilterSpecification)
page	integer or null <int32>
pageSize	integer or null <int32>

Responses

200

post/tickets/service-needed

Request samples

Payload
JS
C#
Java
Python

{"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:
application/json

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

Payload
JS
C#
Java
Python

{"name": "string",
"categoryId": "337f5e5d-288b-40d5-be14-901cc3acacc0",
"locations": ["string"
]
}

Response samples

201
400
default

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:
application/json

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

Payload
JS
C#
Java
Python

{"name": "string",
"categoryId": "337f5e5d-288b-40d5-be14-901cc3acacc0",
"isActive": true,
"locations": ["string"
]
}

Response samples

400
404
default

application/json

{"type": "string",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"property1": null,
"property2": null
}

Retrieves a list of ticket status.

Securityoauth2

Responses

200

get/tickets/status

Request samples

JS
C#
Java
Python

Response samples

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"tab": "string",
"color": "string"
}
]

Gets the list of ticket priorities.

Securityoauth2

Responses

200

get/tickets/priorities

Request samples

JS
C#
Java
Python

Response samples

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"priorityLevel": "urgent"
}
]

Unavailable

Some services are currently unavailable

Willow Public API (v3)

OAuth2

Get OAuth2 Token

Request Body schema: application/x-www-form-urlencoded

Models

List models

query Parameters

Retrieve a model

path Parameters

Twins

List twins

Request Body schema: application/json

Create or replace a twin.

Request Body schema: application/json

Retrieve a twin

path Parameters

query Parameters

Update a twin

path Parameters

Request Body schema: application/json

Retrieve multiple twins

query Parameters

Request Body schema: application/json

Retrieve Twin graph.

Request Body schema: application/json

Count twins

Request Body schema: application/json

Relationships

Create or replace a twin relationship

Request Body schema: application/json

Retrieve a twin relationship

path Parameters

List outgoing relationships for a twin

path Parameters

query Parameters

List incoming relationships for a twin

path Parameters

Insights

List insights.

query Parameters

Request Body schema: application/jsontext/jsonapplication/*+jsonapplication/json

Retrieve an insight.

path Parameters

query Parameters

Events

List events.

Request Body schema: application/jsontext/jsonapplication/*+jsonapplication/json

Create or update multiple events.

Request Body schema: application/jsontext/jsonapplication/*+jsonapplication/json

Delete multiple events.

Request Body schema: application/jsontext/jsonapplication/*+jsonapplication/json

Retrieve an event.

path Parameters

List event types.

Upload events from files.

Request Body schema: multipart/form-data

Tickets

List tickets.

Request Body schema: application/jsontext/jsonapplication/*+jsonapplication/json

Creates a new ticket.

Request Body schema: application/jsontext/jsonapplication/*+jsonapplication/json

Retrieves a ticket by its Id.

path Parameters

Applies a JSON Patch document to update specific properties of a ticket.

path Parameters

Request Body schema: application/jsontext/jsonapplication/*+jsonapplication/json

Retrieves a ticket attachment by its Id.

path Parameters

Ticket Metadata

List categories.

Request Body schema: application/jsontext/jsonapplication/*+jsonapplication/json

Create a category.

Request Body schema: application/jsontext/jsonapplication/*+jsonapplication/json

Update a category.

path Parameters

Request Body schema: application/jsontext/jsonapplication/*+jsonapplication/json

List job types.

Request Body schema: application/jsontext/jsonapplication/*+jsonapplication/json

Create a job type.

Request Body schema: application/jsontext/jsonapplication/*+jsonapplication/json

Request Body schema:
application/json

Request Body schema:
application/json

Request Body schema:
application/json

Request Body schema:
application/json

Request Body schema:
application/json

Request Body schema:
application/json

Request Body schema:
application/json

Request Body schema:
application/json

Request Body schema:
application/json

Request Body schema:
application/json

Request Body schema:
application/json

Request Body schema:
application/json

Request Body schema:
application/json

Request Body schema:
application/json

Request Body schema:
application/json

Request Body schema:
application/json