TR-181 TRData Ingest

This API ingests TRData telemetry snapshots derived from the TR-181 Device Data Model published by the Broadband Forum.

TRData can be delivered via:

• HTTPS POST to the HomeNetworkIQ ingest endpoint
• NATS publish to a tenant-scoped subject

---

Endpoints

HTTPS

• POST https://api.homenetworkiq.com/tr/v1/ingest

NATS

• Server: api.homenetworkiq.com:4222
• Subject template: hniq.tenant.tr.{tenantId}

---

Authentication (JWT Bearer)

All calls are JWT protected.

HTTPS

Send:

• Authorization: Bearer <JWT>
• Content-Type: application/json

NATS

JWT Bearer is provided as a NATS header:

• Authorization: Bearer <JWT>

If your publisher cannot set NATS headers, define a JSON envelope (e.g. { "jwt": "...", "data": { ...TRData } }) and update the examples below accordingly.

---

Publish TRData

HTTPS POST

Request

POST https://api.homenetworkiq.com/tr/v1/ingest

Headers

• Authorization: Bearer <JWT>
• Content-Type: application/json

Body

• A JSON document conforming to the TRData schema (see “Schema” below).

Success / Errors

Because response codes/bodies were not specified, clients should treat any 2xx as a successful acceptance.

Typical errors:

• 400 invalid JSON / schema validation failure
• 401 missing/invalid JWT
• 403 JWT valid but not authorized for tenant/resource
• 429 throttled (if enabled)
• 5xx server error

Example (curl)

curl -X POST "https://api.homenetworkiq.com/tr/v1/ingest" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "customerRef": "CUST-123",
    "networkStatus": "ONLINE",
    "createdDateTime": "2026-02-12T09:15:30Z",
    "wanInfo": {
      "wanIp": "192.168.1.2",
      "publicIp": "203.0.113.10",
      "wanMac": "AA:BB:CC:DD:EE:FF",
      "dialType": "PPPoE",
      "uptime": 123456,
      "gateway": "192.168.1.1",
      "negotiationSpeed": "1Gbps",
      "isp": "ExampleISP",
      "networkType": "FTTP",
      "signalStrength": -55,
      "uplinkRate": 1000,
      "downlinkRate": 1000,
      "connectionTime": 123456
    },
    "homeSsids": [],
    "homeClients": [],
    "neighbourhoodDevices": [],
    "wifiDataElements": {
      "controllerId": "controller-1",
      "nodes": [
        {
          "id": "node-1",
          "role": "CONTROLLER",
          "ip": "192.168.1.1",
          "radios": [
            {
              "band": "5GHz",
              "bandwidth": "80MHz",
              "channel": 36,
              "ssids": [{ "ssid": "HomeWiFi", "bssid": "11:22:33:44:55:66" }],
              "clientsConnected": 1,
              "clients": [
                { "mac": "AA:AA:AA:AA:AA:AA", "hostname": "laptop", "ipv4": "192.168.1.50", "signal": -48 }
              ],
              "traffic": { "bytesReceived": 123456, "bytesSent": 654321 },
              "utilization": 12,
              "noise": -92
            }
          ]
        }
      ]
    }
  }'

NATS Publish

Subject

Publish to the tenant-scoped subject:

hniq.tenant.tr.{tenantId}

Example:

hniq.tenant.tr.acme

Message

Payload: the raw TRData JSON (no wrapper)
Auth: NATS header Authorization: Bearer <JWT>

Example (nats CLI)

# Example assumes your nats CLI supports headers.
# Replace tenant + JWT + payload as required.

nats pub "hniq.tenant.tr.acme" \
  --header "Authorization: Bearer $JWT" \
  '{
    "customerRef": "CUST-123",
    "networkStatus": "ONLINE",
    "createdDateTime": "2026-02-12T09:15:30Z",
    "wifiDataElements": {
      "nodes": [
        {
          "role": "CONTROLLER",
          "radios": [
            { "ssids": [], "clientsConnected": 0, "clients": [], "traffic": { "bytesReceived": 0, "bytesSent": 0 } }
          ]
        }
      ]
    }
  }'

If you use request-reply (acknowledgements) or JetStream, add the reply/ack contract here. This page currently documents fire-and-forget publish.

---

Data Model (TR-181)

TRData represents telemetry aligned to TR-181 concepts (WAN properties, SSIDs, clients, radios, backhaul, QoE).

---

Schema (TRData JSON Schema)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://homenetworkiq.com/schemas/TRData.schema.json",
  "title": "TRData",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "customerRef": { "type": "string" },
    "networkStatus": { "type": "string" },
    "wanInfo": { "$ref": "#/$defs/WanInfo" },
    "homeSsids": {
      "type": "array",
      "items": { "$ref": "#/$defs/SSID" },
      "default": []
    },
    "homeClients": {
      "type": "array",
      "items": { "$ref": "#/$defs/HomeClient" },
      "default": []
    },
    "neighbourhoodDevices": {
      "type": "array",
      "items": { "$ref": "#/$defs/NeighbourhoodDevice" },
      "default": []
    },
    "createdDateTime": {
      "type": ["string", "null"],
      "description": "LocalDateTime serialized as string",
      "format": "date-time"
    },
    "wifiDataElements": { "$ref": "#/$defs/WiFiDataElements" }
  },
  "required": ["customerRef", "networkStatus", "wifiDataElements"],
  "$defs": {
    "WanInfo": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "wanIp": { "type": "string" },
        "publicIp": { "type": "string" },
        "wanMac": { "type": "string" },
        "dialType": { "type": "string" },
        "uptime": { "type": "integer" },
        "gateway": { "type": "string" },
        "negotiationSpeed": { "type": "string" },
        "isp": { "type": "string" },
        "networkType": { "type": "string" },
        "signalStrength": { "type": "integer" },
        "uplinkRate": { "type": "integer" },
        "downlinkRate": { "type": "integer" },
        "connectionTime": { "type": "integer" }
      },
      "required": [
        "wanIp",
        "publicIp",
        "wanMac",
        "dialType",
        "uptime",
        "gateway",
        "negotiationSpeed",
        "isp",
        "networkType",
        "signalStrength",
        "uplinkRate",
        "downlinkRate",
        "connectionTime"
      ]
    },
    "SSID": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "name": { "type": ["string", "null"], "default": "" },
        "band": { "type": ["string", "null"], "default": "" },
        "selectedChannel": { "type": ["string", "null"], "default": "" },
        "channel": { "type": ["string", "null"], "default": "" },
        "bandwidth": { "type": ["string", "null"], "default": "" }
      }
    },
    "HomeClient": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "name": { "type": ["string", "null"], "default": "" },
        "ip": { "type": ["string", "null"], "default": "" },
        "mac": { "type": ["string", "null"], "default": "" },
        "status": { "type": ["string", "null"], "default": "" },
        "connectDeviceName": { "type": ["string", "null"], "default": "" },
        "connectType": { "type": ["string", "null"], "default": "" },
        "connectBand": { "type": ["string", "null"], "default": "" },
        "downstream": { "type": ["string", "null"], "default": "" },
        "upstream": { "type": ["string", "null"], "default": "" },
        "linkRate": { "type": ["string", "null"], "default": "" },
        "duration": { "type": ["string", "null"], "default": "" },
        "rssi": { "type": ["string", "null"], "default": "" }
      }
    },
    "NeighbourhoodDevice": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "bssid": { "type": ["string", "null"], "default": "" },
        "basicDataTransferRates": { "type": ["string", "null"], "default": "" },
        "beaconPeriod": { "type": ["string", "null"], "default": "" },
        "channel": { "type": ["string", "null"], "default": "" },
        "dtimPeriod": { "type": ["string", "null"], "default": "" },
        "encryptionMode": { "type": ["string", "null"], "default": "" },
        "mode": { "type": ["string", "null"], "default": "" },
        "noise": { "type": ["string", "null"], "default": "" },
        "operatingChannelBandwidth": { "type": ["string", "null"], "default": "" },
        "operatingFrequencyBand": { "type": ["string", "null"], "default": "" },
        "operatingStandards": { "type": ["string", "null"], "default": "" },
        "radio": { "type": ["string", "null"], "default": "" },
        "ssid": { "type": ["string", "null"], "default": "" },
        "securityModeEnabled": { "type": ["string", "null"], "default": "" },
        "signalStrength": { "type": ["string", "null"], "default": "" },
        "supportedDataTransferRates": { "type": ["string", "null"], "default": "" },
        "supportedStandards": { "type": ["string", "null"], "default": "" }
      }
    },
    "WiFiDataElements": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "controllerId": { "type": ["string", "null"] },
        "nodes": {
          "type": "array",
          "items": { "$ref": "#/$defs/HrNode" }
        }
      },
      "required": ["nodes"]
    },
    "NodeRole": {
      "type": "string",
      "enum": ["CONTROLLER", "CHILD"]
    },
    "HrNode": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "id": { "type": ["string", "null"] },
        "role": { "$ref": "#/$defs/NodeRole" },
        "ip": { "type": ["string", "null"] },
        "radios": {
          "type": "array",
          "items": { "$ref": "#/$defs/HrRadio" }
        },
        "backhaul": { "$ref": "#/$defs/HrBackhaul" },
        "qoe": { "$ref": "#/$defs/HrQoE" }
      },
      "required": ["role", "radios"]
    },
    "HrRadio": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "band": { "type": ["string", "null"], "description": "e.g., 2.4GHz, 5GHz" },
        "bandwidth": { "type": ["string", "null"], "description": "e.g., 20MHz, 80MHz" },
        "channel": { "type": ["integer", "null"] },
        "ssids": {
          "type": "array",
          "items": { "$ref": "#/$defs/HrSsid" }
        },
        "clientsConnected": { "type": "integer" },
        "clients": {
          "type": "array",
          "items": { "$ref": "#/$defs/HrClient" }
        },
        "traffic": { "$ref": "#/$defs/HrTraffic" },
        "utilization": { "type": ["integer", "null"] },
        "noise": { "type": ["integer", "null"] }
      },
      "required": ["ssids", "clientsConnected", "clients", "traffic"]
    },
    "HrSsid": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "ssid": { "type": ["string", "null"] },
        "bssid": { "type": ["string", "null"] }
      }
    },
    "HrClient": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "mac": { "type": ["string", "null"] },
        "hostname": { "type": ["string", "null"] },
        "ipv4": { "type": ["string", "null"] },
        "ipv6": { "type": ["string", "null"] },
        "signal": { "type": ["integer", "null"] },
        "lastDownlinkMbps": { "type": ["number", "null"] },
        "lastUplinkMbps": { "type": ["number", "null"] },
        "retransmissions": { "type": ["integer", "null"] },
        "bytesReceived": { "type": ["integer", "null"] },
        "bytesSent": { "type": ["integer", "null"] },
        "packetsReceived": { "type": ["integer", "null"] },
        "packetsSent": { "type": ["integer", "null"] },
        "errorsReceived": { "type": ["integer", "null"] },
        "errorsSent": { "type": ["integer", "null"] }
      }
    },
    "HrTraffic": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "bytesReceived": { "type": ["integer", "null"] },
        "bytesSent": { "type": ["integer", "null"] },
        "packetsReceived": { "type": ["integer", "null"] },
        "packetsSent": { "type": ["integer", "null"] },
        "errorsReceived": { "type": ["integer", "null"] },
        "errorsSent": { "type": ["integer", "null"] }
      }
    },
    "HrBackhaul": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "type": { "type": ["string", "null"], "description": "Wi-Fi / Ethernet / null" },
        "status": { "type": ["string", "null"], "description": "Connected / Disconnected" },
        "linkRateMbps": { "type": ["integer", "null"] },
        "snr": { "type": ["integer", "null"] },
        "signal": { "type": ["integer", "null"] },
        "utilization": { "type": ["integer", "null"] }
      }
    },
    "HrQoE": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "cpuPercent": { "type": ["integer", "null"] },
        "memoryFree": { "type": ["integer", "null"] },
        "memoryTotal": { "type": ["integer", "null"] },
        "wanBandwidth": { "type": ["integer", "null"] },
        "wanConnectivity": { "type": ["integer", "null"] },
        "wanThroughput": { "type": ["integer", "null"] },
        "latencyMs": { "type": ["integer", "null"] },
        "jitterMs": { "type": ["integer", "null"] },
        "factor": { "$ref": "#/$defs/HrQoeFactor" }
      }
    },
    "HrQoeFactor": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "availableBandwidthScore": { "type": ["number", "null"] },
        "connectivityScore": { "type": ["number", "null"] },
        "internetDelayScore": { "type": ["number", "null"] },
        "internetJitterScore": { "type": ["number", "null"] },
        "isController": { "type": ["boolean", "null"] },
        "numberOfAlerts": { "type": ["integer", "null"] },
        "systemHealthScore": { "type": ["number", "null"] },
        "wifiAvailability2GScore": { "type": ["number", "null"] },
        "wifiAvailability5GScore": { "type": ["number", "null"] },
        "wifiCoverage2GScore": { "type": ["number", "null"] },
        "wifiCoverage5GScore": { "type": ["number", "null"] }
      }
    }
  }
}

---

Tenant routing rules

• For NATS, the tenant is selected by the subject: hniq.tenant.tr.{tenantId}
• For HTTPS, tenant selection is presumed to be derived from the JWT (claims), unless your gateway uses another mechanism.