qr-agent-core

QR for Agent


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

git clone https://github.com/benswel/qr-for-agent-api.git
cd qr-for-agent-api
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 | |--------|------|-------------| | 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 | |--------|------|-------------| | POST | /api/webhooks | Register webhook endpoint (returns HMAC secret) | | GET | /api/webhooks | List all webhooks | | DELETE | /api/webhooks/:id | Delete a webhook |

Custom Domain (X-API-Key required, Pro only)

| Method | Path | Description | |--------|------|-------------| | GET | /api/domain | Get current custom domain and DNS status | | PUT | /api/domain | Set custom domain | | DELETE | /api/domain | Remove custom domain |

Account (X-API-Key required)

| Method | Path | Description | |--------|------|-------------| | GET | /api/usage | Current usage and quota | | POST | /api/stripe/checkout | Create Stripe Checkout session (upgrade to Pro) | | POST | /api/stripe/portal | Open Stripe billing portal |

Public (no auth)

| Method | Path | Description | |--------|------|-------------| | POST | /api/register | Self-service API key registration (rate-limited) | | GET | /r/:shortId | Redirect to target URL (records scan) | | GET | /t/:shortId | Conversion tracking pixel (returns 1×1 GIF) | | GET | /i/:shortId | Serve QR image (cacheable) | | GET | /health | Health check | | GET | /documentation | Swagger UI | | GET | /.well-known/ai-plugin.json | AI plugin manifest | | GET | /.well-known/mcp.json | MCP discovery manifest |

Admin (X-Admin-Secret header required)

| Method | Path | Description | |--------|------|-------------| | GET | /api/admin/keys | List all registered API keys | | GET | /api/admin/stats | Dashboard metrics |

Authentication

All /api/* endpoints require an X-API-Key header.

• Format: qr_ + 32-character random string
• Auto-generated: on first startup if no keys exist
• Multi-tenant: each key only sees its own QR codes
• Create a key: npm run key:create "my-label"
• List keys: npm run key:list

Public endpoints (/r/, /i/, /health, /documentation, /.well-known/*) don't require auth.

MCP Server

Published as qr-for-agent on npm. 37 tools for AI agents to manage QR codes natively.

npx qr-for-agent

Claude Desktop / Cursor

Add to your MCP config (claude_desktop_config.json or .cursor/mcp.json):

{
  "mcpServers": {
    "qr-for-agent": {
      "command": "npx",
      "args": ["-y", "qr-for-agent"],
      "env": {
        "API_KEY": "your-api-key",
        "BASE_URL": "https://api.qrforagent.com"
      }
    }
  }
}

Available Tools (37)

| Tool | Description | |------|-------------| | create_qr_code | Create a URL QR code with optional custom styling | | get_qr_code | Get QR code details by short ID | | update_qr_destination | Change where a QR code redirects | | list_qr_codes | List all QR codes with pagination | | delete_qr_code | Delete a QR code and its analytics | | get_qr_analytics | Get scan stats and breakdowns | | bulk_create_qr_codes | Create up to 50 QR codes at once | | bulk_update_qr_codes | Update up to 50 QR codes at once | | bulk_delete_qr_codes | Delete up to 50 QR codes at once | | create_vcard_qr | Create a vCard contact QR code | | create_wifi_qr | Create a WiFi credentials QR code | | create_email_qr | Create an email (mailto:) QR code | | create_sms_qr | Create an SMS QR code | | create_phone_qr | Create a phone call QR code | | create_event_qr | Create a calendar event QR code | | create_text_qr | Create a plain text QR code | | create_location_qr | Create a geo-location QR code | | create_social_qr | Create a social media links QR code | | create_app_store_qr | Create a smart app store redirect QR code | | update_vcard_qr | Update a vCard QR code | | update_wifi_qr | Update a WiFi QR code | | update_social_qr | Update a social media QR code | | update_app_store_qr | Update an app store QR code | | create_webhook | Register a webhook endpoint | | list_webhooks | List all registered webhooks | | delete_webhook | Delete a webhook | | register | Register for an API key | | get_usage | Get current usage and quota | | upgrade_to_pro | Create a Stripe Checkout session | | manage_billing | Open Stripe billing portal | | set_utm_params | Set UTM tracking parameters on a QR code | | set_redirect_rules | Set conditional redirect rules on a QR code | | set_custom_domain | Set or remove custom domain (Pro) | | get_custom_domain | Get current custom domain and DNS status | | bulk_create_from_csv | Create up to 500 QR codes from CSV data (Pro) | | record_conversion | Record a post-scan conversion event | | get_conversions | Get conversion stats for a QR code |

Configuration

Copy .env.example to .env and edit:

| Variable | Default | Description | |----------|---------|-------------| | PORT | 3100 | HTTP port | | HOST | 0.0.0.0 | Bind address | | BASE_URL | http://localhost:3100 | Public URL (used in short URLs) | | DATABASE_URL | ./data/qr-agent.db | SQLite file path | | SHORT_ID_LENGTH | 8 | Length of generated short IDs | | ADMIN_SECRET | (none) | Secret for admin endpoints (X-Admin-Secret header) | | STRIPE_SECRET_KEY | (none) | Stripe API secret key | | STRIPE_WEBHOOK_SECRET | (none) | Stripe webhook signing secret | | STRIPE_PRICE_ID | (none) | Stripe Price ID for Pro plan |

Database

SQLite with Drizzle ORM. Six tables:

• api_keys — key storage with label, email, plan (free/pro), Stripe IDs, custom domain
• qr_codes — QR metadata, target URLs, type/type_data, style options, UTM, GTM, redirect rules, expiration/scheduling
• scan_events — scan tracking: timestamp, user-agent, referer, IP, device, browser, OS, country, city
• webhooks — webhook endpoints per API key, HMAC secret, subscribed events
• webhook_deliveries — delivery log: status, response code, error messages
• conversion_events — conversion tracking: event name, value, metadata, referer, IP, timestamp

npm run db:generate   # Generate migration from schema changes
npm run db:migrate    # Apply pending migrations
npm run db:studio     # Open Drizzle Studio (web UI)

Migrations run automatically on server startup.

Deployment

Docker

docker compose up -d

The database is persisted in a Docker volume.

Railway

The project includes railway.toml and a multi-stage Dockerfile. Connect your GitHub repo to Railway — it builds and deploys automatically with health checks on /health.

Tests

195 integration tests covering all endpoints, auth, multi-tenant isolation, QR types, webhooks, bulk operations, custom domains, frames, conversions, CSV upload, and analytics.

npm test           # Run all tests
npm run test:watch # Watch mode

Scripts

| Script | Description | |--------|-------------| | npm run dev | Start dev server with auto-reload | | npm run build | Compile TypeScript | | npm start | Run production server | | npm test | Run test suite | | npm run test:watch | Tests in watch mode | | npm run key:create | Create API key | | npm run key:list | List API keys | | npm run db:generate | Generate migration | | npm run db:migrate | Run migrations | | npm run db:studio | Open Drizzle Studio |

License

MIT