{"openapi":"3.1.0","info":{"title":"qr3.app API","version":"1.0.0","description":"Developer-first QR-Code-Plattform — Dynamische QR-Codes, Analytics, Webhooks und EU Digital Product Passport Support.","contact":{"email":"api@qr3.app","url":"https://docs.qr3.app"},"license":{"name":"Proprietary"},"x-logo":{"url":"https://qr3.app/logo.svg"}},"servers":[{"url":"https://qr3.app/v1","description":"Production"},{"url":"http://localhost:8787/v1","description":"Local Development"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"qr3_sk_xxx or qr3_pk_xxx","description":"API key from https://app.qr3.app/api-keys"}},"schemas":{"ProblemDetails":{"type":"object","required":["type","title","status","detail"],"properties":{"type":{"type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"errors":{"type":"array","items":{"type":"object"}}}},"QRCode":{"type":"object","properties":{"id":{"type":"string","example":"qr_r7f3kx"},"workspace_id":{"type":"string","example":"ws_abc123"},"short_code":{"type":"string","example":"r7f3Kx"},"short_url":{"type":"string","format":"uri","example":"https://qr3.app/r7f3Kx"},"type":{"type":"string","enum":["url","vcard","wifi","email","sms","location","text","phone","event"]},"url":{"type":"string","format":"uri","nullable":true},"is_dynamic":{"type":"boolean"},"status":{"type":"string","enum":["draft","live","paused","archived"]},"total_scans":{"type":"integer","minimum":0},"tags":{"type":"array","items":{"type":"string"}},"notes":{"type":"string","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"images":{"type":"object","properties":{"png":{"type":"string","format":"uri"},"svg":{"type":"string","format":"uri"}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Webhook":{"type":"object","properties":{"id":{"type":"string","example":"wh_abc123"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"},"example":["qr.scanned"]},"is_active":{"type":"boolean"},"consecutive_failures":{"type":"integer"},"last_triggered_at":{"type":"string","format":"date-time","nullable":true},"last_status_code":{"type":"integer","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ScanStats":{"type":"object","properties":{"total_scans":{"type":"integer"},"unique_scanners":{"type":"integer"},"scans_today":{"type":"integer"},"by_day":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"scans":{"type":"integer"},"unique":{"type":"integer"}}}},"by_country":{"type":"array","items":{"type":"object","properties":{"country":{"type":"string","description":"ISO 3166-1 alpha-2"},"scans":{"type":"integer"}}}},"by_device":{"type":"array","items":{"type":"object","properties":{"device_type":{"type":"string","enum":["mobile","desktop","tablet","unknown"]},"scans":{"type":"integer"}}}},"by_os":{"type":"array","items":{"type":"object","properties":{"os":{"type":"string"},"scans":{"type":"integer"}}}},"by_browser":{"type":"array","items":{"type":"object","properties":{"browser":{"type":"string"},"scans":{"type":"integer"}}}}}}}},"paths":{"/health":{"get":{"summary":"Health Check","tags":["System"],"security":[],"responses":{"200":{"description":"API is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"}}}}}}}}},"/codes":{"get":{"summary":"List QR Codes","tags":["QR Codes"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["draft","live","paused","archived"]}},{"name":"type","in":"query","schema":{"type":"string"}},{"name":"tags","in":"query","schema":{"type":"string"}},{"name":"search","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"List of QR codes","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/QRCode"}},"meta":{"type":"object"}}}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}},"post":{"summary":"Create QR Code","tags":["QR Codes"],"parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["url","vcard","wifi","email","sms","location","text","phone","event"],"default":"url"},"url":{"type":"string","format":"uri","description":"Required when type=url"},"is_dynamic":{"type":"boolean","default":true},"notes":{"type":"string","maxLength":2000},"tags":{"type":"array","items":{"type":"string"},"maxItems":20},"expires_at":{"type":"string","format":"date-time"}}}}}},"responses":{"201":{"description":"QR code created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QRCode"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"422":{"description":"Validation error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/codes/{id}":{"get":{"summary":"Get QR Code","tags":["QR Codes"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"QR code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QRCode"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}},"patch":{"summary":"Update QR Code","tags":["QR Codes"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"status":{"type":"string","enum":["live","paused","archived"]},"tags":{"type":"array","items":{"type":"string"}},"notes":{"type":"string"},"expires_at":{"type":"string","format":"date-time","nullable":true}}}}}},"responses":{"200":{"description":"Updated QR code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QRCode"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}},"delete":{"summary":"Delete QR Code","tags":["QR Codes"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted"},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/codes/{id}/stats":{"get":{"summary":"Get Scan Statistics","tags":["Analytics"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Scan statistics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanStats"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/webhooks":{"get":{"summary":"List Webhooks","tags":["Webhooks"],"responses":{"200":{"description":"List of webhooks","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}}}}}}}},"post":{"summary":"Create Webhook","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","secret"],"properties":{"url":{"type":"string","format":"uri","description":"Must be HTTPS"},"events":{"type":"array","items":{"type":"string"},"default":["*"]},"secret":{"type":"string","minLength":16,"description":"HMAC secret (store securely)"}}}}}},"responses":{"201":{"description":"Webhook created (contains secret — only shown once)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"422":{"description":"Validation error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/webhooks/{id}":{"get":{"summary":"Get Webhook","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Webhook","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}}}},"patch":{"summary":"Update Webhook","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"is_active":{"type":"boolean"},"secret":{"type":"string","description":"Rotate the HMAC secret"}}}}}},"responses":{"200":{"description":"Updated webhook"}}},"delete":{"summary":"Delete Webhook","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted"}}}},"/webhooks/{id}/deliveries":{"get":{"summary":"List Webhook Deliveries","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Delivery log"}}}},"/webhooks/{id}/ping":{"post":{"summary":"Ping Webhook","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ping result with status code and response time"}}}},"/api-keys":{"get":{"summary":"List API Keys","tags":["API Keys"],"responses":{"200":{"description":"List of API keys"}}},"post":{"summary":"Create API Key","tags":["API Keys"],"responses":{"201":{"description":"Created API key (secret shown once)"}}}},"/account":{"get":{"summary":"Get Account","tags":["Account"],"responses":{"200":{"description":"Account information"}}}}},"tags":[{"name":"QR Codes","description":"Create, manage and configure QR codes"},{"name":"Analytics","description":"Scan statistics and analytics"},{"name":"Webhooks","description":"Real-time event notifications"},{"name":"API Keys","description":"Manage API keys for your workspace"},{"name":"Account","description":"Account and workspace information"},{"name":"System","description":"Health checks and system endpoints"}]}