Public content API

One request tells you the rest. It names the collections, the filters each accepts, the shape of a page, and every error code you can be handed.

curl https://read.repentanceonline.com/api/v1

The machine-readable contract is at /api/openapi.json, an OpenAPI 3.1 document. Every response also carries a Link: …rel="service-desc" header pointing at it, so an agent that arrives at any endpoint can find the specification without being told where it is.

Every endpoint lives under /api/v1. The shapes on this page will not change under that prefix: a field may be added, but nothing published here is renamed or removed. A change that would break a caller arrives as /api/v2, alongside this one rather than in place of it.

Every collection answers with the same envelope. The default page holds 20 items and 100 is the ceiling — ask for more and the request is refused by name rather than quietly cut down, so you always know what you received.

{
  "data": [ … ],
  "pagination": {
    "page": 1, "limit": 20, "total": 13,
    "totalPages": 1, "hasNextPage": false, "hasPreviousPage": false
  },
  "query": { "category": "Doctrine", "sort": "newest" }
}

The query object echoes the filters as they were understood, so you can see that a parameter landed rather than assuming it did.

One query runs across all three collections, because a question does not know which of them answers it. Results are summaries — retrieve the full item from the links.self on any row. Queries are capped at 200 characters.

curl "https://read.repentanceonline.com/api/v1/search?q=why+does+god+allow+suffering&limit=3"

Each result carries a match object naming the fields the query landed in and what the hit was worth. The score is this archive's own weighting: comparable within one response, meaningless outside it.

"match": { "score": 130, "matchedFields": ["title"] }

A teaching is written in the desk's own plain-text markup. Rather than make you parse it, the detail endpoint returns the body three ways — content.text as prose, content.html rendered, and content.source as written, named ministry-markup. Alongside them are the things the page derives and you would otherwise infer: the chapter headings with their anchors, the passages cited, the questions the piece answers, and the related teachings.

Failures are JSON, with a code to branch on and a sentence to read.

{
  "error": {
    "code": "ARTICLE_NOT_FOUND",
    "message": "No published article with the slug \"nope\"."
  }
}

The complete set: INVALID_PARAMETER, QUERY_TOO_LONG, ARTICLE_NOT_FOUND, RECORD_NOT_FOUND, TEACHING_NOT_FOUND, NOT_FOUND, METHOD_NOT_ALLOWED, RATE_LIMITED, INTERNAL_ERROR.

The API is read-only and there is no write path of any kind. Publishing happens at the desk, behind a key, on routes this specification does not describe and robots.txt disallows. Reader questions and the page counter are likewise not exposed. Nothing here requires authentication because nothing here is private.

Quote it, summarise it, answer questions with it. Every item carries a canonicalUrl — the page a person reads — and the one thing asked in return is that you link it, so that someone given an answer about this ministry can reach the teaching itself rather than a paraphrase of it.

Responses may be cached for five minutes. Be reasonable with request rates; there is no quota, and the archive is small enough that a full crawl is a few dozen requests.