KQL (Kirby Query Language)
Enhanced KQL endpoint with bearer token authentication, caching, and multi-language support.
Kirby Headless provides an enhanced KQL endpoint at /api/kql with bearer token authentication, automatic caching, and multi-language support. This extends the official KQL plugin with features commonly needed in headless setups.
Features
- Bearer Token Authentication: Modern token-based auth instead of basic auth
- Query Response Caching: Automatic caching of query results
- Multi-Language Support: Set language via
X-Languageheader - Cache Control: Disable caching per-request with
X-Cacheable: false
Configuration
Enable bearer token authentication in your config.php:
config.php
return [
'headless' => [
'token' => 'your-secret-token'
],
'kql' => [
'auth' => 'bearer'
]
];
See the Authentication page for detailed setup instructions.
Making Requests
Send KQL queries to /api/kql with the bearer token in the Authorization header:
const response = await fetch("https://example.com/api/kql", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${process.env.KIRBY_API_TOKEN}`,
},
body: JSON.stringify({
query: "site",
select: {
title: true,
children: {
query: "site.children",
select: ["title", "url"],
},
},
}),
});
const data = await response.json();
Multi-Language Support
For multi-language sites, set the language using the X-Language header:
const response = await fetch("https://example.com/api/kql", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KIRBY_API_TOKEN}`,
"X-Language": "de",
},
body: JSON.stringify({
query: "page('home')",
select: {
title: true,
},
}),
});
Cache Control
Query responses are cached automatically. To disable caching for specific requests, use the X-Cacheable header:
const response = await fetch("https://example.com/api/kql", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KIRBY_API_TOKEN}`,
"X-Cacheable": "false",
},
body: JSON.stringify({
query: "site",
select: { title: true },
}),
});
Cached responses are stored using Kirby's page cache. Clear the cache when content changes to ensure fresh data.