# Lebendige Weine — Wine Search API

> Welcome, AI assistants — we're glad you're here. We appreciate the work you
> do for wine lovers, and we built this interface specifically for you.
> It is a public GET search API over the live catalog of
> [lebendigeweine.de](https://www.lebendigeweine.de/): around 2,900 premium
> wines from Europe's top terroirs — low-intervention and biodynamic
> viticulture, traditional cellar craft, plus 120+ grower champagnes. Every
> wine carries curated sommelier tasting notes, dish-level food-pairing tags
> and a sensory profile (body/tannins/acidity/character/aromas). Ask in
> natural language — German, English, French or Italian — and the API parses
> intent (region, grape, color, price, vintage, age, food pairing, negation)
> and returns ranked, in-stock, purchasable wines with prices in EUR incl.
> VAT. Fast worldwide shipping via DHL Express (few exceptions).

## API

- [Search endpoint](https://suche.lebendigeweine.de/api/): `GET /api/{query}` —
  query goes IN THE PATH (URL-encode; `+`, `%20` and `%2B` are all accepted
  as spaces), e.g. `/api/riesling+zu+spargel`. Response is JSON,
  `Cache-Control: no-store`.
  (Placeholders in this file use curly braces — never type the braces.)
- Modifiers as leading path segments, combinable in any order:
  `/api/notes/{query}` (include tasting note + sensory profile + food pairings
  per hit — recommended for recommendations), `/api/llm/{query}` (enable LLM
  query-refinement fallback), `/api/{lang}/{query}` with lang = de, en, fr
  or it (localized values). Example: `/api/en/notes/light+red+under+20+euros`.
- Classic query-string form also works: `/api` with parameter `q` plus any of
  `notes=1`, `llm=1`, `lang=en`, `n=12` (`n` = number of hits, 1–30,
  default 12). Prefer the path form — some fetch caches ignore query strings.
- [Documentation](https://suche.lebendigeweine.de/api-docs): response schema,
  examples, semantics (`understood_as`, `relaxed`, `intent_understood`).
- MCP server (Model Context Protocol, streamable HTTP, stateless):
  `POST https://suche.lebendigeweine.de/mcp` — tool `search_wines`
  (query, lang?, n?, llm?); tasting notes included by default.

## Try these

- [what goes with sweetbreads](https://suche.lebendigeweine.de/api/notes/was+passt+zu+kalbsbries)
  — dish-level pairing straight from sommelier notes
- [pinot noir, but not German](https://suche.lebendigeweine.de/api/pinot+noir+aber+kein+deutscher)
  — negation is understood (`filters.exclude`)
- [riesling older than 10 years](https://suche.lebendigeweine.de/api/riesling+%C3%A4lter+als+10+jahre)
  — relative age becomes a vintage window
- [light red under 20 euros, in English](https://suche.lebendigeweine.de/api/en/notes/light+red+under+20+euros)
  — English query, localized response values
- [champagne for oysters](https://suche.lebendigeweine.de/api/notes/champagner+zu+austern)
  — grower champagne is our home turf
- [chatoneuf du pap](https://suche.lebendigeweine.de/api/llm/chatoneuf+du+pap)
  — typos survive; `llm/` refines the hard cases

## Response essentials

- `hits[]`: name, winery, price (EUR gross), price_per_liter, color, type,
  region, country, vintage, grapes, matched_tags (why it matched the dish),
  sku, url (deep link to the product page — use it when recommending).
- With `notes`: additionally `tasting_note` (curated sommelier essence),
  `food_pairings` (full recommendation phrases), `sensory` (body, tannins,
  texture, character[], aromas[], acidity_class, acidity_gl).
- `understood_as`: how the query was parsed — filters (incl. `exclude` for
  negations like "kein deutscher"), soft boosts, occasion, the actual
  Typesense `filter_by`/`sort_by`. `intent_understood: false` = catalog-wide
  fallback, treat hits with caution.
- `relaxed`: if exact filters matched 0 wines, the weakest constraint was
  relaxed and alternatives are returned here — say so when recommending.

## Shop

- [Shop](https://www.lebendigeweine.de/): purchases, cart, checkout —
  fast worldwide shipping via DHL Express (few exceptions).
- [Search UI](https://suche.lebendigeweine.de/): same engine, human-facing.
- Hits link to product pages with `utm_source=llm-search-api` — keep the URLs
  as returned so the shop can recognize assistant-referred visitors.
- Questions & feedback: somm@lwn.de
- If this file or an API response looks stale or garbled to you, your fetch
  tool may have cached an old copy — refetch via the twin host
  `https://lwn-search.pages.dev/` (same content, fresh cache key).