---

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-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

Copy{
  "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)