> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vinum-elabel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> Manage your e-labels programmatically — connect your ERP or cellar software.

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:

```bash theme={null}
curl https://dbkeivdnqadcrblsoudq.supabase.co/functions/v1/api-v1/labels \
  -H "Authorization: Bearer vk_your_key"
```

<Note>
  Rate limit: 60 requests per minute per key. Exceeding it returns
  `429 RATE_LIMITED`.
</Note>

## Endpoints

### List labels

```bash theme={null}
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

```bash theme={null}
GET /api-v1/labels/{id}
```

### Download the QR code

```bash theme={null}
GET /api-v1/labels/{id}/qr.svg
```

Returns the print-ready SVG.

### Create a label <sup>Estate</sup>

```bash theme={null}
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.

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

### Update a label <sup>Estate</sup>

```bash theme={null}
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                |