CloudPrint API quickstart
Complete one real print before designing background queues or retry workers. This path is intentionally explicit: each command produces an identifier used by the next command, and the final status proves whether printing completed.
Prerequisites and responsibility
You need a CloudPrint account, an installed agent that is online beside the printer, and a backend capable of protecting client_secret. External software calls only https://public-api.cloudprint.me; it must never call the local agent. Create a client app with printers:read, documents:write, print_jobs:write and print_jobs:read.
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. Select a stable printer
curl -sS 'https://public-api.cloudprint.me/api/v1/printers?limit=100' \
-H "Authorization: Bearer $ACCESS_TOKEN"Choose an item where the printer and its agent are online. Save its printer_id in your location or workstation configuration; do not route by display name. 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. Poll until the result is terminal
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 or failed; for failed, preserve failure_reason. Unknown future states are non-terminal. A successful test means the correct physical printer produced exactly one copy and the job reached printed.
6. Record enough evidence
For every request, store CloudPrint's X-Request-Id with your business ID. You may send your own safe correlation value in that header; CloudPrint echoes it or replaces an unsafe value. Persist print_job_id, printer_id, idempotency key and status transitions. A timeout retry repeats the same create request with the same key; an intentional reprint is a new business operation with a new key. Continue with print-job behavior before production.
Production checklist
- Keep API credentials on the backend and scope them to the owning account.
- Use an outbound agent connection; do not expose printer ports to the internet.
- Store the stable printer identity instead of relying only on a display name.
- Handle terminal status, retry policy and duplicate-print protection explicitly.