What is the Headless API?
LeaderOS normally ships with a ready-made theme (for exampleflat) and renders pages on the server with PHP. The Headless API exposes all player-facing features of the same site (login, store, cart, payments, credits, forum, support, blog, voting and more) as a JSON API.
This lets you use LeaderOS as the backend and write the frontend with any technology you like: React, Next.js, Vue, Nuxt, Svelte, a mobile app or any HTTP client.
Write your own theme
Full control over the design. Build a modern React/Next.js site without being limited to theme files.
Same business rules
Validation, permissions, bans, maintenance mode, 2FA and e-mail verification behave exactly like the main site.
AI friendly
OpenAPI,
llms.txt, an MCP server and a ready-made AGENTS.md let an AI assistant build your theme for you.Typed SDK
A TypeScript SDK and a React/Next.js package give you autocomplete and type safety for every endpoint.
How does it work?
- The LeaderOS website keeps running as before: the admin panel, database, payment callbacks and game-server commands all stay there.
- Your frontend sends requests to
https://your-site.com/headless/v1/.... - Every request carries the public key in the
X-LeaderOS-Keyheader. Logged-in players also sendAuthorization: Bearer <token>. - Responses always have the same shape:
What does it offer?
There are more than 160 endpoints, all listed in the interactive docs (see OpenAPI).
The Tebex Store module is not covered by the Headless API. The Tebex payment gateway (
TebexCheckout) is supported.Ecosystem
@leaderos/headless-sdk
Framework-agnostic TypeScript client.
@leaderos/headless-react
Provider, hooks,
<PoweredBy/>, Turnstile and Next.js helpers.create-leaderos-theme
A ready Next.js theme project with one command.
@leaderos/headless-mcp
MCP server for AI assistants.
OpenAPI & llms.txt
Machine-readable API definition.
Deployment
Run your theme on your own VDS.
Important rules
Where to start
1
Enable it
Turn on the Headless API in the admin panel and get the public key → Quickstart
2
Create a theme
Set up the ready project with
npm create leaderos-theme@latest → create-leaderos-theme3
Develop
By hand or with AI → Developing with AI
4
Publish
Deploy to your VDS → Deployment
