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 ```bash 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: ```json { "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: ```bash curl -sS https://public-api.cloudprint.me/api/v1/me \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## 2. Choose a printer and save its ID ```bash 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](../api/agents-and-printers/) before using RAW or non-default options. ## 3. Upload the final document ```bash 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: ```json { "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](../api/documents/) for ZPL and one-request alternatives. ## 4. Create one idempotent job ```bash 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: ```json { "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 ```bash 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](../api/print-jobs/) before going live. ## Next steps