API Reference

The Twynvex REST API lets you query simulation state, retrieve prediction horizons, and configure alert webhooks programmatically. All endpoints require Bearer token authentication.

Base URL

https://api.twynvex.com/v1 — all endpoints are TLS 1.3 only.

Authentication

All API requests must include a Authorization: Bearer <api_key> header. API keys are scoped per workspace and generated in the dashboard under Settings → API keys.

Example request

$ curl https://api.twynvex.com/v1/predictions/distillation-col-1 \
    -H "Authorization: Bearer tvx_live_xxxxxxxxxxxx"

GET /predictions/:model_id

Returns the current 4-hour prediction horizon for a unit operation model. The response includes the Monte Carlo ensemble summary (P10/P50/P90) and the Kalman filter state estimate used to initialize the current horizon.

Response — GET /v1/predictions/distillation-col-1

{
  "model_id": "distillation-col-1",
  "generated_at": "2026-03-04T14:22:18Z",
  "horizon_hours": 4,
  "state_estimate": {
    "t_feed": 147.3,
    "f_feed": 12430,
    "kalman_gain": 0.82
  },
  "predictions": [
    {
      "t_plus_h": 1,
      "overhead_yield_p10": 94.1,
      "overhead_yield_p50": 95.2,
      "overhead_yield_p90": 96.0
    }
  ]
}

GET /state/:model_id

Returns the current estimated physical state of the unit operation — temperatures, pressures, flow rates, and composition estimates — at the current moment, without the prediction horizon.

Response — GET /v1/state/distillation-col-1

{
  "model_id": "distillation-col-1",
  "timestamp": "2026-03-04T14:22:18Z",
  "state": {
    "t_feed": { "value": 147.3, "unit": "degC" },
    "f_feed": { "value": 12430, "unit": "kg/h" },
    "reflux_ratio_est": { "value": 3.18, "unit": "-" },
    "overhead_composition_ethanol": {
      "value": 0.952, "unit": "mol_frac"
    }
  }
}

Alerts & webhooks

Configure webhook alerts when the model detects a predicted deviation exceeding a threshold. Webhooks are sent as HTTP POST with a JSON body to your specified URL.

Webhook POST payload

{
  "event": "prediction_alert",
  "model_id": "distillation-col-1",
  "triggered_at": "2026-03-04T14:22:18Z",
  "alert": {
    "metric": "overhead_yield_p50",
    "threshold": 92.0,
    "predicted_value_t2h": 91.4,
    "hours_until_breach": 2.1,
    "severity": "warning"
  }
}

Next steps