API user guide

Get started

1. Sign in and open your workspace settings.
2. Create a named API key. Copy the secret when it is shown; it cannot be revealed again. Revoke and replace it if it is lost.
3. Keep the key in a secret manager or environment variable. Never publish it in browser code, source control, or support requests.

Authentication

Send the key on every API request using the Bearer authorization header:

Authorization: Bearer YOUR_TENERGEN_OS_API_KEY

Each key acts with the permissions of its owner. A key can access only records owned by that account and offerings permitted for its portal role.

Make a request

The API base URL is http://tenergen.com/api/v1/. For example, create an energy reading:

curl -X POST "http://tenergen.com/api/v1/ai-energy-manager/reading/" \
  -H "Authorization: Bearer $TENERGEN_OS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"building_name":"Clinic","measured_at":"2026-10-01T12:00:00Z","energy_kwh":"82.500","source":"Meter export"}'

Request and response fields follow each offering's workspace form. The OpenAPI schema describes field types and accepted values. Open the schema.

Submit orchestration telemetry

Create readings at http://tenergen.com/api/v1/building-energy-orchestration/telemetry/. Use an asset ID owned by the API key's account and an ISO 8601 timestamp with a timezone.

{
  "asset": 42,
  "measured_at": "2026-10-12T14:30:00Z",
  "energy_kwh": "12.345",
  "reading_type": "interval",
  "interval_minutes": 15,
  "source": "Main meter",
  "message_id": "meter-42-20261012T143000Z"
}

For interval energy, measured_at is the interval end and interval_minutes is required. For a cumulative meter register, set reading_type to cumulative and omit interval_minutes. Existing legacy readings may have an unspecified type.

A message_id is required for telemetry submissions. Keep it stable to make retries idempotent: an identical retry returns the existing record, while reuse with different data returns 409 Conflict.

The same endpoint accepts a JSON array of up to 500 readings. Batch validation and creation are atomic; an invalid row rejects the whole batch.

Resources and methods

Every resource supports collection GET and POST, plus detail GET, PUT, PATCH, and DELETE. Collection responses use limit/offset pagination (limit defaults to 50 and is capped at 100).

The API index also lists machine-readable endpoint URLs.

Responses and usage

• 200 request succeeded; 201 record created; 204 record deleted.
• 400 input validation failed; 401 key missing, invalid, or revoked; 403 your role cannot use that offering; 404 record does not exist or is not yours; 409 telemetry message ID conflicts with existing data.
• The dashboard counts authenticated API requests, including requests that return validation or permission errors. These are request counts, not billable units or energy usage.

Review your key activity and recent requests in workspace settings.