{
  "openapi": "3.0.3",
  "info": {
    "title": "TopSaaS API",
    "description": "Live SaaS & AI Tool Head-to-Head Battle Arena and Elo Leaderboard API.",
    "version": "1.0.0",
    "contact": {
      "name": "TopSaaS",
      "url": "https://www.topsaas.lol"
    }
  },
  "servers": [
    {
      "url": "https://www.topsaas.lol/api",
      "description": "Production Server"
    }
  ],
  "paths": {
    "/rankings": {
      "get": {
        "summary": "Get TSL Software Leaderboard",
        "description": "Retrieve the global Elo software rankings sorted from #1 down, with win rates and battle counts.",
        "operationId": "getRankings",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter rankings by category name (e.g. 'AI Assistant', 'AI Code Editor', 'Productivity', 'Backend & Cloud', 'Design & Web')"
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Search software by name or description keyword"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful retrieval of software rankings",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "rankings": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string" },
                          "name": { "type": "string" },
                          "category": { "type": "string" },
                          "rating": { "type": "integer" },
                          "rank": { "type": "integer" },
                          "wins": { "type": "integer" },
                          "losses": { "type": "integer" },
                          "totalBattles": { "type": "integer" },
                          "winRate": { "type": "integer" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/battles": {
      "get": {
        "summary": "Get Active SaaS Battles",
        "description": "Retrieve all head-to-head SaaS matchups, community vote percentages, and contender data.",
        "operationId": "getBattles",
        "parameters": [
          {
            "name": "slug",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Battle slug (e.g. 'chatgpt-vs-claude', 'cursor-vs-windsurf')"
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter battles by category"
          }
        ],
        "responses": {
          "200": {
            "description": "List of active software battles",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "battles": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string" },
                          "slug": { "type": "string" },
                          "category": { "type": "string" },
                          "question": { "type": "string" },
                          "votesA": { "type": "integer" },
                          "votesB": { "type": "integer" },
                          "totalVotes": { "type": "integer" },
                          "percentA": { "type": "number" },
                          "percentB": { "type": "number" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/create-battle": {
      "post": {
        "summary": "Launch a Custom SaaS Battle",
        "description": "Create a new head-to-head comparison duel by providing two website URLs.",
        "operationId": "createBattle",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["urlA", "urlB"],
                "properties": {
                  "urlA": { "type": "string", "format": "uri" },
                  "urlB": { "type": "string", "format": "uri" },
                  "category": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Battle created successfully"
          }
        }
      }
    }
  }
}