PDF and RAW printer languages
CloudPrint accepts print-ready PDF and four explicit RAW printer languages: ZPL, TSPL, CPCL and ESC/POS. Your integration declares the document language, the agent discovers what each printer reports, and the API prevents incompatible jobs from being routed.
Choose the correct input
| Input | document_format | document_raw_language | Typical use |
|---|---|---|---|
pdf | omit | invoices, packing slips and page-based labels | |
| ZPL | raw | zpl | thermal labels |
| TSPL / TSPL-EZ | raw | tspl | thermal labels |
| CPCL | raw | cpcl | mobile and compact label printers |
| ESC/POS | raw | escpos | receipts and point-of-sale printers |
The names in the API are exact enum values. TSPL-EZ devices may report more than one compatible profile; always use a language that the selected printer actually advertises.
Trust discovered capabilities
Call GET /api/v1/printers and inspect capabilities.language_profiles together with endpoint.raw_passthrough_available. The agent discovers these capabilities from printer-reported data. Do not infer a language from a brand, model or queue name, and do not ask an operator to assign one manually.
Upload RAW data explicitly
Set both RAW fields and send the original printer commands without rendering:
RAW_LANGUAGE=tspl
curl -sS https://public-api.cloudprint.me/api/v1/documents \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-F 'file=@label.prn;type=application/octet-stream' \
-F 'document_format=raw' \
-F "document_raw_language=$RAW_LANGUAGE"Use zpl, tspl, cpcl or escpos. CloudPrint validates the declared language against the selected printer before delivery; it does not translate one printer language into another.
Keep PDF separate from RAW
Upload a print-ready PDF with document_format=pdf and omit document_raw_language. A PDF needs system printing or an agent-supported conversion route. Do not label PDF bytes as RAW. The dashboard accepts PDF and the same explicit RAW languages as the API: ZPL, TSPL, CPCL and ESC/POS.
Test the exact printer and media
Before production, test every printer model, driver or queue, language, DPI and media profile used by the workflow. For a failed job, record print_job_id, X-Request-Id, failure reason and the advertised capabilities. For poor output, verify the original command data, media size, sensor calibration, darkness and speed on the physical device without logging confidential document contents.