Connect an agent and select a printer
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
curl -sS 'https://public-api.cloudprint.me/api/v1/agents?limit=50' \
-H "Authorization: Bearer $ACCESS_TOKEN"{
"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
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:
{
"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.