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