Inicio rápido de la API de Gianna

La API /liturgy/v1 ofrece acceso de solo lectura a datos litúrgicos católicos: calendario, propios de Misa, Oficio y santos de los ritos romano ordinario, romano de 1962 (TLM) y dominicano. Es gratuita con una cuenta de Gianna. El modelo completo está en Liturgia; esta página permite empezar a realizar llamadas.

1. Crear una clave

Crea una clave en la aplicación, en Ajustes, Acceso para desarrolladores. Se muestra una sola vez y no puede recuperarse. También puedes crearla desde una sesión web iniciada con tu cookie gianna_session:

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_…" }

Guarda el valor gianna_…. Cada llamada de datos lo presenta como token bearer: Authorization: Bearer gianna_…. Los datos litúrgicos y de iglesias solo requieren una cuenta. Las llamadas al hogar requieren un plan activo o en prueba; actuar sobre un hogar con plan vencido devuelve 403.

Las personas, instituciones y cargos también están disponibles mediante /registry/v1/people, /registry/v1/sees y /registry/v1/offices. Su documento OpenAPI describe los campos y recursos relacionados. Las lecturas requieren reference:read. Los responsables y administradores pueden añadir y editar estos registros con una clave de cuenta que tenga household:write; su trabajo de referencia no requiere un plan de pago. Consulta Mantener personas y cargos para edición e importaciones.

2. Un día litúrgico

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

La ruta es /calendars/{cal}/days/{date}, donde cal es ordinary, traditional o dominican, y date usa ISO YYYY-MM-DD. El latín siempre está presente; añade Accept-Language: en para recibir también texto inglés.

3. Buscar santos

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

Los resultados usan una envoltura de colección (results, query, page); envía ?page=N para recorrer las páginas.

4. Oraciones y Escritura

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_…'

El texto se devuelve exactamente como fue publicado, con su fuente.

5. Horarios de Misa y Confesión

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_…'

Cada horario lleva source_url, scraped_at y confidence. Buscar por nombre una iglesia desconocida para Gianna devuelve status: "checking" y comienza a buscar sus fuentes; inténtalo más tarde. La clave requiere directory:read.

6. Tu hogar

Con household:read (y household:write para cambios):

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 entrega los recordatorios. Envía Idempotency-Key con cada POST para evitar que un reintento cree otro recordatorio; la misma clave y cuerpo repiten la primera respuesta durante 24 horas. Los cambios aparecen inmediatamente en la aplicación.

Elegir una edición bíblica

El texto de lectura usa por defecto la edición de dominio público de cada idioma. Para elegir una, envía ?editions=<id>[,<id>] (como máximo una por idioma). Ids actuales: vulgate (la), douay (en), cpdv (en); el conjunto vigente está en /liturgy/v1/translations. Los ids desconocidos usan la predeterminada, con tolerancia y aviso en colecciones. La elección resuelta se indica como editions en la respuesta. translations se acepta como alias; editions prevalece si se envían ambos.

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

Límites de solicitudes

Las solicitudes se limitan por hogar en una ventana fija de un minuto. Al superar el límite se recibe 429 Too Many Requests con cabecera Retry-After (segundos hasta que se reinicie la ventana) y cuerpo application/problem+json. Espera esos segundos e inténtalo de nuevo.

El contrato completo

Cada familia publica un documento OpenAPI 3.1 con operationIds: /liturgy/v1/openapi.json, /directory/v1/openapi.json y /household/v1/openapi.json. /.well-known/api-catalog los enumera todos. Los errores usan application/problem+json.

Fuentes de calendario

Las fuentes de fiestas no requieren clave. Suscríbete desde cualquier aplicación de calendario:

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

Consulta Calendarios de fiestas católicas para enlaces directos.