API publique

Le corpus est lisible par une machine. Une adresse en entrée, et tout ce que le corpus sait de ce passage en sortie : son libellé, son texte, et son apparat dans les deux sens — ce qu'il cite, et qui le cite.

L'apparat : les deux sens

C'est la raison d'être du corpus, et la seule idée qu'il faut avoir lue deux fois. Une note de bas de page est à sens unique : un document désigne un passage, et le passage n'apprend jamais qu'on l'a désigné. Ici, la rue se parcourt dans les deux sens.

out — ce que ce passage cite. Les renvois que l'auteur a lui-même mis dans ses notes : l'Écriture qu'il cite, les documents sur lesquels il s'appuie. C'est sa bibliographie, résolue en adresses.

in — qui cite ce passage. Tous ceux qui, dans le corpus, l'ont repris après lui. Personne n'a écrit cette liste : c'est l'out de tous les autres passages, lu à l'envers. C'est ce qu'une note imprimée ne peut pas donner, un texte ne pouvant pas connaître sa propre postérité.

Un avertissement sur ces deux mots, parce qu'ils désarçonnent. out et in nomment le sens de la FLÈCHE dans le graphe — partant de ce passage, arrivant sur lui — et non le sens de l'influence. Qui pense en influence les lit à l'envers : ce qu'un passage cite (out) est ce qui le NOURRIT, son apport, ses sources ; qui le cite (in) est ce qu'il a produit, sa postérité. Dans le doute, oubliez les deux mots et lisez la phrase posée à côté : ce que ce passage cite, qui cite ce passage. Celles-là ne s'inversent jamais.

Les deux sont séparés par nature — scripture et magisterium — parce qu'on ne les lit pas de la même façon, et que les mêler enfouit l'un dans l'autre.

Les entrées arrivent triées par importance, les plus fortes d'abord : pour l'Écriture, le nombre de traditions de renvois indépendantes qui attestent le lien ; pour le Magistère, le poids du passage dans le corpus, mesuré à ce qui le cite. Une liste tronquée n'est donc pas une coupe arbitraire : c'est la part qui compte. Demandez-en quatre, vous aurez les quatre qui comptent.

Gaudium et spes § 22, dans les deux sens :

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

Vers le bas, ce que le Concile citait. Vers le haut, ce que l'Église en a fait ensuite — Centesimus annus, Redemptoris Mater, Ecclesia in Asia, le Catéchisme. Un passage au in chargé est un passage sur lequel la tradition est revenue.

Une entrée peut viser un document ENTIER (lg) plutôt qu'un de ses §, quand la citation ne donne aucun numéro. Les entrées sont des adresses nues : rappelez /v1/locus sur l'une d'elles pour la résoudre — ni libellé ni URL ne sont dupliqués.

URL de base

Tous les chemins ci-dessous s'y accrochent. C'est l'hôte que ce site appelle lui-même : ce que vous lisez ici est ce dont le lecteur se sert.

https://api.theofons.net

Schéma lisible par une machine, et console interactive : https://api.theofons.net/docs ·openapi.json

Le même corpus est exposé en serveur MCP, pour les assistants qui parlent ce protocole : https://api.theofons.net/mcp

Les adresses

Tout, dans le corpus, a une adresse, et l'adresse est le seul vocabulaire de l'API. Un § du magistère s'écrit sigle/n ; un passage biblique livre/chapitre/verset, le verset pouvant être un intervalle.

Numérotation des psaumes

Trois traditions numérotent les psaumes différemment, et un verset faux est pire qu'un verset absent. Le paramètre psalter déclare VOTRE convention : les références entrent et ressortent dedans, et l'API convertit.

protestant

Numérotation hébraïque (massorétique). 150 psaumes, et la suscription (« Psaume de David, lorsque… ») ne compte PAS comme verset. C'est la convention des bibles protestantes et des concordances anglo-saxonnes.

aelf

Mêmes NUMÉROS de psaume que l'hébreu, mais la suscription compte comme verset — un psaume à titre est donc décalé d'un ou deux versets. C'est la numérotation des livres liturgiques francophones (lectionnaire, Liturgie des Heures). Le défaut ici.

vulgate

Numérotation grecque (Septante), suivie par la Vulgate et par le magistère ancien. Les Ps 9 et 10 hébreux n'y font qu'un : du Ps 10 au Ps 146, le numéro vulgate vaut UN DE MOINS que l'hébreu (les Ps 1-8 et 148-150 coïncident ; les Ps 114-115 et 147 se découpent encore autrement). Les versets y comptent la suscription, comme en aelf.

Le même verset — le Miserere — adressé de trois façons :

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

Les trois rendent le même texte. Se tromper de convention, c'est tomber sur le titre du psaume, ou sur le psaume d'à côté.

Points d'entrée

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"] }
  }
}

Limites et CORS

• 120 requêtes par minute et par IP, fenêtre glissante de 60 s. Au-delà : 429. Le compteur est par instance et best-effort — ne construisez pas sur sa valeur exacte, mais sur son ordre de grandeur.
• CORS ouvert à toute origine sur /v1/* et sur le serveur MCP — et là seulement. Vous pouvez appeler cette API depuis une page de navigateur, sans proxy.
• /v1/loci accepte au plus 500 références par appel et pagine (pageSize 50 par défaut, plafond dur 100).
• topN borne les entrées d'apparat par sens : 80 par défaut, plafond dur 500. Les entrées étant triées par importance, l'augmenter ajoute des liens plus faibles, jamais de meilleurs.
• Pas de clé, pas de quota, pas d'inscription. En lecture seule : rien ici n'écrit.

Ce qui est stable, et ce qui ne l'est pas

/v1 est le contrat, et la seule promesse faite. Ce qui peut arriver sans préavis à l'intérieur de /v1 : un point d'entrée de plus, un paramètre facultatif de plus, un champ de plus dans une réponse — un client qui ignore ce qu'il ne connaît pas ne casse pas. Ce qui n'arrivera pas : retirer ou renommer un champ ou un paramètre, en changer le type, le sens ou la valeur par défaut. Ces changements-là font un /v2, servi à côté de /v1 : l'ancien préfixe ne disparaît pas le jour où le nouveau paraît. Le corpus, lui, s'enrichit en continu — nouveaux documents, nouveaux liens d'apparat — sans changer de version : la forme est un contrat, le contenu ne l'est pas. Tout ce qui est offert est sur cette page. Le reste du serveur — le moteur de réponse, la recherche interne du site — est la mécanique de theofons.net : ni publiée, ni documentée, et couverte par aucun engagement.

Droits

L'API sert des textes qui ne lui appartiennent pas. Les droits sur les documents du magistère sont à la Libreria Editrice Vaticana ; les jeux de données importés portent leur propre licence, dont certaines exigent l'attribution. Avant de rediffuser quoi que ce soit tiré d'ici, lisez la page des crédits : elle nomme chaque source et sa licence.

Sources et crédits