Upload PDF and RAW documents
Upload data only after it is ready for the selected printer. Public API accepts PDF or an explicit RAW printer language; it does not convert DOC/DOCX, buy shipping labels or infer a device language from arbitrary bytes.
Upload a PDF
curl -sS https://public-api.cloudprint.me/api/v1/documents \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-F 'file=@invoice.pdf;type=application/pdf'A successful upload returns HTTP 201 and this shape:
{
"document_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
"original_filename": "invoice.pdf",
"mime_type": "application/pdf",
"document_format": "pdf",
"document_raw_language": null,
"size_bytes": 1024
}Persist document_id for the create-job request.
Upload RAW data
curl -sS https://public-api.cloudprint.me/api/v1/documents \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-F 'file=@label.txt;type=application/octet-stream' \
-F 'document_format=raw' \
-F 'document_raw_language=zpl'Allowed RAW languages are zpl, tspl, cpcl and escpos. The selected printer must advertise the same language and RAW passthrough. Do not send PDF bytes as RAW.
Create directly from a public URL
curl -sS https://public-api.cloudprint.me/api/v1/print-jobs/from-url \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: shipment-18452-label-url-v1' \
-d '{
"document_url": "https://files.example.com/labels/shipment-18452.pdf",
"document_filename": "shipment-18452.pdf",
"printer_id": "11111111-1111-4111-8111-111111111111",
"copies": 1,
"intent": "shipping_label",
"media_width_mm": 100,
"media_height_mm": 150,
"dpi": 203
}'The URL must use HTTPS. CloudPrint rejects localhost, private and reserved networks, embedded credentials and redirects that fail the same checks. This returns the normal print-job response.
Create directly from Base64
curl -sS https://public-api.cloudprint.me/api/v1/print-jobs/from-base64 \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: receipt-18452-base64-v1' \
-d '{
"document_base64": "JVBERi0xLjQK...",
"document_filename": "receipt-18452.pdf",
"printer_id": "11111111-1111-4111-8111-111111111111",
"copies": 1,
"intent": "receipt"
}'Use this for small inline documents. Base64 increases the request size; prefer multipart or a protected short-lived public URL for larger files. This also returns the normal print-job response.
Choose the transport
Multipart /api/v1/documents is the default for files in your backend. Use /from-url when the final file already has a safe public HTTPS URL, and /from-base64 for small generated data. All create-job variants should carry an Idempotency-Key.
Validate before upload
Confirm content type, file size, page or media dimensions and orientation. Convert office formats to PDF yourself. For a carrier label, first obtain the final PDF or ZPL from the carrier or shipping platform; CloudPrint starts at printing.
Handle upload errors
400 means a malformed multipart request, 413 means too large, 415 means the detected or declared type is unsupported and 422 means validation failed. Branch on the response error; use message only for operator diagnostics and store X-Request-Id.
Production checklist
- Use an outbound agent connection; do not expose printer ports to the internet.
- Store the stable printer identity instead of relying only on a display name.
- Validate document format, page size and orientation before creating the job.
- Handle terminal status, retry policy and duplicate-print protection explicitly.