Developer API v1.0

Build with the Power of QR

Integrate dynamic QR code generation, management, and analytics directly into your applications.

Introduction#

The CraftUrQR API is built on REST principles. We encourage the use of standard HTTP verbs and response codes. All responses are in JSON format.

Base URL:https://crafturqr.com/api/v1

Authentication#

Authenticate your API requests using your API Key.

You must include the x-api-key header in all requests.

curl -H "x-api-key: YOUR_API_KEY" https://crafturqr.com/api/v1/qr-codes

QR Codes#

Manage your QR codes directly via API.

List QR Codes

GET/qr-codes

Retrieve a paginated list of your QR codes.

Query Parameters

Name	Type	Required	Description
limit	integer	Optional	Number of results to return (default 10)
offset	integer	Optional	Number of results to skip (default 0)
search	string	Optional	Search by title

Response Example

JSON

{
  "data": [
    {
      "id": "uuid-string",
      "title": "My Website QR",
      "target_url": "https://example.com"
    }
  ],
  "count": 1,
  "limit": 10,
  "offset": 0
}

Create QR Code

POST/qr-codes

Create a new dynamic QR code.

Request Body

{
  "title": "Marketing Campaign",
  "target_url": "https://example.com/promo",
  "is_direct": false,
  "customization": {
    "dotsOptions": {
      "color": "#4F46E5",
      "type": "rounded"
    },
    "backgroundOptions": {
      "color": "#ffffff"
    },
    "cornersSquareOptions": {
      "color": "#4F46E5",
      "type": "extra-rounded"
    },
    "cornersDotOptions": {
      "color": "#4F46E5",
      "type": "dot"
    },
    "image": "https://example.com/logo.png",
    "imageOptions": {
      "hideBackgroundDots": true,
      "imageSize": 0.4,
      "margin": 10
    }
  }
}

Response Example

JSON

{
  "data": {
    "id": "new-uuid",
    "title": "Marketing Campaign",
    "short_id": "abc123"
  }
}

Get QR Code

GET/qr-codes/:id

Retrieve details of a specific QR code.

Query Parameters

Name	Type	Required	Description
id	string	Required	The UUID of the QR code

Response Example

JSON

{
  "data": {
    "id": "uuid-string",
    "title": "My QR",
    "target_url": "https://example.com",
    "clicks": 150
  }
}

Update QR Code

PUT/qr-codes/:id

Update the target URL or customization of a QR code. Note: Target URL cannot be changed for Static (Direct) QR codes.

Query Parameters

Name	Type	Required	Description
id	string	Required	The UUID of the QR code

Request Body

{
  "target_url": "https://new-url.com",
  "title": "Updated Title",
  "customization": {
    "dotsOptions": {
      "color": "#000000",
      "type": "dots"
    },
    "backgroundOptions": {
      "color": "#ffffff"
    }
  }
}

Response Example

JSON

{
  "data": {
    "id": "uuid-string",
    "target_url": "https://new-url.com"
  }
}

Delete QR Code

DELETE/qr-codes/:id

Permanently delete a QR code.

Query Parameters

Name	Type	Required	Description
id	string	Required	The UUID of the QR code

Response Example

JSON

{
  "success": true
}

Invoices#

Access your billing history and invoices.

List Invoices

GET/invoices

Retrieve a list of your past invoices.

Query Parameters

Name	Type	Required	Description
limit	integer	Optional	Limit results
offset	integer	Optional	Skip results

Response Example

JSON

{
  "data": [
    {
      "id": "inv_123",
      "amount": 2900,
      "status": "paid",
      "created_at": "2024-01-01T12:00:00Z",
      "download_url": "https://.../download"
    }
  ]
}

Download Invoice

GET/invoices/:id/download

Download an invoice as a PDF file.

Query Parameters

Name	Type	Required	Description
id	string	Required	Invoice ID

Response Example

JSON

{
  "message": "Binary PDF data stream"
}

Subscription#

Check your current plan limits and usage.

Get Subscription Details

GET/subscription

Retrieve current plan details and usage metrics.

Response Example

JSON

{
  "plan": {
    "name": "Pro",
    "status": "active",
    "renews_at": "2024-02-01T00:00:00Z",
    "limits": {
      "qr_limit": 50
    }
  },
  "usage": {
    "qr_codes": 12,
    "scans_this_month": 450
  }
}

Static QR Codes#

Understanding Direct (Static) vs Dynamic QR Codes.

Static (Direct) QR Codes

Static QR codes encode the target URL directly into the QR pattern. Unlike dynamic QRs, they do not redirect through our servers.

Important Restraints

✕Immutable Target: Once created, you cannot change the target URL. The URL is permanently baked into the QR pattern.
✕Permanent Type: You cannot convert a Static QR code to a Dynamic one after creation.
✓Editable Design: You can still update the customization (colors, shapes, logo) at any time.

Analytics#

Get detailed scan analytics for your QR codes.

Get Analytics

GET/analytics

Retrieve aggregated analytics data.

Query Parameters

Name	Type	Required	Description
qr_id	string	Optional	Filter by specific QR code
days	integer	Optional	Number of days (default 30)

Response Example

JSON

{
  "period": "30 days",
  "data": {
    "total_scans": 1540,
    "by_date": {
      "2024-01-01": 50,
      "2024-01-02": 65
    },
    "by_country": {
      "US": 800,
      "DE": 200
    },
    "by_device": {
      "Mobile": 1200,
      "Desktop": 340
    }
  }
}