API Reference

Quickstart

No API key required for development. Send a JSON POST to /api/generate with a payload field:

curl -sS -X POST http://127.0.0.1:5055/api/generate \
  -H "Content-Type: application/json" \
  -d '{"payload": "HELLO PDF417"}' \
  | python3 -m json.tool

Decode the base64 PNG and save to disk:

curl -sS -X POST http://127.0.0.1:5055/api/generate \
  -H "Content-Type: application/json" \
  -d '{"payload": "HELLO PDF417"}' \
  | python3 -c "
import sys, json, base64
data = json.load(sys.stdin)
open('barcode.png', 'wb').write(base64.b64decode(data['pngBase64']))
print('Saved barcode.png')
"

Endpoint

Accepts Content-Type: application/json. Returns application/json. Maximum request body: 512 KB.

Request schema

All fields except payload are optional and fall back to the listed defaults.

Full request example

{
  "payload": "SHIPMENT-001\nDEST: WAREHOUSE-B\nSKU: 4921-AX",
  "columns": 6,
  "errorCorrection": 2,
  "moduleWidth": 3,
  "rowHeight": 9,
  "padding": 20,
  "foreground": "#000000",
  "background": "transparent"
}

Response schema

Successful responses return HTTP 200 with the following JSON body:

{
  "pngBase64": "iVBORw0KGgoAAAANSUhEUg...",
  "info": {
    "standard": "PDF417 (ISO/IEC 15438)",
    "columns": 6,
    "rows": 3,
    "moduleWidth": 3,
    "rowHeight": 9,
    "errorCorrectionLevel": 2,
    "errorCorrectionCodewords": 8,
    "padding": 20,
    "moduleSize": { "width": 171, "height": 3 },
    "imageSize": { "width": 553, "height": 67 },
    "bytes": 618,
    "mode": "RGBA"
  }
}

Response headers

Error codes

Error response body

// HTTP 400
{ "error": "Payload is required." }

// HTTP 429
{
  "error": "Rate limit exceeded.",
  "limit": 60,
  "windowSeconds": 60,
  "retryAfterSeconds": 14
}

Rate limits

The API applies a sliding-window rate limit keyed by client IP address. When the limit is exceeded the server responds with HTTP 429 and a Retry-After header.

API plan customers will have higher limits enforced via API key in a future release.

Code examples

cURL

# Basic generation — save PNG to disk
curl -sS -X POST http://127.0.0.1:5055/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "payload": "ORDER-9821\nSKU: XR-440\nQTY: 12",
    "columns": 6,
    "errorCorrection": 2,
    "moduleWidth": 3,
    "rowHeight": 9,
    "padding": 20
  }' | python3 -c "
import sys, json, base64
d = json.load(sys.stdin)
open('barcode.png','wb').write(base64.b64decode(d['pngBase64']))
print('rows:', d['info']['rows'], '| size:', d['info']['imageSize']['width'], 'x', d['info']['imageSize']['height'])
"

# Transparent background (RGBA PNG)
curl -sS -X POST http://127.0.0.1:5055/api/generate \
  -H "Content-Type: application/json" \
  -d '{"payload": "TICKET-EVENT-2026", "background": "transparent"}' \
  | python3 -c "
import sys, json, base64
open('ticket.png','wb').write(base64.b64decode(json.load(sys.stdin)['pngBase64']))
print('Saved ticket.png')
"

Python

import requests, base64
from pathlib import Path

API_URL = "http://127.0.0.1:5055/api/generate"

def generate_barcode(payload, *, output="barcode.png", **kwargs):
    """Generate a PDF417 barcode PNG and save it to disk."""
    resp = requests.post(
        API_URL,
        json={"payload": payload, **kwargs},
        timeout=15,
    )
    resp.raise_for_status()
    data = resp.json()
    Path(output).write_bytes(base64.b64decode(data["pngBase64"]))
    return data["info"]

# Basic
info = generate_barcode("SHIPMENT-001\nDEST: WAREHOUSE-B", output="shipment.png")
print(f"Generated: {info['imageSize']['width']}x{info['imageSize']['height']}px, {info['rows']} rows")

# Transparent PNG
info = generate_barcode("TICKET-EVENT-2026", background="transparent", output="ticket.png")
print(f"Mode: {info['mode']}")  # RGBA

# Batch from list
for i, item in enumerate(["ORDER-001", "ORDER-002", "ORDER-003"]):
    generate_barcode(item, output=f"barcode_{i:04d}.png")
    print(f"Saved barcode_{i:04d}.png")

JavaScript (fetch)

const API_URL = 'http://127.0.0.1:5055/api/generate';

async function generateBarcode({ payload, columns = 6, errorCorrection = 2,
  moduleWidth = 3, rowHeight = 9, padding = 20, background = '#FFFFFF' }) {
  const resp = await fetch(API_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ payload, columns, errorCorrection,
      moduleWidth, rowHeight, padding, background }),
  });
  if (!resp.ok) {
    const err = await resp.json().catch(() => ({}));
    throw new Error(err.error ?? `HTTP ${resp.status}`);
  }
  return resp.json();
}

// Display in an <img> element
generateBarcode({ payload: 'HELLO PDF417', background: 'transparent' })
  .then(({ pngBase64, info }) => {
    const img = document.getElementById('barcode-preview');
    img.src = `data:image/png;base64,${pngBase64}`;
    console.log(`Generated: ${info.imageSize.width}x${info.imageSize.height}`);
  })
  .catch(console.error);

// Node.js — save to disk
import { writeFileSync } from 'node:fs';
const { pngBase64 } = await generateBarcode({ payload: 'NODE-BATCH-001' });
writeFileSync('barcode.png', Buffer.from(pngBase64, 'base64'));
console.log('Saved barcode.png');

Authentication

The current public API does not require authentication. API key-based auth will be introduced with the paid API plan. When active, pass your key in the Authorization header:

Authorization: Bearer pdf417_live_xxxxxxxxxxxxxxxxxxxx

Development and free-tier usage continues without a key, subject to IP-based rate limits.