A good first call.

Quick start

1. Create a free account and open the developer dashboard.
2. Create an API key. Copy the full key immediately; Winevery stores only its hash.
3. Make a request from your server.

curl 'https://www.winevery.com/api/v1/wines?q=rioja&limit=3' \
  -H 'Authorization: Bearer YOUR_API_KEY'

The Sandbox includes 250 credits per calendar month, with no payment card. The dashboard shows your quota, keys and recent usage.

Authentication

Send Authorization: Bearer YOUR_API_KEY with every request. Keys begin with wv_live_. Store them in server environment variables. Never put them in URLs, frontend bundles, analytics events or public repositories.

API keys only authorize the public data endpoints below. They do not grant access to your account, cellar, journal or Passport. Your website session is used separately to manage keys and billing.

Rotate or revoke keys from the dashboard. Rotation immediately revokes the old key and shows a replacement once. Requests with revoked or expired keys return 401. Browser cross-origin API calls are not enabled; call the API through your backend.

Endpoint reference

Base URL: https://www.winevery.com/api/v1

Request examples

JavaScript / Node.js

const response = await fetch(
  'https://www.winevery.com/api/v1/wines?q=rioja&limit=3',
  { headers: { Authorization: 'Bearer ' + process.env.WINEVERY_API_KEY } }
);
const result = await response.json();
if (!response.ok) throw new Error(result.error.message);
console.log(result.data.wines);

Python

import os
import requests

response = requests.get(
    "https://www.winevery.com/api/v1/wines",
    params={"q": "rioja", "limit": 3},
    headers={"Authorization": "Bearer " + os.environ["WINEVERY_API_KEY"]},
    timeout=20,
)
response.raise_for_status()
print(response.json()["data"]["wines"])

Food pairing

curl 'https://www.winevery.com/api/v1/pairings' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"dish":"roast lamb with rosemary","limit":3}'

Response envelope

{
  "data": { "wines": [], "pagination": { "page": 1, "limit": 3, "hasNext": false } },
  "meta": {
    "requestId": "a UUID for support",
    "creditsUsed": 1,
    "creditsRemaining": 249,
    "quotaResetsAt": "2026-12-01T00:00:00.000Z"
  }
}

This envelope is illustrative. Endpoint data and reset dates depend on your request and subscription.

Credits and limits

Quotas and request rates are shared across every key on your account. A paginated search is one request, up to 48 results. Similarity costs 3 credits and food pairing costs 5 credits. Credits are deducted only for successful 2xx responses; validation and server errors are refunded.

Sandbox quotas reset at the start of each calendar month in UTC. Paid quotas reset with the Stripe monthly billing period. Unused credits expire. There are no automatic overage charges.

Successful responses include X-Credits-Limit, X-Credits-Remaining, X-Quota-Reset (Unix seconds), X-RateLimit-Limit (requests per minute) and X-Request-Id. A 429 response includes Retry-After in seconds. Check the error code to distinguish a short rate-limit wait from an exhausted monthly quota.

POST bodies must be JSON and at most 8 KB. Bulk enumeration and exports are not included in self-service plans.

Errors and retries

{"error":{"code":"invalid_api_key","message":"…","requestId":"…"}}

Contact hello@winevery.com with the request ID, endpoint and approximate time. Do not include your key.

Data, caching and use

Wine profiles use stable Winevery IDs. Taste axes run from 0 to 100. Missing values are unknown; do not turn null into zero. Similarity and pairing use the available recorded attributes, and can return fewer matches when coverage is limited. This release does not provide live retail prices, stock, label recognition or generated tasting notes.

Paid plans allow use and caching of metadata inside the subscribed application, with visible Winevery attribution where practical. Self-service plans do not include raw-data resale, standalone data feeds, bulk exports or model-training rights. Contact us for a separate agreement. See the API terms and API privacy notice.

The public MCP connector remains a separate read-only interface with its existing access model.