{
  "openapi": "3.1.0",
  "info": {
    "title": "SeatWiFi Flight API",
    "version": "1.0.0",
    "description": "Will this flight have Starlink? Flight-level WiFi odds from ADS-B observations of which aircraft flew each flight number over the last 60 days. No key needed within the free limit. If you show a result, link to the url field. Changelog: flight numbers are now validated, so inputs the old 3-8 character check accepted (for example BA123A or 5-digit numbers) return 400 with a hint; flight_number in responses is the normalized value (QR068 becomes QR68); the stats fields, answer, url and attribution are additive and existing fields are unchanged."
  },
  "servers": [{ "url": "https://seatwifi.com" }],
  "paths": {
    "/api/v1/flights/{flightNumber}": {
      "get": {
        "operationId": "getFlight",
        "summary": "Starlink odds and WiFi facts for a flight number",
        "description": "Free tier without a key: 100 requests per day and 10 per minute per IP, for server-to-server calls (requests with a browser Origin header from other sites are refused). Send Authorization: Bearer <key> for paid plans.",
        "security": [{}, { "bearerAuth": [] }],
        "parameters": [
          {
            "name": "flightNumber",
            "in": "path",
            "required": true,
            "description": "Airline code and number. UA1234, UA 1234, ua-1234, B6123 and 6E123 are accepted. Leading zeros are dropped (QR068 is QR68).",
            "schema": { "type": "string", "examples": ["UA1234"] }
          },
          {
            "name": "date",
            "in": "query",
            "required": false,
            "description": "Flight date, YYYY-MM-DD. A past date ends the 60 day window on that date and fills on_date. A future date uses the window ending today.",
            "schema": { "type": "string", "format": "date" }
          }
        ],
        "responses": {
          "200": {
            "description": "Flight result",
            "headers": {
              "X-RateLimit-Limit": { "description": "Requests allowed per day (anonymous only)", "schema": { "type": "integer" } },
              "X-RateLimit-Remaining": { "description": "Requests left today (anonymous only)", "schema": { "type": "integer" } },
              "X-RateLimit-Reset": { "description": "Unix time of the next reset, UTC midnight (anonymous only)", "schema": { "type": "integer" } }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Flight" },
                "example": {
                  "flight_number": "UA1234",
                  "answer": "UA1234 flew a verified Starlink aircraft on 62% of the 29 days observed in the last 60 with known aircraft evidence. Mixed: check closer to departure.",
                  "confidence_level": "high",
                  "verdict": "mixed",
                  "basis": "observed_flights",
                  "starlink_probability": 0.62,
                  "observed_days": 31,
                  "starlink_days": 18,
                  "weak_starlink_days": 2,
                  "unknown_tail_days": 0,
                  "known_not_starlink_days": 11,
                  "inferred_not_starlink_days": 0,
                  "data_as_of": null,
                  "usable_days": 29,
                  "weak_or_missing_share": 0.065,
                  "distinct_tails": 6,
                  "window_days": 60,
                  "last_observed": "2026-10-23",
                  "recent_tails": [
                    { "tail_number": "N12345", "last_flown": "2026-10-23", "starlink": true, "evidence": "verified" }
                  ],
                  "on_date": null,
                  "airline_fleet": null,
                  "wifi_provider": "starlink",
                  "confidence": 65,
                  "airline": "United Airlines",
                  "airline_code": "UA",
                  "url": "https://seatwifi.com/flights/ua1234",
                  "attribution": "Data: seatwifi.com"
                }
              }
            }
          },
          "400": {
            "description": "Invalid flight number or date. The hint field says what to try.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          },
          "401": {
            "description": "Invalid or revoked API key",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          },
          "429": {
            "description": "Free limit reached. Retry-After gives the seconds to wait.",
            "headers": { "Retry-After": { "schema": { "type": "integer" } } },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Paid API key from https://seatwifi.com/for-developers" }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": { "type": "string" },
          "hint": { "type": "string", "description": "What to try next" }
        }
      },
      "RecentTail": {
        "type": "object",
        "properties": {
          "tail_number": { "type": "string" },
          "last_flown": { "type": "string", "format": "date" },
          "starlink": { "type": "boolean", "description": "True only when the tail has verified or corroborated Starlink evidence" },
          "evidence": { "type": "string", "enum": ["verified", "corroborated", "network_confirmed", "lone_report", "inference", "none", "unknown_tail", "absent_from_tracker"], "description": "network_confirmed: a user reported Starlink while connected through the Starlink network on or next to the flight date. absent_from_tracker: the aircraft is owned by the airline and is not on the airline's Starlink tracker list, and the tracker import succeeded within the last 3 days and listed at least 500 aircraft. Counted as not Starlink. Only used for airlines whose tracker list is complete (currently UA)." }
        }
      },
      "Flight": {
        "type": "object",
        "properties": {
          "flight_number": { "type": "string" },
          "answer": { "type": "string", "description": "One sentence an agent can quote" },
          "confidence_level": { "type": "string", "enum": ["high", "medium", "low", "none"], "description": "high: 20+ observed days, medium: 8-19, low: 1-7, none: 0" },
          "verdict": { "type": "string", "enum": ["starlink", "mostly_starlink", "mixed", "rarely_starlink", "no_starlink", "unknown"], "description": "unknown when confidence is low or none, or when weak_or_missing_share is above 0.4. When unknown, starlink_probability is null." },
          "basis": { "type": "string", "enum": ["observed_flights", "airline_fleet", "none"] },
          "starlink_probability": { "type": ["number", "null"], "minimum": 0, "maximum": 1, "description": "starlink_days / usable_days. Days with weak or missing evidence are excluded from both sides, not counted as not Starlink. Null whenever verdict is unknown, and when there are no usable days." },
          "observed_days": { "type": "integer", "description": "Days with an observed aircraft in the window" },
          "starlink_days": { "type": "integer", "description": "Days flown by a tail with verified or corroborated Starlink evidence" },
          "weak_starlink_days": { "type": "integer", "description": "Days flown by a tail whose only Starlink evidence is a lone user report or an inference" },
          "unknown_tail_days": { "type": "integer", "description": "Days flown by a tail with no record in our tail table" },
          "known_not_starlink_days": { "type": "integer", "description": "Days flown by a known tail with no Starlink evidence" },
          "inferred_not_starlink_days": { "type": "integer", "description": "Days flown by an aircraft with evidence class absent_from_tracker: owned by the airline per the aircraft registry, no Starlink evidence in our tail table, and absent from the airline's Starlink tracker list. Only for airlines whose tracker list is complete (currently UA) and only while the tracker import succeeded within the last 3 days and listed at least 500 aircraft. Otherwise those days stay in unknown_tail_days." },
          "data_as_of": { "type": ["string", "null"], "format": "date", "description": "Date of the latest tracker import used for inferred_not_starlink_days. Null when no inference was used." },
          "usable_days": { "type": "integer", "description": "starlink_days + known_not_starlink_days + inferred_not_starlink_days" },
          "weak_or_missing_share": { "type": "number", "description": "(weak_starlink_days + unknown_tail_days) / observed_days. Above 0.4 the verdict is unknown and the confidence level is lowered one step." },
          "distinct_tails": { "type": "integer" },
          "window_days": { "type": "integer" },
          "last_observed": { "type": ["string", "null"], "format": "date" },
          "recent_tails": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/RecentTail" } },
          "on_date": {
            "type": ["object", "null"],
            "description": "Aircraft observed on the requested past date",
            "properties": {
              "date": { "type": "string", "format": "date" },
              "tail_number": { "type": "string" },
              "starlink": { "type": "boolean" },
              "evidence": { "type": "string" }
            }
          },
          "airline_fleet": {
            "type": ["object", "null"],
            "description": "Airline-level fallback. Not specific to this flight.",
            "properties": {
              "airline": { "type": "string" },
              "starlink_status": { "type": "string" },
              "likelihood": { "type": "string" },
              "fleet_percentage": { "type": ["number", "null"] },
              "summary": { "type": "string" }
            }
          },
          "wifi_provider": { "type": "string", "description": "Existing field: predicted provider" },
          "confidence": { "type": "number", "description": "Existing field: prediction confidence in percent" },
          "airline": { "type": ["string", "null"] },
          "airline_code": { "type": ["string", "null"] },
          "aircraft_type": { "type": ["string", "null"] },
          "tail_number": { "type": ["string", "null"] },
          "details": { "type": ["string", "null"] },
          "last_verified": { "type": ["string", "null"] },
          "source": { "type": "string" },
          "url": { "type": "string", "format": "uri", "description": "Flight page. Please link to it when you show this result." },
          "attribution": { "type": "string" }
        },
        "required": ["flight_number", "answer", "confidence_level", "verdict", "basis", "url", "attribution"]
      }
    }
  }
}
