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: 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	Optional key that prevents duplicate print jobs for the same account and payload.	maxLength: 128

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`.	enum: `pdf`, `raw`; example: `"pdf"`
`document_raw_language`	`string \| null`	no	Printer command language used by RAW data, for example ZPL or EPL.	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

bash

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`.	enum: `pdf`, `raw`; example: `"pdf"`
`document_raw_language`	`string \| null`	yes	Printer command language used by RAW data, for example ZPL or EPL.	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

json

{
  "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": null,
  "started_at": null,
  "completed_at": null,
  "failure_reason": null
}

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 type is not supported by the Public API
`422`	Print job validation failed
`429`	Rate limit exceeded
`500`	Unexpected error

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.
Apply the same idempotency and status-tracking rules as for normal job creation.

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 or failed status.

Create a print job from Base64 ​

What this endpoint does ​

Authentication ​

Request ​

Parameters ​

Request body ​

Example requests ​

cURL ​

Response ​

Response fields ​

Example response ​

Errors ​

Integration guidance ​

Related documentation ​