Tempus — Liturgical Calendar

The Tempus engine exposes the Roman Rite liturgical calendar. It merges the Temporal cycle (Advent, Christmas, Lent, Easter, Ordinary Time) with the Sanctoral cycle (saint feasts), resolving conflicts according to traditional rank precedence.

All Tempus endpoints are mounted at /v1/ordo and require an X-API-Key header. See Authentication.

Note

The Tempus engine resolves conflicts between the Temporal and Sanctoral cycles using traditional rank precedence. When a saint’s feast falls on a higher-ranked liturgical day (e.g., a Sunday of Lent), the saint may be commemorated rather than celebrated. The commemorations array in the response captures these displaced feasts.

---

Today’s Ordo

GET /v1/ordo/today

Returns the liturgical ordo for the current UTC date.

Response: OrdoResponse

{
  "date": "2026-01-28",
  "season": "ORDINARY_TIME",
  "color": "WHITE",
  "rank": "FEAST",
  "title": "Saint Thomas Aquinas, Priest and Doctor of the Church",
  "is_saint_feast": true,
  "saint_id": 42,
  "saint_slug": "thomas-aquinas",
  "saint_name": "Thomas Aquinas",
  "commemorations": []
}

---

Ordo for a Specific Date

GET /v1/ordo?date=YYYY-MM-DD

Query parameters:

• date (required) — ISO 8601 date string, e.g., 2026-03-19

Returns a single OrdoResponse for the given date.

---

Full-Year Calendar

GET /v1/ordo/calendar/{year}

Returns all 365 (or 366) days of the liturgical ordo for a given year. Useful for populating calendar UIs or pre-fetching yearly data.

Path parameters:

• year — four-digit year (e.g., 2026)

Response: List[OrdoResponse] — ordered chronologically, one entry per day.

---

Movable Feasts

GET /v1/ordo/movable/{year}

Returns the computed dates of all movable feasts for the given year — dates that shift annually based on Easter.

Path parameters:

• year — four-digit year

Response: Dict[str, date]

{
  "ash_wednesday": "2026-02-18",
  "palm_sunday": "2026-03-29",
  "easter": "2026-04-05",
  "ascension": "2026-05-14",
  "pentecost": "2026-05-24",
  "corpus_christi": "2026-06-04",
  "first_sunday_of_advent": "2026-11-29"
}

---

OrdoResponse — Full Schema

Field	Type	Notes
date	str	ISO 8601 date (YYYY-MM-DD)
season	Season	Liturgical season enum
color	LiturgicalColor	Vestment color enum
rank	Rank	Celebration rank enum
title	str	Liturgical title for the day
is_saint_feast	bool	Whether a saint feast is the principal celebration
saint_id	int?	Internal saint ID (if applicable)
saint_slug	str?	Saint slug (link to Devotio)
saint_name	str?	Saint display name
commemorations	List[Commemoration]	Secondary commemorations (suppressed by higher-rank celebration)

Season Enum

ADVENT, CHRISTMAS, ORDINARY_TIME, LENT, EASTER

LiturgicalColor Enum

GREEN, PURPLE, WHITE, RED, ROSE, BLACK

Rank Enum (highest to lowest)

SOLEMNITY, FEAST, MEMORIAL, OPTIONAL_MEMORIAL, FERIA

Commemoration

{
  "title": "Saint Agnes, Virgin and Martyr",
  "saint_id": 17,
  "saint_slug": "agnes"
}

---

Integration Note

The saint_slug field on OrdoResponse is directly usable as the path parameter for GET /v1/devotio/saints/{slug}, enabling seamless cross-engine lookups. A calendar view can thus enrich each day’s ordo with the full saint biography in a single additional request.