AI Flight Status & Disruption API

Technical Docs Disruption Intelligence Recovery Orchestration Airline + OTA + TMC
Operated by Spyface Tech Company, LLC • 30 N Gould St Ste N, Sheridan, WY 82801 USA • Support: hello@spyface.com

1) Overview

Flight disruption is not only an “event stream” problem. It is a timing + confidence + decision problem. Acting too late loses seats; acting too early causes unnecessary rebook costs and passenger confusion. Spyface exposes disruption as probabilities with calibration, then runs a deterministic optimizer to select actions.

2) Concepts

3) Quickstart

1. POST a flight or itinerary to /v1/flights/disruption/score
2. Optionally, POST alternative itineraries to /v1/flights/recovery/rank
3. Render: show risk + “next best action” with reasons

4) Authentication

Authorization: Bearer YOUR_SPYFACE_API_KEY

5) Endpoints

6) Data Model

6.1 Disruption Scoring Request

{
  "request_id": "req_20260125_flt_21a",
  "flight": {
    "carrier": "TK",
    "flight_number": "001",
    "origin": "IST",
    "destination": "JFK",
    "scheduled_departure": "2026-03-12T09:30:00Z",
    "scheduled_arrival": "2026-03-12T15:10:00Z"
  },
  "status": {
    "estimated_departure": "2026-03-12T10:05:00Z",
    "estimated_arrival": "2026-03-12T15:35:00Z",
    "gate_out": null,
    "wheel_off": null,
    "wheel_on": null,
    "gate_in": null
  },
  "context": {
    "market": "US",
    "channel": "ota",
    "time_of_day_bucket": "morning"
  }
}

6.2 Disruption Scoring Response

{
  "request_id": "req_20260125_flt_21a",
  "generated_at": "2026-01-25T12:00:00Z",
  "risk": {
    "delay_15m": 0.42,
    "delay_60m": 0.18,
    "cancellation": 0.03,
    "diversion": 0.01
  },
  "confidence": {
    "calibration_band": "GOOD",
    "model_agreement": 0.82
  },
  "explanations": [
    {"code":"TURNAROUND_TIGHT", "detail":"Inbound turnaround buffer below route baseline"},
    {"code":"AIRPORT_CONGESTION", "detail":"Origin congestion regime elevated for this hour"},
    {"code":"SCHEDULE_SLIP", "detail":"Estimated departure already +35m vs schedule"}
  ],
  "recommended_next_action": {
    "code": "PREPARE_RECOVERY_OPTIONS",
    "threshold": "delay_60m>0.15 OR cancellation>0.02"
  }
}

6.3 Connection Risk Request

{
  "request_id": "req_20260125_conn_88c",
  "itinerary": {
    "segments": [
      {"carrier":"TK","flight_number":"001","origin":"IST","destination":"FRA",
       "scheduled_departure":"2026-03-12T09:30:00Z","scheduled_arrival":"2026-03-12T11:40:00Z"},
      {"carrier":"LH","flight_number":"405","origin":"FRA","destination":"JFK",
       "scheduled_departure":"2026-03-12T13:05:00Z","scheduled_arrival":"2026-03-12T16:05:00Z"}
    ]
  },
  "airport_rules": {
    "mct_minutes": 75,
    "terminal_change_penalty_minutes": 25
  }
}

6.4 Recovery Ranking Request

{
  "request_id": "req_20260125_reco_3c1",
  "problem": {
    "original_itinerary_id": "it_551",
    "disruption": {"type":"DELAY_RISK", "delay_60m": 0.18, "cancellation": 0.03}
  },
  "traveler": {
    "tier": "premium",
    "assistance": {"wheelchair": false},
    "preferences": {"avoid_overnight": true}
  },
  "constraints": {
    "max_additional_cost_usd": 180,
    "max_additional_travel_time_minutes": 240,
    "must_keep_cabin": "ECONOMY",
    "allow_airport_change": false
  },
  "alternatives": [
    {
      "alt_id":"a1",
      "segments":[
        {"carrier":"LH","flight_number":"403","origin":"FRA","destination":"JFK",
         "departure":"2026-03-12T14:10:00Z","arrival":"2026-03-12T17:10:00Z"}
      ],
      "cost_delta_usd": 120
    },
    {
      "alt_id":"a2",
      "segments":[
        {"carrier":"BA","flight_number":"901","origin":"FRA","destination":"LHR",
         "departure":"2026-03-12T13:40:00Z","arrival":"2026-03-12T14:35:00Z"},
        {"carrier":"BA","flight_number":"117","origin":"LHR","destination":"JFK",
         "departure":"2026-03-12T16:30:00Z","arrival":"2026-03-12T19:30:00Z"}
      ],
      "cost_delta_usd": 80
    }
  ]
}

6.5 Recovery Ranking Response

{
  "request_id": "req_20260125_reco_3c1",
  "results": [
    {
      "alt_id": "a1",
      "rank": {"position": 1, "out_of": 2},
      "scores": {
        "success_probability": 0.84,
        "time_cost_tradeoff": 0.77,
        "policy_feasibility": 0.91,
        "operational_risk": 0.14
      },
      "explanations": [
        {"code":"DIRECT_RECOVERY", "detail":"Single segment reduces misconnect surface area"},
        {"code":"COST_WITHIN_LIMIT", "detail":"Cost delta within constraint"},
        {"code":"LOW_AIRPORT_COMPLEXITY", "detail":"No airport change required"}
      ],
      "action": "OFFER_REBOOK"
    }
  ]
}

7) AI Models (Measurable Specs)

Spyface uses multiple specialized predictors + a deterministic optimizer. Each model has a clear label and metric.

8) Decision Engine (Recovery Ranking)

Recovery ranking is not sorting by arrival time. It is a multi-objective optimization problem:

• Objective: maximize traveler success + SLA compliance, minimize incremental cost and operational risk
• Constraints: policy, cabin, max cost, max extra travel time, avoid airport changes, assistance needs
• Guardrails: don’t offer alternatives likely to fail (low success_probability)

// Conceptual objective
EV(alt) =
  w1 * P(rebook_success) +
  w2 * SLA_score -
  w3 * cost_delta -
  w4 * operational_risk -
  w5 * misconnect_surface_area_penalty

9) Guardrails (Policies & Constraints)

10) Monitoring & KPIs

11) Code Examples

11.1 cURL — Disruption Score

curl -X POST "https://api.spyface.com/v1/flights/disruption/score" \
  -H "Authorization: Bearer YOUR_SPYFACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d @disruption-request.json

11.2 Node.js — Disruption Score

import fetch from "node-fetch";

const res = await fetch("https://api.spyface.com/v1/flights/disruption/score", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SPYFACE_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error(await res.text());
const data = await res.json();

console.log("Delay60:", data.risk.delay_60m, "Cancel:", data.risk.cancellation);
console.log("Next action:", data.recommended_next_action.code);

11.3 Python — Recovery Rank

import os, requests

resp = requests.post(
  "https://api.spyface.com/v1/flights/recovery/rank",
  headers={
    "Authorization": f"Bearer {os.environ['SPYFACE_API_KEY']}",
    "Content-Type": "application/json",
  },
  json=payload,
  timeout=10
)
resp.raise_for_status()
data = resp.json()

best = data["results"][0]
print(best["alt_id"], best["scores"]["success_probability"], best["action"])

11.4 Feedback loop (Outcomes → Calibration)

Send outcomes (actual delay, cancel, missed-connection, rebook success) to reduce drift and improve calibration.

{
  "request_id": "req_20260125_flt_21a",
  "events": [
    {"type":"OUTCOME_DELAY_MINUTES", "value": 47, "ts":"2026-03-12T16:00:00Z"},
    {"type":"OUTCOME_CANCELED", "value": false, "ts":"2026-03-12T16:00:01Z"},
    {"type":"OUTCOME_MISCONNECT", "value": false, "ts":"2026-03-12T16:00:02Z"},
    {"type":"OUTCOME_REBOOK_SUCCESS", "value": true, "ts":"2026-03-12T16:00:03Z"}
  ]
}

12) Errors

13) Security

• Encrypt in transit (TLS). Do not send raw payment data.
• Minimize PII. Traveler context should be pseudonymous where possible.
• Optional: request signing (HMAC) and IP allowlisting for enterprise.