POST/simulate

Run Simulation

Run a disruption recovery simulation using the Pleiades CP-SAT solver.

POST/simulateAUTH

Run a disruption recovery simulation. Evaluates multiple recovery strategies and returns ranked options with KPIs.

Given a disrupted flight and minimum delay, the solver explores configured recovery strategies (delay propagation, aircraft swaps, cancellation, tail cancellation) and returns ranked recovery options with on-time performance, passenger satisfaction, and cost breakdowns.

The solver automatically extracts the disrupted flight date from the flight ID to anchor a 48-hour operational snapshot window.

Request Body

Parameter	Type	Required	Description
`scenario_id`	string	Required	Unique identifier for this simulation scenario.
`disrupted_flight`	string	Required	Flight ID of the disrupted flight (e.g. `QF401_2026-04-07T08:30:00Z`).
`min_delay_minutes`	integer	Required	Minimum delay in minutes for the disrupted flight.
`airline`	string= "QF"	Optional	Airline code.
`schedule_file`	string	Optional	Specific schedule file to load. Omit for the default schedule.
`force_refresh`	boolean= false	Optional	Force a fresh data load, bypassing the server-side cache.
`config`	SolverConfig	Optional	Custom solver configuration. See Solver Config.

Example Request

json

{
  "scenario_id": "disruption-2026-04-07-001",
  "disrupted_flight": "QF401_2026-04-07T08:30:00Z",
  "min_delay_minutes": 180,
  "airline": "QF",
  "config": {
    "operational": {
      "turn_minutes": 35,
      "max_runtime": 30
    },
    "strategies": ["delay", "cancel", "swap", "cancel_tail"]
  }
}

Response

The response contains ranked recovery options, the best option ID, any violations, and the configuration that was actually used (including defaults for omitted fields).

json

{
  "scenario_id": "disruption-2026-04-07-001",
  "flight_id": "QF401_2026-04-07T08:30:00Z",
  "generated_at": "2026-04-07T12:01:30Z",
  "options": [
    {
      "option_id": 1,
      "label": "Delay recovery",
      "action_set": [
        {
          "type": "delay_flight",
          "flight_id": "QF401_2026-04-07T08:30:00Z",
          "delay": 180
        }
      ],
      "summary": { "otp": 0.92, "nps": 0.85, "cost": 540 },
      "details": {
        "strategy": "delay",
        "kpi_breakdown": {
          "otp": 0.92,
          "nps": 0.85,
          "cancelled_flights": 0,
          "swapped_flights": 0,
          "deadheads": 0,
          "maintenance_violations": 0,
          "crew_violations": 0,
          "estimated_cost": 540
        }
      }
    }
  ],
  "best_option_id": 1,
  "violations": { "maintenance": [], "crew_duty": [] },
  "config_used": { "..." },
  "error": null
}

Action Types

Type	Fields	Description
`delay_flight`	`flight_id`, `delay`	Delay a flight by the specified minutes
`cancel_flight`	`flight_id`	Cancel a flight entirely
`swap_aircraft`	`flight_id`, `original_tail`, `new_tail`	Swap aircraft assignment
`deadhead`	`from`, `to`, `count`	Reposition empty aircraft

KPI Definitions

KPI	Range	Description
`otp`	0.0 – 1.0	On-time performance (flights ≤15 min delay / total)
`nps`	0.0 – 1.0	Net promoter proxy (penalised by delays and cancellations)
`cost`	integer	Total weighted cost in solver units

Error Handling

If the simulation fails, the response still conforms to the SimulationResponse schema but with an empty options array and the error field populated:

json

{
  "scenario_id": "...",
  "flight_id": "...",
  "options": [],
  "best_option_id": -1,
  "error": "Simulation failed: Flight 'XX999' not found in schedule."
}

Status	Cause
`400`	Disrupted flight not found in the schedule
`401`	Missing or invalid API key
`500`	Solver failure or internal error