API Documentation

Battery degradation prediction API. Physics-based, 30ms per simulation.

Base URL: https://cozy-hope-production-cb41.up.railway.app

On this page
Quick StartAuthenticationPOST /api/predictPOST /api/dual_predictPOST /api/calibratePOST /api/trialGET /api/healthError Handling

Quick Start

Get a prediction in 60 seconds. No credit card required.

1. Get your API key

curl -X POST https://cozy-hope-production-cb41.up.railway.app/api/trial \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com"}'

2. Run your first prediction

curl -X POST https://cozy-hope-production-cb41.up.railway.app/api/predict \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "silicon_fraction": 0.20,
    "cycles": 1000,
    "c_rate": 1.0,
    "temperature_c": 25.0,
    "include_modes": true
  }'

Python (copy and run)

import requests

API_KEY = "your_api_key_here"  # from step 1
BASE = "https://cozy-hope-production-cb41.up.railway.app"

# Run a degradation prediction
resp = requests.post(f"{BASE}/api/predict",
    headers={"x-api-key": API_KEY},
    json={
        "silicon_fraction": 0.20,   # 20% silicon content
        "cycles": 1000,             # simulate 1,000 charge cycles
        "c_rate": 1.0,              # 1C charge rate
        "temperature_c": 25.0,      # 25°C operating temperature
        "soc_low": 0.1,             # lower SOC limit (0.1 = discharge to 10% SOC)
        "include_modes": True,      # include degradation breakdown
    }
)
data = resp.json()

print(f"Final retention: {data['final_retention_pct']:.1f}%")
print(f"Simulation time: {data['audit']['wall_time_ms']:.0f}ms")

# What's killing the cell?
modes = data["modes"]
print(f"LLI (SEI growth): {modes['lli_pct'][-1]:.1f}%")
print(f"LAM-Si (cracking): {modes['lam_si_pct'][-1]:.1f}%")
print(f"Transport: {modes['transport_pct'][-1]:.1f}%")

Python SDK (coming soon)

A typed Python SDK is in development. For now, the requests library above is the recommended integration path. Contact us if you need early SDK access.

Authentication

All prediction endpoints require an API key passed in the x-api-key header.

x-api-key: sp_free_abc123...

Free trial keys (sp_free_ prefix) include 50 simulations/month. Paid keys (sp_ prefix) include 2,500-10,000 simulations/month depending on tier.

Predict

POST/api/predictrequires API key

Run a single degradation simulation. Returns capacity retention curve, degradation mode decomposition, knee point detection, and safety metrics.

Parameters

silicon_fractionfloatdefault: 0.2
Silicon content by weight (0.0-0.50)
cyclesintdefault: 1000
Number of charge-discharge cycles (1-10,000)
c_ratefloatdefault: 1
Charge/discharge rate in C (0.05-10.0)
temperature_cfloatdefault: 25
Operating temperature in Celsius (-40 to 80)
include_modesbooldefault: true
Include degradation mode decomposition (LLI, LAM-Si, LAM-Gr, transport)
include_safetybooldefault: false
Include thermal runaway risk and safety metrics
sample_everyintdefault: 10
Return every Nth cycle (reduces response size)
seasonal_amplitude_cfloatdefault: 0
Half-amplitude of annual temperature swing in °C
diurnal_amplitude_cfloatdefault: 0
Half-amplitude of daily temperature swing in °C
soc_lowfloatdefault: 0
Lower SOC bound for cycling window (0.0-1.0). Set to 0.2 for 20-100% DOD cycling.
soc_highfloatdefault: 1
Upper SOC bound for cycling window (0.0-1.0). Set to 0.8 for 0-80% DOD cycling.
presetstring
Use a scenario preset (e.g. "ev_standard", "desert_outdoor")
calibrated_presetstring
Use a calibrated preset (e.g. "NatComms_20Si_LPD")

Response

{
  "version": "18.1",
  "cycles": [0, 10, 20, ...],
  "retention_pct": [100.0, 99.2, 98.4, ...],
  "final_retention_pct": 77.89,
  "total_cycles": 1000,
  "knee_point_cycle": null,
  "invariants_passed": true,
  "modes": {
    "lli_pct": [0.0, 0.12, ...],
    "lam_si_pct": [0.0, 0.08, ...],
    "lam_gr_pct": [0.0, 0.01, ...],
    "transport_pct": [0.0, 0.0, ...],
    "dominant_mode": ["LLI", "LLI", ...]
  },
  "audit": {
    "run_id": "abc123",
    "model_version": "18.1",
    "wall_time_ms": 30.7,
    "invariants_passed": true
  },
  "compute_time_s": 0.031
}

Dual Predict (Uncertainty)

POST/api/dual_predictrequires API key

Run a dual-model simulation with automatic uncertainty quantification. Returns central prediction plus pessimistic/optimistic bounds using opposing-bias averaging (Richardson extrapolation).

Additional Parameters

bias_fractionfloatdefault: 0.15
Perturbation magnitude for opposing-bias models (0.05-0.50). Default 0.15 = ±15% rate perturbation.

All other parameters are the same as /api/predict.

Response

{
  "version": "18.1",
  "method": "dual_model_averaging",
  "bias_fraction": 0.15,
  "cycles": [0, 10, 20, ...],
  "central_retention_pct": [100.0, 99.2, ...],
  "pessimistic_retention_pct": [100.0, 99.0, ...],
  "optimistic_retention_pct": [100.0, 99.4, ...],
  "final_retention_pct": 77.94,
  "envelope_width_final": 5.81,
  "bias_cancellation_pct": 98.3,
  "dma_invariants_passed": true,
  "compute_time_s": 0.062
}

Calibrate (Auto-Fit)

POST/api/calibraterequires API key

Fit the model to your experimental data. Provide cycle-retention pairs and the model automatically optimizes its degradation parameters to match your cell's behavior. Returns the fitted prediction and accuracy metrics.

Parameters

target_dataobjectrequired
Your experimental data. Must contain cycle and retention_pct arrays with at least 3 data points.
silicon_fractionfloatdefault: 0.2
Silicon content of the cell being fitted
c_ratefloatdefault: 1
C-rate used in the experiment
temperature_cfloatdefault: 25
Temperature during the experiment
max_iterationsintdefault: 300
Maximum optimizer iterations (capped at 500)

Example

import requests

resp = requests.post(f"{BASE}/api/calibrate",
    headers={"x-api-key": API_KEY},
    json={
        "target_data": {
            "cycle": [0, 100, 200, 300, 400, 500],
            "retention_pct": [100.0, 97.5, 95.0, 92.0, 88.5, 84.0]
        },
        "silicon_fraction": 0.15,
        "c_rate": 1.0,
        "temperature_c": 25.0
    }
)
cal = resp.json()
print(f"RMSE: {cal['calibration']['rmse']:.2f}%")
print(f"Grade: {cal['calibration']['grade']}")
print(f"R²: {cal['calibration']['r_squared']:.4f}")

Response

{
  "version": "18.1",
  "calibration": {
    "rmse": 0.23,
    "mae": 0.18,
    "grade": "A+",
    "r_squared": 0.9994,
    "converged": true,
    "n_iterations": 47,
    "fitted_params": {
      "degradation.SEI_rate_cycling": 5.24e-04,
      "degradation.gamma_Si": 2.09e-05,
      "degradation.crack_SEI_coupling": 4.66e-04,
      "degradation.cracking_rate": 5.57e-07
    }
  },
  "prediction": {
    "cycles": [0, 10, 20, ...],
    "retention_pct": [100.0, 99.7, ...]
  },
  "final_retention_pct": 83.5,
  "compute_time_s": 4.2
}

Free Trial

POST/api/trial

Create a free trial API key. No credit card required. 50 simulations per month.

emailstringrequired
Your email address

Response

{
  "api_key": "sp_free_abc123...",
  "email": "you@company.com",
  "monthly_limit": 50
}

Health Check

GET/api/health

Check API status, model version, and available presets. No authentication required.

Response

{
  "status": "ok",
  "service": "Scale Prognostics Battery Degradation API",
  "model_version": "18.1",
  "latency_ms": 31.2,
  "endpoints": [
    "POST /api/predict",
    "POST /api/dual_predict",
    "POST /api/calibrate",
    "GET /api/health"
  ],
  "scenario_presets": [
    "ev_standard", "premium", "long_life",
    "fast_charge", "temperate_outdoor", ...
  ],
  "calibrated_presets": [
    "NatComms_20Si_LPD", "Kirk_2024_FastCharge", ...
  ]
}

Error Handling

All errors return JSON with an error field.

401Invalid or missing API key
422Parameter out of valid range
429Monthly simulation limit reached
500Simulation failed (server error)
{
  "error": "silicon_fraction must be 0.0-0.50"
}

Usage Notes

Mid-life predictions (starting from degraded state)

The model currently simulates from a fresh cell. To predict remaining useful life for a battery already at 85-90% SOH, use the /api/calibrate endpoint with your observed degradation history. The calibrated model will then extrapolate forward from your last data point when you run a prediction with higher cycle counts. A dedicated initial_soh parameter is on the roadmap.

Charging protocol

The c_rate parameter applies to both charge and discharge. Separate charge/discharge rates and CC-CV protocol support are on the roadmap. For asymmetric protocols, use the dominant (higher-stress) rate as the input.

Rate Limits & Performance

Prediction latency30-50ms (single), 60ms (dual)
Calibration latency2-10 seconds
Monthly quotasFree: 50 | Starter: 2,500 | Professional: 10,000
Burst rateNo per-second throttling. Concurrent requests supported.
Uptime target99.9% availability. Monitor via GET /api/health

One simulation = one API call to /predict, /dual_predict, or /calibrate, regardless of cycle count. Quotas reset monthly (UTC). Overage returns HTTP 429 with upgrade link.

Enterprise

For teams that need more than the self-serve tiers:

✓Unlimited simulations
✓On-premise deployment option
✓Custom SLA with defined uptime and response commitments
✓Dedicated engineering support with named contact
✓Scoped API keys (per-user, per-application)
✓Async batch endpoint with webhook callbacks
✓Python SDK (pip install scale-prognostics)

A Data Processing Agreement (DPA) is available on request for any paid tier. Contact jason@scaleprognostics.com for enterprise pricing or to request a DPA.

Questions? Reach us at support@scaleprognostics.com

Get Started