Synthesis

Synthesis takes raw, hand-written legacy ZPL and produces a clean Template draft: a tidied body with placeholders, a Field Map that names them, sample Values, and a confidence score telling you how much to trust the result.

What#

The analogy: synthesis is like handing a messy, marked-up paper form to an assistant and getting back a clean fill-in-the-blanks template — with the blanks labeled and a sticky note saying "I'm 0.92 sure I got this right."

Why#

Teams almost always already have ZPL — exported from label-design software, copied from an old print job, or pasted from a vendor. That ZPL has the data baked in. Synthesis does the mechanical, error-prone work of finding every variable piece, replacing each with the right ^FN placeholder, and building the field map — in one call.

How#

Send your existing ZPL to POST /v1/templates/synthesize. Behind the scenes a small language model reads the ZPL, identifies the variable fields, and the engine re-parses and scores the result.

cURL

curl -X POST https://api.maddoxapi.dev/v1/templates/synthesize \
  -H "Authorization: Bearer $MADDOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_zpl": "^XA^FO50,50^A0N,30,30^FDMER-04821^FS^XZ",
    "target_scope": "tenant",
    "target_tenant_id": "tnt_…"
  }'

You get back a draft:

draft

{
  "status": "ok",
  "scope": "tenant",
  "draft": {
    "name": "asset_label",
    "width_dots": 812,
    "height_dots": 1218,
    "source_dpi": 203,
    "body": "^XA^FO50,50^A0N,30,30^FN1^FS^XZ",
    "field_map": { "asset_label_text": 1 },
    "values":    { "asset_label_text": "MER-04821" }
  },
  "confidence_score": 0.91,
  "low_confidence": false,
  "warnings": []
}

Confidence Score#

Synthesis is a draft, not a guarantee. Every response carries a confidence_score (0 – 1) and a low_confidence boolean. The score blends signals like parser warnings, field-map coverage, and schema validity.

CautionA low confidence_score (or low_confidence: true) means the draft needs a human glance before you rely on it. Always review low-confidence drafts; treat high-confidence drafts as a fast first pass you can still tweak.

It Produces a Draft — It Does Not Store Anything#

The synthesize call returns a draft and persists nothing addressable. To turn a draft into a reusable Template you commit it under a template_id as a separate step.

It Costs Quota#

Each synthesis call consumes one unit of your plan's monthly synthesis quota. Exhausting it returns a 402-class error pointing you to upgrade. See Plans & Quotas.