Liturgy API quickstart

The /liturgy/v1 API is a read-only, Pro-tier surface for Catholic liturgical data — calendar, Mass propers, Office, and saints across the Roman Ordinary, Roman 1962 (TLM), and Dominican rites. For the full data model see Liturgy; this page just gets you making calls.

1. Mint a key

API keys are minted from a signed-in web session (the key is shown once and cannot be retrieved again). With your gianna_session cookie:

curl -s https://gianna.chat/api/keys \
  -H 'Content-Type: application/json' \
  -b 'gianna_session=YOUR_SESSION_COOKIE' \
  -d '{"name":"my-script"}'
# → { "id": "...", "name": "my-script", "key": "gianna_…" }

Store the gianna_… value. Every data call presents it as a bearer token: Authorization: Bearer gianna_…. Access is Pro-gated, so the household must be on the Pro tier for the data endpoints to answer.

2. A liturgical day

curl -s https://gianna.chat/liturgy/v1/calendars/ordinary/days/2026-12-25 \
  -H 'Authorization: Bearer gianna_…'

The path is /calendars/{cal}/days/{date} where cal is ordinary, traditional, or dominican and date is ISO YYYY-MM-DD. Latin is always present; add Accept-Language: en to also get English text.

3. Search saints

curl -s 'https://gianna.chat/liturgy/v1/saints?q=peter&title=martyr' \
  -H 'Authorization: Bearer gianna_…'

Results come in a collection envelope (results, query, page); pass ?page=N to walk the pages.

Choosing a scripture edition

Reading text defaults to each language's public-domain edition. To pick one, pass ?editions=<id>[,<id>] (≤1 per language). Current ids: vulgate (la), douay (en), cpdv (en) — the live set is at /liturgy/v1/translations. Unknown ids fall back to the default (lenient, with a collection warning). The resolved choice is echoed as editions on the response. translations is an accepted alias; editions wins if both are sent.

curl -s 'https://gianna.chat/liturgy/v1/calendars/ordinary/days/2026-12-25?editions=douay' \
  -H 'Authorization: Bearer gianna_…'

Rate limits

Requests are rate-limited per household on a fixed one-minute window. Over the limit you get 429 Too Many Requests with a Retry-After header (seconds until the window resets) and a application/problem+json body. Back off for that many seconds and retry.

The full contract

The machine-readable OpenAPI 3.1 document — every path, parameter, and response schema — is served at /liturgy/v1/openapi.json (also Pro-gated). Generate a client from it.