kirby-headless-api
Exposes Kirby content to headless clients using the API, KQL, and JSON representations. Use when building API endpoints, KQL queries, or headless frontends.
When & Why to Use This Skill
This Claude skill streamlines the development of headless architectures using Kirby CMS. It enables developers to efficiently expose content via REST APIs, Kirby Query Language (KQL), and JSON representations, facilitating seamless integration with modern frontend frameworks, mobile apps, and external data consumers while ensuring security and performance through optimized caching and authentication workflows.
Use Cases
- Case 1: Building headless frontends (e.g., React, Vue, or Next.js) by exposing Kirby CMS content through structured JSON representations.
- Case 2: Executing complex, cross-collection data queries using Kirby Query Language (KQL) to fetch specific filtered datasets for dynamic web applications.
- Case 3: Developing specialized endpoints for external integrations, such as kiosk applications or auto-populating design tools like Figma with live CMS data.
- Case 4: Implementing secure API authentication and custom routing to manage public versus private content boundaries in a decoupled environment.
| name | kirby-headless-api |
|---|---|
| description | Exposes Kirby content to headless clients using the API, KQL, and JSON representations. Use when building API endpoints, KQL queries, or headless frontends. |
Kirby Headless API
KB entry points
kirby://kb/scenarios/44-headless-api-with-kqlkirby://kb/scenarios/02-json-content-representation-ajax-load-morekirby://kb/scenarios/45-headless-kiosk-applicationkirby://kb/scenarios/28-figma-auto-populate
Required inputs
- Consumers and auth requirements.
- Public vs private content boundaries.
- Response shape and caching policy.
- Preferred approach (KQL, representations, or routes).
Default delivery choices
- Use
.jsonrepresentations for page-backed responses. - Use KQL for cross-collection queries and filtered datasets.
- Use routes for non-page or composite endpoints.
Default response envelope
{
"status": "ok",
"data": {}
}
Caching rule
- Public endpoints: set
Cache-Controlwith a short max-age. - Authenticated endpoints: disable caching.
Common pitfalls
- Exposing private fields or drafts in JSON output.
- Caching authenticated responses.
Verification checklist
- Confirm auth requirements and public/private boundaries.
- Validate JSON output for required fields.
Workflow
- Clarify consumers, authentication, and which content is public vs private.
- Call
kirby:kirby_initand readkirby://config/apito confirm API settings. - Check plugin availability for KQL:
kirby:kirby_plugins_index. - If you need custom endpoints, inspect existing routes with
kirby:kirby_routes_index(install runtime if needed). - Search the KB with
kirby:kirby_search(examples: "headless api with kql", "json content representation", "figma auto populate", "headless kiosk"). - Use
kirby:kirby_onlineto fetch official API/KQL docs when KB coverage is insufficient. - Implement:
- enable API auth (
api.basicAuth) when required - create or update KQL queries for
/api/query - add
.jsonrepresentations for template-backed JSON
- enable API auth (
- Verify:
- request
/api/querywith Basic Auth - render
.jsonrepresentations withkirby:kirby_render_page(contentType: json)
- request