Public API

The corpus is readable by machine. One address in, everything the corpus knows about that passage out: its label, its text, and its apparatus in both directions — what it cites, and who cites it.

The apparatus: two directions

This is what the corpus is for, and the one idea worth reading twice. A footnote is a one-way street: a document points at a passage, and the passage never learns it was pointed at. Here the street runs both ways.

out — what this passage cites. The references the author himself put in his notes: the Scripture he quotes, the documents he leans on. It is his own bibliography, resolved into addresses.

in — who cites this passage. Everyone in the corpus who quoted it afterwards. Nobody wrote this list: it is the out of every other passage, read backwards. It is what a printed footnote can never give you, because a text cannot know its own posterity.

A warning about the two words, because they trip people up. out and in name the direction of the ARROW in the graph — leaving this passage, arriving at it — not the direction of influence. Think in terms of influence and they read backwards: what a passage cites (out) is what FEEDS it, its intake, its sources; who cites it (in) is what it produced, its posterity. If in doubt, ignore the two words and read the sentence next to them: what this passage cites, who cites this passage. Those never reverse.

Both are split by nature — scripture and magisterium — because the two are read differently, and mixing them buries one in the other.

Entries come sorted by importance, strongest first: for Scripture, how many independent cross-reference traditions attest the link; for the Magisterium, how heavily the passage is cited across the corpus. So a truncated list is not an arbitrary slice — it is the part that matters. Ask for four entries and you get the four that count.

Gaudium et spes § 22, in both directions:

gs/22   Gaudium et spes § 22 — Le Christ, homme nouveau

  out  ce que ce § cite  —  ses sources, ce qui le nourrit
       scripture     1co/13/8   1co/3/14   1co/7/3-6   1jn/3/1-2
       magisterium   lg   lg/1   qa   oeuvre:irenee-de-lyon

  in   qui cite ce §     —  sa postérité, ce qu'il a produit
       scripture     —
       magisterium   ca/47   rmat/46   eia/21   cec/521

Read down: what the Council quoted. Read up: what the Church made of it afterwards — Centesimus annus, Redemptoris Mater, Ecclesia in Asia, the Catechism. A passage with a heavy in is a passage the tradition kept coming back to.

An entry can be a whole document (lg) rather than one of its paragraphs, when the citation names no number. Entries are bare addresses: call /v1/locus on any of them to resolve it — labels and URLs are never duplicated.

Base URL

Every path below hangs off this host. It is the very host this site calls: what you read here is what the reader uses.

https://api.theofons.net

Machine-readable schema and interactive console: https://api.theofons.net/docs ·openapi.json

The same corpus is exposed as an MCP server, for assistants that speak that protocol: https://api.theofons.net/mcp

Addresses

Everything in the corpus has an address, and the address is the API's only vocabulary. A magisterial paragraph is siglum/n; a biblical passage is book/chapter/verse, the verse optionally a range.

Psalm numbering

Three traditions number the psalms differently, and a wrong verse is worse than no verse. The psalter parameter states YOUR convention: references go in and come back out in it, and the API converts.

protestant

Hebrew (Masoretic) numbering. 150 psalms, and the superscription (“A psalm of David, when…”) does NOT count as a verse. The convention of Protestant bibles and of English-language concordances.

aelf

Same psalm NUMBERS as the Hebrew, but the superscription DOES count as a verse — so a titled psalm is shifted by one or two verses. This is the numbering of French liturgical books (lectionary, Liturgy of the Hours). The default here.

vulgate

Greek (Septuagint) numbering, followed by the Vulgate and by the older Magisterium. Hebrew Ps 9 and 10 are a single psalm there, so from Ps 10 to Ps 146 the Vulgate number is ONE LESS than the Hebrew (Ps 1-8 and 148-150 agree; 114-115 and 147 divide differently again). Verses count the superscription, as in aelf.

The same verse — the Miserere — addressed three ways:

psalter=protestant   ps/51/1
psalter=aelf         ps/51/3
psalter=vulgate      ps/50/3

All three return the same text. Get it wrong and you land on the title of the psalm, or on the psalm next door.

Endpoints

curl "https://api.theofons.net/v1/documents?lang=fr"

{
  "lang": "fr",
  "count": 91,
  "documents": [
    {
      "siglum": "ls",
      "title": "Laudato si'",
      "author": "François",
      "year": 2015,
      "langs": ["en", "fr", "la"],
      "paragraphs": { "fr": 246, "en": 246, "la": 246 }
    }
  ]
}

curl "https://api.theofons.net/v1/locus?ref=jn/3/16&apparatus=1&topN=2"

{
  "ref": "jn/3/16",
  "kind": "scripture",
  "label": "Jn 3, 16",
  "apparat": {
    "out": { "scripture": ["rm/5/8", "rm/8/32"], "magisterium": [] },
    "in":  { "scripture": ["rm/8/32", "jn/10/28"], "magisterium": ["gs/51", "gs/38"] }
  }
}

curl -X POST "https://api.theofons.net/v1/loci" \
  -H "Content-Type: application/json" \
  -d '{"refs":["ls/217","rf/82"]}'

{
  "page": 1, "pageSize": 50, "total": 2, "returned": 2, "hasMore": false,
  "results": [
    {
      "ref": "ls/217",
      "kind": "magisterium",
      "label": "Laudato si' § 217 — III. LA CONVERSION ÉCOLOGIQUE",
      "document": { "siglum": "ls", "title": "Laudato si'" },
      "section": "III. LA CONVERSION ÉCOLOGIQUE"
    }
  ]
}

curl "https://api.theofons.net/v1/lectionnaire?date=2026-07-29&lang=fr"

{
  "date": "2026-07-29",
  "lang": "fr",
  "psalter": "aelf",
  "jour": {
    "cleJour": "saintMartha",
    "nom": "Sainte Marthe, Disciple du Christ (1er s.)",
    "type": "MEMORIAL", "cycle": "A", "sanctoral": false
  },
  "lectures": {
    "lecture1": { "slot": "Première lecture", "sourceRef": "Jer 15:10, 16-21",
                  "loci": ["jr/15/10", "jr/15/16-21"] },
    "psaume":   { "slot": "Psaume", "sourceRef": "Ps 59:2-3, 4, 10-11, 17, 18",
                  "loci": ["ps/59/2-3", "ps/59/4", "ps/59/10-11", "ps/59/17", "ps/59/18"] },
    "evangile": { "slot": "Évangile", "sourceRef": "Matt 13:44-46",
                  "loci": ["mt/13/44-46"] }
  }
}

Limits and CORS

• 120 requests per minute per IP, sliding window of 60 s. Over the limit: 429. The counter is per instance and best-effort — do not build on its exact value, build on the order of magnitude.
• CORS open to any origin on /v1/* and on the MCP server — and only there. You can call this API from a browser page, with no proxy.
• /v1/loci takes at most 500 references per call and paginates (pageSize default 50, hard cap 100).
• topN caps apparatus entries per direction: default 80, hard cap 500. Since entries come sorted by importance, raising it adds weaker links, never better ones.
• No key, no quota, no sign-up. Read-only: nothing here writes.

What is stable, and what is not

/v1 is the contract, and the only promise made. What can happen inside /v1 without notice: one more endpoint, one more optional parameter, one more field in a response — a client that ignores what it does not recognise will not break. What will not happen: removing or renaming a field or a parameter, changing its type, its meaning, or its default. Those changes make a /v2, served alongside /v1: the old prefix does not vanish the day the new one appears. The corpus itself grows continuously — new documents, new apparatus links — without a version change: the shape is a contract, the content is not. Everything on offer is on this page. The rest of the server — the answer engine, the site's own search — is the internal machinery of theofons.net: not published, not documented, and covered by no undertaking.

Rights

The API serves texts it does not own. Rights on the magisterial documents belong to the Libreria Editrice Vaticana; the imported datasets carry their own licences, some of which require attribution. Before redistributing anything drawn from here, read the credits page — it names every source and its licence.

Sources and credits