Skip to content
The Kosher
Menu

API documentation

REST · JSON · Bearer-token auth. Base URL: https://thekosher.app/api/v1

Authentication

Pass your key as a bearer token on every request. Keep it on your server — never embed in a browser bundle.

Authorization: Bearer tk_live_xxxxxxxx

Errors: 401 invalid / revoked key, 429 rate limit exceeded for the day, 404 resource not found, 400 unsupported or invalid parameters, and 503 unavailable dependency or evidence capability.

GET/restaurants

Paginated list of listed restaurants. All filters AND-combine.

city
string · case-insensitive
country
ISO-2 (e.g. US, GB, IL)
type
MEAT, DAIRY, or PAREVE
cuisine
string · case-insensitive
recorded_agency
Recorded agency slug or abbreviation; does not establish current certification
certification
Current named certification requirement; unavailable until eligible reviewed evidence can fulfill it
lat / lng / radius_miles
Supply all three; great-circle distance in miles, including dateline and poles
limit
1–100 · default 25
offset
0–1,000,000 · default 0
GET/restaurants/{slug}

Directory contact details, matching location, recorded agencies, recorded schedule and scoped evidence. Raw legacy flags do not establish current certification or availability.

GET/search?q=…

Interprets one q parameter of at most 500 characters. Parsed preferences become search requirements. Venue claims require separate supporting evidence. Requests and responses are not cacheable.

GET/certifications

Paginated active agency directory records (limit 1–100, offset 0–1,000,000). Kitniot policy remains unknown without explicit reviewed venue and Pesach-season evidence; a body name does not establish current certification.

Rate limits

The configured key quota is authoritative; an explicit zero means no daily quota. Each request consumes an atomic admission and counters reset at UTC midnight. Quota exhaustion returns 429; an unavailable quota service returns 503.

Evidence and pagination

Filters apply to the venue and the same matching location. Counts include every matching venue before pagination; an empty page beyond the last record still returns the filtered total. Results have stable ordering. Unknown, unreviewed, unavailable, stale, revoked, conflicted and verified-negative evidence are distinct. Preserve those states when presenting results. A recorded agency or schedule cannot supply missing review evidence. All responses use Cache-Control: no-store.

Need something we don’t expose?

Tell us. We tailor the schema based on actual integrations — email hello@thekosher.app.

The Kosher · הכשר