Developers

Everything an AI agent or developer needs to integrate with Shalem. All public endpoints are read-only and require no authentication.

Quick start

The fastest way to understand the surface is to fetch /llms-full.txt — a single flat file describing the entire product. For programmatic integration, fetch the OpenAPI 3.1 specification.

# Fetch the agent view
curl https://shalemapp.com/api/agent-view

# Ask a natural-language question (NLWeb)
curl -X POST https://shalemapp.com/ask \
  -H "Content-Type: application/json" \
  -d '{"query": "I'\''m anxious about a job interview tomorrow."}'

# Stream an /ask response
curl -X POST https://shalemapp.com/ask \
  -H "Content-Type: application/json" \
  -H "Prefer: streaming" \
  -d '{"query": "What does Jewish tradition say about grief?"}'

Authentication

Public endpoints (/api/agent-view, /llms.txt, /llms-full.txt, /openapi.json, /sitemap.xml, /ask, and the MCP endpoint at /mcp) require no authentication. The OAuth Protected Resource metadata at /.well-known/oauth-protected-resource declares scopes_supported: [] for the free tier.

Agents that need to identify themselves can sign requests using the Web Bot Auth directory at /.well-known/http-message-signatures-directory (RFC 9421).

Endpoints

Method	Path	Description
GET	`/api/agent-view`	Structured JSON view of Shalem for agent consumption.
POST	`/ask`	NLWeb-compatible natural-language query endpoint. SSE streaming via `Prefer: streaming`.
POST	`/mcp`	MCP Streamable HTTP transport (JSON-RPC 2.0).
GET	`/llms.txt`	Plain-text agent summary.
GET	`/llms-full.txt`	Full single-document reference.
GET	`/openapi.json`	OpenAPI 3.1 specification.
GET	`/sitemap.xml`	XML sitemap of indexable URLs.
GET	`/index.md`	Homepage as markdown. Also via `Accept: text/markdown` on `/`.

Discovery files

Shalem implements a comprehensive set of agent-discovery standards:

/.well-known/ai-plugin.json — OpenAI plugin manifest
/.well-known/agent-card.json — A2A (Agent-to-Agent) card
/.well-known/mcp/server-card.json — MCP server card
/.well-known/api-catalog — RFC 9727 API catalog (linkset)
/.well-known/oauth-protected-resource — RFC 9728 OAuth metadata
/.well-known/http-message-signatures-directory — RFC 9421 Web Bot Auth
/.well-known/agent-skills/index.json — Agent Skills v0.2.0 index

NLWeb /ask example

The /ask endpoint follows the Microsoft NLWeb protocol. It accepts a natural-language query and returns a JSON object with a _meta block, the matched citations, and an optional 3-day practice.

POST /ask HTTP/1.1
Host: shalemapp.com
Content-Type: application/json

{ "query": "I'm anxious about a job interview tomorrow." }

Response:

{
  "_meta": {
    "response_type": "answer",
    "version": "1.0.0",
    "request_id": "...",
    "generated_at": "2026-05-04T..."
  },
  "query": "I'm anxious about a job interview tomorrow.",
  "answer": "...",
  "citations": [
    {
      "source": "Tehillim 121",
      "text": "I lift my eyes to the mountains...",
      "reference": "https://www.sefaria.org/Psalms.121"
    }
  ],
  "practice": {
    "days": [
      { "day": 1, "title": "Echo", "description": "..." },
      { "day": 2, "title": "Naming", "description": "..." },
      { "day": 3, "title": "Walking", "description": "..." }
    ]
  }
}

MCP integration

The MCP server is reachable at /mcp over Streamable HTTP. Available tools:

reflect_on_moment — Generate a personalized Jewish reflection for an emotional state.
find_psalm — Recommend a specific Tehillim for a need.
list_practices — List the categories of spiritual practices Shalem supports.

For a Claude Desktop integration, add this to your MCP config:

{
  "mcpServers": {
    "shalem": {
      "url": "https://shalemapp.com/mcp"
    }
  }
}

Rate limits

All endpoints respond with the following headers when applicable:

X-RateLimit-Limit — Maximum requests in the current window.
X-RateLimit-Remaining — Requests remaining.
X-RateLimit-Reset — Unix timestamp when the window resets.
Retry-After — Seconds to wait when rate-limited (HTTP 429).

Error format

Errors are returned as structured JSON with the following shape:

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Try again in 60 seconds.",
    "resolution": "Wait for the period indicated in Retry-After before retrying.",
    "documentation_url": "https://shalemapp.com/developers#errors"
  }
}

Source corpus

The matching engine retrieves from 1,278 curated source texts: Tanakh (with emphasis on Tehillim — the 150 Psalms), Talmud passages, Midrash, Hasidic stories, Maimonides, Shulchan Aruch, traditional liturgy, and selected modern rabbinic literature. The corpus is curated, not exhaustive — Shalem does not retrieve from the entire Talmud or pasken halacha.

Constraints

Shalem will not:

Invent source citations.
Pasken halacha (issue rabbinic rulings).
Diagnose mental-health conditions or substitute for clinical care.
Retain user input after processing.

Contact

Integration questions: support@shalemapp.com. Operated by Zan - Zari Labs OÜ (Estonian registry 17286420).