Vraag een API-key aan

Maak een account in het developerportaal. Je begint met 100 gratis calls per dag, zonder creditcard.

Ga naar business.sommelierx.com en kopieer je key. Die begint met sk_live_, gevolgd door 32 hexadecimale tekens.

export SOMMELIERX_API_KEY="sk_live_..."

Kies het juiste endpoint

Kies op basis van wat je al weet. Een vrije gerechtomschrijving is meestal de snelste route.

Voer een werkend voorbeeld uit

Deze request laat SommelierX zelf de ingrediënten uit de beschrijving halen en matchen.

curl -X POST https://api.sommelierx.com/api/v1/pairing/by-text \
  -H "Authorization: Bearer $SOMMELIERX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "gegrilde zalm met citroen en dille",
    "language": "nl"
  }'

De response bevat de herkende ingrediënten en maximaal 25 wijnstijlen, gerangschikt op match_percentage. Resultaten onder 65 worden niet getoond.

Van een wijn naar gerechten

curl https://api.sommelierx.com/api/v1/pairing/by-wine/723/meals \
  -H "Authorization: Bearer $SOMMELIERX_API_KEY"

Eén wijn voor meerdere gangen PRO

curl -X POST https://api.sommelierx.com/api/v1/pairing/group \
  -H "Authorization: Bearer $SOMMELIERX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mealIds": [4329, 4330, 4331], "language": "nl" }'

mealCoverage toont bij hoeveel gangen de wijn de ondergrens haalt; avgScore is het gemiddelde over de gedekte gangen.

Begrijp de matchscore

Free toont het matchpercentage. Starter, Pro en Enterprise tonen ook de volledige berekening.

Gebruik SommelierX via MCP

Koppel de MCP-server aan een compatibele client en stel je vragen in gewone taal.

{
  "mcpServers": {
    "sommelierx": {
      "command": "npx",
      "args": ["@sommelierx/mcp-server"],
      "env": { "SOMMELIERX_API_KEY": "sk_live_..." }
    }
  }
}

De API-key is optioneel. Zonder key geldt het Free-niveau op basis van het IP-adres.

Get an API key

Sign up on the developer portal. You get 100 free calls per day, no credit card required.

Go to business.sommelierx.com, create an account, and copy your key. It starts with sk_live_ followed by 32 hex characters.

Export it as an environment variable so you can use it across the rest of this guide:

export SOMMELIERX_API_KEY="sk_live_..."

Pick the right endpoint

Most pairing tasks fit into one of eight patterns. Find your input on the left, use the endpoint on the right.

Three working examples

Each block below is a complete request with a representative response shape from api.sommelierx.com. Copy, paste, run.

Example A — Pair from a free-text dish

The simplest entry point: send a sentence in any language. The API extracts ingredients, resolves them to database IDs, and returns ranked wine styles.

curl -X POST https://api.sommelierx.com/api/v1/pairing/by-text \
  -H "Authorization: Bearer $SOMMELIERX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "grilled salmon with lemon and dill",
    "language": "en"
  }'

Response (PRO tier, top 2 of 25 results shown):

{
  "data": {
    "resolved_ingredients": [
      { "input": "salmon", "matched": true, "ingredient": { "id": 6144, "name": "Salmon" } },
      { "input": "lemon",  "matched": true, "ingredient": { "id": 3656, "name": "Lemon"  } },
      { "input": "dill",   "matched": true, "ingredient": { "id": 3792, "name": "Dill"   } }
    ],
    "pairing_results": [
      {
        "metaWineId": 723,
        "name": "Semillon-Sauvignon New World Top",
        "type":   { "id": 4, "name": "White dry", "color": "white" },
        "region": "New World",
        "grapes": ["Sauvignon Blanc", "Sémillon"],
        "score": {
          "match_percentage": 88,
          "basic_score":      9,
          "balance_score":    0,
          "aromatic_score":   9
        },
        "priceSegment": "top",
        "whyText": "Sauvignon Blanc's herbaceous intensity amplifies dill's anise notes while Sémillon's waxy texture matches salmon's richness."
      },
      {
        "metaWineId": 1034,
        "name": "Arinto and Fernão Pires Portugal Basic",
        "type":   { "id": 4, "name": "White dry", "color": "white" },
        "region": "Portugal",
        "grapes": ["Arinto", "Fernão Pires", "Sauvignon Blanc", "Viognier"],
        "score": {
          "match_percentage": 88,
          "basic_score":      9,
          "balance_score":    0,
          "aromatic_score":   9
        },
        "priceSegment": "basic"
      }
    ]
  },
  "meta": {
    "tier": "pro",
    "calls_remaining_today": 4998,
    "rate_limit_reset": "2026-04-17T00:00:00.000Z"
  }
}

What you get back. Up to 25 wine styles ranked by match_percentage, filtered to a minimum of 65/100. Each result includes the wine’s name, color, region, grapes, a price segment hint (basic / middle / top), and on PRO tier a one-sentence whyText explaining the match.

Example B — Pair to a meal in our catalog

If you already have a meal ID from GET /meals or GET /search, skip the natural-language step.

curl -X POST https://api.sommelierx.com/api/v1/pairing/by-meal/5572 \
  -H "Authorization: Bearer $SOMMELIERX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "en" }'

Response (meal 5572 = “Salmon sashimi”, top result shown):

{
  "data": {
    "mealId": 5572,
    "results": [
      {
        "metaWineId": 790,
        "name": "Chardonnay Southern Europe Middle",
        "type":   { "id": 4, "name": "White dry", "color": "white" },
        "region": "Southern Europe",
        "grapes": ["Chardonnay"],
        "glassType": { "id": 4, "name": "Burgundy White" },
        "score": {
          "match_percentage": 87,
          "basic_score":      9,
          "balance_score":    0,
          "aromatic_score":   9
        },
        "priceSegment": "middle",
        "whyText": "Southern Europe's warm-climate Chardonnay's mineral backbone amplifies the salmon's natural oils while respecting its pristine texture."
      }
    ]
  },
  "meta": {
    "tier": "pro",
    "calls_remaining_today": 4997,
    "rate_limit_reset": "2026-04-17T00:00:00.000Z"
  }
}

Example C — One wine across three courses PRO

Dinner party with a chicken starter, a vegetable main, and a steak? /pairing/group finds wines that score well across every meal, not just the average.

curl -X POST https://api.sommelierx.com/api/v1/pairing/group \
  -H "Authorization: Bearer $SOMMELIERX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mealIds": [4329, 4330, 4331],
    "language": "en"
  }'

Response (top wine shown):

{
  "data": {
    "meals": [
      { "id": 4329, "name": "Fried chicken with beurre blanc and leaf spinach" },
      { "id": 4330, "name": "Puff pastry tartlet with vegetables" },
      { "id": 4331, "name": "Fried Angus rib-eye with Café de Paris" }
    ],
    "wines": [
      {
        "metaWineId": 1152,
        "name": "Bobal Spain Basic",
        "type":   { "id": 10, "name": "Red dry", "color": "red" },
        "region": "Spain",
        "priceSegment": "basic",
        "avgScore":     75,
        "mealCoverage": 3,
        "totalMeals":   3,
        "perMealScores": [
          { "mealId": 4329, "mealName": "Fried chicken with beurre blanc and leaf spinach", "score": 74 },
          { "mealId": 4330, "mealName": "Puff pastry tartlet with vegetables",              "score": 75 },
          { "mealId": 4331, "mealName": "Fried Angus rib-eye with Café de Paris",           "score": 75 }
        ]
      }
    ]
  },
  "meta": {
    "tier": "pro",
    "calls_remaining_today": 4992,
    "rate_limit_reset": "2026-04-17T00:00:00.000Z"
  }
}

Read this carefully. mealCoverage = how many of the supplied meals scored above the threshold. avgScore = average across covered meals. A wine with mealCoverage: 2 may have a higher average than one with mealCoverage: 3 — sort by whichever matters more for your use case.

Understand the score

Every pairing returns a score object. On FREE tier you get match_percentage only. STARTER, PRO and ENTERPRISE also expose the three components that produced it.

How they combine.

// 1. Average the basic and aromatic scores (or use basic only if aromatic is null)
final = aromatic_score !== null
  ? (basic_score + aromatic_score) / 2
  : basic_score

// 2. Apply the balance penalty
final = balance_score > 0
  ? final - (0.5 * balance_score)
  : final - (-1 * balance_score)

// 3. Scale to 0-100
match_percentage = Math.ceil(final * 10)

Use it in Claude Desktop, Cursor, or Windsurf

If you don’t want to write code, drop the SommelierX MCP server into any MCP-compatible client and ask in plain English.

Add this to your client’s MCP config (e.g. Claude Desktop’s claude_desktop_config.json):

{
  "mcpServers": {
    "sommelierx": {
      "command": "npx",
      "args": ["@sommelierx/mcp-server"],
      "env": {
        "SOMMELIERX_API_KEY": "sk_live_..."
      }
    }
  }
}

Restart your client and ask things like:

• “What wine pairs with grilled lamb and rosemary?”
• “I have a Barolo. What should I cook?”
• “Suggest one wine for a three-course dinner: oysters, duck, chocolate cake.”

The SOMMELIERX_API_KEY env var is optional — without it you get the same FREE tier limits, just keyed to your IP.