Application API

The GridSense Application API gives external applications read-only access to installation metadata and the last-known state of inverters, batteries, energy meters, EV chargers, relays and boilers, plus the current aggregated energy flow.

Base URL: https://api.gridsense.nl/application/v1.

Try the API

1. Open List installations.
2. In the playground's Authorization section, select ApiKey and paste your full gsak_… application API key. Do not add a Bearer prefix.
3. Send the request. The playground shows the actual HTTP status and JSON response from the API. The response examples elsewhere on the page are fictional.
4. Copy an id from the returned installations array and open List installation devices.
5. Replace the example installationId with that ID and send the request to see the installation's latest reported device state.
6. Open Get current installation energy flow with the same installationId for an overview of online devices. gridPower is positive for import and negative for export; data can be null.

The playground remembers the key in this browser's local storage across endpoint pages and reloads. Use Clear API key and response when finished to remove saved credentials and the current result. Requests pass through the GridSense docs server because the application API does not allow cross-origin browser requests. The docs proxy forwards your supplied authentication to the API and does not cache responses.

Authentication and access

Use either Api-Key: YOUR_API_KEY or Authorization: Bearer YOUR_API_KEY. The playground also supports BearerAuth: paste the same full key without the prefix; it adds Bearer automatically. Send one authentication header at a time. If both are supplied, a Bearer authorization header takes precedence.

An application needs an explicit grant for an installation, and its owner must still have access to that installation. A user-owned application can access installations granted through the owner's direct installation membership; company membership alone does not qualify. A company-owned application can access granted installations belonging to that company. Access is checked on each request.

Missing, malformed, unknown, revoked or expired keys and disabled applications all receive the same 401 UNAUTHORIZED. Keys are shown only once at creation. Rotate a key by creating a replacement, updating your integration and then revoking the old key.

Call from your integration

Keep the key in your server's environment or secret store. For example, after setting GRIDSENSE_API_KEY:

curl --fail-with-body \
  -H "Api-Key: $GRIDSENSE_API_KEY" \
  'https://api.gridsense.nl/application/v1/getInstallations'

# Replace 42 with an installation ID returned by getInstallations.
curl --fail-with-body \
  -H "Authorization: Bearer $GRIDSENSE_API_KEY" \
  'https://api.gridsense.nl/application/v1/getInstallationDevices?installationId=42'

curl --fail-with-body \
  -H "Api-Key: $GRIDSENSE_API_KEY" \
  'https://api.gridsense.nl/application/v1/getInstallationCurrentEnergyFlow?installationId=42'

The reference documents GET requests with query parameters. The API also accepts parameters in a POST form body, with POST values taking precedence over query values. All three endpoints only read data.

Responses and errors

Successful responses have valid: true. Failures have valid: false and a machine-readable error. Check the HTTP status as well as the JSON body.

The docs playground can additionally return 502 or 504 if the API cannot be reached, times out, redirects or returns a non-JSON response. These are docs proxy errors, not application API error codes.

Device arrays can be empty. Nullable measurements mean unknown, unavailable or unsupported, not zero. Offline devices are included, so inspect lastSeenDate before treating a value as current. Different devices may have different update times. See Power direction and response fields before calculating energy flows.

OpenAPI specification

Download the OpenAPI 3.1 specification for use with your API client or code generator. The endpoint reference includes a description, type and nullability for every returned field under Responses.

The application API does not expose users, company objects, invoices, subscriptions, gateway objects, MQTT credentials, raw vendor data, control schedules or vehicles. Fields such as device mode and relay desired state are read-only observations; application management and device control use separate APIs and are outside this reference.