API v2: ask only for what you use

Cheap by default

v1 was designed for the Ordo app and returns everything one app screen needs. Someone who only wanted tomorrow's reading references got the whole day, with collect, psalm and morning and evening readings. v2 turns that around.

v1 remains published with no end date. Use v2 for new integrations and migrate one route at a time, if and when it makes sense.

One key, one header

v2 accepts API keys only, sent in the X-API-Key header. It is the same key as v1: your plan, limits and usage dashboard cover both versions.

https://api.caminhoanglicano.com.br/api/v2

curl -G "https://api.caminhoanglicano.com.br/api/v2/days/today" \
  -H "X-API-Key: $ESTEVAO_API_KEY" \
  --data-urlencode "book=loc_2015" \
  --data-urlencode "include=readings,collect"

Without the key the answer is 401 MISSING_API_KEY. Keep the key on your server: never put it in code that runs in a browser or an app.

book is required

On v1, forgetting the book gets you a 200 with data from a book you never chose. On v2, every resource that depends on the book requires book. The prayer book and Bible catalogues and /passages do not.

{
  "type": "https://estevao.caminhoanglicano.com.br/docs/v2/errors#missing-prayer-book",
  "title": "Missing prayer book",
  "status": 400,
  "code": "MISSING_PRAYER_BOOK",
  "detail": "O parâmetro 'book' é obrigatório na v2. Consulte GET /api/v2/prayer-books.",
  "documentation_url": "https://estevao.caminhoanglicano.com.br/docs/v2",
  "request_id": "6f0c2c1e-…"
}

include: what is computed

Without include, /days returns just the liturgical day: season, colour, week and the celebration that prevailed. Each include adds a sub-resource and has a relative cost, reported in X-Request-Cost.

• — A child implies its parent: include=readings.text already computes readings.
• — An include the endpoint does not offer answers 400 INVALID_INCLUDE, with the accepted list in allowed.
• — On /days/:date/readings and /collects/:date the resource is the one in the path; include only adds text or alternatives.

fields: what is serialized

fields[type] takes the list of attributes to return for that resource type. It does not change what is computed, only what comes back in the JSON.

/api/v2/days?book=loc_2015&from=2026-03-01&to=2026-03-31
  &fields[day]=date,season,color,celebration

Accepted types: dayreadingcollectcelebrationcelebration_typeannual_overviewseasonkey_datelectionary_cycleprayer_bookbible_version

data, meta and links

A single envelope, so you write one parser. Keys are English snake_case on every resource; values such as season and colour names come in the book's language or in lang.

{
  "data": {
    "date": "2026-03-25",
    "liturgical_year": 2026,
    "week_of_season": 5,
    "is_sunday": false,
    "is_holy_day": true,
    "day_of_week": "Quarta-feira",
    "season": { "slug": "lent", "name": "Quaresma" },
    "color": "branco",
    "description": ["Anunciação de Nosso Senhor Jesus Cristo à Bem-Aventurada Virgem Maria"],
    "fast": null,
    "celebration": {
      "id": 412,
      "name": "Anunciação de Nosso Senhor Jesus Cristo à Bem-Aventurada Virgem Maria",
      "type": "principal_feast",
      "color": "branco",
      "movable": false,
      "transferred": false
    }
  },
  "meta": {
    "prayer_book": "loc_2015",
    "language": "pt-BR",
    "bible": "nvi",
    "generated_at": "2026-03-25T09:00:00Z"
  }
}

• — meta repeats the context that resolved the response: book, language, Bible translation and lectionary variant, when there is one.
• — Readings are a list with a slot (first_reading, psalm, second_reading, gospel…), not four fixed keys: books differ in how many readings they appoint.
• — A day without readings answers 200 with an empty readings list. 404 is for resources that do not exist.
• — Paginated collections carry links.self and links.next; meta carries count and total.

Cache, cost and limits

Where each route went

The data comes from the same liturgical services as v1; only the shape changes. v2 does not publish the Daily Office yet: for that, stay on v1.

• — The preferences blob becomes flat parameters: book, bible, lectionary, psalter, reading_type and lang. The blob is still accepted to ease migration.
• — Dates are ISO (2026-03-25), both in paths and in responses.
• — Routes use hyphens (key-dates, prayer-books) instead of underscores.