# Carnot Heat Engine API
> Heat-engine efficiency and coefficient of performance as an API, computed locally and deterministically. The efficiency endpoint gives the Carnot maximum efficiency of any heat engine working between two temperatures, η = 1 − Tc/Th (in kelvin) — the absolute upper limit no real engine can beat — and, given a heat input, the maximum work it could produce and the heat it must reject. The heat-pump endpoint gives the Carnot coefficient of performance of a heat pump, COP = Th/(Th − Tc), and of a refrigerator or air conditioner, COP = Tc/(Th − Tc), and the heat moved for a given work input. The engine endpoint analyses a real engine from its heat balance: from any two of the heat input, the work output, the efficiency or the heat rejected it returns the rest using η = W/Qh and Qc = Qh − W, and — given the reservoir temperatures — compares it to the Carnot limit and reports the second-law (exergy) efficiency. Temperatures accept kelvin, Celsius or Fahrenheit. Everything is computed locally and deterministically, so it is instant and private. Ideal for thermodynamics-education tools, engine, turbine and HVAC design, refrigeration and heat-pump apps, and energy-systems software. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is heat-engine and refrigeration-cycle efficiency; for sensible heat use a specific-heat API and for heat-exchanger LMTD use a heat-exchanger API.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/carnot-api/..."
```

## Pricing
- **Free** (Free) — 3,000 calls/Mo, 2 req/s
- **Starter** ($5/Mo) — 40,000 calls/Mo, 5 req/s
- **Pro** ($15/Mo) — 250,000 calls/Mo, 15 req/s
- **Mega** ($49/Mo) — 1,510,000 calls/Mo, 40 req/s

## Endpoints

### Carnot

#### `GET /v1/efficiency` — Carnot maximum efficiency

**Parameters:**
- `hot_temperature` (query, required, string) — Hot reservoir temperature Example: `600`
- `cold_temperature` (query, required, string) — Cold reservoir temperature Example: `300`
- `unit` (query, optional, string) — k|c|f (default k) Example: `k`
- `heat_input` (query, optional, string) — Heat input Qh (J) for max work

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/carnot-api/v1/efficiency?hot_temperature=600&cold_temperature=300&unit=k"
```

**Response:**
```json
{
    "data": {
        "formula": "η = 1 − Tc/Th (temperatures in kelvin).",
        "carnot_efficiency": 0.5,
        "hot_temperature_k": 600,
        "cold_temperature_k": 300,
        "carnot_efficiency_percent": 50
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:42.758Z",
        "request_id": "1cda0185-301f-467a-921d-2e25dc2b4b64"
    },
    "status": "ok",
    "message": "Carnot efficiency",
    "success": true
}
```

#### `GET /v1/engine` — Real engine efficiency & heat balance

**Parameters:**
- `heat_input` (query, optional, string) — Heat input Qh (J) Example: `1000`
- `work_output` (query, optional, string) — Work output W (J) Example: `400`
- `efficiency` (query, optional, string) — Or efficiency (0–1)
- `heat_rejected` (query, optional, string) — Or heat rejected Qc (J)
- `hot_temperature` (query, optional, string) — Hot temp for Carnot comparison
- `cold_temperature` (query, optional, string) — Cold temp for Carnot comparison

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/carnot-api/v1/engine?heat_input=1000&work_output=400"
```

**Response:**
```json
{
    "data": {
        "formula": "η = W/Qh; Qc = Qh − W.",
        "efficiency": 0.4,
        "heat_input_j": 1000,
        "work_output_j": 400,
        "heat_rejected_j": 600,
        "efficiency_percent": 40
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:42.862Z",
        "request_id": "d96ad265-0944-4616-92ce-3c6b5d64a896"
    },
    "status": "ok",
    "message": "Real engine efficiency",
    "success": true
}
```

#### `GET /v1/heat-pump` — Heat-pump / refrigerator COP

**Parameters:**
- `hot_temperature` (query, required, string) — Hot reservoir temperature Example: `295`
- `cold_temperature` (query, required, string) — Cold reservoir temperature Example: `275`
- `unit` (query, optional, string) — k|c|f (default k) Example: `k`
- `work_input` (query, optional, string) — Work input (J) for heat moved

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/carnot-api/v1/heat-pump?hot_temperature=295&cold_temperature=275&unit=k"
```

**Response:**
```json
{
    "data": {
        "formula": "COP_heating = Th/(Th−Tc); COP_cooling = Tc/(Th−Tc).",
        "cop_heating": 14.75,
        "hot_temperature_k": 295,
        "cold_temperature_k": 275,
        "cop_cooling_refrigeration": 13.75
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:42.942Z",
        "request_id": "0c7ce69b-f65f-4830-b85c-ced67c83d8e5"
    },
    "status": "ok",
    "message": "Heat-pump / refrigerator COP",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/carnot-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "api": "carnot",
        "note": "Carnot heat-engine efficiency & COP — computed locally and deterministically, no key, no third-party service.",
        "endpoints": [
            "/v1/efficiency",
            "/v1/heat-pump",
            "/v1/engine",
            "/v1/meta"
        ]
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:43.046Z",
        "request_id": "6fc64000-e995-4fd9-8989-88b9ff08e9e8"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/carnot-api
OpenAPI spec: https://www.oanor.com/api/carnot-api/openapi.json