Quickstart

This page takes you from credentials to your first successful call against both Verdigris APIs.

1. Get an access token

You need a client ID and secret first. Create an API client as described in How to Create or Manage API Keys.

Both APIs use OAuth 2.0 with the client credentials grant. To try requests from the API Reference pages, you don't need to do this: click Log In at the top right of the docs and sign in with your Verdigris account, and Try It fills in your access token automatically (see Authentication). Use the steps below when you are calling the API from your own code. Exchange your client ID and secret for a bearer token.

curl -s -X POST https://auth.verdigris.co/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "'"$VERDIGRIS_CLIENT_ID"'",
    "client_secret": "'"$VERDIGRIS_CLIENT_SECRET"'",
    "audience": "https://api.verdigris.co/"
  }'

The response contains an access_token, plus expires_in (seconds until the token expires) and token_type (Bearer). Export the token and send it as a bearer token on every request:

export TOKEN="<access_token from the response>"

Keep the client secret on your server. Never ship it in browser or mobile code. Cache the token until it expires (the token endpoint allows 20 requests per hour, so do not fetch a new token on every run) instead of requesting a new one for every call, because every API call is also subject to rate limits.

2. First call to the REST API v3

List the first building you can access. per-page accepts 1 to 1000 (default 10) and page starts at 1.

curl -s 'https://api.verdigris.co/v3/buildings?page=1&per-page=1' \
  -H "Authorization: Bearer $TOKEN"

The response is a page of results:

{
  "currentPage": 1,
  "pages": 12,
  "total": 12,
  "buildings": [
    {
      "nanoid": "building_...",
      "oldid": 42,
      "name": "Example HQ",
      "slug": "example-hq",
      "timezone": "America/Los_Angeles",
      "panels": [{ "nanoid": "panel_...", "oldid": 7, "name": "Main switchboard" }]
    }
  ]
}

Values above are illustrative. Note the two identifiers on every entity: nanoid (used by v3 paths) and oldid (an integer, used by Data API v4). See Rebuild your building topology.

Fetch one building, by NanoID or slug, including its top-level panels:

curl -s 'https://api.verdigris.co/v3/buildings/example-hq' \
  -H "Authorization: Bearer $TOKEN"

3. First call to the Data API v4

Data API v4 identifies entities by integer ID (the oldid returned by v3). This request returns hourly average power in watts for two panels:

curl -s -G 'https://api.verdigris.co/data/v4/power/panels' \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode 'ids=101,102' \
  --data-urlencode 'interval=1h' \
  --data-urlencode 'start_time=2025-01-01T00:00:00Z' \
  --data-urlencode 'end_time=2025-01-02T00:00:00Z' \
  --data-urlencode 'timestamp_format=ISO8601'

The response is a JSON array with one row per entity and interval:

[
  { "id": 101, "timestamp": "2025-01-01T00:00:00Z", "power": 18273.97 }
]

Values are illustrative. Add the header Accept: text/csv to receive CSV instead of JSON. See Retrieve telemetry for every parameter.

Common first-call problems