# BarGen API Documentation

## Introduction

The BarGen API generates barcode and QR code images from your data through simple HTTP requests. Output formats: **SVG, PNG, PDF and EPS**.

- **API base URL:** `https://api.bargen.pro`
- **Dashboard:** `https://bargen.pro/dashboard`

## Authentication

Every request — except `GET /v1/formats` and `GET /v1/health` — requires an API key, which you can create in your dashboard at https://bargen.pro/dashboard/api-keys

Pass the key any one of these ways:

- Header: `X-API-Key: YOUR_KEY` *(recommended)*
- Header: `Authorization: Bearer YOUR_KEY`
- Query parameter: `?key=YOUR_KEY`

> The query parameter is named `key` (not `api_key`).

## Endpoints

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| `GET`  | `/v1/health` | no | Service health check |
| `GET`  | `/v1/formats` | no | List all barcode types and the plan each requires |
| `GET`  | `/v1/validate` | yes | Validate your API key and see usage |
| `GET`  | `/v1/barcode/{type}` | yes | Generate a single barcode image |
| `POST` | `/v1/barcode/batch` | yes | Generate up to 50 barcodes in one request |

## Generate a barcode

```
GET /v1/barcode/{type}?data=YOUR_DATA&format=svg
```

The response body is the raw image with the matching `Content-Type`
(`image/svg+xml`, `image/png`, `application/pdf`, or `application/postscript`).

### Parameters

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `data` | yes | — | The content to encode (URL-encode it) |
| `format` | no | `svg` | Output format: `svg`, `png`, `pdf`, `eps` (plan-gated) |
| `scale` | no | `2` | Module scale, 1–10 |
| `width` | no | auto | Target width in px, 10–2000 |
| `height` | no | auto | Target height in px, 10–2000 |
| `color` | no | `000000` | Foreground colour, hex without `#` |
| `bgcolor` | no | `ffffff` | Background colour, hex without `#` |
| `includetext` | no | `true` | Show the human-readable text line |
| `fontsize` | no | `14` | Text size, 8–24 |
| `ecl` | no | `M` | QR error-correction level: `L`, `M`, `Q`, `H` |
| `pngzoom` | no | `1` | Extra zoom for PNG output, 0.5–10 |

### Examples

```bash
# SVG (default)
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.bargen.pro/v1/barcode/qrcode?data=https://example.com&scale=4"

# PNG (Pro and up)
curl -H "X-API-Key: YOUR_KEY" -o barcode.png \
  "https://api.bargen.pro/v1/barcode/ean13?data=5901234123457&format=png"

# PDF (Business and up)
curl -H "X-API-Key: YOUR_KEY" -o barcode.pdf \
  "https://api.bargen.pro/v1/barcode/code128?data=ABC-123&format=pdf"
```

## Supported barcode types

25 types, grouped by the minimum plan that unlocks them.

| Plan | Types (slug) |
|------|--------------|
| **Free** | `qrcode`, `code128`, `code39`, `ean13`, `ean8`, `upca`, `upce`, `itf12`, `itf14`, `itf16`, `gls-ecsomag`, `codabar`, `datamatrix`, `pdf417`, `aztec` |
| **Pro** (adds) | `gs1-128`, `gs1-datamatrix`, `microqr` |
| **Business** (adds) | `imb`, `rms4cc`, `kix`, `postnet`, `planet`, `maxicode`, `dotcode` |

Enterprise unlocks all 25 types with no volume cap. Call `GET /v1/formats` to discover the current list and required plan programmatically.

## Output formats by plan

- **SVG** — all plans (including Free)
- **PNG** — Pro and above
- **PDF, EPS** — Business and above

## List formats

```
GET /v1/formats
```

Public. Returns every barcode type with its name, category, description, the lowest plan that unlocks it, and its status.

## Validate your key

```
GET /v1/validate
```

Returns:

```json
{
  "valid": true,
  "name": "My API key",
  "requests": 1234,
  "created_at": "2026-06-01T10:00:00Z",
  "last_used_at": "2026-06-29T08:15:00Z"
}
```

## Batch generation

```
POST /v1/barcode/batch
Content-Type: application/json
X-API-Key: YOUR_KEY
```

```json
{
  "codes": [
    { "type": "qrcode", "data": "https://example.com" },
    { "type": "ean13",  "data": "5901234123457" }
  ],
  "options": { "scale": 3 }
}
```

Maximum **50** codes per request. Optional top-level `options` apply to every code. Response:

```json
{
  "results": [
    { "index": 0, "success": true,  "svg": "BASE64_ENCODED_SVG" },
    { "index": 1, "success": false, "error": "..." }
  ],
  "total": 2,
  "successful": 1
}
```

Each successful item's `svg` field is **base64-encoded** — decode it client-side. Batch output is always SVG.

## Plans and limits

| Plan | Price | Monthly requests | Formats | Types |
|------|-------|------------------|---------|-------|
| Free | $0 | 1,000 | SVG | 15 |
| Pro | $9.99/mo | 10,000 | SVG, PNG | 18 |
| Business | $29/mo | 100,000 | SVG, PNG, PDF, EPS | 25 (incl. postal) |
| Enterprise | custom | unlimited | all | 25 |

When you reach your monthly limit the API returns `402` until the next billing period or until you upgrade.

## Error responses

Errors are returned as JSON: `{ "error": "message" }`.

| Status | Meaning |
|--------|---------|
| `400` | Invalid barcode type, parameters, or missing `data` |
| `401` | Missing or invalid API key |
| `402` | Monthly request limit reached — upgrade your plan |
| `403` | Your plan does not include this barcode type or output format |
| `404` | Unknown endpoint |
| `500` | Server error |