Common Questions

Which API version should I use?
Use the Verdigris API v3 for topology, gateways and Signals, and Data API v4 for measurements. Verdigris guidance is to avoid legacy v1 and v2.

Do I need to write code to explore the data?
Both APIs are HTTP services. Data can be returned as JSON or CSV, which many tools can load directly. Someone technical will need to make the calls.

How do I authenticate?
Both APIs use OAuth 2.0 client credentials with the token endpoint https://auth.verdigris.co/oauth/token. See the Quickstart and How to Create or Manage API Keys.

Which buildings can my client see?
The buildings your credentials are authorized for. A single token can span buildings from more than one account.

Where are the APIs hosted?
REST API v3 is at https://api.verdigris.co/v3 and the Data API is at https://api.verdigris.co/data/v4. Only production is available to partners.

What is the lowest time resolution?
One minute for energy, power, current, voltage, power factor, THD and control. Weather is hourly or daily. Waveforms provide raw signal shapes.

Can I get data for many buildings at once?
Yes. Most measurement types have a batch endpoint that takes a comma-separated list of IDs.

Which level should I pull, circuit or panel?
It depends on the question. Building or panel data suits overall performance, and circuit or breaker data isolates specific equipment. Current and voltage are circuit-level only; THD is panel-level only; weather, control and forecast are building-level.

How do I know a gap in data is a meter problem rather than an idle building?
Check the gateway health fields in v3 (connection state, last data timestamp, 24-hour uptime, data latency) and the panel's metering status (active, suspended, and so on).

Can I get outdoor weather?
Yes: temperature, humidity and dew point per building, hourly or daily. Forecasts are limited to 10 days ahead.

Do I need to match IDs between v3 and v4?
Yes, but the mapping is simple: the Data API v4 takes the integer oldid that v3 returns next to each entity's text nanoid, for the same kind of entity (building, panel, breaker or circuit). Keep nanoid as your own primary key and oldid as the telemetry join key.

How fresh is the data? How long is history kept?
Data latency and history retention are not covered by this documentation. To see how current a site's data is, check a data gateway's lastDataTimestamp and dataLatencyMinutes in API v3. For retention terms, contact [email protected].