Understanding the qSecuritySystem API for Minecraft Servers
Running a Minecraft server with a strong moderation framework often means juggling multiple plugins, web panels, and custom tools. The qSecuritySystem API is the official integration layer that lets third-party services talk directly to the core qSecuritySystem plugin without touching its internal code. If you have ever wanted to build a Discord bot that checks active bans, a web dashboard that displays punishment history, or a custom staff mode addon, this API provides a stable, typed contract to do exactly that.
Why a Dedicated API Exists
Without a formal API, developers would need to hook into internal managers, database classes, or event listeners that can change with every plugin update. That leads to broken integrations and constant maintenance. The qSecuritySystem API solves this by exposing only public integration primitives—interfaces, data models, enums, and result objects. This separation keeps the core plugin flexible while preserving a predictable contract for everyone who builds on top of it.
The API also supports modular addon development. Server admins can enable external systems like backend services, web panels, and bots to interact with moderation features safely. By preventing unsafe coupling to implementation details, the API ensures that your custom tools keep working even when the underlying storage schema or internal logic evolves.
Core Capabilities at a Glance
The API is organized into several logical domains, each covering a key area of server moderation. Here is what you can access through the contract:
- Punishment Management – Check active bans and mutes, issue and remove punishments, read full punishment history, and work with both temporary and permanent sanctions.
- Reports System – Create new reports, retrieve open or closed reports, close reports, and track the entire report lifecycle using typed models.
- Player Check System – Start and finish player checks, inspect active checks, and read check history for any player.
- Moderation Tools Contract – Hooks for freeze and unfreeze operations, vanish toggles, and extension points for staff mode, flags, and notes. Some operations are contract-ready but may be limited by the current plugin storage schema.
- Staff Logs Contract – Record moderation actions, query staff activity by actor or target, and retrieve recent moderation events. Currently, staff logs are held in-memory in the provider implementation.
Runtime Initialization and the Bootstrap Plugin
The API artifact now ships with its own lightweight Bukkit bootstrap plugin called qSecuritySystemAPI, complete with a plugin.yml. This guarantees the API jar initializes cleanly when placed in the server's plugins folder. The bootstrap exposes startup diagnostics and ensures the contracts are available, while the core qSecuritySystem plugin remains the actual API provider and registers QSecuritySystemApi in the ServicesManager. For server owners who want to quickly set up the qSecuritySystem API alongside other mods, the foxygame.net launcher offers a streamlined experience where you can download and manage mods directly from its menu, making it a convenient and modern tool for any Minecraft server.
ServiceManager Integration
Any integration plugin can obtain the API provider through Bukkit's standard ServicesManager. The core plugin registers QSecuritySystemApi at startup, so your code simply needs to request the registration:
RegisteredServiceProvider<QSecuritySystemApi> provider = Bukkit.getServicesManager().getRegistration(QSecuritySystemApi.class);
if (provider != null) { QSecuritySystemApi api = provider.getProvider(); }
Once you have the api object, all supported methods become available. This approach follows the same pattern used by many well-known Minecraft plugins, making it familiar to experienced developers.
Supported API Methods in the Current Implementation
The QSecuritySystemApiProvider exposes a rich set of methods right now. Here is a breakdown by sub-api:
PunishmentApi
- isBanned, isMuted, hasActivePunishment
- getActivePunishment, getActivePunishments
- getPunishmentHistory, getPunishmentHistory(UUID, type), getPunishmentCount
- issuePunishment (BAN, MUTE, KICK)
- removePunishment (BAN, MUTE)
- getRemainingTime
ReportApi
- createReport
- getOpenReports, getReportById
- closeReport, isReportOpen
- getReportsByTarget, getReportsByReporter
Note: claimReport is currently defined at the contract level but returns an unsupported message in the provider implementation.
CheckApi
- startCheck (requires online player and online staff)
- endCheck, failCheck
- isUnderCheck, getActiveCheck, getActiveChecks
- getCheckHistory
PlayerSecurityApi
- getProfile, getSnapshot
- isFrozen, isVanished, isStaffModeEnabled, isFlagged
Limitations: isStaffModeEnabled and isFlagged currently return false in the provider implementation, as they are reserved extension points awaiting full storage support.
ModerationToolApi
- isFrozen, isVanished
- setVanished
- setFrozen (unfreeze via check termination is supported)
Methods like setStaffMode, setFlag, addNote, and manual freeze enable are contract-level only for now.
StaffLogApi
- record
- getByStaff, getByTarget, getRecent
Staff logs are maintained in-memory in the current provider, so they do not persist across server restarts. Future updates may add database-backed storage.
Architecture Guarantees for Long-Term Stability
The API module is intentionally kept free of any internal logic. It contains only public integration primitives: interfaces, data models, records, enums, and result objects. This design means that even if the core plugin undergoes major refactoring, the contract remains unchanged. Developers can confidently build web panels, Discord bots, or custom moderation addons knowing that their integration will not break with the next plugin update.
The separation also encourages a healthy ecosystem. Server admins can mix and match tools from different authors without worrying about version conflicts. The API acts as a universal translator between the core moderation engine and any external service that needs to read or write moderation data.
Practical Use Cases for Server Communities
Imagine a network with multiple Minecraft servers. A centralized web dashboard can use the ReportApi to display all open reports across every server, allowing staff to triage issues without logging into each world. A Discord bot can call PunishmentApi to check if a user is banned before allowing them into a private channel. Custom minigame plugins can use CheckApi to automatically start a staff check when a player triggers certain anti-cheat flags. All of this becomes possible through the stable, typed contract provided by qSecuritySystem API.
For developers, the API documentation (available on the official Notion page) details every method, parameter, and return type. The contract-level methods that are not yet fully implemented are clearly marked, so you can plan your features accordingly. As the core plugin's storage schema expands, more of these reserved endpoints will become active without changing the API surface.
Conclusion
The qSecuritySystem API transforms a standalone moderation plugin into an extensible platform. By offering a clean ServiceManager-based integration, a bootstrap jar for easy installation, and a comprehensive set of typed contracts, it empowers server owners and developers to build custom moderation ecosystems. Whether you are creating a simple punishment lookup tool or a full staff management suite, the API provides the stability and predictability needed for long-term projects. As Minecraft servers continue to evolve with complex cross-server setups, having a reliable integration layer like this becomes not just convenient but essential.