REST API Reference

If you prefer to use the REST API directly instead of the JavaScript SDK, the service exposes the following endpoints on https://localhost:53052. The API is the same on Windows and macOS; a few scan options are ignored on macOS — see Platform Differences.

Authentication

No authentication is required. The service is localhost-only and relies on the operating system's network isolation.

CORS

The service accepts requests from any origin and supports Chrome's Private Network Access preflight headers.

Endpoints

Health Check

GET /health

Returns the service health status as plain text.

Response:

Healthy

On Windows the response is Degraded while the Desktop App is not running.

Get Service Status

GET /api/twain/status

Returns the status of the service and desktop app connectivity.

Response (200):

{
  "success": true,
  "serviceOnline": true,
  "desktopAppConnected": true,
  "scannerStatus": {
    "isOnline": true,
    "isPaperLoaded": true,
    "isSourceOpen": false,
    "ocrEnabled": false
  },
  "timestamp": "2026-02-25T12:00:00Z"
}

Get Version

GET /api/twain/version

Returns the installed version of AmbirScan Web Connect. The service version is always available; the desktop version is included only when the desktop app is connected.

Response (200):

{
  "success": true,
  "productName": "AmbirScan Web Connect",
  "serviceVersion": "4.1.0.0",
  "desktopVersion": "4.1.0.0",
  "desktopAppConnected": true,
  "timestamp": "2026-02-25T12:00:00Z"
}

Clients installed before this endpoint existed return 404, which itself signals a legacy install that should be updated.

List Scanners

GET /api/twain/scanners

Returns a list of all available TWAIN scanners.

Response (200):

{
  "success": true,
  "scanners": [
    {
      "name": "TravelScan Pro",
      "manufacturer": "Ambir Technology",
      "model": "Ambir Technology",
      "isOnline": true,
      "hasFeeder": true,
      "hasFlatbed": true,
      "supportsDuplex": false
    }
  ],
  "count": 1
}

Response (503, Windows only — the Desktop App is not running):

{
  "success": false,
  "error": "Desktop application not connected"
}

Get Scanner Capabilities

GET /api/twain/scanners/{name}/capabilities

Returns the capabilities of a specific scanner. The scanner name must be URL-encoded.

Example:

GET /api/twain/scanners/TravelScan%20Pro/capabilities

Response (200):

{
  "success": true,
  "capabilities": {
    "resolutions": [150, 200, 300, 600],
    "colorModes": ["Color", "Grayscale", "BlackAndWhite"],
    "supportsDuplex": false,
    "supportsAutoRotate": true,
    "supportsAutoDeskew": true,
    "supportsAutoCrop": false,
    "supportedPageSizes": ["Letter", "Legal", "A4", "Auto"]
  }
}

On macOS this endpoint also returns supportedOcrLanguages, the OCR languages available on that Mac. It is informational: the OCR language cannot be chosen in this release. On macOS, supportedPageSizes lists the sizes that fit the scanner, but pageSize is not applied when scanning.

Scan

POST /api/twain/scan
Content-Type: application/json

Perform a scan. Handles opening the scanner, scanning, and returning results.

Request Body:

{
  "scannerName": "TravelScan Pro",
  "parameters": {
    "resolution": 200,
    "colorMode": "Grayscale",
    "duplexMode": "Simplex",
    "pageSize": "Letter",
    "autoRotate": false,
    "autoDeskew": true,
    "autoCrop": true,
    "imageFormat": "Png",
    "jpegQuality": 90,
    "barcodeReadingEnabled": false,
    "barcodeFilterLevel": "Normal",
    "barcodeFormats": [],
    "barcodeStopAfterFirst": false,
    "ocrEnabled": false,
    "requestTimeoutSeconds": 0,
    "transferMode": "Auto"
  }
}

This endpoint names the output format imageFormat ("Png", "Jpeg", "Tiff" or "Bmp"), unlike the TWAIN Direct endpoint used by the JavaScript SDK, which calls it outputFormat. See Parameter names by endpoint.

jpegQuality (1–100, default 90) applies only to JPEG output.
barcodeFormats and barcodeStopAfterFirst narrow barcode decoding; see Choosing Symbologies. An empty barcodeFormats array searches every supported symbology.
transferMode is optional ("Auto", "Native" or "Buffered") and rarely needed. Omit it to use the mode configured in the desktop app, which defaults to native transfer; see Transfer Mode.

Response (200):

{
  "success": true,
  "status": "Success",
  "message": "Scan completed successfully",
  "images": [
    {
      "base64Data": "/9j/4AAQSkZJRg...",
      "mimeType": "image/png",
      "pageNumber": 1,
      "width": 2550,
      "height": 3300,
      "resolution": 300,
      "format": "Png",
      "fileSizeBytes": 1234567,
      "ocrText": "",
      "barcodes": []
    }
  ],
  "imageCount": 1,
  "elapsedMs": 4500
}

Response with Barcodes (when barcodeReadingEnabled: true):

{
  "success": true,
  "images": [
    {
      "base64Data": "...",
      "barcodes": [
        {
          "text": "ABC123456",
          "barcodeType": "CODE_128",
          "confidence": 0.95
        },
        {
          "text": "DLDAQ12345...",
          "barcodeType": "PDF_417",
          "confidence": 0.88
        }
      ]
    }
  ]
}

Error Responses:

Status	Description
400	Scanner name is required
503	Desktop application not connected (Windows only)
504	Scan timed out
500	Internal server error

Cancel Scan

POST /api/twain/cancel
Content-Type: application/json

Cancel an active scan operation.

Request Body:

{
  "requestId": "optional-request-id"
}

Response (200):

{
  "success": true,
  "message": "Cancel request sent"
}

Enable Auto Scan

POST /api/twain/autoscan/enable
Content-Type: application/json

Enable auto-scan mode. The scanner watches its paper sensor and automatically captures each document as it is inserted. Images are delivered over the auto-scan event stream.

Request Body:

{
  "parameters": {
    "resolution": 200,
    "colorMode": "Grayscale",
    "duplexMode": "Simplex",
    "pageSize": "Letter",
    "autoRotate": false,
    "autoDeskew": true,
    "autoCrop": true,
    "imageFormat": "Png",
    "barcodeReadingEnabled": false,
    "barcodeFilterLevel": "Normal",
    "ocrEnabled": false,
    "requestTimeoutSeconds": 0,
    "transferMode": "Auto"
  }
}

Takes the same parameters as Scan, including imageFormat, jpegQuality, barcodeFormats and barcodeStopAfterFirst.

Response (200):

{
  "success": true,
  "message": "Auto-scan enabled"
}

Auto-scan stays on only while a client holds the event stream open. If nothing reads the stream for five minutes, auto-scan disables itself and discards pages that were scanned but not delivered.

Response (503): Desktop application not connected (Windows only).

Disable Auto Scan

POST /api/twain/autoscan/disable

Disable auto-scan mode. Pages that were scanned but not yet delivered are discarded.

Response (200):

{
  "success": true,
  "message": "Auto-scan disabled"
}

Auto Scan Events

GET /api/twain/autoscan/events

A Server-Sent Events (text/event-stream) endpoint that pushes each document to the browser as it is scanned while auto-scan is enabled. Enable auto-scan first with the endpoint above.

Event types:

Event	Data	Description
`image`	Scanned image object (same shape as a `scan` image)	Sent once per captured document
`disabled`	`{ "message": "Auto-scan was disabled" }`	Auto-scan was turned off; the stream ends
`error`	`{ "error": "..." }`	The desktop app disconnected or another error occurred

Example stream:

event: image
data: {"base64Data":"...","mimeType":"image/png","pageNumber":1,"width":2550,"height":3300,...}

event: disabled
data: {"message":"Auto-scan was disabled"}

TWAIN Direct Protocol Endpoint

POST /api/twain
Content-Type: application/json

The main TWAIN Direct protocol endpoint used by the JavaScript SDK.

Supported Methods:

Method	Description
`getSources`	List available scanners
`openSource`	Open a scanner
`closeSource`	Close the current scanner
`getCapabilities`	Get scanner capabilities
`getStatus`	Get scanner status
`scan`	Perform a scan

Request Format:

{
  "kind": "twainlocalscanner",
  "method": "getSources",
  "params": null
}

Response Format:

{
  "kind": "twainlocalscanner",
  "commandId": "unique-id",
  "method": "getSources",
  "results": {
    "success": true,
    "code": "success"
  },
  "data": {
    "availableSources": [...]
  }
}

Scan request — the parameters are the SDK scan parameters:

{
  "kind": "twainlocalscanner",
  "method": "scan",
  "params": {
    "resolution": 300,
    "colorMode": "Color",
    "outputFormat": "jpeg",
    "jpegQuality": 85,
    "barcodeReadingEnabled": true,
    "barcodeFormats": ["Pdf417"],
    "barcodeStopAfterFirst": true
  }
}

Parameter names by endpoint

The TWAIN Direct endpoint and the simplified endpoints accept the same options, but name the output format differently:

Option	`POST /api/twain` (SDK `scan()`)	`POST /api/twain/scan` and `/api/twain/autoscan/enable`
Output format	`outputFormat`: `"png"`, `"jpeg"`/`"jpg"`, `"tiff"`/`"tif"`, `"bmp"` (case-insensitive)	`imageFormat`: `"Png"`, `"Jpeg"`, `"Tiff"`, `"Bmp"`
Everything else	Same names as the SDK scan parameters	Same names

A field an endpoint doesn't recognise is ignored rather than rejected, so sending outputFormat to /api/twain/scan produces PNG.

Enum Values

Color Modes

Value	Description
`Color`	Full color scan (24-bit RGB)
`Grayscale`	Grayscale scan (8-bit)
`BlackAndWhite`	Black and white scan (1-bit)

Duplex Modes

Value	Description
`Simplex`	Single-sided scanning
`DuplexLongEdge`	Double-sided, flip on long edge
`DuplexShortEdge`	Double-sided, flip on short edge

Page Sizes

Value	Description
`Letter`	8.5" x 11"
`Legal`	8.5" x 14"
`A4`	210mm x 297mm
`A5`	148mm x 210mm
`A6`	105mm x 148mm
`B5`	JIS B5, 182mm x 257mm
`Auto`	Auto-detect page size

Which sizes a scanner can actually produce is reported in supportedPageSizes from Get Scanner Capabilities. It may also include A3 or Executive, which the SDK's scan() does not accept.

Output Formats

`outputFormat` (`/api/twain`)	`imageFormat` (simplified endpoints)	MIME Type
`png`	`Png`	`image/png`
`jpeg` or `jpg`	`Jpeg`	`image/jpeg`
`bmp`	`Bmp`	`image/bmp`
`tiff` or `tif`	`Tiff`	`image/tiff`

Barcode Formats

Pdf417, QrCode, DataMatrix, Aztec, Code128, Code39, Code93, Ean13, Ean8, UpcA, UpcE, Itf, Codabar. Case-insensitive. See Supported Barcode Formats for the barcodeType name each one reports in results.

Barcode Filter Levels

Level	Description
`Low`	Minimal validation, may include false positives
`Normal`	Balanced validation (recommended)
`High`	Strict validation, fewer false positives
`VeryHigh`	Most strict, only high-confidence results

Authentication​

CORS​

Endpoints​

Health Check​

Get Service Status​

Get Version​

List Scanners​

Get Scanner Capabilities​

Scan​

Cancel Scan​

Enable Auto Scan​

Disable Auto Scan​

Auto Scan Events​

TWAIN Direct Protocol Endpoint​

Parameter names by endpoint​

Enum Values​

Color Modes​

Duplex Modes​

Page Sizes​

Output Formats​

Barcode Formats​

Barcode Filter Levels​

Authentication

CORS

Endpoints

Health Check

Get Service Status

Get Version

List Scanners

Get Scanner Capabilities

Scan

Cancel Scan

Enable Auto Scan

Disable Auto Scan

Auto Scan Events

TWAIN Direct Protocol Endpoint

Parameter names by endpoint

Enum Values

Color Modes

Duplex Modes

Page Sizes

Output Formats

Barcode Formats

Barcode Filter Levels