API documentation (v1)

Embed the eTruck Range engine into your TMS, dealer portal or energy product. Auth via Bearer API key, billing per successful simulation. Machine-readable spec: /v1/openapi.json.

Authentication

Every request needs the header Authorization: Bearer etr_live_…. You create keys under Developer (Partner plan). The secret is shown exactly once.

Endpoints

POST	/v1/simulations	Single simulation · 1 unit
POST	/v1/simulations/batch	up to 100 tours · 1 unit per successful item
GET	/v1/vehicles	Vehicle catalog · free
GET	/v1/usage	Quota · free
GET	/v1/health	Status + model version · no auth

Example

curl -X POST https://etruck-range.de/v1/simulations \
  -H "Authorization: Bearer etr_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f3c…" \
  -d '{
    "vehicleId": "mercedes-eactros-600",
    "environment": { "temperatureC": 0, "weather": "schnee" },
    "segments": [
      { "distanceKm": 45, "baseSpeedKmh": 60, "massKg": 32000,
        "uphillM": 200, "downhillM": 180,
        "roadSplit": { "autobahnKm": 30, "landstrasseKm": 10, "stadtKm": 5 } }
    ]
  }'

Response:

{
  "data": {
    "verdict": "feasible",
    "feasible": true,
    "finalSocPct": 63.2,
    "totalDistanceKm": 45,
    "totalConsumptionKwh": 71.4,
    "kwhPerKm": 1.59,
    "modelVersion": "1.0.0"
  }
}

Billing & limits

Partner plan: 20,000 simulations/month included, then overage per unit.
Only successful simulations count — 4xx/5xx/validation errors do not.
Rate limit 300/min per key (header RateLimit-*, on 429 Retry-After).
Idempotency: Idempotency-Key header for safe retries on POST.