API Documentation

Integrate Qurrl.ink’s URL shortening and QR code generation into your applications.

🚀 Quick Start

Get started with the Qurrl API in minutes. Generate an API key from your Dashboard, then make your first request:

curl -X POST https://qurrl.ink/wp-json/qurrl/v1/link/shorten \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/my-long-url"}'
https://qurrl.ink/wp-json/qurrl/v1

📑 Contents

🔐 Authentication

All API requests require authentication using an API key. Include your key in the X-API-Key header with every request.

🔑 API Key Header

Include this header in all requests:

X-API-Key: your_api_key_here

You can generate API keys from the API tab in your Dashboard. Keep your API keys secure and never expose them in client-side code.

⏱️ Rate Limiting

Free accounts: 100 requests per hour
Premium accounts: 1,000 requests per hour

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

POST /link/shorten Create a shortened URL

Creates a new short link that redirects to your target URL. Optionally specify a custom alias.

Request Parameters

ParameterDescription
urlstringrequired The destination URL to shorten. Must be a valid URL starting with http:// or https://
aliasstringoptional Custom short code (3-20 characters, alphanumeric and hyphens only). If not provided, a random code is generated.
titlestringoptional A descriptive title for the link (for your reference in the dashboard)

Example Request

cURL 
curl -X POST https://qurrl.ink/wp-json/qurrl/v1/link/shorten \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/very-long-url-path",
    "alias": "my-link",
    "title": "My Campaign Link"
  }'

Example Response

JSON Response 
{
  "success": true,
  "data": {
    "short_url": "https://qurrl.ink/my-link",
    "short_code": "my-link",
    "original_url": "https://example.com/very-long-url-path",
    "created_at": "2025-12-21T09:30:00Z"
  }
}
POST /link/dynamic Create an editable QR code link

Creates a dynamic short link specifically designed for QR codes. The destination can be changed later without reprinting the QR code.

Request Parameters

ParameterDescription
urlstringrequired The initial destination URL
namestringoptional A name/label for this dynamic QR (e.g., “Restaurant Menu QR”)

Example Request

cURL 
curl -X POST https://qurrl.ink/wp-json/qurrl/v1/link/dynamic \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://myrestaurant.com/menu",
    "name": "Table QR Menu"
  }'

Example Response

JSON Response 
{
  "success": true,
  "data": {
    "short_url": "https://qurrl.ink/d/abc123",
    "short_code": "abc123",
    "original_url": "https://myrestaurant.com/menu",
    "name": "Table QR Menu",
    "is_dynamic": true,
    "created_at": "2025-12-21T09:30:00Z"
  }
}

Generate QR Code

POST /qr/generate Generate a customized QR code image

Generates a QR code image with extensive customization options including colors, gradients, dot styles, and logo embedding.

Request Parameters

ParameterDescription
datastringrequired The content to encode (URL, text, vCard, WiFi config, etc.)
sizeintegeroptional Image size in pixels (100-2000). Default: 300
formatstringoptional Output format: png, svg, base64. Default: png
fg_colorstringoptional Foreground/dots color (hex). Default: #000000
bg_colorstringoptional Background color (hex). Default: #FFFFFF
gradientobjectoptional Gradient configuration: {"type": "linear"|"radial", "color_start": "#hex", "color_end": "#hex"}
dot_stylestringoptional Dot pattern: square, dots, rounded, classy, classy-rounded, extra-rounded
corner_stylestringoptional Corner square style: square, dot, extra-rounded
logo_urlstringoptional URL of logo image to embed in center
logo_sizefloatoptional Logo size as ratio of QR (0.1-0.4). Default: 0.25

Example Request

cURL 
curl -X POST https://qurrl.ink/wp-json/qurrl/v1/qr/generate \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "data": "https://qurrl.ink",
    "size": 500,
    "format": "png",
    "fg_color": "#0078A1",
    "bg_color": "#FFFFFF",
    "dot_style": "rounded",
    "corner_style": "extra-rounded",
    "gradient": {
      "type": "linear",
      "color_start": "#0078A1",
      "color_end": "#00A86B"
    }
  }'

Example Response

JSON Response 
{
  "success": true,
  "data": {
    "qr_url": "https://qurrl.ink/qr-images/abc123.png",
    "format": "png",
    "size": 500,
    "expires_at": "2025-12-28T09:30:00Z"
  }
}

Note: Generated QR images are temporarily hosted and expire after 7 days. Download and store them permanently if needed.

Bulk Generate QR Codes

POST /qr/bulk Generate multiple QR codes at once

Generate up to 500 QR codes in a single request. Returns a ZIP file containing all generated QR codes.

Request Parameters

ParameterDescription
itemsarrayrequired Array of objects, each containing data (content) and optional filename
sizeintegeroptional Size for all QR codes (100-2000). Default: 300
formatstringoptional Output format: png, svg. Default: png
styleobjectoptional Shared style options (fg_color, bg_color, dot_style, etc.) applied to all QRs

Example Request

cURL 
curl -X POST https://qurrl.ink/wp-json/qurrl/v1/qr/bulk \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"data": "https://example.com/product-1", "filename": "product-1"},
      {"data": "https://example.com/product-2", "filename": "product-2"},
      {"data": "https://example.com/product-3", "filename": "product-3"}
    ],
    "size": 400,
    "format": "png",
    "style": {
      "fg_color": "#333333",
      "dot_style": "rounded"
    }
  }'

Example Response

JSON Response 
{
  "success": true,
  "data": {
    "download_url": "https://qurrl.ink/bulk-downloads/xyz789.zip",
    "count": 3,
    "expires_at": "2025-12-22T09:30:00Z"
  }
}

Error Handling

The API uses standard HTTP response codes to indicate success or failure.

200 Success – Request completed successfully
400 Bad Request – Invalid parameters or missing required fields
401 Unauthorized – Invalid or missing API key
403 Forbidden – API key lacks permission for this action
409 Conflict – Resource already exists (e.g., alias taken)
429 Too Many Requests – Rate limit exceeded
500 Server Error – Something went wrong on our end

Error Response Format

Error Response 
{
  "success": false,
  "error": {
    "code": "INVALID_URL",
    "message": "The provided URL is not valid",
    "details": "URL must start with http:// or https://"
  }
}

Common Error Codes

CodeDescription
INVALID_API_KEYThe API key is invalid or has been revoked
MISSING_API_KEYNo API key was provided in the request
INVALID_URLThe URL parameter is not a valid URL
ALIAS_TAKENThe requested custom alias is already in use
RATE_LIMIT_EXCEEDEDYou’ve exceeded your rate limit
INVALID_FORMATUnsupported output format requested
SIZE_OUT_OF_RANGEQR size must be between 100-2000 pixels
BULK_LIMIT_EXCEEDEDBulk request exceeds maximum 500 items

SDKs & Libraries

Official and community SDKs to integrate Qurrl in your favorite language:

🟨
JavaScript / Node.js
Coming Soon
🐍
Python
Coming Soon
💎
Ruby
Coming Soon
🐘
PHP
Coming Soon

Need help? Contact us at support@qurrl.ink or check our Help Center.