{
  "openapi": "3.1.0",
  "info": {
    "title": "Kingshot Planner API",
    "version": "3.1.0",
    "description": "Server-side AI counsel endpoints for the Kingshot Planner tactical toolkit. All endpoints accept JSON and return JSON; they are public, unauthenticated, and rate-limited by Cloudflare Pages default quotas. Game data follows community guides through the Gen 8 hero release.",
    "contact": { "name": "Adlord Gaming", "url": "https://kingshotplanner.com" },
    "license": { "name": "Free to use", "url": "https://kingshotplanner.com" }
  },
  "servers": [{ "url": "https://kingshotplanner.com" }],
  "paths": {
    "/api/rally": {
      "post": {
        "operationId": "analyzeRally",
        "summary": "Bear Trap formation advice",
        "description": "Given the player's troop pool, squad capacities, buff state and per-troop ATK research, returns a recommended main-rally and join-march percentage split (each triple sums to 100) plus notes. Optionally accepts a base64 troop-screen screenshot for vision analysis.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["params"],
                "properties": {
                  "params": {
                    "type": "object",
                    "properties": {
                      "mainCap": { "type": "number", "description": "Effective main squad capacity after buffs" },
                      "joinQueue": { "type": "integer", "description": "Number of join marches to plan" },
                      "joinCap": { "type": "number", "description": "Troops per join march" },
                      "infantry": { "type": "number" },
                      "cavalry": { "type": "number" },
                      "archer": { "type": "number" },
                      "archerAtk": { "type": "number", "description": "Archer ATK% from research and gear" },
                      "cavalryAtk": { "type": "number" },
                      "infantryAtk": { "type": "number" },
                      "savageLevel": { "type": "integer" },
                      "roarLevel": { "type": "integer" },
                      "pantherBonus": { "type": "number", "description": "Lethality % buff from Gen 5 pet" },
                      "deployBonusPct": { "type": "number" }
                    }
                  },
                  "imageBase64": { "type": ["string", "null"], "description": "Optional data-URL or base64 PNG screenshot" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tactical analysis",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "summary": { "type": "string" },
                    "tips": { "type": "array", "items": { "type": "string" } },
                    "override": {
                      "type": ["object", "null"],
                      "properties": {
                        "mainPct": { "$ref": "#/components/schemas/split" },
                        "joinPct": { "$ref": "#/components/schemas/split" }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "502": { "$ref": "#/components/responses/UpstreamError" }
        }
      }
    },
    "/api/charms": {
      "post": {
        "operationId": "counselCharms",
        "summary": "Charm upgrade second opinion",
        "description": "Given the 18 charm levels, held Guides and Designs, build profile and the greedy upgrade plan, returns priorities and farming advice.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "charms": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "troop": { "type": "string", "enum": ["infantry", "cavalry", "archer"] }, "level": { "type": "integer", "minimum": 0, "maximum": 22 } } } },
                  "guides": { "type": "integer" },
                  "designs": { "type": "integer" },
                  "profile": { "type": "string", "enum": ["pve", "bear", "pvp", "even"] },
                  "plan": { "type": "array", "items": { "type": "object" } }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Counsel result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/counsel" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "502": { "$ref": "#/components/responses/UpstreamError" }
        }
      }
    },
    "/api/govgear": {
      "post": {
        "operationId": "counselGear",
        "summary": "Governor gear upgrade second opinion",
        "description": "Given the 6 gear pieces' current steps, held Satin, Gilded and Vision materials, build profile and the greedy plan, returns set-bonus-aware priorities.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "gear": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "troop": { "type": "string" }, "step": { "type": "string" } } } },
                  "satin": { "type": "integer" },
                  "gilded": { "type": "integer" },
                  "vision": { "type": "integer" },
                  "profile": { "type": "string", "enum": ["balanced", "lead", "pvp", "even"] },
                  "plan": { "type": "array", "items": { "type": "object" } }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Counsel result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/counsel" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "502": { "$ref": "#/components/responses/UpstreamError" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "split": {
        "type": "object",
        "description": "Percentage shares of one march; always sums to 100",
        "properties": {
          "infantry": { "type": "integer", "minimum": 0, "maximum": 100 },
          "cavalry": { "type": "integer", "minimum": 0, "maximum": 100 },
          "archer": { "type": "integer", "minimum": 0, "maximum": 100 }
        }
      },
      "counsel": {
        "type": "object",
        "properties": {
          "summary": { "type": "string" },
          "priorities": { "type": "array", "items": { "type": "string" } },
          "farm": { "type": "array", "items": { "type": "string" } },
          "tips": { "type": "array", "items": { "type": "string" } }
        }
      }
    },
    "responses": {
      "BadRequest": { "description": "Invalid or missing fields", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } },
      "UpstreamError": { "description": "AI model unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }
    }
  }
}