{"openapi":"3.1.0","info":{"title":"QR Maker API","version":"2.1.0","description":"Agent-first QR infrastructure as a service. Generate styled QR codes, manage dynamic short links with click analytics, publish micro-landing pages, and reuse branded templates — all via API key authentication.","contact":{"email":"support@qr-maker.io"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://api.qr-maker.io/v2","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key — get yours from Settings → API Keys in the dashboard"}},"schemas":{"DotsOptions":{"type":"object","properties":{"color":{"type":"string","example":"#6366f1","description":"Hex color"},"type":{"type":"string","enum":["square","dots","rounded","extra-rounded","classy","classy-rounded"],"default":"rounded"}}},"BackgroundOptions":{"type":"object","properties":{"color":{"type":"string","example":"#ffffff"}}},"QrStyleOptions":{"type":"object","properties":{"width":{"type":"integer","default":400},"height":{"type":"integer","default":400},"margin":{"type":"integer","default":10},"dotsOptions":{"$ref":"#/components/schemas/DotsOptions"},"backgroundOptions":{"$ref":"#/components/schemas/BackgroundOptions"},"cornersSquareOptions":{"$ref":"#/components/schemas/DotsOptions"},"cornersDotOptions":{"$ref":"#/components/schemas/DotsOptions"}}},"GenerateQrRequest":{"type":"object","required":["content"],"properties":{"content":{"type":"string","example":"https://qr-maker.io","description":"URL, plain text, WiFi string, vCard, etc."},"format":{"type":"string","enum":["png","svg","jpg","jpeg","pdf"],"default":"png"},"style":{"$ref":"#/components/schemas/QrStyleOptions","description":"QR styling options (also accepts \"options\" as alias)"},"template_id":{"type":"string","description":"Optional style preset ID to use as base"}}},"GenerateQrResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"content":{"type":"string","description":"The content encoded in the QR (short URL when a link was created, or raw content for WiFi/vCard/text)."},"format":{"type":"string"},"type":{"type":"string","description":"Always \"image\"."},"url":{"type":"string","description":"Public URL of the QR image. ALWAYS render inline: ![QR Code](url)"},"alt":{"type":"string","description":"Alt text for the QR image."},"image_url":{"type":"string","description":"Alias for url (backward compat). Prefer url."},"image_base64":{"type":"string","description":"Base64-encoded image. Only in non-compact mode. Use url for display."},"short_link":{"type":"object","nullable":true,"description":"Short link created for URL content. ALWAYS show the short URL to the user so they can share it. Null when content is non-URL (WiFi, vCard, etc.).","properties":{"id":{"type":"string"},"code":{"type":"string","description":"Short link code"},"url":{"type":"string","description":"Full short URL (e.g. https://go-to.at/AbCdEfG). Always display this to the user."}}},"created_at":{"type":"string","format":"date-time"}}}}},"BatchResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Batch job ID for polling"},"status":{"type":"string","enum":["processing","done","failed"]},"total":{"type":"integer"},"completed":{"type":"integer"},"failed":{"type":"integer"},"items":{"type":"array","items":{"type":"object"}},"created_at":{"type":"string","format":"date-time"}}}}},"StylePreset":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"options":{"$ref":"#/components/schemas/QrStyleOptions"},"thumbnail_url":{"type":"string","nullable":true},"version":{"type":"integer"},"is_public":{"type":"boolean"},"tags":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"CreateStylePresetRequest":{"type":"object","required":["name","options"],"properties":{"name":{"type":"string","example":"Brand style violet"},"options":{"$ref":"#/components/schemas/QrStyleOptions"},"description":{"type":"string"},"is_public":{"type":"boolean","default":false},"tags":{"type":"array","items":{"type":"string"}}}},"ShortLink":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"short_url":{"type":"string","example":"https://go-to.at/abc123"},"target_url":{"type":"string"},"status":{"type":"string","enum":["active","disabled"]},"expires_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"CreateLinkRequest":{"type":"object","required":["target_url"],"properties":{"target_url":{"type":"string","example":"https://qr-maker.io"},"custom_code":{"type":"string","description":"Optional custom short code (4-16 chars)"},"expires_at":{"type":"string","format":"date-time","description":"Optional expiration date"}}},"PublishLandingRequest":{"type":"object","required":["html"],"properties":{"html":{"type":"string","description":"Full HTML content of the landing page (max 2MB). Inline CSS and base64 images supported."},"title":{"type":"string","example":"My Landing Page","description":"Optional title (max 200 chars)"},"format":{"type":"string","enum":["png","svg","jpg","jpeg","pdf"],"default":"png","description":"QR code output format"},"style":{"$ref":"#/components/schemas/QrStyleOptions","description":"QR code style options"}}},"PublishLandingResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"landing":{"type":"object","description":"Published landing page. ALWAYS show landing.url to the user as a clickable link.","properties":{"url":{"type":"string","description":"Short URL pointing to the landing page. ALWAYS display this to the user."},"short_url":{"type":"string","description":"Same as url — the tracked short link for sharing."},"title":{"type":"string","nullable":true},"id":{"type":"string"},"version":{"type":"integer"}}},"qr":{"type":"object","description":"Generated QR code. ALWAYS display inline as an image using qr.url.","properties":{"type":{"type":"string","description":"Always \"image\""},"format":{"type":"string"},"url":{"type":"string","description":"Public URL of the QR image. ALWAYS render inline: ![QR Code](qr.url)"},"alt":{"type":"string","description":"Alt text for the QR image"},"image_base64":{"type":"string","description":"Base64-encoded QR. Only present in non-compact mode. Use qr.url for display."}}},"manage":{"type":"object","description":"Management link for non-technical users to edit/disable the landing.","properties":{"url":{"type":"string","description":"Management URL with auth token"}}},"short_link":{"type":"object","description":"Short link details for programmatic use.","properties":{"id":{"type":"string"},"code":{"type":"string"},"url":{"type":"string"}}},"created_at":{"type":"string","format":"date-time"}}}}},"UpdateLandingRequest":{"type":"object","required":["html"],"properties":{"html":{"type":"string","description":"Updated HTML content"},"title":{"type":"string"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"suggestion":{"type":"string","nullable":true}}}}}}},"paths":{"/qr/generate":{"post":{"operationId":"generateQr","x-openai-isConsequential":false,"summary":"Generate a styled QR code","description":"Generates a QR code image for any content type (URL, text, WiFi, vCard, etc.) with full style customization. The response includes image_url — always display it inline as ![QR Code](image_url).","tags":["QR"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateQrRequest"}}}},"responses":{"200":{"description":"QR generated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateQrResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded"}}}},"/qr/generate/batch":{"post":{"operationId":"batchGenerateQr","x-openai-isConsequential":false,"summary":"Batch generate QR codes (async)","description":"Enqueues up to 100 QR code generation jobs. Requires Pro tier or above. Poll `/qr/batch/{id}` for results.","tags":["QR"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/GenerateQrRequest"}},"format":{"type":"string","enum":["png","svg"],"default":"png"}}}}}},"responses":{"202":{"description":"Batch accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResponse"}}}},"403":{"description":"Requires Pro tier","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/qr/batch/{id}":{"get":{"operationId":"getBatchStatus","summary":"Poll batch generation status","tags":["QR"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Batch status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResponse"}}}},"404":{"description":"Batch not found"}}}},"/links":{"post":{"operationId":"createLink","x-openai-isConsequential":false,"summary":"Create a tracked short link","description":"Creates a dynamic short link with click analytics. The QR code always encodes the short URL — change the destination anytime without reprinting.","tags":["Links"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLinkRequest"}}}},"responses":{"201":{"description":"Link created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShortLink"}}}},"400":{"description":"Validation error"},"403":{"description":"Quota exceeded"}}},"get":{"operationId":"listLinks","summary":"List short links","tags":["Links"],"parameters":[{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor"},{"name":"limit","in":"query","schema":{"type":"integer","default":25,"maximum":100}}],"responses":{"200":{"description":"Paginated list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ShortLink"}},"meta":{"type":"object","properties":{"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}}},"/links/{id}":{"get":{"operationId":"getLink","summary":"Get short link details","tags":["Links"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Link details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShortLink"}}}},"404":{"description":"Not found"}}},"patch":{"operationId":"updateLink","summary":"Update short link","tags":["Links"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"target_url":{"type":"string"},"status":{"type":"string","enum":["active","disabled"]},"expires_at":{"type":"string","format":"date-time","nullable":true}}}}}},"responses":{"200":{"description":"Updated"},"404":{"description":"Not found"}}},"delete":{"operationId":"deleteLink","summary":"Delete short link","tags":["Links"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted"},"404":{"description":"Not found"}}}},"/links/{id}/analytics":{"get":{"operationId":"getLinkAnalytics","summary":"Get link click analytics","description":"Returns total clicks, unique visitors, country and daily breakdowns for the last 30 days.","tags":["Links"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Analytics data"},"404":{"description":"Not found"}}}},"/templates":{"post":{"operationId":"createStylePreset","x-openai-isConsequential":false,"summary":"Create a reusable QR style preset","description":"Saves QR styling options (colors, dots, corners, logo) as a reusable preset.","tags":["Style Presets"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateStylePresetRequest"}}}},"responses":{"201":{"description":"Style preset created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StylePreset"}}}},"400":{"description":"Validation error"}}},"get":{"operationId":"listStylePresets","summary":"List style presets","tags":["Style Presets"],"parameters":[{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor"},{"name":"limit","in":"query","schema":{"type":"integer","default":25,"maximum":100}}],"responses":{"200":{"description":"Paginated list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StylePreset"}},"meta":{"type":"object","properties":{"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}}},"/templates/{id}":{"get":{"operationId":"getStylePreset","summary":"Get style preset","tags":["Style Presets"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Style preset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StylePreset"}}}},"404":{"description":"Not found"}}},"patch":{"operationId":"updateStylePreset","summary":"Update style preset","tags":["Style Presets"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"options":{"$ref":"#/components/schemas/QrStyleOptions"}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StylePreset"}}}},"404":{"description":"Not found"}}},"delete":{"operationId":"deleteStylePreset","summary":"Delete style preset","tags":["Style Presets"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted"},"404":{"description":"Not found"}}}},"/templates/{id}/render":{"post":{"operationId":"renderTemplate","x-openai-isConsequential":false,"summary":"Render QR from style preset","description":"Generates a QR image using a saved style preset, with optional per-call style overrides.","tags":["Style Presets"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["content"],"properties":{"content":{"type":"string"},"format":{"type":"string","enum":["png","svg","jpg","jpeg","pdf"],"default":"png"},"overrides":{"$ref":"#/components/schemas/QrStyleOptions"}}}}}},"responses":{"200":{"description":"QR rendered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateQrResponse"}}}},"404":{"description":"Not found"}}}},"/landings/publish-with-qr":{"post":{"operationId":"publishLandingWithQr","x-openai-isConsequential":false,"summary":"Publish landing page + QR in one call","description":"Publishes an HTML landing page to CDN, creates a tracked short link, and generates a QR code — all in one call. Free-tier landings include a small \"Powered by QR Maker\" footer. After publishing, display the QR inline as ![QR Code](qr.image_url) and share the landing URL from landing.url.","tags":["Landings"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishLandingRequest"}}}},"responses":{"201":{"description":"Landing published","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishLandingResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/landings/{id}":{"get":{"operationId":"getLanding","summary":"Get landing page details","tags":["Landings"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Landing details"},"404":{"description":"Not found"}}},"put":{"operationId":"updateLanding","summary":"Update landing HTML and re-publish","description":"Updates the HTML content and re-publishes to CDN. The short link and QR code remain the same.","tags":["Landings"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateLandingRequest"}}}},"responses":{"200":{"description":"Landing updated"},"404":{"description":"Not found"}}}},"/usage":{"get":{"operationId":"getUsage","summary":"Get current period usage","description":"Returns QR generation count, links created, API calls, and plan limits for the current billing period.","tags":["Usage"],"responses":{"200":{"description":"Usage data","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"tier":{"type":"string"},"analytics_tier":{"type":"string"},"period":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}}},"usage":{"type":"object","properties":{"qr_generated":{"type":"integer"},"links_created":{"type":"integer"},"api_calls":{"type":"integer"}}},"limits":{"type":"object","properties":{"qr_per_month":{"type":"integer","nullable":true},"links":{"type":"integer","nullable":true},"rate_per_minute":{"type":"integer"}}},"estimated_cost_usd":{"type":"number","nullable":true}}}}}}}}}}},"/usage/history":{"get":{"operationId":"getUsageHistory","summary":"Get usage history (last 12 months)","tags":["Usage"],"responses":{"200":{"description":"Monthly usage history"}}}},"/capabilities":{"get":{"operationId":"getCapabilities","summary":"Get plan capabilities and feature matrix","description":"Returns the full feature matrix for your API key tier — quotas, rate limits, available features, and upgrade options. Call this first to understand what is available.","tags":["Capabilities"],"responses":{"200":{"description":"Capabilities and tier info"}}}}}}