JewishMythology.com public API

When to use this

Use these APIs when an agent needs sourced Jewish myth, midrash, aggadah, Kabbalah, apocrypha, or Maggid anthology stories with citations.

• Ranked hits without a generated answer → POST /api/v1/semantic-search
• A Maggid-voice answer grounded in the anthology → POST /api/v1/ai-search
• Continue an on-page Maggid chat with the current myth pinned → POST /api/v1/chat
• Read a myth or theme as HTML, or send Accept: text/markdown

Do not use this site for comparative religion, Christian or Islamic framing, legal rulings (pesak), or bulk republication of adapted prose. robots.txt disallows /data/.

Machine contract: OpenAPI 3.1 · RFC 9727 catalog · auth.md · llms.txt

Authentication

None. Do not send bearer tokens. Do not expect 401. Admin OAuth (/api/admin/*) is retired (410).

Versioning

Responses send API-Version: 1. The canonical URL prefix is /api/v1/. Unversioned /api/* paths are aliases of v1 while 1.x remains backward compatible. Breaking changes increment the major version and move to /api/v{major}/. Deprecations use RFC 9745 Deprecation and Sunset headers.

Rate limits

60 requests per 60 seconds per IP. Responses include IETF RateLimit and RateLimit-Policy headers. HTTP 429 also sends Retry-After. Back off and retry with jitter.

Errors

Failed JSON calls return RFC 9457 application/problem+json. error is a legacy alias of detail for existing browser clients. POST-only operations return 405 on GET (not an empty 404), with Allow: POST, OPTIONS.

{
  "type": "https://jewishmythology.com/docs#invalid-query",
  "title": "Invalid query",
  "status": 400,
  "detail": "Query required (max 500 chars).",
  "code": "invalid_query",
  "instance": "/api/v1/semantic-search",
  "error": "Query required (max 500 chars)."
}

invalid-json

400 — body is not JSON. Fix the payload; do not retry the same bytes.

invalid-query

400 — query missing, not a string, or longer than 500 characters.

content-too-long

400 — chat content exceeds 12000 characters. Trim the pinned myth body.

method-not-allowed

405 — wrong HTTP method. Read Allow and call POST (or GET on /api/v1/status).

rate-limit

429 — wait Retry-After seconds. Safe to retry.

embedding-failed

502 — query embedding failed. Retry with backoff; no side effects.

not-found

404 — no API operation at this path.

gone

410 — admin OAuth retired. Use the public unauthenticated APIs instead.

Endpoints

POST /api/v1/semantic-search

Embeds the query and returns ranked myth, text, and source hits. No generated answer.

POST /api/v1/semantic-search HTTP/1.1
Host: jewishmythology.com
Content-Type: application/json

{"query":"Who is Lilith?","topK":5}

POST /api/v1/ai-search

Same JSON body (query required, optional history). Response is text/event-stream. Events are JSON: {"sources":[...]} then {"token":"..."} chunks.

POST /api/v1/chat

Same Maggid model, with optional slug, title, and content for the myth the reader is on.

GET /api/v1/status

Liveness JSON. Safe to poll.