API Documentation

Getting Started

Generate your first barcode in three steps:

1. Create an account at the Barcoding dashboard to get your API key.
2. Make a request to the generation endpoint with your barcode data.
3. Receive your barcode as a PNG or SVG image in the response.

Your API key is available immediately after signup. The free tier includes 500 generations per month with no credit card required.

Quick Example

The response is the barcode image with the appropriate Content-Type header (image/png or image/svg+xml).

Authentication

All API requests require an API key passed in the Authorization header using the Bearer scheme.

Authorization: Bearer YOUR_API_KEY

API keys can be created and managed from the dashboard. Each account supports multiple API keys with custom labels. Keys can be revoked at any time.

Key format: API keys are prefixed with brc_. The full key is shown once at creation — store it securely.

Requests without a valid API key receive a 401 Unauthorized response:

{
  "code": "unauthorized",
  "error": "a valid API key is required in the Authorization header"
}

Generate a Barcode

Send a JSON payload with the barcode type and data. The response is the barcode image.

Request Body

Example Request

Response

On success, the response body is the barcode image with the corresponding Content-Type header:

• PNG: Content-Type: image/png
• SVG: Content-Type: image/svg+xml

To receive a JSON response with a base64-encoded image instead, set the Accept header to application/json:

{
  "image": "iVBORw0KGgo...",
  "format": "png",
  "type": "ean13",
  "data": "4006381333931",
  "width_px": 264,
  "height_px": 180
}

Validate Data

Check whether input data is valid for a given barcode type without generating an image. Useful for pre-validating user input.

Request Body

Example

Response

{
  "valid": true,
  "type": "ean13",
  "data": "4006381333931",
  "check_digit": "1"
}

If the data is invalid:

{
  "valid": false,
  "type": "ean13",
  "data": "12345",
  "code": "invalid_data_length",
  "error": "data length is invalid for the requested barcode type"
}

Barcode Types

Code 128

A high-density 1D barcode supporting the full ASCII character set. Commonly used for shipping labels, logistics, and general-purpose labeling.

• Valid data: ASCII characters (0-127)
• Length: 1 to 80 characters (recommended maximum)
• Check digit: Automatically calculated

The encoder selects the optimal character set (A, B, or C) to minimize barcode width. Character set C is used for runs of digits.

EAN-13

The international standard for retail product identification. Used worldwide on consumer products.

• Valid data: 12 or 13 digits
• With 12 digits: The check digit is calculated automatically
• With 13 digits: The check digit is verified against the input

Leading zeros are significant (e.g., country code 001 is different from 01).

UPC-A

The North American standard for retail product identification. A subset of EAN-13.

• Valid data: 11 or 12 digits
• With 11 digits: The check digit is calculated automatically
• With 12 digits: The check digit is verified against the input

QR Code

A 2D barcode capable of encoding text, URLs, and binary data. Used for marketing, payments, authentication, and general-purpose linking.

• Valid data: Up to 2,953 bytes (depending on error correction level)
• Error correction levels:

The encoder automatically selects the optimal QR version (size) based on the data length and error correction level.

Configuration Options

Output Format

Colors

Foreground (fg_color) and background (bg_color) accept 6-digit hex values with a # prefix:

{
  "fg_color": "#1a1a1a",
  "bg_color": "#ffffff"
}

Ensure sufficient contrast between foreground and background for reliable scanning.

Rate Limiting

Each plan has a per-minute request limit:

Every API response includes rate limit headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1707782400

When the limit is exceeded, the API returns 429 Too Many Requests:

{
  "code": "rate_limited",
  "error": "rate limit exceeded, try again later"
}

Error Handling

All errors return a consistent JSON structure with an HTTP status code, a machine-readable error code, and a human-readable message.

Error Response Format

{
  "code": "invalid_check_digit",
  "error": "the check digit is incorrect for the provided data"
}

Error Codes

Examples

curl

Python

JavaScript

Go