HW agent API 2.15.3
Agent API Cloud API Cloud MCP Help OpenAPI Русский

API section

Document scanners

WIA and TWAIN document scanners: scan to PDF or a JPEG per page, result files and their deletion. Needs the Document scanner module in the key (except the emulator).

POST/api/v1/document-scanners/scanScan
GET/api/v1/scans/{id}/{file}Scan result file
GET/api/v1/document-scannersDocument scanners
DELETE/api/v1/scans/{id}Delete the scan result

Scan#

POST/api/v1/document-scanners/scan
Operation

Operation document-scan; result — id and file links (one PDF or a JPEG per page), download — GET /api/v1/scans/{id}/{file}. Without the module key — 402 LICENSE_REQUIRED (except device: emulator). Handy with Prefer: wait=120 — the response comes when the scanner is done

Parameters

NameInTypeDescription
Idempotency-Keyrequiredheaderstring
Preferheaderstring

Request body application/json

Fields · ScanSettings
  • devicestring
  • sourcestring
  • dpiinteger int32
    from 50
    to 1200
  • colorstring
  • formatstring
  • pageSizestring
  • widthMmnumber double
    from 10
    to 1000
  • heightMmnumber double
    from 10
    to 1000
  • brightnessinteger int32
    from -1000
    to 1000
  • contrastinteger int32
    from -1000
    to 1000
  • qualityinteger int32
    from 10
    to 100
  • maxPagesinteger int32
    from 1
    to 500
JSON
{
  "device": "string",
  "source": "string",
  "dpi": 50,
  "color": "string",
  "format": "string",
  "pageSize": "string",
  "widthMm": 10,
  "heightMm": 10,
  "brightness": -1000,
  "contrast": -1000,
  "quality": 10,
  "maxPages": 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/document-scanners/scan' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30' \
  -H 'Content-Type: application/json' \
  --data '{"device":"string","source":"string","dpi":50,"color":"string","format":"string","pageSize":"string","widthMm":10,"heightMm":10,"brightness":-1000,"contrast":-1000,"quality":10,"maxPages":1}'
curl
curl -X POST 'https://cloud.hw-connector.ru/agent/api/v1/document-scanners/scan' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30' \
  -H 'Content-Type: application/json' \
  --data '{"device":"string","source":"string","dpi":50,"color":"string","format":"string","pageSize":"string","widthMm":10,"heightMm":10,"brightness":-1000,"contrast":-1000,"quality":10,"maxPages":1}'

Scan result file#

GET/api/v1/scans/{id}/{file}

File name — from the operation's result.files: scan.pdf, page-1.jpg…

Parameters

NameInTypeDescription
idrequiredpathstring uuid
filerequiredpathstring

Response 200

File.

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

Request example

curl
curl 'http://localhost:7790/api/v1/scans/3f6c1d9e-1b2a-4c55-9e0d-6a1f0c2b7d11/scan.pdf'
curl
curl 'https://cloud.hw-connector.ru/agent/api/v1/scans/3f6c1d9e-1b2a-4c55-9e0d-6a1f0c2b7d11/scan.pdf' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'

Document scanners#

GET/api/v1/document-scanners

WIA — all scanners and MFPs with a Windows driver, TWAIN — if NAPS2 is installed, and the emulator. The agent connects to each scanner, the response may take a few seconds

Response 200 application/json

Fields · ScannerList
  • licensedboolean
  • scannersarray of ScannerInfo
    5 fields · ScannerInfo
    • idstring
    • driverstring
    • namestring
    • manufacturerstring
    • sourcesarray of string

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

Request example

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

Delete the scan result#

DELETE/api/v1/scans/{id}

Right away, without waiting for the retention period (hw.document-scanner.keep-hours)

Parameters

NameInTypeDescription
idrequiredpathstring uuid

Response 200

No body.

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

Request example

curl
curl -X DELETE 'http://localhost:7790/api/v1/scans/3f6c1d9e-1b2a-4c55-9e0d-6a1f0c2b7d11'
curl
curl -X DELETE 'https://cloud.hw-connector.ru/agent/api/v1/scans/3f6c1d9e-1b2a-4c55-9e0d-6a1f0c2b7d11' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'