# Introduction (https://eulabel.eu/docs/api-reference/overview/introduction)

> Fetch the complete documentation index at: https://eulabel.eu/docs/llms.txt
> Use this file to discover all available pages before exploring further.
> Full content: https://eulabel.eu/docs/llms-full.txt
> Append .md to any page URL for markdown, or send Accept: text/markdown.



The EUlabel API provides endpoints for managing products, digital passports, suppliers, and scan analytics. All endpoints follow a consistent design: simple, predictable, and well-documented.

Base URL [#base-url]
```text
https://api.eulabel.eu/v1
```
Authentication [#authentication]

All requests require an API key in the `Authorization` header:
```bash
curl https://api.eulabel.eu/v1/products \
  -H "Authorization: Bearer sk_test_..."
```
See [Authentication](https://eulabel.eu/docs/documentation/get-started/authentication) for details on API keys and scopes.

Request format [#request-format]

* Request bodies use JSON (`Content-Type: application/json`)
* All timestamps are ISO 8601 in UTC
* Product identifiers are UUIDs; passport IDs use short prefixed strings (`ps_...`)

Pagination [#pagination]

List endpoints return paginated results:
```json
{
  "data": [...],
  "pagination": {
    "total": 142,
    "limit": 20,
    "offset": 0
  }
}
```
| Parameter | Type    | Default | Description                       |
| --------- | ------- | ------- | --------------------------------- |
| `limit`   | integer | `20`    | Maximum items to return (max 100) |
| `offset`  | integer | `0`     | Number of items to skip           |
```bash
curl "https://api.eulabel.eu/v1/products?limit=50&offset=50" \
  -H "Authorization: Bearer sk_test_..."
```
Rate limiting [#rate-limiting]

> **Warning**
> Exceeding the rate limit returns a `429` status code. Implement exponential backoff in your retry logic.

Requests are rate-limited per API key.

> **Note**
> Rate-limit response headers (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`) are **planned** but not yet returned. Design your integration with exponential backoff so it works today and benefits from these headers automatically when they ship.

See the [Error Handling guide](https://eulabel.eu/docs/knowledge-base/guides/error-handling) for retry strategies.

Versioning [#versioning]

The API is versioned via URL path (`/v1/`). Breaking changes result in a new version. Non-breaking additions (new fields, new endpoints) are added to the current version without notice.

Error format [#error-format]

All errors return a nested `error` object:
```json
{
  "error": {
    "type": "validation_error",
    "message": "gtin is required",
    "code": "validation_error",
    "param": "gtin",
    "suggestion": "Provide a valid 8, 12, 13, or 14-digit GTIN.",
    "documentationUrl": "https://eulabel.eu/docs/knowledge-base/guides/gtin-validation"
  }
}
```
| Field              | Type   | Description                                                  |
| ------------------ | ------ | ------------------------------------------------------------ |
| `type`             | string | Machine-readable error category                              |
| `message`          | string | Human-readable explanation                                   |
| `code`             | string | Error code (matches `type`)                                  |
| `param`            | string | The request field that caused the error (when applicable)    |
| `suggestion`       | string | Actionable guidance on how to fix the error (when available) |
| `documentationUrl` | string | Link to relevant documentation (when available)              |

The HTTP status code is returned in the response status line, not in the body. The `suggestion` and `documentationUrl` fields are present on most validation errors to help developers and AI agents resolve issues without leaving the terminal.

Status codes [#status-codes]

| Code  | Meaning                                      |
| ----- | -------------------------------------------- |
| `200` | Success                                      |
| `201` | Resource created                             |
| `400` | Malformed request (invalid JSON)             |
| `401` | Missing or invalid authentication            |
| `403` | Insufficient permissions                     |
| `404` | Resource not found                           |
| `422` | Validation error (check the `message` field) |
| `429` | Rate limit exceeded                          |
| `500` | Internal server error                        |

Endpoints [#endpoints]

- [Passports](https://eulabel.eu/docs/api-reference/endpoints/passports) — Create, enrich, and retrieve Digital Product Passports — the primary entry point
- [Products](https://eulabel.eu/docs/api-reference/endpoints/products) — List and manage products (created implicitly via passports)
- [QR Codes](https://eulabel.eu/docs/api-reference/endpoints/qr-codes) — Generate GS1 Digital Link QR codes
- [Suppliers](https://eulabel.eu/docs/api-reference/endpoints/suppliers) — Manage economic operators
- [Domains](https://eulabel.eu/docs/api-reference/endpoints/domains) — Register and verify custom domains
- [API Keys](https://eulabel.eu/docs/api-reference/endpoints/api-keys) — Create, list, and revoke API keys
- [Analytics](https://eulabel.eu/docs/api-reference/endpoints/analytics) — Retrieve scan analytics