API section

Printing

Printing PDF by URL or as a file, images and printer commands (ESC/POS, ZPL, EPL) on Windows printers and driverless printers; the printer by name, device number or role. Printer queue and status.

GET	`/api/v1/print-jobs`	Agent print jobs
POST	`/api/v1/print-jobs`	Printing
POST	`/api/v1/print-jobs/{id}/retry`	Retry a print job
POST	`/api/v1/print-jobs/{id}/cancel`	Cancel a print job
GET	`/api/v1/printers`	Windows printers, their roles and print settings
GET	`/api/v1/printers/status`	Printer status
GET	`/api/v1/printers/jobs`	System printer queue
DELETE	`/api/v1/printers/jobs`	Clear the printer queue
GET	`/api/v1/printers/capabilities`	Printer capabilities

Agent print jobs#

GET/api/v1/print-jobs

Newest first; status as for operations: QUEUED, RUNNING, SUCCEEDED, FAILED

Parameters

Name	In	Type	Description
`limit`	query	integer int32

Response 200 application/json

Array · Operation

idstring uuid
typestring
idempotencyKeystring
resourcesarray of string
statusstring
values: QUEUED RUNNING SUCCEEDED FAILED UNKNOWN
stagestring
createdAtstring date-time
startedAtstring date-time
finishedAtstring date-time
resultany value
errorOperationError
3 fields · OperationError
- codestring
- messagestring
- detailsany value
warningsarray of string

Errors — problem+json with a code field, see error codes.

Request example

curl

curl 'http://localhost:7790/api/v1/print-jobs'

curl

curl 'https://cloud.hw-connector.ru/agent/api/v1/print-jobs' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'

Printing#

POST/api/v1/print-jobs

Operation

PDF by URLs, a ready PDF or images — with printer settings (scale, paper); raw — ESC/POS, ZPL, EPL commands straight to the printer. URLs are downloaded before printing

Parameters

Name	In	Type	Description
`Idempotency-Key`required	header	string
`Prefer`	header	string

Request body application/json required

Fields · PrintJobRequest

urlsarray of string
documentstring
imagesarray of string
rawstring
textarray of TextLine
4 fields · TextLine
- kindstringrequired
  values: TEXT PAIR SEPARATOR
- textstring
- rightstring
- alignstring
  values: LEFT CENTER RIGHT
printerstring
deviceinteger int32
rolestring
copiesinteger int32
from 1
to 20
htmlstring
htmlUrlstring
optionsPrintOptions
14 fields · PrintOptions
- pagesstring
- duplexstring
  values: ONE_SIDED LONG_EDGE SHORT_EDGE
- traystring
- colorstring
  values: COLOR MONOCHROME
- dpiinteger int32
- nUpinteger int32
  from 1
  to 16
- collateboolean
- orientationstring
  values: AUTO PORTRAIT LANDSCAPE
- rotationinteger int32
- scalingstring
  values: ACTUAL FIT SHRINK
- paperWidthMmnumber double
- paperHeightMmnumber double
- marginsMmstring
- jobNamestring
expireAfterSecinteger int32
from 1

JSON

{
  "urls": [
    "string"
  ],
  "document": "string",
  "images": [
    "string"
  ],
  "raw": "string",
  "text": [
    {
      "kind": "TEXT",
      "text": "string",
      "right": "string",
      "align": "LEFT"
    }
  ],
  "printer": "string",
  "device": 1,
  "role": "string",
  "copies": 1,
  "html": "string",
  "htmlUrl": "string",
  "options": {
    "pages": "string",
    "duplex": "ONE_SIDED",
    "tray": "string",
    "color": "COLOR",
    "dpi": 1,
    "nUp": 1,
    "collate": false,
    "orientation": "AUTO",
    "rotation": 1,
    "scaling": "ACTUAL",
    "paperWidthMm": 1.5,
    "paperHeightMm": 1.5,
    "marginsMm": "string",
    "jobName": "string"
  },
  "expireAfterSec": 1
}

Response 200 application/json

Fields · Operation

idstring uuid
typestring
idempotencyKeystring
resourcesarray of string
statusstring
values: QUEUED RUNNING SUCCEEDED FAILED UNKNOWN
stagestring
createdAtstring date-time
startedAtstring date-time
finishedAtstring date-time
resultany value
errorOperationError
3 fields · OperationError
- codestring
- messagestring
- detailsany value
warningsarray of string

Errors — problem+json with a code field, see error codes.

Request example

curl

curl -X POST 'http://localhost:7790/api/v1/print-jobs' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30' \
  -H 'Content-Type: application/json' \
  --data '{"urls":["string"],"document":"string","images":["string"],"raw":"string","text":[{"kind":"TEXT","text":"string","right":"string","align":"LEFT"}],"printer":"string","device":1,"role":"string","copies":1,"html":"string","htmlUrl":"string","options":{"pages":"string","duplex":"ONE_SIDED","tray":"string","color":"COLOR","dpi":1,"nUp":1,"collate":false,"orientation":"AUTO","rotation":1,"scaling":"ACTUAL","paperWidthMm":1.5,"paperHeightMm":1.5,"marginsMm":"string","jobName":"string"},"expireAfterSec":1}'

curl

curl -X POST 'https://cloud.hw-connector.ru/agent/api/v1/print-jobs' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30' \
  -H 'Content-Type: application/json' \
  --data '{"urls":["string"],"document":"string","images":["string"],"raw":"string","text":[{"kind":"TEXT","text":"string","right":"string","align":"LEFT"}],"printer":"string","device":1,"role":"string","copies":1,"html":"string","htmlUrl":"string","options":{"pages":"string","duplex":"ONE_SIDED","tray":"string","color":"COLOR","dpi":1,"nUp":1,"collate":false,"orientation":"AUTO","rotation":1,"scaling":"ACTUAL","paperWidthMm":1.5,"paperHeightMm":1.5,"marginsMm":"string","jobName":"string"},"expireAfterSec":1}'

Retry a print job#

POST/api/v1/print-jobs/{id}/retry

Operation

A new job with the same documents and options; needs a new Idempotency-Key

Parameters

Name	In	Type
`id`required	path	string uuid
`Idempotency-Key`required	header	string
`Prefer`	header	string

Response 200 application/json

Fields · Operation

idstring uuid
typestring
idempotencyKeystring
resourcesarray of string
statusstring
values: QUEUED RUNNING SUCCEEDED FAILED UNKNOWN
stagestring
createdAtstring date-time
startedAtstring date-time
finishedAtstring date-time
resultany value
errorOperationError
3 fields · OperationError
- codestring
- messagestring
- detailsany value
warningsarray of string

Errors — problem+json with a code field, see error codes.

Request example

curl

curl -X POST 'http://localhost:7790/api/v1/print-jobs/3f6c1d9e-1b2a-4c55-9e0d-6a1f0c2b7d11/retry' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30'

curl

curl -X POST 'https://cloud.hw-connector.ru/agent/api/v1/print-jobs/3f6c1d9e-1b2a-4c55-9e0d-6a1f0c2b7d11/retry' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30'

Cancel a print job#

POST/api/v1/print-jobs/{id}/cancel

Only while it waits for the printer (QUEUED); a started job is already in the Windows queue — clear it with DELETE /printers/jobs

Parameters

Name	In	Type	Description
`id`required	path	string uuid

Response 200 application/json

Fields · Operation

idstring uuid
typestring
idempotencyKeystring
resourcesarray of string
statusstring
values: QUEUED RUNNING SUCCEEDED FAILED UNKNOWN
stagestring
createdAtstring date-time
startedAtstring date-time
finishedAtstring date-time
resultany value
errorOperationError
3 fields · OperationError
- codestring
- messagestring
- detailsany value
warningsarray of string

Errors — problem+json with a code field, see error codes.

Request example

curl

curl -X POST 'http://localhost:7790/api/v1/print-jobs/3f6c1d9e-1b2a-4c55-9e0d-6a1f0c2b7d11/cancel'

curl

curl -X POST 'https://cloud.hw-connector.ru/agent/api/v1/print-jobs/3f6c1d9e-1b2a-4c55-9e0d-6a1f0c2b7d11/cancel' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'

Windows printers, their roles and print settings#

GET/api/v1/printers

Response 200 application/json

Array · PrinterInfo

namestring
isDefaultboolean
rolesarray of string
settingsPrinterSettings
4 fields · PrinterSettings
- scalingstring
  values: ACTUAL FIT SHRINK
- orientationstring
  values: AUTO PORTRAIT LANDSCAPE
- paperWidthMmnumber double
- paperHeightMmnumber double

Errors — problem+json with a code field, see error codes.

Request example

curl

curl 'http://localhost:7790/api/v1/printers'

curl

curl 'https://cloud.hw-connector.ru/agent/api/v1/printers' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'

Printer status#

GET/api/v1/printers/status

Ready, printing, offline, error and reasons (no paper, jam, door open); changes arrive as printer events

Response 200 application/json

Array · Status

enabledboolean
unlockedboolean

Errors — problem+json with a code field, see error codes.

Request example

curl

curl 'http://localhost:7790/api/v1/printers/status'

curl

curl 'https://cloud.hw-connector.ru/agent/api/v1/printers/status' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'

System printer queue#

GET/api/v1/printers/jobs

Jobs in the Windows queue (CUPS on Linux and macOS), including ones not from the agent

Parameters

Name	In	Type	Description
`name`required	query	string

Response 200 application/json

Array · Job

idstring
documentstring
statusstring
pagesinteger int32
submittedstring

Errors — problem+json with a code field, see error codes.

Request example

curl

curl 'http://localhost:7790/api/v1/printers/jobs?name=fn.days_left'

curl

curl 'https://cloud.hw-connector.ru/agent/api/v1/printers/jobs?name=fn.days_left' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'

Clear the printer queue#

DELETE/api/v1/printers/jobs

Removes all jobs from this printer's Windows (CUPS) queue

Parameters

Name	In	Type	Description
`name`required	query	string

Response 200 application/json

Type: map → any value

Errors — problem+json with a code field, see error codes.

Request example

curl

curl -X DELETE 'http://localhost:7790/api/v1/printers/jobs?name=fn.days_left'

curl

curl -X DELETE 'https://cloud.hw-connector.ru/agent/api/v1/printers/jobs?name=fn.days_left' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'

Printer capabilities#

GET/api/v1/printers/capabilities

Trays, paper, duplex, color, resolutions, copies, N-up — as reported by the driver

Parameters

Name	In	Type	Description
`name`required	query	string

Response 200 application/json

Type: map → any value

Errors — problem+json with a code field, see error codes.

Request example

curl

curl 'http://localhost:7790/api/v1/printers/capabilities?name=fn.days_left'

curl

curl 'https://cloud.hw-connector.ru/agent/api/v1/printers/capabilities?name=fn.days_left' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'