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`, `allergens`	string[]	canonical keys or free text
`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

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

​Authentication

​Endpoints

​List labels

​Get a label

​Download the QR code

​Create a label Estate

​Update a label Estate

​Fields

​Errors

Authentication

Endpoints

List labels

Get a label

Download the QR code

Create a label ^Estate

Update a label ^Estate

Fields

Errors