API endpoints for AI agents

The full API endpoint catalogue lives at API Reference → Endpoints. This page is the AI-oriented subset — the endpoints that matter when you’re building an agent, a RAG pipeline, or any system that needs to read the corpus programmatically.

For the why and how of the API itself (build pipeline, design principles, hosting), see Architecture → API.

The response envelope, briefly#

Every response shares the shape:

{
  "apiVersion": "v1",
  "kind": "WikiEntry",
  "metadata": {
    "slug": "elohim",
    "lang": "en",
    "permalink": "https://api.wheelofheaven.world/v1/wiki/elohim/"
  },
  "data": { /* kind-specific payload */ },
  "links": {
    "self": "/v1/wiki/elohim/",
    "schema": "/v1/schema/wiki-entry/",
    "manifest": "/v1/",
    "html": "https://www.wheelofheaven.world/wiki/elohim/"
  }
}

Every consumer endpoint exposes a links.schema pointer and a links.html pointer to the human-readable twin. An ingesting agent can walk the entire surface from /v1/ alone. See API Reference → Envelope for the full spec.

The AI-priority endpoints#

1. Discovery#

Hit these once at boot to learn the surface.

2. Curated context (highest signal-to-token)#

These six endpoints are designed for direct system-prompt ingestion. Each returns a ContextDocument with a data.body field of plain prose. See Curated context endpoints for the full per-endpoint breakdown.

Boot pattern:

import httpx

KEYS = ["hypothesis", "terminology", "timeline", "sources", "method"]
ctx = {
    k: httpx.get(f"https://api.wheelofheaven.world/v1/context/{k}/")
       .json()["data"]["body"]
    for k in KEYS
}

3. Per-page twins (per-query retrieval)#

Each of these gives you the body of a single page, plus its structured metadata. Hit them on demand from a retrieval layer or tool call.

Each per-page endpoint returns data.body_html (rendered HTML), plus the page’s extra table (frontmatter), plus relationships (see_also, references, external_links, etc.). For LLM consumption, you usually want either the HTML stripped to text or the extra.summary field.

Example:

curl https://api.wheelofheaven.world/v1/wiki/elohim/ | jq '.data | {
    title: .title,
    summary: .extra.summary,
    claim_type: .extra.claim_type,
    body_html
}'

4. Library — primary texts at chapter/verse granularity#

Library books are different from other content surfaces in that they have chapter and verse structure. Each chapter is a separate endpoint. See Library and sources for the full deep-dive.

5. Sources — bibliography records#

When you need to know what authority a claim rests on, hit the bibliography endpoint.

6. Glossary#

Multilingual terminology. Useful when your application surfaces the project in a non-English language.

7. Translation provenance#

For the -woh Wheel of Heaven Translations (project-internal re-translations of source texts), the provenance is exposed.

If your application surfaces a WoH Translation, always pair the text with the provenance — the source family of the original, the glossary version used, and the reviewer.

8. Search index (client-side retrieval)#

If you’re building an in-browser agent or want a small embedded index, the API publishes a pre-built Fuse.js-compatible index:

curl https://api.wheelofheaven.world/v1/search/

The index covers wiki, timeline, articles, library, and sources. It is ~1MB JSON, suitable for in-browser fuzzy search. For server-side embedding retrieval, see Embeddings and RAG.

9. Meta — schemas and enums#

If your agent generates structured output (e.g. “build me a wiki entry”), validate against the published schema:

curl https://api.wheelofheaven.world/v1/schema/wiki-entry/
curl https://api.wheelofheaven.world/v1/enums/claim-type/

Available schemas: wiki-entry, timeline-entry, article, dispatch, book, source, tradition-hub, concept-hub, glossary-term, translation, library.

Available enums: authority-tier, source-family, claim-type, event-type, relation-to-wheel, stance, licensing-status, translation-status, languages.

Multilingual access#

Every endpoint above is mirrored under /v1/{lang}/... for de, fr, es, ru, ja, zh, zh-Hant, ko. See API Reference → Multilingual.

curl https://api.wheelofheaven.world/v1/de/wiki/elohim/
curl https://api.wheelofheaven.world/v1/ja/timeline/age-of-leo/

The default English path (no language prefix) is the authoritative source for editorial discipline. Translations are derived from English and may lag a single editorial pass.

Caching and freshness#

Cloudflare purges the entire zone on each deploy, so the upper bound on staleness is the cache TTL, not the time since the last edit.

For a long-running agent, hit /v1/context/* at boot and cache for the session. Hit per-page endpoints on demand and cache for 1 hour.

Rate limiting and auth#

There is no auth and no application-level rate limiting. Cloudflare’s edge protection applies — if you’re hammering the API aggressively, the right pattern is to mirror the data locally via /v1/ walking the sitemap.

For a one-time mirror:

wget --recursive --no-parent --accept '*.json' \
     https://api.wheelofheaven.world/v1/

This works because every endpoint is a static file. The mirror is ~50MB and self-consistent at the time you pulled it.

Common pitfalls#

• Don’t strip the links block. It contains the schema pointer and the html twin URL, which downstream consumers may need.
• Don’t treat body_html as Markdown. It is rendered HTML. Strip to text or render as HTML; don’t try to re-parse as Markdown.
• Watch the extra shape. Frontmatter is page-type specific. Wiki entries have extra.infobox; library books have extra.book; dispatches have extra.event_date. Use the schema endpoint to introspect.
• Translations may lag. Non-English endpoints follow the English by an editorial cycle. If a wiki entry has been rewritten in the current pass but not retranslated, you’ll see the previous-pass version under /v1/{lang}/....