benswel/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.qrforagent.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
On first startup, an API key is auto-generated and printed to the console.
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 |
|--------|------|-------------|
| GET | /api/analytics/:shortId | Scan stats with device, browser, OS, country, city breakdowns + conversions |
Conversions (X-API-Key required)
| Method | Path | Description |
|--------|------|-------------|
| POST | /api/conversions | Record a conversion event for a QR code you own |
| GET | /api/conversions/:shortId | Get conversion stats (totals, by_event, by_day, recent) |
Webhooks (X-API-Key required)
| Method | Path | Description |