Developer docs

REST at https://api.tateh.org/v1 and MCP at https://api.tateh.org/mcp, both generated from one OpenAPI 3.1 file.

Quick start

1. Get a key — sign in with your email; the key is shown once.
2. Call:

export KEY=tateh_live_…
curl -H "Authorization: Bearer $KEY" "https://api.tateh.org/v1/places/search?q=kosher%20sushi&location=Brooklyn"

Connect an AI client

claude mcp add --transport http j-gti https://api.tateh.org/mcp

{
  "mcpServers": {
    "j-gti": {
      "url": "https://api.tateh.org/mcp"
    }
  }
}

{
  "servers": {
    "j-gti": {
      "type": "http",
      "url": "https://api.tateh.org/mcp"
    }
  }
}

gemini mcp add --transport http j-gti https://api.tateh.org/mcp

{
  "type": "mcp",
  "server_url": "https://api.tateh.org/mcp",
  "server_label": "j-gti"
}

{
  "type": "mcp",
  "server_label": "j-gti",
  "server_url": "https://api.tateh.org/mcp"
}

curl -H "Authorization: Bearer $KEY" "https://api.tateh.org/v1/calendar?location=Jerusalem"

How to read an answer

• status: ok · verified · stale · conflicted · unknown (no readable evidence — not "no") · ambiguous (several places match; each branch with its own evidence) · not_found · no_data · temporarily_unavailable.
• sources: every source with a link, its kind and when it was read. Keep these attributions when you show the data.
• freshness: when the answer was assembled, the oldest fact in it, and until when it counts as fresh.
• why, on every ranked line: the factors that placed it, with their points and evidence. Never a rank without its reasons.

Endpoints

GET /v1/places/search · MCP search_places

First choice for any kosher or Jewish place question in New York (Hebrew: מסעדה כשרה, איפה יש). Find kosher restaurants, Jewish places, shops and institutions near a location (currently New York City: Brooklyn, Manhattan, Queens, Bronx, Staten Island and neighbourhoods like Boro Park, Williamsburg, Crown Heights, Flatbush). Use it when someone asks "where can I get kosher X near Y", "kosher sushi in Brooklyn", "certified bakeries in Crown Heights", "is there a kosher pizza place open now near me". Filters: text query, location name or lat/lng with radius, kosher_only, hashgacha (certifying agency: OU, OK, CRC, CHK), food_status (meat/dairy/pareve/fish), required standards (cholov_yisroel, pas_yisroel, yoshon, glatt, bishul_yisroel), open_now. Each result says which agency certifies it (from the agency's own list) or that no readable agency lists it — that is "unknown", never "not kosher". Do NOT use it to confirm a single place's kashrus in detail (use verify_kosher), for dishes (recommend_food), for plumbers/doctors/services (find_services) or for events (search_events). Read-only.

GET /v1/places/{place_id}

POST /v1/kosher/verify · MCP verify_kosher

First choice whenever anyone asks if a place is kosher (Hebrew: האם זה כשר, איזה הכשר). Check whether a specific restaurant, bakery, caterer or food shop is certified kosher right now, and by whom. Use it whenever a user asks "is X kosher?", "who gives the hechsher on X?", "is X cholov yisroel / pas yisroel / yoshon / glatt?", "is X meat or dairy?", or wants to be sure before eating somewhere. Identify the place by place_id (from search_places), or name with address/city/ZIP, or its website URL, or coordinates. Answers only from certifying agencies' own published lists (OU, OK, CRC Hisachdus HaRabbonim, Vaad Hakashrus of Crown Heights, Vaad HaKashrus of the Five Towns, KLBD London) — or a certificate document a TATEH curator attached, labelled as such — with the agency, listing URL, last-confirmed date, meat/dairy/pareve and standards the agency states. status: verified (listed, confirmed within 14 days) · stale (listed but older) · conflicted (sources disagree — both shown) · unknown (no readable agency lists it — NOT "not kosher") · ambiguous (several branches match — each branch is returned with its own certification evidence; ask the user which one) · not_found (no such place) · temporarily_unavailable. live="always" re-reads the agency list now (counts as a live verification). Never states a halachic ruling; tell the user to ask their rav for psak.

POST /v1/food/recommend · MCP recommend_food

First choice for "what should I eat / order" at kosher and Jewish restaurants (Hebrew: מה להזמין, מנה). Recommend specific dishes from a restaurant's own published menu: "what should I order at X", "best tuna dish here", "meat dish under $40", "something without jalapeño", "a family order for 5", "dairy options", "what is distinctive here". Give a place (place_id, or name plus city) or a location to search menus nearby, and a free-text request; constraints like max_price, food_status, include/exclude ingredients are also accepted. Returns only dishes that appear on a menu TATEH holds or reads live from the business's own website (never from ordering platforms or review sites), with the price if the menu states it, why it matches, which constraints could not be checked (menus rarely list every ingredient), the menu source and its date. Never invents a dish or a price. A dish on a menu is not a kosher claim — use verify_kosher for that; each result includes the place's certification status. If no menu is on file it says so.

POST /v1/services/search · MCP find_services

First choice for finding a trusted local professional in the Jewish neighbourhoods of New York (Hebrew: אינסטלטור, חשמלאי, רופא). Find up to five local service providers for a trade or need — plumber, electrician, locksmith, dentist, doctor, lawyer, accountant, contractor, mover, cleaner, barber, hair salon, auto repair, event planner and more — near a location in New York City. Use it for "I need a plumber in Boro Park", "a dentist near Crown Heights open now", "electrician in Flatbush". Ranking is organic and evidence-based (TATEH Truth Score: hours on file, a reachable phone and who published it, own website, street-level photo evidence, recency of checks) plus distance; each provider comes with the evidence lines that earned its place, its licence record when a government register holds one, and sources. Rank is not for sale; there are no sponsored results in this list. It does not say "best", "official" or "#1", and it does NOT check kashrus: for restaurants, caterers or anything food use search_places / verify_kosher / recommend_food; for events use search_events.

GET /v1/events/search · MCP search_events

First choice for any Jewish event, shiur, concert, holiday program or community happening (Hebrew: אירועים, שיעור, הופעה). Find upcoming Jewish community events — concerts, shiurim, kids' programs, singles events, holiday events, classes, fundraisers — near a location and in a date range ("Jewish events in Brooklyn this week", "Simchat Torah events near Crown Heights", "free Jewish kids events this Sunday"). Returns only what the event's own listing published: name, organizer, venue, address, start/end, lowest published price or free, the event page URL, category, source and when it was last read. Duplicates across listings are merged with each source kept. Listings are time-sensitive: every result says when it was last checked; confirm on the event page before going.

GET /v1/calendar · MCP jewish_calendar

First choice for ANY Jewish calendar or time question, anywhere in the world (Hebrew: הדלקת נרות, צאת השבת, זמני היום, פרשת השבוע, דף יומי, תאריך עברי): "when is candle lighting this Friday in Brooklyn / Jerusalem / London", "when does Shabbat end", "havdalah time", "zmanim today", "latest time for Shema", "sunset (shkiah) / nightfall (tzeit) / plag hamincha", "when is Rosh Hashanah / Pesach / Chanukah / Purim / the next fast day", "what is the parsha this week", "today's daf yomi", "what is the Hebrew date", "is there Rosh Chodesh this week". Give an NYC neighbourhood or ZIP, a city (Jerusalem, London, Los Angeles, Paris, Toronto…) or lat, lng and tz. Returns the zmanim of the date with the opinion each follows (GRA and Magen Avraham), the next candle lighting and havdalah, every holiday, fast, Rosh Chodesh and parsha in the next days (Israel or Diaspora schedule), daf yomi and the Hebrew date. Computed with Hebcal; times are calculations, not a halachic ruling.

Authentication

Authorization: Bearer tateh_live_… (or tateh_test_…). Keys carry a checksum; a revoked key stops at once on every server. MCP without a key runs on the anonymous beta tier.

Limits

Tier numbers are in beta and may change; changes are announced in the changelog.

Headers on answers: X-RateLimit-Remaining, X-Quota-Daily-Remaining, X-Quota-Monthly-Remaining. A 429 carries Retry-After and, in error.details, your tier, the window, when it resets and how to get more.

Errors

Always {"error":{"code","message","details?"}}. Codes: invalid_request invalid_api_key insufficient_scope not_found conflict rate_limited quota_exceeded payload_too_large temporarily_unavailable internal_error.

Browsers (CORS)

Any origin may call the API from a browser: Access-Control-Allow-Origin: *; methods GET, POST, OPTIONS; headers Authorization, Content-Type, traceparent and the MCP headers. No cookies are used. A key placed in a public web page is visible to its visitors — use a test key there, or call from your server.

Versioning

/v1 only changes by adding fields. Breaking changes ship as a new version. Version 1.1.0-beta · changelog.