Kiroku API documentation

The HTTP surface of the Kiroku backend — what it is and how to call it.

This is a first-party, internal API. It exists to serve the Kiroku app and Kiroku's own tooling. There is no third-party API key program, onboarding flow, or rate card — authentication is a Firebase ID token belonging to a real Kiroku user. These pages document the API for Kiroku developers and the curious.

What this API is

A single Firebase Cloud Functions v2 HTTPS function running an Express app under /v1/*, Cloud Run–backed, Node 20, region europe-west1.

It is a migration layer. The Kiroku mobile app historically wrote to Firebase Realtime Database directly; this API exists so that, action by action, the app can call an endpoint instead — and the endpoint returns the same onyxData shape the client already knows how to apply to its local store. Offline-critical writes (logging a drinking session on a plane) deliberately stay client-side; cross-user authority, global-index consistency, aggregation, and security/billing concerns move server-side.

Base URLs & environments

Every route is versioned under /v1.

Environment	Base URL
Production	`https://api.kiroku.cz`
Development	`https://api-dev.kiroku.cz`

GET /v1/healthz needs no auth and self-reports build provenance (commit, environment, build time), so you can always confirm which build an environment is running: try it on this host.

The docs

Getting started — a guided first run: base URLs, getting a Firebase ID token, your first calls, and how to read the response.
Conventions — the cross-cutting contract: the auth model, the response envelope, the error model, and the 407 reauthentication pattern.
Reference — the endpoint inventory, grouped by router.

Source of truth

These pages are the published adaptation of the markdown documentation in the (private) kiroku-api repository (docs/api/); the repository remains the source of truth. Where these pages and the code disagree, the code and its tests win.