Skip to main content

What is the Headless API?

LeaderOS normally ships with a ready-made theme (for example flat) 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-Key header. Logged-in players also send Authorization: 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

The “Powered by LeaderOS” link is mandatory. By license, the <PoweredBy /> component (or the same link) must stay visible in your frontend. It can only be removed if you hold a branding-removal license (config.branding.canRemove = true).
The LeaderOS site that runs the Headless API must have a valid license. The license is checked on the server per domain; an invalid or expired license returns LICENSE_INVALID / LICENSE_EXPIRED (HTTP 402).

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-theme
3

Develop

By hand or with AI → Developing with AI
4

Publish

Deploy to your VDS → Deployment