API user guide

Premiers pas

1. Connectez-vous et ouvrez vos paramètres de l’espace de travail.
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.

Authentification

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.

Envoyer une requête

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

curl -X POST "http://staging.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. Ouvrir le schéma.

Submit orchestration telemetry

Créez des relevés à l’adresse http://staging.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

La plupart des ressources permettent GET et POST sur la collection, ainsi que GET, PUT, PATCH et DELETE sur un enregistrement. Les transmissions de rénovation ne peuvent pas être modifiées directement après leur création ; utilisez la route de transition auditée pour changer leur statut. Les collections sont paginées avec limit/offset (limite par défaut 50, maximum 100).

The API index also lists machine-readable endpoint URLs.

Responses and usage

• 200 request succeeded; 201 dossier créé ; 204 dossier supprimé.
• 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 paramètres de l’espace de travail.