Create a print job from a URL
Fetch a document from a public HTTPS URL and create a normal CloudPrint document and print job in one request.
What this endpoint does
Fetch a document from a public HTTPS URL 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-url
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_url | string (uri) | yes | Public HTTPS URL from which CloudPrint downloads the document. | example: "https://files.example.com/labels/order-100045.pdf" |
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
bash
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: order-100045-label' \
-d '{
"document_url": "https://files.example.com/labels/order-100045.pdf",
"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
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": "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 URL 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 | Remote document is too large |
415 | Document format is not supported |
422 | Document content, declared format, remote URL, or print job request is invalid |
429 | Rate limit exceeded |
500 | Unexpected error |
503 | Document security inspection is temporarily unavailable |
Integration guidance
- The source must be a public HTTPS URL; localhost, private networks, embedded credentials and unsafe redirects are rejected.
- Use a short-lived, narrowly scoped download URL that remains valid long enough for CloudPrint to fetch it. PDF and RAW input retain the existing
documents:writeauthorization. - A
422document rejection requires corrected input; retry a temporary inspection503with bounded backoff. - Apply the same idempotency and status-tracking rules as for normal job creation.
Related documentation
Create a print jobSend an uploaded CloudPrint document to a selected printer with idempotency and explicit print options.Create a print job from Base64Decode a small Base64 document and create a normal CloudPrint document and print job in one request.Get a print job statusRead one CloudPrint print job until it reaches the terminal printed, failed or cancelled status.