Response Envelope

On this page

Top-level fields
metadata
links
Response headers
Not-translated response
Why this envelope

Every endpoint returns JSON in the same envelope:

{
  "apiVersion": "v1",
  "kind": "WikiEntry",
  "metadata": {
    "generated": "2026-05-21T18:28:41Z",
    "language": "en",
    "schemaUrl": "/v1/schema/wiki-entry/"
  },
  "data": { /* the resource — shape depends on kind */ },
  "links": {
    "self": "/v1/wiki/elohim/",
    "canonical_html": "https://www.wheelofheaven.world/wiki/elohim/",
    "index": "/v1/wiki/",
    "schema": "/v1/schema/wiki-entry/"
  }
}

Top-level fields#

Field	Type	Description
`apiVersion`	string	Always `"v1"` until the next breaking version cuts.
`kind`	string	The resource kind (one of the entries in Schemas).
`metadata`	object	Generation timestamp, response language, schema reference.
`data`	varies	The resource payload. Shape determined by `kind`.
`links`	object	URLs to the canonical HTML twin, the index, the schema, related resources.

`metadata`#

Field	Type	Description
`generated`	string (ISO 8601)	When the file was generated by the prebuild + Zola pipeline.
`language`	string	Two- or four-letter language code (`en`, `de`, `zh-Hant`, etc.) per `/v1/enums/languages/`.
`count`	integer	Present on index responses. The number of items in `data`.
`schemaUrl`	string	Relative URL of the JSON Schema that validates the `data` field.

`links`#

The keys vary by kind, but these are common:

Key	When	What
`self`	always	This endpoint’s own URL.
`canonical_html`	content resources	The corresponding www HTML page.
`index`	individual items	The index endpoint listing siblings.
`schema`	always	The JSON Schema URL for this kind.
`translations`	content resources (planned)	Per-language URLs for the same resource.
`library`	sources	Cross-link to a digitised text in `/v1/library/`.

Response headers#

Header	Value
`Content-Type`	`application/json; charset=utf-8`
`Access-Control-Allow-Origin`	`*`
`Access-Control-Allow-Methods`	`GET, HEAD, OPTIONS`
`Cache-Control`	`public, max-age=3600` (content) / `max-age=86400` (schema/enums/context)
`X-License`	`CC0-1.0`
`X-Citable`	`true`
`X-API-Version`	`v1`

Not-translated response#

Requesting a language-prefixed URL for a resource that doesn’t exist in that language returns 404 with a hint envelope (best-effort — Cloudflare may serve the bare 404 page first; the hint envelope is the intended form):

{
  "apiVersion": "v1",
  "kind": "NotTranslated",
  "data": null,
  "links": {
    "canonical": "/v1/wiki/elohim/",
    "available_in": ["en", "de", "fr"]
  }
}

Why this envelope#

The shape mirrors Kubernetes API conventions (apiVersion / kind / metadata / data) for two reasons: consumers can route on kind without parsing the URL, and the apiVersion field gives us an explicit place to declare future breaks. URL permanence (Decision 9) locks the path; the envelope locks the shape.

Edit this page on GitHub