Wine Pairing API Quickstart

Get an API key

Sign up on the developer portal. You get 50 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 six 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 real, unedited response 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. On PRO and ENTERPRISE you also see 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.