Skip to content
REST API Reference/
/
Create or update multiple...

Willow Public API (v3)

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

OAuth2

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

Operations

Models

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

Operations

Twins

The Twins endpoints enable creating, updating, and fetching one or more twins at a time. When receiving twins, there are also options to include relationships in the same response.

Operations

Relationships

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

Operations

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

List events.

Request

Returns a paginated list of events.

Security
oauth2
Body
required

The filter criteria and pagination details for the events to be retrieved.

sortSpecificationsArray of objects(SortSpecification)
filterSpecificationsArray of objects(FilterSpecification)
pageinteger or null(int32)
pageSizeinteger or null(int32)
{
  "sortSpecifications": [
    { … }
  ],
  "filterSpecifications": [
    { … }
  ],
  "page": 0,
  "pageSize": 0
}

Responses

A paginated collection of events that match the specified filter criteria.

Body
beforeinteger(int32)
afterinteger(int32)
totalinteger(int32)
itemsArray of objects or null(Event)
Response
No response example

Create or update multiple events.

Request

Security
oauth2
Body
required

A collection of Event objects to be created or updated.

Array [
idstring(uuid)

Gets the event id which acts as the primary key in the database.

namestring or nullrequired

Gets or sets the event name.

descriptionstring or null

Gets or sets the event description.

startTimestring(date-time)required

Gets or sets the event start time.

endTimestring or null(date-time)

Gets or sets the event end time.

eventTypeIdinteger(int32)required

Gets the event type id which is defined by Willow, e.g. CalendarEvent, WeatherForecast, UtilityBill, ….

eventSourceIdstring or null

Gets the name of the source system, which is for informational purposes.

externalIdstring or null

Gets an Id linking it to the source system, facilitating updates and deletes.

payloadstring or nullrequired

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

payloadVersionstring or nullrequired

Gets or sets a version for the payload to assist in the deserialization of the payload.

scalarValuenumber or null(double)

Gets or sets a double value that may be stored to complement the Payload value.

twinIdstring or nullrequired

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

locationsstring or null

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

createdDatestring(date-time)required

Gets or sets the date the event was created in the system.

lastModifiedDatestring(date-time)required

Gets or sets the date the event was last modified in the system.

]
[
  {
    "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.1,
    "twinId": "string",
    "locations": "string",
    "createdDate": "2019-08-24T14:15:22Z",
    "lastModifiedDate": "2019-08-24T14:15:22Z"
  }
]

Responses

Returns an EventsPutResponse containing details of the create/update operation.

Body
eventsCreatedCountinteger(int32)

Gets or sets the number of created events.

eventsUpdatedCountinteger(int32)

Gets or sets the number of updated events.

Response
No response example

Delete multiple events.

Request

Security
oauth2
Body
required

Collection of ids for the events to be deleted.

Array [
string(uuid)
]
[
  "497f6eca-6276-4993-bfeb-53cbbbba6f08"
]

Responses

A task representing the asynchronous operation.

Retrieve an event.

Request

Security
oauth2
Path
eventIdstring(uuid)required

Id of the event.

No request payload

Responses

OK

Body
idstring(uuid)

Gets the event id which acts as the primary key in the database.

namestring or nullrequired

Gets or sets the event name.

descriptionstring or null

Gets or sets the event description.

startTimestring(date-time)required

Gets or sets the event start time.

endTimestring or null(date-time)

Gets or sets the event end time.

eventTypeIdinteger(int32)required

Gets the event type id which is defined by Willow, e.g. CalendarEvent, WeatherForecast, UtilityBill, ….

eventSourceIdstring or null

Gets the name of the source system, which is for informational purposes.

externalIdstring or null

Gets an Id linking it to the source system, facilitating updates and deletes.

payloadstring or nullrequired

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

payloadVersionstring or nullrequired

Gets or sets a version for the payload to assist in the deserialization of the payload.

scalarValuenumber or null(double)

Gets or sets a double value that may be stored to complement the Payload value.

twinIdstring or nullrequired

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

locationsstring or null

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

createdDatestring(date-time)required

Gets or sets the date the event was created in the system.

lastModifiedDatestring(date-time)required

Gets or sets the date the event was last modified in the system.

Response
No response example

List event types.

Request

Returns the possible types that an event can have.

Security
oauth2
No request payload

Responses

A collection of event types.

Body
Array [
idinteger(int32)required

The unique identifier for the event type.

namestringrequired

The name of the event type.

]
Response
No response example

Upload events from files.

Request

Security
oauth2
Bodymultipart/form-datarequired

A collection of files to be uploaded.

filesArray of strings(binary)(IFormFile)required
multipart/form-data
{
  "files": [
    "string"
  ]
}

Responses

An EventsUploadResponse containing details of the upload operation.

Body
fileUploadedobject

Gets the dictionary of file names and any error messages.

Response
No response example

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.