johannschopplich / kirby-headless

8.1.0 2026-08-07 07:00 UTC

Requires

• php: >=8.2
• getkirby/composer-installer: ^1

Requires (Dev)

• getkirby/cms: ^5
• getkirby/kql: ^3
• phpunit/phpunit: ^12

MIT

• Johann Schopplich

• headless
• kirby

Published on Packagist.org on 2026-08-07 07:00 UTC

README

Kirby Headless

Kirby Headless is a plugin for Kirby CMS that adds bearer-authenticated KQL, UUID resolution in blocks and layouts, JSON templates, and an Express-style API builder – keep editing in Kirby and serve the result to whatever frontend you prefer.

Note

Want a ready-to-use headless-only project? Start from the Kirby Headless Starter.

When to Use

I want to…	Use
Query content from a frontend over HTTP	KQL endpoint at /api/kql
Lock the API behind a token instead of basic auth	kql.auth => 'bearer' + headless.token
Resolve UUIDs in blocks and layouts to real objects	$field->toResolvedBlocks()
Resolve permalinks in writer and text fields	$field->resolvePermalinks()
Return JSON straight from a template	JSON templates / __template__ endpoint
Compose custom, authenticated API routes	Api::createHandler() + middlewares
Build navigation and language switchers in the frontend	page methods (frontendUrl(), i18nMeta(), …)

Features

• 🔑 Bearer Token Authentication: Protect /api/kql and your own API routes with a bearer token, or fall back to Kirby's native API authentication – see authentication.
• 🧱 Block & Layout Resolution: UUIDs in blocks and layouts resolved to file and page objects server-side, with configurable fields and custom resolvers – see field methods.
• ⚡️ Enhanced KQL: A drop-in /api/kql endpoint with bearer authentication, response caching, and multi-language support via a request header; needs getkirby/kql installed – see KQL.
• 🗂 JSON Templates: Return JSON from templates instead of HTML, with built-in __template__ and __sitemap__ endpoints, or serve every page as JSON through one catch-all route – see JSON templates.
• 🍢 API Builder: Compose routes from middleware chains, Express-style, and reuse bearer auth, file and page resolution, or your own validators – see API builder.
• 🧭 Page Methods: Frontend URLs, breadcrumb data, and multi-language metadata for navigation and language switchers – see page methods.

Requirements

• Kirby 5

Note

Using Kirby 4? Install the v4 release.

Installation

Composer (Recommended)

composer require johannschopplich/kirby-headless

Manual Installation

Download and copy this repository to /site/plugins/kirby-headless.

Documentation

For installation, configuration, and usage, see the Kirby Headless documentation.

License

MIT License © 2022-PRESENT Johann Schopplich