Devices, printers and scales

A device is a machine running the PrintSocket agent, and printers and scales are the hardware that machine can see. You do not create any of them through this API. The agent discovers them and reports them, so these endpoints are about reading state and reacting to it: which printers exist, which are online, what each one can do, and what the scale on the counter currently weighs.

The one thing you do create here is an enrollment token, which is how a machine joins your account. It is the last section on this page, and it is worth reading before you ship an installer to a customer: the token exchanges for device-scoped credentials, so your account API keys never have to leave your server.

Devices

A device is a machine running the PrintSocket agent.

Device object:

{
  "id": "dev_7hk2m",
  "object": "device",
  "name": "Front desk PC",
  "state": "online",            // online | offline | revoked
  "hostname": "FRONTDESK-01",
  "os": { "family": "windows", "version": "11" },
  "agent_version": "1.4.2",
  "last_seen_at": "2026-07-29T14:01:55Z",
  "created_at": "...",
  "metadata": {},
  "virtual": false
}

agent_version is the build the machine is running right now, not the one it enrolled with. It updates when the agent updates. os is recorded at enrollment time only.

virtual is true only for the test-mode fixture device, and it is the only field that tells you which one that is: the fixture looks like a real device in every other respect, and you can rename it. Revoke is the single thing it refuses, with a 409 device_virtual, because a revoke cannot be undone and nothing would give you a new fixture. Everything else works on it, including disabling its printer, which is how you make a test-mode job fail with printer_disabled.

Printers

Printers are discovered automatically by the agent. They are not created through the API.

Printer object:

{
  "id": "prn_8f2k1",
  "object": "printer",
  "device_id": "dev_7hk2m",
  "name": "Label printer",          // your alias, PATCHable
  "system_name": "ZDesigner ZD420", // as reported by the OS
  "state": "online",                // online | offline (offline whenever the device is offline)
  "enabled": true,
  "default_options": { "copies": 1 },
  "capabilities": {
    "color": false,
    "duplex": false,
    "copies_max": 99,
    "dpis": ["203x203"],
    "papers": { "4x6": [1016, 1524] },   // tenths of a mm
    "trays": ["Main"],
    "media": [],
    "collate": true,
    "custom_paper_size": false
  },
  "created_at": "...",
  "metadata": {}
}

default_options merge underneath per-job options, so you can configure a printer once (always 203 dpi, tray 2) instead of repeating it on every job.

Removal. Agents report the complete queue list, so a printer missing from a report has been deleted from the OS. Queues that are present but unreachable are still reported, as offline. A removed printer leaves every listing, GET /printers/{id} returns 404, and printer.removed fires. If the queue reappears under the same system_name, the printer revives with the same id and printer.discovered fires again.

Scales

Read-only telemetry from USB scales attached to a device.

Scale object:

{
  "id": "scl_9d3f2",
  "object": "scale",
  "device_id": "dev_7hk2m",
  "system_name": "Mettler Toledo PS60",
  "state": "online",                 // online | offline (offline whenever the device is offline)
  "reading": {                       // null until the agent reports one
    "weight_grams": 1234,
    "stable": true,
    "captured_at": "2026-07-29T14:02:08Z"
  },
  "created_at": "..."
}

Scales are discovered and reported by the agent, like printers. A report without a fresh reading keeps the previous one, so check captured_at to see how stale a weight is, and stable to know whether the scale had settled. Read the weight on demand at the moment you need it, typically when buying a label. Scales carry no metadata and emit no webhook events.

Enrolling a device

1. From your server, POST /enrollment_tokens → { "token": "enr_...", "expires_at": ... }.
2. Run the agent installer on the target machine with that token (CLI flag or paste into the GUI).
3. The agent exchanges the token for device-scoped credentials. The device appears as dev_... and device.enrolled fires.
4. Printers are discovered automatically; a printer.discovered event fires for each.

Enrollment tokens are short-lived and single-use, and the credentials the agent ends up holding are scoped to that one device. Your account API keys never need to be embedded in an installer or stored on an end customer's machine.