{"service":"tavolo-api","description":"Guest-facing BFF for the Tavolo marketplace app (apps/mobile).","auth":"Bearer <token from POST /auth/verify-otp> on every /me/* route and the restaurant write routes. ONE route, `/chat/token` (`auth: \"session-or-anonymous\"`), also accepts the read-only anonymous visitor token from POST /auth/anonymous — typed chat. Nothing spoken does: `/voice/token`, `/concierge/token` and `/chat/transcribe` stay account-only, because each one is paid audio (Maged 2026-10-09: anything you say needs an account).","endpoints":[{"method":"GET","path":"/","auth":false,"desc":"This catalog."},{"method":"GET","path":"/v1/orders","auth":"api-key","scopes":["orders:read"],"desc":"H10 public API — the restaurant's orders: id, ref, type, status, totalCents, tipCents, items, createdAt, scheduledFor. NO guest details — the name, phone, delivery address and the order note (which carries allergy information) need `customers:read`, a scope a restaurant grants separately. Authenticated by `Authorization: Bearer tav_live_…`; the tenant is the key's own, never a parameter. ?limit (clamped to 200). Returns RateLimit-* headers; 429 with Retry-After when over budget."},{"method":"GET","path":"/v1/reservations","auth":"api-key","scopes":["reservations:read"],"desc":"H10 public API — the restaurant's reservations: when, how many, in what state, and through which channel. NO guest details (see `/v1/orders`). ?limit (clamped to 200)."},{"method":"GET","path":"/v1/menu","auth":"api-key","scopes":["menu:read"],"desc":"H10 public API — the menu as a guest chooses from it: name, description, category, priceCents, isAvailable, allergens, dietaryTags, spiceLevel, prepMinutes, imageUrl, modifiers, taxClass. An explicit projection, so a new internal column never reaches an integrator by accident."},{"method":"GET","path":"/v1/store","auth":"api-key","scopes":["orders:read"],"desc":"H15 public API — can this restaurant take an order right now? `acceptingOrders`, `pausedUntil` (when a deliberate pause lifts), `pauseReason` (the operator's own words) and `prepTimeMinutes` (the live quote, already stretched for kitchen load). `acceptingOrders` covers EVERY way a restaurant stops: the operator's manual pause, their automatic \"stop at N open tickets\" valve, and the kitchen being outside its opening hours or past its own last orders — it is decided by the same gate `POST /v1/orders` refuses on, so the two can never disagree. A valve-caused stop carries no `pausedUntil` and no `pauseReason`: retry rather than wait for a stated time. Poll it before pushing, and mirror `acceptingOrders` onto your storefronts — a stopped kitchen refuses `POST /v1/orders` with 503 `ordering_paused`."},{"method":"GET","path":"/v1/stock","auth":"api-key","scopes":["stock:read"],"desc":"H10 public API — active stock items with their on-hand position: name, sku, unit, qty, parLevel, reorderPoint. Valuation (`avgUnitCostCents`) is deliberately NOT returned — an integration that needs the restaurant's cost base gets it on a scope that says so."},{"method":"GET","path":"/v1/labour","auth":"api-key","scopes":["labour:read"],"desc":"H10 public API — the rota, and only the rota: who is on, from when to when, and in what state. Pay rates and operator shift notes are NOT returned. ?from / ?to (ISO dates); defaults to the next 7 days and is clamped to a 92-day window, so one call can never scan the whole history."},{"method":"PATCH","path":"/v1/orders/:id","auth":"api-key","scopes":["orders:write"],"desc":"H10 public API — cancel an order the API itself placed (`{\"status\":\"cancelled\"}`, optional `reason`). The ONLY change a partner may make: accepting, starting and completing are the restaurant's own record, made on the KDS. Refuses an order from another channel, an order money has moved on, and one the kitchen has started — `because` names which. Cancelling an already-cancelled order answers 200, so a retried request reads as success. Notifies the restaurant and closes a delivery run. Audited with the key id and your reason."},{"method":"POST","path":"/v1/orders","auth":"api-key","scopes":["orders:write"],"desc":"H10 public API — place an order. Item ids + quantities only; the price comes from the restaurant's own menu (never the body). Requires an `Idempotency-Key`, so a retried timeout cannot place a second order. 409 `out_of_zone` / `below_minimum` / `allergen_conflict`; 409 `kitchen_closed` (outside opening hours, carries `reopensAt`) / `last_orders_passed` (past the kitchen's own cut-off, carries `cutoff`); 503 `ordering_paused` when the restaurant has deliberately stopped (carries `resumesAt` — retry after it, the same body will be accepted). H15: optional `scheduledFor` (ISO 8601 with `Z` or an offset) orders for LATER; the hours are then asked at that time, and a time the kitchen cannot keep is 409 `scheduled_unavailable` with `reason` (and `reopensAt` when shut)."},{"method":"POST","path":"/v1/reservations","auth":"api-key","scopes":["reservations:write"],"desc":"H10 public API — book a table. Availability + the per-table double-booking guard run under the same advisory lock the app and voice paths use; 409 `slot_unavailable` carries `suggestedSlots`. Requires an `Idempotency-Key`."},{"method":"PATCH","path":"/v1/menu/:id","auth":"api-key","scopes":["menu:write"],"desc":"H10 public API — 86 an item (`isAvailable`) or re-price it (`priceCents`). Deliberately two fields wide: a partial PATCH must never be able to blank an item's allergens."},{"method":"POST","path":"/v1/stock/movements","auth":"api-key","scopes":["stock:write"],"desc":"H10 public API — post one movement to the stock ledger (receive/consume/waste/adjust/count). Costed by the same core arithmetic the dashboard injects, FIFO included. Requires an `Idempotency-Key`."},{"method":"GET","path":"/v1/customers","auth":"api-key","scopes":["customers:read"],"desc":"H10 public API — the restaurant's own customer records. ?limit (clamped to 200). Name, phone, language and tags only — never an operator's private notes."},{"method":"GET","path":"/v1/webhooks","auth":"api-key","scopes":["webhooks:manage"],"desc":"H10 public API — the restaurant's webhook endpoints, with their signing secrets (a receiver needs one to verify every delivery)."},{"method":"POST","path":"/v1/webhooks","auth":"api-key","scopes":["webhooks:manage"],"desc":"H10 public API — subscribe an https endpoint to events. The signing secret is returned once, in the response. Requires an `Idempotency-Key`."},{"method":"DELETE","path":"/v1/webhooks/:id","auth":"api-key","scopes":["webhooks:manage"],"desc":"H10 public API — remove a webhook endpoint. 404 when it is not this key's restaurant's."},{"method":"GET","path":"/health","auth":false,"desc":"Liveness probe (process up; no DB). Also reports `capabilities` — booleans about this environment's own config (e.g. transcribe), so a deploy check can verify a feature is switched on without a signed-in guest."},{"method":"GET","path":"/health/blob","auth":false,"desc":"Blob-store self-test: writes a few bytes to the configured store and deletes them, so \"can this environment actually accept a photo?\" is answerable without a signed-in guest. Returns { ok } or { ok:false, error, detail } — never the token. 429 on a short cooldown (the endpoint writes)."},{"method":"GET","path":"/ready","auth":false,"desc":"Readiness probe (pings the DB; 503 when unreachable). `checks.instanceState` reports whether the cache and rate-limit counters are shared across instances (Act XV · T3) — scopes only, never folded into `ok`."},{"method":"GET","path":"/version","auth":false,"desc":"Deployed-build marker — { service, commit (git SHA, or 'unknown' locally), commitFull, startedAt (this instance's boot), nodeEnv, dbPool }. Answers 'is this instance running current code?' in one call (the stale-deploy diagnostic); `dbPool` is the connection pool class + sizing + a named identity (Act XV · T1). Secret-free."},{"method":"GET","path":"/restaurants","auth":false,"desc":"Discovery list (?q, ?cuisine, ?cuisines, ?sort, ?brandId, ?deliveryMode=pickup|delivery, ?city, ?lat+?lng). ?q matches the restaurant NAME, its stored cuisine slug, an available DISH name and the address CITY (case-insensitive, 3 characters minimum), so 'pizza' and 'Zürich' find restaurants instead of nothing. ?cuisines is a comma-separated list of cuisine slugs the app resolved from the guest's own words against the localized cuisine and chip labels in all four catalogs ('Italienisch', 'إيطالي', 'Italiaans', 'Sushi'); it is OR'd with the name match, unlike ?cuisine, which NARROWS to one slug. An unknown slug is dropped rather than refusing the request. ?brandId narrows to one chain's branches, so a brand page does not depend on the listing cap. Passing ?city and/or coords makes each row's canDeliver address-aware and fills distanceKm (real km, null when either end lacks coords); sort=nearby then orders by that distance. When deliveryMode=delivery: only restaurants whose zones cover the address are returned; if no city/coords, authenticated guests fall back to their default address; restaurants with no zones are excluded. Zones with a radiusKm match by true distance when coords are known (else by area name). A chain's branches collapse into ONE card (branchCount + siblingBranches, nearest-first) — brandless rows are unaffected. A restaurant HQ hid from the app (an `app.hide_from_discovery` override) is left out; it is still served by id."},{"method":"GET","path":"/restaurants/:id","auth":false,"desc":"Public restaurant projection (canDeliver + distanceKm derived from ?city/?lat+?lng or the guest's default address, and voiceAvailable — the W2·6 voice pre-flight: whether the server's voice service is configured). Also maxPartySize: the largest party the restaurant books, read by core's capacityFrom, so the app's party stepper stops where the booking guards refuse; omitted when the stored rules give no positive whole number. Also chatAvailable: whether this restaurant's own chat host takes guests (its per-tenant chat.intelligence flag, failing closed, and a configured voice service); the app offers 'Chat with …' only when true. Also orderingPausedUntil (ISO) + orderingPauseReason: the kitchen's deliberate pause (H15), sent only while it is in force at the time of the read (core's orderingPauseState, the rule the checkout's 503 ordering_paused refuses on), else both null; the app says 'not taking orders, back at …' before a basket and closes its order buttons until that time passes."},{"method":"GET","path":"/restaurants/by-slug/:slug","auth":false,"desc":"The same public restaurant projection as /restaurants/:id, found by the restaurant's own printed address (its orderingSlug) instead of its id — the slug hop behind the QR / universal-link bridge, so a menu URL that opens the Tavolo app can resolve to the restaurantId every other read is keyed on. The slug is validated against core's own orderingSlugSchema (so the API can never refuse an address the dashboard let a restaurant print) and normalized, so a capitalized hand-typed address still resolves. 404 not_found covers EVERY refusal — unknown slug, not publicly listed, operator-paused, HQ-suspended — because a slug is guessable in a way an id is not and this route must not answer whether a given name is on the platform."},{"method":"GET","path":"/restaurants/:id/menu","auth":false,"desc":"Public menu (includes sold-out items flagged isAvailable:false; each item carries dietaryTags, allergens, spiceLevel, isPopular/isSpecial, pairsWith, modifiers)."},{"method":"GET","path":"/specials","auth":false,"desc":"Today's specials across the marketplace (available isSpecial dishes + a lean restaurant summary for deep-linking). Dishes of a restaurant hidden from the app are left out."},{"method":"GET","path":"/flags","auth":false,"desc":"Evaluated CLIENT feature flags (VI-15) — the app reads these on launch to gate features / show a service notice. Returns { flags: { key: boolean } } for the app-namespaced allowlist only (never internal operator/HQ flags); each fails closed to its safe default."},{"method":"GET","path":"/restaurants/:id/reviews","auth":false,"desc":"Rating summary + the newest reviews. Optional ?limit=1..50 + ?cursor= (keyset, from the previous page's nextCursor) page newest-first; with either param the response adds nextCursor (null = end). Without params: the 20 newest, no nextCursor."},{"method":"GET","path":"/restaurants/:id/knowledge","auth":false,"desc":"Guest-facing FAQ + house-rules card (B9·6; guest-safe projection of faqs/houseRules — never agent config)."},{"method":"GET","path":"/restaurants/:id/recommendations","auth":false,"desc":"Ranked dish picks for one restaurant (B9·5; personalized 'your usual' order-again when signed in). Returns { id, reason }[]."},{"method":"GET","path":"/restaurants/:id/availability","auth":false,"desc":"Bookable slots for a date (?date=YYYY-MM-DD&partySize); pass ?dateTime=ISO (Z or an offset) to also confirm one exact slot against the per-table guard."},{"method":"GET","path":"/restaurants/:id/full-slots","auth":false,"desc":"H15: the pre-order pickup times (quarter hours, next two days) that already hold as many orders as the restaurant's own stop line allows, as { full: ISO[] }. The Tavolo app hides these from its picker; POST /orders still refuses a full slot as 409 slot_full with nextFreeSlot."},{"method":"POST","path":"/auth/request-otp","auth":false,"desc":"Send a phone OTP {phone} → { ok, devCode? }. devCode only in development/test, or under production for an OTP_DEV_ECHO_PHONES test number while OTP_DEV_ECHO=true; with no SMS provider any other number gets 503 otp_unconfigured. 429 rate_limited."},{"method":"POST","path":"/auth/verify-otp","auth":false,"desc":"Verify OTP → session token + guest."},{"method":"POST","path":"/auth/register","auth":false,"desc":"Email + password sign-up {email, password, name?, locale?} → { token, guest }. Brand-new emails only: 409 if the email already exists on ANY account (password or social) — rate-limited per ip:email (429 rate_limited)."},{"method":"POST","path":"/auth/login","auth":false,"desc":"Email + password sign-in {email, password} → { token, guest }. Generic 401 on bad creds; rate-limited per ip:email (429 rate_limited)."},{"method":"POST","path":"/auth/google","auth":false,"desc":"Google sign-in {idToken} — token verified server-side (signature, exp, email_verified) → { token, guest }. The token's aud is checked against an allowlist (GOOGLE_OAUTH_CLIENT_IDS overrides; defaults to the app's baked web+iOS client ids), so a token minted for another app is refused — but with no env config prod still signs in against those defaults."},{"method":"POST","path":"/auth/oauth/apple","auth":false,"desc":"Apple sign-in {identityToken, fullName?} — JWT verified against Apple JWKS → { token, guest }. Succeeds even when Apple omits the email on re-authorization (account keyed on a hashed-sub synthetic handle)."},{"method":"POST","path":"/auth/forgot","auth":false,"desc":"Request a password reset {email} → { ok: true }, identical whether the email exists, the send succeeds or it fails (never reveals an account, by body or by timing). An existing account is emailed (Resend, after the response is written) a tavolo://reset-password?token= link plus the same token as a paste-in code, in the guest's stored locale, else the request's; a send failure is reported as reset_email_unconfigured / reset_email_send_failed / reset_email_unreachable. devToken also echoed in development and test only, never under production; rate-limited per ip:email, 429 rate_limited."},{"method":"POST","path":"/auth/reset","auth":false,"desc":"Complete a password reset {token, password} → { ok: true }. The token is single-use — it stops verifying the instant the account changes (including this reset itself), so a captured/replayed token can't be reused."},{"method":"POST","path":"/auth/anonymous","auth":false,"desc":"TALK WITHOUT AN ACCOUNT: mint a 30-minute anonymous visitor token → { token, expiresInSeconds, anonymous: true }. No body. Creates nothing — no account, no consent record, no write. The token is accepted ONLY by POST /chat/token, and is refused by every route marked `auth: true` (it carries typ:\"anon\", which the session verifier rejects), so it can neither reach /me/* nor place, pay for, change or read anything. The agent session it opens is READ-ONLY: the write tools answer `sign_in_required` and the host asks the guest to sign in. Rate-limited per IP (10/min). The agent tokens it mints are metered per visitor (10 mints/min; a token lives 5 minutes and is not single-use, so this counts mints, not sessions) AND per IP (60 anonymous agent requests/min). How many conversations strangers hold at once is bounded by the voice service: every no-account session together gets at most half the marketplace chat pool, so free self-issued identities cannot lock signed-in guests out."},{"method":"POST","path":"/voice/token","auth":true,"desc":"Short-lived token to call a restaurant's AI host. One token opens one call, and one account holds one call at a time (the voice service enforces both). An account may start at most VOICE_TOKEN_DAILY_MAX_PER_GUEST (default 20) of these per rolling 24 hours, counted before the body is read; past it: 429 { error: \"voice_daily_limit\", retryAfterMs } with Retry-After."},{"method":"POST","path":"/concierge/token","auth":true,"desc":"Short-lived token to talk to the Tavolo Concierge (marketplace host). Requires an account: the session it opens is the marketplace VOICE host, a per-minute billed realtime audio model call, so (like /voice/token) it is a spend decision and does NOT accept the anonymous visitor token."},{"method":"POST","path":"/chat/transcribe","auth":true,"desc":"Voice note → text (a guest SESSION only — anything spoken needs an account, Maged 2026-10-09): JSON { mime, data(base64), locale? } → { text }. One buffered utterance for the chat composer (NOT the live voice call). 400 on a bad/oversized/non-audio upload, 422 no_speech on a silent recording, 429 rate_limited, 503 stt_not_configured when no key is set."},{"method":"POST","path":"/chat/token","auth":"session-or-anonymous","desc":"Short-lived token for the streaming guest CHAT (kind:chat). No restaurantId ⇒ the marketplace concierge chat; a restaurantId ⇒ that restaurant's host chat. 404 not_found when the restaurant is not publicly listed; 404 chat_disabled when its own chat is switched off (the same answer as chatAvailable on /restaurants/:id). Accepts a guest session OR an anonymous visitor token (POST /auth/anonymous); an anonymous session is READ-ONLY — it can read the menu, prices, allergens, hours and free slots, and it cannot book, order, pay, cancel or look anything up (sign_in_required)."},{"method":"POST","path":"/restaurants/:id/reservations","auth":true,"desc":"Create a reservation. Accepts an optional Idempotency-Key header — a retry with the same key + same body replays the original 201 (no second booking); a different body under the same key → 409 idempotency_conflict."},{"method":"GET","path":"/me/reservations","auth":true,"desc":"Your reservations across restaurants."},{"method":"GET","path":"/me/reservations/:id","auth":true,"desc":"One reservation."},{"method":"PATCH","path":"/me/reservations/:id","auth":true,"desc":"Modify (dateTime — Z or an offset, partySize and/or notes); re-runs the create guards — minimum party size, then availability."},{"method":"DELETE","path":"/me/reservations/:id","auth":true,"desc":"Cancel (soft → CANCELLED)."},{"method":"POST","path":"/me/reservations/:id/arrive","auth":true,"desc":"Self-check-in (sets arrivedAt; idempotent; only while PENDING/CONFIRMED)."},{"method":"POST","path":"/restaurants/:id/delivery-quote","auth":true,"desc":"Preview a delivery cart's fee + minimum at an address (status: ok|below_minimum|out_of_zone). A zoneless restaurant is not deliverable and previews as out_of_zone (empty zones). out_of_zone carries zones: the restaurant's delivery-area names, so the app can show where it DOES deliver."},{"method":"POST","path":"/restaurants/:id/orders","auth":true,"desc":"Place a capture-only order (items carry selected modifiers + optional per-item notes ≤200 chars; delivery enforces zone fee + min-order; optional tipPercent 0/5/10/15 of the food subtotal, computed server-side). Accepts an optional Idempotency-Key header — a retry with the same key replays the original 201 (no second order), backed by the DB unique index for concurrent races; a different body under the same key → 409 idempotency_conflict. Optional `scheduledFor` (ISO instant) orders now for later: the requested time is checked against the restaurant's hours AT THAT INSTANT and refused by name — 409 scheduled_closed (carrying reopensAt) / scheduled_closed_date (one of the restaurant's closed dates; carrying reopensAt) / scheduled_too_soon / scheduled_too_far / scheduled_not_a_slot / invalid_scheduled_time. Absent = as soon as possible."},{"method":"POST","path":"/restaurants/:restaurantId/orders/:orderId/payment-intent","auth":true,"desc":"Mint (or reuse) a Stripe PaymentIntent for an order → { clientSecret, publishableKey, amountCents, currency } plus EITHER { customerId, customerEphemeralKeySecret } (platform charge — ensures the guest's Stripe Customer and opts the card into off-session reuse, so the PaymentSheet shows saved cards + a save toggle) OR { stripeAccount } (Stripe Connect direct charge — the intent lives on the restaurant's connected account, so the client MUST initialise Stripe with that account id; saved cards are platform-scoped and are not offered). Never both. 409 already_paid / order_not_payable (cancelled or completed); 503 stripe_unconfigured."},{"method":"POST","path":"/me/payment-methods/setup-intent","auth":true,"desc":"Mint a Stripe SetupIntent to SAVE a card off-session (no order) → { clientSecret, publishableKey, customerId, customerEphemeralKeySecret }. Card entry stays in the on-device PaymentSheet; PAN never reaches the server. 503 stripe_unconfigured."},{"method":"GET","path":"/me/payment-methods","auth":true,"desc":"Your saved cards → { methods: [{ id, brand, last4, expMonth, expYear, isDefault }] } (no PAN — brand/last4 fetched live from Stripe). Empty when you have no Stripe Customer yet. 503 stripe_unconfigured."},{"method":"DELETE","path":"/me/payment-methods/:paymentMethodId","auth":true,"desc":"Remove a saved card → { ok: true }. Verifies the card belongs to YOUR Stripe Customer before detaching (404 not_found otherwise). 503 stripe_unconfigured."},{"method":"POST","path":"/me/payment-methods/:paymentMethodId/default","auth":true,"desc":"Make a saved card your default → { ok: true }. Writes Stripe invoice_settings.default_payment_method (the same field the list's isDefault reads back). Verifies the card belongs to YOUR Stripe Customer first (404 not_found otherwise). 503 stripe_unconfigured."},{"method":"POST","path":"/me/orders/:id/pay/confirm","auth":true,"desc":"Settle your order's payment after the on-device PaymentSheet succeeds — re-fetches the PaymentIntent from Stripe server-side and only marks PAID when Stripe itself reports succeeded (never trusts the client). Idempotent: safe to call more than once, never overwrites an already-settled stripeRef. 409 order_not_payable (cancelled/completed) or mismatch."},{"method":"GET","path":"/me/orders","auth":true,"desc":"Your orders across restaurants. Optional ?limit=1..100 + ?cursor= (keyset, from the previous page's nextCursor) paginate newest-first; with either param the response adds nextCursor (null = end). Without params: the full legacy list (capped at 100)."},{"method":"GET","path":"/me/loyalty","auth":true,"desc":"Your points and tier at each restaurant whose loyalty scheme you belong to (found by your verified phone; each balance and tier computed by core's guestLoyaltySummary, the till's own arithmetic). `{ restaurants: [{ restaurantId, restaurantName, currency, coverImageUrl, points|null, pointsValueCents|null, tier|null, nextTier|null }] }`; empty without a phone."},{"method":"GET","path":"/me/orders/:id","auth":true,"desc":"One order (with VAT split). Carries `courierTrackingUrl`: the external courier's own live page, only for a run handed to a courier and only while the courier has the food (core `courierTrackingUrlForGuest`), else null. Carries `driverApprox` for a run on the restaurant's OWN driver: { distanceKm, dirX, dirY } — how far away and in which compass direction, never a coordinate (core `driverApproxForGuest`); null outside the same share window, on a stale fix, and when the order address has no geo."},{"method":"POST","path":"/me/orders/:id/cancel","auth":true,"desc":"Cancel an order (soft → CANCELLED; only while PENDING/CONFIRMED)."},{"method":"GET","path":"/me/orders/:id/review","auth":true,"desc":"Read your own review for an order (404 no_review when none)."},{"method":"POST","path":"/me/orders/:id/review","auth":true,"desc":"Rate + review a COMPLETED order (verified, one per order); recomputes the restaurant rating."},{"method":"POST","path":"/me/orders/:id/issue","auth":true,"desc":"Open a problem on an order (reason + first message + optional refund request)."},{"method":"GET","path":"/me/orders/:id/issue","auth":true,"desc":"Read the current problem thread for an order."},{"method":"POST","path":"/me/issues/:id/messages","auth":true,"desc":"Post a message into your problem thread (reopens a resolved one)."},{"method":"POST","path":"/restaurants/:id/support-threads","auth":true,"desc":"Start a general support conversation with a restaurant (not order-tied — an account question, a receipt request, etc)."},{"method":"GET","path":"/me/support-threads","auth":true,"desc":"All your support conversations, across every restaurant you've messaged."},{"method":"GET","path":"/me/support-threads/:id","auth":true,"desc":"One support conversation + its full history."},{"method":"POST","path":"/me/support-threads/:id/messages","auth":true,"desc":"Post a message into your support conversation (reopens a resolved one)."},{"method":"POST","path":"/me/support-threads/:id/csat","auth":true,"desc":"Rate your own RESOLVED support conversation (Act XIII · S9): { score: 1–5, comment? } → 201 { ok: true }. 409 not_ratable for every refusal (not yours, not resolved, already rated — first answer wins); 400 invalid_request."},{"method":"GET","path":"/me","auth":true,"desc":"Your account, plus hasPassword (whether a password is set: the app offers Add or Change from it; the hash never leaves the server)."},{"method":"PATCH","path":"/me","auth":true,"desc":"Update name/locale/country and dietary/notification prefs."},{"method":"DELETE","path":"/me","auth":true,"desc":"Erase account (GDPR right to erasure); also purges the avatar blob and DELETES the guest's Stripe Customer — the name/phone/email we sent Stripe and every saved card. Both external purges are best-effort: they report but never fail the erasure, which always answers 200 { ok: true }."},{"method":"POST","path":"/me/avatar","auth":true,"desc":"Upload a profile photo: JSON { mime, data(base64) } → EXIF-stripped + downscaled to a 512² webp in Vercel Blob → returns the updated guest DTO (with avatarUrl). 400 on a bad/oversized/non-image upload; 503 image_storage_not_configured when no Blob token is set."},{"method":"DELETE","path":"/me/avatar","auth":true,"desc":"Remove the profile photo (clears avatarUrl + deletes the blob) → returns the updated guest DTO."},{"method":"POST","path":"/me/phone/request","auth":true,"desc":"Send an OTP to a phone the signed-in guest wants to attach (email/OAuth accounts sign up phoneless). Same shape as /auth/request-otp: { ok, devCode? } or 429 rate_limited."},{"method":"POST","path":"/me/phone/verify","auth":true,"desc":"Verify the OTP {phone, code} and attach the phone to your account so you can book + order → returns the updated guest DTO. 401 bad_code on a wrong/expired code; 409 phone_in_use if another account already owns that phone (no silent account merge)."},{"method":"POST","path":"/me/password","auth":true,"desc":"Add a password to the SIGNED-IN account {password} → { token, guest } (links email+password onto a Google/Apple account). 409 password_already_set if one exists. This — not /auth/register — is the only way to add a password to an existing account."},{"method":"POST","path":"/me/password/change","auth":true,"desc":"Change the SIGNED-IN account's password {currentPassword, newPassword} → { token, guest }. Requires the current password. 400 password_too_weak (same rule as sign-up) · 409 no_password_set (add one with POST /me/password) · 403 wrong_current_password · 409 same_as_current · 429 rate_limited (5 guesses per guest per 15 min). Ends outstanding reset tokens, and every other session: each token carries the version of the password it was minted under, so only the returned token stays valid."},{"method":"POST","path":"/me/devices","auth":true,"desc":"Register an APNs/FCM push token."},{"method":"DELETE","path":"/me/devices","auth":true,"desc":"Unregister a push token (sign-out): { pushToken }. Guest-scoped + idempotent — 200 even if already gone."},{"method":"GET","path":"/me/recommendations","auth":true,"desc":"Personalized 'For You' restaurant picks (B9·7; order-again + favourites + top-rated). Returns { restaurant, reason }[]."},{"method":"POST","path":"/me/concierge","auth":true,"desc":"Tavolo Concierge (Epic 36) — marketplace 'what should I eat?' picks. Body: optional {query, cuisine, dietary[], priceMaxTier, maxDistanceKm, openNow} filters. Filters the PUBLIC marketplace, ranks by YOUR favourites + order history. Returns { restaurant, reason }[] (public-safe; no cross-tenant/cross-guest data)."},{"method":"GET","path":"/me/notifications","auth":true,"desc":"Your in-app notifications (newest first)."},{"method":"POST","path":"/me/notifications/:id/read","auth":true,"desc":"Mark one notification read."},{"method":"GET","path":"/me/favourites","auth":true,"desc":"Favourite restaurants — read BY ID, so a saved restaurant can never drop off the wishlist once the marketplace passes the discovery listing cap (it used to filter the rating-ranked top 200)."},{"method":"POST","path":"/me/favourites","auth":true,"desc":"Add a favourite. The restaurant must be publicly listed (404 otherwise) and a guest holds at most 500 (409 favourites_full) — the wishlist read passes the saved ids straight to the database, and nothing else bounds them."},{"method":"DELETE","path":"/me/favourites/:id","auth":true,"desc":"Remove a favourite."},{"method":"GET","path":"/me/addresses","auth":true,"desc":"Your saved delivery addresses (default first)."},{"method":"POST","path":"/me/addresses","auth":true,"desc":"Save a delivery address (geocoded server-side unless the device sends latitude/longitude). Accepts an optional Idempotency-Key header — a retry with the same key + same body replays the original 201 (no duplicate address); a different body under the same key → 409 idempotency_conflict."},{"method":"PATCH","path":"/me/addresses/:id","auth":true,"desc":"Update a saved address (a locality change re-geocodes unless coords are supplied)."},{"method":"DELETE","path":"/me/addresses/:id","auth":true,"desc":"Delete a saved address."}]}