Welcome to the Ret2Shell API reference.

This guide records HTTP / WebSocket interfaces, field conventions, middleware behavior, and error semantics. If you want to contribute code to Ret2Shell or build third-party integrations around it, this is the route-level entry index to start from.

Code contributions are always welcome. The goal is to keep evolving Ret2Shell into a stronger training and competition platform together.

The author is also fine with other platform developers learning from the architecture and implementation ideas here, and is happy to communicate openly.

As an open-source project, the hope is that this work can push technology forward in any form instead of being trapped in a closed, defensive market mindset.

Even with that open attitude, please still respect the project license and its additional terms when you copy code / distill code with AI. Architecture ideas themselves are not restricted in the same way.

For shell resale / tender abuse, violations of the GPL-3.0-derived open-source license, paid gates at the product entry, refusal to publish required source, and similar behavior, we reserve every right to pursue the matter.

Conventions

• Every path is shown with the ${API_BASE} prefix, which comes from SERVER_CONFIG.api_base_path and is commonly /api.
• The backend router tree does not expose a separate /v1 namespace; compatibility follows the Ret2Shell release line itself.
• Every endpoint card always shows method, uri, optional query / body, response, and errors, plus explicit authentication and data-loading behavior.

Middleware

Auth And Permissions

Public

No login is required; any deeper gate is enforced inside the handler.

Guest-aware

The route itself is open, but caller identity still changes filtering and desensitization.

Basic

A logged-in user is required.

Verified

The caller must be logged in and already email-verified.

Basic + Verified

Both the login and email-verification checks must pass.

Permission::User

Requires platform-level user-management permission.

Permission::Bulletin

Requires bulletin-management permission.

Permission::Calendar

Requires calendar-management permission.

Permission::Wiki

Requires Wiki-management permission.

Permission::Game

Requires game-management permission for protected resources such as registries.

Permission::Host

Requires the ability to create and manage games.

Permission::DevOps

Requires platform operations permission.

Permission::Statistics

Requires platform statistics and log access permission.

Statistics | DevOps

Either Permission::Statistics or Permission::DevOps is accepted.

Institute Token

The effective identity comes from the raw original bearer token, not from a normal user session.

game_access_required

After the game is loaded, the caller must be allowed to enter the game context.

challenge_access_required

Adds challenge visibility, release, and team-state checks on top of game access.

game_admin_required

The caller must hold Permission::Game and also be listed as an admin of that game.

Internal Hook Auth

The request must come from localhost and match one-time session and auth cache entries.

Data Preparation

prepare_user_info

Loads the current token owner into the request context for direct handler use.

prepare_data!(institute)

Loads the institute entity from the path parameter and records it in tracing context.

prepare_data!(user)

Loads the target user entity from the path parameter and records it in tracing context.

prepare_data!(game)

Loads the game entity from the path parameter and records it in tracing context.

prepare_team_info

Resolves the current caller team context inside the game; the result may be empty.

prepare_data!(challenge)

Loads the challenge entity from the path parameter and records it in tracing context.

prepare_data!(team)

Loads the target team entity from the path parameter and records it in tracing context.

prepare_data!(notification)

Loads the notification entity from the path parameter and records it in tracing context.

prepare_data!(audit)

Loads the audit entity from the path parameter and records it in tracing context.

How To Read This Reference

• Start from the doc tree on the left, then drill into the endpoint cards for query, body, and response details.
• When a route returns a stream, a proxied upstream response, or a WebSocket upgrade, the Response section marks that return type directly.
• Pages such as account, cluster, and game stay grouped by the source modules in routes, so you can jump between the code and the docs without remapping the structure in your head.