# JewishMythology.com public API

> Unauthenticated semantic search, Maggid RAG, and Maggid chat over a sourced Jewish myth anthology. No API keys. No OAuth. No paid tiers.

Contract: [OpenAPI 3.1](https://jewishmythology.com/openapi.json) · Catalog: [RFC 9727 api-catalog](https://jewishmythology.com/.well-known/api-catalog) · Auth: [auth.md](https://jewishmythology.com/auth.md)

## 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/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/`.

## Authentication

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

## Versioning

- Responses send `API-Version: 1`.
- Canonical prefix: `/api/v1/…`
- Unversioned `/api/…` is an alias of v1 while 1.x stays 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.

```
RateLimit-Policy: "default";q=60;w=60
RateLimit: "default";r=59;t=60
```

HTTP `429` also sends `Retry-After`. Back off and retry with jitter.

## Errors

Every failed JSON call returns RFC 9457 `application/problem+json`. `error` is a legacy alias of `detail` for existing browser clients.

```json
{
  "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)."
}
```

POST-only operations return **405** on GET (not an empty 404), with `Allow: POST, OPTIONS`.

<a id="invalid-json"></a>
### invalid-json

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

<a id="invalid-query"></a>
### invalid-query

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

<a id="content-too-long"></a>
### content-too-long

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

<a id="method-not-allowed"></a>
### method-not-allowed

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

<a id="rate-limit"></a>
### rate-limit

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

<a id="embedding-failed"></a>
### embedding-failed

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

<a id="not-found"></a>
### not-found

`404` — no API operation at this path.

<a id="gone"></a>
### gone

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

## Endpoints

### `POST /api/v1/semantic-search`

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

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

Returns `{ "results": [ { "id", "type", "title", "slug", "canonicalUrl", "snippet", "score" } ] }`.

### `POST /api/v1/ai-search`

Same JSON body (`query` required, optional `history`). Response is `text/event-stream`. Events are JSON: `{ "sources": [...] }` then `{ "token": "..." }` chunks. Stream errors are `{ "error": "..." }` events, not RFC 9457 (the HTTP envelope already opened as 200).

### `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.

## Discovery

- [llms.txt](https://jewishmythology.com/llms.txt)
- [auth.md](https://jewishmythology.com/auth.md)
- [Agent skills](https://jewishmythology.com/.well-known/agent-skills/index.json)
- [Homepage markdown](https://jewishmythology.com/index.md)
- [Contact](https://jewishmythology.com/contact)