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
`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.qragentcore.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

Name		Name	Last commit message	Last commit date
Latest commit History 52 Commits
drizzle/migrations		drizzle/migrations
packages/mcp		packages/mcp
src		src
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.mcp.json.example		.mcp.json.example
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
drizzle.config.ts		drizzle.config.ts
glama.json		glama.json
package-lock.json		package-lock.json
package.json		package.json
railway.toml		railway.toml
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

QR Agent Core

Features

Quick Start

API Endpoints

QR Code Management (`X-API-Key` required)

Analytics (`X-API-Key` required)

Conversions (`X-API-Key` required)

Webhooks (`X-API-Key` required)

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

Account (`X-API-Key` required)

Public (no auth)

Admin (`X-Admin-Secret` header required)

Authentication

MCP Server

Claude Desktop / Cursor

Available Tools (37)

Configuration

Database

Deployment

Docker

Railway

Tests

Scripts

License

About

Uh oh!

Releases 1

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

QR Agent Core

Features

Quick Start

API Endpoints

QR Code Management (X-API-Key required)

Analytics (X-API-Key required)

Conversions (X-API-Key required)

Webhooks (X-API-Key required)

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

Account (X-API-Key required)

Public (no auth)

Admin (X-Admin-Secret header required)

Authentication

MCP Server

Claude Desktop / Cursor

Available Tools (37)

Configuration

Database

Deployment

Docker

Railway

Tests

Scripts

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

QR Code Management (`X-API-Key` required)

Analytics (`X-API-Key` required)

Conversions (`X-API-Key` required)

Webhooks (`X-API-Key` required)

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

Account (`X-API-Key` required)

Admin (`X-Admin-Secret` header required)

Packages