API Reference

9 public endpoints for Legal Eye — a Hebrew legal RAG system that returns verbatim citations from real Israeli case law. No auth. Rate-limited.

Overview

Base URL: https://legal-i-legal-eye.hf.space

All endpoints return JSON. Hebrew text is UTF-8 encoded. Most endpoints accept anonymous requests (no auth header). The service is hosted on Hugging Face Spaces (free CPU tier), so cold-start latency may be 30-60 seconds on the first request after idle.

Authentication

Public endpoints: none required. The system is open by design — see /founder for the "why".

Admin endpoints (not documented here): require an X-Admin-Key header matching TAU_RAG_ADMIN_KEY set in the Space's secrets.

Rate limits

Per-IP, sliding window:

Endpoint	Limit	Window
`/v1/demo/analyze`	10 requests	per hour
`/v1/demo/lead`	5 requests	per hour
`/v1/track`	60 requests	per minute
All other public endpoints	no explicit limit	—

Exceeding a limit returns HTTP 429 with {"ok": false, "reason": "rate_limit", "message_he": "..."}.

Error format

Errors generally follow:

{
  "ok": false,
  "reason": "",
  "message_he": ""
}

HTTP status codes: 200 success, 400 bad input, 403 auth required, 404 not found, 429 rate-limited, 500 server error.

Health check

GET /readyz

Returns the status of internal subsystems (retriever, generator, verifier, monitor) and the list of available retrievers.

Response

{
  "ok": true,
  "detail": {
    "retriever": "ok",
    "generator": "ok",
    "retriever_type": "MultiRetriever",
    "retriever_members": ["bm25", "gematria", "hilbert", "graph", "hebrew_encoder"]
  }
}

Example

curl https://legal-i-legal-eye.hf.space/readyz

GET /v1/corpus/inventory

Returns counts of documents per shard + per court + per source. Live data — updates as the corpus grows.

Response (truncated)

{
  "total": 749135,
  "tier_a": 16595,
  "tier_b": 732540,
  "judgments": 732540,
  "tier_b_breakdown": {
    "general": 207442,
    "procedure": 149985,
    "constitutional": 144136,
    // ... 12 more shards ...
  },
  "by_court": { "בית המשפט העליון": 16531 },
  "fetched_at": 1778554410
}

GET /v1/founding50/status

Returns the live Founding 50 counter — powers the urgency widget on the landing page.

Response

{
  "ok": true,
  "taken": 0,
  "total": 50,
  "spots_left": 50,
  "updated_at": 1778616577
}

Query (RAG)

POST /v1/lawyer/ask

The main RAG endpoint. Returns a bundle of arguments synthesized from real Israeli case law. Each argument.text is verbatim from the source case — never generated by an LLM.

Request body

Field	Type	Required	Description
`question`	string	required	Hebrew legal question or claim. ≤500 chars.

Response (truncated)

{
  "ok": true,
  "confidence": "high",
  "domain": "contracts",
  "bundle": {
    "anchor_label": "ע\"א 6328/97",
    "anchor_quote": "פרשנותו של כל חוזה נלמדת...",
    "cluster_score": 1.51,
    "coverage": 0.15,
    "applications": [...],
    "statute_refs": [...]
  },
  "arguments": [
    {
      "polish_method": "graph_bundle",
      "text": "",
      "source_case": "ע\"א 6328/97"
    }
  ]
}

Example

curl -X POST https://legal-i-legal-eye.hf.space/v1/lawyer/ask \
  -H "Content-Type: application/json" \
  -d '{"question": "פרשנות תכליתית של חוזה לפי הלכת אפרופים"}'

✓ Verifiability: every source_case can be looked up on Nevo. This is the defining feature.

POST /v1/hgraph/argument

Bundle-only query (skips the synthesizer). Faster than /v1/lawyer/ask for diagnostic uses (e.g., the eval harness uses this mode).

Request body

Field	Type	Required	Description
`user_facts`	string	required	Hebrew query string.
`retrieval_k`	int	optional, default 20	Top-k candidates per retriever.

Response is just {bundle: {...}} from the same shape as /v1/lawyer/ask.

POST /v1/demo/analyze

Public demo endpoint — powers the landing page widget. Returns a condensed analysis (max 2 pro + 2 con arguments). Rate-limited: 10 requests/hour/IP.

Request body

Field	Type	Required	Description
`claim`	string	required	Hebrew legal claim / question. ≤300 chars.

Response (truncated)

{
  "ok": true,
  "strength_score": 71,
  "strength_caption": "חזקה",
  "pro_arguments": [
    { "text": "...", "source_case": "ע\"א 6328/97" },
    { "text": "...", "source_case": "..." }
  ],
  "con_arguments": [...],
  "locked": { "n_more_pro": 3, "n_more_con": 2 }
}

⚠ Rate limit: 10/hour/IP. HTTP 429 with message_he if exceeded.

Catalog endpoints

GET /v1/doctrines/catalog

Returns the curated catalog of manually-verified Israeli legal doctrines (currently 29 across 12 domains). Used by the /doctrines UI page.

Response (truncated)

{
  "ok": true,
  "n_doctrines": 29,
  "by_domain": {
    "contracts": 5,
    "torts": 4,
    "labor": 4,
    // ... 9 more domains ...
  },
  "doctrines": [
    {
      "id": "parshanut_takhleitit",
      "name_he": "פרשנות תכליתית של חוזה (הלכת אפרופים)",
      "name_en": "Purposive interpretation of contracts",
      "domain": "contracts",
      "anchor_case": "ע\"א 4628/93 מדינת ישראל נ' אפרופים",
      "anchor_year": 1995,
      "n_leading_cases": 3,
      "n_statute_refs": 1
    }
  ],
  "_disclaimer": "Seed catalog written by AI assistant..."
}

GET /v1/clusters

Returns the auto-discovered doctrine clusters (computed by the hierarchical clustering pipeline). This is different from the curated catalog above — clusters are algorithmically grouped (currently ~646), the catalog is hand-verified (29).

Query params

Field	Type	Description
`limit`	int	Max results (default 50, max 200).

Response

{
  "ok": true,
  "n_total": 646,
  "items": [
    {
      "cluster_id": "1f0c2c9694dc",
      "anchor_label": "תקנות סדר הדין האזרחי",
      "size": 1044,
      "n_applications": 1043,
      "domain": "procedure"
    }
  ]
}

Funnel endpoints

POST /v1/track

Log a funnel event. Used internally by our pages (page_view, demo_started, email_submitted, etc.). Stores hashed IP only, no raw PII.

Request body

Field	Type	Required	Description
`event`	string	required	Event name. ≤60 chars.
`page`	string	optional	Page path. ≤120 chars.
`props`	object	optional	Arbitrary props. Capped at 500 chars JSON.
`referrer`	string	optional	Referrer URL. ≤200 chars.

⚠ Rate limit: 60/min/IP.

POST /v1/demo/lead

Capture an email lead from the landing demo widget. Triggers an automated welcome email (via Resend if configured, else queues for manual send).

Request body

Field	Type	Required	Description
`email`	string	required	Valid email address.
`name`	string	optional	≤120 chars.
`claim`	string	optional	Context. ≤600 chars.
`last_analyzed_claim`	string	optional	The query they ran. ≤600 chars.
`source`	string	optional, default "landing_demo"	Channel. ≤60 chars.

⚠ Rate limit: 5/hour/IP.

Versioning

The API path uses a /v1/ prefix. Breaking changes will be introduced under /v2/ with at least 90 days notice. Non-breaking changes (new fields, new endpoints) ship continuously.

Changelog

For UI changes, see the live changelog at legal-eye.1bigfam.com (click the version tag in the top-right).

Public eval results are at /eval · raw JSON at github.com/GreenCycle2025/legal-eye-eval.

Contact

Built and maintained by Avri Barzel, Esq. · ivri0024@gmail.com.

Partnership integrations: email above with a short description of your use case. We respond within 24h on weekdays.

Bug reports / security issues: same email.