API Documentation

Integrate Claudeo QR into your applications. Create QR codes, manage short URLs, track analytics, and more programmatically.

Base URL

https://qr.claudeo.ai/api/v1

Authentication

Include your API key in the x-api-key header with every request:

# List all QR codes
curl -H "x-api-key: sk_live_your_api_key_here" \
  https://qr.claudeo.ai/api/v1/qr

# Create a short URL
curl -X POST \
  -H "x-api-key: sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"destinationUrl":"https://example.com","title":"My Link"}' \
  https://qr.claudeo.ai/api/v1/links

All authenticated endpoints also support browser session auth (NextAuth) for dashboard use. API key auth is for programmatic/server-to-server access.

Authentication

All API requests require an API key passed via the x-api-key header. Generate keys from Dashboard → Settings (Business plan required). API keys use SHA-256 hashing — the full key is shown only once at creation.

GET/api/v1/api-keys

List all API keys for your workspace. Returns key prefixes (never the full key).

Response

{
  "keys": [
    {
      "id": "uuid",
      "name": "Production Key",
      "keyPrefix": "sk_live_ab",
      "isActive": true,
      "createdAt": "2026-01-15T10:00:00Z",
      "lastUsedAt": "2026-03-28T14:30:00Z"
    }
  ]
}

POST/api/v1/api-keys

Create a new API key. Maximum 5 keys per workspace. Save the key — it cannot be retrieved again.

Request Body

{
  "name": "Production Key"
}

Response

{
  "id": "uuid",
  "name": "Production Key",
  "key": "sk_live_a1b2c3d4e5f6...",
  "keyPrefix": "sk_live_ab",
  "createdAt": "2026-03-21T12:00:00Z"
}

DELETE/api/v1/api-keys

Revoke an API key permanently.

Request Body

{
  "id": "uuid-of-key-to-delete"
}

Response

{ "success": true }

QR Codes

Create, retrieve, update, and delete dynamic QR codes with full styling, routing, password protection, and expiry configuration.

GET/api/v1/qr?limit=50&offset=0

List all QR codes in your workspace. Supports pagination via limit and offset query parameters.

Response

{
  "data": [
    {
      "id": "uuid",
      "title": "My Menu QR",
      "shortCode": "abc123",
      "destinationUrl": "https://example.com/menu",
      "qrType": "url",
      "isDynamic": true,
      "scanCount": 142,
      "isActive": true,
      "styleConfig": { "foregroundColor": "#000" },
      "routingConfig": null,
      "createdAt": "2026-01-10T08:00:00Z"
    }
  ],
  "limit": 50,
  "offset": 0
}

GET/api/v1/qr/:id

Get a single QR code by ID.

Response

{
  "id": "uuid",
  "title": "My Menu QR",
  "shortCode": "abc123",
  "destinationUrl": "https://example.com/menu",
  "qrType": "url",
  "isDynamic": true,
  "scanCount": 142,
  "isActive": true,
  "password": null,
  "expiresAt": null,
  "styleConfig": { ... },
  "routingConfig": { ... },
  "createdAt": "2026-01-10T08:00:00Z"
}

POST/api/v1/qr

Create a new QR code. Supports types: url, wifi, vcard, email, sms, phone, text. Optional password protection and expiry.

Request Body

{
  "title": "Product Launch QR",
  "destinationUrl": "https://example.com/launch",
  "qrType": "url",
  "isDynamic": true,
  "password": null,
  "expiresAt": null,
  "styleConfig": {
    "foregroundColor": "#000000",
    "backgroundColor": "#ffffff",
    "dotStyle": "rounded",
    "errorCorrectionLevel": "M",
    "width": 400
  }
}

Response

{
  "id": "uuid",
  "shortCode": "xYz789",
  "shortUrl": "https://qr.claudeo.ai/r/xYz789",
  "qrDataUrl": "data:image/png;base64,iVBOR...",
  "title": "Product Launch QR",
  "destinationUrl": "https://example.com/launch",
  "scanCount": 0,
  "createdAt": "2026-03-21T12:00:00Z"
}

PATCH/api/v1/qr/:id

Update a QR code's destination, title, style, routing config, or active status. Routing rules and A/B testing are plan-gated.

Request Body

{
  "title": "Updated Title",
  "destinationUrl": "https://newdomain.com/page",
  "isActive": true,
  "routingConfig": {
    "rules": [
      {
        "conditions": [{ "field": "country", "value": "IN" }],
        "destinationUrl": "https://india.example.com"
      }
    ]
  }
}

Response

{
  "id": "uuid",
  "title": "Updated Title",
  "destinationUrl": "https://newdomain.com/page",
  "isActive": true,
  "routingConfig": { ... }
}

DELETE/api/v1/qr/:id

Delete a QR code permanently.

Response

{ "success": true }

POST/api/v1/qr/generatePublic

Generate a QR code image as a data URL without creating a database record. No authentication required.

Request Body

{
  "data": "https://example.com",
  "style": {
    "foregroundColor": "#000000",
    "backgroundColor": "#ffffff",
    "width": 400
  }
}

Response

{
  "dataUrl": "data:image/png;base64,iVBOR..."
}

Short URLs

Create and manage short URLs with click tracking, custom codes, UTM parameters, password protection, and expiry.

GET/api/v1/links?limit=50&offset=0

List all short URLs in your workspace. Supports pagination.

Response

{
  "data": [
    {
      "id": "uuid",
      "shortCode": "abc",
      "destinationUrl": "https://example.com/long-page",
      "title": "Marketing Link",
      "clickCount": 89,
      "isActive": true,
      "createdAt": "2026-02-01T10:00:00Z"
    }
  ],
  "limit": 50,
  "offset": 0
}

GET/api/v1/links/:id

Get a single short URL by ID.

Response

{
  "id": "uuid",
  "shortCode": "abc",
  "shortUrl": "https://qr.claudeo.ai/r/abc",
  "destinationUrl": "https://example.com/long-page",
  "title": "Marketing Link",
  "clickCount": 89,
  "isActive": true,
  "password": null,
  "expiresAt": null,
  "utmSource": "newsletter",
  "utmMedium": "email",
  "utmCampaign": "spring-sale"
}

POST/api/v1/links

Create a new short URL. Supports custom short codes, UTM parameters, password protection, and expiry.

Request Body

{
  "destinationUrl": "https://example.com/very-long-page-url",
  "title": "Campaign Link",
  "customCode": "my-link",
  "password": null,
  "expiresAt": null,
  "utmSource": "newsletter",
  "utmMedium": "email",
  "utmCampaign": "spring-sale"
}

Response

{
  "id": "uuid",
  "shortCode": "my-link",
  "shortUrl": "https://qr.claudeo.ai/r/my-link",
  "destinationUrl": "https://example.com/very-long-page-url"
}

PATCH/api/v1/links/:id

Update a short URL's destination, title, or active status.

Request Body

{
  "title": "Updated Link",
  "destinationUrl": "https://newdomain.com/page",
  "isActive": true
}

Response

{
  "id": "uuid",
  "shortCode": "my-link",
  "shortUrl": "https://qr.claudeo.ai/r/my-link",
  "destinationUrl": "https://newdomain.com/page",
  "isActive": true
}

DELETE/api/v1/links/:id

Delete a short URL permanently.

Response

{ "success": true }

AI Analytics & Insights

Retrieve scan analytics, generate AI-powered insights on demand, and export raw data as CSV.

GET/api/v1/analytics

Get workspace-level aggregate stats: total QR codes, links, scans, and AI art generations.

Response

{
  "totalQrCodes": 12,
  "totalLinks": 25,
  "totalScans": 4821,
  "totalAiArts": 8
}

GET/api/v1/analytics/:id?days=30&tz=Asia/Kolkata

Get detailed analytics for a specific QR code. Supports days (default 30) and tz (timezone) query parameters. Analytics retention depends on plan.

Response

{
  "totalScans": 142,
  "uniqueScans": 98,
  "scansOverTime": [
    { "date": "2026-03-20", "scans": 12 }
  ],
  "topLocations": [
    { "city": "Mumbai", "country": "IN", "scans": 45 }
  ],
  "countries": [
    { "country": "IN", "scans": 85 }
  ],
  "devices": [
    { "device": "mobile", "count": 110 }
  ],
  "operatingSystems": [
    { "os": "Android", "count": 78 }
  ],
  "browsers": [
    { "browser": "Chrome", "count": 92 }
  ],
  "referrers": [
    { "referrer": "instagram.com", "count": 30 }
  ],
  "scansByHour": [
    { "hour": 14, "count": 22 }
  ]
}

GET/api/v1/analytics/:id/insights?days=30

Generate AI-powered insights for a QR code's scan data on demand (uses GPT-4o-mini). Requires Starter plan or above.

Response

{
  "insights": [
    {
      "type": "trend",
      "title": "Scan Growth",
      "description": "Scans increased 35% this week...",
      "confidence": 0.92
    },
    {
      "type": "recommendation",
      "title": "Optimize for Mobile",
      "description": "78% of scans come from mobile..."
    }
  ]
}

GET/api/v1/analytics/:id/export?days=30

Export raw scan data as CSV. Returns a downloadable file. Requires Pro or Business plan.

Response

Date,Time,Country,City,Region,Latitude,Longitude,Language,Device,OS,Browser,Referrer,Unique,Matched Rule,A/B Variant
2026-03-20,14:30:00,IN,Mumbai,MH,19.0760,72.8777,en,mobile,Android,Chrome,instagram.com,Yes,,

AI Art

Generate AI-powered artistic QR codes using Google Gemini (fast, synchronous) or Replicate ControlNet (async, polling). Monthly generation limits apply per plan.

GET/api/v1/ai-art

List available styles, recent AI art generations, and monthly usage for your workspace.

Response

{
  "styles": [
    { "id": "watercolor", "name": "Watercolor", "prompt": "..." }
  ],
  "arts": [
    {
      "id": "uuid",
      "name": "AI Art — Watercolor",
      "style": "watercolor",
      "imageUrl": "data:image/png;base64,...",
      "prompt": "A Japanese garden with cherry blossoms",
      "createdAt": "2026-03-20T10:00:00Z"
    }
  ],
  "usage": { "used": 3, "limit": 10, "plan": "pro" }
}

POST/api/v1/ai-art

Generate a new AI art QR code. Use engine 'gemini' for fast synchronous results or 'replicate' for async ControlNet generation. Provide either qrCodeId or qrCodeContent.

Request Body

{
  "prompt": "A watercolor painting of a sunset over mountains",
  "qrCodeId": "uuid-of-existing-qr",
  "engine": "gemini",
  "style": "watercolor",
  "name": "Sunset Art",
  "qrOpacity": 0.85,
  "qrPosition": "center",
  "qrStyle": "dark-on-light",
  "qrPadding": true
}

Response

{
  "engine": "gemini",
  "status": "succeeded",
  "output": "data:image/png;base64,iVBOR...",
  "usage": { "used": 4, "limit": 10 }
}

Linkpages

Create and manage link-in-bio pages with customizable themes, backgrounds, button styles, and multiple links. Supports templates.

GET/api/v1/linkpages

List all linkpages in your workspace.

Response

{
  "data": [
    {
      "id": "uuid",
      "slug": "lp-abc123",
      "title": "My Links",
      "bio": "Digital creator",
      "isPublished": true,
      "viewCount": 340,
      "backgroundColor": "#f0fdf4",
      "buttonColor": "#059669",
      "buttonStyle": "rounded",
      "createdAt": "2026-02-15T10:00:00Z"
    }
  ]
}

GET/api/v1/linkpages/:id

Get a single linkpage with all its links.

Response

{
  "id": "uuid",
  "slug": "lp-abc123",
  "title": "My Links",
  "bio": "Digital creator",
  "isPublished": true,
  "backgroundColor": "#f0fdf4",
  "buttonColor": "#059669",
  "links": [
    {
      "id": "uuid",
      "label": "Portfolio",
      "url": "https://example.com",
      "icon": null,
      "sortOrder": 0,
      "isActive": true
    }
  ]
}

POST/api/v1/linkpages

Create a new linkpage. Optionally pass template fields (backgroundColor, buttonColor, buttonStyle) and initial links array.

Request Body

{
  "title": "My Brand",
  "backgroundColor": "#ffffff",
  "buttonColor": "#059669",
  "buttonStyle": "rounded",
  "links": [
    { "label": "Website", "url": "https://example.com" },
    { "label": "Twitter", "url": "https://x.com/me" }
  ]
}

Response

{
  "id": "uuid",
  "slug": "lp-xyz789",
  "title": "My Brand",
  "isPublished": false
}

PATCH/api/v1/linkpages/:id

Update linkpage settings. Passing a links array replaces all existing links.

Request Body

{
  "title": "Updated Brand",
  "bio": "Digital creator & developer",
  "backgroundColor": "#f0fdf4",
  "buttonColor": "#059669",
  "fontFamily": "Inter",
  "isPublished": true,
  "links": [
    { "label": "Portfolio", "url": "https://...", "isActive": true },
    { "label": "Twitter", "url": "https://...", "isActive": true }
  ]
}

Response

{
  "id": "uuid",
  "title": "Updated Brand",
  "slug": "lp-abc123",
  "isPublished": true,
  "links": [ ... ]
}

DELETE/api/v1/linkpages/:id

Delete a linkpage and all its links permanently.

Response

{ "success": true }

Forms

Create forms (manually or via AI), collect responses, and manage form data. Supports field types: text, email, number, textarea, select (dropdown), radio, and checkbox.

GET/api/v1/forms

List all forms in your workspace.

Response

{
  "data": [
    {
      "id": "uuid",
      "title": "Feedback Form",
      "description": "Collect user feedback",
      "isPublished": true,
      "responseCount": 42,
      "fields": [ ... ],
      "createdAt": "2026-03-01T10:00:00Z"
    }
  ]
}

GET/api/v1/forms/:id

Get a form with all its fields and collected responses.

Response

{
  "id": "uuid",
  "title": "Contact Form",
  "description": "Get in touch",
  "isPublished": true,
  "fields": [
    { "id": "f1", "type": "text", "label": "Name", "required": true },
    { "id": "f2", "type": "email", "label": "Email", "required": true },
    { "id": "f3", "type": "radio", "label": "Priority", "options": ["Low", "Medium", "High"] }
  ],
  "responses": [
    {
      "id": "uuid",
      "data": { "Name": "John", "Email": "john@example.com", "Priority": "High" },
      "submittedAt": "2026-03-20T10:00:00Z"
    }
  ],
  "responseCount": 42
}

POST/api/v1/forms

Create a new form with custom fields. Supported field types: text, email, number, textarea, select, radio, checkbox. Include options array for select and radio types.

Request Body

{
  "title": "Contact Form",
  "description": "Get in touch with us",
  "fields": [
    { "id": "f1", "type": "text", "label": "Name", "required": true },
    { "id": "f2", "type": "email", "label": "Email", "required": true },
    { "id": "f3", "type": "select", "label": "Department",
      "options": ["Sales", "Support", "Engineering"], "required": true },
    { "id": "f4", "type": "radio", "label": "Priority",
      "options": ["Low", "Medium", "High"] },
    { "id": "f5", "type": "textarea", "label": "Message", "required": false }
  ]
}

Response

{
  "id": "uuid",
  "title": "Contact Form",
  "isPublished": false,
  "responseCount": 0,
  "createdAt": "2026-03-21T12:00:00Z"
}

POST/api/v1/forms/ai-generate

Generate a form using AI (Gemini 2.5 Flash). Describe the form you need in natural language. Limited to 10 AI-generated forms per month.

Request Body

{
  "prompt": "Create a customer satisfaction survey for a restaurant with ratings, food quality feedback, and suggestions"
}

Response

{
  "id": "uuid",
  "title": "Customer Satisfaction Survey",
  "description": "Rate your dining experience",
  "fields": [
    { "id": "field_1", "type": "text", "label": "Your Name", "required": true },
    { "id": "field_2", "type": "radio", "label": "Overall Rating",
      "options": ["Excellent", "Good", "Average", "Poor"] },
    { "id": "field_3", "type": "textarea", "label": "Suggestions" }
  ],
  "isPublished": false,
  "responseCount": 0
}

PATCH/api/v1/forms/:id

Update a form's title, description, fields, or publish status.

Request Body

{
  "title": "Updated Form Title",
  "isPublished": true,
  "fields": [
    { "id": "f1", "type": "text", "label": "Full Name", "required": true },
    { "id": "f2", "type": "email", "label": "Email", "required": true }
  ]
}

Response

{
  "id": "uuid",
  "title": "Updated Form Title",
  "isPublished": true,
  "updatedAt": "2026-03-21T14:00:00Z"
}

DELETE/api/v1/forms/:id

Delete a form and all its responses permanently.

Response

{ "success": true }

POST/api/v1/forms/:id/submitPublic

Submit a response to a published form. No authentication required — this is a public endpoint for form respondents.

Request Body

{
  "data": {
    "Name": "Jane Doe",
    "Email": "jane@example.com",
    "Priority": "High",
    "Message": "Hello!"
  }
}

Response

{ "success": true }

Rate Limits & Plan Limits

Plan	API Access	Rate Limit	API Keys
Free / Starter / Pro	Not available	—	—
Business	Full access	1,000 req/min	Up to 5
Enterprise	Full access	Custom	Custom

AI Form Generation: 10 forms/month across all plans.

AI Art Generation: Monthly limit depends on plan (e.g., 10/month on Pro).

AI Insights: Requires Starter plan or above.

CSV Export: Requires Pro or Business plan.

Error Codes

Code	Description
`400`	Bad Request — Invalid parameters or missing required fields
`401`	Unauthorized — Missing or invalid API key
`403`	Forbidden — Plan limit reached or feature not available on your plan
`404`	Not Found — Resource does not exist or belongs to another workspace
`409`	Conflict — Duplicate resource (e.g., short code already taken)
`429`	Too Many Requests — Rate limit or monthly generation limit exceeded
`502`	Bad Gateway — External AI service error (Gemini, OpenAI)
`500`	Internal Server Error — Unexpected failure

All error responses follow the format: {"error": "message"}. Some errors include a code field (e.g., PLAN_LIMIT_REACHED) for programmatic handling.

Ready to integrate?

Get your API key from the dashboard and start building.

Get API Key Go to Dashboard