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

This endpoint has no path, query or custom header parameters.

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.	enum: pdf, raw; example: "raw"
document_raw_language	string | null	no	Printer command language used by RAW data, for example ZPL or EPL.	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	—	example: "invoice.pdf"
mime_type	string	yes	—	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
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	Uploaded file type is not supported by the Public API
422	Document validation failed
429	Rate limit exceeded
500	Unexpected error

Integration guidance

• PDF is the default. 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.
• 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.

OpenAPIOpen accountPrivacy PolicyTermsPayment and refundsDPA