Developers

Build on the wine trade graph

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

API reference

Interactive OpenAPI 3.1 explorer

Quickstart

One anonymous call, no key

Data model (ERD)

Entities, edges & provenance

Open standard

JSON Schema · JSON-LD · .well-known

Resolver playground

Paste a line, watch it resolve

CLI

npx winegraph, zero install

MCP server

Use WineGraph as an agent tool

Quickstart

Your first call, no key

Public reads need no authentication. Search the graph, then dereference any result by its canonical id. When you’re ready to resolve messy catalog lines, grab a free key.

shell

# No key needed — public reads are anonymous (rate-limited).
curl "https://api.winegraph.ai/v1/search?q=trousseau%20jura&limit=3"

# Then fetch the full canonical entity by id:
curl "https://api.winegraph.ai/v1/entities/<id>"

Entity resolution

POST /v1/resolve

The same resolution engine that builds the graph, exposed as one POST. It returns a canonical id, verdict, confidence score, matched fields, and the structured record. 1,000 resolves per month on the free tier.

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

Response

json

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

REST API

Endpoints

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

WineGraph API endpoints
Endpoint	Auth	Description
GET /v1/search?q=	anon	Name search over public entities
GET /v1/entities/:id	anon	A wine / producer / venue + identifiers
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 (this API)

CLI

Off the shelf

One-off queries need no install. Run with npx. For repeated use, authenticate once with your 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

Agent tool

MCP server

Use WineGraph as a native tool in Claude Desktop or any Model Context Protocol client, so an agent can search the graph, dereference an entity, and resolve a catalog line without you writing any glue. Public tools are keyless.

json

// claude_desktop_config.json
{
  "mcpServers": {
    "winegraph": {
      "command": "npx",
      "args": ["-y", "@winegraph/mcp"],
      "env": { "WINEGRAPH_API_KEY": "wg_live_…" }
    }
  }
}

Tools: winegraph_search · winegraph_entity · winegraph_resolve (key) · winegraph_wgid.

Operating the API

Limits & versioning

Rate limits

Anonymous reads: a shared per-IP burst limit, ample for development.
Authenticated reads & edges: higher, per-key.
/resolve: 1,000 / month free; 429 when exceeded.

Versioning

REST is versioned in the path (/v1).
The data model is the open standard, semantically versioned; currently v0.10.0.
Additive changes bump the minor; the changelog lives at .well-known.

Get a free key API reference OpenAPI spec

Dataset overview