Gianna API quickstart

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

1. Mint a key

Create a key in the app under Settings, Developer access. The key is shown once and cannot be retrieved again. You can also mint one from a signed-in web session 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_…. Liturgy and church data need only an account. Household calls need an active or trialing plan; acting on a lapsed household gets 403.

People, institutions and offices are also available through /registry/v1/people, /registry/v1/sees and /registry/v1/offices. Their OpenAPI document describes the fields and related resources. Reads need reference:read. Curators and administrators can add and edit these records with an account-bound key that has household:write; their reference work has no paid-plan requirement. See Maintaining people and offices for editing and imports.

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.

4. Prayers and Scripture

curl -s https://gianna.chat/liturgy/v1/prayers/hail-mary -H 'Authorization: Bearer gianna_…'
curl -s 'https://gianna.chat/liturgy/v1/scripture?ref=Jn%203:16&editions=douay' \
  -H 'Authorization: Bearer gianna_…'

Text comes back exactly as published, with its source.

5. Mass and Confession times

curl -s 'https://gianna.chat/directory/v1/churches?near=Cambridge' -H 'Authorization: Bearer gianna_…'
curl -s 'https://gianna.chat/directory/v1/churches?q=Our%20Lady&locality=Cambridge' \
  -H 'Authorization: Bearer gianna_…'

Each service time carries source_url, scraped_at, and confidence. A name search for a church Gianna does not know yet returns status: "checking" and starts sourcing it; try again later. The key needs directory:read.

6. Your household

With household:read (and household:write for changes):

curl -s https://gianna.chat/household/v1/tasks -H 'Authorization: Bearer gianna_…'
curl -s https://gianna.chat/household/v1/reminders -H 'Authorization: Bearer gianna_…' \
  -H 'Content-Type: application/json' -H 'Idempotency-Key: 4f1c…' \
  -d '{"body":"Pray the Angelus","at":"2026-12-24T12:00:00Z","recurrence":{"unit":"daily"}}'

Gianna delivers reminders itself. Send an Idempotency-Key with every POST so the same key and body replay the first response for 24 hours, including across server restarts. If the outcome is uncertain, read the current state before making another change; do not bypass the result with a new key. Check state before repeating an action after 24 hours. Changes appear in the app at once.

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

Each family publishes a public OpenAPI 3.1 document with operationIds: /liturgy/v1/openapi.json, /directory/v1/openapi.json, and /household/v1/openapi.json. /.well-known/api-catalog lists them all. Errors are application/problem+json.

Calendar feeds

The feast-day feeds need no key. Subscribe from any calendar app:

https://gianna.chat/liturgy/v1/calendars/ordinary/feasts.ics?rank=feast&region=general

See Catholic feast calendars for one-click links.