Local Printer API for web and SaaS applications
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"
},
"status_evidence": {
"source": "windows_spooler",
"reasons": [
"paper_out"
],
"accepting_jobs": true,
"queued_jobs": 3
}
}
],
"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.
Separate device state from queue acceptance
status describes the physical or configured printer state. status_evidence describes the latest queue observation: source is cups_ipp, windows_spooler, configured or unknown; reasons contains normalized device and spooler conditions; accepting_jobs says whether a native spooler can durably accept another job; and queued_jobs is the local operating-system queue snapshot, not pending CloudPrint work. Null queue metrics are not authoritative. An online agent plus native accepting_jobs=true can remain dispatchable during a transient device warning, but keep the physical warning visible.
Check what the printer supports
RAW requires a matching capabilities.language_profiles[*].language and endpoint.raw_passthrough_available=true. PDF needs system printing or a CloudPrint-supported rendering path. Before setting non-default color, duplex, orientation, copies, media, scaling, offsets or DPI, check the related capability fields.
Paginate and handle unavailable queues
Both lists return next_cursor. Request the next page with ?limit=100&cursor=VALUE until it is null. Pause automatic routing when the agent is offline or native evidence does not authorize queue acceptance. 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.