{"openapi":"3.1.0","info":{"title":"ZPLJet API","version":"1.0.0","description":"Convert ZPL (Zebra Programming Language) to PDF or PNG. Send raw ZPL and get the file bytes back directly (default — nothing is stored) or, on paid plans, a hosted signed URL with plan-based retention."},"servers":[{"url":"https://api.zpljet.com","description":"Production"},{"url":"http://localhost:3737","description":"Local development"}],"security":[{"ApiKeyAuth":[]}],"paths":{"/v1/convert":{"post":{"operationId":"convert","summary":"Convert ZPL to PDF or PNG","description":"Renders the supplied ZPL. With `output: \"data\"` (the default) the file bytes are returned directly and nothing is stored. With `output: \"url\"` (paid plans only) the file is hosted and a signed URL is returned, retained for `retentionDays` (bounded by your plan).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConvertRequest"}}}},"responses":{"200":{"description":"Conversion succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConvertResponse"}},"application/pdf":{"schema":{"type":"string","format":"binary"}},"image/png":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Invalid request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Monthly conversion quota exceeded for the current plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Hosting (`output: \"url\"`) is not permitted — either the plan is data-only or enforced no-retention mode is on.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded for this API key. The `Retry-After` header (seconds) indicates when to retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The rendering engine failed to process the ZPL.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Your API key, e.g. `zpl_...`. Create one in the dashboard."}},"schemas":{"ConvertRequest":{"type":"object","required":["zpl"],"properties":{"zpl":{"type":"string","description":"Raw ZPL (one or more ^XA…^XZ labels). Max 512 KB.","maxLength":524288,"examples":["^XA^FO50,50^A0N,50,50^FDHello^FS^XZ"]},"dpmm":{"type":"integer","enum":[6,8,12,24],"default":8,"description":"Print density in dots/mm. 8 = 203 dpi, 12 = 300 dpi, 24 = 600 dpi."},"widthMm":{"type":"number","default":101.6,"description":"Label width in millimeters (default 4 in)."},"heightMm":{"type":"number","default":152.4,"description":"Label height in millimeters (default 6 in)."},"format":{"type":"string","enum":["pdf","png"],"default":"pdf","description":"Output format."},"output":{"type":"string","enum":["data","url"],"default":"data","description":"Delivery mode. `data` returns the raw file bytes and stores nothing (all plans). `url` hosts the file and returns a signed link (paid plans only)."},"retentionDays":{"type":"integer","minimum":1,"description":"For `output: \"url\"` only — days to retain the hosted file. Clamped to your plan maximum (Starter 3, Pro 30, Scale 90). Defaults to 3."}}},"ConvertResponse":{"type":"object","description":"Returned when `output: \"url\"`.","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri","description":"Signed URL to the hosted file. Valid until `urlExpiresAt` (at most 7 days); request a fresh conversion if the file outlives its link."},"pages":{"type":"integer","description":"Number of label pages rendered."},"retentionDays":{"type":"integer","description":"Days the hosted file is retained before deletion."},"expiresAt":{"type":"string","format":"date-time","description":"When the hosted file is deleted (retention window)."},"urlExpiresAt":{"type":"string","format":"date-time","description":"When this signed URL stops working (SigV4 caps links at 7 days)."}}},"Error":{"type":"object","properties":{"error":{"type":"string"}}}}}}