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

squaredotsroundedextra-roundedclassyclassy-rounded

Corner Styles

squaredotextra-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
`short_link_domain`	TEXT	-	Domain for the short link (e.g. uqr.sh). Defaults to system default if not specified
`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_link_domain`	TEXT	Domain used for the short link (e.g. uqr.sh)
`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

1Website/URL1 required

2Text1 required

3Email1 required

4vCard0 required

5WiFi1 required

6Phone1 required

12SMS1 required

13Location2 required

14PDF3 required

15Image Gallery2 required

17Image2 required

19File2 required

20List of Links2 required

21MP32 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