CloudPrint Documentation/API reference

Create a print job from Base64

Decode a small Base64 document and create a normal CloudPrint document and print job in one request.

POST/api/v1/print-jobs/from-base64API version: v1operationId: createPrintJobFromBase64View as Markdown

What this endpoint does

Decode a small Base64 document and create a normal CloudPrint document and print job in one request.

Authentication

Send a short-lived access token in Authorization: Bearer <access_token>.

Required scopes: documents:write, print_jobs:write

Request

Production base URL: https://public-api.cloudprint.me/api/v1/print-jobs/from-base64

Parameters

Name	Location	Type	Required	Description	Constraints
Idempotency-Key	header	string	no	Stable caller-generated key that makes retries return the original result instead of creating a duplicate.	maxLength: 128
X-Request-Id	header	string	no	Optional request identifier for tracing; CloudPrint returns a safe value in the response header.	maxLength: 128; example: "order-100045-attempt-1"

Request body

Content type: application/json

Name	Type	Required	Description	Constraints
document_base64	string (byte)	yes	Complete document bytes encoded as Base64 without a data-URL prefix.	—
document_filename	string | null	no	File name used for format detection and operator diagnostics.	example: "order-100045.pdf"
document_format	string | null	no	Explicit print format, such as pdf or raw. Both formats use documents:write.	enum: pdf, raw; example: "pdf"
document_raw_language	string | null	no	Printer command language used by RAW data, for example ZPL or TSPL.	enum: tspl, zpl, cpcl, escpos; example: null
printer_id	string (uuid)	yes	Stable CloudPrint UUID of the destination printer.	—
copies	integer	no	Number of copies CloudPrint asks the printer to produce.	min: 1; max: 99; example: 1
intent	string	no	Business purpose of the print job, used for diagnostics and sensible defaults.	enum: document, shipping_label, product_label, invoice, packing_slip, a4_document, receipt; example: "shipping_label"
color_mode	string	no	Requested color handling; default leaves the decision to the printer configuration.	enum: default, monochrome, color; example: "default"
duplex_mode	string	no	Requested one-sided or two-sided printing mode.	enum: default, simplex, duplex_long_edge, duplex_short_edge; example: "default"
media_width_mm	number | null	no	Requested media or label width in millimetres.	min: 1; max: 2000; example: 58
media_height_mm	number | null	no	Requested media or label height in millimetres.	min: 1; max: 2000; example: 40
dpi	integer | null	no	Target print resolution in dots per inch; use a value supported by the printer.	min: 72; max: 2400; example: 203
scale_mode	string	no	Controls whether the document keeps its size or is fitted to the target media.	enum: none, fit; example: "none"
orientation	string	no	Requested page orientation; default uses printer settings.	enum: default, portrait, landscape; example: "default"
offset_x_mm	number	no	Horizontal print offset in millimetres.	min: -2000; max: 2000; example: 0
offset_y_mm	number	no	Vertical print offset in millimetres.	min: -2000; max: 2000; example: 0
margin_top_mm	number	no	Additional print margin in millimetres.	min: 0; max: 2000; example: 0
margin_right_mm	number	no	Additional print margin in millimetres.	min: 0; max: 2000; example: 0
margin_bottom_mm	number	no	Additional print margin in millimetres.	min: 0; max: 2000; example: 0
margin_left_mm	number	no	Additional print margin in millimetres.	min: 0; max: 2000; example: 0

Example requests

cURL

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: order-100045-label' \
  -d '{
    "document_base64": "JVBERi0xLjQK...",
    "document_filename": "order-100045.pdf",
    "printer_id": "11111111-1111-4111-8111-111111111111",
    "copies": 1,
    "intent": "shipping_label",
    "media_width_mm": 58,
    "media_height_mm": 40,
    "dpi": 203
  }'

Response

HTTP status: 201 — Print job created

Response fields

Name	Type	Required	Description	Constraints
print_job_id	string (uuid)	yes	Stable UUID of the print job; persist it for status checks and support.	—
document_id	string (uuid)	yes	Stable UUID returned after a successful document upload.	—
document_mime_type	string	yes	MIME type of the supplied document.	example: "application/pdf"
document_format	string	yes	Explicit print format, such as pdf or raw. Both formats use documents:write.	enum: pdf, raw; example: "pdf"
document_raw_language	string | null	yes	Printer command language used by RAW data, for example ZPL or TSPL.	enum: tspl, zpl, cpcl, escpos; example: null
printer_id	string (uuid)	yes	Stable CloudPrint UUID of the destination printer.	—
status	string	yes	Current resource or workflow state; use the endpoint-specific enum values.	enum: pending, reserved, printing, printed, failed, cancelled; example: "pending"
copies	integer	yes	Number of copies CloudPrint asks the printer to produce.	min: 1; max: 99; example: 1
intent	string	yes	Business purpose of the print job, used for diagnostics and sensible defaults.	enum: document, shipping_label, product_label, invoice, packing_slip, a4_document, receipt; example: "shipping_label"
color_mode	string	yes	Requested color handling; default leaves the decision to the printer configuration.	enum: default, monochrome, color; example: "default"
duplex_mode	string	yes	Requested one-sided or two-sided printing mode.	enum: default, simplex, duplex_long_edge, duplex_short_edge; example: "default"
media_width_mm	number | null	yes	Requested media or label width in millimetres.	min: 1; max: 2000; example: 58
media_height_mm	number | null	yes	Requested media or label height in millimetres.	min: 1; max: 2000; example: 40
dpi	integer | null	yes	Target print resolution in dots per inch; use a value supported by the printer.	min: 72; max: 2400; example: 203
scale_mode	string	yes	Controls whether the document keeps its size or is fitted to the target media.	enum: none, fit; example: "none"
orientation	string	yes	Requested page orientation; default uses printer settings.	enum: default, portrait, landscape; example: "default"
offset_x_mm	number	yes	Horizontal print offset in millimetres.	min: -2000; max: 2000; example: 0
offset_y_mm	number	yes	Vertical print offset in millimetres.	min: -2000; max: 2000; example: 0
margin_top_mm	number	yes	Additional print margin in millimetres.	min: 0; max: 2000; example: 0
margin_right_mm	number	yes	Additional print margin in millimetres.	min: 0; max: 2000; example: 0
margin_bottom_mm	number	yes	Additional print margin in millimetres.	min: 0; max: 2000; example: 0
margin_left_mm	number	yes	Additional print margin in millimetres.	min: 0; max: 2000; example: 0
created_at	string (date-time)	yes	ISO 8601 timestamp recorded by CloudPrint.	—
reserved_at	string | null (date-time)	yes	ISO 8601 timestamp recorded by CloudPrint.	—
started_at	string | null (date-time)	yes	ISO 8601 timestamp recorded by CloudPrint.	—
completed_at	string | null (date-time)	yes	ISO 8601 timestamp recorded by CloudPrint.	—
failure_reason	string | null	yes	Machine-readable or diagnostic reason recorded when printing fails.	—

Example response

{
  "print_job_id": "11111111-1111-4111-8111-111111111111",
  "document_id": "11111111-1111-4111-8111-111111111111",
  "document_mime_type": "application/pdf",
  "document_format": "pdf",
  "document_raw_language": null,
  "printer_id": "11111111-1111-4111-8111-111111111111",
  "status": "pending",
  "copies": 1,
  "intent": "shipping_label",
  "color_mode": "default",
  "duplex_mode": "default",
  "media_width_mm": 58,
  "media_height_mm": 40,
  "dpi": 203,
  "scale_mode": "none",
  "orientation": "default",
  "offset_x_mm": 0,
  "offset_y_mm": 0,
  "margin_top_mm": 0,
  "margin_right_mm": 0,
  "margin_bottom_mm": 0,
  "margin_left_mm": 0,
  "created_at": "2026-08-06T12:00:00Z",
  "reserved_at": "2026-08-06T12:00:00Z",
  "started_at": "2026-08-06T12:00:00Z",
  "completed_at": "2026-08-06T12:00:00Z",
  "failure_reason": "string"
}

Errors

HTTP status	Description
400	Invalid base64 request
401	OAuth bearer token is missing or invalid
403	OAuth bearer token lacks documents:write or print_jobs:write
409	Idempotency key conflict or unsupported print route. Unsupported routes include details.reason.
413	Document is too large
415	Document format is not supported
422	Document content, declared format, or print job request is invalid
429	Rate limit exceeded
500	Unexpected error
503	Document security inspection is temporarily unavailable

Integration guidance

• Base64 increases request size; prefer multipart upload or a public HTTPS URL for larger documents.
• Use this shortcut for small receipts or labels when a separate upload is impractical. PDF and RAW input retain the existing documents:write authorization.
• A 422 document rejection requires corrected input; retry a temporary inspection 503 with bounded backoff.
• Apply the same idempotency and status-tracking rules as for normal job creation.

Related documentation

Create a print job from a URLFetch a document from a public HTTPS URL and create a normal CloudPrint document and print job in one request.Create a print jobSend an uploaded CloudPrint document to a selected printer with idempotency and explicit print options.Get a print job statusRead one CloudPrint print job until it reaches the terminal printed, failed or cancelled status.

Service statusOpenAPIDeveloper PortalOpen accountPrivacy PolicyTermsDPAService Level Agreement