QR Agent Core

QR-as-a-Service API built for AI agents. Create, update, and track dynamic QR codes programmatically via REST API or MCP (37 tools).

QR codes point to short URLs (/r/:shortId) that you can retarget at any time — the QR image never changes, but scanning it goes to the new destination. Multi-tenant by design, with full scan analytics.

Live API: api.qragentcore.com  |  Site: qrforagent.com  |  MCP: qr-for-agent

Features

• Dynamic QR codes — change the destination URL without regenerating the image
• 11 QR types — URL, vCard, WiFi, Email, SMS, Phone, Event, Text, Location, Social, App Store
• Custom styling — dot shapes (square, rounded, dots, classy-rounded), corner styles, colors, gradients, logo embedding, frames with CTA text
• SVG & PNG — vector and bitmap output
• Enriched analytics — device type, browser, OS, country, city, referrer, scans-by-day
• Real-time webhooks — HMAC-SHA256 signed payloads with delivery logging
• UTM tracking — auto-append UTM parameters to redirect URLs
• GTM support — intermediate page with Google Tag Manager snippets
• Conditional redirects — route by device, OS, country, language, time range, or A/B split
• Custom domains — Pro users brand short URLs with their own domain (qr.yourbrand.com/r/abc123)
• Expiration & scheduling — auto-expire QR codes or schedule URL swaps
• Conversion tracking — tracking pixel + API for post-scan events (purchases, signups) with ROI analytics
• Frames & templates — decorative frames around QR codes (banner_top, banner_bottom, rounded) with CTA text
• Bulk operations — create, update, or delete up to 50 QR codes per request, or up to 500 via CSV upload (Pro)
• Multi-tenant — each API key sees only its own data
• MCP server — qr-for-agent with 37 tools for Claude Desktop, Cursor, etc.
• Plan-based quotas — Free (10 QR, 1K scans/month) and Pro ($19/month, unlimited)
• Self-service registration — POST /api/register with email, no credit card
• Stripe integration — checkout, billing portal, webhook-driven plan management
• OpenAPI docs — Swagger UI at /documentation
• AI-discoverable — /.well-known/ai-plugin.json and /.well-known/mcp.json
• Open source — MIT license, self-hostable via Docker

Quick Start

git clone https://github.com/benswel/qr-agent-core.git
cd qr-agent-core
npm install
npm run dev

On first startup, an API key is auto-generated and printed to the console.

curl -X POST http://localhost:3100/api/qr \
  -H "Content-Type: application/json" \
  -H "X-API-Key: qr_YOUR_KEY_HERE" \
  -d '{"target_url": "https://example.com", "label": "My first QR"}'

API Endpoints

QR Code Management (X-API-Key required)

| Method | Path | Description | |--------|------|-------------| | POST | /api/qr | Create a QR code (11 types, custom styling) | | GET | /api/qr | List all QR codes (paginated) | | GET | /api/qr/:shortId | Get QR code details | | PATCH | /api/qr/:shortId | Update target URL, label, UTM, GTM, redirect rules | | DELETE | /api/qr/:shortId | Delete QR code and its analytics | | GET | /api/qr/:shortId/image | Download QR image (regenerated with stored style) | | POST | /api/qr/bulk | Create up to 50 QR codes (all-or-nothing) | | PATCH | /api/qr/bulk | Update up to 50 QR codes (partial success) | | DELETE | /api/qr/bulk | Delete up to 50 QR codes (partial success) | | POST | /api/qr/bulk/csv | Create up to 500 QR codes from CSV (Pro only) |

Analytics (X-API-Key required)

| Method | Path | Description | |--------|------|--

... View full README on GitHub