An agent reports operating-system printer queues to CloudPrint over an outbound connection. Your integration reads agent and printer state from Public API, saves the selected CloudPrint printer ID and uses capabilities to decide what can be printed.
## Check the agent ```bash curl -sS 'https://public-api.cloudprint.me/api/v1/agents?limit=50' \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ```json { "agents": [ { "agent_id": "22222222-2222-4222-8222-222222222222", "name": "Warehouse PC agent", "status": "online", "hostname": "warehouse-pc", "version": "0.1.1", "update": { "status": "up_to_date", "current_version": "0.1.1", "latest_version": "0.1.1", "minimum_supported_version": "0.1.0", "channel": "stable", "required": false }, "last_seen_at": "2026-06-08T10:10:00+00:00" } ], "next_cursor": null } ``` The list requires `agents:read`. An agent should be `online`; inspect `update.required` and version fields when diagnosing an installation. ## Discover printers ```bash curl -sS 'https://public-api.cloudprint.me/api/v1/printers?limit=100' \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` A shortened response shows the fields used during selection: ```json { "printers": [ { "printer_id": "11111111-1111-4111-8111-111111111111", "agent_id": "22222222-2222-4222-8222-222222222222", "name": "Warehouse Label Printer", "status": "online", "agent_name": "Warehouse PC agent", "agent_status": "online", "capabilities": { "backend": "windows_native", "language_profiles": [ { "language": "zpl", "version": "zpl2" } ], "supports_custom_media": true, "supports_orientation": true, "supports_copies": true, "supported_dpi": [ 203 ] }, "endpoint": { "system_print_available": true, "raw_passthrough_available": true, "os": "windows", "driver_name": "ZDesigner ZD421-203dpi ZPL", "connection_type": "windows_spooler" } } ], "next_cursor": null } ``` ## Save the correct identifier Persist `printer_id` for the customer location, packing station or document workflow. Display `name`, `agent_name` and status to an administrator, but never use the name as a unique routing key. When an operating-system queue is recreated, require explicit reassignment and a test print. ## Use capabilities as a contract RAW requires a matching `capabilities.language_profiles[*].language` and `endpoint.raw_passthrough_available=true`. PDF needs system printing or a CloudPrint-resolved renderer route. Before non-default color, duplex, orientation, copies, media, scaling, offsets or DPI, verify the related capability fields. ## Paginate and handle offline state Both lists return `next_cursor`. Request the next page with `?limit=100&cursor=VALUE` until it is `null`. Do not create an automatic job for an offline assignment unless your product deliberately queues work; never silently choose another printer in a different location. ## What endpoint fields mean Driver, port, OS and connection type are diagnostic descriptions of the local spooler. They are not addresses your backend should call. Credentials embedded in device URIs are redacted before CloudPrint reports them. ## Production checklist - 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. - Validate document format, page size and orientation before creating the job. - Handle terminal status, retry policy and duplicate-print protection explicitly. ## Next steps