{"openapi":"3.1.0","info":{"title":"MenuMap API","version":"0.1.0","description":"Find restaurants by city or by distance from any address, and read their full menus with prices — built to be easy for people, search engines and AI agents to use."},"servers":[{"url":"https://menumap.eu"}],"paths":{"/api/restaurants":{"get":{"operationId":"searchRestaurants","summary":"Search restaurants by city and/or proximity to an address","description":"Returns restaurants, optionally filtered by city. When `near` (an address) or `lat`+`lng` is given, results are sorted by distance and include `distanceKm`; restaurants whose coordinates are unknown come last with `distanceKm: null`.","parameters":[{"name":"city","in":"query","schema":{"type":"string"},"example":"Sofia","description":"Exact city name"},{"name":"near","in":"query","schema":{"type":"string"},"example":"Vitosha Blvd 100, Sofia","description":"Free-text address, geocoded server-side"},{"name":"lat","in":"query","schema":{"type":"number"},"description":"Latitude (use with lng instead of near)"},{"name":"lng","in":"query","schema":{"type":"number"},"description":"Longitude (use with lat)"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}}}}},"/api/restaurants/{slug}":{"get":{"operationId":"getRestaurant","summary":"Get restaurant details (address, hours, contact)","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"example":"carnivale","description":"Restaurant identifier, as returned by the search endpoint."}],"responses":{"200":{"description":"Restaurant","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/restaurants/{slug}/menu":{"get":{"operationId":"getMenu","summary":"Get a restaurant's full menu with prices and item images","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"example":"carnivale","description":"Restaurant identifier, as returned by the search endpoint."}],"responses":{"200":{"description":"Menu","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Menu"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/v1/locations/match":{"post":{"tags":["Ingest API"],"security":[{"IngestKey":[]}],"operationId":"matchLocation","summary":"Whether MenuMap already has a restaurant, in any state (MenuMap's own key only)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchRequestV1"}}}},"responses":{"200":{"description":"match (reuse slug), ambiguous (hold for a person) or none","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchResultV1"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"403":{"description":"The key may not do this (scope, or another tenant's location)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"404":{"description":"Unknown location, source or item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"413":{"description":"The body is too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"422":{"description":"The document doesn't match the schema, or breaks a database rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"429":{"description":"Rate limit (per key); see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}}}}},"/api/v1/locations/{slug}":{"put":{"tags":["Ingest API"],"security":[{"IngestKey":[]}],"operationId":"putLocation","summary":"Create a location or merge into its profile (Restaurant Document v1): absent keys keep, null clears","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"example":"carnivale","description":"The location's slug; must match the body's slug"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestaurantDocumentV1"}}}},"responses":{"200":{"description":"Updated"},"201":{"description":"Created"},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"403":{"description":"The key may not do this (scope, or another tenant's location)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"404":{"description":"Unknown location, source or item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"413":{"description":"The body is too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"422":{"description":"The document doesn't match the schema, or breaks a database rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"429":{"description":"Rate limit (per key); see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}}}}},"/api/v1/locations/{slug}/menus":{"put":{"tags":["Ingest API"],"security":[{"IngestKey":[]}],"operationId":"putMenus","summary":"Push the complete set of one source's menus for a location (Menu Document v1)","description":"Applied in one transaction. Matched items keep their IDs. The outcome is applied, unchanged (same document as last time), quarantined (it would remove more than half of 10+ items) or suggested (a MenuMap source of a location its owner manages).","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"example":"carnivale","description":"Restaurant identifier, as returned by the search endpoint."},{"name":"source_id","in":"query","schema":{"type":"string","format":"uuid"},"description":"Write through this registered source (required for MenuMap keys; default: your push source)"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key returns the first result"},{"name":"X-Run-Token","in":"header","schema":{"type":"string","format":"uuid"},"description":"Crawlers: the fencing token of their claim"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MenuDocumentV1"}}}},"responses":{"200":{"description":"Outcome","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SnapshotResult"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"403":{"description":"The key may not do this (scope, or another tenant's location)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"404":{"description":"Unknown location, source or item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"409":{"description":"Stale run token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"413":{"description":"The body is too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"422":{"description":"The document doesn't match the schema, or breaks a database rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"429":{"description":"Rate limit (per key); see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}}}}},"/api/v1/items/{item_no}":{"patch":{"tags":["Ingest API"],"security":[{"IngestKey":[]}],"operationId":"patchItem","summary":"Change one item's price and/or availability","parameters":[{"name":"item_no","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"price":{"type":["number","null"],"minimum":0},"available":{"type":"boolean"}}}}}},"responses":{"200":{"description":"The item after the change"},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"403":{"description":"The key may not do this (scope, or another tenant's location)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"404":{"description":"Unknown location, source or item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"413":{"description":"The body is too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"422":{"description":"The document doesn't match the schema, or breaks a database rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"429":{"description":"Rate limit (per key); see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}}}}},"/api/v1/sources":{"get":{"tags":["Ingest API"],"security":[{"IngestKey":[]}],"operationId":"listSources","summary":"The sources this key manages, with schedule, health and the last run","parameters":[{"name":"slug","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Sources"},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"403":{"description":"The key may not do this (scope, or another tenant's location)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"404":{"description":"Unknown location, source or item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"413":{"description":"The body is too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"422":{"description":"The document doesn't match the schema, or breaks a database rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"429":{"description":"Rate limit (per key); see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}}}},"post":{"tags":["Ingest API"],"security":[{"IngestKey":[]}],"operationId":"registerSource","summary":"Register a page or feed for MenuMap to fetch on a schedule (pull)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceRegistrationV1"}}}},"responses":{"201":{"description":"The source"},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"403":{"description":"The key may not do this (scope, or another tenant's location)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"404":{"description":"Unknown location, source or item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"413":{"description":"The body is too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"422":{"description":"The document doesn't match the schema, or breaks a database rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"429":{"description":"Rate limit (per key); see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}}}}},"/api/v1/sources/{id}/refresh":{"post":{"tags":["Ingest API"],"security":[{"IngestKey":[]}],"operationId":"refreshSource","summary":"Fetch a source on the next cron tick","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Scheduled"},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"403":{"description":"The key may not do this (scope, or another tenant's location)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"404":{"description":"Unknown location, source or item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"413":{"description":"The body is too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"422":{"description":"The document doesn't match the schema, or breaks a database rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"429":{"description":"Rate limit (per key); see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}}}}},"/api/v1/runs/{id}":{"post":{"tags":["Ingest API"],"security":[{"IngestKey":[]}],"operationId":"reportRun","summary":"Crawlers: report a claimed run's progress (needs the crawler scope)","description":"captured: the page was fetched and stored, extraction follows. unchanged: same content as last time, the run ends. failed: the source backs off. The menus themselves go to PUT /api/v1/locations/{slug}/menus with X-Run-Token.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["lease_token","outcome"],"properties":{"lease_token":{"type":"string","format":"uuid"},"outcome":{"enum":["captured","unchanged","failed"]},"content_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"capture_path":{"type":"string","maxLength":500},"error":{"type":"string","maxLength":2000}}}}}},"responses":{"200":{"description":"Recorded"},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"403":{"description":"The key may not do this (scope, or another tenant's location)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"404":{"description":"Unknown location, source or item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"409":{"description":"Stale run token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"413":{"description":"The body is too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"422":{"description":"The document doesn't match the schema, or breaks a database rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"429":{"description":"Rate limit (per key); see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}}}}},"/api/v1/reports":{"post":{"operationId":"fileReport","tags":["Support"],"summary":"Report a problem with a listing (Digital Services Act Art. 16)","description":"A notice that a menu, price, address or other content is wrong or illegal. No key needed; at most 10 per hour per IP. Returns a reference; MenuMap tells the reporter its decision by email. The Support page's form posts here as application/x-www-form-urlencoded and is redirected back with the reference.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"subject":{"type":"string","minLength":1,"maxLength":500,"description":"The restaurant or page the notice is about, e.g. /restaurants/psari"},"kind":{"type":"string","enum":["price","details","owner","illegal"],"description":"price: a price or dish is wrong; details: address, hours or phone, or closed; owner: the restaurant objects; illegal: illegal content"},"explanation":{"type":"string","minLength":10,"maxLength":5000},"name":{"type":"string","minLength":1,"maxLength":200},"email":{"type":"string","maxLength":320,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"good_faith":{"type":"boolean","const":true,"description":"The reporter confirms, in good faith, that the notice is accurate and complete (DSA Art. 16(2)(d))"},"lang":{"default":"en","type":"string","enum":["en","bg"]}},"required":["subject","kind","explanation","name","email","good_faith"]}}}},"responses":{"201":{"description":"Filed","content":{"application/json":{"schema":{"type":"object","required":["reference"],"properties":{"reference":{"type":"string","pattern":"^MM-[0-9A-F]{8}$"}}}}}},"400":{"description":"Not JSON or a form"},"422":{"description":"A required field is missing or invalid"},"429":{"description":"Too many reports from this address; try again later"}}}},"/api/onboard/drafts/{id}/publish":{"post":{"operationId":"publishDraft","tags":["Onboarding"],"summary":"Publish a menu preview as a new restaurant, on a private link","description":"For the Publish screen. Needs a business session (the __Host-mm_session cookie, same origin) and the preview's edit token in x-draft-token. In one call it creates the business with the signed-in person as Owner, an unlisted location and its menu with the fixes; the location is listed after MenuMap's check. A restaurant already on MenuMap becomes a submission instead, and only a listed one is named. A retry by the same person returns the first answer and the same link.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"x-draft-token","in":"header","required":true,"schema":{"type":"string"},"description":"The preview's edit token"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"place":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"street":{"type":"string","minLength":1,"maxLength":300},"city":{"type":"string","minLength":1,"maxLength":120},"postal_code":{"type":"string","maxLength":20},"country":{"default":"BG","type":"string","pattern":"^[A-Z]{2}$"},"lat":{"type":"number","minimum":-90,"maximum":90},"lng":{"type":"number","minimum":-180,"maximum":180}},"required":["name","street","city","lat","lng"],"additionalProperties":false,"description":"The restaurant as the publisher confirmed it: the name, the address and the pin"},"terms":{"type":"boolean","const":true,"description":"The terms are accepted"},"attested":{"type":"boolean","const":true,"description":"I am allowed to publish this restaurant's menu on its behalf"}},"required":["place","terms","attested"],"additionalProperties":false}}}},"responses":{"200":{"description":"A retry: the first answer again, with replayed: true; or a submission ({outcome: submitted, name, listed_slug})"},"201":{"description":"Published on a private link","content":{"application/json":{"schema":{"type":"object","required":["outcome","slug","name","link"],"properties":{"outcome":{"const":"published"},"slug":{"type":"string"},"name":{"type":"string"},"tenant_id":{"type":"string","format":"uuid","description":"The business made; left out on a replay after the caller left it"},"location_id":{"type":"string","format":"uuid","description":"The new location, in that business; left out with tenant_id"},"link":{"type":["string","null"],"format":"uri","description":"The private page; the token is in the fragment"}}}}}},"401":{"description":"Not signed in"},"403":{"description":"Another origin, or a disabled person"},"404":{"description":"No such preview for this token, or publishing is off"},"409":{"description":"Not ready, expired, or published by someone else"},"422":{"description":"The restaurant, the terms or the authority statement is missing or invalid"}}}},"/api/v1/runs/{id}/retry":{"post":{"tags":["Ingest API"],"security":[{"IngestKey":[]}],"operationId":"retryRun","summary":"Crawlers: retry a quarantined crawl once, as a new fenced run (needs the crawler scope)","description":"For a second extraction with a larger model after the database quarantined the first. Allowed once per run, within 15 minutes, while nothing else holds the source. The new run carries the content hash and capture over; push its snapshot with the returned lease_token.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["lease_token"],"properties":{"lease_token":{"type":"string","format":"uuid"}}}}}},"responses":{"201":{"description":"The retry run","content":{"application/json":{"schema":{"type":"object","properties":{"run_id":{"type":"string","format":"uuid"},"lease_token":{"type":"string","format":"uuid"},"retry_of":{"type":"string","format":"uuid"}}}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"403":{"description":"The key may not do this (scope, or another tenant's location)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"404":{"description":"Unknown location, source or item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"409":{"description":"Not retryable: stale token, not quarantined, too late, already retried, or the source is busy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"413":{"description":"The body is too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"422":{"description":"The document doesn't match the schema, or breaks a database rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}},"429":{"description":"Rate limit (per key); see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestError"}}}}}}}},"components":{"securitySchemes":{"IngestKey":{"type":"http","scheme":"bearer","description":"An Ingest API key (mm_…), shown once when created"}},"schemas":{"SearchResponse":{"type":"object","properties":{"query":{"type":"object"},"origin":{"type":["object","null"],"properties":{"lat":{"type":"number"},"lng":{"type":"number"},"label":{"type":"string"}}},"error":{"type":["string","null"]},"count":{"type":"integer"},"results":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"city":{"type":"string"},"cuisine":{"type":"array","items":{"type":"string"}},"priceRange":{"type":"string","description":"Omitted when unknown"},"geo":{"type":"object","description":"Omitted when the restaurant's coordinates are unknown","properties":{"lat":{"type":"number"},"lng":{"type":"number"}}},"distanceKm":{"type":["number","null"]},"image":{"type":["string","null"],"format":"uri"},"url":{"type":"string","format":"uri"},"menuUrl":{"type":["string","null"],"format":"uri"}}}}}},"MenuItem":{"type":"object","required":["name","price","image_url"],"properties":{"name":{"type":"string"},"name_bg":{"type":["string","null"],"description":"Bulgarian name"},"description":{"type":["string","null"]},"weight":{"type":["string","null"],"description":"Portion size as printed on the menu, e.g. 350 g"},"price":{"type":["number","null"],"description":"In the menu's currency (its ISO 4217 code); null when the menu shows no price"},"image_url":{"type":["string","null"],"format":"uri","description":"The restaurant's own photo of the item"},"illustration":{"type":"object","readOnly":true,"description":"Reads only, for an item with no photo of its own: a curated dish type's illustrative photo. It shows the kind of dish, not this restaurant's; show it labelled as illustrative, with its attribution (O.10)","required":["dish_type","image_url","title","source_url","credit","licence"],"properties":{"dish_type":{"type":"string"},"name_bg":{"type":"string"},"name_en":{"type":"string"},"image_url":{"type":"string","format":"uri"},"title":{"type":"string","description":"The work's title, as its source names it"},"source_url":{"type":"string","format":"uri"},"credit":{"type":"string","description":"Its author"},"licence":{"type":"string"},"licence_url":{"type":["string","null"],"format":"uri"}}},"item_no":{"type":"integer","description":"Short public number (database only). MCP item IDs are <slug>:<item_no>"},"external_id":{"type":"string","description":"The item's ID in the source system (Ingest API)"},"available":{"type":"boolean","description":"false: listed but not available right now. Omitted when available"}}},"MenuCategory":{"type":"object","properties":{"name":{"type":"string"},"name_bg":{"type":["string","null"]},"external_id":{"type":"string"},"subcategories":{"type":"array","items":{"$ref":"#/components/schemas/MenuCategory"}},"items":{"type":"array","items":{"$ref":"#/components/schemas/MenuItem"}}}},"Menu":{"type":"object","properties":{"restaurant":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"}}},"source":{"type":"string","format":"uri","description":"Restaurant website page the menu was taken from"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","example":"EUR","description":"ISO 4217 code of every price in the menu"},"currency_note":{"type":"string","description":"Present when prices were converted from BGN"},"fetched_at":{"type":"string","format":"date-time"},"menus":{"type":"array","items":{"type":"object","properties":{"menu_type":{"type":"string","example":"main"},"name":{"type":"string","example":"Main Menu"},"categories":{"type":"array","items":{"$ref":"#/components/schemas/MenuCategory"}}}}}}},"MenuItemV1":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":500,"description":"The item's name: in English when the menu prints one, otherwise as printed (docs/MENU_MODEL.md)"},"name_bg":{"description":"The Bulgarian name, when the menu prints one that differs from name","anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"description":{"description":"Description or ingredients as printed","anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]},"weight":{"description":"The portion as printed, e.g. \"350 g\", \"0.5 l\", \"30 cm\"","anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"price":{"description":"In the document's currency; null when no price is shown","anyOf":[{"type":"number","minimum":0,"maximum":1000000},{"type":"null"}]},"image_url":{"description":"An absolute http(s) image URL","anyOf":[{"type":"string","maxLength":2000,"pattern":"^https?:\\/\\/"},{"type":"null"}]},"external_id":{"description":"The item's ID in the source system; matched first, so the item keeps its identity","type":"string","minLength":1,"maxLength":200},"available":{"description":"false: listed but not available right now","type":"boolean"}},"required":["name"]},"MenuCategoryV1":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":300,"description":"The category's name, with the same language rule as an item's"},"name_bg":{"description":"The Bulgarian name, when it differs from name","anyOf":[{"type":"string","maxLength":300},{"type":"null"}]},"external_id":{"description":"The category's ID in the source system","type":"string","minLength":1,"maxLength":200},"subcategories":{"default":[],"maxItems":200,"type":"array","items":{"$ref":"#/components/schemas/MenuCategoryV1"}},"items":{"default":[],"maxItems":2000,"type":"array","items":{"$ref":"#/components/schemas/MenuItemV1"}}},"required":["name"]},"MenuV1":{"type":"object","properties":{"key":{"description":"Identifies the menu within its source; defaults to menu_type (repeats become main-2, main-3 …)","type":"string","maxLength":60,"pattern":"^[a-z0-9]+(-[a-z0-9]+)*$"},"external_id":{"description":"The menu's ID in the source system","type":"string","minLength":1,"maxLength":200},"menu_type":{"default":"main","type":"string","enum":["main","drinks","lunch","breakfast","wine","other"]},"name":{"type":"string","minLength":1,"maxLength":300},"categories":{"maxItems":500,"type":"array","items":{"$ref":"#/components/schemas/MenuCategoryV1"},"description":"Categories in menu order; each may nest subcategories"}},"required":["name","categories"]},"MenuDocumentV1":{"type":"object","properties":{"source":{"description":"Where the menu was taken from","type":"string","maxLength":2000,"pattern":"^https?:\\/\\/"},"fetched_at":{"description":"When it was taken, ISO 8601 with an offset","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"currency":{"default":"EUR","description":"The prices' ISO 4217 currency (EUR, USD, GBP, NOK ...), kept as given. BGN is the exception: converted to EUR at 1.95583","type":"string","pattern":"^[A-Z]{3}$"},"currency_note":{"description":"How the prices were converted, if they were","anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"menus":{"maxItems":50,"type":"array","items":{"$ref":"#/components/schemas/MenuV1"},"description":"All of the source's menus; a menu left out is removed"}},"required":["menus"]},"RestaurantDocumentV1":{"type":"object","required":["slug","name"],"description":"A location's profile: the same shape GET /api/restaurants/{slug} returns. It merges into what is stored: an absent key keeps the stored value, null clears it. Any address part may be missing; a location without a complete address is kept from the public.","properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(-[a-z0-9]+)*$"},"name":{"type":"string"},"description":{"type":["string","null"]},"cuisine":{"type":["array","null"],"items":{"type":"string"}},"priceRange":{"type":["string","null"],"enum":["€","€€","€€€","€€€€",null]},"address":{"type":"object","properties":{"street":{"type":["string","null"]},"postalCode":{"type":["string","null"]},"city":{"type":["string","null"]},"country":{"type":["string","null"],"pattern":"^[A-Z]{2}$"}}},"staged":{"type":"boolean","description":"MenuMap's key only: a new location stays disabled until its import batch is released"},"batch":{"type":"string","pattern":"^[a-z0-9]+(-[a-z0-9]+)*$","description":"MenuMap's key only: the import batch that records this write"},"geo":{"type":["object","null"],"properties":{"lat":{"type":"number"},"lng":{"type":"number"}}},"phone":{"type":["string","null"],"pattern":"^\\+[0-9]{6,15}$"},"email":{"type":["string","null"]},"website":{"type":["string","null"],"format":"uri"},"sameAs":{"type":"array","items":{"type":"string","format":"uri"}},"openingHours":{"type":"array","items":{"type":"object","properties":{"days":{"type":"array","items":{"type":"string","enum":["Mo","Tu","We","Th","Fr","Sa","Su"]}},"opens":{"type":"string","example":"11:00"},"closes":{"type":"string","example":"23:00","description":"Earlier than opens: the next day"}}}},"services":{"type":["object","null"],"properties":{"delivery":{"type":["boolean","null"]},"pickup":{"type":["boolean","null"]}}},"menuUrl":{"type":["string","null"],"format":"uri"}}},"MatchRequestV1":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":300},"street":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]},"city":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"country":{"anyOf":[{"type":"string","pattern":"^[A-Z]{2}$"},{"type":"null"}]},"lat":{"anyOf":[{"type":"number","minimum":-90,"maximum":90},{"type":"null"}]},"lng":{"anyOf":[{"type":"number","minimum":-180,"maximum":180},{"type":"null"}]},"place_id":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]},"website":{"anyOf":[{"type":"string","maxLength":2000,"pattern":"^https?:\\/\\/"},{"type":"null"}]},"slug":{"description":"Also say whether this slug is taken, in any state","type":"string","maxLength":100,"pattern":"^[a-z0-9]+(-[a-z0-9]+)*$"}},"required":["name"],"additionalProperties":false},"MatchResultV1":{"type":"object","required":["status","candidates"],"properties":{"status":{"type":"string","enum":["match","ambiguous","none"]},"slug":{"type":"string","description":"With match: the existing location's slug"},"candidates":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"city":{"type":["string","null"]},"street":{"type":["string","null"]},"why":{"type":"string","enum":["place_id","name_within_150m","name_street_city","name_website","name_city"]}}}}}},"SourceRegistrationV1":{"type":"object","required":["slug","kind","url"],"properties":{"slug":{"type":"string"},"kind":{"type":"string","enum":["crawler","feed"],"description":"crawler: a page MenuMap extracts; feed: a Menu Document v1 JSON URL"},"url":{"type":"string","format":"uri"},"adapter":{"type":"string","enum":["auto","html","pdf","image","json"],"default":"auto"},"interval_minutes":{"type":"integer","minimum":15,"maximum":43200,"default":1440},"paused":{"type":"boolean","default":false}}},"SnapshotResult":{"type":"object","properties":{"slug":{"type":"string"},"run_id":{"type":"string","format":"uuid"},"source_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["applied","unchanged","quarantined","suggested"]},"counts":{"type":"object","additionalProperties":{"type":"integer"},"description":"menus, pages, items, added, changed, removed"},"replayed":{"type":"boolean","description":"true when an Idempotency-Key repeated an earlier request"}}},"IngestError":{"type":"object","properties":{"error":{"type":"string"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}}}