{"openapi":"3.1.0","info":{"title":"EZQR API","version":"1.0.0","description":"Create, manage, and track QR codes programmatically. Supports static & dynamic QR codes, batch creation, analytics, and showcase landing pages.","contact":{"url":"https://dev.ez-qr.com/api-docs"}},"servers":[{"url":"https://dev.ez-qr.com/api/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"paths":{"/qr-codes":{"get":{"operationId":"listQrCodes","summary":"List QR codes","tags":["QR Codes"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":100}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}},{"name":"type","in":"query","schema":{"type":"string","enum":["static","dynamic"]}}],"responses":{"200":{"description":"Paginated list of QR codes","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/QrCode"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}}}},"post":{"operationId":"createQrCode","summary":"Create a QR code","tags":["QR Codes"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateQrCode"}}}},"responses":{"201":{"description":"Created QR code","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/QrCode"}}}}}}}}},"/qr-codes/{id}":{"get":{"operationId":"getQrCode","summary":"Get a QR code by ID","tags":["QR Codes"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"QR code details","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/QrCode"}}}}}},"404":{"description":"Not found"}}},"patch":{"operationId":"updateQrCode","summary":"Update a QR code","tags":["QR Codes"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateQrCode"}}}},"responses":{"200":{"description":"Updated QR code","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/QrCode"}}}}}}}},"delete":{"operationId":"deleteQrCode","summary":"Delete a QR code","tags":["QR Codes"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}}}}},"/qr-codes/batch":{"post":{"operationId":"batchCreateQrCodes","summary":"Batch create QR codes (max 100)","tags":["QR Codes"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["codes"],"properties":{"codes":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/CreateQrCode"}}}}}}},"responses":{"201":{"description":"Batch result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"created":{"type":"integer"},"errors":{"type":"array","items":{"type":"string"}}}}}}}}}}}},"/qr-codes/{id}/analytics":{"get":{"operationId":"getQrCodeAnalytics","summary":"Get scan analytics for a QR code","tags":["Analytics"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"period","in":"query","schema":{"type":"string","enum":["7d","30d","90d","all"],"default":"30d"}}],"responses":{"200":{"description":"Analytics data","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Analytics"}}}}}}}}},"/showcases":{"get":{"operationId":"listShowcases","summary":"List showcase landing pages","tags":["Showcases"],"responses":{"200":{"description":"List of showcases","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Showcase"}}}}}}}}},"post":{"operationId":"createShowcase","summary":"Create a showcase landing page","tags":["Showcases"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateShowcase"}}}},"responses":{"201":{"description":"Created showcase","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Showcase"}}}}}}}}},"/showcases/{id}":{"get":{"operationId":"getShowcase","summary":"Get a showcase by ID","tags":["Showcases"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Showcase details","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Showcase"}}}}}}}},"patch":{"operationId":"updateShowcase","summary":"Update a showcase","tags":["Showcases"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateShowcase"}}}},"responses":{"200":{"description":"Updated showcase","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Showcase"}}}}}}}},"delete":{"operationId":"deleteShowcase","summary":"Delete a showcase","tags":["Showcases"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key (ezqr_...)","description":"API key from your EZQR dashboard. Requires Business plan. Format: Bearer ezqr_<key>"}},"schemas":{"QrCode":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"type":{"type":"string","enum":["static","dynamic"]},"contentType":{"type":"string"},"content":{"type":"string"},"targetUrl":{"type":"string","nullable":true},"shortCode":{"type":"string","nullable":true},"style":{"type":"object","nullable":true},"isActive":{"type":"boolean"},"totalScans":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"CreateQrCode":{"type":"object","required":["name","contentType","content"],"properties":{"name":{"type":"string"},"type":{"type":"string","enum":["static","dynamic"],"default":"static"},"contentType":{"type":"string","description":"QR content type (e.g. url, wifi, vcard, email, phone, sms, text)"},"content":{"type":"string"},"targetUrl":{"type":"string","format":"uri","nullable":true},"style":{"type":"object","nullable":true}}},"UpdateQrCode":{"type":"object","properties":{"name":{"type":"string"},"content":{"type":"string"},"targetUrl":{"type":"string","format":"uri","nullable":true},"isActive":{"type":"boolean"},"style":{"type":"object","nullable":true}}},"Analytics":{"type":"object","properties":{"totalEvents":{"type":"integer"},"uniqueVisitors":{"type":"integer"},"eventsByDay":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"count":{"type":"integer"}}}},"topDevices":{"type":"array","items":{"$ref":"#/components/schemas/NameCount"}},"topBrowsers":{"type":"array","items":{"$ref":"#/components/schemas/NameCount"}},"topOs":{"type":"array","items":{"$ref":"#/components/schemas/NameCount"}},"topCountries":{"type":"array","items":{"$ref":"#/components/schemas/NameCount"}},"topCities":{"type":"array","items":{"$ref":"#/components/schemas/NameCount"}},"topReferrers":{"type":"array","items":{"$ref":"#/components/schemas/NameCount"}}}},"NameCount":{"type":"object","properties":{"name":{"type":"string"},"count":{"type":"integer"}}},"Showcase":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"qrCodeId":{"type":"string","format":"uuid"},"title":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string","nullable":true},"template":{"type":"string","enum":["minimal","modern","bold","professional","dark"]},"customColors":{"type":"object","nullable":true},"customBackgroundUrl":{"type":"string","format":"uri","nullable":true},"logoUrl":{"type":"string","nullable":true},"socialLinks":{"type":"array","nullable":true},"ctaButtons":{"type":"array","nullable":true},"showBranding":{"type":"boolean"},"isActive":{"type":"boolean"},"viewCount":{"type":"integer"},"downloadCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}}},"CreateShowcase":{"type":"object","required":["qrCodeId","title"],"properties":{"qrCodeId":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"slug":{"type":"string"},"template":{"type":"string","enum":["minimal","modern","bold","professional","dark"],"default":"minimal"},"customColors":{"type":"object","nullable":true},"customBackgroundUrl":{"type":"string","format":"uri","nullable":true},"logoUrl":{"type":"string","nullable":true},"showBranding":{"type":"boolean","default":true}}},"UpdateShowcase":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string","nullable":true},"slug":{"type":"string"},"template":{"type":"string","enum":["minimal","modern","bold","professional","dark"]},"customColors":{"type":"object","nullable":true},"customBackgroundUrl":{"type":"string","format":"uri","nullable":true},"logoUrl":{"type":"string","nullable":true},"showBranding":{"type":"boolean"},"isActive":{"type":"boolean"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{}}}}}}