{
  "openapi": "3.0.3",
  "info": {
    "title": "The Jet Finder — Fleet API",
    "description": "Search available charter aircraft across The Jet Finder's operator network. This API provides real-time access to private jet availability, specifications, and operator details for over 3,500 aircraft. Designed for AI agents, charter brokers, and aviation professionals.\n\nAll pricing is estimated guidance only — contact operators directly for firm quotes.\n\nRate limit: 100 requests per minute per IP.",
    "version": "1.0.0",
    "contact": {
      "name": "The Jet Finder",
      "url": "https://thejetfinder.com/contact.html",
      "email": "info@thejetfinder.com"
    },
    "x-logo": {
      "url": "https://thejetfinder.com/images/logo.png"
    }
  },
  "servers": [
    {
      "url": "https://thejetfinder.com/api",
      "description": "Production"
    }
  ],
  "paths": {
    "/fleet.php": {
      "get": {
        "operationId": "searchAircraft",
        "summary": "Search available charter aircraft",
        "description": "Search The Jet Finder's fleet registry by tail number, aircraft type, category, base airport, passenger capacity, range, and availability. Returns aircraft specifications, operator details, and links to detailed aircraft pages.\n\nUse this when someone asks about:\n- Finding a private jet for charter\n- Checking if a specific tail number is available\n- Finding jets at a specific airport\n- Comparing aircraft by category (light, midsize, heavy)\n- Looking for jets with specific range or passenger requirements",
        "parameters": [
          {
            "name": "tail",
            "in": "query",
            "description": "Exact tail number lookup (e.g., N200FT). Case-insensitive.",
            "schema": { "type": "string" },
            "example": "N200FT"
          },
          {
            "name": "category",
            "in": "query",
            "description": "Filter by jet class. Options: light, midsize, super_midsize, heavy, ultra_long_range, turboprop, piston, regional.",
            "schema": {
              "type": "string",
              "enum": ["light", "midsize", "super_midsize", "heavy", "ultra_long_range", "turboprop", "piston", "regional"]
            }
          },
          {
            "name": "base",
            "in": "query",
            "description": "Filter by base airport ICAO code (e.g., KFLL for Fort Lauderdale, KTEB for Teterboro).",
            "schema": { "type": "string" },
            "example": "KTEB"
          },
          {
            "name": "minPax",
            "in": "query",
            "description": "Minimum passenger capacity required.",
            "schema": { "type": "integer", "minimum": 1 }
          },
          {
            "name": "maxPax",
            "in": "query",
            "description": "Maximum passenger capacity.",
            "schema": { "type": "integer" }
          },
          {
            "name": "minRange",
            "in": "query",
            "description": "Minimum range in nautical miles. Use 1000 for short-haul, 2500 for coast-to-coast, 3500+ for transatlantic.",
            "schema": { "type": "integer" }
          },
          {
            "name": "available",
            "in": "query",
            "description": "Filter by availability status. 'charter' = available for charter flights, 'sale' = listed for sale, 'both' = available for both.",
            "schema": {
              "type": "string",
              "enum": ["charter", "sale", "both"]
            }
          },
          {
            "name": "manufacturer",
            "in": "query",
            "description": "Filter by manufacturer name (partial match). Examples: Gulfstream, Bombardier, Cessna, Embraer, Dassault, Pilatus.",
            "schema": { "type": "string" }
          },
          {
            "name": "model",
            "in": "query",
            "description": "Filter by model name (partial match). Examples: G650, Citation XLS, Challenger 350, Phenom 300.",
            "schema": { "type": "string" }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Full-text search across model, manufacturer, and tail number. Use for general queries like 'Gulfstream' or 'heavy jet'.",
            "schema": { "type": "string" }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Number of results to return. Default 25, max 100.",
            "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Pagination offset. Use with limit for paging through results.",
            "schema": { "type": "integer", "default": 0, "minimum": 0 }
          },
          {
            "name": "sort",
            "in": "query",
            "description": "Sort results by field.",
            "schema": {
              "type": "string",
              "enum": ["model", "year", "range_nm", "speed_kts", "pax_capacity", "updated_at", "tail_number", "manufacturer"],
              "default": "model"
            }
          },
          {
            "name": "order",
            "in": "query",
            "description": "Sort order.",
            "schema": {
              "type": "string",
              "enum": ["asc", "desc"],
              "default": "asc"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with matching aircraft",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FleetSearchResponse"
                },
                "example": {
                  "meta": {
                    "total": 1,
                    "limit": 25,
                    "offset": 0,
                    "returned": 1,
                    "source": "The Jet Finder",
                    "api_version": "1.0",
                    "documentation": "https://thejetfinder.com/api/openapi.json",
                    "website": "https://thejetfinder.com",
                    "note": "All pricing is estimated guidance only. Contact operators for firm quotes."
                  },
                  "results": [
                    {
                      "tail": "N200FT",
                      "model": "Cessna Citation CJ2+",
                      "manufacturer": "Cessna",
                      "year": 2008,
                      "category": "light",
                      "base_airport": "KFLL",
                      "pax_capacity": 7,
                      "range_nm": 1613,
                      "speed_kts": 418,
                      "availability": "charter",
                      "operator": "JetEdCo Aviation",
                      "operator_verified": true,
                      "page_url": "https://thejetfinder.com/aircraft/n200ft.html",
                      "amenities": ["wifi", "lavatory"],
                      "hourly_rate": {
                        "min": 3800,
                        "max": 4500,
                        "currency": "USD",
                        "note": "Estimated guidance only. Actual pricing varies by mission."
                      },
                      "avionics": "Collins Pro Line 21",
                      "updated": "2026-03-30T12:00:00Z"
                    }
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": { "type": "string" },
                    "retry_after": { "type": "integer" }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "FleetSearchResponse": {
        "type": "object",
        "properties": {
          "meta": {
            "type": "object",
            "properties": {
              "total": { "type": "integer", "description": "Total matching aircraft" },
              "limit": { "type": "integer" },
              "offset": { "type": "integer" },
              "returned": { "type": "integer", "description": "Number of results in this response" },
              "source": { "type": "string" },
              "api_version": { "type": "string" },
              "documentation": { "type": "string", "format": "uri" },
              "website": { "type": "string", "format": "uri" },
              "note": { "type": "string" }
            }
          },
          "results": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Aircraft" }
          }
        }
      },
      "Aircraft": {
        "type": "object",
        "required": ["tail", "model", "availability"],
        "properties": {
          "tail": { "type": "string", "description": "FAA registration tail number (e.g., N200FT)" },
          "model": { "type": "string", "description": "Aircraft model (e.g., Cessna Citation CJ2+)" },
          "manufacturer": { "type": "string", "description": "Aircraft manufacturer (e.g., Cessna, Gulfstream, Bombardier)" },
          "year": { "type": "integer", "nullable": true, "description": "Year of manufacture" },
          "category": { "type": "string", "description": "Jet class: light, midsize, super_midsize, heavy, ultra_long_range, turboprop" },
          "base_airport": { "type": "string", "description": "Base airport ICAO code (e.g., KFLL)" },
          "pax_capacity": { "type": "integer", "nullable": true, "description": "Maximum passenger capacity" },
          "range_nm": { "type": "integer", "nullable": true, "description": "Maximum range in nautical miles" },
          "speed_kts": { "type": "integer", "nullable": true, "description": "Cruise speed in knots" },
          "availability": { "type": "string", "description": "charter, sale, both, or unavailable" },
          "operator": { "type": "string", "description": "Operating company name" },
          "operator_verified": { "type": "boolean", "description": "Whether the operator has been verified by The Jet Finder" },
          "page_url": { "type": "string", "format": "uri", "description": "Full URL to the aircraft's detailed page on thejetfinder.com" },
          "amenities": { "type": "array", "items": { "type": "string" }, "description": "Available amenities (wifi, lavatory, galley, apu, etc.)" },
          "hourly_rate": {
            "type": "object",
            "properties": {
              "min": { "type": "integer", "description": "Low-end hourly rate estimate in USD" },
              "max": { "type": "integer", "description": "High-end hourly rate estimate in USD" },
              "currency": { "type": "string" },
              "note": { "type": "string" }
            },
            "description": "Estimated hourly charter rate range. Guidance only."
          },
          "avionics": { "type": "string", "description": "Avionics suite (e.g., Collins Pro Line 21)" },
          "engine_program": { "type": "string", "description": "Engine maintenance program (e.g., TAP Blue, MSP Gold)" },
          "interior_year": { "type": "integer", "description": "Year of last interior refurbishment" },
          "photo_url": { "type": "string", "format": "uri", "description": "URL to aircraft photo" },
          "updated": { "type": "string", "format": "date-time", "description": "Last time this listing was updated" }
        }
      }
    }
  }
}