{
  "openapi": "3.1.0",
  "info": {
    "title": "PenBlitz API",
    "description": "Handwriting robot as a service: render previews, run mail merges with per-recipient text and QR codes, queue and monitor print jobs.\n\nPlaceholders: `{{name}}` or `{name}`, fallback `{{name:Text}}`, filters `|upper`, `|lower`, `|trim`, `|url`.\n\nAuthentication: if an API key is configured, send it as `X-API-Key` header (or `Authorization: Bearer <key>`).",
    "contact": {
      "name": "Steven Schulz"
    },
    "license": {
      "name": ""
    },
    "version": "0.2.0"
  },
  "paths": {
    "/api/v1/config": {
      "get": {
        "tags": [
          "system"
        ],
        "summary": "Current settings.",
        "operationId": "get_config",
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Config"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      },
      "put": {
        "tags": [
          "system"
        ],
        "summary": "Replace the settings. API bind/port changes take effect after a restart.\nSend `api.api_key` as `********` to keep the current key.",
        "operationId": "put_config",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Config"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Config"
                }
              }
            }
          },
          "400": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/api/v1/data/csv": {
      "post": {
        "tags": [
          "render"
        ],
        "summary": "Parse CSV text (`;`, `,` or tab separated, first line = column names) into\nrecords that can be passed to `POST /jobs`.",
        "operationId": "parse_csv",
        "requestBody": {
          "content": {
            "text/csv": {
              "schema": {
                "type": "string"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CsvResult"
                }
              }
            }
          },
          "400": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/api/v1/fonts": {
      "get": {
        "tags": [
          "system"
        ],
        "summary": "The fonts: built-in ones and imported handwriting (`own`).",
        "operationId": "fonts",
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/FontInfo"
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/api/v1/health": {
      "get": {
        "tags": [
          "system"
        ],
        "summary": "Liveness check (no authentication).",
        "operationId": "health",
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/jobs": {
      "get": {
        "tags": [
          "jobs"
        ],
        "summary": "List jobs, oldest first.",
        "operationId": "list_jobs",
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "description": "Filter: `open` (not finished), `finished`, or a state such as `printing`.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "external_id",
            "in": "query",
            "description": "Filter by the caller's reference.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/JobSummary"
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      },
      "post": {
        "tags": [
          "jobs"
        ],
        "summary": "Create a job. One sheet per record (times `copies`); placeholders in text\nand QR codes are filled per record. The job is queued immediately unless\n`scheduled_at` lies in the future.",
        "operationId": "create_job",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JobRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "400": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/api/v1/jobs/{id}": {
      "get": {
        "tags": [
          "jobs"
        ],
        "summary": "One job with all pages.",
        "operationId": "get_job",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Job id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "404": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      },
      "delete": {
        "tags": [
          "jobs"
        ],
        "summary": "Delete a job that is not printing.",
        "operationId": "delete_job",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Job id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": ""
          },
          "404": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/api/v1/jobs/{id}/cancel": {
      "post": {
        "tags": [
          "jobs"
        ],
        "summary": "Cancel a job. A printing job stops and the pen is lifted.",
        "operationId": "cancel_job",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Job id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobSummary"
                }
              }
            }
          },
          "404": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/api/v1/jobs/{id}/pages/{page}/preview.svg": {
      "get": {
        "tags": [
          "jobs"
        ],
        "summary": "SVG preview of one page of a job (0-based page number).",
        "operationId": "job_page_svg",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Job id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "path",
            "description": "Page index, starting at 0",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "image/svg+xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/api/v1/jobs/{id}/pause": {
      "post": {
        "tags": [
          "jobs"
        ],
        "summary": "Pause a job (a printing job pauses after the current page).",
        "operationId": "pause_job",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Job id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobSummary"
                }
              }
            }
          },
          "404": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/api/v1/jobs/{id}/resume": {
      "post": {
        "tags": [
          "jobs"
        ],
        "summary": "Continue a paused job, confirm the paper change, or retry a failed or\ncancelled job from the first unprinted page.",
        "operationId": "resume_job",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Job id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobSummary"
                }
              }
            }
          },
          "404": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/api/v1/orders": {
      "post": {
        "tags": [
          "orders"
        ],
        "summary": "Create an order: one handwritten piece for one recipient.",
        "operationId": "create_order",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NewOrder"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Order with this external_id already exists",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "201": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "400": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/api/v1/orders/{id}": {
      "get": {
        "tags": [
          "orders"
        ],
        "summary": "Order status. `id` may be the order id or your `external_id`.",
        "operationId": "get_order",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Order id or external_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "404": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      },
      "delete": {
        "tags": [
          "orders"
        ],
        "summary": "Cancel an order that has not been written yet.",
        "operationId": "cancel_order",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Order id or external_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "404": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/api/v1/page-presets": {
      "get": {
        "tags": [
          "system"
        ],
        "summary": "Paper format presets.",
        "operationId": "page_presets",
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/PagePreset"
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/api/v1/printer": {
      "get": {
        "tags": [
          "printer"
        ],
        "summary": "Printer state (online, idle/printing/error).",
        "operationId": "printer_status",
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrinterStatus"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/api/v1/printer/eject": {
      "post": {
        "tags": [
          "printer"
        ],
        "summary": "Lift the pen, park and eject the sheet.",
        "operationId": "printer_eject",
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Done"
                }
              }
            }
          },
          "409": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "502": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/api/v1/printer/feed": {
      "post": {
        "tags": [
          "printer"
        ],
        "summary": "Pull one sheet from the tray (`M998`).",
        "operationId": "printer_feed",
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Done"
                }
              }
            }
          },
          "409": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "502": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/api/v1/printer/pen": {
      "post": {
        "tags": [
          "printer"
        ],
        "summary": "Move the pen holder: `install` lowers it for a pen change, `up` lifts it again.",
        "operationId": "printer_pen",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PenRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Done"
                }
              }
            }
          },
          "409": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "502": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/api/v1/printer/settings": {
      "get": {
        "tags": [
          "printer"
        ],
        "summary": "Settings reported by the printer's WiFi module (feed rate, offsets, WiFi, ...).",
        "operationId": "printer_settings",
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": {
                    "type": "string"
                  },
                  "propertyNames": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "502": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/api/v1/printer/stop": {
      "post": {
        "tags": [
          "printer"
        ],
        "summary": "Emergency stop: cancels the printing job (if any), stops the printer and lifts the pen.",
        "operationId": "printer_stop",
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Done"
                }
              }
            }
          },
          "502": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/api/v1/products": {
      "get": {
        "tags": [
          "orders"
        ],
        "summary": "Products that can be ordered.",
        "operationId": "list_products",
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Product"
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/api/v1/queue": {
      "get": {
        "tags": [
          "jobs"
        ],
        "summary": "Queue overview.",
        "operationId": "get_queue",
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueueInfo"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/api/v1/queue/clear-finished": {
      "post": {
        "tags": [
          "jobs"
        ],
        "summary": "Remove all finished, failed and cancelled jobs from the list.",
        "operationId": "clear_finished",
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Done"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/api/v1/queue/pause": {
      "post": {
        "tags": [
          "jobs"
        ],
        "summary": "Hold the whole queue: no new page starts (the current page finishes).",
        "operationId": "pause_queue",
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueueInfo"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/api/v1/queue/resume": {
      "post": {
        "tags": [
          "jobs"
        ],
        "summary": "Release the queue.",
        "operationId": "resume_queue",
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueueInfo"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/api/v1/render": {
      "post": {
        "tags": [
          "render"
        ],
        "summary": "Render a preview without printing: SVG, warnings, statistics, optional G-code.",
        "operationId": "render_preview",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RenderRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RenderResponse"
                }
              }
            }
          },
          "400": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/api/v1/render/svg": {
      "post": {
        "tags": [
          "render"
        ],
        "summary": "Same as `/render`, but returns the SVG image directly.",
        "operationId": "render_svg",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RenderRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "image/svg+xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/api/v1/templates": {
      "get": {
        "tags": [
          "templates"
        ],
        "summary": "List stored templates.",
        "operationId": "list_templates",
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Template"
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      },
      "post": {
        "tags": [
          "templates"
        ],
        "summary": "Create a template.",
        "operationId": "create_template",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TemplateInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Template"
                }
              }
            }
          },
          "400": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/api/v1/templates/{id}": {
      "get": {
        "tags": [
          "templates"
        ],
        "summary": "One template.",
        "operationId": "get_template",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Template id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Template"
                }
              }
            }
          },
          "404": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      },
      "put": {
        "tags": [
          "templates"
        ],
        "summary": "Replace a template (creates it if missing).",
        "operationId": "put_template",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Template id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TemplateInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Template"
                }
              }
            }
          },
          "400": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      },
      "delete": {
        "tags": [
          "templates"
        ],
        "summary": "Delete a template.",
        "operationId": "delete_template",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Template id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": ""
          },
          "404": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/api/v1/templates/{id}/variables": {
      "get": {
        "tags": [
          "templates"
        ],
        "summary": "Placeholders used by a template.",
        "operationId": "template_variables",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Template id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Variables"
                }
              }
            }
          },
          "404": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "Align": {
        "type": "string",
        "enum": [
          "left",
          "center",
          "right"
        ]
      },
      "ApiConfig": {
        "type": "object",
        "properties": {
          "api_key": {
            "type": "string",
            "description": "If set, requests must send it as `X-API-Key` or `Authorization: Bearer`.",
            "default": ""
          },
          "bind": {
            "type": "string",
            "description": "Listen address. `127.0.0.1` = this computer only, `0.0.0.0` = whole network.",
            "default": "127.0.0.1"
          },
          "enabled": {
            "type": "boolean",
            "default": true
          },
          "port": {
            "type": "integer",
            "format": "int32",
            "default": 8787,
            "minimum": 0
          }
        }
      },
      "ApiError": {
        "type": "object",
        "description": "Error body of every failed request.",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Human readable message."
          }
        }
      },
      "BTreeMap": {
        "type": "object",
        "additionalProperties": {
          "type": "string"
        },
        "propertyNames": {
          "type": "string"
        }
      },
      "Block": {
        "oneOf": [
          {
            "allOf": [
              {
                "$ref": "#/components/schemas/TextBlock"
              },
              {
                "type": "object",
                "required": [
                  "type"
                ],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "text"
                    ]
                  }
                }
              }
            ]
          },
          {
            "allOf": [
              {
                "$ref": "#/components/schemas/QrBlock"
              },
              {
                "type": "object",
                "required": [
                  "type"
                ],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "qr"
                    ]
                  }
                }
              }
            ]
          },
          {
            "allOf": [
              {
                "$ref": "#/components/schemas/SpacerBlock"
              },
              {
                "type": "object",
                "required": [
                  "type"
                ],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "spacer"
                    ]
                  }
                }
              }
            ]
          },
          {
            "allOf": [
              {
                "$ref": "#/components/schemas/LineBlock"
              },
              {
                "type": "object",
                "required": [
                  "type"
                ],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "line"
                    ]
                  }
                }
              }
            ]
          },
          {
            "allOf": [
              {
                "$ref": "#/components/schemas/SvgBlock"
              },
              {
                "type": "object",
                "required": [
                  "type"
                ],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "svg"
                    ]
                  }
                }
              }
            ]
          }
        ]
      },
      "Config": {
        "type": "object",
        "properties": {
          "api": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/ApiConfig"
              }
            ],
            "default": {
              "enabled": true,
              "bind": "127.0.0.1",
              "port": 8787,
              "api_key": ""
            }
          },
          "language": {
            "type": "string",
            "description": "Language of the app: `auto` (system language) or a code such as `en` or `de`.",
            "default": "auto"
          },
          "machine": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/MachineConfig"
              }
            ],
            "default": {
              "origin_x": -10.0,
              "origin_y": -56.0,
              "pen_up": 0.0,
              "pen_down": 8.0,
              "pen_install": 7.0,
              "pen_width_mm": 0.30000001192092896,
              "feed_travel": 6000,
              "feed_draw": 5000,
              "feed_pen": 4000,
              "x_scale": 1.0,
              "y_scale": 1.0,
              "x_offset_mm": 0.0,
              "y_offset_mm": 0.0,
              "eject": true,
              "park_x": 290.0,
              "eject_y": 500.0
            }
          },
          "mcp": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/McpConfig",
                "description": "AI assistants connected through the MCP server."
              }
            ],
            "default": {
              "direct_print": false
            }
          },
          "printer": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/PrinterConfig"
              }
            ],
            "default": {
              "host": "192.168.178.38",
              "tcp_port": 9000,
              "http_port": 80,
              "mode": "upload",
              "remote_file": "/penblitz",
              "feed_before_print": false,
              "serial_port": "",
              "serial_baud": 250000,
              "start_timeout_s": 90,
              "page_timeout_s": 3600,
              "pause_between_pages_s": 4
            }
          },
          "theme": {
            "type": "string",
            "description": "Appearance of the app: `auto` (follow the system), `light` or `dark`.",
            "default": "auto"
          }
        }
      },
      "CsvResult": {
        "type": "object",
        "required": [
          "headers",
          "records"
        ],
        "properties": {
          "headers": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "records": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BTreeMap"
            }
          }
        }
      },
      "Document": {
        "type": "object",
        "description": "A printable document (one sheet).",
        "properties": {
          "blocks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Block"
            },
            "default": [
              {
                "type": "text",
                "text": "",
                "font": "cursive",
                "size_mm": 6.0,
                "line_height": 1.649999976158142,
                "paragraph_gap": 0.8999999761581421,
                "letter_spacing_mm": 0.0,
                "word_spacing": 1.0,
                "align": "left"
              }
            ]
          },
          "humanize": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Humanize",
                "description": "Default handwriting settings for all text blocks."
              }
            ],
            "default": {
              "enabled": true,
              "intensity": 1.0,
              "bold_prob": 0.30000001192092896,
              "line_spacing_jitter": 0.029999999329447746,
              "left_gap_jitter_mm": 0.6000000238418579,
              "word_space_jitter": 0.11999999731779099,
              "page_offset_jitter_mm": 1.0
            }
          },
          "name": {
            "type": "string",
            "default": "Untitled"
          },
          "page": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Page"
              }
            ],
            "default": {
              "width_mm": 210.0,
              "height_mm": 297.0,
              "margin_left": 22.0,
              "margin_right": 22.0,
              "margin_top": 26.0,
              "margin_bottom": 22.0,
              "rotate": 0,
              "postal_zones": true
            }
          }
        }
      },
      "Done": {
        "type": "object",
        "required": [
          "ok",
          "message"
        ],
        "properties": {
          "message": {
            "type": "string"
          },
          "ok": {
            "type": "boolean"
          }
        }
      },
      "FontInfo": {
        "type": "object",
        "description": "Description of a font, as reported by the API.",
        "required": [
          "id",
          "name",
          "style"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier used in documents (`font` field)."
          },
          "name": {
            "type": "string",
            "description": "Human readable name."
          },
          "own": {
            "type": "boolean",
            "description": "True for a font the user imported (their own handwriting)."
          },
          "style": {
            "type": "string",
            "description": "`handwriting` or `print`."
          }
        }
      },
      "Health": {
        "type": "object",
        "required": [
          "status",
          "version",
          "open_jobs",
          "queue_paused"
        ],
        "properties": {
          "open_jobs": {
            "type": "integer",
            "description": "Number of jobs that are not finished yet.",
            "minimum": 0
          },
          "queue_paused": {
            "type": "boolean"
          },
          "status": {
            "type": "string"
          },
          "version": {
            "type": "string"
          }
        }
      },
      "Humanize": {
        "type": "object",
        "description": "Handwriting variation. `intensity` scales jitter, rotation, glyph warp and\npen tremble together; the other fields tune individual effects.",
        "properties": {
          "bold_prob": {
            "type": "number",
            "format": "float",
            "description": "Probability (0..1) that a letter is traced twice and looks bolder.",
            "default": 0.30000001192092896
          },
          "enabled": {
            "type": "boolean",
            "default": true
          },
          "intensity": {
            "type": "number",
            "format": "float",
            "description": "0 = perfectly regular, 1 = natural (default), 2 = shaky.",
            "default": 1.0
          },
          "left_gap_jitter_mm": {
            "type": "number",
            "format": "float",
            "description": "Random extra indent at the start of each line, in mm.",
            "default": 0.6000000238418579
          },
          "line_spacing_jitter": {
            "type": "number",
            "format": "float",
            "description": "Random variation of the line distance, as a fraction (0.05 = +-5 %).",
            "default": 0.029999999329447746
          },
          "page_offset_jitter_mm": {
            "type": "number",
            "format": "float",
            "description": "Every sheet is shifted as a whole by a random amount of up to this many mm in each\ndirection, so the sheets of a batch do not line up exactly. Document level only.",
            "default": 1.0
          },
          "word_space_jitter": {
            "type": "number",
            "format": "float",
            "description": "Random variation of word gaps, as a fraction.",
            "default": 0.11999999731779099
          }
        }
      },
      "Job": {
        "type": "object",
        "description": "A print job with all its data.",
        "required": [
          "id",
          "name",
          "state",
          "created_at",
          "documents",
          "pages",
          "seed"
        ],
        "properties": {
          "callback_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "URL that receives a `POST` with the job summary whenever the job\nfinishes, fails or is cancelled."
          },
          "confirm_each_page": {
            "type": "boolean",
            "description": "Stop after every page and wait for `resume` (manual paper feeding)."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "documents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Document"
            },
            "description": "Main document followed by additional documents (e.g. an envelope)."
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          },
          "external_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Caller's own reference (e.g. order number of another system)."
          },
          "finished_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "id": {
            "type": "string"
          },
          "meta": {
            "type": "object",
            "description": "Free-form metadata of the caller.",
            "additionalProperties": {
              "type": "string"
            },
            "propertyNames": {
              "type": "string"
            }
          },
          "name": {
            "type": "string"
          },
          "note": {
            "type": "string",
            "description": "What the printer is doing right now."
          },
          "page_progress": {
            "type": "number",
            "format": "float",
            "description": "Progress of the page currently printing, 0..1."
          },
          "pages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PageInfo"
            }
          },
          "scheduled_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "seed": {
            "type": "integer",
            "format": "int64",
            "description": "Base seed of the handwriting variation; every page derives its own.",
            "minimum": 0
          },
          "started_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "state": {
            "$ref": "#/components/schemas/JobState"
          }
        }
      },
      "JobRequest": {
        "allOf": [
          {
            "$ref": "#/components/schemas/NewJob"
          },
          {
            "type": "object",
            "properties": {
              "csv": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Mail-merge data as CSV text (alternative to `records`)."
              }
            }
          }
        ],
        "description": "Create a print job (single sheet or mail merge)."
      },
      "JobState": {
        "type": "string",
        "enum": [
          "scheduled",
          "queued",
          "printing",
          "paused",
          "waiting_for_paper",
          "done",
          "failed",
          "canceled"
        ]
      },
      "JobSummary": {
        "type": "object",
        "description": "Compact view of a job (lists, webhooks).",
        "required": [
          "id",
          "name",
          "state",
          "created_at",
          "pages_total",
          "pages_done",
          "progress",
          "remaining_s",
          "note",
          "warnings",
          "meta"
        ],
        "properties": {
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          },
          "external_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "finished_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "id": {
            "type": "string"
          },
          "meta": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "propertyNames": {
              "type": "string"
            }
          },
          "name": {
            "type": "string"
          },
          "note": {
            "type": "string"
          },
          "pages_done": {
            "type": "integer",
            "minimum": 0
          },
          "pages_total": {
            "type": "integer",
            "minimum": 0
          },
          "progress": {
            "type": "number",
            "format": "float",
            "description": "Overall progress 0..1."
          },
          "remaining_s": {
            "type": "number",
            "format": "float",
            "description": "Estimated remaining seconds."
          },
          "scheduled_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "started_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "state": {
            "$ref": "#/components/schemas/JobState"
          },
          "warnings": {
            "type": "integer",
            "description": "Number of render warnings across all pages.",
            "minimum": 0
          }
        }
      },
      "LineBlock": {
        "type": "object",
        "description": "A straight line in absolute page coordinates (e.g. a signature rule).",
        "required": [
          "x1_mm",
          "y1_mm",
          "x2_mm",
          "y2_mm"
        ],
        "properties": {
          "x1_mm": {
            "type": "number",
            "format": "float"
          },
          "x2_mm": {
            "type": "number",
            "format": "float"
          },
          "y1_mm": {
            "type": "number",
            "format": "float"
          },
          "y2_mm": {
            "type": "number",
            "format": "float"
          }
        }
      },
      "MachineConfig": {
        "type": "object",
        "description": "Machine geometry and motion parameters (K_AT firmware).",
        "properties": {
          "eject": {
            "type": "boolean",
            "description": "Park the pen and push the sheet out at the end of a page.",
            "default": true
          },
          "eject_y": {
            "type": "number",
            "format": "float",
            "default": 500.0
          },
          "feed_draw": {
            "type": "integer",
            "format": "int32",
            "default": 5000,
            "minimum": 0
          },
          "feed_pen": {
            "type": "integer",
            "format": "int32",
            "default": 4000,
            "minimum": 0
          },
          "feed_travel": {
            "type": "integer",
            "format": "int32",
            "description": "Feed rates in mm/min.",
            "default": 6000,
            "minimum": 0
          },
          "origin_x": {
            "type": "number",
            "format": "float",
            "description": "`G92` origin used in stream mode (matches the firmware's M1102 offset).",
            "default": -10.0
          },
          "origin_y": {
            "type": "number",
            "format": "float",
            "default": -56.0
          },
          "park_x": {
            "type": "number",
            "format": "float",
            "default": 290.0
          },
          "pen_down": {
            "type": "number",
            "format": "float",
            "default": 8.0
          },
          "pen_install": {
            "type": "number",
            "format": "float",
            "description": "Pen axis position for inserting a pen: the holder is lowered so the tip can rest on the paper.",
            "default": 7.0
          },
          "pen_up": {
            "type": "number",
            "format": "float",
            "description": "Pen axis (E) positions.",
            "default": 0.0
          },
          "pen_width_mm": {
            "type": "number",
            "format": "float",
            "description": "Width of the line the pen draws, in mm (fine pen 0.3, felt tip 0.6 – 1.0).",
            "default": 0.30000001192092896
          },
          "x_offset_mm": {
            "type": "number",
            "format": "float",
            "default": 0.0
          },
          "x_scale": {
            "type": "number",
            "format": "float",
            "description": "Calibration: scale and shift applied to all coordinates.",
            "default": 1.0
          },
          "y_offset_mm": {
            "type": "number",
            "format": "float",
            "default": 0.0
          },
          "y_scale": {
            "type": "number",
            "format": "float",
            "default": 1.0
          }
        }
      },
      "McpConfig": {
        "type": "object",
        "description": "What AI assistants may do through `penblitz-server mcp`.",
        "properties": {
          "direct_print": {
            "type": "boolean",
            "description": "Assistants may start printing by themselves. Off (default): their jobs\nwait in the app until a person approves them.",
            "default": false
          }
        }
      },
      "NewJob": {
        "type": "object",
        "description": "Request to create a job.",
        "properties": {
          "additional_documents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Document"
            },
            "description": "Further documents printed after the main one for every record\n(e.g. the matching envelope)."
          },
          "additional_template_ids": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Stored templates appended to `additional_documents`."
          },
          "callback_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "confirm_each_page": {
            "type": "boolean"
          },
          "copies": {
            "type": "integer",
            "format": "int32",
            "description": "Copies per record.",
            "minimum": 0
          },
          "document": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Document",
                "description": "Inline document (ignored when `template_id` is set)."
              }
            ]
          },
          "external_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "hold": {
            "type": "boolean",
            "description": "Do not print until a person approves the job in the app (used for jobs from AI assistants)."
          },
          "meta": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "propertyNames": {
              "type": "string"
            }
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Display name. Defaults to the document name."
          },
          "records": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BTreeMap"
            },
            "description": "Mail-merge data: one sheet per record. Empty = a single sheet."
          },
          "scheduled_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Do not start before this time."
          },
          "seed": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Fixed seed for reproducible handwriting. Random if omitted.",
            "minimum": 0
          },
          "strict": {
            "type": "boolean",
            "description": "Reject the job if a placeholder has no value in some record."
          },
          "strict_layout": {
            "type": "boolean",
            "description": "Reject the job if a sheet draws outside the page margins or into an area the post office needs free."
          },
          "template_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Use a stored template instead of an inline `document`."
          }
        }
      },
      "NewOrder": {
        "type": "object",
        "description": "A simple \"write this text for this person\" order, as used by shop or CRM\nintegrations.",
        "required": [
          "text"
        ],
        "properties": {
          "callback_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "Receives a `POST` when the order is printed, failed or cancelled."
          },
          "external_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Your own order number. Sending the same `external_id` again returns\nthe existing order instead of printing twice."
          },
          "product": {
            "type": "string",
            "description": "`postcard`, `letter` or `card` (see `GET /products`)."
          },
          "qr_data": {
            "type": [
              "string",
              "null"
            ],
            "description": "Add an individual QR code below the text (placeholders allowed)."
          },
          "recipient": {
            "$ref": "#/components/schemas/Recipient"
          },
          "scheduled_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "template_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Use this template instead of the product's default."
          },
          "text": {
            "type": "string",
            "description": "The finished text. May still contain placeholders that are filled\nfrom `variables`."
          },
          "variables": {
            "$ref": "#/components/schemas/BTreeMap",
            "description": "Extra placeholder values (e.g. `sender`, `code`)."
          },
          "with_envelope": {
            "type": "boolean",
            "description": "Also write a DL envelope with the recipient's address."
          }
        }
      },
      "Order": {
        "type": "object",
        "required": [
          "id",
          "status",
          "job"
        ],
        "properties": {
          "external_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "id": {
            "type": "string",
            "description": "Order id (identical to the job id)."
          },
          "job": {
            "$ref": "#/components/schemas/JobSummary"
          },
          "status": {
            "type": "string",
            "description": "`pending` (scheduled), `queued` (waiting or printing), `sent`\n(written), `failed` or `canceled`."
          }
        }
      },
      "Page": {
        "type": "object",
        "description": "Paper format and margins, all in millimetres.",
        "properties": {
          "height_mm": {
            "type": "number",
            "format": "float",
            "default": 297.0
          },
          "margin_bottom": {
            "type": "number",
            "format": "float",
            "default": 22.0
          },
          "margin_left": {
            "type": "number",
            "format": "float",
            "default": 22.0
          },
          "margin_right": {
            "type": "number",
            "format": "float",
            "default": 22.0
          },
          "margin_top": {
            "type": "number",
            "format": "float",
            "default": 26.0
          },
          "postal_zones": {
            "type": "boolean",
            "description": "Keep the areas free that the post office reserves on cards and standard letters\n(stamp area, sorting-code strip, right edge). Only matters for those formats.",
            "default": true
          },
          "rotate": {
            "type": "integer",
            "format": "int32",
            "description": "Rotate the finished drawing on the sheet: 0, 90, 180 or 270 degrees.",
            "default": 0,
            "minimum": 0
          },
          "width_mm": {
            "type": "number",
            "format": "float",
            "default": 210.0
          }
        }
      },
      "PageInfo": {
        "type": "object",
        "description": "One sheet of a job.",
        "required": [
          "index",
          "document",
          "record_index",
          "state",
          "record",
          "estimate_s"
        ],
        "properties": {
          "document": {
            "type": "integer",
            "description": "Which of the job's documents this sheet uses (0 = main document).",
            "minimum": 0
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          },
          "estimate_s": {
            "type": "number",
            "format": "float",
            "description": "Estimated printing time in seconds."
          },
          "index": {
            "type": "integer",
            "minimum": 0
          },
          "record": {
            "$ref": "#/components/schemas/BTreeMap",
            "description": "Placeholder values for this sheet."
          },
          "record_index": {
            "type": "integer",
            "description": "Index of the data record this sheet was generated from.",
            "minimum": 0
          },
          "seconds": {
            "type": [
              "number",
              "null"
            ],
            "format": "float",
            "description": "Measured printing time in seconds, once printed."
          },
          "state": {
            "$ref": "#/components/schemas/PageState"
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Problems found while rendering (missing placeholders, overflow, ...)."
          }
        }
      },
      "PagePreset": {
        "type": "object",
        "required": [
          "id",
          "name",
          "page"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "page": {
            "$ref": "#/components/schemas/Page"
          }
        }
      },
      "PageState": {
        "type": "string",
        "enum": [
          "pending",
          "printing",
          "done",
          "failed"
        ]
      },
      "PenPosition": {
        "type": "string",
        "description": "Where to move the pen holder (pen axis E).",
        "enum": [
          "up",
          "down",
          "install"
        ]
      },
      "PenRequest": {
        "type": "object",
        "required": [
          "position"
        ],
        "properties": {
          "position": {
            "$ref": "#/components/schemas/PenPosition",
            "description": "`install` = pen change position, `up` = lifted, `down` = writing height."
          }
        }
      },
      "PrinterConfig": {
        "type": "object",
        "properties": {
          "feed_before_print": {
            "type": "boolean",
            "description": "Send `M998` (pull a sheet from the tray) before each page.",
            "default": false
          },
          "host": {
            "type": "string",
            "description": "IP address or host name of the plotter's WiFi module.",
            "default": "192.168.178.38"
          },
          "http_port": {
            "type": "integer",
            "format": "int32",
            "description": "HTTP port of the upload endpoint.",
            "default": 80,
            "minimum": 0
          },
          "mode": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/TransportMode"
              }
            ],
            "default": "upload"
          },
          "page_timeout_s": {
            "type": "integer",
            "format": "int32",
            "description": "Hard limit per page in seconds.",
            "default": 3600,
            "minimum": 0
          },
          "pause_between_pages_s": {
            "type": "integer",
            "format": "int32",
            "description": "Pause between two pages of a batch, in seconds.",
            "default": 4,
            "minimum": 0
          },
          "remote_file": {
            "type": "string",
            "description": "File name used in the printer's memory (upload mode).",
            "default": "/penblitz"
          },
          "serial_baud": {
            "type": "integer",
            "format": "int32",
            "description": "Baud rate of the serial port (K_AT firmware: 250000).",
            "default": 250000,
            "minimum": 0
          },
          "serial_port": {
            "type": "string",
            "description": "Serial device for USB mode, e.g. `/dev/cu.usbserial-120`; empty = find it automatically.",
            "default": ""
          },
          "start_timeout_s": {
            "type": "integer",
            "format": "int32",
            "description": "Seconds to wait for the printer to start a page before failing.",
            "default": 90,
            "minimum": 0
          },
          "tcp_port": {
            "type": "integer",
            "format": "int32",
            "description": "TCP port of the G-code / `[ESP…]` command channel.",
            "default": 9000,
            "minimum": 0
          }
        }
      },
      "PrinterStatus": {
        "type": "object",
        "description": "Snapshot of the printer state.",
        "required": [
          "online",
          "state",
          "message"
        ],
        "properties": {
          "code": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "Raw status code from the heartbeat (1 idle, 2 printing, 3 no paper, 5 busy, 6 error)."
          },
          "file": {
            "type": [
              "string",
              "null"
            ],
            "description": "File currently being printed, if any."
          },
          "message": {
            "type": "string",
            "description": "Extra information (error text, firmware line, ...)."
          },
          "online": {
            "type": "boolean"
          },
          "state": {
            "type": "string",
            "description": "`idle`, `printing`, `no_paper`, `busy`, `error`, `offline`, `mock` or `unknown`."
          }
        }
      },
      "Product": {
        "type": "object",
        "description": "A product that can be ordered (maps to a stored template).",
        "required": [
          "id",
          "name",
          "description",
          "template_id"
        ],
        "properties": {
          "description": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "template_id": {
            "type": "string",
            "description": "Template used for this product; edit it to change the layout."
          }
        }
      },
      "QrBlock": {
        "type": "object",
        "description": "A QR code drawn with pen hatching. `data` may contain placeholders, so\nevery letter of a mail merge can carry its own code.",
        "required": [
          "data"
        ],
        "properties": {
          "align": {
            "$ref": "#/components/schemas/Align"
          },
          "caption": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional text written below the code (placeholders allowed)."
          },
          "caption_size_mm": {
            "type": "number",
            "format": "float"
          },
          "data": {
            "type": "string"
          },
          "ec": {
            "type": "string",
            "description": "Error correction: `l`, `m`, `q` or `h`."
          },
          "module_mm": {
            "type": "number",
            "format": "float",
            "description": "Size of one QR module in mm (1.0 – 1.5 scans reliably with a fine pen)."
          },
          "x_mm": {
            "type": [
              "number",
              "null"
            ],
            "format": "float"
          },
          "y_mm": {
            "type": [
              "number",
              "null"
            ],
            "format": "float"
          }
        }
      },
      "QueueInfo": {
        "type": "object",
        "required": [
          "paused",
          "open_jobs",
          "remaining_s"
        ],
        "properties": {
          "open_jobs": {
            "type": "integer",
            "minimum": 0
          },
          "paused": {
            "type": "boolean"
          },
          "remaining_s": {
            "type": "number",
            "format": "float",
            "description": "Estimated remaining printing time of all open jobs in seconds."
          }
        }
      },
      "Recipient": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string"
          },
          "country": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "postal_code": {
            "type": "string"
          },
          "street": {
            "type": "string"
          }
        }
      },
      "RenderRequest": {
        "type": "object",
        "description": "What to render: a stored template or an inline document, filled with one record.",
        "properties": {
          "document": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Document"
              }
            ]
          },
          "include_gcode": {
            "type": "boolean",
            "description": "Include the G-code program (upload format) in the response."
          },
          "record": {
            "$ref": "#/components/schemas/BTreeMap",
            "description": "Placeholder values."
          },
          "seed": {
            "type": "integer",
            "format": "int64",
            "description": "Seed of the handwriting variation (same seed = same result).",
            "minimum": 0
          },
          "template_id": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "RenderResponse": {
        "type": "object",
        "required": [
          "svg",
          "warnings",
          "missing",
          "variables",
          "stats"
        ],
        "properties": {
          "gcode": {
            "type": [
              "string",
              "null"
            ]
          },
          "missing": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Placeholders without a value."
          },
          "stats": {
            "$ref": "#/components/schemas/Stats"
          },
          "svg": {
            "type": "string",
            "description": "SVG preview of the sheet."
          },
          "variables": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "All placeholders the document uses."
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "SpacerBlock": {
        "type": "object",
        "description": "Vertical gap in the block flow.",
        "required": [
          "height_mm"
        ],
        "properties": {
          "height_mm": {
            "type": "number",
            "format": "float"
          }
        }
      },
      "Stats": {
        "type": "object",
        "description": "Drawing statistics of a page.",
        "required": [
          "strokes",
          "draw_mm",
          "travel_mm",
          "seconds"
        ],
        "properties": {
          "draw_mm": {
            "type": "number",
            "format": "float",
            "description": "Ink path length in mm."
          },
          "seconds": {
            "type": "number",
            "format": "float",
            "description": "Rough duration estimate in seconds."
          },
          "strokes": {
            "type": "integer",
            "description": "Number of pen-down strokes after merging.",
            "minimum": 0
          },
          "travel_mm": {
            "type": "number",
            "format": "float",
            "description": "Pen-up travel in mm."
          }
        }
      },
      "SvgBlock": {
        "type": "object",
        "description": "A line drawing from an SVG file (logo, letterhead, traced signature).\nThe pen follows the outlines; fills are ignored.",
        "required": [
          "svg"
        ],
        "properties": {
          "align": {
            "$ref": "#/components/schemas/Align"
          },
          "svg": {
            "type": "string",
            "description": "SVG source text."
          },
          "variants": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "More versions of the same drawing (e.g. several signatures). Every\nsheet gets one of them, `svg` included, picked at random."
          },
          "width_mm": {
            "type": "number",
            "format": "float",
            "description": "Width of the drawing on paper; the height follows the aspect ratio."
          },
          "x_mm": {
            "type": [
              "number",
              "null"
            ],
            "format": "float"
          },
          "y_mm": {
            "type": [
              "number",
              "null"
            ],
            "format": "float"
          }
        }
      },
      "Template": {
        "type": "object",
        "description": "A stored, reusable document.",
        "required": [
          "id",
          "name",
          "document",
          "updated_at"
        ],
        "properties": {
          "description": {
            "type": "string"
          },
          "document": {
            "$ref": "#/components/schemas/Document"
          },
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "TemplateInput": {
        "type": "object",
        "description": "Data for creating or replacing a template.",
        "required": [
          "name",
          "document"
        ],
        "properties": {
          "description": {
            "type": "string"
          },
          "document": {
            "$ref": "#/components/schemas/Document"
          },
          "id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional fixed id when creating (letters, digits, `-`, `_`)."
          },
          "name": {
            "type": "string"
          }
        }
      },
      "TextBlock": {
        "type": "object",
        "description": "A block of (wrapped) text. Text may contain placeholders such as\n`{{first_name}}` or `{first_name}`.",
        "required": [
          "text"
        ],
        "properties": {
          "align": {
            "$ref": "#/components/schemas/Align"
          },
          "font": {
            "type": "string",
            "description": "Font id, see `GET /api/v1/fonts`."
          },
          "humanize": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Humanize",
                "description": "Per-block handwriting settings. Omit to use the document default."
              }
            ]
          },
          "letter_spacing_mm": {
            "type": "number",
            "format": "float",
            "description": "Extra space between letters in mm (may be negative)."
          },
          "line_height": {
            "type": "number",
            "format": "float",
            "description": "Line distance as a multiple of `size_mm`."
          },
          "mix_fonts": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Additional fonts mixed in randomly per letter (old-app \"mixed fonts\")."
          },
          "paragraph_gap": {
            "type": "number",
            "format": "float",
            "description": "Extra gap between paragraphs (blank line) as a multiple of `size_mm`."
          },
          "shrink_to_fit": {
            "type": "boolean",
            "description": "Write smaller, down to 60 % of `size_mm`, if the text would otherwise leave its\ncolumn or run into the bottom of the sheet (e.g. a long address)."
          },
          "size_mm": {
            "type": "number",
            "format": "float",
            "description": "Height of capital letters in mm."
          },
          "text": {
            "type": "string"
          },
          "width_mm": {
            "type": [
              "number",
              "null"
            ],
            "format": "float",
            "description": "Width of the text column in mm. Omit to use the page content width."
          },
          "word_spacing": {
            "type": "number",
            "format": "float",
            "description": "Word gap as a multiple of the font's natural space."
          },
          "x_mm": {
            "type": [
              "number",
              "null"
            ],
            "format": "float",
            "description": "Absolute left edge in mm. Omit to use the page margin."
          },
          "y_mm": {
            "type": [
              "number",
              "null"
            ],
            "format": "float",
            "description": "Absolute top edge in mm. Omit to continue below the previous block."
          }
        }
      },
      "TransportMode": {
        "type": "string",
        "description": "How a page gets to the plotter.",
        "enum": [
          "upload",
          "stream",
          "usb",
          "mock"
        ]
      },
      "Variables": {
        "type": "object",
        "required": [
          "variables"
        ],
        "properties": {
          "variables": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "api_key": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  },
  "tags": [
    {
      "name": "orders",
      "description": "Simple order facade for shop/CRM integrations"
    },
    {
      "name": "jobs",
      "description": "Print jobs and mail merge"
    },
    {
      "name": "templates",
      "description": "Stored documents with placeholders"
    },
    {
      "name": "render",
      "description": "Previews without printing"
    },
    {
      "name": "printer",
      "description": "Direct printer control"
    },
    {
      "name": "system",
      "description": "Health, settings, fonts"
    }
  ]
}
