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.
X-Language headerX-Cacheable: falseEnable bearer token authentication in your config.php:
return [
'headless' => [
'token' => 'your-secret-token'
],
'kql' => [
'auth' => 'bearer'
]
];
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();
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,
},
}),
});
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 },
}),
});