{"openapi":"3.1.0","info":{"title":"QR Cake API","version":"1.0.0","description":"Public REST API for QR Cake. Lets QR Cake users manage their QR Codes programmatically: create, read, update, and delete. Authentication uses an API key created in the QR Cake dashboard and sent in the `x-api-key` request header.","termsOfService":"https://qrcake.com/terms","contact":{"name":"QR Cake Support","url":"https://qrcake.com/help","email":"support@qrcake.com"},"license":{"name":"QR Cake Terms of Service","url":"https://qrcake.com/terms"}},"servers":[{"url":"https://api.qrcake.com/v1/product/api","description":"Production API. API-key endpoints are versioned under /v1/product/api and authenticated with the x-api-key header."}],"externalDocs":{"description":"QR Cake API documentation (full reference with examples and interactive tester)","url":"https://qrcake.com/docs"},"tags":[{"name":"QR Codes","description":"Create, read, update, and delete QR Codes (referred to as \"products\" in path names)."},{"name":"Account","description":"Inspect API-key plan limits and usage."}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key sent in the `x-api-key` header. Create one in the QR Cake dashboard under API Keys."}},"schemas":{"Product":{"type":"object","description":"A QR Cake product (a single QR Code).","properties":{"accountId":{"type":"string","description":"ID of the account that owns the QR Code."},"productId":{"type":"string","description":"Unique identifier for the QR Code. Use this in URL paths."},"userId":{"type":"string","description":"ID of the user that created the QR Code."},"redirect":{"type":"string","format":"uri","description":"The current destination the QR Code redirects to when scanned. Editable without reprinting the code."},"state":{"type":"string","enum":["ACTIVE","INACTIVE"],"description":"Whether the QR Code is currently active (ACTIVE) or paused (INACTIVE)."},"metadata":{"type":"object","description":"Free-form metadata for the QR Code. The `type` field selects the QR content type (see QrType). Other fields configure design, content, and labels.","properties":{"type":{"$ref":"#/components/schemas/QrType"}},"additionalProperties":true},"expiresAt":{"type":"integer","format":"int64","description":"Optional expiry timestamp in Unix epoch milliseconds. Most codes have no expiry."},"createdAt":{"type":"integer","format":"int64","description":"Creation time in Unix epoch milliseconds."},"updatedAt":{"type":"integer","format":"int64","description":"Last-update time in Unix epoch milliseconds."}},"required":["accountId","productId","userId","redirect","state","metadata","createdAt","updatedAt"]},"ProductMutation":{"type":"object","description":"Request body for creating or updating a QR Code. Must be JSON-stringified before sending.","properties":{"redirect":{"type":"string","format":"uri","description":"Destination URL the QR Code should resolve to when scanned.","example":"https://example.com"},"metadata":{"type":"object","description":"QR Code design and content metadata. Include `type` to set the QR content type.","properties":{"type":{"$ref":"#/components/schemas/QrType"}},"additionalProperties":true,"example":{"type":"redirect"}},"state":{"type":"string","enum":["ACTIVE","INACTIVE"],"description":"Whether the QR Code should be active.","default":"ACTIVE"},"uploads":{"type":"array","items":{"type":"string"},"description":"Upload keys (from the signed upload endpoint) for any files referenced by this QR Code, e.g. a file-download target or a logo image."}}},"Permissions":{"type":"object","properties":{"success":{"type":"boolean"},"result":{"type":"object","properties":{"userId":{"type":"string","description":"ID of the account that owns the API key."},"tier":{"type":"string","description":"Plan tier identifier.","example":"subscriber"},"active":{"type":"boolean","description":"Whether the account has an active paid subscription."},"analytics":{"type":"boolean","description":"Whether the plan grants access to scan analytics."},"productLimit":{"type":"integer","description":"Maximum number of QR Codes the account may own in total."},"productTotal":{"type":"integer","description":"Current number of QR Codes owned by the account."},"productActiveLimit":{"type":"integer","description":"Maximum number of ACTIVE QR Codes the account may have at once."},"productActiveTotal":{"type":"integer","description":"Current number of ACTIVE QR Codes owned by the account."}}}},"required":["success","result"]},"Unauthorized":{"type":"object","description":"Returned when the x-api-key header is missing or the API key is invalid.","properties":{"message":{"type":"object","description":"Error details (shape may vary)."}}},"DeleteResponse":{"type":"object","properties":{"productId":{"type":"string","description":"ID of the deleted QR Code."}}},"QrType":{"type":"string","enum":["redirect","link","image","video","file","pdf","audio","app","event","vCard","review","email"],"description":"The QR content type. `redirect` = website/URL, `link` = link list, `image` = image, `video` = video, `file` = file download, `pdf` = PDF document, `audio` = audio file, `vCard` = digital business card. `app` and `event` are reserved (currently in preview)."}},"responses":{"UnauthorizedResponse":{"description":"Authentication failed (missing, invalid, or expired API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized"}}}}},"parameters":{"ProductIdPath":{"name":"productId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the QR Code (product) to operate on."}}},"security":[{"apiKeyAuth":[]}],"paths":{"/product":{"get":{"tags":["QR Codes"],"summary":"List QR Codes","description":"Lists every QR Code owned by the authenticated API key.","operationId":"listProducts","responses":{"200":{"description":"An array of QR Code objects.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"}}},"post":{"tags":["QR Codes"],"summary":"Create a QR Code","description":"Creates a new QR Code (product). Body must be JSON-stringified (for example, `JSON.stringify(payload)` in JavaScript).","operationId":"createProduct","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductMutation"}}}},"responses":{"200":{"description":"The newly created QR Code object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"}}}},"/product/{productId}":{"get":{"tags":["QR Codes"],"summary":"Get a QR Code","description":"Fetches a single QR Code by its productId.","operationId":"getProduct","parameters":[{"$ref":"#/components/parameters/ProductIdPath"}],"responses":{"200":{"description":"The QR Code object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"}}},"put":{"tags":["QR Codes"],"summary":"Update a QR Code","description":"Updates an existing QR Code. Body must be JSON-stringified (for example, `JSON.stringify(payload)` in JavaScript).","operationId":"updateProduct","parameters":[{"$ref":"#/components/parameters/ProductIdPath"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductMutation"}}}},"responses":{"200":{"description":"The updated QR Code object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"}}},"delete":{"tags":["QR Codes"],"summary":"Delete a QR Code","description":"Permanently deletes a QR Code. The printed code will stop redirecting after deletion.","operationId":"deleteProduct","parameters":[{"$ref":"#/components/parameters/ProductIdPath"}],"responses":{"200":{"description":"The deleted QR Code productId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"}}}},"/permission":{"get":{"tags":["Account"],"summary":"Get API key permissions","description":"Returns the plan limits and current usage for the authenticated API key (tier, analytics access, total/active product limits and counts).","operationId":"getPermissions","responses":{"200":{"description":"Plan limits and usage for the API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Permissions"}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"}}}}}}