https://your-site.com/headless/v1
Authentication
There are two layers:- Public key
- Bearer token
Required on every request (except browser-redirect routes):The
?key=pk_live_... query parameter is accepted as an alternative.Response format
error.code, never on message. Messages are translated and may change; codes are stable.
- Pagination:
?page=2; the result is inmeta.pagination. - Images are returned as absolute URLs.
- Money values are numbers in the base currency; use the
*Formattedfields for text converted to the visitor’s currency.
Account guards (403)
Logged-in accounts that have not completed a step receive these errors. Your frontend should catch them and send the player to the right screen:
All error codes and their meaning appear in each endpoint’s
x-error-codes in OpenAPI and in the MCP list_error_codes tool.
Language and currency
Translation files come from
GET /i18n/{code}. The English text is the key; the SDK and template use it as t('English text').
Captcha (Cloudflare Turnstile)
Thecaptcha field in GET /site/config contains enabled, provider, siteKey and whether each page needs it (pages: login, register, forgot_password, open_ticket, post_thread…). When the page needs it, send the Turnstile token from your form as captchaToken in the body. Failure returns CAPTCHA_FAILED. The <Turnstile page="login" onToken={...} /> component in the React package does this for you and renders nothing when no captcha is needed.
Module and feature checks
Before rendering a feature, checkconfig.modules[slug].active. Endpoints of a disabled module return 404. In React use useModule('forum'), on the server isModuleActive(config, 'forum').
Redirect flows (handoff)
For actions where the browser must go to another site (payment page, Discord or an external provider) the API returns a one-time URL (handoff). In the SDK,leaderos.payments.start(intent) takes the browser there. The URL is valid for 60 seconds and can be used once.
A payment request (PaymentIntent) returns one of these next values:
After payment the player returns to the Payment success / error pages you defined in the panel. A
CONTACT_REQUIRED error means a name/phone is required.
Rate limiting
The Headless API has no built-in rate limit (the main site has none either). On a live site, add rate-limit rules at a service such as Cloudflare for sensitive paths like/headless/v1/auth/*.
License and branding
- The API validates your site’s license on the server (cached for 5 minutes).
- If
config.branding.canRemoveisfalse, the “Powered by LeaderOS” link must be visible in your frontend.
