Waste-heat recovery API

What this API supports

This pilot screens direct, counter-current, single-phase sensible heat recovery. It constrains delivered heat by source outlet floor, both exchanger terminal approaches, and coincident sink demand. Caller-provided heat capacities remain constant. It calculates conditional annual energy, physical-exergy changes, fuel displacement, simple payback, and optional emissions and sensitivity cases.

It does not size equipment, model heat pumps or condensation, establish field performance, or approve procurement. Results name their inputs, equations, limitations and next measurements. No customer input is sent to an AI provider by this API.

Set up your integration

1. 1

   Create and verify your account

   Sign up and verify your email, then sign in. The pilot is available to active verified accounts.

2. 2

   Create an API key

   Open Account Settings → API keys (/settings/api). Save the new key when it is displayed; only its digest is stored. Keys expire after 90 days. Rotate by creating a replacement and revoking the old key.

3. 3

   Store the key on your server

   Send Authorization: Bearer <key>. Browser cookies cannot authorize this API, and these keys cannot authorize general Workspace or Computer Use routes.

const basis = await fetch("https://exergy-lab.com/examples/heat-recovery.json").then(r => r.json());
const response = await fetch("https://exergy-lab.com/api/v1/waste-heat/assessments", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.EXERGY_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID()
  },
  body: JSON.stringify(basis)
});
const result = await response.json();
if (!response.ok) throw new Error(result.error.message);
console.log(result.id, result.status, result.thermal, result.brief_markdown);

Inputs and data quality

• Download the example at /examples/heat-recovery.json and the OpenAPI 3.1 contract at /api/v1/openapi.json. Temperatures are Celsius, approach is kelvin difference, mass flow is kg/s, cp is kJ/(kg·K), pump power is kW, prices/capex are USD, and operating hours represent one year (at most 8760). Unknown properties and numeric strings are rejected.
• Missing operating boundaries return status needs_data with no fabricated calculation. Missing financial inputs suppress payback. A new, valid needs_data response counts as one screen; invalid requests do not.
• For time bins, send operating_periods in JSON or multipart/form-data with file (CSV) and basis (JSON text without operating_periods). CSV columns must be hours,source_inlet_c,source_mass_flow_kg_s,sink_return_c,sink_mass_flow_kg_s. At most 1000 rows; the whole request must be at most 256000 bytes. Rows are integrated before averaging, and their hours must match operating_hours when supplied.
• These are supplied annual operating bins, not arbitrary raw timestamp logs. Missing units, extrapolation, duplicate timestamps and operating schedules need reconciliation before submission; the API does not silently infer them.

Endpoints and retries

• This bounded deterministic calculation completes synchronously; there is no analysis job to poll. HTTP 200 does not mean site feasibility is established. Inspect status, missing_inputs, limitations and the calculation provenance.
• Retry network errors and 503 with the same Idempotency-Key and original payload. Successful replay reports Idempotency-Replayed: true and uses no additional screen. A changed payload with the same key returns 409.
• 401 means invalid/expired/revoked key; 403 means the account is unavailable; 400/413/415 mean invalid input/oversized body/unsupported content type; 429 supplies Retry-After. Quotas are enforced per account across all its keys.
• DELETE /api/v1/waste-heat/assessments/{id} immediately erases that result and normalized inputs. It keeps a content-free retry tombstone for the retrieval window and does not refund the screen. Replay of a deleted result returns 410.

Plan allowances, limits and retention

Waste-heat API access is included with existing account plans: Free includes 25 new assessments per UTC calendar month; Plus ($19/month) includes 250; Pro ($99/month) includes 1,000. There is no separate API subscription or automatic overage billing. These allowances are separate from daily Live tokens and Workspace analyses. Existing paid-checkout availability is unchanged; see /pricing.

Usage is shared across all keys and retained when plans change. The current database account tier controls the next request, including existing keys. An upgrade raises the limit without resetting usage. A downgrade blocks new work when the consumed count reaches the lower allowance; existing results, deletion and identical retries remain available. Scheduled cancellation keeps paid access until the existing billing system ends it. Allowances reset at 00:00 UTC on the first of each month and do not roll over.

All plans allow 10 successful authenticated API requests per minute and up to three active keys. IP-based abuse protection additionally limits bursts. Plan changes do not increase burst limits. See /settings/api for your current allowance and usage, and /settings/billing to manage your account plan.

Results are retrievable/replayable for 30 days. Older records are purged on the account’s next assessment request; this is not a scheduled physical-deletion guarantee. Delete a result through its DELETE endpoint at any time. Account deletion erases API keys, input/result records and API usage.

Synthetic benchmarks and cost assumptions are documented in the release assessment. Included allowances are implemented; customer value and unit economics still require real-workflow validation. General workspace endpoints remain private beta.