Understanding Verdigris API

Verdigris monitors electrical systems in buildings. Two APIs work together to give you that data. Both are read-only: you can retrieve data but not create, change, or delete anything through them.

API	What it is	What it gives you
Verdigris API (v3)	The "what exists and what is happening to it" API	The structure of a site (buildings, panels, breakers, circuits), the metering devices (data gateways) attached to it, and Signals: detections and notifications raised by Verdigris.
Data API (v4)	The "how much, and when" API	Time series measurements: energy, power, current, voltage, power factor, harmonic distortion, plus building controls, weather, and an energy forecast.

📘
Which versions to use
Use v3 for structure and Data API v4 for measurements. Verdigris guidance is to avoid the older v1 and v2 APIs.

The equipment hierarchy

Verdigris organizes electrical equipment the same way a building's electrical system is physically organized:

Account
 └─ Building
     └─ Panel          (panels can feed other panels)
         └─ Breaker
             └─ Circuit  (a measured phase on a breaker)

Account (organization): the customer that owns the buildings.
Building: a site, with a name, address, time zone, and optional details such as floor area and industry.
Panel: an electrical panel in a building. A panel can have sub-panels downstream of it, and the breaker that feeds it upstream.
Breaker: a breaker inside a panel. A breaker can be marked as a mains breaker.
Circuit: a breaker carries one or more circuits, each on a phase (A, B, or C). Circuits are the finest-grained thing that is measured.
Data gateway: the Verdigris metering device attached to a panel. It is identified by a serial number, and the sensors on it are linked to specific circuits.

Which API answers my question?

Your question	API	Where to look
Which buildings do I have access to?	v3	Buildings
What panels, sub-panels, breakers and circuits are in a building?	v3	Buildings, Panels, Breakers
Which gateway is on which panel, and is it online?	v3	Data gateways, Summary
Is a panel currently being metered (active, planned, suspended, and so on)?	v3	Panel metering status events
How much energy did a building, panel, breaker or circuit use?	v4	Energy
What was the power draw over time?	v4	Power
What were current, voltage, or power quality (power factor, harmonic distortion)?	v4	Current, Voltage, Power Factor, THD
What is the outdoor temperature, humidity or dew point at a building?	v4	Weather
What did the building control system report?	v4	Control
What energy use is expected in the coming period?	v4	Forecast
Has something anomalous been detected on my equipment?	v3	Signals notifications
Which metrics do Signals use, and what detections exist for my equipment?	v3	Site metrics, Signals specifications

How the two APIs connect

You discover the equipment through v3, then use the identifiers from that discovery to ask v4 for measurements. Both APIs apply the same access rules, so you only see equipment your credentials are authorized for.

📘
Identifier note
v3 objects carry both a text nanoid and an integer oldid. v4 endpoints take integer IDs. The integer oldid of an entity in v3 is the ID that v4 expects for the same kind of entity (building, panel, breaker or circuit). Use nanoid as your own primary key and keep oldid as the join key to telemetry.

Glossary

Term	Meaning
`nanoid`	The stable text identifier of a building, panel, breaker or circuit in API v3, prefixed by its type (for example `building_...`). Use it as your own primary key.
`oldid`	The integer identifier of the same entity. The Data API v4 takes these integers.
Building, panel, breaker, circuit	The equipment hierarchy: a building contains panels, a panel contains breakers, and a breaker carries one or more circuits (the measured conductors).
`downstreamPanels`	Panels fed from a breaker in this panel. Following it gives you the panel-to-panel feed tree.
`upstreamBreaker`	The breaker that feeds a panel.
`mains`	A panel's supply configuration: its supply voltage and phases.
Data gateway	The Verdigris metering device attached to a panel.
Signals	Detection rules Verdigris runs on your measurements, and the notifications they raise.

Which versions to use

The equipment hierarchy

Which API answers my question?

How the two APIs connect

Identifier note

Glossary

Next