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

# OpenAPI Documentation

> How to access the OpenAPI definition and use it for client generation, testing and AI.

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:

| Address | Contents |
| - | - |
| `https://your-site.com/headless/docs` | Interactive docs (Scalar UI, dark theme) |
| `https://your-site.com/headless/openapi.json` | OpenAPI definition (JSON) |
| `https://your-site.com/headless/llms.txt` | Short endpoint index for AI |
| `https://your-site.com/headless/llms-full.txt` | Full detailed reference for AI |

You can also reach these links in the admin panel under **Settings → Headless API → Developer Resources**.

> [!NOTE]
>
> 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.

> [!TIP]
>
> 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?

> [card] Generate types (TypeScript)
>
> ```bash theme={null}
> npx openapi-typescript https://your-site.com/headless/openapi.json -o api.d.ts
> ```
>
> The official SDK already includes types; use this if you write your own client.

> [card] Generate clients (other languages)
>
> Generate a client for PHP, Python, Kotlin, Swift, C# and more with OpenAPI Generator:
>
> ```bash theme={null}
> npx @openapitools/openapi-generator-cli generate \
>   -i https://your-site.com/headless/openapi.json \
>   -g python -o ./leaderos-client
> ```

> [card] 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.

> [card] AI
>
> Give the URL to an assistant or let it read automatically through the MCP server (see [MCP](https://developer.leaderos.net/headless/en/mcp.md)).

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

| Header | Meaning |
| - | - |
| `X-Locale` | Response language (`tr`, `en`…) |
| `X-Currency` | Currency |
| `Content-Type: application/json` | For requests with a JSON body |

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`).


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