{
  "components": {
    "schemas": {
      "DlcInfo": {
        "properties": {
          "id": {
            "type": "string"
          },
          "installed": {
            "type": "boolean"
          },
          "name": {
            "type": "string"
          },
          "vehicle": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "vehicle",
          "installed"
        ],
        "type": "object"
      },
      "FeedbackRequest": {
        "properties": {
          "feedback_type": {
            "enum": [
              "feature",
              "bug",
              "general"
            ],
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "scenario_id": {
            "nullable": true,
            "type": "string"
          }
        },
        "required": [
          "feedback_type",
          "message"
        ],
        "type": "object"
      },
      "GenerateRequest": {
        "properties": {
          "aircraft": {
            "description": "Primary flyable aircraft (F/A-26B, F-45A, EF-24G, AV-42C, AH-94, T-55, or Auto)",
            "example": "F/A-26B",
            "type": "string"
          },
          "api_key": {
            "description": "Optional custom OpenRouter / LLM API key",
            "type": "string"
          },
          "dlc_filter": {
            "description": "DLC vehicle constraint filter",
            "enum": [
              "all",
              "base_only"
            ],
            "example": "all",
            "type": "string"
          },
          "game_mode": {
            "description": "Game mode",
            "enum": [
              "Singleplayer",
              "MultiplayerCoop",
              "MultiplayerPvP"
            ],
            "example": "MultiplayerPvP",
            "type": "string"
          },
          "loadout": {
            "description": "Semicolon-delimited weapon equipment codes",
            "example": "aim-120;aim9+;cagm-6;",
            "type": "string"
          },
          "player_count": {
            "description": "Number of multiplayer pilot slots (1-16)",
            "example": 16,
            "maximum": 16,
            "minimum": 1,
            "type": "integer"
          },
          "prompt": {
            "description": "Natural language tactical briefing prompt or mission description",
            "example": "Multiplayer PvP air superiority and strike operation over rugged alpine peaks",
            "type": "string"
          },
          "stage_count": {
            "description": "Number of sequential campaign stages (1-5)",
            "example": 3,
            "maximum": 5,
            "minimum": 1,
            "type": "integer"
          },
          "terrain_preset": {
            "description": "Geomorphological procedural terrain preset",
            "enum": [
              "Standard",
              "AlpinePeaks",
              "TacticalCanyon",
              "CoastalFjord",
              "TabletopSpire",
              "VolcanicCaldera",
              "RiverValley",
              "Archipelago"
            ],
            "example": "AlpinePeaks",
            "type": "string"
          }
        },
        "required": [
          "prompt"
        ],
        "type": "object"
      },
      "GenerateResponse": {
        "properties": {
          "map_id": {
            "example": "autogen_48273_1786672353281_map",
            "type": "string"
          },
          "message": {
            "example": "Multi-stage campaign successfully generated with 3 progressive mission stages!",
            "type": "string"
          },
          "scenario_id": {
            "example": "autogen_48273_1786672353281",
            "type": "string"
          },
          "units": {
            "items": {
              "$ref": "#/components/schemas/UnitMarkerDto"
            },
            "type": "array"
          }
        },
        "required": [
          "scenario_id",
          "map_id",
          "message",
          "units"
        ],
        "type": "object"
      },
      "InstallRequest": {
        "properties": {
          "scenario_id": {
            "type": "string"
          }
        },
        "required": [
          "scenario_id"
        ],
        "type": "object"
      },
      "InstallResponse": {
        "properties": {
          "path": {
            "type": "string"
          },
          "status": {
            "example": "installed",
            "type": "string"
          }
        },
        "required": [
          "status",
          "path"
        ],
        "type": "object"
      },
      "SteamSessionDto": {
        "properties": {
          "authenticated": {
            "type": "boolean"
          },
          "avatar_url": {
            "nullable": true,
            "type": "string"
          },
          "persona_name": {
            "nullable": true,
            "type": "string"
          },
          "steam_id": {
            "nullable": true,
            "type": "string"
          }
        },
        "required": [
          "authenticated"
        ],
        "type": "object"
      },
      "UnitMarkerDto": {
        "properties": {
          "faction": {
            "example": "Enemy",
            "type": "string"
          },
          "name": {
            "example": "SA-10 SAM Radar",
            "type": "string"
          },
          "role": {
            "example": "IADS Radar",
            "type": "string"
          },
          "threat_radius_m": {
            "example": 45000.0,
            "type": "number"
          },
          "unit_type": {
            "example": "SAM Radar",
            "type": "string"
          },
          "x": {
            "example": 138000.0,
            "type": "number"
          },
          "y": {
            "example": 1450.0,
            "type": "number"
          },
          "z": {
            "example": 238000.0,
            "type": "number"
          }
        },
        "required": [
          "name",
          "unit_type",
          "faction",
          "x",
          "y",
          "z"
        ],
        "type": "object"
      },
      "WorkshopStatusDto": {
        "properties": {
          "error": {
            "nullable": true,
            "type": "string"
          },
          "progress": {
            "nullable": true,
            "type": "number"
          },
          "published_file_id": {
            "nullable": true,
            "type": "integer"
          },
          "state": {
            "enum": [
              "idle",
              "item_created",
              "ready_to_submit",
              "uploading",
              "completed",
              "failed"
            ],
            "type": "string"
          },
          "url": {
            "nullable": true,
            "type": "string"
          }
        },
        "required": [
          "state"
        ],
        "type": "object"
      },
      "WorkshopUploadRequest": {
        "properties": {
          "description": {
            "nullable": true,
            "type": "string"
          },
          "published_file_id": {
            "description": "Optional existing Workshop item ID to update",
            "nullable": true,
            "type": "integer"
          },
          "scenario_id": {
            "type": "string"
          },
          "title": {
            "nullable": true,
            "type": "string"
          }
        },
        "required": [
          "scenario_id"
        ],
        "type": "object"
      },
      "WorkshopUploadStartResponse": {
        "properties": {
          "message": {
            "type": "string"
          },
          "scenario_id": {
            "type": "string"
          },
          "status": {
            "example": "upload_started",
            "type": "string"
          }
        },
        "required": [
          "status",
          "scenario_id",
          "message"
        ],
        "type": "object"
      },
      "X402ConfigDto": {
        "properties": {
          "enabled": {
            "type": "boolean"
          },
          "price": {
            "$ref": "#/components/schemas/X402Price"
          },
          "protocol": {
            "example": "x402",
            "type": "string"
          },
          "recipient": {
            "type": "string"
          }
        },
        "required": [
          "enabled",
          "protocol",
          "price",
          "recipient"
        ],
        "type": "object"
      },
      "X402PaymentRequirement": {
        "properties": {
          "description": {
            "example": "Micropayment for AI campaign synthesis via Cloudflare Monetization Gateway",
            "type": "string"
          },
          "error": {
            "example": "Payment Required",
            "type": "string"
          },
          "price": {
            "$ref": "#/components/schemas/X402Price"
          },
          "protocol": {
            "example": "x402",
            "type": "string"
          },
          "recipient": {
            "example": "0xD6Bb3f845bE46397F43f482174094FB8116aB99b",
            "type": "string"
          },
          "resource_id": {
            "example": "/api/generate",
            "type": "string"
          },
          "status": {
            "example": 402,
            "type": "integer"
          },
          "version": {
            "example": "1.0",
            "type": "string"
          }
        },
        "required": [
          "error",
          "status",
          "protocol",
          "version",
          "price",
          "recipient",
          "resource_id"
        ],
        "type": "object"
      },
      "X402Price": {
        "properties": {
          "amount": {
            "example": "1.00",
            "type": "string"
          },
          "currency": {
            "example": "USDC",
            "type": "string"
          },
          "network": {
            "example": "base",
            "type": "string"
          }
        },
        "required": [
          "amount",
          "currency",
          "network"
        ],
        "type": "object"
      }
    },
    "securitySchemes": {
      "x402PaymentAuth": {
        "description": "x402 stablecoin micropayment settlement proof or Cloudflare edge verification token.",
        "in": "header",
        "name": "X-402-Payment-Proof",
        "type": "apiKey"
      }
    }
  },
  "info": {
    "contact": {
      "name": "VTOL VR Mission Architect Team",
      "url": "https://github.com/vtol-vr-mission-architect"
    },
    "description": "Tactical Flight Campaign Synthesizer & Procedural Mission Engine for VTOL VR. Comprehensive REST API for procedural VTOL VR campaign synthesis, terrain heightmap generation, ConfigNode AST validation, Steam OpenID authentication, and Steam Workshop UGC publishing.",
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    },
    "title": "VTOL VR Campaign Architect API",
    "version": "2026.1.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/api/dlcs": {
      "get": {
        "description": "Returns metadata regarding supported VTOL VR DLC vehicles (e.g. EF-24G Mischief, AH-94 Dragonfly, T-55 Tyro) and base aircraft compatibility.",
        "operationId": "listDlcs",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/DlcInfo"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Array of DLC metadata"
          }
        },
        "summary": "List Available DLCs"
      }
    },
    "/api/download/{scenario_id}": {
      "get": {
        "description": "Downloads the full zipped scenario archive containing .vts scenario ConfigNode, .vtm map ConfigNode, 16-bit heightmap.png, and WorkshopItemInfo.xml ready for VTOL VR.",
        "operationId": "downloadScenarioZip",
        "parameters": [
          {
            "description": "Scenario identifier",
            "in": "path",
            "name": "scenario_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/zip": {}
            },
            "description": "Zipped scenario archive"
          },
          "404": {
            "description": "Scenario not found"
          }
        },
        "summary": "Download Scenario Package (.zip)"
      }
    },
    "/api/feedback": {
      "get": {
        "description": "Retrieves recent feedback submissions.",
        "operationId": "listFeedback",
        "responses": {
          "200": {
            "description": "Array of feedback items"
          }
        },
        "summary": "List User Feedback"
      },
      "post": {
        "description": "Saves feedback ratings, bug reports, or feature requests.",
        "operationId": "submitFeedback",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FeedbackRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Feedback recorded"
          }
        },
        "summary": "Submit User Feedback"
      }
    },
    "/api/generate": {
      "post": {
        "description": "Synthesizes a complete procedural VTOL VR mission with 16-bit terrain heightmap, ConfigNode AST (.vts/.vtm), carrier strike groups, IADS networks, and weapon configurations.",
        "operationId": "generateMission",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GenerateRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenerateResponse"
                }
              }
            },
            "description": "Campaign scenario successfully synthesized"
          },
          "400": {
            "content": {
              "text/plain": {
                "example": "Invalid weapon compatibility for aircraft F/A-26B"
              }
            },
            "description": "Invalid generation parameters or loadout configuration"
          },
          "402": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/X402PaymentRequirement"
                }
              }
            },
            "description": "Payment Required via x402 Protocol (Cloudflare Monetization Gateway)"
          }
        },
        "summary": "Generate Campaign Mission"
      }
    },
    "/api/heightmap/{scenario_id}": {
      "get": {
        "description": "Returns the 16-bit PNG heightmap or topographic relief preview for the specified scenario.",
        "operationId": "getHeightmap",
        "parameters": [
          {
            "description": "Unique scenario identifier (e.g. autogen_54321_1786672353281)",
            "in": "path",
            "name": "scenario_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "image/png": {}
            },
            "description": "Heightmap PNG image"
          },
          "404": {
            "description": "Scenario not found"
          }
        },
        "summary": "Get Scenario Heightmap / Preview"
      }
    },
    "/api/install": {
      "post": {
        "description": "Directly installs the scenario package into the local VTOL VR CustomScenarios folder (%APPDATA%\\Boundless Dynamics, LLC\\VTOLVR\\SaveData\\CustomScenarios).",
        "operationId": "installScenario",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InstallRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InstallResponse"
                }
              }
            },
            "description": "Scenario installed successfully"
          }
        },
        "summary": "Install Scenario to Local CustomScenarios"
      }
    },
    "/api/steam/logout": {
      "post": {
        "description": "Terminates current Steam session and clears authentication cookies.",
        "operationId": "steamLogout",
        "responses": {
          "200": {
            "description": "Session successfully invalidated"
          }
        },
        "summary": "Log Out Steam Session"
      }
    },
    "/api/steam/session": {
      "get": {
        "description": "Returns current Steam user authentication status, SteamID64, persona name, and avatar URL.",
        "operationId": "getSteamSession",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SteamSessionDto"
                }
              }
            },
            "description": "Current authentication status"
          }
        },
        "summary": "Get Steam Authentication Session"
      }
    },
    "/api/workshop/status/{scenario_id}": {
      "get": {
        "description": "Polls the current status, progress percentage, published file ID, and Steam Community URL of an active Workshop upload.",
        "operationId": "getWorkshopStatus",
        "parameters": [
          {
            "description": "Scenario identifier",
            "in": "path",
            "name": "scenario_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkshopStatusDto"
                }
              }
            },
            "description": "Current upload status"
          }
        },
        "summary": "Get Workshop Upload Status"
      }
    },
    "/api/workshop/upload": {
      "post": {
        "description": "Initiates asynchronous UGC publication or update to Steam Workshop for App ID 667970.",
        "operationId": "uploadWorkshopItem",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WorkshopUploadRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkshopUploadStartResponse"
                }
              }
            },
            "description": "Upload started in background worker"
          }
        },
        "summary": "Upload or Update Steam Workshop Item"
      }
    },
    "/api/x402/config": {
      "get": {
        "description": "Returns the active x402 stablecoin payment configuration, pricing, recipient wallet, and status.",
        "operationId": "getX402Config",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/X402ConfigDto"
                }
              }
            },
            "description": "x402 protocol configuration"
          }
        },
        "summary": "Get x402 Monetization Gateway Configuration"
      }
    },
    "/auth/steam/callback": {
      "get": {
        "description": "Verifies the cryptographic OpenID 2.0 assertion with Valve servers and creates an authenticated SteamSession.",
        "operationId": "steamCallback",
        "responses": {
          "200": {
            "description": "Authentication verified and session cookie issued"
          }
        },
        "summary": "Steam OpenID Callback Handler"
      }
    },
    "/auth/steam/login": {
      "get": {
        "description": "Redirects the browser to the official Steam OpenID 2.0 authentication gateway.",
        "operationId": "steamLogin",
        "responses": {
          "307": {
            "description": "Redirect to https://steamcommunity.com/openid/login"
          }
        },
        "summary": "Initiate Steam OpenID Login"
      }
    },
    "/health": {
      "get": {
        "description": "Returns HTTP 200 OK if the Mission Architect server is healthy and responding.",
        "operationId": "healthCheck",
        "responses": {
          "200": {
            "content": {
              "text/plain": {
                "example": "OK"
              }
            },
            "description": "Server is operational"
          }
        },
        "summary": "Health Check"
      }
    }
  },
  "servers": [
    {
      "description": "Local Development Server",
      "url": "http://127.0.0.1:3000"
    }
  ]
}