Devotio — Saints & Prayers

The Devotio engine serves the Church’s living treasury of saints and prayer. It exposes two resources: the hagiographic database (/saints) and the prayer library (/prayers).

All Devotio endpoints require an X-API-Key header. See Authentication.

---

Saints — /v1/devotio/saints

Search Saints

GET /v1/devotio/saints

Query parameters:

• q (optional) — free-text search on name and biography
• rank (optional) — liturgical rank (e.g., Doctor of the Church, Martyr)
• patron (optional) — patronage string (e.g., students, Italy)
• month (optional) — feast month filter (e.g., 03 for March)
• limit — max results (default: 20)

Response: List[SaintRead]

[
  {
    "id": 42,
    "name": "Thomas Aquinas",
    "slug": "thomas-aquinas",
    "title": "Doctor of the Church",
    "ranks": ["Doctor of the Church", "Confessor"],
    "feast_day": "01-28",
    "born_year": 1225,
    "died_year": 1274,
    "patronage": ["students", "universities", "philosophers"],
    "iconography": ["star on chest", "ox"],
    "attributes": ["book", "lily"],
    "quotes": ["..."],
    "bio_markdown": "...",
    "relationships": [...],
    "citations": [...]
  }
]

---

Get Saint by Slug

GET /v1/devotio/saints/slug/{slug}

Returns the full SaintRead record for a single saint.

Example: GET /v1/devotio/saints/slug/thomas-aquinas

---

Get Saint by ID

GET /v1/devotio/saints/{saint_id}

Returns a SaintRead by integer ID.

---

Get Feast Date

GET /v1/devotio/saints/slug/{slug}/feast

Lightweight endpoint returning only the name and feast date. Useful for calendar integrations.

Response:

{
  "name": "Thomas Aquinas",
  "feast_day": "01-28"
}

feast_day format is MM-DD.

Tip

Combine the feast date endpoint with the Tempus engine to build a full liturgical saint calendar — query today’s ordo for the liturgical context, then fetch the saint details from Devotio.

---

List Ranks

GET /v1/devotio/saints/ranks

Returns all unique liturgical ranks present in the database.

Response: List[str]

---

List Patronages

GET /v1/devotio/saints/patronages

Returns all unique patronage strings. Useful for building filter UIs.

Response: List[str]

---

SaintRead — Full Schema

Field	Type	Notes
id	int	Internal ID
name	str	Canonical English name
slug	str	URL-safe identifier
title	str?	Honorific title
ranks	List[str]	Liturgical ranks
feast_day	str?	MM-DD format
born_year	int?	Approximate birth year
born_text	str?	Free-text birth description
died_year	int?	Approximate death year
died_text	str?	Free-text death description
canonization_year	int?	Year of canonization
patronage	List[str]	Patronages
iconography	List[str]	Iconographic symbols
attributes	List[str]	Traditional attributes
quotes	List[str]	Notable quotes
bio_markdown	str?	Full biography (Markdown)
relationships	List[SaintRelationshipRead]	Related saints/orders
citations	List[CitationRead]	Source citations — see below

---

CitationRead — Provenance

Every saint may carry citations recording where its life was drawn from. A citation points either at a chapter of our own corpus — in which case source resolves to a readable chapter — or at a work we cite but do not hold, in which case source is null and bibliography carries the volume details.

Field	Type	Notes
source_type	str	capitulum (internal chapter), bibliographicum (print work, not held), externum (external URL)
usage_type	str	VITA_PRIMARIA (the principal life), GENERAL (corroborating), PROOF_TEXT
url	str?	External URL, when the source is a web document
text	str?	Quoted excerpt, where one was recorded
bibliography	object?	Volume, author, article title, rights — free-form JSON
source	CitationSourceRef?	Present only when the source is a chapter we hold

CitationSourceRef

Field	Type	Notes
capitulum_id	int	Internal chapter ID
opus_slug	str?	Work slug — use with the Veritas opera routes
opus_title	str?	Human-readable work title
chapter_slug	str?	Chapter slug
chapter_title	str?	Human-readable chapter title

Read the cited source directly: GET /v1/veritas/opera/{opus_slug}/read/{chapter_slug}

{
  "source_type": "capitulum",
  "usage_type": "VITA_PRIMARIA",
  "url": null,
  "text": null,
  "bibliography": {
    "opus": "The Catholic Encyclopedia (1913)",
    "articulus": "The Venerable Bede",
    "rights": "public domain"
  },
  "source": {
    "capitulum_id": 3325,
    "opus_slug": "catholic_encyclopedia_1913",
    "opus_title": "The Catholic Encyclopedia (1913)",
    "chapter_slug": "the_venerable_bede_ce",
    "chapter_title": "The Venerable Bede"
  }
}

Caution

Provenance is presently recorded only for hand-scribed saints. The larger body of saints ingested by the Refinery returns an empty citations array — absence of a citation is not a claim that no source exists. Backfilling is deliberately a human-reviewed process, since name similarity alone cannot establish that an article is the life of a given saint.

---

Prayers — /v1/devotio/prayers

Browse Prayers

GET /v1/devotio/prayers

Query parameters:

• typus (optional) — prayer type (e.g., rosary, litany, novena, psalm)
• q (optional) — free-text search on title and text
• limit — max results (default: 10)

Response: List[PrayerRead]

[
  {
    "id": 7,
    "slug": "hail-mary",
    "title": "Hail Mary",
    "type": "marian",
    "text_latin": "Ave Maria, gratia plena...",
    "text_en": "Hail Mary, full of grace...",
    "tags": ["marian", "rosary", "classic"]
  }
]

---

Get Prayer by Slug

GET /v1/devotio/prayers/{slug}

Returns a single PrayerRead record.

---

Get Random Prayer

GET /v1/devotio/prayers/random

Returns a single PrayerRead chosen at random. Useful for daily devotional feeds.

---

PrayerRead — Full Schema

Field	Type	Notes
id	int	Internal ID
slug	str	URL-safe identifier
title	str	Prayer title
type	str	Prayer category
text_latin	str?	Latin text (if available)
text_en	str?	English translation
tags	List[str]	Descriptive tags