API du Catéchisme

Le site expose une petite API JSON en lecture seule, sans clé ni inscription. Elle sert à afficher les pages du Catéchisme et alimente également ce site : c'est la même API que vous pouvez appeler directement.

Points d'accès

Le document /api/openapi.json décrit l'ensemble au format OpenAPI 3.1, utilisable par un générateur de client ou par un agent.

Essayer

Choisissez une route, modifiez l'adresse si vous le souhaitez, puis envoyez la requête. L'appel part de votre navigateur vers cette même API, sans clé ni intermédiaire.

Paragraphe par numéro

GET /api/cec/[number] renvoie un paragraphe du Catéchisme, de 1 à 2865, avec son contexte (partie, section, article, intertitre) et ses renvois.

GET /api/cec/2559

{
  "number": 2559,
  "corpus": "ccc",
  "text_html": "<span>« La prière est l'élévation de l'âme vers Dieu…",
  "text": "« La prière est l'élévation de l'âme vers Dieu…",
  "cross_refs": ["2613", "2736"],
  "bible_refs": [{ "text": "Ps 130:14" }, { "text": "Lc 18:9-14" }],
  "citations": [],
  "magisterial_refs": [
    { "type": "patristic", "raw": "saint Jean Damascène, de fide orthodoxa 3:24 : PG 94:1089D", "idx": "a" },
    { "type": "bible", "raw": "Ps 130:14", "idx": 1, "display_idx": 1 }
  ],
  "breadcrumb": {
    "part": { "slug": "4-priere-chretienne", "title": "La prière chrétienne", "number": 4,
              "range": { "from": 2558, "to": 2865 } },
    "section": { "slug": "1-priere-dans-la-vie-chretienne", "title": "La prière dans la vie chrétienne",
                 "number": 1, "range": { "from": 2558, "to": 2758 } },
    "article": { "slug": "quest-ce-que-la-priere", "title": "Qu'est-ce que la prière ?",
                 "range": { "from": 2559, "to": 2565 } },
    "heading": { "id": "la-priere-comme-don-de-dieu", "title": "La prière comme don de Dieu" }
  },
  "prev": 2558,
  "next": 2560,
  "permalink": "https://catechismecatholique.fr/cec/2559"
}

Les niveaux de breadcrumb sont facultatifs : le Prologue n'a ni section ni article, et un paragraphe hors intertitre n'a pas de heading.

cross_refs est un tableau de chaînes, chacune un numéro de paragraphe. Un même numéro peut y figurer deux fois lorsque le texte le signale par deux marques distinctes. Le bloc cited_by parcourt la même relation en sens inverse et sert des entiers dédoublonnés : c'est un index dérivé, non la forme brute.

bible_refs donne la référence telle que le Catéchisme l'écrit, avec deux points entre le chapitre et le verset (Ps 130:1). L'usage français met une virgule, et c'est ce que le site affiche · le bloc bible décrit plus bas fournit cette forme dans son champ display, avec le livre, le chapitre et le verset résolus.

Texte, sources citées et passage complet

text est le jumeau en texte brut de text_html : la prose du paragraphe, et elle seule. 352 paragraphes citent en outre une source · un concile, un Père, une prière · rendue en bloc détaché sous le texte. Ces citations vivent dans citations, chacune avec son text_html et son text.

La distinction compte : 307 de ces paragraphes finissent sur un deux-points que la citation complète. Lire text seul y laisse une phrase en suspens. text_full donne le passage entier, prose puis citations, séparées par une ligne blanche. Il n'apparaît que si le paragraphe cite quelque chose : son absence dit qu'il n'y a rien à joindre, et les 2513 autres paragraphes ne portent pas une seconde copie de text pour rien.

GET /api/cec/302

{
  "text_html": "<span>La création a sa bonté…vers cette perfection :</span>",
  "text": "La création a sa bonté…vers cette perfection :",
  "text_full": "La création a sa bonté…vers cette perfection :

Dieu garde et gouverne par sa providence tout ce qu'Il a créé…",
  "citations": [
    {
      "text_html": "<span>Dieu garde et gouverne par sa providence…</span>",
      "text": "Dieu garde et gouverne par sa providence tout ce qu'Il a créé…"
    }
  ]
}

Il n'y a délibérément pas de text_full_html. Concaténer les balises mettrait la citation dans un span frère de la prose, sans rien pour les distinguer : les mots d'un concile se liraient comme ceux du Catéchisme. Le texte brut ne perd rien en les joignant, puisqu'il ne sait pas exprimer cette différence de toute façon · le HTML le sait, et la perdrait. Un client qui rend du HTML dispose de text_html et de citations[].text_html, et les enveloppe comme il l'entend.

Un numéro hors de 1..2865 répond 404 avec un champ error.

Plusieurs paragraphes

GET /api/cec sert plusieurs paragraphes en une requête, soit par liste (numbers=1,2,3), soit par plage (range=10-25). Chaque élément de items a exactement la forme d'une réponse unitaire.

GET /api/cec?range=1-3

{
  "count": 3,
  "items": [
    {
      "number": 1,
      "corpus": "ccc",
      "text": "Dieu, infiniment Parfait et Bienheureux en Lui-même…",
      "cross_refs": [],
      "bible_refs": [],
      "breadcrumb": {
        "part": { "slug": "prologue", "title": "Prologue", "range": { "from": 1, "to": 25 } },
        "heading": { "id": "i-la-vie-de-lhomme-connaitre-et-aimer-dieu",
                     "title": "I. La vie de l'homme – connaître et aimer Dieu" }
      },
      "prev": null,
      "next": 2,
      "permalink": "https://catechismecatholique.fr/cec/1"
    }
  ]
}

Au plus 50 paragraphes par requête. Si numbers et range sont donnés tous les deux, range l'emporte. Un include large sur une plage large est refusé : le produit du nombre de paragraphes par le nombre de blocs ne peut dépasser 100 lectures.

Recherche

GET /api/search?q=… effectue une recherche plein texte sur le Catéchisme, le Compendium et le Compendium de la doctrine sociale.

GET /api/search?q=eucharistie

{
  "q": "eucharistie",
  "hits": [
    {
      "id": "p:1327",
      "kind": "paragraph",
      "number": 1327,
      "text": "Bref, l'Eucharistie est le résumé et la somme de notre foi…",
      "title": "",
      "score": 21.99,
      "match": { "eucharistie": ["text"] }
    }
  ],
  "mode": "and",
  "tokens": ["eucharistie"],
  "matchedTokens": ["eucharistie"],
  "suggestions": []
}

mode vaut "and" quand tous les mots de la requête ont été trouvés dans chaque résultat, ou "or" quand la recherche est retombée sur au moins un mot en cas d'échec du mode strict. Si hits est vide, suggestions peut proposer des entrées du glossaire proches de la requête.

Références bibliques

GET /api/bible/[book]/[chapter]/[verse] prend le problème dans l'autre sens : quels paragraphes du Catéchisme citent ce verset. Le livre s'écrit en slug français (jean) ou en code USFX (JHN).

GET /api/bible/jean/3/16

{
  "book": "JHN",
  "book_slug": "jean",
  "book_name": "Jean",
  "chapter": 3,
  "verse": 16,
  "paragraphs": [219, 444, 454, 458, 706]
}

Sans le verset, la route renvoie le chapitre entier : verse vaut null, paragraphs réunit tout le chapitre, et un objet verses détaille le découpage verset par verset.

GET /api/bible/jean/3

{
  "book": "JHN",
  "book_slug": "jean",
  "book_name": "Jean",
  "chapter": 3,
  "verse": null,
  "paragraphs": [161, 219, 423, 432, 440, 444, "…"],
  "verses": {
    "5": [432, 720, 728, 1215, 1225, 1238, "…"],
    "16": [219, 444, 454, 458, 706]
  }
}

Joindre le texte des paragraphes

Par défaut ces routes renvoient des numéros, pas du texte : la réponse reste un index, petite et très cacheable. include=texts joint le texte de chaque paragraphe cité, ce qui évite un aller-retour vers /api/cec. C'est la seule valeur que include accepte ici · les blocs d'étude décrits plus bas appartiennent à /api/cec.

GET /api/bible/jean/3/16?include=texts

{
  "book": "JHN",
  "book_slug": "jean",
  "book_name": "Jean",
  "chapter": 3,
  "verse": 16,
  "paragraphs": [219, 444, 454, 458, 706],
  "texts": [
    {
      "number": 219,
      "text": "L'amour de Dieu pour Israël est comparé à l'amour d'un père pour son fils…",
      "citations": [],
      "permalink": "https://catechismecatholique.fr/cec/219"
    },
    "…"
  ]
}

Chaque entrée porte les mêmes champs que /api/cec/[number] pour le texte : text pour la prose, citations pour les sources citées, et text_full lorsqu'il y en a. Un paragraphe rendu ici et par /api/cec se décrit de la même façon des deux côtés.

texts donne le texte brut, sans balises : les appels de note n'ont pas de sens détachés de leur apparat, et permalink mène à l'enregistrement complet. Pour le HTML et les renvois d'un paragraphe, appelez /api/cec/[number].

Au plus 50 paragraphes par requête. Au-delà, la liste est coupée · les numéros les plus bas sont gardés et la réponse porte texts_truncated: true. paragraphs reste complet dans tous les cas, de sorte qu'un client peut toujours aller chercher le reste. Un paragraphe dont le fichier manque est simplement absent de texts plutôt que de faire échouer la réponse.

Péricopes

GET /api/pericope?ref=… prend une référence telle que le lectionnaire l'écrit et renvoie les paragraphes du Catéchisme qui citent ce passage. C'est la route à utiliser pour une plage de versets : elle évite d'avoir à écrire un analyseur de références françaises.

GET /api/pericope?ref=Lc 7, 11-16

{
  "count": 1,
  "items": [
    {
      "ref": "Lc 7, 11-16",
      "book": "LUK",
      "book_slug": "luc",
      "book_name": "Luc",
      "spans": [{ "chapter": 7, "from": 11, "to": 16 }],
      "paragraphs": [994, 1503],
      "verses": { "11": [994], "14": [994], "16": [994, 1503] }
    }
  ]
}

Les formes acceptées couvrent ce que le lectionnaire produit réellement :

• Lc 7, 11-16 et Lc 7:11-16 · virgule française ou deux points
• Gn 49, 1-2.8-10 · groupes disjoints, le lectionnaire saute des versets
• Ps 79, 2ac.3bc, 15-16a · les lettres de demi-verset sont ignorées
• Ps 118 (119), 97-98 · le numéro entre parenthèses l'emporte, car le texte biblique servi ici suit la numérotation hébraïque
• Mt 26, 14 - 27, 66 · les péricopes qui franchissent un chapitre
• Ap 4 · un chapitre entier, et Jude 3 comme verset

Au plus 50 références par requête, soit en répétant le paramètre (?ref=…&ref=…), soit en les séparant par un point-virgule (?ref=Lc 7, 11-16; Jn 3, 16). Une référence illisible ne fait pas échouer la requête : elle revient dans items avec son propre error et le code bad_reference, pour qu'un lectionnaire entier ne soit pas perdu à cause d'une référence malformée.

paragraphs réunit et dédoublonne tout le passage, verses détaille verset par verset. Un passage que le Catéchisme ne cite jamais renvoie une liste vide : c'est une réponse, non une erreur.

include=texts fonctionne ici aussi, avec une différence : le texte arrive dans un texts unique au premier niveau de la réponse, réunissant tous les ref demandés, et non recopié dans chaque item. Les lectures d'un même jour se recoupent souvent, et chaque item nomme déjà ses propres numéros. Le plafond de 50 paragraphes porte sur cette réunion.

GET /api/pericope?ref=Lc 7, 11-16&include=texts

{
  "count": 1,
  "items": [{ "ref": "Lc 7, 11-16", "paragraphs": [994, 1503], "…": "…" }],
  "texts": [
    { "number": 994, "text": "…", "permalink": "https://catechismecatholique.fr/cec/994" },
    { "number": 1503, "text": "…", "permalink": "https://catechismecatholique.fr/cec/1503" }
  ]
}

Calendrier liturgique

GET /api/liturgie/[date] donne la célébration du jour et les paragraphes du Catéchisme proposés à la méditation avec les lectures, groupés par thème. La date s'écrit AAAA-MM-JJ, ou today.

GET /api/liturgie/2026-12-13

{
  "date": "2026-12-13",
  "slug": "troisieme-dimanche-de-lavent",
  "calendar_source": "year",
  "cycle": "b",
  "liturgical_color": "rose",
  "celebration": {
    "title": "Troisième Dimanche de l'Avent",
    "season": "avent",
    "color": "rose",
    "cycle": "b"
  },
  "meditation": [
    { "theme": "la joie", "paragraphs": [30, 163, 301, 736, 1829, 1832, 2015, 2362] },
    { "theme": "les caractéristiques du Messie attendu", "paragraphs": [713, 714] }
  ]
}

cycle est déterminant : le même dimanche revient en années A, B et C et le même jour de semaine en années paires et impaires (cycles I et II), avec des paragraphes différents. calendar_source indique d'où vient le jour : year pour un dimanche ou une fête mobile, weekday pour un jour de semaine du temps ordinaire, proper pour un jour fixé à une date. Un jour propre à une date n'a pas de cycle et cycle vaut alors null.

Thèmes

GET /api/themes liste le vocabulaire thématique complet, et GET /api/themes/[slug] donne les paragraphes portant un thème.

GET /api/themes

{
  "count": 208,
  "themes": [
    { "name": "Abraham", "slug": "abraham", "count": 22, "glossary_url": "/glossaire/abraham" },
    { "name": "Accomplissement", "slug": "accomplissement", "count": 41,
      "glossary_url": "/glossaire/accomplissement" }
  ]
}

GET /api/themes/priere

{
  "slug": "priere",
  "name": "Prière",
  "glossary_url": "/glossaire/priere",
  "count": 52,
  "paragraphs": [28, 122, 197, 249, 307, 435, "…"]
}

Structure

GET /api/structure renvoie l'arborescence du Catéchisme. Le paramètre depth la tronque : 1 aux parties, 2 aux sections, 3 aux chapitres. Sans depth, l'arbre est complet jusqu'aux articles.

GET /api/structure?depth=1

{
  "corpus": "ccc",
  "parts": [
    {
      "slug": "prologue",
      "title": "Prologue",
      "prologue": true,
      "range": { "from": 1, "to": 25 },
      "intro_paragraphs": [1, 2, 3, "…"],
      "intro_headings": [
        { "id": "i-la-vie-de-lhomme-connaitre-et-aimer-dieu", "level": 2,
          "title": "I. La vie de l'homme – connaître et aimer Dieu", "paragraph_start": 1 }
      ]
    },
    {
      "slug": "1-profession-de-la-foi",
      "title": "La profession de la foi",
      "number": 1,
      "prologue": false,
      "range": { "from": 26, "to": 1065 }
    }
  ]
}

intro_paragraphs et intro_headings n'apparaissent que sur les niveaux qui ouvrent sur un texte avant leur première subdivision.

Glossaire

GET /api/glossary liste les entrées et leurs grappes thématiques, GET /api/glossary/[slug] sert une entrée. Les slugs sont les mêmes que ceux des thèmes.

GET /api/glossary/priere

{
  "slug": "priere",
  "term": "Prière",
  "latin": "Oratio",
  "definition": "Élévation de l'âme vers Dieu, demande adressée à Dieu…",
  "directRefs": [28, 122, 197, "…"],
  "subEntries": [
    { "label": "Définition de la prière", "refs": [2559] },
    { "label": "Dieu exauce notre prière", "refs": [1127, 2737] }
  ],
  "seeAlso": ["Notre Père", "Psaumes", "Liturgie des Heures"],
  "clusters": ["priere"],
  "totalRefs": 294,
  "refsCovered": [28, 122, 197, "…"],
  "standalone": false,
  "url": "/glossaire/priere"
}

Cette route est la seule dont les champs sont en camelCase : elle sert l'entrée du glossaire telle qu'elle est stockée. directRefs réunit les paragraphes cités par l'entrée elle-même, refsCovered y ajoute ceux des sous-entrées.

Blocs d'étude

/api/cec/[number] et /api/cec acceptent un paramètre include qui joint les données du panneau d'étude à la réponse : cited_by, themes, sources, liturgy, compendium, en_bref, bible, cdse, denzinger. La valeur all les joint tous.

GET /api/cec/2559?include=cited_by,themes,sources

{
  "number": 2559,
  "text": "« La prière est l'élévation de l'âme vers Dieu…",

  "cited_by": [2613, 2628, 2733, 2736],

  "themes": [
    { "name": "Dieu", "slug": "dieu", "glossary_url": "/glossaire/dieu" },
    { "name": "Humilité", "slug": "humilite", "glossary_url": "/glossaire/humilite" }
  ],

  "sources": {
    "refs": [
      { "type": "patristic",
        "raw": "saint Jean Damascène, de fide orthodoxa 3:24 : PG 94:1089D",
        "display": "saint Jean Damascène, de fide orthodoxa 3:24 : PG 94:1089D" }
    ],
    "documents": []
  }
}

Le bloc bible résout les citations scripturaires du paragraphe : il donne le livre, le chapitre, les versets et une adresse vers le lecteur biblique, plus la forme française dans display.

GET /api/cec/2559?include=bible

{
  "bible": [
    {
      "text": "Lc 18:9-14",
      "display": "Lc 18, 9-14",
      "book": "LUK",
      "book_slug": "luc",
      "book_name": "Luc",
      "chapter": 18,
      "verse_start": 9,
      "verse_end": 14,
      "url": "/bible/luc/18/9"
    }
  ]
}

Une référence sans verset (Ap 4) a verse_start et verse_end à null et une adresse de chapitre. Une abréviation que le serveur ne reconnaît pas revient avec ses champs à null et son text intact, sans adresse inventée.

Chaque bloc apparaît comme une clé de premier niveau. Sans include, la réponse est exactement celle documentée plus haut. Un bloc qui échoue vaut null et son nom apparaît dans partial : le texte du paragraphe reste servi.

Un bloc sans données pour ce paragraphe se distingue d'un bloc en échec : les blocs de liste (cited_by, themes, compendium, cdse, denzinger, liturgy) renvoient un tableau vide, et en_bref renvoie null pour les paragraphes qu'aucun encadré « En bref » ne résume.

Le bloc ai se demande explicitement et n'est jamais inclus par all. Il sert un commentaire généré automatiquement, marqué "generated": true, qui n'appartient pas au Catéchisme et n'a aucune autorité magistérielle.

Données brutes

Les fichiers JSON qui alimentent le site sont servis tels quels et lisibles depuis un autre domaine. Par exemple /data/cec/cited-by.json contient la relation complète des renvois inverses, paragraphe par paragraphe.

Usage

Pas de clé, pas d'authentification, pas de quota annoncé : merci simplement d'un usage raisonnable. Les réponses sont mises en cache à l'édge Cloudflare, donc les requêtes répétées sur un même paragraphe ou une même recherche sont peu coûteuses.

Toutes les réponses portent l'en-tête Access-Control-Allow-Origin: * : l'API est donc appelable depuis un navigateur, sur n'importe quel domaine. Les erreurs portent un champ code stable (par exemple paragraph_out_of_range) à tester de préférence au message, qui est rédigé en français et peut être reformulé.

L'API est fournie telle quelle, sans garantie de disponibilité. Les champs documentés ici sont stables : de nouveaux champs peuvent s'ajouter, mais aucun champ documenté n'est retiré ni renommé. Une rupture de compatibilité passerait par /api/v2.