GridLyt API documentation

Overview

The GridLyt API gives you programmatic access to every asset, anomaly, and revenue metric in your fleet. All requests are authenticated with a Bearer token and return JSON. The API is versioned — breaking changes will always ship under a new version prefix.

curl https://api.gridlyt.io/v1/assets \
  -H "Authorization: Bearer gl_live_xxxxxxxxxxxx"

Authentication

All API requests require a Bearer token in the Authorization header. Generate tokens in your GridLyt dashboard under Settings → API Keys. Tokens are scoped per integration and can be revoked at any time.

Authorization: Bearer gl_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Assets

Retrieve fleet asset data including State of Health, State of Charge, operating status, and revenue at risk.

Anomalies

Access active and historical anomalies with AI-generated explanations and revenue impact calculations.

Webhooks

Subscribe to real-time events. GridLyt sends a signed HTTP POST to your endpoint within milliseconds of an event. Payloads are signed with HMAC-SHA256 — verify the X-GridLyt-Signature header before processing.

Event types

Payload example

// POST https://your-system.com/hooks/gridlyt
// Headers:
//   X-GridLyt-Signature: sha256=<hmac>
//   X-GridLyt-Event: anomaly.detected

{
  "event": "anomaly.detected",
  "id": "anm-0x4A2F",
  "asset_id": "bess-04",
  "fault_code": "ERR_CELL_IMBALANCE_0x4A2F",
  "severity": "medium",
  "ai_explanation": "Cell group 3 showing 18mV imbalance...",
  "revenue_impact_daily": 2340,
  "timestamp": "2026-06-06T14:32:07Z"
}

import crypto from 'crypto';

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from('sha256=' + expected),
    Buffer.from(signature)
  );
}

// In your Express handler:
app.post('/hooks/gridlyt', (req, res) => {
  const sig = req.headers['x-gridlyt-signature'];
  const valid = verifyWebhook(JSON.stringify(req.body), sig, process.env.WEBHOOK_SECRET);
  if (!valid) return res.status(401).send('Invalid signature');
  res.sendStatus(200);
});

Errors & rate limits

Error format

All errors return a consistent JSON body with a machine-readablecode and a human-readable message.

{
  "error": {
    "code": "asset_not_found",
    "message": "No asset with id 'bess-99' exists in your fleet.",
    "status": 404
  }
}

HTTP status codes

Rate limits

Rate limits are applied per API token. Limits are returned in response headers on every request.

SDKs & libraries

Official SDKs are in active development. In the meantime, the API is straightforward to call directly from any HTTP client.

# Download the OpenAPI spec
curl https://api.gridlyt.io/v1/openapi.json -o gridlyt-openapi.json

# Generate a client with openapi-generator
npx @openapitools/openapi-generator-cli generate \
  -i gridlyt-openapi.json \
  -g typescript-fetch \
  -o ./gridlyt-client