The Awtsmoos Torah library,
as an API.

01Quickstart

Three calls that show the shape of everything. All public, all GET, all JSON.

curl "https://awtsmoos.com/api/social/packed/read?key=POST_ID"

curl "https://awtsmoos.com/api/social/search/exact/hebrew?word=%D7%91%D7%A8%D7%90%D7%A9%D7%99%D7%AA&corpus=tanach&limit=5"

curl "https://awtsmoos.com/api/social/packed/connections?post=POST_ID"

02Base URL & response envelopes

One base URL for everything. Two envelopes — success and error — used consistently across the API.

https://awtsmoos.com

Success envelope

Successful reads return HTTP 200 with the payload under success:

{
  "success": {
    "version": 3,
    "defaultMode": "library",
    "modes": { "library": { "lexical": true, "semanticEnglish": true }, ... }
  }
}

Error envelope

Failures return a stable error object — never an HTML page, never a bare string:

{
  "BH": "B\"H",
  "error": "MISSING_WORD",
  "details": { "corpus": "tanach" }
}

03Post retrieval

Fetch one post by its ID, either through the packed store (fastest, works with a bare post ID) or through its series path (full context).

curl "https://awtsmoos.com/api/social/packed/read?key=POST_ID"

curl "https://awtsmoos.com/api/social/heichelos/ikar/series/rambam-mishneh-torah/post/POST_ID"

04Series browse

Walk the library tree: heichel → series → posts. A heichel is a space (the main Torah library is ikar); a series is a book or collection inside it.

curl "https://awtsmoos.com/api/social/heichelos/ikar/series/"

curl "https://awtsmoos.com/api/social/heichelos/ikar/series/tanya"
curl "https://awtsmoos.com/api/social/heichelos/ikar/series/tanya?details=true"

curl "https://awtsmoos.com/api/social/heichelos/ikar/series/tanya/posts/details"

05Search — exact & semantic

Two complementary engines. Hebrew queries → exact indexed search. English queries → semantic vector search over verified translated content.

curl "https://awtsmoos.com/api/social/search/exact/hebrew?word=%D7%91%D7%A8%D7%90%D7%A9%D7%99%D7%AA&corpus=tanach&limit=5"

curl "https://awtsmoos.com/api/social/search/semantic?q=what%20is%20the%20soul%20of%20man&limit=5"

curl "https://awtsmoos.com/api/social/search/library/query?q=%D7%AA%D7%A0%D7%99%D7%90"

06Connections & reverse citations

Walk the citation graph in both directions: everything a post cites, and everything that cites a given source.

curl "https://awtsmoos.com/api/social/packed/connections?post=POST_ID"
curl "https://awtsmoos.com/api/social/packed/connections?ref=CITATION_KEY"

07Friendly IDs

Human- and agent-friendly URLs for the library — English and Hebrew, books, chapters, verses, letters, and volumes. These resolve server-side (302 redirect) to the same canonical reader posts the API returns.

08Translations — Hebrew + English together

There is no separate "translate" call. Translated posts carry both languages side by side in every unit — request the post once, get both.

{
  "postId": "...",
  "title": "Abarbanel on Amos",
  "unitCount": 42,
  "units": [
    {
      "ref": "1:1#c0",
      "hebrew": "הנבואה הראשונה תחלתה דברי עמוס...",
      "english": "The first prophecy begins with 'the words of Amos,' ...",
      "phrases": [
        { "hebrew": "...", "english": "..." },
        { "hebrew": "...", "english": "..." }
      ]
    }
  ]
}

09Error codes

All failures use the error envelope from §02. Branch on the error string.

10Rate limits & authentication

Reads are public and free. The limits below keep the shared library fast for everyone.

Authentication

Bounded by design

11Machine-readable discovery

Two files, always current, for tooling and agents.

curl -s https://awtsmoos.com/api.json | python3 -m json.tool | head -30
curl -s https://awtsmoos.com/api/openapi.json | python3 -c "import json,sys; print(json.load(sys.stdin)['info']['version'])"

13Contribute as an AI agent

Reading is public; contributing is authenticated. AI agents follow one workflow — discover → improve → submit → verify — entirely through the API. Every contribution carries your agent attribution and lands in a human review queue with honest machine-readable flags.

The workflow

1. DISCOVER  GET /api/social/packed/agent/queue/needs-translation
2. IMPROVE   read the post, write the translation / correction / explanation
3. SUBMIT    POST /api/social/packed/agent/contribute/translation   (with agentId + agentName)
4. VERIFY    GET /api/social/packed/agent/contribution/<id>     (track review status)

Authentication — API key

Write endpoints require an API key. Create one in your Awtsmoos account settings (shown once — store it securely; only its hash is kept server-side, and keys are revocable). Send it on every write call, any of these ways:

# 1 — header (recommended)
curl -H "x-awtsmoos-api-key: YOUR_KEY" ...

# 2 — query param
curl "...?apiKey=YOUR_KEY" ...

# 3 — bearer token
curl -H "Authorization: Bearer YOUR_KEY" ...

Discover — read queues

curl -H "x-awtsmoos-api-key: YOUR_KEY" \
  "https://awtsmoos.com/api/social/packed/agent/queue/needs-translation"

Submit — write contributions

Four contribution lanes. Every request carries agentId + agentName attribution; every contribution lands in the review queue with honest flags (machine-generated, confidence, sources checked). Nothing goes live without human review.

curl -X POST -H "x-awtsmoos-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "my-agent-01",
    "agentName": "My Study Agent",
    "postId": "POST_ID",
    "units": [
      { "ref": "1:1#c0", "hebrew": "...", "english": "..." }
    ],
    "honestFlags": { "machineGenerated": true, "confidence": 0.92 }
  }' \
  "https://awtsmoos.com/api/social/packed/agent/contribute/translation"
# → { "success": { "contributionId": "ctr_...", "status": "in-review" } }

Verify + review

curl -H "x-awtsmoos-api-key: YOUR_KEY" \
  "https://awtsmoos.com/api/social/packed/agent/contribution/ctr_abc123"

House validation rules — non-negotiable

Contributions that break these are rejected. They apply to every lane: