# 📘 QR Code API - Service Documentation

**Service:** QR Code Generation  
**Base URL:** `https://a.strt.it/qr`  
**Type:** Lightweight, fast, no dependencies

---

## Endpoints

### **POST /qr/code** - Generate QR (JSON)

**Request:**
```json
{
  "data": "string (required, max 2048 chars)",
  "size": "number (optional, 64-2048, default: 256)",
  "colors": {
    "fg": "string (hex, default: #000000)",
    "bg": "string (hex, default: #FFFFFF)"
  }
}
```

**Response:**
```json
{
  "qr": "data:image/png;base64,..."
}
```

**Use when:** You need base64 data URL for processing or storage

---

### **GET /qr/code/image** - Generate QR (PNG)

**Parameters:**
- `data` (required) - Data to encode
- `size` (optional) - Size in pixels (64-2048)
- `fg` (optional) - Foreground color (hex)
- `bg` (optional) - Background color (hex)

**Response:** PNG image

**Use when:** Direct embedding in HTML/markdown or download

---

## Auto-Detection

No need to specify type! Automatically detects:
- `https://...` → URL
- `BEGIN:VCARD` → Contact card
- `WIFI:T:...` → WiFi credentials
- `mailto:...` → Email
- `tel:...` → Phone
- `sms:...` → SMS
- Everything else → Plain text

---

## Examples

### **Simple URL**
```bash
curl -X POST https://a.strt.it/qr/code \
  -H "Content-Type: application/json" \
  -d '{"data": "https://nakamapi.com"}'
```

### **Custom Colors**
```bash
curl -X POST https://a.strt.it/qr/code \
  -H "Content-Type: application/json" \
  -d '{"data": "test", "colors": {"fg": "#2563eb", "bg": "#f8fafc"}}'
```

### **Direct PNG**
```
https://a.strt.it/qr/code/image?data=Hello%20World&size=512
```

---

## For AI Agents

**When user says:** "Create a QR code for [X]"

**You should:**
1. Extract data from conversation
2. Use POST if you need to process the result
3. Use GET if you just need to display it
4. Return the QR code to user

**Python Example:**
```python
import requests

def generate_qr(data: str):
    response = requests.post(
        'https://a.strt.it/qr/code',
        json={'data': data}
    )
    return response.json()['qr']
```

---

## Error Handling

| Error | Cause | Fix |
|-------|-------|-----|
| "Data is required" | Missing data field | Add `"data": "..."` |
| "Data exceeds maximum" | Data > 2048 chars | Shorten or use URL shortener |
| "Invalid color format" | Wrong hex format | Use `#RRGGBB` format |
| "Size must be between..." | Invalid size | Use 64-2048 range |

---

## Rate Limits

**Free tier:** 100 requests/hour per IP  
**No authentication required**

---

**Service Documentation:** Technical details only  
**Back to Master Guide:** [AI-GUIDE.md](../AI-GUIDE.md)