{
  "openapi": "3.1.0",
  "info": {
    "title": "Z+ Security API",
    "version": "1.0.0",
    "description": "Public and authenticated API for the Z+ Security Discord bot dashboard. Provides bot statistics, command catalogs, team info, support tickets, and full server management for authenticated users.",
    "contact": {
      "name": "Z+ Security Support",
      "url": "https://discord.gg/HbNjZyNmyH"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://www.handry.site",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/public/stats": {
      "get": {
        "operationId": "getPublicStats",
        "summary": "Get live bot statistics",
        "description": "Returns real-time bot statistics including server count, total users across all servers, shard count, and API latency in milliseconds.",
        "tags": ["Public"],
        "responses": {
          "200": {
            "description": "Live statistics",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["success", "stats", "servers", "users", "shards", "ping"],
                  "properties": {
                    "success": { "type": "boolean", "const": true },
                    "stats": {
                      "type": "object",
                      "properties": {
                        "servers": { "type": "integer", "description": "Number of Discord servers the bot is in" },
                        "users": { "type": "integer", "description": "Total users across all servers" },
                        "shards": { "type": "integer", "description": "Number of bot shards" },
                        "ping": { "type": "integer", "description": "Database round-trip latency in milliseconds" }
                      }
                    },
                    "servers": { "type": "integer" },
                    "users": { "type": "integer" },
                    "shards": { "type": "integer" },
                    "ping": { "type": "integer" },
                    "latency": { "type": "integer" }
                  }
                }
              }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/api/commands": {
      "get": {
        "operationId": "listCommands",
        "summary": "List all bot commands",
        "description": "Returns the full catalog of bot commands with names, descriptions, categories (antinuke, moderation, automod, welcome, leveling, giveaway, utility), command types, and aliases.",
        "tags": ["Public"],
        "responses": {
          "200": {
            "description": "Command catalog",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["success", "commands"],
                  "properties": {
                    "success": { "type": "boolean", "const": true },
                    "commands": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Command" }
                    }
                  }
                }
              }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/api/bots": {
      "get": {
        "operationId": "listBots",
        "summary": "List bot instances",
        "description": "Returns all registered bot instances managed by Z+ Security.",
        "tags": ["Public"],
        "responses": {
          "200": {
            "description": "Bot listing",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["success", "bots"],
                  "properties": {
                    "success": { "type": "boolean", "const": true },
                    "bots": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string" },
                          "name": { "type": "string" },
                          "avatar": { "type": "string" }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/api/team": {
      "get": {
        "operationId": "listTeam",
        "summary": "List team members",
        "description": "Returns the Z+ Security team members with their roles and profiles.",
        "tags": ["Public"],
        "responses": {
          "200": {
            "description": "Team listing",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["success", "team"],
                  "properties": {
                    "success": { "type": "boolean", "const": true },
                    "team": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": { "type": "string" },
                          "role": { "type": "string" },
                          "avatar": { "type": "string" },
                          "discord_id": { "type": "string" }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/api/invite-url": {
      "get": {
        "operationId": "getInviteUrl",
        "summary": "Get bot invite URL",
        "description": "Returns the Discord OAuth2 authorization URL to invite Z+ Security to a server with the required permissions.",
        "tags": ["Public"],
        "responses": {
          "200": {
            "description": "Invite URL",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["success", "url"],
                  "properties": {
                    "success": { "type": "boolean", "const": true },
                    "url": { "type": "string", "format": "uri", "description": "Discord OAuth2 bot invite URL" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/api/tickets": {
      "post": {
        "operationId": "createTicket",
        "summary": "Create a support ticket",
        "description": "Submit a support ticket to the Z+ Security team. Authentication is optional — anonymous tickets are accepted with a guest name.",
        "tags": ["Support"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["subject", "message"],
                "properties": {
                  "subject": { "type": "string", "description": "Ticket subject line", "minLength": 1 },
                  "message": { "type": "string", "description": "Detailed description of the issue", "minLength": 1 },
                  "guild_id": { "type": "string", "description": "Discord guild ID if relevant" },
                  "name": { "type": "string", "description": "Your name or Discord username" },
                  "email": { "type": "string", "format": "email", "description": "Contact email (optional)" }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Ticket created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["success", "ticket"],
                  "properties": {
                    "success": { "type": "boolean", "const": true },
                    "ticket": {
                      "type": "object",
                      "properties": {
                        "uuid": { "type": "string", "format": "uuid" },
                        "subject": { "type": "string" },
                        "status": { "type": "string", "enum": ["open", "in_progress", "resolved", "closed"] }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/api/@me": {
      "get": {
        "operationId": "getCurrentUser",
        "summary": "Get current user profile",
        "description": "Returns the Discord profile of the currently authenticated user. Requires an active Discord OAuth2 session.",
        "tags": ["Authenticated"],
        "security": [{ "discordOAuth": [] }],
        "responses": {
          "200": {
            "description": "User profile",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["success"],
                  "properties": {
                    "success": { "type": "boolean", "const": true },
                    "id": { "type": "string" },
                    "name": { "type": "string" },
                    "avatar": { "type": "string" },
                    "discriminator": { "type": "string" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/api/@me/guilds": {
      "get": {
        "operationId": "listUserGuilds",
        "summary": "List user's manageable guilds",
        "description": "Returns Discord guilds the authenticated user can manage, indicating which ones have Z+ Security installed.",
        "tags": ["Authenticated"],
        "security": [{ "discordOAuth": [] }],
        "responses": {
          "200": {
            "description": "Guild list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["success", "guilds"],
                  "properties": {
                    "success": { "type": "boolean", "const": true },
                    "guilds": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": ["id", "name", "installed"],
                        "properties": {
                          "id": { "type": "string" },
                          "name": { "type": "string" },
                          "installed": { "type": "boolean", "description": "Whether Z+ Security is installed in this guild" },
                          "owner": { "type": "boolean" },
                          "icon": { "type": "string" },
                          "role": { "type": "string" }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "discordOAuth": {
        "type": "http",
        "scheme": "cookie",
        "description": "Discord OAuth2 session cookie. Start a session by navigating to GET /api/login in your browser."
      }
    },
    "schemas": {
      "Command": {
        "type": "object",
        "required": ["name", "description", "category", "type"],
        "properties": {
          "name": { "type": "string", "description": "Command name including subcommands (e.g. 'antinuke enable')" },
          "description": { "type": "string", "description": "What the command does" },
          "category": {
            "type": "string",
            "enum": ["antinuke", "moderation", "automod", "welcome", "leveling", "giveaway", "utility"],
            "description": "Functional category"
          },
          "type": { "type": "string", "enum": ["prefix", "slash"], "description": "Command invocation type" },
          "aliases": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Alternative names for this command"
          }
        }
      },
      "ApiError": {
        "type": "object",
        "required": ["success", "error"],
        "properties": {
          "success": { "type": "boolean", "const": false },
          "error": { "type": "string", "description": "Human-readable error message with resolution hints" }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid input — check the error message for details",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ApiError" }
          }
        }
      },
      "Unauthorized": {
        "description": "Discord session not available — navigate to GET /api/login to authenticate",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ApiError" }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit exceeded — check Retry-After header",
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait before retrying",
            "schema": { "type": "integer" }
          },
          "RateLimit-Limit": {
            "description": "Maximum requests allowed in the current window",
            "schema": { "type": "integer" }
          },
          "RateLimit-Remaining": {
            "description": "Requests remaining in the current window",
            "schema": { "type": "integer" }
          },
          "RateLimit-Reset": {
            "description": "Unix timestamp when the rate limit window resets",
            "schema": { "type": "integer" }
          }
        },
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ApiError" }
          }
        }
      },
      "InternalError": {
        "description": "Server error — the Z+ service is temporarily unavailable",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ApiError" }
          }
        }
      }
    }
  },
  "tags": [
    { "name": "Public", "description": "Endpoints that require no authentication" },
    { "name": "Support", "description": "Support ticket submission" },
    { "name": "Authenticated", "description": "Endpoints requiring Discord OAuth2 session" }
  ]
}