API and data
Pshat aims to be the best structured, citable source of Torah knowledge, for people and for machines: apps, educators, researchers and AI assistants. The API is free and open, with no keys and no paid tiers, and the site itself uses the same API as everyone else.
The public API is being built. This page describes it as it's planned; meanwhile, this preview reads the same shapes from a small local release.
Principles
- Every answer carries its proof: sources (refs and quotes), a citation, the license, and a link to the page's history.
- Stable identifiers: immutable IDs, canonical refs compatible with Sefaria's, permanent addresses, and responses pinned to a release.
- Structure over prose: items, views with their standing, claims and rulings as typed JSON, not HTML.
- Simple to start: readable addresses, sensible defaults, an OpenAPI spec, examples.
- Free and open: no keys, no paid tiers; heavy users download the releases.
- The site uses the same API as everyone else, so the API is always complete.
Base and versions
https://api.pshat.org/v1/…, with an OpenAPI 3.1 spec at/v1/openapi.json.- Breaking changes go to
/v2;/v1stays supported for at least 12 months after/v2ships. ?release=…reads from an immutable snapshot; the default is the latest.- JSON by default, and JSON-LD with
Accept: application/ld+json. - Common parameters:
lang=en|he,level=1|2,community=ashkenazi|sephardi|chabad,include=….
Resources
| Endpoint | Returns |
|---|---|
| GET /v1/refs/parse?q=gen 12 5 | Canonical refs from any input (“Gen 12:5”, “בראשית יב ה”, “Lech Lecha 4”) |
| GET /v1/units/{ref} | One unit of any text, assembled: texts, explanations, questions and views, mentions, links, context |
| GET /v1/texts/{ref} | Raw text by version and language, respecting each version's license |
| GET /v1/texts/{ref}/tokens | Words with glosses, roots and parts (Tanach) |
| GET /v1/divisions/{kind}/{slug} | A parsha, aliyah, perek, episode, sugya or siman, with ranges and summaries |
| GET /v1/entities/{kind}/{slug} | An entity of any kind: names, claims (with disputes), mentions, relations; with include=angles, its hub |
| GET /v1/entities?kind=person&q=… | Entities by any name or alias |
| GET /v1/halacha/{slug} | A halacha page: rulings per community, reasons, the source trail |
| GET /v1/prayers/{slug}?rite=ashkenaz | A prayer: when, structure, key words, why, differences between rites, the text where licensed |
| GET /v1/occasions/{slug}?year=5787 | An occasion: that year's dates, what, why and how, the story, prayers, Torah readings |
| GET /v1/calendar?from=…&to=… | Occasions, Rosh Chodesh, fasts and the weekly parsha in a date range |
| GET /v1/lists/{slug} | A list: its defining source, ordered members, disputes |
| GET /v1/links?ref=…&kind=… | Typed links from or to a passage |
| GET /v1/search?q=… | Intent-first search: refs, hubs, halacha, prayer and occasion pages, Hebrew words, questions |
| GET /v1/changes?page=…&since=… | The changelog: one page's history, or every change since a date |
| GET /v1/releases | Releases with download addresses, checksums and notes |
AI access
- An MCP server with tools for assistants (
lookup_ref,explain_unit,get_entity,search,halacha,occasion,find_sources); every result includes sources and a citation. - /llms.txt: a plain-language map of the site and the API for language models.
- JSON-LD on every page, with schema.org types.
- Crawling is welcome, for every crawler, with a sitemap and stable addresses. No blocking, no anti-scraping.
- How to cite Pshat, for people and machines.
Limits and caching
No API keys. Cached responses are unlimited; uncached ones (search, live queries) have generous
limits per address, only to keep the service up. Every response has ETag and Cache-Control, and release-pinned responses can be cached forever. Errors follow
RFC 9457 (problem+json), with a clear message and a fix.
Data releases
Bulk data comes as releases: JSONL (and Parquet), one file per table or layer, with checksums and a manifest, monthly at first and then weekly. Each release states the license of every layer and includes the changelog for its period.
Licensing
Pshat's own content and data are public domain (CC0 1.0): explanations, claims, structure, links, lists and the changelog. Use them for anything. Imported texts keep their own licenses, stated in every response and release (see Credits).