# Willow Public API Version: v3 ## Servers ``` https://{instance}.app.willowinc.com/api/v3 ``` Variables: - `instance`: Your Willow instance name. ## Security ### oauth2 Type: oauth2 ## Download OpenAPI description [Willow Public API](https://developers.willowinc.com/_bundle/openapi/@v3/willow-api.yaml) ## OAuth2 Authentication is required prior to accessing the Willow API. Refer to Authentication section above for details. ### Get OAuth2 Token - [POST /oauth2/token](https://developers.willowinc.com/openapi/willow-api/oauth2/getoauth2token.md): Generates an OAuth2 token. ## Models Models endpoints are used for getting the models and their details. ### List models - [GET /models](https://developers.willowinc.com/openapi/willow-api/models/modelsv2_getmodels.md) ### Retrieve a model - [GET /models/{id}](https://developers.willowinc.com/openapi/willow-api/models/modelsv2_getmodel.md) ## 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 - [POST /twins](https://developers.willowinc.com/openapi/willow-api/twins/twinsv2_gettwinsasync.md) ### Create or replace a twin. - [PUT /twins](https://developers.willowinc.com/openapi/willow-api/twins/twinsv2_createorreplacetwinasync.md) ### Retrieve a twin - [GET /twins/{id}](https://developers.willowinc.com/openapi/willow-api/twins/twinsv2_gettwinbyidasync.md) ### Update a twin - [PATCH /twins/{id}](https://developers.willowinc.com/openapi/willow-api/twins/twinsv2_patchtwin.md) ### Retrieve multiple twins - [POST /twins/ids](https://developers.willowinc.com/openapi/willow-api/twins/twinsv2_gettwinsbyidsasync.md): 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. ### Retrieve Twin graph. - [POST /twins/graph](https://developers.willowinc.com/openapi/willow-api/twins/twinsv2_gettwingraph.md): 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. ### Count twins - [POST /twins/count](https://developers.willowinc.com/openapi/willow-api/twins/twinsv2_gettwinscount.md) ## Relationships Relationship endpoints enable creating, updating, and fetching relationship details. ### Create or replace a twin relationship - [PUT /twins/relationships](https://developers.willowinc.com/openapi/willow-api/relationships/relationshipsv2_upsertrelationship.md): 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. ### Retrieve a twin relationship - [GET /twins/{twinId}/relationships/{relationshipId}](https://developers.willowinc.com/openapi/willow-api/relationships/relationshipsv2_getrelationship.md) ### List outgoing relationships for a twin - [GET /twins/{twinId}/relationships/outgoing](https://developers.willowinc.com/openapi/willow-api/relationships/relationshipsv2_getrelationships.md) ### List incoming relationships for a twin - [GET /twins/{twinId}/relationships/incoming](https://developers.willowinc.com/openapi/willow-api/relationships/relationshipsv2_getincomingrelationships.md) ## 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). ### Insert time series values - [POST /time-series](https://developers.willowinc.com/openapi/willow-api/time-series/posttelemetry.md) ### Retrieve a time series - [GET /time-series/{twinId}](https://developers.willowinc.com/openapi/willow-api/time-series/gettimeseriesbyid.md) ### Retrieve the latest value - [GET /time-series/{twinId}/latest](https://developers.willowinc.com/openapi/willow-api/time-series/gettimeseriesbyidlatest.md) ### Retrieve multiple time series - [POST /time-series/ids](https://developers.willowinc.com/openapi/willow-api/time-series/gettimeseriesids.md) ### Retrieve multiple latest values - [POST /time-series/ids/latest](https://developers.willowinc.com/openapi/willow-api/time-series/gettimeseriesidslatest.md) ## 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. Pagination applies only to root elements (ScenarioId == null). When fetching a page, include all children of those roots. Search/filtering applies to both parent and children: If a parent matches, return the parent with all its children. If a child matches, return the child and its parent (even if the parent wouldn’t match by itself). - [POST /insights](https://developers.willowinc.com/openapi/willow-api/insights/postinsightsinsights.md): Returns a paginated list insight. Default page size is 10. ### Retrieve an insight. - [GET /insights/{insightId}](https://developers.willowinc.com/openapi/willow-api/insights/getinsightsinsightsinsightid.md) ## Events Events endpoints enable creating, updating, and deleting discrete occurrences such as Weather Forecast, Calendar events etc. ### List events. - [POST /events](https://developers.willowinc.com/openapi/willow-api/events/posteventsevents.md): Returns a paginated list of events. ### Create or update multiple events. - [PUT /events](https://developers.willowinc.com/openapi/willow-api/events/puteventsevents.md) ### Delete multiple events. - [DELETE /events](https://developers.willowinc.com/openapi/willow-api/events/deleteeventsevents.md) ### Retrieve an event. - [GET /events/{eventId}](https://developers.willowinc.com/openapi/willow-api/events/geteventseventseventid.md) ### List event types. - [GET /events/types](https://developers.willowinc.com/openapi/willow-api/events/geteventseventstypes.md): Returns the possible types that an event can have. ### Upload events from files. - [POST /events/files](https://developers.willowinc.com/openapi/willow-api/events/posteventseventsfiles.md) ## 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. - [POST /tickets](https://developers.willowinc.com/openapi/willow-api/tickets/postticketstickets.md): Returns a paginated list of tickets. Default page size is 100, maximum is 1000. ### Creates a new ticket. - [PUT /tickets](https://developers.willowinc.com/openapi/willow-api/tickets/putticketstickets.md) ### Retrieves a ticket by its Id. - [GET /tickets/{ticketId}](https://developers.willowinc.com/openapi/willow-api/tickets/getticketsticketsticketid.md) ### Applies a JSON Patch document to update specific properties of a ticket. - [PATCH /tickets/{ticketId}](https://developers.willowinc.com/openapi/willow-api/tickets/patchticketsticketsticketid.md): 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. ### Retrieves a ticket attachment by its Id. - [GET /tickets/{ticketId}/attachments/{attachmentId}](https://developers.willowinc.com/openapi/willow-api/tickets/getticketsticketsticketidattachmentsattachmentid.md) ## 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. - [POST /tickets/categories](https://developers.willowinc.com/openapi/willow-api/ticket-metadata/postticketmetadataticketscategories.md): Returns a paginated list of the possible categories that a ticket can have. ### Create a category. - [PUT /tickets/categories](https://developers.willowinc.com/openapi/willow-api/ticket-metadata/putticketmetadataticketscategories.md) ### Update a category. - [PATCH /tickets/categories/{categoryId}](https://developers.willowinc.com/openapi/willow-api/ticket-metadata/patchticketmetadataticketscategoriescategoryid.md) ### List job types. - [POST /tickets/job-types](https://developers.willowinc.com/openapi/willow-api/ticket-metadata/postticketmetadataticketsjobtypes.md): Returns a paginated list of the possible job types that a ticket can have. ### Create a job type. - [PUT /tickets/job-types](https://developers.willowinc.com/openapi/willow-api/ticket-metadata/putticketmetadataticketsjobtypes.md) ### Update a job type. - [PATCH /tickets/job-types/{jobTypeId}](https://developers.willowinc.com/openapi/willow-api/ticket-metadata/patchticketmetadataticketsjobtypesjobtypeid.md) ### List services needed. - [POST /tickets/service-needed](https://developers.willowinc.com/openapi/willow-api/ticket-metadata/postticketmetadataticketsserviceneeded.md): Returns a paginated list of the possible services needed that a ticket can have. ### Create a service needed. - [PUT /tickets/service-needed](https://developers.willowinc.com/openapi/willow-api/ticket-metadata/putticketmetadataticketsserviceneeded.md) ### Update a service needed. - [PATCH /tickets/service-needed/{serviceNeededId}](https://developers.willowinc.com/openapi/willow-api/ticket-metadata/patchticketmetadataticketsserviceneededserviceneededid.md) ### Retrieves a list of ticket status. - [GET /tickets/status](https://developers.willowinc.com/openapi/willow-api/ticket-metadata/getticketmetadataticketsstatus.md) ### Gets the list of ticket priorities. - [GET /tickets/priorities](https://developers.willowinc.com/openapi/willow-api/ticket-metadata/getticketmetadataticketspriorities.md)