API reference

The Vinum E-Label API lets your systems read and manage e-labels. Read access is included in the Unlimited plan; creating and updating labels requires Estate.

Authentication

Create an API key under Account → API. The key is shown once — store it securely. Send it as a bearer token:

curl https://dbkeivdnqadcrblsoudq.supabase.co/functions/v1/api-v1/labels \
  -H "Authorization: Bearer vk_your_key"

Rate limit: 60 requests per minute per key. Exceeding it returns 429 RATE_LIMITED.

Endpoints

List labels

GET /api-v1/labels

Returns your hosted labels (up to 200, newest first). External labels tracked from other providers are not included.

Get a label

GET /api-v1/labels/{id}

Download the QR code

GET /api-v1/labels/{id}/qr.svg

Returns the print-ready SVG.

Create a label ^Estate

POST /api-v1/labels
Content-Type: application/json

{
  "wineName": "Riesling 2025",
  "wineType": "white",
  "producer": "Weingut Beispiel",
  "country": "germany",
  "region": "Mosel",
  "alcoholContent": "11.5% vol",
  "ingredients": ["grapes", "sulphites"]
}

Labels are created as drafts ("active": false). The free-tier label cap applies to API-created labels too.

Ingredients accept canonical keys (grapes, sulphites, tartaric-acid, …) which display translated in all 24 languages — or free text, shown as sent.

Update a label ^Estate

PATCH /api-v1/labels/{id}

Send only the fields you want to change. Setting "active": true publishes the label — make sure the mandatory particulars are complete first.

Fields

Field	Type	Notes
`wineName`	string
`wineType`	string	`red`, `white`, `rose`, `sparkling`, `other`
`producer`, `country`, `region`, `bottler`	string
`alcoholContent`	string	e.g. `"11.5% vol"`
`netContent`	string	e.g. `"750ml"`
`energyKJ`, `energyKcal`, `fat`, `saturatedFat`, `carbohydrates`, `sugar`, `protein`, `salt`	string	per 100 ml
`ingredients`	string[]	Canonical keys (`grapes`, `tartaric-acid`, `sulphites`, …) or free text. Additives are published with their functional category; a canonical additive takes it from the EU list. Where the EU list allows more than one function (`citric-acid`), or for a free-text additive, send the function with the entry: `stabilising-agents:citric-acid`, `acidity-regulators:citric-acid`, `stabilising-agents:My additive`. Categories: `acidity-regulators`, `preservatives-antioxidants`, `stabilising-agents`, `gases`. For a canonical additive a category outside the EU list is ignored. Sulphites that are present above 10 mg/l without having been added are sent as `sulphites-natural`: declared as an allergen, without a category.
`allergens`	string[]	Canonical keys (`sulphites`, `egg`, `milk`) or free text. List every allergen in `ingredients` too: a declared allergen that is missing from the list is still shown publicly, at the end of the list.
`active`	boolean	publish state

Errors

Code	Meaning
`401 INVALID_API_KEY`	Missing, malformed or revoked key
`403 PLAN_REQUIRED`	API needs the Unlimited or Estate plan
`403 ESTATE_REQUIRED`	Write endpoints need Estate
`403 LABEL_LIMIT_REACHED`	Free-tier label cap hit
`429 RATE_LIMITED`	Over 60 requests/minute

Partner wineries

Concierge-enabled partner accounts can create read API keys even without an account-level Unlimited subscription. Write operations still require Estate.

GET /api-v1/wineries returns owned winery IDs, names, addresses, identity locks and billing summaries.
GET /api-v1/labels?winery_id=<uuid> filters the account’s labels by winery. Label responses include wineryId and winery: { id, name }.
Estate POST /api-v1/labels accepts wineryId. It is required when the account has multiple wineries; an account with exactly one winery can omit it. Complete winery onboarding before creating labels.
Winery assignment is permanent. producer is derived from the winery; contractBottler is the optional different bottler including address.
Publication enforces completeness and the partner winery subscription in the database, including direct active: true inserts. WINERY_SUBSCRIPTION_REQUIRED, WINERY_REVIEW_REQUIRED, LABEL_WINERY_IMMUTABLE and LABEL_INCOMPLETE return HTTP 409.

Printed QR URLs continue to use https://vinum-elabel.com/e-labels/<label-id>?src=qr. Retiring a partner label preserves its last published public content while excluding it from future renewal quantities.

Get started

Guides

Compliance

Reference

Developers

Authentication

Endpoints

List labels

Get a label

Download the QR code

Create a label ^Estate

Update a label ^Estate

Fields

Errors

Partner wineries

​Authentication

​Endpoints

​List labels

​Get a label

​Download the QR code

​Create a label Estate

​Update a label Estate

​Fields

​Errors

​Partner wineries

Authentication

Endpoints

List labels

Get a label

Download the QR code

Create a label ^Estate

Update a label ^Estate

Fields

Errors

Partner wineries