Getting started

Prerequisites

• curl and a JSON pretty-printer (jq is used below; optional).
• For an authenticated call: a Firebase ID token for a real Kiroku user in the environment you are targeting (see Get a token).

You do not need any API key, client secret, or onboarding step — this is an internal API keyed off Firebase Auth. There is no third-party API key program.

Base URL and /v1 versioning

Every endpoint lives under a versioned prefix, /v1. Pick the base URL for your target environment and append the versioned path:

So the health check in dev is https://api-dev.kiroku.cz/v1/healthz. The examples below use a shell variable so you can switch environments in one place:

BASE=https://api-dev.kiroku.cz

Step 1 — an unauthenticated call to /v1/healthz

/v1/healthz needs no token. It returns build provenance — which commit and environment the function is actually running:

curl -s "$BASE/v1/healthz" | jq

{
  "ok": true,
  "version": "v1",
  "build": {
    "commit": "<short sha>",
    "env": "dev",
    "time": "<iso timestamp>"
  }
}

Only the versioned path is exposed — a bare /healthz is not served.

Step 2 — get a token

Every business endpoint expects a Firebase ID token in an Authorization: Bearer <token> header, verified with the Firebase Admin SDK. Two practical ways to get one:

• From the running Kiroku app (most representative): the signed-in client holds one — await firebase.auth().currentUser.getIdToken() in a debug console prints exactly the token the app would send.
• Via the Firebase Auth REST API, signing in a test user with the project's Web API key:

  curl -s "https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key=$FIREBASE_WEB_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{"email":"<test-user>","password":"<password>","returnSecureToken":true}' \
    | jq -r .idToken

ID tokens expire after about an hour; re-fetch when calls stop authenticating. Capture it in a variable:

TOKEN=<paste the idToken here>

Step 3 — an authenticated call: GET /v1/app/open

GET /v1/app/open is the bootstrap the app calls on launch to hydrate the signed-in user's session, profile, preferences, onboarding, supporter status, and a cached snapshot of their drinking sessions. It reads only the caller's own data — authority comes from the token, never from the request body.

curl -s "$BASE/v1/app/open" \
  -H "Authorization: Bearer $TOKEN" | jq

A new user (no data yet) gets back just a session seed and an empty cache:

{
  "jsonCode": 200,
  "onyxData": [
    { "onyxMethod": "merge", "key": "session", "value": { "userID": "<uid>", "email": "<email>" } },
    { "onyxMethod": "set",   "key": "cachedDrinkingSessions", "value": { "<uid>": {} } }
  ]
}

An existing user gets additional updates — one entry per piece of state the server found. A missing token yields a 401.

How to read the response

Every /v1 business endpoint answers with the same envelope (the Kiroku app already knows how to consume it — that is the entire point of the migration layer):

{
  "jsonCode": 200,        // 200 = success; non-200 = failure; 407 = token expired → reauth
  "onyxData": [ /* OnyxUpdate[] */ ],
  "lastUpdateID": 0,      // optional, incremental-sync ordering
  "previousUpdateID": 0   // optional
}

onyxData is the meaningful part: an array of mutations the app applies directly to its local Onyx store. Each element is { "onyxMethod": "merge" | "set" | "mergecollection" | "clear", "key": "<ONYXKEY>", "value": <any> }. The envelope semantics — including the 407 reauthentication pattern — are explained in Conventions.

Next steps

• Browse the full endpoint surface → Reference
• Understand the contract and patterns → Conventions