Developers

API & CLI

WineGraph is shared, neutral infrastructure for the wine trade: a typed graph and an entity-resolution API you build on, the same way you would reach for Stripe or Plaid. Public reads are anonymous and rate-limited. /resolve and graph traversal require a free, role-validated key.

CLI

Off the shelf

The CLI requires no install for one-off queries — run it with npx. For repeated use, authenticate once with your API key.

shell

# zero install
npx winegraph search "trousseau jura"
npx winegraph wine <id>

# with a key (get one at /access)
npx winegraph auth wg_live_…
npx winegraph resolve "2022 Overnoy Ploussard" --json
npx winegraph usage

REST API

Endpoints

Authentication: pass your key as Authorization: Bearer wg_live_… on all authenticated endpoints. Get a free key at /access.

WineGraph API endpoints
Endpoint	Auth	Description
GET /v1/entities/:id	anon	A wine / producer / venue + identifiers
GET /v1/search?q=	anon	Name search over public entities
GET /v1/entities/:id/edges	key	Trade-graph edges (produces, listed_by, opt-in imports)
POST /v1/resolve	key	Resolve a catalog line → canonical entity (1k/mo free)
GET /v1/usage	key	Your quota
GET /openapi.json	—	OpenAPI 3.1

Entity resolution

POST /v1/resolve

The same resolution engine that builds the graph is exposed as a single POST. One call returns a canonical ID, verdict, confidence score, matched fields, and the full structured record. 1,000 calls per month on the free tier.

shell

curl -X POST https://api.winegraph.ai/v1/resolve \
  -H "Authorization: Bearer wg_live_…" \
  -H "Content-Type: application/json" \
  -d '{"raw":"2022 Overnoy Ploussard"}'

{
  "canonicalId": "…",
  "verdict": "auto_merge",
  "score": 0.97,
  "matchedOn": ["producer","vintage","grape"],
  "entity": {
    "name": "…",
    "wine": { "grapes": [{"grape":"ploussard"}] }
  }
}

Get a free key OpenAPI spec

Dataset overview →