# Digital menus and storefronts

This site hosts digital menus and online storefronts for restaurants, cafes and
shops. Each location is addressed by an uppercase domain code: the menu of
location MYCAFE lives at /MYCAFE on this host (the same code is encoded in the
table QR codes).

The platform runs under several brand apex domains. Everything below is
relative to the apex domain this file is served from — substitute it for
`<apex>`. The one absolute URL in this file is explicitly marked as an example.

- Human-readable API documentation: /docs/llm-api
- MCP servers manifest: /.well-known/mcp.json
- Per-location machine-readable guide: https://cdn.<apex>/{DOMAIN}/llms.txt
- Raw menu data per location: https://cdn.<apex>/{DOMAIN}/menu_{lang}.json

## API for LLM systems and agents

Machine-friendly API (no auth required) to read menus and storefronts, ask
questions about the store, build a cart, place orders and track them. All paths
below are relative to https://api.<apex> :

- Discovery: /llm/v1
- OpenAPI 3.1: /llm/v1/openapi.json
- Menu: GET /llm/v1/locations/{DOMAIN}/menu?lang={iso2}
- Item: GET /llm/v1/locations/{DOMAIN}/items/{itemId}
- Items in bulk (up to 10): GET /llm/v1/locations/{DOMAIN}/items?ids=a,b,c
- Semantic product search: GET /llm/v1/locations/{DOMAIN}/search?q={query}
- Create a cart: POST /llm/v1/locations/{DOMAIN}/carts
- Read a cart: GET /llm/v1/locations/{DOMAIN}/carts/{cartId}
- Update a cart: PATCH /llm/v1/locations/{DOMAIN}/carts/{cartId}
- Place order: POST /llm/v1/locations/{DOMAIN}/orders
- Order status: GET /llm/v1/locations/{DOMAIN}/orders/{orderId}
- Table availability: GET /llm/v1/locations/{DOMAIN}/reservations/availability?start={iso}&durationMinutes=120
- Reserve a table: POST /llm/v1/locations/{DOMAIN}/reservations
- Reservation status / cancel: GET|DELETE /llm/v1/locations/{DOMAIN}/reservations/{reservationId}
- Store info, policies and FAQ: exposed as the MCP tools get_store_info and
  search_policies_and_faqs; their REST paths are listed in the discovery
  document and in the OpenAPI spec above.

Example request (meni.ge brand — substitute your own apex domain):
https://api.meni.ge/llm/v1/locations/MYCAFE/menu?lang=en

## MCP (Model Context Protocol)

Stateless streamable-HTTP MCP server at https://api.<apex>/llm/mcp with 13
guest tools:

- Catalog: get_menu, get_item, search_products
- Cart: update_cart, get_cart
- Store: get_store_info, search_policies_and_faqs
- Orders: create_order, get_order_status
- Reservations: check_table_availability, create_reservation,
  get_reservation_status, cancel_reservation

## Cart and checkout handoff

update_cart creates or edits a cart (the returned cartId is an unguessable
bearer token) and returns a view with per-line prices computed from the live
menu, a subtotal, and a checkoutUrl of the form
https://<apex>/{DOMAIN}?llmCart={cartId} . Hand that URL to the person: opening
it loads the cart into the site's own basket so they can review and finish the
order themselves. Alternatively, call create_order with the cartId to place the
order directly. Carts expire 7 days after their last update; prices are never
stored inside a cart, they are recomputed from the live menu on every read.

## Store information

get_store_info returns structured facts about a location: address and
coordinates, phone and email, timezone, working hours and whether the place is
open right now, social links, accepted payment methods and currency, delivery
and pickup terms, shipping/returns terms, available languages, and links to the
location's legal documents. search_policies_and_faqs answers free-form
questions over the location's legal documents, published pages and FAQ
sections.

## Notes

- Orders placed through the API appear in the location's admin panel in real
  time; the unguessable orderId returned by the API is the access token for
  status checks — keep it private.
- Orders created by AI agents are attributed with channel "ai-agent".
- Pass idempotencyKey (8..64 characters) to create_order when retrying, so that
  a retry cannot create a duplicate order.
- customer.name and customer.phone are required for pickup and delivery orders;
  delivery.address is required for delivery.
- Texts served to agents are in English unless a lang/language parameter asks
  for another language.