Skip to content
/Models

Willow Public API (v3)

Download OpenAPI description
willow-api.json
willow-api.yaml
Languages
Servers
https://{instance}.app.willowinc.com/api/v3/

OAuth2

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

Operations

Models

Models endpoints are used for getting the models and their details.

Operations

List models

Request

Security
oauth2
Query
rootModelstring or null

Root model to get dependencies from

includeModelDefinitionsboolean

When true, the response includes the model definitions

Default false
No request payload

Responses

Returns models for the input root Id.

Bodyapplication/jsonArray [
idstring

Id of the Model.

Example: "dtmi:com:willowinc:Room;1"
displayNameobject or null

Display Names of the Model keyed by language code.

Example: {"en":"Room"}
descriptionobject or null

Description of the Model keyed by language code.

Example: {"en":"A portion of space within a building that's usually enclosed and has its own walls, floor, and ceiling."}
modelDefinitionstring

Encoded JSON string of DTDL model definition.

Example: "{\"@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 }"
uploadTimestring or null(date-time)

Timestamp when the model was uploaded in ISO 8601 format

Example: "2024-08-30T03:33:54.7015118+00:00"
]
Response
application/json
[
  {
    "id": "dtmi:com:willowinc:Room;1",
    "displayName": { … },
    "description": { … },
    "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

Request

Security
oauth2
Path
idstringrequired

Id of the model

No request payload

Responses

If model retrieved successfully.

Bodyapplication/json
idstring

Id of the Model.

Example: "dtmi:com:willowinc:Room;1"
displayNameobject or null

Display Names of the Model keyed by language code.

Example: {"en":"Room"}
descriptionobject or null

Description of the Model keyed by language code.

Example: {"en":"A portion of space within a building that's usually enclosed and has its own walls, floor, and ceiling."}
modelDefinitionstring

Encoded JSON string of DTDL model definition.

Example: "{\"@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 }"
uploadTimestring or null(date-time)

Timestamp when the model was uploaded in ISO 8601 format

Example: "2024-08-30T03:33:54.7015118+00:00"
Response
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.

Operations

Relationships

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

Operations

Time Series

The Time Series endpoints are used for sending or receiving telemetry data. Once a Capability twin has been created that represents the time series, the telemetry associated with that twin can be created using either the twin's dtId (aka twinId) or externalId, a timestamp, and a value. Data is transmitted as an array so time series data can be batched and sent within a single request. Similarly, time series can be retreived for one or more Capability twins at a time using the twinId(s).

Operations

Insights

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

Operations

Events

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

Operations

Tickets

This API group is in pre-release and may change without notice. Use with caution. Breaking changes may occur as development continues.
Tickets endpoints enable creating, updating and retrieving Tickets.

Operations

Ticket Metadata

This API group is in pre-release and may change without notice. Use with caution. Breaking changes may occur as development continues.
Ticket Metadata endpoints enable creating, updating and retrieving Ticket Metadata.

Operations
Copyright © 2024 Willow. All rights reserved.