Documentation — Whittle Protocol API

01 Getting Started

Base URL

https://whittle-emissions-api.llpilot-api.workers.dev

All API endpoints are prefixed with /v1/. Responses use application/json.

Authentication

All /v1/* endpoints require an API key in the Authorization header:

Authorization: Bearer whtl_live_<your_key>

Key prefixes: whtl_live_* (production), whtl_free_* (free tier), whtl_test_* (sandbox).

Get a free key instantly at Sign In → Get API Key.

First Request

cURL

curl -X POST https://whittle-emissions-api.llpilot-api.workers.dev/v1/flight/emissions \
  -H "Authorization: Bearer whtl_free_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"engine_type":"CFM56-7B","altitude_m":10668,"mach":0.78}'

JavaScript

const resp = await fetch(
  'https://whittle-emissions-api.llpilot-api.workers.dev/v1/flight/emissions',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer whtl_free_YOUR_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      engine_type: 'CFM56-7B',
      altitude_m: 10668,
      mach: 0.78,
    }),
  }
);
const data = await resp.json();
console.log(data.emissions.co2_kg_h); // → 8216

Rate Limits

Tier	Daily	Monthly	Price
Free	100	3,000	$0
Startup	333	10,000	$49/mo
Business	3,333	100,000	$299/mo
Enterprise	Custom	Custom	Contact

02 Emission Estimation Methodology

The Whittle Protocol engine follows the methodology presented at ISABE 2024:

"Whittle Protocol: An Open Source Gas Turbine Performance Modelling Initiative"
ISABE 2024 — International Society for Air Breathing Engines, Toulouse, France

2.1 — ISA Atmosphere Model

Ambient conditions are derived from the ICAO Standard Atmosphere (Doc 7488/3):

Temperature (Troposphere, h ≤ 11 km): T(h) = 288.15 − 0.0065 × h

Temperature (Stratosphere, h > 11 km): T(h) = 216.65 K (constant)

Pressure (Troposphere): P(h) = 101325 × (T/288.15)^5.2561

Density: ρ(h) = P(h) / (R × T(h)) where R = 287.05 J/kg·K

Validated against ICAO tables to <0.01% up to 20 km (157 unit tests verified).

2.2 — Thermodynamic Cycle Model

A simplified two-spool turbofan cycle is solved at each operating point:

Inlet → Fan → HPC → Combustor → HPT → LPT → Core Nozzle
                 ↘ Bypass Nozzle

Station-by-Station Calculation:

Ram compression: T₀₂ = T₀ × (1 + (γ−1)/2 × M²), with inlet recovery η = 0.998
Fan: T₀₂₁ = T₀₂ × [1 + (FPR^(γ−1)/γ − 1) / η_fan]
HPC: T₀₃ = T₀₂₁ × [1 + (HPC_PR^(γ−1)/γ − 1) / η_HPC]
Combustor: f = (c_pH·T₀₄ − c_pC·T₀₃) / (η_comb·Q_r − c_pH·T₀₄), with 4.2% pressure drop
HPT: Extracts HPC work, accounting for cooling bleed fraction
LPT: Drives fan for core + bypass mass flow, with cooling correction
Nozzles: Choked/unchoked exit, critical NPR = ((γ+1)/2)^γ/(γ−1)

Key Thermodynamic Constants:

Parameter	Value	Unit
γ (cold)	1.4	—
γ (hot)	1.333	—
c_p (cold)	1005	J/kg·K
c_p (hot)	1148	J/kg·K
Q_r (Jet-A1 LHV)	43.1 × 10⁶	J/kg
Nozzle Cv	0.995	—

2.3 — Emissions Model

CO₂ — Stoichiometric

CO₂ (kg/h) = Fuel Flow (kg/h) × 3.16

The factor 3.16 is the mass ratio of CO₂ to carbon in Jet-A1 (C₁₂H₂₃ average composition × molecular weights). This is exact per IPCC/ICAO.

H₂O — Stoichiometric

H₂O (kg/h) = Fuel Flow (kg/h) × 1.24

NOx — BFFM2 Method

NOx Emission Index is computed using the Boeing Fuel Flow Method 2 (DuBois & Paynter, SAE 2006-01-1987):

Correct fuel flow to sea-level static: W_f,SLS = W_f / (δ_ram × θ_ram^3.8)
Interpolate ICAO LTO data: Log-log interpolation across 4 LTO modes (idle, approach, climb-out, take-off)
Humidity correction: EI × exp(−19.0 × (ω − 0.00634)), where ω = 0.008 × exp(−h/2500)

ICAO LTO data sourced from EASA TCDS and ICAO EEDB v29.

2.4 — Deterioration Model

Engine ageing increases SFC linearly with deterioration percentage:

FF_degraded = FF_baseline × (1 + deterioration_pct / 100)

Typical values: 1–2% for mature engines, 3–5% for severely degraded. This directly maps to excess CO₂ and carbon cost, enabling maintenance ROI calculations.

2.5 — Carbon Pricing Schemes

Scheme	Price (USD/tonne CO₂)	Source
EU ETS	$80	European Union Emissions Trading System
ICAO CORSIA	$40	Carbon Offsetting & Reduction Scheme for International Aviation
Gold Standard	$25	Gold Standard voluntary carbon credits
Verra (VCS)	$12	Verified Carbon Standard
Social Cost of Carbon	$185	US EPA social cost estimate

03 Endpoint Reference

POST /v1/flight/emissions

Compute emissions at a single flight operating point.

Request Body

Field	Type	Required	Description
`engine_type`	string	✓	Engine family ID (see catalogue)
`altitude_m`	number	✓	Altitude in metres (0–15000)
`mach`	number	✓	Flight Mach number (0.01–0.95)
`tet`	number		Turbine Entry Temp in K (800–2000). Default: engine design TET
`deterioration_pct`	number		SFC penalty % (0–20). Default: 0

Response

{
  "engine": "CFM56-7B",
  "aircraft": "Boeing 737NG",
  "conditions": { "altitude_m": 10668, "mach": 0.78, "tet_k": 1450, "deterioration_pct": 0 },
  "performance": { "thrust_kn": 73.04, "sfc_mg_ns": 35.63, "fuel_flow_kg_h": 2600, "opr": 25.0, "bpr": 5.1 },
  "emissions": { "co2_kg_h": 8216, "nox_ei_g_kg": 34.0, "nox_kg_h": 88.38, "h2o_kg_h": 3224 },
  "station_data": { "t4_k": 1450, "t5_k": 928.3, "p3_kpa": 593.2 },
  "validated": true,
  "_meta": { "engine": "Whittle Physics Engine v2.0", "tier": "free", "daily_usage": 1, "daily_limit": 100 }
}

POST /v1/mission/emissions

Gate-to-gate mission trajectory integration.

Request Body

Field	Type	Required	Description
`engine_type`	string	✓	Engine family ID
`trajectory`	array	✓	Array of segments: `{altitude_m, mach, duration_s}`
`num_engines`	number		Number of engines (default: 2)
`seats`	number		Seat count (default: 180)
`load_factor`	number		Passenger load factor (default: 0.82)
`distance_km`	number		Great-circle distance for CO₂/pax·km

Example: LHR → JFK Profile

{
  "engine_type": "CFM56-7B",
  "seats": 162,
  "distance_km": 5540,
  "trajectory": [
    { "altitude_m": 3000, "mach": 0.45, "duration_s": 600 },
    { "altitude_m": 7000, "mach": 0.65, "duration_s": 600 },
    { "altitude_m": 10668, "mach": 0.78, "duration_s": 21600 },
    { "altitude_m": 5000, "mach": 0.55, "duration_s": 900 },
    { "altitude_m": 1500, "mach": 0.35, "duration_s": 300 }
  ]
}

POST /v1/fleet/emissions

Annual fleet-level carbon cost with mixed engine types and deterioration.

Request Body

Field	Type	Required	Description
`aircraft`	array	✓	Array of `{engine_type, annual_fh, count?, deterioration_pct?}`
`scheme`	string		Carbon pricing scheme (default: `eu_ets`)
`custom_price`	number		Override price per tonne CO₂

POST /v1/carbon/cost

Compute carbon offset cost across 5 pricing schemes.

Request Body

Field	Type	Required	Description
`co2_kg`	number	✓	CO₂ amount in kg (0–10⁹)
`scheme`	string		Pricing scheme (default: `eu_ets`)
`seats`	number		For per-pax calculation (default: 180)
`load_factor`	number		Load factor (default: 0.82)

POST /v1/maintenance/roi

Quantify excess CO₂ from deferred maintenance and compute payback period.

Request Body

Field	Type	Required	Description
`engine_type`	string	✓	Engine family ID
`annual_fh`	number	✓	Annual flight hours
`sfc_penalty_pct`	number	✓	Current SFC deterioration %
`maintenance_cost_usd`	number	✓	Cost of engine restoration
`scheme`	string		Carbon pricing scheme

GET /v1/engines

List all supported engine families with design parameters and validation status.

No request body needed. Returns the full engine catalogue.

POST /keys/provision No Auth

Provision a free API key for an email address. If the email already has a key, the existing key is returned.

Request Body

Field	Type	Required	Description
`email`	string	✓	Your email address
`name`	string		Your name or org (default: email local part)

GET /keys/me

Get your key info, tier, and current usage stats. Requires Authorization: Bearer whtl_*.

Engine	Aircraft	BPR	FPR	OPR	TET (K)	Max Thrust (kN)	Baseline FF (kg/h)	Validated
CFM56-7B	Boeing 737NG	5.1	1.60	25.0	1450	121	2600	✓
CFM56-5B	Airbus A320ceo	5.5	1.55	27.0	1480	120	2700	—
LEAP-1A	Airbus A320neo	11.0	1.45	40.0	1580	130	2200	—
LEAP-1B	Boeing 737 MAX	9.0	1.48	41.0	1570	120	2300	—
V2500-A5	Airbus A320ceo	4.8	1.58	28.0	1500	140	2650	—

Code	Meaning	Common Causes
`400`	Bad Request	Missing required fields, invalid engine type, parameter out of range
`401`	Unauthorized	Missing or invalid API key, expired key
`405`	Method Not Allowed	Using GET on a POST endpoint (or vice versa)
`422`	Unprocessable	Engine solver did not converge at the given operating point
`429`	Rate Limited	Daily or monthly request quota exceeded
`500`	Server Error	Internal error — contact support

API Reference & Methodology

01 Getting Started

Base URL

Authentication

First Request

Rate Limits

02 Emission Estimation Methodology

2.1 — ISA Atmosphere Model

2.2 — Thermodynamic Cycle Model

Station-by-Station Calculation:

Key Thermodynamic Constants:

2.3 — Emissions Model

CO₂ — Stoichiometric

H₂O — Stoichiometric

NOx — BFFM2 Method

2.4 — Deterioration Model

2.5 — Carbon Pricing Schemes

03 Endpoint Reference

Request Body

Response

Request Body

Example: LHR → JFK Profile

Request Body

Request Body

Request Body

Request Body

04 Engine Catalogue

05 Error Codes

Error Response Format