{
    "openapi": "3.1.0",
    "info": {
        "title": "qr9 API",
        "version": "1.0.0",
        "summary": "Create and manage QR codes from your own system.",
        "description": "REST API of qr9, a Swiss QR code service. Create link QR codes, change their target after printing, fetch the image and the scan numbers. Available on the Business and Agentur plans. Authenticate with an API key created in the account under \"API\", sent as a bearer token. Requests and responses are JSON. Rate limit: 120 requests per minute per account. QR codes cannot be deleted through the API, because a deleted code breaks whatever was printed with it."
    },
    "servers": [
        {
            "url": "https://qr9.ch/api/v1"
        }
    ],
    "security": [
        {
            "bearerAuth": []
        }
    ],
    "paths": {
        "/qr-codes": {
            "get": {
                "operationId": "listQrCodes",
                "summary": "List QR codes, newest first.",
                "parameters": [
                    {
                        "name": "client_id",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Only codes of this client."
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100,
                            "default": 25
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "default": 1
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/QrCodeList"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or invalid API token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Plan does not include the API, or the QR code limit is reached.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "More than 120 requests per minute."
                    }
                }
            },
            "post": {
                "operationId": "createQrCode",
                "summary": "Create a link QR code.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/QrCodeCreate"
                            },
                            "example": {
                                "name": "Flyer Sommer",
                                "target_url": "https://example.ch/sommer",
                                "slug": "sommer-aktion"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/QrCodeResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid input, slug taken, or unsafe target.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or invalid API token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Plan does not include the API, or the QR code limit is reached.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "More than 120 requests per minute."
                    }
                }
            }
        },
        "/qr-codes/{id}": {
            "get": {
                "operationId": "getQrCode",
                "summary": "Get one QR code.",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Id of the QR code: a random string such as \"k3x9q7m2p0a8d4fz\", as returned in \"id\"."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/QrCodeResponse"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Unknown id.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or invalid API token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Plan does not include the API, or the QR code limit is reached.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "More than 120 requests per minute."
                    }
                }
            },
            "patch": {
                "operationId": "updateQrCode",
                "summary": "Change name, target, slug, client or expiry. Send only the fields to change.",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Id of the QR code: a random string such as \"k3x9q7m2p0a8d4fz\", as returned in \"id\"."
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/QrCodeUpdate"
                            },
                            "example": {
                                "target_url": "https://example.ch/herbst"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/QrCodeResponse"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Unknown id.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid input, slug taken, or unsafe target.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or invalid API token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Plan does not include the API, or the QR code limit is reached.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "More than 120 requests per minute."
                    }
                }
            }
        },
        "/qr-codes/{id}/image": {
            "get": {
                "operationId": "getQrCodeImage",
                "summary": "The QR code as an image file.",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Id of the QR code: a random string such as \"k3x9q7m2p0a8d4fz\", as returned in \"id\"."
                    },
                    {
                        "name": "format",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "svg",
                                "png"
                            ],
                            "default": "svg"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Image.",
                        "content": {
                            "image/svg+xml": {
                                "schema": {
                                    "type": "string"
                                }
                            },
                            "image/png": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Unknown id.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or invalid API token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Plan does not include the API, or the QR code limit is reached.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "More than 120 requests per minute."
                    }
                }
            }
        },
        "/qr-codes/{id}/scans": {
            "get": {
                "operationId": "getQrCodeScans",
                "summary": "Scan total and scans per day.",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Id of the QR code: a random string such as \"k3x9q7m2p0a8d4fz\", as returned in \"id\"."
                    },
                    {
                        "name": "days",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 90,
                            "default": 30
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ScansResponse"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Unknown id.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or invalid API token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Plan does not include the API, or the QR code limit is reached.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "More than 120 requests per minute."
                    }
                }
            }
        },
        "/clients": {
            "get": {
                "operationId": "listClients",
                "summary": "Your clients, to assign QR codes to.",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ClientList"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or invalid API token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Plan does not include the API, or the QR code limit is reached.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "More than 120 requests per minute."
                    }
                }
            },
            "post": {
                "operationId": "createClient",
                "summary": "Create a client (shown as \"Projekt\" in the dashboard). Names need not be unique.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "name"
                                ],
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255
                                    },
                                    "company": {
                                        "type": [
                                            "string",
                                            "null"
                                        ],
                                        "maxLength": 255
                                    }
                                }
                            },
                            "example": {
                                "name": "B\u00e4ckerei Muster"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ClientResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid input.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or invalid API token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Plan does not include the API, or the QR code limit is reached.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "More than 120 requests per minute."
                    }
                }
            }
        },
        "/domains": {
            "get": {
                "operationId": "listDomains",
                "summary": "Your custom domains, to create QR codes under one of them.",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/DomainList"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or invalid API token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Plan does not include the API, or the QR code limit is reached.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "More than 120 requests per minute."
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "description": "API key from the account page \"API\". Starts with \"qr9_\"."
            }
        },
        "schemas": {
            "QrCode": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "description": "Random, stable id. Ids are strings, never numbers."
                    },
                    "name": {
                        "type": "string"
                    },
                    "type": {
                        "type": "string",
                        "enum": [
                            "dynamic",
                            "static"
                        ],
                        "description": "dynamic: the code holds a short link and the target can be changed later. static: the code holds the target itself and cannot be changed or tracked."
                    },
                    "content_type": {
                        "type": "string",
                        "enum": [
                            "url",
                            "vcard",
                            "wifi",
                            "sms",
                            "email",
                            "text"
                        ],
                        "description": "Codes created through the API are always \"url\"; the others come from the dashboard."
                    },
                    "target_url": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "slug": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "Null for static codes."
                    },
                    "short_url": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "The link encoded in a dynamic code. Null for static codes."
                    },
                    "client_id": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "custom_domain": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "scan_count": {
                        "type": "integer"
                    },
                    "expires_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                }
            },
            "QrCodeCreate": {
                "type": "object",
                "required": [
                    "name",
                    "target_url"
                ],
                "properties": {
                    "name": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Internal name, shown in the dashboard."
                    },
                    "target_url": {
                        "type": "string",
                        "format": "uri",
                        "maxLength": 2048,
                        "description": "Where a scan leads. http or https only. Checked against Google Safe Browsing."
                    },
                    "slug": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "minLength": 3,
                        "maxLength": 50,
                        "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
                        "description": "Readable end of the short link (/r/{slug}). Dynamic codes only. Input is normalised (\"Sommer Aktion\" becomes \"sommer-aktion\"). Must be globally unique. Omit to get a random one. Changing it keeps the former slug working."
                    },
                    "client_id": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "Id of one of your clients (see GET /clients)."
                    },
                    "expires_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date",
                        "description": "Last day the code works (Europe/Zurich). Null for no expiry."
                    },
                    "type": {
                        "type": "string",
                        "enum": [
                            "dynamic",
                            "static"
                        ],
                        "default": "dynamic"
                    },
                    "custom_domain_id": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "Id of a verified custom domain of the account (see GET /domains)."
                    },
                    "design": {
                        "type": "object",
                        "properties": {
                            "fg_color": {
                                "type": "string",
                                "description": "Hex colour of the dots, e.g. #000000."
                            },
                            "bg_color": {
                                "type": "string",
                                "description": "Hex colour of the background, e.g. #ffffff."
                            },
                            "dot_style": {
                                "type": "string",
                                "enum": [
                                    "square",
                                    "round"
                                ]
                            }
                        }
                    }
                }
            },
            "QrCodeUpdate": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Internal name, shown in the dashboard."
                    },
                    "target_url": {
                        "type": "string",
                        "format": "uri",
                        "maxLength": 2048,
                        "description": "Where a scan leads. http or https only. Checked against Google Safe Browsing."
                    },
                    "slug": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "minLength": 3,
                        "maxLength": 50,
                        "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
                        "description": "Readable end of the short link (/r/{slug}). Dynamic codes only. Input is normalised (\"Sommer Aktion\" becomes \"sommer-aktion\"). Must be globally unique. Omit to get a random one. Changing it keeps the former slug working."
                    },
                    "client_id": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "Id of one of your clients (see GET /clients)."
                    },
                    "expires_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date",
                        "description": "Last day the code works (Europe/Zurich). Null for no expiry."
                    }
                }
            },
            "QrCodeResponse": {
                "type": "object",
                "properties": {
                    "data": {
                        "$ref": "#/components/schemas/QrCode"
                    }
                }
            },
            "QrCodeList": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/QrCode"
                        }
                    },
                    "meta": {
                        "type": "object",
                        "properties": {
                            "current_page": {
                                "type": "integer"
                            },
                            "last_page": {
                                "type": "integer"
                            },
                            "per_page": {
                                "type": "integer"
                            },
                            "total": {
                                "type": "integer"
                            }
                        }
                    }
                }
            },
            "ScansResponse": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "total": {
                                "type": "integer",
                                "description": "All scans since the code was created."
                            },
                            "timezone": {
                                "type": "string"
                            },
                            "days": {
                                "type": "array",
                                "items": {
                                    "type": "object",
                                    "properties": {
                                        "date": {
                                            "type": "string",
                                            "format": "date"
                                        },
                                        "count": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "Client": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "company": {
                        "type": [
                            "string",
                            "null"
                        ]
                    }
                }
            },
            "ClientResponse": {
                "type": "object",
                "properties": {
                    "data": {
                        "$ref": "#/components/schemas/Client"
                    }
                }
            },
            "ClientList": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Client"
                        }
                    }
                }
            },
            "DomainList": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "string",
                                    "description": "Send as custom_domain_id when creating a QR code."
                                },
                                "domain": {
                                    "type": "string"
                                },
                                "client_id": {
                                    "type": [
                                        "string",
                                        "null"
                                    ],
                                    "description": "The client the domain belongs to, if any."
                                },
                                "verified": {
                                    "type": "boolean",
                                    "description": "Only verified domains can be used for QR codes."
                                },
                                "https": {
                                    "type": "boolean",
                                    "description": "True once the certificate is issued; until then short links use http."
                                }
                            }
                        }
                    }
                }
            },
            "Error": {
                "type": "object",
                "properties": {
                    "error": {
                        "type": "string",
                        "description": "Stable code: unauthenticated, plan_required, qr_limit_reached."
                    },
                    "message": {
                        "type": "string"
                    }
                }
            },
            "ValidationError": {
                "type": "object",
                "properties": {
                    "message": {
                        "type": "string"
                    },
                    "errors": {
                        "type": "object",
                        "description": "Messages per field, in German.",
                        "additionalProperties": {
                            "type": "array",
                            "items": {
                                "type": "string"
                            }
                        }
                    }
                }
            }
        }
    }
}