API docs by Redocly

Cozify Han API (1.0)

Download OpenAPI specification:

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

This is the OpenAPI specification for the Cozify HAN reader.

System

System status, events, and connectivity

Info

Returns general information about the HAN reader, including UUID, name, model, serial, firmware version, state, MAC address, network IPs, online status, and release channel.

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "type": "HAN_STATE_MESSAGE",
  • "uuid": "7f2f8c1e-2c6d-4a25-b2b1-6f6a27d5f5de",
  • "name": "Cozify-HAN-123-456",
  • "model": "HAN",
  • "serial": "HAN12345678",
  • "version": "1.0.1.0",
  • "state": "REGISTERED",
  • "mac": "AA:BB:CC:DD:EE:FF",
  • "ethIp": "192.168.1.50",
  • "wifiIp": "192.168.2.50",
  • "online": true,
  • "channel": "release"
}

WebSocket

Establishes a WebSocket connection to the HAN reader. This endpoint upgrades the HTTP connection to a WebSocket (ws:// or wss://). The WebSocket protocol is used for real-time, bidirectional communication. Current payload behavior:

  • Sends an initial state payload with discriminator type = HAN_STATE_MESSAGE.
  • Streams electricity meter payloads with discriminator type = HAN_METER_MESSAGE.
Authorizations:
None

Responses

ServerSentEvents

Opens a stream of server-sent events (SSE) from the HAN reader. The response uses the text/event-stream content type. Current event names and payload discriminator values:

  • HAN_METER_MESSAGE: streams electricity meter payloads.
  • HAN_STATE_MESSAGE: initial state snapshot sent when the client connects.
Authorizations:
None

Responses

Health

Returns health and status information about the HAN reader, including UUID, hostname, heap memory statistics, CPU reset reason, and uptime.

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "type": "HAN_HEALTH_MESSAGE",
  • "uuid": "7f2f8c1e-2c6d-4a25-b2b1-6f6a27d5f5de",
  • "hostname": "Cozify-HAN-123-456",
  • "free_heap_size": 182144,
  • "minimum_free_heap_size": 176320,
  • "cpu_reset_reason": "RST_POWERON",
  • "uptime_ms": 1234567
}

Configuration

HAN reader configuration and setup

Setup

Sets up the HAN reader with basic WiFi configuration. Accepts a JSON object with WiFi enablement, SSID, and password. Returns success status and message. May trigger a HAN reader reboot.

Authorizations:
None
Request Body schema: application/json
required
s
required
boolean

Enable WiFi (must be true)

ss
required
string

WiFi SSID

sp
required
string

WiFi password

Responses

Request samples

Content type
application/json
{
  • "s": true,
  • "ss": "string",
  • "sp": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Configuration

Returns the current HAN reader configuration, including firmware version, timezone, spot price usage, fixed price, pricing and fuse settings, ethernet, and WiFi settings.

  • Pricing and fuse settings include the main fuse value used by the HAN reader.
  • Ethernet and WiFi settings include enablement, network mode (dhcp/static), and network details.
  • Passwords and secrets are masked as "***" if configured.
Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "type": "HAN_CONFIGURATION",
  • "v": "string",
  • "t": "string",
  • "s": true,
  • "p": 0,
  • "m": {
    },
  • "e": {
    },
  • "w": {
    }
}

ConfigurationUpdate

Updates the HAN reader configuration. Accepts a JSON object with any subset of the configuration fields as defined in the GET response. Returns success status and message. Some changes may require a HAN reader reboot.

Authorizations:
None
Request Body schema: application/json
required
s
boolean

Use spot price

p
number

Fixed price

object

Pricing and fuse settings used by the HAN reader

object

Ethernet settings

object

WiFi settings

Responses

Request samples

Content type
application/json
{
  • "s": true,
  • "p": 0,
  • "m": {
    },
  • "e": {
    },
  • "w": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Network

Network operations and WiFi management

ScanNetworks

Initiates or returns the result of a WiFi network scan. If a scan is running or requested, returns status. If scan is complete, returns a list of found networks with details.

Note: Performing a WiFi scan may temporarily disconnect the HAN reader from its currently connected WiFi network.

  • If the scan is running or just started, returns { "status": "SCAN_RUNNING" }.
  • If the scan failed, returns { "status": "SCAN_FAILED" }.
  • If the scan succeeded, returns { "status": "SCAN_SUCCESS", "networks": [...] }.

Each network entry includes SSID, BSSID, RSSI, channel, and authentication type.

Authorizations:
None
header Parameters
X-Scan-Start
string

If present, triggers a new WiFi scan.

Responses

Response samples

Content type
application/json
{
  • "status": "SCAN_RUNNING",
  • "networks": [
    ]
}

Meter

Electricity meter data reported by the HAN reader

Meter

Returns the latest electricity meter data received by the HAN reader. This endpoint is intended for the latest live reading values reported by the electricity meter.

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "type": "HAN_METER_MESSAGE",
  • "ts": 173568240000,
  • "ic": 1000,
  • "ec": 10,
  • "ric": 1,
  • "rec": 1,
  • "p": [
    ],
  • "pi": [
    ],
  • "pe": [
    ],
  • "r": [
    ],
  • "ri": [
    ],
  • "re": [
    ],
  • "u": [
    ],
  • "i": [
    ]
}

Meter identity

Returns low-churn electricity meter identity fields parsed from HAN telegrams. This endpoint is intended for metadata that changes rarely, so clients can fetch meter identity separately from high-frequency /meter polling.

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "type": "HAN_METER_IDENTITY_MESSAGE",
  • "manufacturerId": "KFM",
  • "deviceType": "E",
  • "meterId": "A123456789012345",
  • "meterName": "AM550"
}