Headless Mode and API Tokens
In headless mode, Laravix stays your editorial home — content, media, users, settings — while any frontend you like (Nuxt, Next.js, a mobile app) consumes the content over a REST API. This article sets up a headless site, from the mode switch to the first authenticated request.
Theme vs. headless — per site
The mode is a property of each site, so one installation can serve a Blade-rendered marketing site and a headless app side by side. Consequences of headless mode:
- The Blade frontend is off — requests to the site's domain return 404.
- The API tab appears in Settings (replacing Appearance); the visual builder tab and code-registered SEO fields are hidden in the content form.
- Content, media, taxonomies, navigation and settings become available under
/api/v1.
1. Switch the site to headless
When creating a site, choose Mode: Headless (API). For an existing site, a super admin changes the mode in Sites → edit site.
2. Create an API token
- In the admin, open Settings → API.
- Copy the API Base URL shown there —
https://{your-domain}/api/v1. - Click Create Token, give it a name (e.g. "production frontend") and an optional expiry.
- Copy the token from the confirmation dialog. It is shown only once — the database stores only a hash.
Tokens look like lvx_ followed by 40 random characters. The token list shows each token's prefix, last-used time and expiry; Revoke Token deletes one immediately.
Tip: Create one token per consumer (web frontend, mobile app, CI) so you can revoke them independently and see per-token usage.
3. Make a request
Every request needs the token in the Authorization header:
curl https://example.com/api/v1/pages \
-H "Authorization: Bearer lvx_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
Laravix resolves the site from the request's hostname. When your API calls don't go through the site's own domain — local development, a shared API host — send the site's domain explicitly:
curl https://cms.internal/api/v1/pages \
-H "Authorization: Bearer lvx_..." \
-H "X-Site-Domain: example.com"
Error responses
| Status | Meaning |
|---|---|
401 |
Missing, invalid or expired token ({"message": "Missing API token."} etc.) |
403 |
The resolved site is not in headless mode |
404 |
No site matches the hostname / X-Site-Domain, or the content doesn't exist |
422 |
Validation failed (e.g. /search without q) |
429 |
Rate limit exceeded |
Rate limiting
Requests are limited to 120 per minute per token (falling back to per-IP when unauthenticated). Watch the standard X-RateLimit-* headers and back off on 429.
Locales
Content endpoints default to the site's default language. Request another enabled language with the locale query parameter: /api/v1/pages?locale=cs. Unknown locales silently fall back to the default.
Related articles
- API Reference — all endpoints and response shapes
- Architecture and Multi-tenancy