CloudPrint API quickstart
Start with one end-to-end print test. Each API step returns an identifier for the next request, while physical output is verified separately from the final job status.
Before you begin
You need a CloudPrint account, a computer that can print to the target printer, the CloudPrint Agent installed and online on that computer, and a backend that can protect client_secret. Your backend sends requests only to https://public-api.cloudprint.me; it does not call the local agent. Create a client app with printers:read, documents:write, print_jobs:write and print_jobs:read. The existing documents:write scope covers print-ready PDF and validated RAW uploads.
1. Obtain and verify a token
curl -sS https://public-api.cloudprint.me/oauth/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=YOUR_CLIENT_ID' \
--data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
--data-urlencode 'scope=printers:read documents:write print_jobs:write print_jobs:read'The token response contains the value and lifetime:
{
"token_type": "Bearer",
"expires_in": 900,
"access_token": "eyJ..."
}Set ACCESS_TOKEN in your test shell, then call /api/v1/me to catch a wrong account or missing scope before touching a printer:
curl -sS https://public-api.cloudprint.me/api/v1/me \
-H "Authorization: Bearer $ACCESS_TOKEN"2. Choose a printer and save its ID
curl -sS 'https://public-api.cloudprint.me/api/v1/printers?limit=100' \
-H "Authorization: Bearer $ACCESS_TOKEN"Require an online agent. For conservative automatic routing, use a printer whose status is online, or native cups_ipp/windows_spooler evidence with accepting_jobs=true. Keep any physical warning visible to the operator. Save printer_id; display names can change and are not routing keys. Read agents and printers before using RAW or non-default options.
3. Upload the final document
curl -sS https://public-api.cloudprint.me/api/v1/documents \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-F 'file=@invoice.pdf;type=application/pdf'The response supplies the identifier for the job:
{
"document_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
"original_filename": "invoice.pdf",
"mime_type": "application/pdf",
"document_format": "pdf",
"document_raw_language": null,
"size_bytes": 1024
}Only print-ready PDF and explicit RAW printer-language data are accepted. See document upload for ZPL and one-request alternatives.
4. Create one idempotent job
curl -sS https://public-api.cloudprint.me/api/v1/print-jobs \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: order-18452-invoice-v1' \
-d '{
"document_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
"printer_id": "11111111-1111-4111-8111-111111111111",
"copies": 1,
"intent": "invoice",
"color_mode": "default",
"duplex_mode": "default",
"scale_mode": "none",
"orientation": "default"
}'The fields are top-level JSON properties; there is no nested options object. Save the returned print_job_id beside your order or invoice ID:
{
"print_job_id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb",
"document_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
"document_mime_type": "application/pdf",
"document_format": "pdf",
"document_raw_language": null,
"printer_id": "11111111-1111-4111-8111-111111111111",
"status": "pending",
"copies": 1,
"intent": "invoice",
"color_mode": "default",
"duplex_mode": "default",
"media_width_mm": null,
"media_height_mm": null,
"dpi": null,
"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-06-08T10:12:00+00:00",
"reserved_at": null,
"started_at": null,
"completed_at": null,
"failure_reason": null
}5. Wait for the final status
curl -sS https://public-api.cloudprint.me/api/v1/print-jobs/bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb \
-H "Authorization: Bearer $ACCESS_TOKEN"Continue while the status is pending, reserved or printing. Stop at printed, failed or cancelled. printed means that the operating-system spooler accepted the document; it does not confirm physical output. For failed, preserve failure_reason; cancelled means that spool acceptance did not complete. Treat future unknown statuses as non-terminal. Complete a pre-production test only after the intended printer produces exactly one copy and the API job reaches printed.
6. Save troubleshooting details
Store CloudPrint's X-Request-Id with your business ID for every request. You may send your own safe correlation value in that header; CloudPrint echoes it or replaces an unsafe value. Also keep print_job_id, printer_id, the idempotency key and status changes. After a timeout, repeat the same create request with the same key. An intentional reprint is a separate business operation and needs a new key. Read print jobs before going live.