Cozify OneAPI (3.0)

Cozify Graph is the primary, unified API surface. Instead of per-resource REST endpoints, a single pair of endpoints dispatches a polymorphic set of typed messages, each selected by its type discriminator:

• PUT /graph/command — change state.
• POST /graph/query — read state.

Commands that start long-running work return an operation you can track to completion, and server-side changes are delivered live as push messages over the SignalR hub stream. The classic per-provider REST endpoints (Hub, Hubs, DeviceRegister) are deprecated in favor of Graph.

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

• resource — A manageable item available through the platform. Hubs, Devices and Sites are examples of resources; resource groups, subscriptions and tags are too.
• resource group — A container that holds related resources for a platform solution. You decide which resources belong to a group based on what makes the most sense for your organization.
• resource provider — A service that supplies platform resources. For example, the canonical site resource provider is Cozify.Sites, which supplies the structural management of site (a.k.a. building) resources. Cozify.Site is accepted as a compatibility alias for clients that model the provider namespace separately from the plural resource type. Cozify.DeviceRegister is another common resource provider.

In addition to the REST endpoints described here, the API is available over a persistent SignalR connection at the /hub/v1 endpoint. See Microsoft's guide to SignalR streaming for how to consume it from a .NET / JavaScript / Java client.

Graph over SignalR

The Graph command/query API is exposed as hub methods that carry the same envelopes as the REST endpoints:

• Command(CommandRequest) returns CommandResponse — the equivalent of PUT /graph/command.
• Query(QueryRequest) returns QueryResponse — the equivalent of POST /graph/query.

Device events — deprecated

Deprecated. This whole feature — the DeviceEventsStream stream, the four subscribe methods, and their request payloads — is superseded by the contracted push stream. Use Push and its DeviceStateDeviceRegisterPush message instead: it carries the same device state, is part of this document rather than hand-copied by each consumer, and delivers the current state of every device in the register as its first messages, so a subscriber has nothing to poll for an initial value.

It still works and is not scheduled for removal. One known consumer remains on it; removal waits on that migration rather than on a date.

1. To receive device events you must open the event stream — otherwise no events are delivered, regardless of subscriptions. Open the DeviceEventsStream stream; its messages are delivered over SignalR and are not part of this OpenAPI document — which is itself a reason to prefer the push.
2. To manage event subscriptions, use the following hub methods:
   • DeviceEventsSubscribeAll(deviceRegisterId) — subscribe to events from all devices in the register.
   • DeviceEventsUnsubscribeAll(deviceRegisterId) — unsubscribe from all device events from the register.
   • DeviceEventsSubscribe(request) — subscribe to events from specific devices in the register. Warning: if you previously subscribed to all events from the same register, this changes nothing — you will still receive events from every device.
   • DeviceEventsUnsubscribe(request) — unsubscribe from specific devices in the register. Warning: if you previously subscribed to all events from the same register, this changes nothing — use DeviceEventsUnsubscribeAll instead.

Note: Cozify supports Transport Layer Security (TLS) 1.2 or later only.

Operations for managing device registers, such as executing commands on device registers and querying device register states.

Cozify Graph is the unified gateway to data and actions in Cozify One. In place of per-resource REST endpoints, a single pair of endpoints - PUT /graph/command to change state and POST /graph/query to read it - dispatches a polymorphic set of typed commands and queries, each selected by its type discriminator. Commands that start long-running work return an operation you can track to completion, and server-side changes are delivered live as push messages over stream.

Operations related to the Cozify Hub, including command execution and querying the state of the hub and its connected devices.

Operations related to the Cozify Hubs services, including command execution and querying the state of the fleet.

Service-level operational endpoints, such as the anonymous status/version probe.