HOP Sensors API Reference

Overview

Authentication

Every request must include your API key in the X-API-Key header. Your key is provisioned when your account is created. It is scoped to your utility — you can only read and write data for your own substations.

# Required on every request
X-API-Key: your-api-key-here

# Example curl
curl -H "X-API-Key: your-api-key-here" \
     https://ingest.hopsensorsllc.com/query/substations

Base URL

All API endpoints share a single base URL:

https://ingest.hopsensorsllc.com

Full example for the telemetry ingest endpoint:

POST https://ingest.hopsensorsllc.com/ingest/telemetry

Errors

POST /ingest/telemetry Ingest

Write a real-time telemetry reading for one substation. Send one record per substation per polling cycle. The platform supports any rate up to once per second per substation. This endpoint drives the live telemetry panel, time-series charts, frequency monitor, and ML anomaly scoring.

Request Body

Example Request

// POST /ingest/telemetry
// X-API-Key: your-api-key-here

{
  "substation_id":  "SUB001",
  "region_id":      "PGE-REGION-01",
  "feeder_id":      "FDR002",
  "equipment_id":   "SUB001-RTU-01",
  "equipment_type": "substation",
  "site_name":      "Portland North",
  "voltage_kv":     229.8,
  "current_a":      1187.4,
  "power_mw":       274.2,
  "frequency_hz":   60.002,
  "status_code":    "NORMAL",
  "timestamp":      "2026-06-11T14:32:00Z"
}

{ "status": "ok", "utility": "pge", "substation_id": "SUB001" }

POST /ingest/transformer Ingest

Write transformer health telemetry — oil temperature, tap position, and load percentage. Appears on the Telemetry tab transformer panel. Send one record per transformer per polling cycle.

Request Body

Example Request

{
  "substation_id": "SUB001",
  "region_id":     "PGE-REGION-01",
  "equipment_id":  "XFMR-001",
  "oil_temp_c":    68.4,
  "tap_position":  3,
  "load_percent":  74.2,
  "voltage_kv":    229.8,
  "current_a":     312.7,
  "status_code":   "NORMAL",
  "timestamp":     "2026-06-11T14:32:00Z"
}

{ "status": "ok", "utility": "pge", "equipment_id": "XFMR-001" }

POST /ingest/event Ingest

Write a discrete grid event — a state change, alarm, or operational transition at a device or feeder. Events populate the Alarms & Outages tab. FEEDER_TRIP events with severity ALARM trigger email alerts to configured operators.

Request Body

Event Types

Example — Feeder Trip

{
  "device_id":  "SUB001-FDR002",
  "feeder_id":  "FDR002",
  "severity":   "ALARM",
  "event_type": "FEEDER_TRIP",
  "old_state":  "CLOSED",
  "new_state":  "OPEN",
  "message":    "Overcurrent protection operated — FDR002",
  "latitude":   45.5231,
  "longitude":  -122.6765,
  "timestamp":  "2026-06-11T14:35:00Z"
}

{ "status": "ok", "utility": "pge" }

POST /ingest/outage Ingest

Write or update an outage record with customer impact data. Send an ACTIVE record when an outage begins and a RESTORED record when it is cleared. Outages appear on the Alarms & Outages tab, Executive View, and the outage map.

Request Body

Example — Active Outage

{
  "outage_id":      "OUT-SUB001-FDR002-1749650000",
  "feeder_id":      "FDR002",
  "substation_id":  "SUB001",
  "region_id":      "PGE-REGION-01",
  "customers_out":  847,
  "mw_interrupted": 12.4,
  "status":         "ACTIVE",
  "cause":          "STORM",
  "etr_time":       "2026-06-11T16:00:00Z",
  "timestamp":      "2026-06-11T14:35:00Z"
}

Example — Restore

{
  "outage_id":     "OUT-SUB001-FDR002-1749650000",
  "feeder_id":     "FDR002",
  "customers_out": 0,
  "status":        "RESTORED",
  "timestamp":     "2026-06-11T15:48:00Z"
}

{ "status": "ok", "utility": "pge", "outage_id": "OUT-SUB001-FDR002-1749650000" }

GET /query/telemetry/latest Query

Returns the most recent telemetry reading per substation. Drives the live telemetry panel on the dashboard. Data is served from Redis — sub-second response time.

[
  {
    "substation_id": "SUB001",
    "frequency_hz":  60.002,
    "voltage_kv":    229.8,
    "current_a":     1187.4,
    "power_mw":      274.2,
    "time":          "2026-06-11 14:32:00+00:00"
  }
]

GET /query/telemetry/timeseries Query

Returns voltage, power, and frequency time series for a single substation. Drives the time-series charts on the Telemetry tab. Data is sliced from Redis sorted sets with sub-second latency.

Query Parameters

GET /query/telemetry/timeseries?substation_id=SUB001&minutes=60

GET /query/telemetry/history Query

Returns full telemetry history for a single substation, backed by a 7-day rolling window in Redis.

Query Parameters

GET /query/telemetry/history?substation_id=SUB001&hours=48

GET /query/transformer/latest Query

Returns the most recent transformer reading per transformer equipment ID. Includes oil temperature, tap position, and load percentage.

GET /query/transformer/latest

GET /query/ml/latest Query

Returns the most recent ML anomaly score per substation. Drives the score cards on the ML Anomaly tab. Scores are produced every 60 seconds by the ML service using a z-score model on frequency_hz.

[
  {
    "substation_id":  "SUB001",
    "anomaly_score":  0.234,  // 0.0–1.0. >= 0.7 = anomaly
    "is_anomaly":     false,
    "baseline_mean":  60.001,
    "baseline_std":   0.0082,
    "z_score":        0.585,
    "latest_value":   60.002,  // frequency_hz reading that was scored
    "time":           "2026-06-11 14:32:00+00:00"
  }
]

GET /query/ml/trend Query

Returns ML anomaly score history across all substations for trend visualization on the ML Anomaly tab.

Query Parameters

GET /query/ml/trend?minutes=60

GET /query/events Query

Returns recent grid events — feeder trips, restores, and all other logged SCADA events — ordered most-recent first.

Query Parameters

GET /query/events?minutes=60

GET /query/outages/active Query

Returns currently active outages — records with status = ACTIVE written within the last 2 hours, deduplicated by outage_id.

[
  {
    "outage_id":      "OUT-SUB001-FDR002-1749650000",
    "feeder_id":      "FDR002",
    "substation_id":  "SUB001",
    "customers_out":  847,
    "mw_interrupted": 12.4,
    "cause":          "STORM",
    "etr_time":       "2026-06-11T16:00:00Z",
    "time":           "2026-06-11 14:35:00+00:00"
  }
]

GET /query/frequency/thresholds Query

Returns frequency readings for all substations for the threshold plot on the Frequency Monitor tab. Threshold bands are applied client-side: warn 59.85–60.15 Hz, alarm outside 59.5–60.5 Hz.

Query Parameters

GET /query/frequency/thresholds?minutes=30

GET /query/substations Query

Returns all substations registered to your utility in the HOP Sensors platform. Useful for validating that your integration is sending data for the expected substations.

[
  { "substation_id": "SUB001" },
  { "substation_id": "SUB002" }
]

Thresholds

The following thresholds are applied by the HOP Sensors ML and alerting services. Provided here for reference when interpreting query responses.

Data Model

All data is written to InfluxDB 3 Core across four measurements and synced to Redis by the cache service. Understanding the schema helps when interpreting query responses.

scada_telemetry

Primary time-series measurement. Stores raw substation telemetry.

scada_transformers

Transformer health readings — oil temperature, tap position, load percentage.

scada_ml_scores

ML anomaly scores written every 60 seconds by the ML service.

scada_events

Discrete event log. Every feeder trip, restore, and state transition.

outages

Outage lifecycle records. Each outage has an ACTIVE record and a RESTORED record identified by the same outage_id.

GET /health

Returns API and Redis health status. No authentication required. Use for uptime monitoring and integration validation.

GET https://ingest.hopsensorsllc.com/health

{
  "status":      "ok",
  "version":     "v6",
  "redis":       true,
  "redis_keys":  1842,
  "timestamp":   "2026-06-11T14:32:00.000000+00:00"
}