Skip to main content

Making Your First API request

This tutorial will walk you through making your first API request. In the process also you'll learn about authentication and the difference between our production and sandbox envrionments. This tutorial does not cover OpenADR. For that topic, see OpenADR at Voltus.

The base url of the public api is https://api.voltus.co/2022-04-15. We currently use dates for versioning. Breaking changes to existing endpoints will result in a new date path prefix. IE, if a breaking change to an existing endpoint was released on the 20th of September 2025, the new base url would be https://api.voltus.co/2025-09-20.

All endpoints require authentication in the form of a secret key placed in a 'X-Voltus-API-Key' header. If you're already under contract with Voltus, you can reach out to your customer representative and they will send you a secure one-time link containing a key. If you lose it or it gets compromised, don't hesitate to reach out to receive a new one.

If you aren’t yet a customer or partner, but would still like to follow this tutorial, you can make requests using test credentials. It returns fake static data for all GET endpoints and is intended to "kick the tires" before ​​you receive a real API key. Test credentials can be used to ensure your code is making well-formed requests and parsing responses correctly.

This tutorial assumes you have curl installed.

Making the Request​

Below you’ll find curl requests that will hit the GET /sites endpoint with production and test credentials which return a list of the sites you own.

Curl command with test environment​

curl --header "X-Voltus-API-Key: secret" https://sandbox.voltus.co/2022-04-15/sites

You can use 'secret' as the api key for all requests.

Curl command with production environment​

curl --header "X-Voltus-API-Key: [YOUR API KEY HERE]" https://api.voltus.co/2022-04-15/sites

Depending on where you are in the onboarding process this may return an empty list of sites.

Understanding the Response​

The response should look something like this.

{
  "page": 0,
  "perPage": 0,
  "sites": [
    {
      "customer_location_id": "f4",
      "id": "asdf",
      "meters": [
        {
          "id": "asdf",
          "name": "Generator"
        },
        {
          "id": "asdf",
          "name": "Generator"
        }
      ],
      "name": "2 Park Ave"
    },
    {
      "customer_location_id": "f4",
      "id": "asdf",
      "meters": [
        {
          "id": "asdf",
          "name": "Generator"
        },
        {
          "id": "asdf",
          "name": "Generator"
        }
      ],
      "name": "2 Park Ave"
    }
  ]
}

You may notice that page, and perPage are both 0. This is because pagination is currently not implemented for the sites endpoint and can be safely ignored. All of your sites will be returned in a single call.

The GET /sites response contains an array of sites that you own with the following properties:

  • customer_location_id corresponds to the ID you provided us for the site during the onboarding process.
  • id is the voltus-generated unique identifier for the site.
  • name is a descriptive name, also provided by you during the onboarding process.
  • meters is a list of meters that are attached to the site. A meter is the datastream that sends energy data to Voltus. It's usually an energy meter managed by your utility that measures your energy usage. However, it may also refer to other things depending on the specifics of your sites and the programs they are enrolled in.

Making other Requests​

You can refer to our API reference for details about other endpoints and code samples in many programming languages. Remember: all requests expect the X-Voltus-API-Key header that contains a valid API key.