> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plato.ae/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP API

> Endpoints exposed by the PC printer driver.

# HTTP API

All endpoints are served from the configured driver host.

```txt theme={null}
http://<driver-host>:8080
https://plato-printer.local
```

## Common Printer Target

Printer-targeting endpoints require `ip_address` and `port`.

```json theme={null}
{
  "vendor_id": 1208,
  "product_id": 1208,
  "ip_address": "192.168.1.50",
  "port": "9100",
  "beep": false
}
```

`vendor_id` and `product_id` are accepted for client compatibility. The current network print path targets printers by `ip_address` and `port`.

## POST /print

Queues a print job and returns immediately.

```http theme={null}
POST /print
Content-Type: application/json
```

```json theme={null}
{
  "vendor_id": 1208,
  "product_id": 1208,
  "ip_address": "192.168.1.50",
  "port": "9100",
  "beep": true,
  "chunks": ["GSB2MAA..."],
  "runAt": 1735689600000
}
```

| Field        | Required | Notes                                                                                                |
| ------------ | -------- | ---------------------------------------------------------------------------------------------------- |
| `ip_address` | Yes      | Printer IP address.                                                                                  |
| `port`       | Yes      | Printer TCP port, usually `9100`.                                                                    |
| `chunks`     | Yes      | Non-empty array of base64 ESC/POS chunks.                                                            |
| `beep`       | No       | Adds the configured beep sequence after print/cut.                                                   |
| `runAt`      | No       | Millisecond timestamp, numeric string, or parseable date string. Future values delay the BullMQ job. |

Successful response:

```json theme={null}
{
  "ok": true,
  "jobId": "42",
  "queued": true
}
```

Validation errors:

| Status | Error                     |
| ------ | ------------------------- |
| `400`  | `Missing printer address` |
| `400`  | `Missing print data`      |
| `400`  | `Invalid runAt timestamp` |

## POST /status

Returns cached or live printer status.

```json theme={null}
{
  "ip_address": "192.168.1.50",
  "port": "9100",
  "validate": true
}
```

Response:

```json theme={null}
{
  "ok": true,
  "printerKey": "192.168.1.50:9100",
  "status": "online",
  "validated": true,
  "busy": false,
  "source": "probe",
  "lastPingOn": "2026-06-16T07:00:00.000Z",
  "lastError": null,
  "waiting": 0,
  "active": 0,
  "delayed": 0,
  "failed": 0,
  "completed": 0
}
```

Status behavior:

* If the queue has waiting, active, or delayed jobs, status returns cached state with `busy: true`.
* If the queue is idle, the driver can probe the printer.
* `source: "probe"` means a live socket check was performed.
* `source: "cache"` means the response came from stored state and queue counts.

## POST /beep

Queues the beep sequence for a printer.

```json theme={null}
{
  "ip_address": "192.168.1.50",
  "port": "9100"
}
```

Response:

```json theme={null}
{
  "ok": true,
  "jobId": "43",
  "queued": true
}
```

## POST /cash-drawer

Queues the ESC/POS cash drawer pulse command.

```json theme={null}
{
  "ip_address": "192.168.1.50",
  "port": "9100"
}
```

Response:

```json theme={null}
{
  "ok": true,
  "jobId": "44",
  "queued": true
}
```

## GET /health

Returns process health and build version.

```json theme={null}
{
  "ok": true,
  "version": 66,
  "uptime": 123.45
}
```

## GET /queue-status

Returns known printer queues.

```json theme={null}
{
  "queue": [
    {
      "printerKey": "192.168.1.50:9100",
      "status": "online",
      "validated": false,
      "busy": false,
      "source": "cache",
      "lastPingOn": "2026-06-16T07:00:00.000Z",
      "lastError": null,
      "waiting": 0,
      "active": 0,
      "delayed": 0,
      "failed": 0,
      "completed": 0
    }
  ],
  "totalPending": 0,
  "isProcessing": false
}
```

## GET /mesh-status

When mesh is enabled:

```json theme={null}
{
  "enabled": true,
  "path": "/mesh",
  "port": 8080,
  "connectedPeers": [],
  "peerCount": 0
}
```

When mesh is disabled:

```json theme={null}
{
  "enabled": false,
  "message": "Mesh disabled by config.json"
}
```

## GET /ca.crt

Available when HTTPS is enabled. Downloads the CA certificate as `plato-printer-ca.crt`.

## WS /mesh

PeerJS signaling endpoint mounted when `features.meshEnabled` is true.