> ## Documentation Index
> Fetch the complete documentation index at: https://developer.leaderos.net/llms.txt
> Use this file to discover all available pages before exploring further.

# What is the Headless API?

> An overview of the LeaderOS Headless API: what it is for, how it works and which tools come with it.

## 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.

> [card] Write your own theme
>
> Full control over the design. Build a modern React/Next.js site without being limited to theme files.

> [card] Same business rules
>
> Validation, permissions, bans, maintenance mode, 2FA and e-mail verification behave exactly like the main site.

> [card] AI friendly
>
> OpenAPI, `llms.txt`, an MCP server and a ready-made `AGENTS.md` let an AI assistant build your theme for you.

> [card] Typed SDK
>
> A TypeScript SDK and a React/Next.js package give you autocomplete and type safety for every endpoint.

## How does it work?

```
┌──────────────────────┐        ┌────────────────────────────┐
│  Your frontend       │  JSON  │  LeaderOS website          │
│  (Next.js / React…)  │ ─────► │  https://your-site.com     │
│  on your own VDS     │ ◄───── │  /headless/v1/...          │
└──────────────────────┘        └────────────────────────────┘
        player                    database, payments, game server
```

* 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:

```json theme={null}
{ "success": true, "data": { "...": "..." }, "meta": { "pagination": {}, "seo": {} } }
```

```json theme={null}
{ "success": false, "error": { "code": "VALIDATION_FAILED", "message": "…", "fields": { "email": { "required": "…" } } } }
```

## What does it offer?

| Area | Scope |
| - | - |
| Site | Configuration, menus, translations, redirects, sitemap, home page |
| Identity | Login, registration, password reset, 2FA, e-mail verification, external login providers |
| Account | Profile, avatar, settings, orders, subscriptions, credit history, linked accounts, Discord |
| Commerce | Store, cart, coupons, payments, credit top-up/transfer, chest, gift codes, bazaar, Gaming Night, Fortune Wheel |
| Community | Forum, suggestions, support tickets, applications, forms, help center |
| Content | Blog, pages, downloads, members, leaderboards, punishments, changelog, staff, voting |
| AI | AI replies on support tickets |

There are **more than 160 endpoints**, all listed in the interactive docs (see [OpenAPI](https://developer.leaderos.net/headless/en/openapi.md)).

> [!NOTE]
>
> The Tebex Store module is **not** covered by the Headless API. The Tebex payment gateway (`TebexCheckout`) is supported.

## Ecosystem

> [card] [@leaderos/headless-sdk](https://developer.leaderos.net/headless/en/sdk-and-react.md)
>
> Framework-agnostic TypeScript client.

> [card] [@leaderos/headless-react](https://developer.leaderos.net/headless/en/sdk-and-react.md)
>
> Provider, hooks, `<PoweredBy/>`, Turnstile and Next.js helpers.

> [card] [create-leaderos-theme](https://developer.leaderos.net/headless/en/create-leaderos-theme.md)
>
> A ready Next.js theme project with one command.

> [card] [@leaderos/headless-mcp](https://developer.leaderos.net/headless/en/mcp.md)
>
> MCP server for AI assistants.

> [card] [OpenAPI & llms.txt](https://developer.leaderos.net/headless/en/openapi.md)
>
> Machine-readable API definition.

> [card] [Deployment](https://developer.leaderos.net/headless/en/deployment.md)
>
> Run your theme on your own VDS.

## Important rules

> [!WARNING]
>
> **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`).

> [!WARNING]
>
> 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](https://developer.leaderos.net/headless/en/quickstart.md)

**2. Create a theme**

Set up the ready project with `npm create leaderos-theme@latest` → [create-leaderos-theme](https://developer.leaderos.net/headless/en/create-leaderos-theme.md)

**3. Develop**

By hand or with AI → [Developing with AI](https://developer.leaderos.net/headless/en/ai-development.md)

**4. Publish**

Deploy to your VDS → [Deployment](https://developer.leaderos.net/headless/en/deployment.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.