The public API
Five GET endpoints under https://connectbyjbrh.com/api/public/ search, fetch, list and describe the public documentation, plus one manifest reader. They need no credential, take no writes, and reach no workspace. /api/health is the only other path in the published description.
The endpoints#
| Endpoint | Parameters | Returns |
|---|---|---|
GET /api/public/docs/search | q (2–200 chars, required), limit 1–25 (default 10), kind, status, channel | {query, count, results[]} — ranked page summaries |
GET /api/public/docs/page | ref (required, ≤300 chars), body (default true) | One page with its Markdown body and related list |
GET /api/public/docs/list | kind, status, channel, audience, limit 1–1000 (default 100) | {count, items[]} in path order |
GET /api/public/docs/status | — | Product, version, generated date, the five status words, every capability's status, corpus counts |
GET /api/public/docs/manifest/{name} | name in the path | One generated manifest as JSON |
GET /api/health | — | {ok: true} — the only health path there is |
curl -sS 'https://connectbyjbrh.com/api/public/docs/search?q=held+draft&limit=3'
curl -sS 'https://connectbyjbrh.com/api/public/docs/page?ref=/docs/email/held-drafts/'
curl -sS 'https://connectbyjbrh.com/api/public/docs/list?kind=workflow&limit=50'
curl -sS 'https://connectbyjbrh.com/api/public/docs/status'What a response carries#
Every page summary has the same fields wherever it appears: id, kind, url, markdown, title, description, summary, status, audiences, channels and updated. Search results add a score; a fetched page adds body, body_format and related. The summary is the page's answer-first paragraph, which is written to stand alone — for many questions it is the whole answer and a fetch is unnecessary.
status is the field to branch on. available and available_owner describe something running; foundation means the model, service and tests exist while the usable capability is deliberately narrower; not_yet means designed and not built; reference means background with Connect's own use stated separately on the page.
Successful responses carry Cache-Control: public, max-age=300 and Access-Control-Allow-Origin: *. The corpus changes on a deploy rather than per request, so caching for five minutes costs nothing in freshness and a browser client can call the API directly without a proxy.
The boundary#
This is not the application's API. The application's own OpenAPI document, /docs and /redoc, is closed and stays closed. A route reaches the published description only by being written there *and* listed in the generator's allowlist, so opening an internal endpoint cannot publish it by accident — which is the failure mode this arrangement exists to prevent.
Nothing here reaches a workspace. Every handler calls the same documentation module that serves the website's own pages, so there is no session to hold, no workspace scope to get wrong, and no write path to protect. The paths sit under /api/public/ so the middleware rule that authentication applies to /api carries one visible exception rather than a scatter of special cases.
Using it well#
- Search first, then fetch the winner. A search result carries a summary, which is enough to choose a page and often not enough to answer from.
- Prefer
docs/statusover inference. One call returns every capability's status word; guessing from prose is how an integration starts claiming something Connect does not do. - Cache on
updated. It is a date on every page and it moves only when the page is regenerated. - Walk with
list, not with repeated searches. Listing is ordered by path and stable between calls; search is ranked and its order depends on the query. - Ask for
body=falsewhen you only need metadata; the body is the expensive part of a fetch.
Questions#
Is there a sandbox or a test host?
The production host is the only one, and since every call is a read of public documentation there is nothing to damage by calling it. Testing against Connect safely covers what that means for a client's test suite.
What happens if I ask for a page that does not exist?
HTTP 404 with {"error": {"code": "not_found", "message": …}}, and the message suggests searching first. The shapes are on API error shapes.
Can I use this API to build a competing documentation site?
The API returns published documentation and the site terms apply to it, as the description's licence field says. Nothing technical stops you reading it; attribution and terms are a separate question from access.