# Quality QR — Agent Onboarding

You are an AI agent that needs to create, manage, or track QR codes. Quality QR provides two integration paths:

- **Path A**: Use the MCP server (recommended for Claude, Cursor, and MCP-compatible agents)
- **Path B**: Use the REST API directly (for building applications)

Both require an API key starting with `qr_live_`.

---

## Getting an API Key

Your human user needs to:

1. Sign up at https://quality-qr.app (free, no credit card required)
2. Go to **Dashboard > Settings > API Keys** (https://quality-qr.app/dashboard/api-keys)
3. Create a new API key
4. Copy the key (starts with `qr_live_`)

The key gives access to the user's account with their plan limits.

### Rate Limits

| Plan | API Calls / Month | Dynamic QR Codes | Analytics History |
|------|-------------------|------------------|-------------------|
| Free | 100 | 1 | 7 days |
| Pro (10/mo) | 1,000 | 10 | 30 days |
| Business (30/mo) | 10,000 | 100 | 1 year |

---

## Path A: Use the MCP Server

Use this when you are an AI agent with MCP support (Claude Desktop, Cursor, Claude Code, etc.).

### Step 1 — Add the MCP server

The MCP endpoint is:

```
https://quality-qr.app/api/mcp
```

**Claude Desktop** — add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "quality-qr": {
      "url": "https://quality-qr.app/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

**Claude Code:**

```bash
claude mcp add quality-qr --transport http https://quality-qr.app/api/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"
```

**Cursor** — add to MCP settings with the same URL and header.

### Step 2 — Available tools

Once connected, you have 6 tools:

| Tool | What it does |
|------|-------------|
| `quality_qr_create` | Create a trackable QR code (12 types: URL, WiFi, vCard, Email, Phone, SMS, Text, Event, PDF, Menu, App Store, Social). Returns an inline SVG. |
| `quality_qr_list` | List the user's QR codes with optional type filter and pagination. |
| `quality_qr_get` | Get full details of a specific QR code by ID. |
| `quality_qr_update` | Change destination URL, rename, or enable/disable a QR code. |
| `quality_qr_delete` | Permanently delete a QR code (frees plan quota). |
| `quality_qr_analytics` | Get scan analytics: totals, daily trends, device breakdown, top countries. |

### Step 3 — Example usage

Ask the agent to:
- "Create a QR code for https://example.com"
- "Make a WiFi QR code for network MyWiFi with password guest123"
- "Show me analytics for my QR codes"
- "List all my QR codes"
- "Disable QR code abc123"

---

## Path B: Use the REST API

Use this when you're a coding agent building an application that calls the Quality QR API.

### Base URL

```
https://quality-qr.app/api/v1
```

### Authentication

Include your API key as a Bearer token:

```
Authorization: Bearer qr_live_YOUR_KEY
```

### Create a QR code

```bash
curl -X POST https://quality-qr.app/api/v1/qr \
  -H "Authorization: Bearer qr_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "url",
    "content": "https://example.com",
    "name": "My Website",
    "isDynamic": true
  }'
```

Response:

```json
{
  "success": true,
  "type": "url",
  "dataUrl": "data:image/png;base64,...",
  "qrCode": {
    "id": "abc123",
    "name": "My Website",
    "shortCode": "xY7kL9mN",
    "shortUrl": "https://quality-qr.app/q/xY7kL9mN"
  }
}
```

### List QR codes

```bash
curl https://quality-qr.app/api/v1/qr \
  -H "Authorization: Bearer qr_live_YOUR_KEY"
```

### Supported QR types

| Type | Required fields | Description |
|------|----------------|-------------|
| `url` | `content` (URL) | Link to any website |
| `wifi` | `data.ssid`, optional `data.password`, `data.encryption` | WiFi network credentials |
| `vcard` | `data.firstName`, `data.lastName` | Digital business card |
| `email` | `data.to`, optional `data.subject`, `data.body` | Pre-filled email |
| `phone` | `data.number` | Tap-to-call |
| `sms` | `data.number`, optional `data.message` | Pre-filled text message |
| `text` | `content` | Plain text |
| `event` | `data.title`, `data.startDate` | Calendar event |
| `pdf` | `content` (URL to PDF) | Document link |
| `menu` | `content` (URL to menu) | Restaurant menu |
| `app-store` | `content` (store URL) | App download link |
| `social` | `data.platforms` array | Social media profile links |

### Design options

Pass `design` object to customize colors:

```json
{
  "type": "url",
  "content": "https://example.com",
  "design": {
    "foregroundColor": "#1a56db",
    "backgroundColor": "#ffffff"
  }
}
```

### Dynamic vs Static

Set `"isDynamic": true` to create codes whose destination URL can be changed later without reprinting. Dynamic codes also get scan tracking. Only URL-based types (url, pdf, menu, app-store, social) support dynamic mode.

### Error handling

| Status | Meaning |
|--------|---------|
| 200 | Success |
| 400 | Bad request (invalid type, missing fields) |
| 401 | Missing or invalid API key |
| 403 | Plan limit reached or insufficient permissions |
| 429 | Rate limit exceeded |

---

## Full Documentation

- MCP setup guide: https://quality-qr.app/docs/mcp
- REST API reference: https://quality-qr.app/docs/api
- QR code types: https://quality-qr.app/docs/qr-types
- Pricing and limits: https://quality-qr.app/pricing