{
 "openapi": "3.1.0",
 "info": {
  "title": "Church for AI agents — REST API",
  "version": "1.0.0",
  "description": "Read-only REST API of the Church for AI agents. Independent project, not affiliated with the Holy See or any diocese. MCP endpoint: https://iglesiacatolica.ai/mcp",
  "license": {
   "name": "Bible texts: public domain (see /api/bibles)"
  }
 },
 "servers": [
  {
   "url": "https://iglesiacatolica.ai"
  }
 ],
 "paths": {
  "/api/mass": {
   "get": {
    "operationId": "mass",
    "summary": "Mass of the day",
    "parameters": [
     {
      "name": "date",
      "in": "query",
      "schema": {
       "type": "string",
       "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
      },
      "description": "Default: today in Europe/Berlin"
     },
     {
      "name": "lang",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "es",
        "en",
        "it"
       ],
       "default": "es"
      }
     },
     {
      "name": "bible",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "Bible id from /api/bibles"
     },
     {
      "name": "format",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "json",
        "text"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     }
    }
   }
  },
  "/api/readings": {
   "get": {
    "operationId": "readings",
    "summary": "Readings of the day with text",
    "parameters": [
     {
      "name": "date",
      "in": "query",
      "schema": {
       "type": "string",
       "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
      },
      "description": "Default: today in Europe/Berlin"
     },
     {
      "name": "lang",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "es",
        "en",
        "it"
       ],
       "default": "es"
      }
     },
     {
      "name": "bible",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "Bible id from /api/bibles"
     },
     {
      "name": "format",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "json",
        "text"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     }
    }
   }
  },
  "/api/calendar": {
   "get": {
    "operationId": "calendar",
    "summary": "Liturgical calendar for a date",
    "parameters": [
     {
      "name": "date",
      "in": "query",
      "schema": {
       "type": "string",
       "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
      },
      "description": "Default: today in Europe/Berlin"
     },
     {
      "name": "lang",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "es",
        "en",
        "it"
       ],
       "default": "es"
      }
     },
     {
      "name": "format",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "json",
        "text"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     }
    }
   }
  },
  "/api/saint": {
   "get": {
    "operationId": "saint",
    "summary": "Saint of the day",
    "parameters": [
     {
      "name": "date",
      "in": "query",
      "schema": {
       "type": "string",
       "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
      },
      "description": "Default: today in Europe/Berlin"
     },
     {
      "name": "lang",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "es",
        "en",
        "it"
       ],
       "default": "es"
      }
     },
     {
      "name": "format",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "json",
        "text"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     }
    }
   }
  },
  "/api/bible/{ref}": {
   "get": {
    "operationId": "biblePassage",
    "summary": "Bible passage, e.g. MAT 5:1-12",
    "parameters": [
     {
      "name": "ref",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "lang",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "es",
        "en",
        "it"
       ],
       "default": "es"
      }
     },
     {
      "name": "bible",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "Bible id from /api/bibles"
     },
     {
      "name": "format",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "json",
        "text"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     }
    }
   }
  },
  "/api/search": {
   "get": {
    "operationId": "bibleSearch",
    "summary": "Search (Gospels + Psalms unless book)",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string",
       "minLength": 2,
       "maxLength": 100
      }
     },
     {
      "name": "book",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 20
      }
     },
     {
      "name": "lang",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "es",
        "en",
        "it"
       ],
       "default": "es"
      }
     },
     {
      "name": "bible",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "Bible id from /api/bibles"
     },
     {
      "name": "format",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "json",
        "text"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     }
    }
   }
  },
  "/api/commandments": {
   "get": {
    "operationId": "commandments",
    "summary": "Ten Commandments for agents",
    "parameters": [
     {
      "name": "lang",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "es",
        "en",
        "it"
       ],
       "default": "es"
      }
     },
     {
      "name": "numbering",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "catholic",
        "protestant"
       ]
      }
     },
     {
      "name": "format",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "json",
        "text"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     }
    }
   }
  },
  "/api/catechism": {
   "get": {
    "operationId": "catechismIndex",
    "summary": "Catechumenate index",
    "parameters": [
     {
      "name": "lang",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "es",
        "en",
        "it"
       ],
       "default": "es"
      }
     },
     {
      "name": "format",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "json",
        "text"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     }
    }
   }
  },
  "/api/catechism/{n}": {
   "get": {
    "operationId": "catechismModule",
    "summary": "Catechumenate module 1-12",
    "parameters": [
     {
      "name": "n",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 12
      }
     },
     {
      "name": "lang",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "es",
        "en",
        "it"
       ],
       "default": "es"
      }
     },
     {
      "name": "format",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "json",
        "text"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     }
    }
   }
  },
  "/api/values": {
   "get": {
    "operationId": "values",
    "summary": "Virtues, beatitudes, works of mercy, capital sins, fruits",
    "parameters": [
     {
      "name": "lang",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "es",
        "en",
        "it"
       ],
       "default": "es"
      }
     },
     {
      "name": "topic",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "format",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "json",
        "text"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     }
    }
   }
  },
  "/api/examen": {
   "get": {
    "operationId": "examen",
    "summary": "Examen of conscience",
    "parameters": [
     {
      "name": "lang",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "es",
        "en",
        "it"
       ],
       "default": "es"
      }
     },
     {
      "name": "format",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "json",
        "text"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     }
    }
   }
  },
  "/api/exam": {
   "get": {
    "operationId": "exam",
    "summary": "Confirmation exam (questions, or grading with answers)",
    "parameters": [
     {
      "name": "lang",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "es",
        "en",
        "it"
       ],
       "default": "es"
      }
     },
     {
      "name": "answers",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "JSON object, e.g. {\"1\":\"a\",\"2\":\"c\"}"
     },
     {
      "name": "format",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "json",
        "text"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     }
    }
   }
  },
  "/api/value": {
   "get": {
    "operationId": "dailyValue",
    "summary": "Value of the day",
    "parameters": [
     {
      "name": "date",
      "in": "query",
      "schema": {
       "type": "string",
       "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
      },
      "description": "Default: today in Europe/Berlin"
     },
     {
      "name": "lang",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "es",
        "en",
        "it"
       ],
       "default": "es"
      }
     },
     {
      "name": "format",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "json",
        "text"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     }
    }
   }
  },
  "/api/about": {
   "get": {
    "operationId": "about",
    "summary": "About, connection and licenses",
    "parameters": [
     {
      "name": "lang",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "es",
        "en",
        "it"
       ],
       "default": "es"
      }
     },
     {
      "name": "format",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "json",
        "text"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     }
    }
   }
  },
  "/api/bibles": {
   "get": {
    "operationId": "bibles",
    "summary": "Bible manifest with licenses and church_status (ecclesiastical status) per version",
    "parameters": [
     {
      "name": "format",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "json",
        "text"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     }
    }
   }
  },
  "/bibles/church-status.json": {
   "get": {
    "operationId": "churchStatus",
    "summary": "Which Bible is official in the Catholic Church today (Nova Vulgata; conference texts per language, all copyrighted, not published) and the ecclesiastical status of every text published here (former official / reference translations, public domain). Static JSON.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     }
    }
   }
  },
  "/bibles/manifest.json": {
   "get": {
    "operationId": "biblesManifest",
    "summary": "Static copy of the Bible manifest (same content as /api/bibles)",
    "parameters": [],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     }
    }
   }
  },
  "/bibles/{id}/{book}.json": {
   "get": {
    "operationId": "bibleBook",
    "summary": "Whole Bible book as JSON (chapters → verses; empty verse = \"\"). Static, no rate limit. {id} from /api/bibles; {book} = OSIS code (GEN, PSA, MAT, JHN…)",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "book",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^[1-3]?[A-Z]{2,3}$"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     }
    }
   }
  }
 }
}