{
  "openapi": "3.1.0",
  "info": {
    "title": "Rotate Pilot Aviation API",
    "description": "Free, no-key aviation data API for pilots, developers, and AI agents. Live METAR weather, airport info by ICAO, aircraft specs, an aviation glossary, FAA-style practice questions, and a daily pilot quiz. All endpoints return JSON over HTTPS with open CORS. Rate limit: 60 requests per IP per hour. Maintained by Rotate Pilot (rotatepilot.com), built by a commercial pilot.",
    "version": "1.0.0",
    "termsOfService": "https://rotatepilot.com/terms",
    "contact": {
      "name": "Rotate Pilot",
      "url": "https://rotatepilot.com/developers",
      "email": "hello@rotatepilot.com"
    },
    "license": {
      "name": "Free for any use with attribution to Rotate Pilot",
      "url": "https://rotatepilot.com/developers"
    }
  },
  "servers": [
    { "url": "https://rotatepilot.com", "description": "Production" }
  ],
  "externalDocs": {
    "description": "API documentation",
    "url": "https://rotatepilot.com/developers"
  },
  "tags": [
    { "name": "Weather", "description": "Live aviation weather" },
    { "name": "Reference", "description": "Airports, aircraft, and glossary data" },
    { "name": "Training", "description": "Practice questions and quizzes" },
    { "name": "Meta", "description": "Platform info and stats" }
  ],
  "paths": {
    "/api/v1/metar": {
      "get": {
        "tags": ["Weather"],
        "summary": "Decoded METAR (and optional TAF) for an airport",
        "operationId": "getMetar",
        "parameters": [
          { "name": "icao", "in": "query", "required": true, "description": "4-letter ICAO airport code (e.g. KJFK).", "schema": { "type": "string", "example": "KJFK" } },
          { "name": "taf", "in": "query", "required": false, "description": "Set to 1 to also include the TAF forecast.", "schema": { "type": "integer", "enum": [0, 1], "default": 0 } }
        ],
        "responses": {
          "200": {
            "description": "Decoded current weather",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Metar" } } }
          },
          "404": { "description": "No report available for that ICAO" }
        }
      }
    },
    "/api/v1/airport/{icao}": {
      "get": {
        "tags": ["Reference"],
        "summary": "Airport information by ICAO code",
        "operationId": "getAirport",
        "parameters": [
          { "name": "icao", "in": "path", "required": true, "description": "4-letter ICAO airport code.", "schema": { "type": "string", "example": "KJFK" } }
        ],
        "responses": {
          "200": { "description": "Airport record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Airport" } } } },
          "404": { "description": "Airport not found" }
        }
      }
    },
    "/api/v1/aircraft/{slug}": {
      "get": {
        "tags": ["Reference"],
        "summary": "Aircraft specifications by slug",
        "operationId": "getAircraft",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "description": "Aircraft slug (e.g. cessna-172-skyhawk, piper-pa-28-warrior, airbus-a320neo).", "schema": { "type": "string", "example": "cessna-172-skyhawk" } }
        ],
        "responses": {
          "200": { "description": "Aircraft record", "content": { "application/json": { "schema": { "type": "object" } } } },
          "404": { "description": "Aircraft not found (response includes a hint with example slugs)" }
        }
      }
    },
    "/api/v1/glossary/{term}": {
      "get": {
        "tags": ["Reference"],
        "summary": "Aviation glossary definition by slug",
        "operationId": "getGlossaryTerm",
        "parameters": [
          { "name": "term", "in": "path", "required": true, "description": "Glossary term slug (e.g. squawk, angle-of-attack).", "schema": { "type": "string", "example": "squawk" } }
        ],
        "responses": {
          "200": { "description": "Glossary entry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlossaryTerm" } } } },
          "404": { "description": "Term not found" }
        }
      }
    },
    "/api/v1/question": {
      "get": {
        "tags": ["Training"],
        "summary": "FAA-style practice questions",
        "operationId": "getQuestions",
        "parameters": [
          { "name": "subject", "in": "query", "required": false, "description": "Filter by subject (e.g. meteorology, regulations, navigation).", "schema": { "type": "string" } },
          { "name": "count", "in": "query", "required": false, "description": "Number of questions to return (1-5).", "schema": { "type": "integer", "minimum": 1, "maximum": 5, "default": 1 } }
        ],
        "responses": {
          "200": { "description": "Practice questions", "content": { "application/json": { "schema": { "type": "object" } } } }
        }
      }
    },
    "/api/v1/quiz-of-day": {
      "get": {
        "tags": ["Training"],
        "summary": "The aviation question of the day",
        "operationId": "getQuizOfDay",
        "responses": {
          "200": { "description": "Question of the day", "content": { "application/json": { "schema": { "type": "object" } } } }
        }
      }
    },
    "/api/v1/quote": {
      "get": {
        "tags": ["Meta"],
        "summary": "Aviation quote of the day",
        "operationId": "getQuote",
        "responses": {
          "200": { "description": "Quote of the day", "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string" }, "text": { "type": "string" }, "author": { "type": "string" } } } } } }
        }
      }
    },
    "/api/v1/stats": {
      "get": {
        "tags": ["Meta"],
        "summary": "Platform statistics and API endpoint index",
        "operationId": "getStats",
        "responses": {
          "200": { "description": "Stats and endpoint list", "content": { "application/json": { "schema": { "type": "object" } } } }
        }
      }
    },
    "/api/public/v1/info": {
      "get": {
        "tags": ["Meta"],
        "summary": "Machine-readable platform manifest",
        "operationId": "getInfo",
        "responses": {
          "200": { "description": "Platform manifest", "content": { "application/json": { "schema": { "type": "object" } } } }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Metar": {
        "type": "object",
        "properties": {
          "icao": { "type": "string", "example": "KJFK" },
          "raw": { "type": "string", "example": "METAR KJFK 130851Z 33015G21KT 10SM SCT250 23/15 A2982" },
          "reportTime": { "type": "string", "format": "date-time" },
          "category": { "type": "string", "enum": ["VFR", "MVFR", "IFR", "LIFR"], "example": "VFR" },
          "visibilitySm": { "type": "number", "example": 10 },
          "temperatureC": { "type": "number", "example": 23.3 },
          "dewpointC": { "type": "number", "example": 15 },
          "windDir": { "type": "integer", "example": 330 },
          "windSpeedKt": { "type": "integer", "example": 15 }
        }
      },
      "Airport": {
        "type": "object",
        "properties": {
          "icao": { "type": "string", "example": "KJFK" },
          "iata": { "type": "string", "example": "JFK" },
          "name": { "type": "string", "example": "John F. Kennedy International Airport" },
          "city": { "type": "string", "example": "New York" },
          "country": { "type": "string", "example": "United States" },
          "region": { "type": "string", "example": "North America" },
          "coordinates": { "type": "object", "properties": { "lat": { "type": "number" }, "lon": { "type": "number" } } },
          "elevation": { "type": "integer", "example": 13 },
          "runways": { "type": "integer", "example": 4 }
        }
      },
      "GlossaryTerm": {
        "type": "object",
        "properties": {
          "slug": { "type": "string", "example": "squawk" },
          "term": { "type": "string", "example": "Squawk Code" },
          "abbreviation": { "type": "string", "nullable": true },
          "category": { "type": "string", "example": "regulations" },
          "definition": { "type": "string" },
          "related": { "type": "array", "items": { "type": "string" } }
        }
      }
    }
  }
}