API docs by Redocly

Cozify OneAPI (1.0)

Download OpenAPI specification:

E-mail: support@cozify.fi License: Apache 2.0 Terms of Service

This is OpenAPI specification for Cozify ONE platform.

Terminology

If you are new to Cozify Services, there are some terms you might not be familiar with.

  • resource - A manageable item that is available through Cozify. Hubs, devices and sites are examples of resources. Resource groups, subscriptions and tags are also examples of resources.
  • resource group - A container that holds related resources for an Cozify solution. The resource group includes those resources that you want to manage as a group. You decide which resources belong in a resource group based on what makes the most sense for your organization.
  • resource provider - A service that supplies Cozify resources. For example, a common resource provider is Cozify.Sites, which supplies the structural management of site (aka. Buildings) resource. Cozify.Devices is another common resource provider.

Receiving events from server using SignalR

In addition to the REST endpoints described here, there is also SignalR hub for streaming device events and managing event subscriptions at /hub/v1 endpoint. See the following page for more information about SignalR streams and how to use them with a .NET/JavaScript/Java client: https://learn.microsoft.com/en-us/aspnet/core/signalr/streaming

  1. In order to be able to receive events from the hub, you must open the event stream, otherwise no events will be delivered regardless of subscriptions:
  • The device events stream name is DeviceEventsStream
    • The event type DeviceEvent is defined in this OpenApi document
  • For instructions how to use the server-to-client streaming sections in this article
  1. To manage event subscriptions there are the following methods:
  • DeviceEventsSubscribeAll(string deviceRegisterId)
    • Subscribe to events from all devices in the register
  • DeviceEventsUnsubscribeAll(string deviceRegisterId)
    • Unsubscribe from all device events from the register
  • DeviceEventsSubscribe(SubscribeDeviceEvents subscribeRequest)
    • Subscribe to events from specific devices in the register
    • The SubscribeDeviceEvents type is defined in this OpenApi document.
    • WARNING: If previously subscribed to all events from the same register, this does not change anything; You will still receive events from all devices
  • DeviceEventsUnsubscribe(UnsubscribeDeviceEvents unsubscribeRequest)
    • Unsubscribe from specific devices from the register
    • The UnsubscribeDeviceEvents type is defined in this OpenApi document.
    • WARNING: If previously subscribed to all events from the same register, this does not change anything; You will still receive events from all devices
      • Use DeviceEventsUnsubscribeAll instead in this case

Note

Cozify will only support Transport Layer Security (TLS) 1.2 or later.

Cozify Hub API

Tenants

Tenant commands and querying.

GetActiveTenant

Gets active tenant for current principal.

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "id": "/Tenant/2c269807-b266-4b5e-af95-c807d7aca12c",
  • "tenantId": "2c269807-b266-4b5e-af95-c807d7aca12c",
  • "displayName": "My Company Ab"
}

SetActiveTenant

Set the currently active tenant for logged in principal. When changing the currently active tenant you must retrieve new access token and use it in order to access resources of that tenant.

Authorizations:
OAuth2
Request Body schema: application/json
tenantId
required
string [ 1 .. 50 ] characters

Responses

Request samples

Content type
application/json
{
  • "tenantId": "abcdefgh-1234-5678-9834-73661824c1bc"
}

Response samples

Content type
application/json
{
  • "id": "/Tenant/2c269807-b266-4b5e-af95-c807d7aca12c",
  • "tenantId": "2c269807-b266-4b5e-af95-c807d7aca12c",
  • "displayName": "My Company Ab"
}

List

Gets the tenants for your account.

Authorizations:
OAuth2
query Parameters
pageSize
integer <int32>
Example: pageSize=50

Maximum size of the page. Value must be between 1-2000.

next
string
Example: next=ZbXBsZS1kZXZpY2UtMQ

Cursor to get next page of results if there are any.

prev
string
Example: prev=ASDsZS1kZXZpY2Us

Cursor to get previous page of results if there are any.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    }
}

CreateTenant

Create tenant details for your account.

This is only used internally.
Authorizations:
OAuth2
Request Body schema: application/json
displayName
required
string (DisplayName) [ 1 .. 50 ] characters

Responses

Request samples

Content type
application/json
{
  • "displayName": "West wing"
}

Response samples

Content type
application/json
{
  • "id": "/Tenant/2c269807-b266-4b5e-af95-c807d7aca12c",
  • "tenantId": "2c269807-b266-4b5e-af95-c807d7aca12c",
  • "displayName": "My Company Ab"
}

Get tenant

Gets an tenant by given id.

Authorizations:
OAuth2
path Parameters
tenantId
required
string
Example: 2c269807-b266-4b5e-af95-c807d7aca12c

An tenant id

Responses

Response samples

Content type
application/json
{
  • "id": "/Tenant/2c269807-b266-4b5e-af95-c807d7aca12c",
  • "tenantId": "2c269807-b266-4b5e-af95-c807d7aca12c",
  • "displayName": "My Company Ab"
}

GetTenantTemplates

Get all available templates of given type for tenant.

Authorizations:
OAuth2
path Parameters
tenantId
required
string
templateType
required
string (TemplateTypes)
Enum: "device" "dashboard" "schema"

Responses

Response samples

Content type
application/json
[
  • {
    }
]

AddTenantTemplate

This will add template for the tenant. Template will be available for all resources owned by the tenant.

Authorizations:
OAuth2
path Parameters
tenantId
required
string
templateType
required
string (TemplateTypes)
Enum: "device" "dashboard" "schema"
Request Body schema: application/json
required
id
string [ 1 .. 100 ] ^([a-z0-9-_])+$
displayName
string [ 1 .. 100 ]
content
object

Template content. Expects a JSON object.

setAsDefault
boolean
Default: false

Set the template as default for the template type.

Responses

Request samples

Content type
application/json
{
  • "id": "my-unique-template-id",
  • "displayName": "My template",
  • "content": { },
  • "setAsDefault": false
}

Response samples

Content type
application/json
{
  • "id": "my-unique-template-id",
  • "name": "ZEN",
  • "content": {
    }
}

UpdateTenantTemplate

  • This will fully replace the given template.
Authorizations:
OAuth2
path Parameters
tenantId
required
string
templateId
required
string
templateType
required
string (TemplateTypes)
Enum: "device" "dashboard" "schema"
Request Body schema: application/json
required
displayName
string [ 1 .. 100 ]
content
object

Template content. Expects a JSON object.

setAsDefault
boolean

Set the template as default for the template type.

Responses

Request samples

Content type
application/json
{
  • "displayName": "Renamed template",
  • "content": { },
  • "setAsDefault": true
}

Response samples

Content type
application/json
{
  • "id": "my-unique-template-id",
  • "name": "ZEN",
  • "content": {
    }
}

DeleteTenantTemplate

  • This will delete given tenant template.
Authorizations:
OAuth2
path Parameters
tenantId
required
string
templateType
required
string (TemplateTypes)
Enum: "device" "dashboard" "schema"
templateId
required
string

Responses

Response samples

Content type
application/problem+json
{}

AddTenantDeviceTemplate

Add device configuration template for device type for tenant. This will add device configuration for the tenant. Template will be available on all device registers owned by the tenant.

Authorizations:
OAuth2
path Parameters
tenantId
required
string
deviceType
required
string
Request Body schema: application/json
required
id
string [ 1 .. 100 ] ^([a-z0-9-_])+$
displayName
string [ 1 .. 100 ]
content
object

Template content. Expects a JSON object.

setAsDefault
boolean
Default: false

Set the template as default for the template type.

Responses

Request samples

Content type
application/json
{
  • "id": "my-unique-template-id",
  • "displayName": "My template",
  • "content": { },
  • "setAsDefault": false
}

Response samples

Content type
application/json
{
  • "id": "my-unique-template-id",
  • "name": "ZEN",
  • "content": {
    }
}

UpdateTenantDeviceTemplate

Update device configuration template for tenant. This will fully replace the given template.

Authorizations:
OAuth2
path Parameters
tenantId
required
string
deviceType
required
string
templateId
required
string
Request Body schema: application/json
required
displayName
string [ 1 .. 100 ]
content
object

Template content. Expects a JSON object.

setAsDefault
boolean

Set the template as default for the template type.

Responses

Request samples

Content type
application/json
{
  • "displayName": "Renamed template",
  • "content": { },
  • "setAsDefault": true
}

Response samples

Content type
application/json
{
  • "id": "my-unique-template-id",
  • "name": "ZEN",
  • "content": {
    }
}

DeleteTenantDeviceTemplate

Delete device configuration template for tenant

Authorizations:
OAuth2
path Parameters
tenantId
required
string
deviceType
required
string
templateId
required
string

Responses

Subscriptions

Subscriptions commands and querying.

List

Gets the subscriptions for your account.

Authorizations:
OAuth2
query Parameters
pageSize
integer <int32>
Example: pageSize=50

Maximum size of the page. Value must be between 1-2000.

next
string
Example: next=ZbXBsZS1kZXZpY2UtMQ

Cursor to get next page of results if there are any.

prev
string
Example: prev=ASDsZS1kZXZpY2Us

Cursor to get previous page of results if there are any.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    }
}

Create

Create subscription for your account active tenant.

Authorizations:
OAuth2
Request Body schema: application/json
displayName
required
string (DisplayName) [ 1 .. 50 ] characters
object (Tags)

The collection of tags

Responses

Request samples

Content type
application/json
{
  • "displayName": "West wing",
  • "tags": {
    }
}

Response samples

Content type
application/json
{
  • "id": "/Subscriptions/ae3fc088-3446-4d93-b105-d18700a2dac3",
  • "subscriptionId": "ae3fc088-3446-4d93-b105-d18700a2dac3",
  • "displayName": "West wing",
  • "tags": {
    }
}

Get

Gets an subscription by given id.

Authorizations:
OAuth2
path Parameters
subscriptionId
required
string
Example: ae3fc088-3446-4d93-b105-d18700a2dac3

An subscription id

Responses

Response samples

Content type
application/json
{
  • "id": "/Subscriptions/ae3fc088-3446-4d93-b105-d18700a2dac3",
  • "subscriptionId": "ae3fc088-3446-4d93-b105-d18700a2dac3",
  • "displayName": "West wing",
  • "tags": {
    }
}

Delete

Delete an subscription by given id.

Authorizations:
OAuth2
path Parameters
subscriptionId
required
string
Example: ae3fc088-3446-4d93-b105-d18700a2dac3

An subscription id

Responses

Response samples

Content type
application/problem+json
{}

Resource Groups

Resource groups commands and querying.

List

Gets resource groups in the subscription.

Authorizations:
OAuth2
path Parameters
subscriptionId
required
string
query Parameters
pageSize
integer <int32>
Example: pageSize=50

Maximum size of the page. Value must be between 1-2000.

next
string
Example: next=ZbXBsZS1kZXZpY2UtMQ

Cursor to get next page of results if there are any.

prev
string
Example: prev=ASDsZS1kZXZpY2Us

Cursor to get previous page of results if there are any.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    }
}

Create

Create resource group in the subscription.

Authorizations:
OAuth2
path Parameters
subscriptionId
required
string
Request Body schema: application/json
name
required
string [ 3 .. 50 ] characters
location
required
string
object (Tags)

The collection of tags

Responses

Request samples

Content type
application/json
{
  • "name": "west-resources-rg",
  • "location": "eu-north-1",
  • "tags": {
    }
}

Response samples

Content type
application/json
{
  • "id": "/Subscriptions/ae3fc088-3446-4d93-b105-d18700a2dac3/ResourceGroups/west-resources-rg",
  • "name": "west-resources-rg",
  • "location": "eu-north-1",
  • "tags": {
    }
}

Get

Gets an resource group in given subscription.

Authorizations:
OAuth2
path Parameters
subscriptionId
required
string
Example: ae3fc088-3446-4d93-b105-d18700a2dac3

An subscription id

resourceGroupName
required
string
Example: west-resources-rg

An resource group name

Responses

Response samples

Content type
application/json
{
  • "id": "/Subscriptions/ae3fc088-3446-4d93-b105-d18700a2dac3/ResourceGroups/west-resources-rg",
  • "name": "west-resources-rg",
  • "location": "eu-north-1",
  • "tags": {
    }
}

Delete

Delete an resource group in given subscription.

Authorizations:
OAuth2
path Parameters
subscriptionId
required
string
Example: ae3fc088-3446-4d93-b105-d18700a2dac3

An subscription id

resourceGroupName
required
string
Example: west-resources-rg

An resource group name

Responses

Response samples

Content type
application/problem+json
{}

Resources

Resource commands and querying.

Create

Create resource in given resource group.

Authorizations:
OAuth2
path Parameters
subscriptionId
required
string
Example: ae3fc088-3446-4d93-b105-d18700a2dac3

An subscription id

resourceGroupName
required
string
Example: west-resources-rg

An resource group name

Request Body schema: application/json
required
object (CreateSite)
name
required
string [ 3 .. 50 ] characters
object (Tags)

The collection of tags

Responses

Request samples

Content type
application/json
Example
{
  • "init": {
    },
  • "name": "device-register",
  • "tags": {
    },
  • "provider": "Cozify.Sites"
}

Response samples

Content type
application/json
{
  • "id": "/Subscriptions/ae3fc088-3446-4d93-b105-d18700a2dac3/ResourceGroups/west-resources-rg/Providers/Cozify.DeviceRegister/my-device-register",
  • "name": "my-device-register",
  • "type": "Cozify.DeviceRegister",
  • "location": "eu-north-1",
  • "displayName": "My devices",
  • "tags": {
    }
}

Delete

Delete resource with given name in resource group.

Authorizations:
OAuth2
path Parameters
subscriptionId
required
string
Example: ae3fc088-3446-4d93-b105-d18700a2dac3

An subscription id

resourceGroupName
required
string
Example: west-resources-rg

An resource group name

resourceProvider
required
string
Example: west-resources-rg

An resource group name

resourceName
required
string
Example: my-device-register

An resource name

Responses

Response samples

Content type
application/problem+json
{}

List

Gets resource in the resource group.

Authorizations:
OAuth2
path Parameters
subscriptionId
required
string
resourceGroupName
required
string
query Parameters
pageSize
integer <int32>
Example: pageSize=50

Maximum size of the page. Value must be between 1-2000.

next
string
Example: next=ZbXBsZS1kZXZpY2UtMQ

Cursor to get next page of results if there are any.

prev
string
Example: prev=ASDsZS1kZXZpY2Us

Cursor to get previous page of results if there are any.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    }
}

Get

Gets an resource in given resource group.

Authorizations:
OAuth2
path Parameters
subscriptionId
required
string
Example: ae3fc088-3446-4d93-b105-d18700a2dac3

An subscription id

resourceGroupName
required
string
Example: west-resources-rg

An resource group name

resourceName
required
string
Example: my-device-register

An resource name

Responses

Response samples

Content type
application/json
{
  • "id": "/Subscriptions/ae3fc088-3446-4d93-b105-d18700a2dac3/ResourceGroups/west-resources-rg/Providers/Cozify.DeviceRegister/my-device-register",
  • "name": "my-device-register",
  • "type": "Cozify.DeviceRegister",
  • "location": "eu-north-1",
  • "displayName": "My devices",
  • "tags": {
    }
}

DeviceRegister

Device register operations

Get list of devices in the register.

Paging

The returned results are paged. Default page size is 50 devices. This means that to get list all devices it is necessary to retrieve the subsequent result pages. This can be done using the next cursor that is in links property when there are more results available. The cursor link contains the endpoint and necessary query parameters.

Ordering

By default the devices are ordered by id. Use the orderBy query parameter to change the ordering. Valid values include:

  • name
  • nativeId
  • serialnumber
  • type
  • createdBy
  • modifiedBy

To have devices ordered in descending order, add descending query parameter with value true.

Search

To perform a search/filtering, set value to search query parameter.

Filter

It is also possible to filter the list by specifying value which specific field should contain, in same manner as the search query parameter. When multiple filters and/or search are specified, the device needs to match ALL of them in order to be returned. Possible query parameters include:

  • id
  • name
  • type
  • nativeId
  • serialNumber
  • model
  • manufacturer
  • routing
  • tags (allows multiple parameters, i.e. you can do &tags=one&tags=two)
  • capabilities (allows multiple parameters, i.e. you can do &capabilities=one&capabilities=two)
Authorizations:
OAuth2
path Parameters
registerId
required
string
query Parameters
pageSize
integer <int32>
Example: pageSize=50

Maximum size of the page. Value must be between 1-2000.

next
string or null
Default: null
Example: next=ZbXBsZS1kZXZpY2UtMQ

Cursor to get next page of results if there are any.

prev
string or null
Default: null
Example: prev=AS1kZXZpY2s

Cursor to get previous page of results if there are any.

orderBy
string
Example: orderBy=id

Name of the field to order devices by.

descending
boolean

Set to true to order results in descending order.

search
string

Search string that can be used to filter the results. Searches from every field except timestamps. When set, must be at least 3 characters and at most 100.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    }
}

Add device to register.

Authorizations:
OAuth2
path Parameters
registerId
required
string
Request Body schema: application/json
id
required
string [ 3 .. 50 ] characters ^([a-z0-9-_])+$

Device id.

name
required
string <= 100 characters

Device name

type
string

Type of the device for display purpose.

capabilities
Array of strings

An list of capabilities of the device.

DeviceRoutingInfo (object)
nativeId
string <= 100 characters
Default: ""

Native ID of the device

serialNumber
string <= 100 characters
Default: ""

Serial number of the device

model
string <= 100 characters
Default: ""

Model of the device

manufacturer
string <= 100 characters
Default: ""

Manufacturer of the device

object (Tags)

The collection of tags

Responses

Request samples

Content type
application/json
{
  • "id": "ec83e906-2ea7-4bd8-8d61-75196761c3eb",
  • "name": "Device 12345",
  • "type": "COZIFY_HUB",
  • "capabilities": [
    ],
  • "routing": {
    },
  • "nativeId": "EXAMPLE_2_1_00035536",
  • "serialNumber": "",
  • "model": "",
  • "manufacturer": "",
  • "tags": {
    }
}

Response samples

Content type
application/json
{
  • "id": "ec83e906-2ea7-4bd8-8d61-75196761c3eb",
  • "isActive": true,
  • "name": "Device 12345",
  • "type": "COZIFY_HUB",
  • "capabilities": [
    ],
  • "createdAt": 1600255801000,
  • "modifiedAt": 1663327801000,
  • "routing": {
    },
  • "nativeId": "EXAMPLE_2_1_00035536",
  • "serialNumber": "",
  • "model": "",
  • "manufacturer": "",
  • "tags": {
    }
}

Get device metadata.

Authorizations:
OAuth2
path Parameters
registerId
required
string
deviceId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "ec83e906-2ea7-4bd8-8d61-75196761c3eb",
  • "isActive": true,
  • "name": "Device 12345",
  • "type": "COZIFY_HUB",
  • "capabilities": [
    ],
  • "createdAt": 1600255801000,
  • "modifiedAt": 1663327801000,
  • "routing": {
    },
  • "nativeId": "EXAMPLE_2_1_00035536",
  • "serialNumber": "",
  • "model": "",
  • "manufacturer": "",
  • "tags": {
    }
}

UpdateDeviceMetadata

Update device metadata. This will replace existing information.

Authorizations:
OAuth2
path Parameters
registerId
required
string
deviceId
required
string
Request Body schema: application/json
name
required
string <= 100 characters

Device name

capabilities
Array of strings

An list of capabilities of the device.

(DeviceRoutingInfo (object or null))

Routing information for commands

nativeId
string <= 100 characters
Default: ""

Native ID of the device

serialNumber
string <= 100 characters
Default: ""

Serial number of the device

model
string <= 100 characters
Default: ""

Model of the device

manufacturer
string <= 100 characters
Default: ""

Manufacturer of the device

object (Tags)

The collection of tags

Responses

Request samples

Content type
application/json
{
  • "name": "Device 12345",
  • "capabilities": [
    ],
  • "routing": {
    },
  • "nativeId": "EXAMPLE_2_1_00035536",
  • "serialNumber": "",
  • "model": "",
  • "manufacturer": "",
  • "tags": {
    }
}

Response samples

Content type
application/json
{
  • "id": "ec83e906-2ea7-4bd8-8d61-75196761c3eb",
  • "isActive": true,
  • "name": "Device 12345",
  • "type": "COZIFY_HUB",
  • "capabilities": [
    ],
  • "createdAt": 1600255801000,
  • "modifiedAt": 1663327801000,
  • "routing": {
    },
  • "nativeId": "EXAMPLE_2_1_00035536",
  • "serialNumber": "",
  • "model": "",
  • "manufacturer": "",
  • "tags": {
    }
}

Remove device from register.

Authorizations:
OAuth2
path Parameters
registerId
required
string
deviceId
required
string

Responses

Send a command to a device.

Authorizations:
OAuth2
path Parameters
registerId
required
string
deviceId
required
string

Responses

Send a execute command to a device.

Authorizations:
OAuth2
path Parameters
registerId
required
string
deviceId
required
string
Request Body schema:
required
string <binary>

Responses

Request samples

Content type
No sample

Get latest reported state of a device.

Authorizations:
OAuth2
path Parameters
registerId
required
string
deviceId
required
string

Responses

Register Cozify Hub as an gateway device to register.

Authorizations:
OAuth2
path Parameters
registerId
required
string
Request Body schema: application/json
required
serialNumber
required
string [ 2 .. 100 ] characters

Serial number of the Hub device

name
string [ 3 .. 100 ] characters

Device name

model
string <= 100 characters
Default: ""

Model of the device

manufacturer
string <= 100 characters
Default: ""

Manufacturer of the device

object (Tags)

The collection of tags

Responses

Request samples

Content type
application/json
{
  • "serialNumber": "20021212-X-0202",
  • "name": "Hub 0202",
  • "model": "",
  • "manufacturer": "",
  • "tags": {
    }
}

Response samples

Content type
application/json
{
  • "id": "ec83e906-2ea7-4bd8-8d61-75196761c3eb",
  • "isActive": true,
  • "name": "Device 12345",
  • "type": "COZIFY_HUB",
  • "capabilities": [
    ],
  • "createdAt": 1600255801000,
  • "modifiedAt": 1663327801000,
  • "routing": {
    },
  • "nativeId": "EXAMPLE_2_1_00035536",
  • "serialNumber": "",
  • "model": "",
  • "manufacturer": "",
  • "tags": {
    }
}

Restart Cozify Hub

Authorizations:
OAuth2
path Parameters
registerId
required
string
deviceId
required
string

Responses

Reboot Cozify Hub

Authorizations:
OAuth2
path Parameters
registerId
required
string
deviceId
required
string

Responses

Get Cozify Hub users

Authorizations:
OAuth2
path Parameters
registerId
required
string
deviceId
required
string

Responses

Response samples

Content type
application/json
{
  • "users": [
    ]
}

Invite user to Cozify Hub

Authorizations:
OAuth2
path Parameters
registerId
required
string
deviceId
required
string
Request Body schema: application/json
required
email
string <= 256 characters

Email address

role
string <= 64 characters

One of the known values: OWNER, ADMIN, USER, REMOTEGUEST, GUEST, ANONYMOUS

Responses

Request samples

Content type
application/json
{
  • "email": "mail@example.com",
  • "role": "ADMIN"
}

Response samples

Content type
application/json
{
  • "userId": "fbb836df-b52d-4e77-a89d-1a36a403b2e4",
  • "email": "mail@example.com",
  • "role": "ADMIN"
}

Get Cozify Hub user

Authorizations:
OAuth2
path Parameters
registerId
required
string
deviceId
required
string
userId
required
string

Responses

Response samples

Content type
application/json
{
  • "userId": "fbb836df-b52d-4e77-a89d-1a36a403b2e4",
  • "email": "mail@example.com",
  • "role": "ADMIN"
}

Revoke Cozify Hub user

Authorizations:
OAuth2
path Parameters
registerId
required
string
deviceId
required
string
userId
required
string

Responses

devices templates

Device register template operations

devices configuration

Device configuration endpoints

Sites

Site and site entity operations

Get site metadata.

Authorizations:
OAuth2
path Parameters
siteId
required
string

Responses

Response samples

Content type
application/json
{
  • "displayName": "My Site",
  • "createdAt": 1600255801000,
  • "modifiedAt": 1663327801000,
  • "attributes": null
}

Update site. This is partial update.

  • This is a partial update. Only content in the request will be updated.
  • To remove an attribute, set it's value field to null.
Authorizations:
OAuth2
path Parameters
siteId
required
string
Request Body schema: application/json
required
displayName
string <= 50 characters
required
Array of StringAttributeValue (object) or LongAttributeValue (object) or IntAttributeValue (object) or DoubleAttributeValue (object) or BooleanAttributeValue (object) or JsonAttributeValue (object) or null (SiteAttributes)
Default: null

Any of the attribute values inheriting from AttributeValue

Responses

Request samples

Content type
application/json
{
  • "displayName": "My Site",
  • "attributes": null
}

Response samples

Content type
application/json
{
  • "displayName": "My Site",
  • "createdAt": 1600255801000,
  • "modifiedAt": 1663327801000,
  • "attributes": null
}

Find entities in the site.

TIPS:

  • To get single entity, set the globPattern parameter to entity path.
    • For example building/1 (get building 1)
  • To find multiple entities, set the glob to be a glob.
    • For example ++/area (get all areas)
  • To get all entities of a site, use *

NOTE: The results are paged. To get next page of results use the next cursor in the response when it is not null.

Authorizations:
OAuth2
path Parameters
siteId
required
string
globPattern
required
string
Example: building/1/floor/a
query Parameters
pageSize
integer <int32>
Example: pageSize=50

Maximum size of the page. Value must be between 1-2000.

next
string or null
Default: null
Example: next=ZXBsZS1kZXZpY2UtMQ

Cursor to get next page of results if there are any.

prev
string or null
Default: null
Example: prev=ZS1kZXZpY2

Cursor to get previous page of results if there are any.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    }
}

Create new site entity under the current resource.

  • The parent entity must exist.
Authorizations:
OAuth2
path Parameters
siteId
required
string
globPattern
required
string
Example: building/1
Request Body schema: application/json
type
string [ 1 .. 50 ] characters ^([a-z0-9-_])+$
name
string [ 1 .. 50 ] characters ^([a-z0-9-_])+$
displayName
string <= 50 characters
Array of StringAttributeValue (object) or LongAttributeValue (object) or IntAttributeValue (object) or DoubleAttributeValue (object) or BooleanAttributeValue (object) or JsonAttributeValue (object) or null (SiteAttributes)
Default: null

Any of the attribute values inheriting from AttributeValue

Responses

Request samples

Content type
application/json
Example

Add new entity

{
  • "type": "building",
  • "name": "1"
}

Response samples

Content type
application/json
{
  • "displayName": "My Site",
  • "createdAt": 1600255801000,
  • "modifiedAt": 1663327801000,
  • "attributes": null
}

Update site entity.

  • This is a partial update. Only content in the request will be updated.
  • To remove an attribute, set it's value field to null.
  • Entity can only be moved when:
    • It does not have child entities
    • The new parent entity exists
    • Entity with the would be new path does not exist before the move
Authorizations:
OAuth2
path Parameters
siteId
required
string
globPattern
required
string
Example: building/1/floor/a/area/2
Request Body schema: application/json
displayName
string <= 50 characters
Array of StringAttributeValue (object) or LongAttributeValue (object) or IntAttributeValue (object) or DoubleAttributeValue (object) or BooleanAttributeValue (object) or JsonAttributeValue (object) or null (SiteAttributes)
Default: null

Any of the attribute values inheriting from AttributeValue

changeParentPath
string or null
Default: null

Move the entity under this parent path. The parent must exist. Only set this value if you intend to move the entity in the site.

Responses

Request samples

Content type
application/json
{
  • "displayName": "My Beautiful Entity",
  • "attributes": null,
  • "changeParentPath": null
}

Response samples

Content type
application/json
{
  • "displayName": "My Site",
  • "createdAt": 1600255801000,
  • "modifiedAt": 1663327801000,
  • "attributes": null
}

Delete site entity

Authorizations:
OAuth2
path Parameters
siteId
required
string
globPattern
required
string

Responses

Get site properties.

Authorizations:
OAuth2
path Parameters
siteId
required
string

Responses

Response samples

Content type
application/json
{
  • "siteType": { },
  • "timeZone": "Europe/Helsinki",
  • "features": {
    }
}

Update site properties. This is full update.

  • This is full update. All properties will be replaced.
Authorizations:
OAuth2
path Parameters
siteId
required
string
Request Body schema: application/json
required
object (SiteType)

Base type for site types

timeZone
string

Time zone of the site in TZ format.

object (SiteFeatures)

Features enabled for the site.

Responses

Request samples

Content type
application/json
{
  • "siteType": { },
  • "timeZone": "Europe/Helsinki",
  • "features": {
    }
}

Response samples

Content type
application/json
{
  • "siteType": { },
  • "timeZone": "Europe/Helsinki",
  • "features": {
    }
}

Get site schema used for validating the site structure.

Authorizations:
OAuth2
path Parameters
siteId
required
string

Responses

Response samples

Content type
application/json
{
  • "attributes": [
    ],
  • "entities": [
    ]
}

Replace existing site schema.

  • This will replace any existing site schema. The schema is used to validate changes made to the site and it's entities.
  • When there are attributes defined that have typeSchemaName set, the schemas must contain the JSON schema used to validate the attribute.
Authorizations:
OAuth2
path Parameters
siteId
required
string
Request Body schema: application/json
required
Array of objects (AttributeDefinition)

Attributes the site can or must have. When empty no attributes are allowed. To allow arbitrary attributes define wildcard attributes with asterisk.

Array of objects (EntityDefinition)

Entities which can be added to the site.

Responses

Request samples

Content type
application/json
{
  • "attributes": [
    ],
  • "entities": [
    ]
}

Response samples

Content type
application/json
{
  • "attributes": [
    ],
  • "entities": [
    ]
}

Get site events egress targets. Deprecated

Authorizations:
OAuth2
path Parameters
siteId
required
string
query Parameters
next
string or null
Default: null
Example: next=ZbXBsZS1kZXZpY2UtMQ

Cursor to get next page of results if there are any.

prev
string or null
Default: null
Example: prev=AssZS1kZXZpY2s

Cursor to get previous page of results if there are any.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    }
}

Create site events egress target. Deprecated

This endpoint accepts any egress target as long as the type discriminator is used.

Authorizations:
OAuth2
path Parameters
siteId
required
string
Request Body schema: application/json
required
url
required
string

The URL of the REST endpoint to which event batches will be sent.

method
required
string
Default: "POST"
Enum: "POST" "PUT"

The HTTP method (POST or PUT) used to send the event batch to the target URL.

object

A collection of HTTP headers to be included in each request to the target URL.

serverScript
string or null
Default: null

JavaScript code to be executed on the server for filtering or manipulating events before they are sent in the request.

requestTimeoutSeconds
number or null <double> [ 1 .. 60 ]
Default: null

The timeout for the HTTP request in seconds. Must be between 1 and 60 seconds.

$type
required
string

A discriminator to identify the type of egress target.

id
required
string [ 3 .. 50 ] characters ^[a-zA-Z0-9]+$

A unique identifier for this specific egress configuration at the site. The identifier must be between 3 and 50 characters in length and consist only of alphanumeric characters (no special characters or spaces).

isEnabled
boolean
Default: true

Indicates whether the egress target is enabled. If false, events will not be sent to the target.

fetchMaxEvents
integer [ 1 .. 10000 ]
Default: 10

The maximum number of events to include in each batch sent to the target URL. Must be between 1 and 10000.

fetchWaitMaxMs
integer [ 2 .. 60000 ]
Default: 10

The maximum amount of time in milliseconds to wait before sending a batch of events, even if the batch size has not been reached. Must be between 2 ms and 60000 ms.

Responses

Request samples

Content type
application/json
Example
{
  • "url": "string",
  • "method": "POST",
  • "headers": {
    },
  • "serverScript": null,
  • "requestTimeoutSeconds": null,
  • "$type": "rest",
  • "id": "monitor",
  • "isEnabled": true,
  • "fetchMaxEvents": 10,
  • "fetchWaitMaxMs": 10
}

Response samples

Content type
application/json
Example
{
  • "url": "string",
  • "method": "POST",
  • "headers": {
    },
  • "serverScript": null,
  • "requestTimeoutSeconds": null,
  • "$type": "rest",
  • "id": "monitor",
  • "isEnabled": true,
  • "fetchMaxEvents": 10,
  • "fetchWaitMaxMs": 10
}

Update existing site events egress target. Deprecated

This endpoint accepts any egress target as long as the type discriminator is used and matches the existing target.

Authorizations:
OAuth2
path Parameters
siteId
required
string
Request Body schema: application/json
required
One of
url
required
string

The URL of the REST endpoint to which event batches will be sent.

method
required
string
Default: "POST"
Enum: "POST" "PUT"

The HTTP method (POST or PUT) used to send the event batch to the target URL.

object

A collection of HTTP headers to be included in each request to the target URL.

serverScript
string or null
Default: null

JavaScript code to be executed on the server for filtering or manipulating events before they are sent in the request.

requestTimeoutSeconds
number or null <double> [ 1 .. 60 ]
Default: null

The timeout for the HTTP request in seconds. Must be between 1 and 60 seconds.

$type
required
string

A discriminator to identify the type of egress target.

id
required
string [ 3 .. 50 ] characters ^[a-zA-Z0-9]+$

A unique identifier for this specific egress configuration at the site. The identifier must be between 3 and 50 characters in length and consist only of alphanumeric characters (no special characters or spaces).

isEnabled
boolean
Default: true

Indicates whether the egress target is enabled. If false, events will not be sent to the target.

fetchMaxEvents
integer [ 1 .. 10000 ]
Default: 10

The maximum number of events to include in each batch sent to the target URL. Must be between 1 and 10000.

fetchWaitMaxMs
integer [ 2 .. 60000 ]
Default: 10

The maximum amount of time in milliseconds to wait before sending a batch of events, even if the batch size has not been reached. Must be between 2 ms and 60000 ms.

Responses

Request samples

Content type
application/json
{
  • "$type": "rest",
  • "id": "monitor",
  • "isEnabled": true,
  • "fetchMaxEvents": 10,
  • "fetchWaitMaxMs": 10
}

Response samples

Content type
application/json
Example
{
  • "url": "string",
  • "method": "POST",
  • "headers": {
    },
  • "serverScript": null,
  • "requestTimeoutSeconds": null,
  • "$type": "rest",
  • "id": "monitor",
  • "isEnabled": true,
  • "fetchMaxEvents": 10,
  • "fetchWaitMaxMs": 10
}

Delete site events egress target. Deprecated

Authorizations:
OAuth2
path Parameters
siteId
required
string
targetId
required
string

Responses

Get site event egress targets. Deprecated

Authorizations:
OAuth2
path Parameters
siteId
required
string
Example: customer-site-1
targetId
required
string
Example: monitor

Responses

Response samples

Content type
application/json
Example
{
  • "url": "string",
  • "method": "POST",
  • "headers": {
    },
  • "serverScript": null,
  • "requestTimeoutSeconds": null,
  • "$type": "rest",
  • "id": "monitor",
  • "isEnabled": true,
  • "fetchMaxEvents": 10,
  • "fetchWaitMaxMs": 10
}

sites operations

Special site and entity operations

site dashboard templates

Site dashboard template operations

Get all available templates for site

Authorizations:
OAuth2
path Parameters
siteId
required
string
templateType
required
string (TemplateTypes)
Enum: "device" "dashboard" "schema"

Only 'schema' and 'dashboard' are valid options for site.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get template

Authorizations:
OAuth2
path Parameters
siteId
required
string
templateType
required
string (TemplateTypes)
Enum: "device" "dashboard" "schema"

Only 'schema' and 'dashboard' are valid options for site.

templateId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "my-unique-template-id",
  • "name": "ZEN",
  • "content": {
    }
}

DeviceRegister templates

Get all available device templates for all device types

Authorizations:
OAuth2
path Parameters
registerId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get templates for device type

Authorizations:
OAuth2
path Parameters
registerId
required
string
deviceType
required
string

Responses

Response samples

Content type
application/json
{
  • "type": "COZIFY_HUB",
  • "defaultTemplateId": "",
  • "templates": [
    ]
}

DeviceRegister configuration

Get device configuration

Authorizations:
OAuth2
path Parameters
registerId
required
string
deviceId
required
string

Responses

Response samples

Content type
application/json
{ }

Update device configuration

Authorizations:
OAuth2
path Parameters
registerId
required
string
deviceId
required
string
Request Body schema: application/json
required

Configuration value to set for device

property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }