static/openapi.json

{
  "openapi": "3.0.3",
  "info": {
    "title": "Football Prediction API",
    "description": "Complete football prediction system with ML ensemble, advanced features, live odds, and more.",
    "version": "2.0.0",
    "contact": {
      "name": "API Support"
    }
  },
  "servers": [
    {"url": "http://localhost:5000", "description": "Local development"},
    {"url": "https://your-app.koyeb.app", "description": "Production"}
  ],
  "tags": [
    {"name": "Predictions", "description": "Match predictions"},
    {"name": "Live", "description": "Live data and odds"},
    {"name": "ML", "description": "Machine Learning models"},
    {"name": "Training", "description": "Model training and tuning"},
    {"name": "Analytics", "description": "Accuracy and analytics"}
  ],
  "paths": {
    "/api/v2/predict": {
      "get": {
        "tags": ["Predictions"],
        "summary": "Enhanced prediction with all features",
        "parameters": [
          {"name": "home", "in": "query", "required": true, "schema": {"type": "string"}, "example": "Germany"},
          {"name": "away", "in": "query", "required": true, "schema": {"type": "string"}, "example": "France"}
        ],
        "responses": {
          "200": {
            "description": "Prediction result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {"type": "boolean"},
                    "final_prediction": {
                      "type": "object",
                      "properties": {
                        "home_win_prob": {"type": "number"},
                        "draw_prob": {"type": "number"},
                        "away_win_prob": {"type": "number"},
                        "predicted_outcome": {"type": "string"},
                        "confidence": {"type": "number"}
                      }
                    },
                    "goals": {
                      "type": "object",
                      "properties": {
                        "home_xg": {"type": "number"},
                        "away_xg": {"type": "number"},
                        "over_2.5": {"type": "number"},
                        "btts": {"type": "number"}
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/form/{team}": {
      "get": {
        "tags": ["Predictions"],
        "summary": "Get team's recent form",
        "parameters": [
          {"name": "team", "in": "path", "required": true, "schema": {"type": "string"}}
        ],
        "responses": {
          "200": {"description": "Team form data"}
        }
      }
    },
    "/api/h2h": {
      "get": {
        "tags": ["Predictions"],
        "summary": "Head-to-head statistics",
        "parameters": [
          {"name": "team1", "in": "query", "required": true, "schema": {"type": "string"}},
          {"name": "team2", "in": "query", "required": true, "schema": {"type": "string"}}
        ],
        "responses": {
          "200": {"description": "H2H stats"}
        }
      }
    },
    "/api/live-odds": {
      "get": {
        "tags": ["Live"],
        "summary": "Get live odds from multiple bookmakers",
        "parameters": [
          {"name": "sport", "in": "query", "schema": {"type": "string", "default": "soccer_epl"}}
        ],
        "responses": {
          "200": {"description": "Odds comparison data"}
        }
      }
    },
    "/api/live-scores": {
      "get": {
        "tags": ["Live"],
        "summary": "Get live match scores",
        "responses": {
          "200": {"description": "Live matches"}
        }
      }
    },
    "/api/training/start": {
      "post": {
        "tags": ["Training"],
        "summary": "Start model retraining",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "async": {"type": "boolean", "default": true},
                  "params": {"type": "object"}
                }
              }
            }
          }
        },
        "responses": {
          "200": {"description": "Training started"}
        }
      }
    },
    "/api/training/status": {
      "get": {
        "tags": ["Training"],
        "summary": "Get training status",
        "responses": {
          "200": {"description": "Training status"}
        }
      }
    },
    "/api/tuning/set": {
      "post": {
        "tags": ["Training"],
        "summary": "Set hyperparameters",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "model": {"type": "string", "enum": ["xgb", "lgb", "cat", "nn"]},
                  "params": {"type": "object"}
                }
              }
            }
          }
        },
        "responses": {
          "200": {"description": "Hyperparameters updated"}
        }
      }
    },
    "/api/accuracy/stats": {
      "get": {
        "tags": ["Analytics"],
        "summary": "Get accuracy statistics",
        "parameters": [
          {"name": "period", "in": "query", "schema": {"type": "string", "enum": ["today", "week", "month", "all"]}}
        ],
        "responses": {
          "200": {"description": "Accuracy stats"}
        }
      }
    },
    "/api/backtest/run": {
      "post": {
        "tags": ["Analytics"],
        "summary": "Run historical backtest",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "start_year": {"type": "integer", "default": 2020},
                  "end_year": {"type": "integer", "default": 2024}
                }
              }
            }
          }
        },
        "responses": {
          "200": {"description": "Backtest results"}
        }
      }
    }
  }
}