API Documentation

Getting Started

Welcome to the uqr.ai API! Use our REST API to create, manage, and customize dynamic QR codes programmatically.

Create dynamic QR codes with custom designs

Track scans with real-time analytics

Update QR code destinations without reprinting

Customize colors, logos, and styles

Quick Start

Get your API key

Make your first request

Use the API key to authenticate and create your first QR code.

Integrate and scale

Build powerful QR code features into your applications.

Authentication

All API requests require authentication using your API key.

Include your API key in the x-api-key header:

curl -H "x-api-key: YOUR_API_KEY" https://uqr.ai/api/v1/qr-codes

Or use the Authorization header with Bearer token:

curl -H "Authorization: Bearer YOUR_API_KEY" https://uqr.ai/api/v1/qr-codes

Base URL

https://uqr.ai/api/v1

Endpoints

Available API endpoints for managing QR codes

GET

/qr-codesList all QR codes

POST

/qr-codesCreate a new QR code

GET

/qr-codes/:idGet a single QR code

PUT

/qr-codes/:idUpdate a QR code

DELETE

/qr-codes/:idDelete a QR code

Design Options

Customize the appearance of your QR codes

Full Options Schema

{
  "options": {
    "width": 1080,
    "height": 1080,
    "margin": 0,
    "image": "https://example.com/logo.png",
    
    "qrOptions": {
      "errorCorrectionLevel": "Q"  // L, M, Q, H
    },
    
    "dotsOptions": {
      "type": "square",
      "color": "#000000",
      "gradient": null
    },
    
    "backgroundOptions": {
      "color": "#ffffff"
    },
    
    "cornersSquareOptions": {
      "type": "square",
      "color": "#000000"
    },
    
    "cornersDotOptions": {
      "type": "square",
      "color": "#000000"
    },
    
    "imageOptions": {
      "hideBackgroundDots": true,
      "imageSize": 0.4,
      "margin": 0
    },
    
    "frameOptions": {
      "enabled": false,
      "type": "bottom",
      "text": "Scan Me",
      "backgroundColor": "#ffffff",
      "textColor": "#000000",
      "fontSize": 16
    }
  }
}

Design Examples

Professional Blue

{
  "dotsOptions": { "type": "rounded", "color": "#1e40af" },
  "cornersSquareOptions": { "type": "extra-rounded", "color": "#1e3a8a" },
  "backgroundOptions": { "color": "#eff6ff" }
}

Modern Gradient

{
  "dotsOptions": {
    "type": "dots",
    "gradient": {
      "colorStops": [
        { "offset": 0, "color": "#ec4899" },
        { "offset": 1, "color": "#8b5cf6" }
      ]
    }
  },
  "cornersSquareOptions": { "type": "dot", "color": "#8b5cf6" }
}

With Frame

{
  "dotsOptions": { "type": "rounded", "color": "#000000" },
  "frameOptions": {
    "enabled": true,
    "type": "bottom",
    "text": "SCAN ME",
    "backgroundColor": "#f1f5f9",
    "textColor": "#334155",
    "fontSize": 18
  }
}

With Logo

{
  "image": "https://example.com/logo.png",
  "dotsOptions": { "type": "rounded", "color": "#000000" },
  "imageOptions": {
    "hideBackgroundDots": true,
    "imageSize": 0.3,
    "margin": 5
  },
  "qrOptions": { "errorCorrectionLevel": "H" }
}

Dot Styles

square

dots

rounded

extra-rounded

classy

classy-rounded

Corner Styles

square

dot

extra-rounded

Common Fields

Fields available for all QR types

Field	DB Type	Required	Description
`type_id`	BIGINT		QR type identifier (1-21)
`name`	TEXT	-	QR code display name
`options`	JSONB	-	Design options object
`folder`	UUID	-	Folder ID for organization
`template_id`	UUID	-	Design template ID
`theme`	JSONB	-	Theme configuration for landing pages

Premium fields (require subscription)

Fields requiring a premium subscription

Field	DB Type	Description
`short_id`	TEXT	Custom short ID (e.g., "my-brand")
`link_password`	TEXT	Password to protect QR access
`password_enabled`	BOOLEAN	Enable password protection
`expires_at`	TIMESTAMPTZ	Expiration date (ISO 8601)
`expiration_enabled`	BOOLEAN	Enable expiration
`expired_redirect_url`	TEXT	Redirect URL after expiration
`scan_limit`	INTEGER	Maximum scans allowed
`scan_limit_reached_url`	TEXT	Redirect URL after limit reached
`watermark`	N/A	Set to false to remove watermark

Response Fields

Fields returned when creating or fetching QR codes

Field	DB Type	Description
`short_id`	TEXT	Short ID for URL
`short_url`	N/A	Full scannable URL
`image`	TEXT	URL to generated QR code image
`image_status`	N/A	Image processing status
`image_base64`	N/A	Base64 encoded image (initial only)

QR Code Types

Use these type_id values when creating QR codes

Website/URL1 required

Text1 required

Email1 required

vCard0 required

WiFi1 required

Phone1 required

SMS1 required

Location2 required

PDF3 required

Image Gallery2 required

Image2 required

File2 required

List of Links2 required

MP32 required

Error Codes

Possible error responses from the API

401

missing_api_key

No API key provided in the request

401

invalid_api_key

The provided API key is invalid

401

api_key_inactive

The API key has been deactivated

403

premium_required

The requested feature requires a premium subscription

400

validation_error

Invalid request parameters

404

not_found

The requested resource was not found

500

database_error

A database error occurred

500

server_error

An unexpected server error occurred