Docs

A quickstart, the full v1 API reference covering every endpoint, object, and error the API actually ships today, a page on the agent for whoever installs it, and guides to the common jobs. New here? Start with the quickstart.

API reference

A lightweight agent runs on your machine, connects outbound to PrintSocket, and exposes that machine's printers (and scales) to this REST API. No inbound ports, no print server to run.

Base URL: https://api.printsocket.com/v1

The reference is split by what you are doing: authentication and the conventions every endpoint shares, the devices and hardware the agent reports, the jobs you send to them, the webhooks that tell you what happened, and the agent itself, which is the part that runs on a machine you may not own.

Every endpoint on these pages is also described by an OpenAPI 3.1 document. Point a code generator at it for a client in a language we do not publish one for, import it into Postman or Insomnia, or read it for the exact shape of every request and response.

Guides

Longer reads on one part of the API each, for the problem you came with rather than the endpoint you will end up on.

Print from a web app

A browser cannot reach a printer. How an outbound agent and a REST API let your server print to a customer's printers with no inbound ports or VPN.

ESC/POS printing from an API

Send ESC/POS receipt printer commands over HTTP. Raw bytes are passed through to the printer unchanged, from a call on your own server.

ZPL label printing API

Print ZPL shipping labels over HTTP, with idempotency so a retry cannot print a label twice, and completion confidence so you know it came out.

Read a USB shipping scale over HTTP

Read the weight from a USB shipping scale over a REST API: grams, whether the scale had settled, and how old the reading is.

Quickstart

1. Create an account

Sign up at https://app.printsocket.com. There is no password: you get a sign-in link by email. Name your account and you land on the dashboard.

2. Get an API key

In Settings → API keys, create a key. Pick test mode to start: test keys get a virtual device and printer that simulates the whole job lifecycle, so you can build before any hardware is involved. The secret is shown once, so store it now.

curl https://api.printsocket.com/v1/me \
  -H "Authorization: Bearer sk_test_..."

3. Enroll a machine

When you are ready for real printers, open Devices → Add device. That gives you a single-use enrollment token and the installer links. Install the agent on the machine that talks to your printers, then enroll it:

psagent enroll -token enr_... -server https://api.printsocket.com
psagent run

The agent connects outbound over a WebSocket, so nothing needs to be reachable from the internet. It reports every printer queue it can see, with capabilities, and keeps them updated.

4. Find your printer

curl "https://api.printsocket.com/v1/printers?state=online" \
  -H "Authorization: Bearer sk_test_..."

5. Send a job

curl https://api.printsocket.com/v1/jobs \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-12345" \
  -d '{
    "printer_id": "prn_8f2k1",
    "title": "Order #12345 label",
    "content": { "format": "pdf", "url": "https://example.com/label.pdf" },
    "options": { "paper": "A4" }
  }'

On Node.js, PHP, or Python, the official clients (printsocket-node, printsocket-php, printsocket-python) wrap the same call, along with the rest of the API:

Node.js PHP Python

# npm install printsocket
import PrintSocket from "printsocket";

const ps = new PrintSocket({ apiKey: "sk_test_..." });
const job = await ps.jobs.create({
  printer_id: "prn_8f2k1",
  title: "Order #12345 label",
  content: { format: "pdf", url: "https://example.com/label.pdf" },
  options: { paper: "A4" }
});

# composer require printsocket/printsocket
$ps = new PrintSocket\PrintSocketClient(['api_key' => 'sk_test_...']);
$job = $ps->jobs->create([
  'printer_id' => 'prn_8f2k1',
  'title' => 'Order #12345 label',
  'content' => ['format' => 'pdf', 'url' => 'https://example.com/label.pdf'],
  'options' => ['paper' => 'A4'],
]);

# pip install printsocket
import printsocket

ps = printsocket.PrintSocket(api_key="sk_test_...")
job = ps.jobs.create({
    "printer_id": "prn_8f2k1",
    "title": "Order #12345 label",
    "content": {"format": "pdf", "url": "https://example.com/label.pdf"},
    "options": {"paper": "A4"},
})

A 201 comes back with the job object, "status": "queued", and an id starting job_. On the virtual printer it reaches succeeded within a few seconds. Anything else is an error envelope whose code is in the error code table: a 401 is the key, a 404 is a printer id from the other mode, and a 422 printer_offline means the agent on that machine is not connected.

Poll GET /v1/jobs/{id}, read the transition history at GET /v1/jobs/{id}/events, or register a webhook and get pushed the state changes as they happen. Everything on this page is also doable from the dashboard, including sending a test print without writing any code.

All reference sections, by name