kirby-headless-api

bnomei's avatarfrom bnomei

Exposes Kirby content to headless clients using the API, KQL, and JSON representations. Use when building API endpoints, KQL queries, or headless frontends.

⭐17stars🔀0forks📁View on GitHub🕐Updated Jan 10, 2026

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.
namekirby-headless-api
descriptionExposes 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-kql
  • kirby://kb/scenarios/02-json-content-representation-ajax-load-more
  • kirby://kb/scenarios/45-headless-kiosk-application
  • kirby://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 .json representations 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-Control with 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

  1. Clarify consumers, authentication, and which content is public vs private.
  2. Call kirby:kirby_init and read kirby://config/api to confirm API settings.
  3. Check plugin availability for KQL: kirby:kirby_plugins_index.
  4. If you need custom endpoints, inspect existing routes with kirby:kirby_routes_index (install runtime if needed).
  5. Search the KB with kirby:kirby_search (examples: "headless api with kql", "json content representation", "figma auto populate", "headless kiosk").
  6. Use kirby:kirby_online to fetch official API/KQL docs when KB coverage is insufficient.
  7. Implement:
    • enable API auth (api.basicAuth) when required
    • create or update KQL queries for /api/query
    • add .json representations for template-backed JSON
  8. Verify:
    • request /api/query with Basic Auth
    • render .json representations with kirby:kirby_render_page(contentType: json)