Skip to main content
The whole Headless API is documented with an OpenAPI 3 definition. It stays current with the API: whatever your site’s version supports is what the document describes.

Where to find it

All of these addresses are public (no key or license needed) and relative to your site: You can also reach these links in the admin panel under Settings → Headless API → Developer Resources.
To use these addresses the Headless API must be on in the panel.

Using the interactive docs

Open /headless/docs:
1

Browse endpoints

The left menu lists the groups (Site, Auth, Store, Cart, Forum…). Use search to find an endpoint.
2

Read the details

Each endpoint shows its parameters, request body, success response schemas, possible error codes, captcha requirement and the authentication it needs.
3

Try it

Send a request with Test Request. In the authentication section enter your pk_live_... key (publicKey) and, if needed, the token from the login response (bearerAuth).
4

Get a code sample

The right panel offers ready-made request samples in cURL, JavaScript, PHP, Python and more.
If you hit a CORS error while testing from the browser, use the docs on your site’s own address (https://your-site.com is always allowed) or temporarily add the origin during development.

Structure of the definition

  • Server: {siteUrl}/headless/v1 (your site address as a variable).
  • Security schemes:
    • publicKey: the X-LeaderOS-Key header
    • bearerAuth: Authorization: Bearer <token>
  • Tags (groups): Site, Auth, Account, Store, Cart, Payments, Credits, Chest, Forum, Support, Blog, Help and more.
  • Every operation has a unique operationId (e.g. listBlogPosts), x-error-codes (possible error codes) and, where needed, x-captcha (which captcha page).

What can you do with OpenAPI?

Generate types (TypeScript)

The official SDK already includes types; use this if you write your own client.

Generate clients (other languages)

Generate a client for PHP, Python, Kotlin, Swift, C# and more with OpenAPI Generator:

Postman / Insomnia / Bruno

Import the openapi.json URL to get every endpoint as a collection. Fill in siteUrl and the key in the collection variables.

AI

Give the URL to an assistant or let it read automatically through the MCP server (see MCP).

Importing into Postman

  1. Choose Import → Link and enter https://your-site.com/headless/openapi.json.
  2. In the collection Variables, set siteUrl = https://your-site.com.
  3. On the collection’s Authorization tab choose API Key: key X-LeaderOS-Key, value pk_live_..., add to Header.
  4. For login-protected requests, add the token from the POST /auth/login response as a Bearer Token.

Language and content headers

You can also use these headers while testing: Upload endpoints (avatar, support attachments and so on) accept multipart/form-data.

Versions and changes

OpenAPI info.version shows the API version. When you upgrade your site with a LeaderOS update, openapi.json updates automatically; you only need to regenerate your client types (with the official SDK, npm update @leaderos/headless-sdk).