CloudPrint Documentation/API reference

Upload a document for printing

Upload a print-ready PDF or explicit RAW printer-language payload before creating a CloudPrint print job.

POST/api/v1/documentsAPI version: v1operationId: uploadDocumentView as Markdown

What this endpoint does

Upload a print-ready PDF or explicit RAW printer-language payload before creating a CloudPrint print job.

Authentication

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

Required scopes: documents:write

Request

Production base URL: https://public-api.cloudprint.me/api/v1/documents

Parameters

Name	Location	Type	Required	Description	Constraints
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: multipart/form-data

Name	Type	Required	Description	Constraints
file	string (binary)	yes	Binary PDF or RAW document uploaded as multipart form data.	—
document_format	string | null	no	Explicit print format, such as pdf or raw. Both formats use documents:write.	enum: pdf, raw; example: "raw"
document_raw_language	string | null	no	Printer command language used by RAW data, for example ZPL or TSPL.	enum: tspl, zpl, cpcl, escpos; example: "zpl"

Example requests

cURL

curl -sS https://public-api.cloudprint.me/api/v1/documents \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F "file=@shipping-label.pdf"

Response

HTTP status: 201 — Document uploaded

Response fields

Name	Type	Required	Description	Constraints
document_id	string (uuid)	yes	Stable UUID returned after a successful document upload.	—
original_filename	string	yes	Original document filename recorded during upload.	example: "invoice.pdf"
mime_type	string	yes	MIME type of the published installer or stored 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
size_bytes	integer	yes	Stored document size in bytes.	example: 1024

Example response

{
  "document_id": "11111111-1111-4111-8111-111111111111",
  "original_filename": "invoice.pdf",
  "mime_type": "application/pdf",
  "document_format": "pdf",
  "document_raw_language": null,
  "size_bytes": 1024
}

Errors

HTTP status	Description
400	Invalid upload request
401	OAuth bearer token is missing or invalid
403	OAuth bearer token does not include documents:write
413	Uploaded file is too large
415	Document format is not supported
422	Document content, declared format, or upload request is invalid
429	Rate limit exceeded
500	Unexpected error
503	Document security inspection is temporarily unavailable

Integration guidance

• The existing documents:write scope covers PDF and RAW. For RAW printing, explicitly send document_format=raw and document_raw_language.
• Convert DOC and DOCX to a print-ready PDF in your backend before uploading.
• A 422 document rejection requires corrected input; retry a temporary inspection 503 with bounded backoff.
• Keep the returned document_id for the subsequent print-job request.

Related documentation

Upload PDF and RAW documentsChoose multipart upload, a public HTTPS URL or Base64, and prepare PDF or RAW printer-language data for CloudPrint.Create a print jobSend an uploaded CloudPrint document to a selected printer with idempotency and explicit print options.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.

Service statusOpenAPIDeveloper PortalOpen accountPrivacy PolicyTermsDPAService Level Agreement